CL_CIL_SVC

Requests that a ZY illuminate a retro reflector target with its laser beam.

ZIYRet CL_CIL_SVC(PM_CL_CIL)

Parameters:

All parameters are contained in the PM_CL_CIL structure.

struct PM_CL_CIL

{
  SRVD   sd;
  string RetroName<NAME_STR>;
  int    RetroIndex;
  long   AZ;
  long   EL;
  double X;
  double Y;
  double Z;
};

sd.Name

The name of the ZY.

sd.Flags

This is an array of flags that controls the operation of the CL_CIL_SVC RPC call. The following flags can be used to specify how a retro-reflector is referenced. They are mutually exclusive:

CL_CIL_BYNAME

The retro-reflector is referenced by name, i.e. ZRG (for the reference retro-reflector.)

CL_CIL_BYINDEX

The retro-reflector is referenced by its index position in the list of retros, i.e. 0 (for the reference retro-reflector.)

The following flags determine whether and how the CL_CIL_SVC RPC call will supply the coordinates for the retro-reflector. These bits are mutually exclusive, but can be OR'ed with either CL_CIL_BYNAME or CL_CIL_BYINDEX:

CL_CIL_NOCOORDS

No new coordinates for the retro-reflector will be supplied. Coordinates stored by the ZY will be used.

CL_CIL_AZEL

This instructs the ZY to point to the retro-reflector using the supplied AZ/EL encoder counts to aim the laser. These new AZ/EL values will be used subsequently until new ones are downloaded, or until the ZY re-calculates the AZ/EL coordinates for this retro.

CL_CIL_XYZ

This instructs the ZY to point to the retro-reflector using the supplied XYZ Cartesian coordinates (in the coordinate system of the retro-reflector). The ZY will use these to calculate new AZ/EL encoder values to hit its target.

sd.ErrorMsg

Not used.

sd.TID

Not used.

sd.TS

Not used.

RetroName

When the CL_CIL_BYNAME flag is set in sd.Flags, then this data member points to the name of the retro-reflector that is to be illuminated by the laser.

RetroIndex

When the CL_CIL_BYINDEX flag is set in sd.Flags, then this data member holds the index value of the retro-reflector that is to be illuminated by the laser.

AZ

If the CL_CIL_AZEL flag is set in sd.Flags, then this data member holds the Azimuth encoder value to be used in aiming the laser.

EL

If the CL_CIL_AZEL flag is set in sd.Flags, then this data member holds the Elevation encoder value to be used in aiming the laser.

X

If the CL_CIL_XYZ flag is set in sd.Flags, then this data member holds the X coordinate of the retro-reflector.

Y

If the CL_CIL_XYZ flag is set in sd.Flags, then this data member holds the Y coordinate of the retro-reflector.

Z

If the CL_CIL_XYZ flag is set in sd.Flags, then this data member holds the Z coordinate of the retro-reflector.

Return Value:

A ZIYRet structure, which contains the success code and an error message, if the call failed (see ZIYRet, section 4.2.2.)

Remarks:

This command requests that a ZY illuminate a retro reflector target with its laser. This function can refer to a cube by name or by its index number, and can optionally provide new coordinates to use when illuminating the target, depending on which of the flags described above is set. Flags CL_CIL_BYNAME and CL_CIL_NOCOORDS are assumed if no flags are set. If this is the first time that the ZY was asked to illuminate the target, it uses the Cartesian coordinates of the target to calculate the Az/El encoder values used by the servo system to point the laser to the target, and caches these values in memory. This caching is done for performance reasons, as, from the standpoint of an embedded system, the calculations needed to obtain the encoder values are not trivial. The Az/El values will remain cached until something happens to invalidate them. This includes the following:

1. The ZY is given new Cartesian coordinates for this target, and then asked to illuminate the target.
2. The ZY is given new Az/El encoder values for this target, replacing the cached values. Of course, these new values are temporary, as they themselves will be replaced in the event that new values must be recalculated by the ZY (see items 1 & 3.)
3. The ZY is given new positions for itself (the ZY moved,) necessitating the recalculation of Az/El encoder values for all targets in its memory (for performance reasons, these new Az/El values are only recalculated when actually needed. Thus, if a target is not needed the overhead of re-calculating new encoder values for it is avoided.)

Example:

PM_CL_CIL p;


p.sd.Name = "zy10";             // address ZY10
p.sd.ErrorMsg = null_str;       // Keep XDR lib happy
p.sd.Flags = CL_CIL_BYNAME | CL_CIL_XYZ;
p.RetroName = "ZBG10";          // Name of target
p.X = 12345.67;                 // Use new coordinates for the
p.Y = 86400.10;                 // target
p.Z = 180000.00;

CL->rexec(CL_CIL_SVC, (xdrproc_t)xdr_PM_CL_CIL, (char *)&p,
          (xdrproc_t)xdr_ZIYRet, (char *)&in, sizeof(ZIYRet));

See also:

ZIYRet, SRVD, CL_CMEAS_SVC, CL_COO_SVC, PM_CL_CIL