![[SLAC Controls Department]](/grp/cd/soft/images/logo_cd.gif){kind=logo}
![[SLAC Home Page]](/grp/cd/soft/images/logo_slac.gif){kind=logo}
10.1 ANALOG STATUS UTILITIES . . . . . . . . . . . . 10-1
10.1.1 DBGET_ASTS . . . . . . . . . . . . . . . . . . 10-1
10.1.2 DBLGET_ASTS . . . . . . . . . . . . . . . . . 10-2
10.1.3 DBLIST_ASTS . . . . . . . . . . . . . . . . . 10-3
10.1.4 DBUNITS_ASTS . . . . . . . . . . . . . . . . . 10-5
10.1.5 DB_ASTS_VALID . . . . . . . . . . . . . . . . 10-5
10.2 BPM UTILITIES . . . . . . . . . . . . . . . . . 10-6
10.2.1 BPM_CREATE_DEF . . . . . . . . . . . . . . . . 10-7
10.2.2 BPM_READ_DEF . . . . . . . . . . . . . . . . . 10-8
10.2.3 BPM_SELECT_DEF . . . . . . . . . . . . . . . . 10-9
10.2.4 BPMCAL_DOWNLOAD_UTIL . . . . . . . . . . . . . 10-10
10.2.5 BPM_AVG . . . . . . . . . . . . . . . . . . . 10-11
10.2.6 BPMLIST . . . . . . . . . . . . . . . . . . . 10-13
10.2.7 BPMLGET . . . . . . . . . . . . . . . . . . . 10-15
10.2.8 BPMGET . . . . . . . . . . . . . . . . . . . . 10-16
10.2.9 BPM Structure Definitions . . . . . . . . . . 10-17
10.3 KLYSTRON UTILITIES . . . . . . . . . . . . . . . 10-18
10.3.1 KLYS_GET_ENERGY . . . . . . . . . . . . . . . 10-19
10.4 KLYSTRON DATA ACCESS UTILITIES . . . . . . . . . 10-21
10.4.1 KLYS_FTP_DRVR . . . . . . . . . . . . . . . . 10-23
10.4.2 KLYS_FTP_SBCALL . . . . . . . . . . . . . . . 10-25
10.4.3 KLYS_FTP_TEMPLATE . . . . . . . . . . . . . . 10-25
10.4.4 KLYS_FTP_DEL . . . . . . . . . . . . . . . . . 10-25
10.4.5 PIOP_DATA_GET . . . . . . . . . . . . . . . . 10-26
10.4.6 PIOP_DATA_VALID . . . . . . . . . . . . . . . 10-26
10.4.7 KFTP_STRUC Include Item . . . . . . . . . . . 10-27
10.4.7.1 KFTP Structure . . . . . . . . . . . . . . . 10-27
10.4.7.2 RESULT Structure . . . . . . . . . . . . . . 10-28
10.5 MAGNET UTILITIES . . . . . . . . . . . . . . . . 10-28
10.5.1 MAG_ADCL . . . . . . . . . . . . . . . . . . . 10-28
10.5.2 MAG_FUNC . . . . . . . . . . . . . . . . . . . 10-29
10.5.3 MAG_LIST . . . . . . . . . . . . . . . . . . . 10-30
10.5.4 MAG_READ_ADC . . . . . . . . . . . . . . . . . 10-30
10.6 TIMING UTILITIES . . . . . . . . . . . . . . . . 10-31
10.6.1 GET_TREF . . . . . . . . . . . . . . . . . . . 10-35
10.6.2 TM_ACTIVATE . . . . . . . . . . . . . . . . . 10-36
10.6.3 TM_ACTIVATE_KLYS . . . . . . . . . . . . . . . 10-37
10.6.4 TM_DEACTIVATE . . . . . . . . . . . . . . . . 10-38
10.6.5 TM_DEACTIVATE_KLYS . . . . . . . . . . . . . . 10-39
10.6.6 TMDEVICE . . . . . . . . . . . . . . . . . . . 10-40
10.6.7 TMGET . . . . . . . . . . . . . . . . . . . . 10-41
10.6.8 TMLGET . . . . . . . . . . . . . . . . . . . . 10-42
10.6.9 TMLIST . . . . . . . . . . . . . . . . . . . . 10-43
10.6.10 TMLPUT . . . . . . . . . . . . . . . . . . . . 10-45
10.6.11 TMPCD . . . . . . . . . . . . . . . . . . . . 10-46
10.6.12 TMPUT . . . . . . . . . . . . . . . . . . . . 10-48
10.6.13 TM_REACTIVATE . . . . . . . . . . . . . . . . 10-49
10.6.14 TM_REACTIVATE_KLYS . . . . . . . . . . . . . . 10-50
10.6.15 TMUNITS . . . . . . . . . . . . . . . . . . . 10-51
10.6.16 TNOMINAL . . . . . . . . . . . . . . . . . . . 10-52
10.6.17 TRIG_RATE . . . . . . . . . . . . . . . . . . 10-53
10.6.18 T_VAL_IS_DEACT . . . . . . . . . . . . . . . . 10-54 (DATA,DBLIST) Routine to get ASTS data via a list previously constructed by DBLIST_ASTS. DATA is used to hold returned data. (output) It is an array of any type, but its first word (2 bytes) must be the length of DATA in words. On return, the second word of DATA will contain the number of words filled. This routine will add a variable number of words to the list. (See description of DBLIST_ASTS for number of words returned for different secondaries.)
GENERAL UTILITIES Page 10-3 DBLIST should be a list constructed by DBLIST_ASTS (input). This routine is analogous to DBLGET, however, the DBLIST passed consists of quadruplets rather than doublets and should be constructed by DBLIST_ASTS.10.1.3 DBLIST_ASTS DBLIST_ASTS INTEGER*4 FUNCTION DBLIST_ASTS(LIST,MICR,UNIT,SECN,CHAN) This INTEGER*4 function will return a database list similar to that returned by DBLIST. The differences are the following: The PRIM is assumed to be ASTS. The CHANnel name supplied should be a valid channel name for the given micro and unit. If the channel is not valid, the list will not be incremented and DB_BADCHAN (bad channel name) will be returned. The list must be long enough to allow for 4 I*2 words (rather than 2) per each item referenced. LIST is an I*2 output array. The user responsibilities are: The first word of the array must be the length of the array. If a new list is being started, as opposed to incrementing an existing list, then the second word must be set to 0. MICR is the micro name, 4 Ascii characters in I*4 longword. (input). ALL* allowed. UNIT is the unit number, an I*4 ascii OR integer representation of the unit number.(input) ALL* allowed.
GENERAL UTILITIES Page 10-4 SECN is the secondary, 4 Ascii characters in I*4 longword.(input) The following secondaries are allowed: SECONDARY # Data Words Returned Type of Data Returned NAME 4 8 Ascii Characters LIMS 4 2 Real*4 values SCAL 4 2 Real*4 values CTRL 2 1 Integer*4 value STAT 1 1 Integer*2 value DATA 2 1 Real*4 value (scaled data) CHAN is the channel name, I*4 array (2 longwrods). 8 Ascii characters blank filled. (input) If CHAN contains the wildcard *, all channels that start with the characters preceeding the * will be returned. Example: STAT=DBLIST_ASTS(LIST,'LI00',1,'DATA','ISO_PLAN') This call will increment the list with the pointers for the ISO-PLANE temperatures in sector LI00. List must be long enough to contain 4 I*2 words for each item referenced list structure: 2 word standard header quad words as follows: doublets consisting of node into dbnodes pointing to the micro and pointer into db pointing to the subtype block pointer to beginning word for specified channel # of I*2 words to transfer
GENERAL UTILITIES Page 10-510.1.4 DBUNITS_ASTS DBUNITS_ASTS INTEGER*4 FUNCTION DBUNITS_ASTS(LIST,MICR,CHAN) This INTEGER*4 function will return a database units list similar to that returned by DBUNITS. The differences are the following: The PRIM is assumed to be ASTS. LIST is an I*2 output array. The user responsibilities are: The first word of the array must be the length of the array. If a new list is being started, as opposed to incrementing an existing list, then the second word must be set to 0. MICR is the micro name, 4 Ascii characters in I*4 longword.(input) ALL* allowed. CHAN is the channel name, I*4 array (2 longwords). 8 Ascii characters blank filled. (input) If CHAN contains the wildcard *, all channels that start with the characters preceeding the * will be returned.
10.1.5 DB_ASTS_VALID DB_ASTS_VALID
GENERAL UTILITIES Page 10-6 INTEGER*4 FUNCTION DB_ASTS_VALID(MICR,UNIT,CHAN) This Integer*4 function checks whether the specified channel (CHAN) is valid for the given micro (MICRO) and unit (UNIT). DB_OKOK is returned if valid, else DB_BADMICR, DB_BADUNIT, or DB_BADCHAN etc. (something false) is returned. The PRIM is assumed to be ASTS. MICR I*4 ascii micro name (input) It must specify a single micro (ALL* is NOT allowed). UNIT I*4 ascii OR integer representation of unit number (input) It must specify a single unit (ALL* is NOT allowed). CHAN I*4 array (2 longwords) ascii channel name (8 characters blank filled) (input). It must specify a single channel.10.2 BPM UTILITIES Several steps must occur before an operator may display BPM data using the standard displays available from the touchpanel. First a Measurement Definition must be created, which specifies the range of BPMs to be measured, the beam on which they are to be measured, and certain other parameters (e.g., timing values). Next the Measurement Definition must be calibrated. Finally, the operator may request measurement data; the data will be acquired by the micros, sent to the SCP, and displayed. Four classes of BPM utilities exist so that programs may acquire BPM data for their own use rather than for the standard BPM displays available from the touchpanel: routines to
GENERAL UTILITIES Page 10-7 manipulate Measurement Definitions (BPM_CREATE_DEF, BPM_SELECT_DEF, BPM_READ_DEF), a routine to download calibration data (BPMCAL_DOWNLOAD_UTIL), a routine to cause new measurement data to be acquired by the sector micros (BPM_AVG), and routines to pass that data to the calling program (BPMGET, BPMLIST, and BPMLGET). Most of these routines are also used by the BPM touchpanel code. The most notable difference in the process of acquiring data under program control or through the touchpanel is in the calibration step: for now the only way to make a NEW calibration is through the touchpanel.10.2.1 BPM_CREATE_DEF INTEGER*4 FUNCTION BPM_CREATE_DEF(MEASDEF_RECORD, MEASDEF_SN,BUTTON_NUM) This routine will create a Measurement Definition with the characteristics supplied in MEASDEF_RECORD. The new definition will be current (i.e., the one with the bar), just as it would be if it had been created through the touchpanel. ARGUMENTS: MEASDEF_RECORD record input See SLCTXT:BPMSTRUC.TXT for the definition of the structure type MEAS_DEF_STRUC MEASDEF_SN I*4 output Unique identifier for the meas. def created. This quantity must be supplied by the calling program in some of the utilites defined below. BUTTON_NUM I*2 modify This argument is used to specify in which button the new measure- ment definition is to be stored. If it is in the range 1-MAXDEFS (the latter is currently 5) that button will be used. If it is
GENERAL UTILITIES Page 10-8 set to the special flag value -1, the first "empty" button, if any will be used; if there are none, button number 1 will be used. On output BUTTON_NUM always contains the number of the button actually used. FUNCTION RETURNS: BPMO_OKOK Success BPMO_NOSUCHBUTTON Invalid BUTTON_NUM argument BPMO_BADRANGE Illegal range or range inconsistent with display group in MEASDEF_RECORD argument BPMO_BADPP Illegal PP component in MEASDEF_RECORD argument BPMO_BADTS Illegal TS component in MEASDEF_RECORD argument BPMO_BADBUNCH Illegal BUNCH component in MEASDEF_RECORD argument. It is also possible for the function to return a system code if some system service or run-time-library routine has been called and failed on behalf of BPM_CREATE_DEF.10.2.2 BPM_READ_DEF INTEGER*4 FUNCTION BPM_READ_DEF(MEASDEF_RECORD, MEASDEF_SN) This function gets the values of measurement definition parameters and stores them in the supplied argument. ARGUMENTS: MEASDEF_RECORD record or output Record or records to contain array returned data on the requested measurement definitions. See include file SLCTXT:BPMSTRUC.TXT. MEASDEF_SN I*4 modify Specifies which meas. def. record is to be copied to MEASDEF_RECORD argument. If MEASDEF_SN is in fact the
GENERAL UTILITIES Page 10-9 sequence number of a current- ly defined meas. def, that meas. def. will be copied. If it is the special flag value -1, the current meas def will be copied, and MEASDEF_SN will be modified to be its sequence number. If MEASDEF_SN is the special flag value 'ALL*' all currently de- fined meas. defs will be copied. In this case MEASDEF_RECORD should be an array dimensioned to MAXDEFS (see the include file SLCTXT:BPMPARAM.TXT). FUNCTION RETURNS: BPMO_OKOK Success BPMO_NOSUCHSN Illegal MEAS_DEF_SN argument BPMO_NOCREATE No measurement definitions have been created yet.10.2.3 BPM_SELECT_DEF INTEGER*4 FUNCTION BPM_SELECT_DEF(MEASDEF_SN) This function selects (i.e., makes current) the specified meas. def. ARGUMENTS: MEASDEF_SN I*4 input Measurement definition to be selected (i.e., made current). This must be the sequence number of an existing measurement definition. FUNCTION RETURNS BPMO_OKOK Success BPMO_NOSUCHSN Illegal MEAS_DEF_SN argument BPMO_NO_CREATE No measurment definitons have been created BPMO_CALUNFERRR Unable to read in calibration file for this measurement definition (meas def will be selected, but must be re-calibrated to be
GENERAL UTILITIES Page 10-10 used).10.2.4 BPMCAL_DOWNLOAD_UTIL INTEGER*4 FUNCTION BPMCAL_DOWNLOAD_UTIL(CALB_FILE, BUTTON_NUM, MEASDEF_SN, OVERRIDE,OVERRIDE_MASK) -------- ------------- BPMCAL_DOWNLOAD_UTIL creates a measurement definition and downloads calibration information to the affected micros. This is accomplished by first reading in the user-specified (old) calibration file. The file contains all the information necessary to re-create the measurement definition in effect when the calibration was done. The caller may override some of the components of the measurement definition by means of the optional arguments OVERRIDE (a record of type MEAS_DEF_STRUC) and OVERRIDE_MASK (a mask to indiciate which components of OVERRIDE should override the corresponding components read from the calibration file). ARGUMENTS: CALB_FILE CHARACTER*(*) input Name of unformatted file created by previous cal- ibration containing meas def parameters and cali- bration data. BUTTON_NUM I*2 modify Button number for new meas def to be created. If in the normal range, specified button number will be used. If -1, BPMCAL_DOWNLOAD_UTIL will choose a button in which to put the new meas def, and its number will be returned in BUTTON_NUM. MEASDEF_SN I*4 output Sequence number of the new
GENERAL UTILITIES Page 10-11 measurement definition. OVERRIDE record input Optional record of type MEAS_DEF_STRUC which may be used to override some components of the meas def in CALB_FILE. OVERRIDE_MASK I*4 input Optional bit mask indicating which components of OVERRIDE should override corresponding components of the meas def record read from CALB_FILE. See SLCTXT:BPMSTRUC.TXT for definitions of meanings of bits in the bit mask. FUNCTION RETURNS: BPMO_OKOK Success BPMO_CALUNFERR Unable to read or open CALB_FILE. Depending on when the error occurred, the new meas def will either not have been created at all, or will have been cre- ated successfully, but will not be usable until calibrated (from the touchpanel). BPMO_FAIL Failure in downloading calibration data. New meas def has been created, but must be calibrated (from the touchpanel) before it may be used. Any status which may be returned by BPM_CREATE_DEF may also be returned here. See description under BPM_CREATE_DEF above.10.2.5 BPM_AVG INTEGER*4 FUNCTION BPM_AVG(NMEAS, DEVICE) ------ This is the function which acquires BPM data. One call to BPM_AVG will acquire a single data point (possibly the result of several measurements) for each hardware device within the range specified by the current measurement definition and of a type consistent with the value of the DEVICE argument. Before BPM_AVG can be used a valid
GENERAL UTILITIES Page 10-12 measurement definition must be selected (either from the panel or via BPM_SELECT_DEF or BPM_CREATE_DEF) and the micros concerned must have valid calibration information, either from a calibration requested from the panel, or downloaded because of a previous call to BPMCAL_DOWNLOAD_UTIL. The caller may choose how many measurements are to be averaged to produce a single data point per hardware device, and which type(s) of hardware will be used. The data so acquired will not be available to the caller until he has made appropriate calls to the BPM data access routines BPMLIST and BPMLGET or BPMGET. ARGUMENTS: NMEAS I*4 input number of measurements to be taken and averaged to produce a single data point for each device. DEVICE I*2 input optional bit mask indicating from which primaries data should be collected. Current possibilities are BPMS's, tor- oids, and beam width monitors. See SLCTXT:BPMPARAM.TXT for bit definitions. If omitted, this argument defaults to MEASBPM_BIT + MEASBWM_BIT i.e., measure BPMS's and BWMS's. FUNCTION RETURNS: BPMO_OKOK Success BPMO_NO_MEASDEF No currently-selected measurement definition BPMO_NOCAL Currently-selected measurement definition does not have a valid calibration. BPMO_FAIL BPM operation has failed. When returned by BPM_AVG, it means that an illegal value for NMEAS has been supplied, there are no units of the requested primaries within the cur- rent range, or that the act of taking data failed. BPMO_ABORT Operator aborted operation with ^C BPMO_MPGREQ Request to MPG failed. This usually means a PP was requested which in fact is not being broadcast. BPMO_NORESLTS No data was received from any sector micros
GENERAL UTILITIES Page 10-13 BPMO_NETERR Network error BPMO_NETTIME At least one sector micro (but not all) did not send back data within the time limit.10.2.6 BPMLIST INTEGER*4 FUNCTION BPMLIST(CLIST_HEADER, COMMANDLIST, PRIM, MICR, UNIT, SECN) BPMLIST is used to create lists for BPM (or BPM-like) data, much as DBLIST is used to create lists for data contained in the database. The list created will always be for the current measurement definition, but may be used when the measurement definition is no longer current (but still exists in some button or other). ARGUMENTS: CLIST_HEADER I*2 array modify Three-word array which describes the COMMANDLIST array, much as the first TWO words of a database list describe the list. The first word of CLIST_HEADER must be set by the caller to the declared length (in words) of COMMANDLIST. The second word in CLIST_HEADER is the "active length" of the COMMANDLIST. It is generally initialized by the caller to zero before the first call to BPMLIST. Thereafter the caller should re- initialize the second word to zero only when he wishes to create a new list; he should leave it alone when he wishes to append. The third word in CLIST_HEADER should not be touched by the caller; it is both written and read exclusively by the BPM utilities. COMMANDLIST I*2 array output Array in which list information is kept. A pair of I*2 words will be needed for each "item" in the list.
GENERAL UTILITIES Page 10-14 Here "item" means a single (PRIM,MICR,UNIT,SECN) entry, where SECN may be 'ALL*', or both UNIT and SECN may be 'ALL*' (or, of course, just a single pseudo- secondary for a single unit is specified). PRIM I*4 input BPM-like database primary. Allow- able values include 'BPMS', 'BWMS' and 'TORO'. MICR I*4 input Ascii micro name UNIT I*4 input Integer unit number, Ascii unit number, or special Ascii value 'ALL*' SECN I*4 input Pseudo-secondary name or special value 'ALL*' (recommended for efficiency). Acceptable values for SECN depend on the supplied value of PRIM. In addition to 'ALL*', acceptable for any primary, the following combina- tions are allowed. For PRIM = 'BPMS', SECN may be 'X ', 'Y ','TMIT','XRMS','YRMS','TRMS', 'QRAW','STAT' or 'GMEAS'. For 'TORO' SECN may be 'TMIT','TRMS', 'QRAW', 'STAT' or 'GEAS'. For 'BWMS' SECN may be 'QMOM', 'TMIT', 'MRMS','TRMS','QRAW','STAT' or 'GEAS'. FUNCTION RETURNS: BPMO_OKOK Success BPMO_NO_MEASDEF No measurement definition is current. BPMO_MICRO_NOT_IN_RANGE Specified micro is not in the range determined by the current meas def. BPMO_BADPRIM Illegal value for PRIM argument. BPMO_BADSECN Illegal value for SECN argument. BPMO_NOBITID Illegal value for MICR argument. BPMO_ZERO_PTRL Specified micro has no units (for any primary) in current meas def. BPMO_LISTSHORT COMMANDLIST is too short for request BPMO_BADUNIT Illegal UNIT argument
GENERAL UTILITIES Page 10-15 BPMO_NOUNIT This micro has no units for requested primary.10.2.7 BPMLGET INTEGER*4 FUNCTION BPMLGET(DLIST_HEADER, DATALIST, CLIST_HEADER, COMMANDLIST) BPMLGET returns BPM (or BPM-like) data in DATALIST. WHICH data is to be returned is determined by the contents of the input array arguments CLIST_HEADER and COMMANDLIST, built up by a previous call or calls to BPMLIST. Typically BPMLIST will be called once, after a mesurement definition has been created. BPMLGET may then be called repeatedly, but always after a fresh (successful) call to BPM_AVG. Whether the data for a particular hardware unit is "good" (i.e., at least new) may be determined by examining the STAT component of the data record for that unit. It is cleared to zero by BPM_AVG before the new data, if any, comes in. ARGUMENTS: DLIST_HEADER I*2 array modify Two-word array. The first word array. The first word should be initialized by the caller to the (I*2) declared length of DATALIST. The second word is the "active length" of DATALIST. It should be initialized by the caller to zero before the first call to BPMLGET, and anytime thereafter that the caller wants to overwrite old data. DATALIST array output Will contain the requested data on output. The type of the array will depend on the data being requested. If,
GENERAL UTILITIES Page 10-16 as is most common, the data is ALL* pseudo-secondaries for a particular primary, DATALIST should be declared as an array of records of the appropriate type, e.g. of type BPMS_DATA for PRIM = 'BPMS'. See the include file SLCTXT:BPMSTRUC.TXT. CLIST_HEADER I*2 array input Three-word I*2 array set by a previous call or calls to BPMLIST. COMMANDLIST I*2 array input Array of pointers set by a previous call or calls to BPMLIST. FUNCTION RETURNS: BPMO_OKOK Success BPMO_NO_MEASDEF COMMANDLIST refers to a non-existent measurement definition. BPMO_LISTSHORT DATALIST is too short for requested data.10.2.8 BPMGET INTEGER*4 FUNCTION BPMGET(DLIST_HEADER,DATALIST,PRIM,MICR, UNIT,SECN) This function makes calls to BPMLIST and BPMLGET on behalf of the caller, using its own internal COMMANDLIST. Multiple calls to BPMGET with the same PRIM, MICR, UNIT and SECN arguments should be replaced by a single call to BPMLIST, followed by multiple calls to BPMLGET. BPMGET only returns data for the current measurement definition. ARGUMENTS: DLIST_HEADER I*2 array modify See description under BPMLGET DATALIST array output See description under BPMLGET
GENERAL UTILITIES Page 10-17 PRIM I*4 input Ascii primary name: 'BPMS', 'BWMS' or 'TORO' MICR I*4 input Ascii microname or 'ALL*' UNIT I*4 input Ascii unit number, integer unit number or 'ALL*' SECN I*4 input Pseudo-secondary name or 'ALL*'. See description under BPMLIST. FUNCTION RETURNS: Any of the values returned by BPMLIST or BPMLGET may be returned by BPMGET.10.2.9 BPM Structure Definitions The include file BPMSTRUCT.TXT which defines the BPM structures is listed below. C Define structures to contain BPMS, TORO, and BWMS data C (Note: BPMPARAM must also be included (somehow).) C C Lengths of the structures... C INTEGER*2 BPMS_DATA_BYTES, TORO_DATA_BYTES, BWMS_DATA_BYTES, > BPMS_DATA_WORDS, TORO_DATA_WORDS, BWMS_DATA_WORDS PARAMETER (BPMS_DATA_BYTES = 34, > TORO_DATA_BYTES = 14, > BWMS_DATA_BYTES = 24) PARAMETER (BPMS_DATA_WORDS = BPMS_DATA_BYTES/2, > TORO_DATA_WORDS = TORO_DATA_BYTES/2, > BWMS_DATA_WORDS = BWMS_DATA_BYTES/2) C C Max total number of data words for a single micro: C INTEGER*2 BPMS_MIC_WORDS, TORO_MIC_WORDS, BWMS_MIC_WORDS PARAMETER (BPMS_MIC_WORDS = BPMS_DATA_WORDS*MBPMS, > TORO_MIC_WORDS = TORO_DATA_WORDS*MAXTOR, > BWMS_MIC_WORDS = BWMS_DATA_WORDS*MBWMS) C C STRUCTURE /BPMS_DATA/ REAL*4 X, Y, TMIT, X_RMS, Y_RMS, TMIT_RMS INTEGER*2 QRAW(3), STAT, GOODMEAS END STRUCTURE ! BPMS_DATA_STRUC C
GENERAL UTILITIES Page 10-18 STRUCTURE /TORO_DATA/ REAL*4 TMIT, TMIT_RMS INTEGER*2 QRAW, STAT, GOODMEAS END STRUCTURE ! TORO_DATA_STRUC C STRUCTURE /BWMS_DATA_STRUC/ REAL*4 QUAD_MOMENT, TMIT, QMOM_RMS, TMIT_RMS INTEGER*2 QRAW(2), STAT, GOODMEAS END STRUCTURE ! BWMS_DATA_STRUC C STRUCTURE / MEAS_DEF_TYPE/ INTEGER*2 PP INTEGER*2 TS INTEGER*2 BUNCH INTEGER*4 BUNCH_DEL INTEGER*2 ATTN REAL*8 DGRP UNION MAP INTEGER*4 ASC_FMIC END MAP MAP CHARACTER*4 CFMIC END MAP END UNION UNION MAP INTEGER*4 ASC_LMIC END MAP MAP CHARACTER*4 CLMIC END MAP END UNION LOGICAL*1 SIGN LOGICAL*1 CALIB INTEGER*4 MEAS_DEF_SN CHARACTER*25 CALIB_FILE END STRUCTURE ! MEAS_DEF_RECORD10.3 KLYSTRON UTILITIES There are a number of routines which are "customized" to support the needs of klystron control.
GENERAL UTILITIES Page 10-19 The following routines are available to the user: o KLYS_GET_ENERGY -- Returns the energy gain per klystron for a set of klystrons, including selected "second order effects", as directed by an options argument. o KLYS_MOD -- Returns a value which is symmetrically bounded. (ie.: +/- 180 or +/- 360 degrees). o KLYS_TRIM -- Requests the "trimming" of a set of klystron phase shifters. o KLSY_TRIM_ONE -- Requests the "trimming" or "perturbing" of a klystron's phase shifter. o KLYS_STAT -- A package (including co-routines) to allow the recovery of the returned status' from micros when using the MSG_SYNC routines.10.3.1 KLYS_GET_ENERGY The KLYS_GET_ENERGY routine uses the no-load energy gain (ENLD) as the reference energy in its computations. "Second order" effects of energy contribution can be selected by setting the appropriate bits in a flag argument. The effects currently are: o PHASE OFFSET -- Multiply the ENLD of each klystron by the cosine of the rf phase to account for the specific phase of each klystron. o SLED TIMING -- Multiply the ENLD of each klystron by a SLED timing factor to account for beam time with respect to the SLED cavity output. o BEAM LOADING -- For the specified bunch, include the beam loading effects due to earlier bunches and the specified bunch. This is currently not included in the calculation. o BUNCH PHASE -- Account for the difference of the rf phase for the different bunches. This is currently not included in the calculation. o WAVE GUIDE -- Account for the different lengths of disc-loaded wave guide which are excited by the beam loading effect. This is Acurrently not included in the calculation.
GENERAL UTILITIES Page 10-20 o INCLUDE_STANDBY -- Do energy calculation as if the klystron is accelerating, effectively ignoring whether the klystron is activated or deactivated on the specified beam. iss = KLYS_GET_ENERGY (ELIST, MICRO, UNIT, BEAM, BUNCH, DGRP, FLAGS) ----- ---- ----- ARGUMENTS: (required) ELIST I*2 array standard list with a two word header. MICRO I*4 micro name of klystrons of interest. Can be ALL*. UNIT I*4 ASCII or binary unit number of klystron. Can be ALL*. BEAM I*4 ASCII or binary beam number for which energy gain is to be calculated. Cannot be ALL*. ARGUMENTS: (optional) BUNCH I*4 integer particle bunch number. Allowed values values are 1, 2, or 3. If not present, then beam loading and bunch phase effects are not included in the calculation. DGRP R*8 ASCII display group name. If not present, the LIN_KLYS display group will be assumed. FLAGS I*4 bit mask which selects specific effects to be included in the energy calculation. The bit settings are defined in the KLYS_GET_ENERGY_OPTIONS.TXT include file. If not present then KGE_ALLSOE bit settings are assumed, which includes all "second order" effects and excludes standby klystrons. RETURNS: The second word of the ELIST will be updated to the new length of the list and the calculated energies will be appended into the list. Energy units are giga electron volts (GeV). FUNCTION RETURNS: KLYS_OKOK: success. KLYS_LISTSHORT: ELIST too short to hold all the data. ELIST is unchanged. TIME_BADARG: BEAM cannot be ALL* or invalid bunch number. Values returned by:
GENERAL UTILITIES Page 10-21 LINAC_KLYS_STAT DBGET NOTE: MICRO is allowed to be ALL* only when UNIT is ALL*. This restriction is imposed by LINAC_KLYS_STAT.10.4 KLYSTRON DATA ACCESS UTILITIES Klystrons are complicated animals, and there is a lot more information available to the user than exists in the SLC DataBase. Some of the additional information is of the nature of beam-code specific Fast Time Plots, while other information is not considered critical to the real-time control of accelerator klystrons for SLC. The following distinct classes of data sets are available to the user: o The PIOP Data FTP -- Contains approximately 60 of the internal working constants available to the internal processor. The block contains variables which are not considered critical to the real-time control of the system, but rather used for specific diagnostic purposes. o The "Standard" FTP -- Contains the 64 data points which are used to create the standard FTP display. The data is "unreduced", and is available to higher level code which might do further analysis such as the calculation of the no-load energy gain from an amplitude FTP. o The "Error Log" -- Contains the counts of signaled errors which were generated by the PIOP. The result is a count from either the most recent IPL, or since the last read_and_clear command.
GENERAL UTILITIES Page 10-22 These blocks are available to higher level code through the "KLYS_FTP_DRVR" package of routines. The primary routine, KLYS_FTP_DRVR, allows the user to cause the data acquisition associated with any of the above standard displays. This routine supports standard micro-lists, as well as wild cards (ALL*) for either the primary or unit specifier. Virtual memory is acquired to contain the desired results, and the data is scaled by the applicable constants to convert the data into "real*4" engineering units. A structure-based storage system allows the data to be accessed symbolically in it's raw form (I*2), scaled form (R*4), as well as the Primary, Micro, Unit, and Status. There are a few unallocated words in the structure for use by subsequent analysis routines. The following routines are intended to help the user access some of this data. o KLYS_FTP_DRVR -- The FTP data acquisition routine. o KLYS_FTP_SBCALL -- The coroutine caller routine. Calls a user-supplied routine with the dynamic structures directly accessable. o KLYS_FTP_TEMPLATE -- A template for a subroutine or function called by the ...SBCALL routine (above). o KLYS_FTP_DEL -- Allows the user to give back the acquired virtual memory used in the FTP request. o PIOP_DATA_GET -- Used by a coroutine to extract and convert the PIOP Data found in the returned data structure from the raw integer data to a user list in the appropriate (usually R*4) format in engineering units. o PIOP_DATA_VALID -- Tests the supplied Pseudo-secondary against the list of supported items, and returns true if valid.
GENERAL UTILITIES Page 10-23 o INCLUDE '(KFTP_STRUC)' -- The structure definitions used by the above for internal data storage.10.4.1 KLYS_FTP_DRVR KLYS_FTP_DRVR is the data acquisition routine used for accumulating FTP type data. An appropriate message service package is constructed, and the necessary dynamic memory is acquired. A message service call is made to all of the micros in the supplied micro-list, and a coroutine copies the data into the acquired memory. A second pass is made through the data, updating each item's status word and scaling the raw data into engineering units as required. The return status is the accumulated (and optionally) signaled status. ie: "KLYS-E-ERROR Klystron FTP Completed with errors". The status of individual item should be used to regulate the processing of data, since single item errors are not uncommon. ISS = KLYS_FTP_DRVR( PRIMARY, MICRO, UNIT, DATA_SET, > START, STEP, SUMMARY_FLAG, BEAM_FLAG, P_DESCR) Integer*4 KLYS_FTP_DRVR returned status. Integer*4 PRIMARY primary or "ALL*". Integer*4 MICRO micro or micro-list. Integer*4 UNIT unit (Hollerith or Integer) or "ALL*" Character*8 DATA_SET name of logical data_set. Integer*4 START start offset. Integer*4 STEP step size. Integer*4 SUMMARY_FLAG logical -- signal summary messages? Integer*4 BEAM_FLAG logical -- use global beam? Real*8 P_DESCR token to describe memory set. The arguments are used as needed to acquire the data. Their meanings are: o PRIMARY -- Usual Primary name or "ALL*". ALL* indicates all klystrons, sub-boosters, and RF devices in the sector. If the nature of the selected "data_set" requires special hardware (ie: MKSU), the individual item status is set to zero for the un-supported hardware.
GENERAL UTILITIES Page 10-24 o MICRO -- Usual Micro name or micro-list. See message service chapter. o UNIT -- Unit name or "ALL*". ALL* returns units in the DBUNITS order, and is the default for PRIMARY=ALL*. o DATA_SET -- Symbolic name for DATA_SET type. Currently supported DATA_SETs are: - PIOPDIAG -- The PIOP diagnostic data. See routine PIOP_DATA_GET for further information. - PHASE -- Phase-type FTP. Phase vs Time. - PHAS_RAW -- Special diagnostic phase plot. Uncorrected phase-type units vs Time. - MIXER -- Special phase mixer diagnostic. Raw mixer volts vs Phase shifter. - AMPL_%, AMPL_MW, AMPL_MEV -- Amplitude type FTP. Amplitude units as implied vs Time. - SATURATE -- Saturation type FTP. Amplitude (%) vs Drive. - BEAMVOLT, BEAMCURR -- Klystron input FTP. Volts or Amps vs Time. - KLYS_FE, KLYS_RE, KLYDRIVE -- Forward, Reflected, and Drive FTP. - PERVEANC -- Klystron Perveance FTP. Perveance vs Time. - AMP-DRIV -- Special timing FTP. Klystron FE output minus DRIVE input is acquired vs Time. Both signals have been normalized to a maximum of 10 Volts. - MKSU_CAL, MKSU_GND -- Special Calibration FTP for MKSU internal sample circuits. - ERRORS, ERRORS_C -- Read error log (and perhaps clear). No scaling of data. o START -- Applicable on Time-domain requests only. Values of "CENT"er or "NORM"al produce FTP's which are as the SCP uses, or centered about the PADO time. Other values (Integers) are wrt TREF in PDU Ticks. o STEP -- Applicable as START above. Values of "WIDE", "NORM"al, "NARR"ow, and "JITT"er are specifically supported. Other values (Integers) are in PDU Ticks. o SUMMARY_FLAG, BEAM_FLAG -- Logical flags. See above.
GENERAL UTILITIES Page 10-25 o P_DESCR -- Real*8 Descriptor of virtual memory. Should be zero on first use, and never changed except by the KLYS_FTP utilities.10.4.2 KLYS_FTP_SBCALL This routine takes the memory token (supplied) and any optional parameters, and calls the coroutine with the correctly computed memory references and the supplied arguments. The status returned is the value of the coroutine. ISS = KLYS_FTP_SBCALL( COROUTINE, P_DESCR, ARG1, ... ) Integer*4 KLYS_FTP_SBCALL returned status. Real*8 P_DESCR token to describe memory set. (any) ARG1 optional, coroutine specific argument.
10.4.3 KLYS_FTP_TEMPLATE Routine is a blank template with some comments reminding the user of the more important structure elements. Include files and required declarations are supplied. This module has parameters as expected by KLYS_FTP_SBCALL.
10.4.4 KLYS_FTP_DEL Deletes dynamically allocated memory allocated for a previous FTP request. Routine sets token to zero, and should always return true. ISS = KLYS_FTP_DEL( P_DESCR) Integer*4 KLYS_FTP_DEL returned status. Real*8 P_DESCR token to describe memory set.
GENERAL UTILITIES Page 10-2610.4.5 PIOP_DATA_GET For the data_set type "PIOPDIAG", the data is not scaled into engineering type units. The reason is twofold: 1) the resultant data type ranges from I*2 to 8-byte Tmask, and 2) some users are only interested in one piece of data per item. (ie: "Z"-plots.) The routine PIOP_DATA_GET converts the requested pseudo-secondary from the ...RAW_DATA(x) into the appropriate engineering system, and appends it to the user's list. ISS = PIOP_DATA_GET( DLIST, RESULT(mic), 'PSECN ') Integer*4 PIOP_DATA_GET returned status. (Array) DLIST standard database-type list. Structure RESULT(mic) incoming data structure. Real*8 'PSECN ' Symbolic secondary name. (Hollerith.) The routine is designed to "eat" the incoming data in micro-sized pieces, and for multiple micro use, a "DO" loop is in order. The valid Pseudo-secondaries for this routine will evolve as the PIOP is upgraded to meet the needs of SLC control, and the user is referred to the source code for the complete list.
10.4.6 PIOP_DATA_VALID This routine evaluates a candidate pseudo-secondary against the supported list, and returns true if valid. ISS = PIOP_DATA_VALID( 'PSECN ') Integer*4 PIOP_DATA_VALID returned status. Real*8 'PSECN ' Symbolic secondary name. (Hollerith.)
GENERAL UTILITIES Page 10-2710.4.7 KFTP_STRUC Include Item The KLYS_FTP_... routines use a set of structures which contain the local knowledge of the requested data set. There are two sets which are of special interest to the higher level user: o KFTP -- Contains the context of the data acquisition. This is a fixed length structure which contains no information specific to a single klystron station (or item). o RESULT -- Contains the resultant data, status's, and some post-processor results. This is ordered by micro and by item. The include item contains the structure definitions for these and some other structures. NOTE: this include library item is subject to change as the needs change, and any user who does not reference the data symbolicaly through these declarations will be generating unsupportable code.
10.4.7.1 KFTP Structure - The contextual structure RECORD /KFTP_STRUC/ KFTP contains the information used by the KLYS_FTP... facility to generate the data request. Some of the elements are: Type Element KFTP. Contents ---- ------------- -------------------------- I*4 .NMICROS_USED Actual number of micros C*8 .DATA_SET Symbolic "data_set" name I*4 .BEAM_FLAG Logical -- Was global beam used? C*8 .X_TYPE Symbolic X-axis "type" C*8 .Y_TYPE Symbolic Y-axis "type" C*60 .MAIN_TITLE Main title for FTP type displays C*48 .X_TITLE X-axis title for FTP type displays C*32 .Y_TITLE Y-axis title for FTP type displays I*4 .PRIMARY Primary (name or "ALL*") for errors I*4 .MICRO Micro (name or "LIST") for errors I*4 .UNIT Unit (name or "ALL*") for error C*12 .POSTPROCESSOR Name (user supplied) of postprocessor
GENERAL UTILITIES Page 10-2810.4.7.2 RESULT Structure - The ITEM Specific structure a) RECORD /KFTP_RESULT_STRUC/ RESULT(*) or b) RECORD /.../ RESULT provides access to the structure elements of a) many, or b) one micro of data. Some of the elements are: Type Element RESULT(mic). Contents ---- -------------------- ----------------------------- I*2 .N_ITEMS Number of items "this" element I*4 .ITEM(item).PRIMARY Primary. ie: "KLYS" I*4 .ITEM(item).MICRO Micro. I*4 .ITEM(item).UNIT Unit. (Hollerith) ie: " 21" I*4 .ITEM(item).STATUS Status of this FTP request. I*2 .ITEM(item).RAW_DATA(-2:64) Raw data for this item. R*4 .ITEM(item).X_START Start time or value for data. R*4 .ITEM(item).X_STEP Step time or value for data. R*4 .ITEM(item).T_OFFSET Delay from nominal time for start. R*4 .ITEM(item).Y_DATA(64) Scaled data. I*4 .ITEM(item).USER_STATUS Status of this postprocessor run. R*4 .ITEM(item).USER(10) Real data from analysis. I*4 .ITEM(item).USER_I(5) Integer data from analysis.
10.5 MAGNET UTILITIES
10.5.1 MAG_ADCL This routine finds the CTLW of the ADC used by a specific primary, etc. The result is returned directly, and no list-structure is needed. ISS = MAG_ADCL( ADCL, CHANNEL, PRIMARY, MICRO, UNIT, SECONDARY ) --------- Integer*4 MAG_ADCL returned status. Integer*4 ADCL returned CTLW. Integer*4 CHANNEL returned ADC channel. Integer*4 PRIMARY primary name. Integer*4 MICRO micro name. Integer*4 UNIT unit name. Integer*4 SECONDARY secondary name. (optional - defaults to 'ADCP') Return status is as returned by the DBGET facility, or .FALSE. if the inferred adc location is noticably invalid.
GENERAL UTILITIES Page 10-29 The secondary name is only needed when requesting information about devices which have multiple ADC channels associated with them (ie.: the STEP primary), and should, in general, not be supplied.10.5.2 MAG_FUNC This routine sends a data list to the micro magnet job consisting of triplets of I*4 values - Primary, first unit, last unit. The list is built and transmitted to the requested micro(s) with function code FUNC and optional display group, terse, and timeout. NOTE: It is STRONGLY RECOMMENDED that users call MAG_LIST first to construct the input LIST. MAG_FUNC takes an input list in arbitrary order and sorts it by micro before constructing the outgoing messages. Users MUST NOT assume that the list order after a MAG_FUNC call is the same as the input list. ISS = MAG_FUNC( FUNC, LIST, DGRP, TERS, TIME) Integer*4 FUNC magnet function code (any of 'TRIM', 'CALB', 'STDZ', 'PTRB', 'ZERO', 'RSET', 'CHCK') Integer*2 LIST a standard SLC list consisting of maximum length (I*2), current length (I*2), and one or more quadruplets of micro (A*4), primary (A*4), first unit (I*4), and last unit (I*4). 'ALL*' may be specified for primary or unit entries. Real*8 DGRP optional display group name (A*8) for msgs Logical*4 TERS optional flag to allow/suppress messages Integer*4 TIME optional timeout value in milliseconds-- usually the default selected by MAG_FUNC is adequate. If TERS is not specified then MAG_FUNC assumes the caller will handle any errors. If TERS is .FALSE. then then all messages will be issued. If TERS is .TRUE. then success messages will not be issued.
GENERAL UTILITIES Page 10-3010.5.3 MAG_LIST This routine builds a data list for the micro magnet job consisting of quadruplets of I*4 values - Micro, Primary, first unit, last unit. If micro is ALL*, it is expanded using the Display group argument. ISS = MAG_LIST( LIST, PRIM, MICR, FRST, LAST, DGRP) Integer*2 LIST a standard SLC list consisting of maximum length (I*2), current length (I*2), and one or more quadruplets of micro (A*4), primary (A*4), first unit (I*4), and last unit (I*4). Integer*4 PRIM database primary name or 'ALL*' Integer*4 MICR micro name or 'ALL*' Integer*4 FRST first unit number in range or 'ALL*' Integer*4 LAST optional last unit number in range or 'ALL*' Real*8 DGRP optional display group name (A*8) If the optional argument LAST is not specified then FRST will be used. If FRST is ALL*, the appropriate limits for the DGRP are used and LAST is ignored.
10.5.4 MAG_READ_ADC This routine reads the adc implied by the Primary etc. using transparent CAMAC. The result is returned directle, and no list-structure is needed. The result is always in VAX/VMS Real*4 floating point format, converted from IEEE format as necessary. ISS = MAG_READ_ADC( VALUE, PRIMARY, MICRO, UNIT, SECONDARY ) --------- Integer*4 MAG_READ_ADC returned status. Real*4 VALUE returned value. Integer*4 PRIMARY primary name. Integer*4 MICRO micro name. Integer*4 UNIT unit name. Integer*4 SECONDARY secondary name. (optional - defaults to 'ADCP') Return status is as returned by the DBGET facility, the CAMAC
GENERAL UTILITIES Page 10-31 facility, or .FALSE. if the inferred adc location is noticably invalid. The secondary name is only needed when requesting information about devices which have multiple ADC channels associated with them (ie.: the STEP primary), and should, in general, not be supplied.10.6 TIMING UTILITIES The Timing Utility routines allow easy and efficient access to the timing values of the controlled pulsed devices in the SLC. There are two classes of device referred to in the routines; Pulsed Class Devices (PCD), and Devices Using Pulsed Class Devices (DUPCD). The timing values are stored in a data structure known as the T_MATRIX which is shared by all processes on the VAX which need to access the timing values, just as the Data Base is shared. Timing values are addressed by the device (PRIM, MICRO, UNIT), and beam number. The routines available to the user to get timing values and information about the T_MATRIX are:
GENERAL UTILITIES Page 10-32 o GET_TREF -- Returns the specified DUPCDs standard reference time and its PDU time, if its PCD is a PDU. o TM_ACTIVATE -- Activates the specified DUPCD(s) to "standard" activate value(s) (cannot be used for primary='PAU '). o TM_ACTIVATE_KLYS -- Activates the specified klystron(s) to "standard" activate value(s), after checking TMSK compatibility and, if necessary, activating the associated SBST. o TM_DEACTIVATE -- Deactivates the specified DUPCD by placing a deactivate timing value in the T_MATRIX. o TM_DEACTIVATE_KLYS -- Deactivates the specified klystron(s) by placing a deactivate timing value in the T_MATRIX. SBST is also deactivated if there are no klystrons using SBST left active in the sector. o TM_DEVICE -- Returns the primary and unit of the DUPCD which is driven by the specified PCD channel. o TMGET -- Returns the timing value of the specified DUPCD for the specified beam. Does a TMLIST and then a TMLGET. o TMLGET -- Returns the timing values for the items specified in an access list which was created by TMLIST. o TMLIST -- Creates an access list for the specified DUPCDs which can then be used for calls to TMLGET and TMLPUT. o TMLPUT -- Puts the given timing values into the T_MATRIX for the items specified in an access list which was created by TMLIST. o TMPCD -- Returns the PCD type, unit number, and channel which drives the specified DUPCD. o TMPUT -- Puts the given timing value into the T_MATRIX for the specified DUPCD. Does a TMLIST and then a TMLPUT. o TM_REACTIVATE -- Reactivates the specified DUPCD with the timing value it had when it was deactivated with TM_DEACTIVATE. o TM_REACTIVATE_KLYS -- Reactivates the specified klystron(s) with the timing value(s) they had when deactivated with TM_DEACTIVATE, after checking TMSK compatibility and, if necessary, reactivating the associated SBST. o TMUNITS -- Returns a list of unit numbers in T_MATRIX order for the given primary and micro. o TNOMINAL -- Returns the sector nominal time for the specified micro and beam.
GENERAL UTILITIES Page 10-33 o TRIG_RATE -- Returns the total rate at which the specified DUPCD is being triggered for all beams being produced by the MPG. o T_VAL_IS_DEACT -- This function determines if a given timing value is a valid deactivate, valid activate, or an invalid value.
GENERAL UTILITIES Page 10-34 The routines TMGET, TMLGET, TMLIST, TMLPUT, TMPUT, and TMUNITS have direct DataBase analogs and use the same list structure with two I*2 header words. All timing values, supplied or returned, are I*4 integer number of PDU ticks of 119 megahertz. The valid beam numbers are in the range [1,N_BEAMS], N_BEAMS being defined in the SLCPARM.TXT include file. All of the routines are I*4 functions and return status codes from the TIME facility.
GENERAL UTILITIES Page 10-3510.6.1 GET_TREF GET_TREF is used to get parts of the actual timing value for a DUPCD from the DataBase which are fixed by the installation of the DUPCD, such as the delay time from the PCD to the DUPCD, and the standard timing value given when the DUPCD is activated. These values are useful for displaying timing values since the time with respect to some other part of the timing value is more meaningful to users than absolute timing values. iss = GET_TREF (PRIM, MICRO, UNIT, TREF, PDUT) ---- ---- This function will get PDUT for the DUPCD spceified by PRIM, MICRO, UNIT, and return the PCD's TREF. If PRIM is PDU, then only its TREF is returned and PDUT is ignored. If PRIM is PSU, then PSUT is returned instead of PDUT. ARGUMENTS: (required) PRIM I*4 DUPCD primary name. Cannot be ALL*. MICRO I*4 DUPCD micro name. Cannot be ALL*. UNIT I*4 DUPCD binary unit number. Cannot be ALL*. RETURNS: (optional) TREF I*4 associated PCD's TREF, in ticks. PDUT I*4 specified DUPCD's PDUT. FUNCTION RETURNS: TIME_OKOK: success. TIME_BADMICRO: invalid micro name. TIME_BADPRIM: primary is not a DUPCD or PDU or PSU. TIME_NOMATCH: DUPCD not found in T_MATRIX to reference PCD.
GENERAL UTILITIES Page 10-3610.6.2 TM_ACTIVATE INTEGER*4 FUNCTION TM_ACTIVATE(PRIM,MICR,UNIT,BEAM) This routine will get the "standard" activate value(s) TREF+PDUT+T_NOMINAL for the specified device(s), put the value(s) in the _MATRIX, and update the micro. Arguments: (required) PRIM I*4 DUPCD primary name (cannot be ALL*) MICR I*4 DUPCD micro name (cannot be ALL*) UNIT I*4 DUPCD unit number (can be ALL*) BEAM I*4 Beam number (cannot be ALL*) Function returns: Values returned by TMUNITS, TMPUT
GENERAL UTILITIES Page 10-3710.6.3 TM_ACTIVATE_KLYS INTEGER*4 FUNCTION TM_ACTIVATE_KLYS(MICR,UNIT,BEAM, > NOTIFY,SBST_OFFSET) In addition to activating klystron(s) specified by MICR,UNIT on BEAM, this routine checks klystron and BEAM TMSK's for compatibility. If a klystron specified by MICR,UNIT does not have a solid state subbooster, this routine makes sure subbooster in MICR is active on BEAM, then activates klystron(s) specified by MICR,UNIT on BEAM. If subbooster was not already active, the subbooster and klystron(s) are all activated to their standard values (TREF+PDUT+T_NOMINAL). If subbooster is already active, the klystron(s) are activated to standard value plus offset of subbooster from its standard value. Arguments: (required) MICR I*4 DUPCD micro name (cannot be ALL*) UNIT I*4 DUPCD unit number (can be ALL*) BEAM I*4 Beam number (cannot be ALL*) NOTIFY L*4 Flag telling whether to put out informational messages when SBST is activated. Returned argument (optional): SBST_OFFSET I*4 Subbooster offset in ticks from standard value
GENERAL UTILITIES Page 10-38 Function returns: Values returned by TMUNITS, TMPUT, TM_VAL_IS_DEACT, TM_VAL_IS_ACTIVE, SOLID_STATE_SBST10.6.4 TM_DEACTIVATE TM_DEACTIVATE changes timing values in the T_MATRIX to valid deactivate values. To restore the old timing values, use TM_REACTIVATE. TM_DEACTIVATE will have no effect on timing values that are already deactivate values. iss = TM_DEACTIVATE (PRIM, MICRO, UNIT, BEAM) This function will get the timing values for the specified DUPCD and beam from the T_MATRIX, set the deactivate bit, and put the values back into the T_MATRIX (and update the micro). ARGUMENTS: (required) PRIM I*4 DUPCD primary name. Cannot be ALL*. MICRO I*4 DUPCD micro name. Cannot be ALL*. UNIT I*4 DUPCD ASCII or binary unit number. Can be ALL*. BEAM I*4 ASCII or binary beam number. Can be ALL*. RETURNS: None. FUNCTION RETURNS: This function returns the values returned by: TMLIST TMLGET TMLPUT
GENERAL UTILITIES Page 10-3910.6.5 TM_DEACTIVATE_KLYS INTEGER*4 FUNCTION TM_DEACTIVATE_KLYS(MICR,UNIT,BEAM,NOTIFY) This routine deactivates the klystron(s) specified by MICR,UNIT on BEAM. If there are no klystrons without solid state subboosters left active on BEAM in the sector, the routine also deactivates the subbooster on BEAM. Arguments: (required) MICR I*4 DUPCD micro name (cannot be ALL*) UNIT I*4 DUPCD unit number (can be ALL*) BEAM I*4 Beam number (can be ALL*) NOTIFY L*4 Flag telling whether to put out informational error messages when SBST is deactivated. Function returns: Values returned by other timing utilities
GENERAL UTILITIES Page 10-4010.6.6 TMDEVICE TMDEVICE is used to find out what DUPCD, if any, is connected to a particular PCD channel. It is useful for PCD allocation diagnostics. This routine is the inverse of TMPCD, which gives PCD information for a particular DUPCD. iss = TMDEVICE (PCDU, PCDC, MICRO, PRIM, UNIT) ---- ---- This function will return the DUPCD PRIMary and UNIT for the PCD unit and channel number of the specified MICRO. The information is obtained from the T_PCD and T_DEVICE arrays of the T_MATRIX structure. ARGUMENTS: (required) PCDU I*4 PCD ASCII or binary unit number. Cannot be ALL*. PCDC I*4 PCD ASCII or binary channel number. Cannot be ALL*. MICRO I*4 PCD micro name. Cannot be ALL*. RETURNS: (optional) PRIM I*4 DUPCD primary name. UNIT I*4 DUPCD binary unit number. FUNCTION RETURNS: TIME_OKOK: success. TIME_BADMICRO: micro name was invalid. TIME_NOMATCH: PCD unit/channel was not found. (Error message not written to the terminal.)
GENERAL UTILITIES Page 10-4110.6.7 TMGET TMGET returns timing values in an array which is treated as a list like the DataBase lists. Use TMGET when repeated access to the same timing values is not needed. If a put or repeated get's are to be done, use TMLIST, TMLGET, and TMLPUT, which make efficient use of an access list. iss = TMGET (DLIST, PRIM, MICRO, UNIT, BEAM) This function will return in DLIST the timing values for the specified DUPCD on the specified BEAM from the T_MATRIX. This routine calls TMLIST and then TMLGET. ARGUMENTS: (required) DLIST I*2 array a list in which values will be returned. PRIM I*4 DUPCD primary name. Cannot be ALL*. MICRO I*4 DUPCD micro name. Cannot be ALL*. UNIT I*4 DUPCD ASCII or binary unit number. Can be ALL*. BEAM I*4 ASCII or binary beam number. Can be ALL*. RETURNS: The second word of DLIST is updated to the new active list length and the timing values are appended into DLIST. FUNCTION RETURNS: TIME_OKOK: success. TIME_BADMICRO: invalid micro name. TIME_INVALIDBEAM: beam number out of the range [1,N_BEAMS]. TIME_NOMATCH: PRIM, MICRO, UNIT not found in T_MATRIX. TIME_LISTSHORT: DLIST too short to hold all data values or too many devices/beams specified. NOTE: When BEAM is ALL*, each DUPCD specified by PRIM, MICRO, UNIT, including ALL* units, will have N_BEAMS timing values, one for each beam.
GENERAL UTILITIES Page 10-4210.6.8 TMLGET TMLGET returns the timing values for DUPCDs specified in an access list which was made by TMLIST. Use TMLGET when repeated access to the same set of timing values is required. The access list can also be used by TMLPUT, so that you can do a TMLIST, TMLGET, modify data, then a TMLPUT with the same access list. iss = TMLGET (DLIST, PLIST) This function will return in DLIST the timing values for the specified DUPCD on the specified beam from the T_MATRIX. The DUPCD/beam's are specified in PLIST, which is generated by TMLIST. ARGUMENTS: (required) DLIST: I*2 array a list in which values will be returned. PLIST: I*2 array an access list made by TMLIST. RETURNS: The second word of DLIST is updated to the new active list length and the timing values are appended into DLIST. FUNCTION RETURNS: TIME_OKOK: success. TIME_LISTSHORT: DLIST too short to hold all values. TIME_BAD_DEV_INDEX: PLIST values corrupted. TIME_INVALIDBEAM: PLIST values corrupted. NOTE: When beam is ALL*, there will be N_BEAMS data values added to the DLIST, one for each beam, for that DUPCD. This means that the DLIST and PLIST may be different lengths after TMLGET is finished.
GENERAL UTILITIES Page 10-4310.6.9 TMLIST TMLIST will make an access list for use with the TMLGET and TMLPUT routines. Unlike the arguments allowed in TMGET and TMPUT, the access list allows the TMLGET and TMLPUT routines to get and put timing values for a variety of DUPCDs in different micros and with different primary names. Make successive calls to TMLIST for all the DUPCDs you need and then just one call to TMLGET will return all the DUPCDs' timing values, or TMLPUT will put all the timing values in the T_MATRIX. iss = TMLIST (PLIST, PRIM, MICRO, UNIT, BEAM) This function will make a T_MATRIX access list for the DUPCD specified by PRIM, MICRO, UNIT, and on BEAM. This access list can then be used for efficient access of timing values in the T_MATRIX with the TMLGET and TMLPUT routines. Use TMLIST when you will do more than one TMGET or TMPUT on the same DUPCD and beam. This way, the list will be built once and re-used, instead of being built for each access of the particular timing values. ARGUMENTS: (required) PLIST I*2 array list into which access pointers will be appended. PRIM I*4 DUPCD primary name. Cannot be ALL*. MICRO I*4 DUPCD micro name. Cannot be ALL*. UNIT I*4 DUPCD ASCII or binary unit number. Can be ALL*. BEAM I*4 ASCII or binary beam number of the desired timing value. Can be ALL*. RETURNS: The active list length is updated to the new active list length and the T_MATRIX pointers are append into PLIST. The active list length is incremented by the number of units that were added to the list times two. So, if UNIT is not ALL*, then the active list length is incremented by two.
GENERAL UTILITIES Page 10-44 FUNCTION RETURNS: TIME_OKOK: Success. TIME_NOMATCH: The specified DUPCD was not found in the T_MATRIX. The active list length is not changed. If UNIT is ALL* no error message is sent to the terminal. TIME_BADMICRO: Micro name was invalid. TIME_BADPRIM: PRIM is not a DUPCD primary. TIME_INVALIDBEAM: beam number not in the range [1..N_BEAMS] and not ALL*. TIME_LISTSHORT: PLIST too short to hold all the pointers. The list will contain as many pointers as can fit. TIME_BADARGS: The ASCII UNIT or BEAM arguments, if not ALL*, did not convert to binary numbers. NOTE: The pointer list will be structured in the order that the units appear in the T_MATRIX when UNIT is ALL*, not in Data Base order. Use TMUNITS to get the list of units in T_MATRIX order to properly decode the datalists returned by TMLGET and TMLPUT. If BEAM is ALL*, only one entry per unit is made in PLIST, but N_BEAMS entries per unit are made when the PLIST is passed to TMLGET, and expected when passed to TMLPUT, in their data lists.
GENERAL UTILITIES Page 10-4510.6.10 TMLPUT TMLPUT puts the timing values in the T_MATRIX for DUPCDs specified in an access list which was made by TMLIST. Use TMLPUT when repeated access to the same set of timing values is required. The access list can also be used by TMLGET, so that you can do a TMLIST, TMLGET, modify data, then a TMLPUT with the same access list. iss = TMLPUT (DLIST, PLIST) This function will put the timing values in DLIST for the specified DUPCD on the specified beam into the T_MATRIX. The DUPCD/beam's are specified in PLIST, which is generated by TMLIST. ARGUMENTS: (required) DLIST: I*2 array a list from which values will be taken. PLIST: I*2 array an access list made by TMLIST. RETURNS: None. FUNCTION RETURNS: TIME_OKOK: success. TIME_LISTSHORT: DLIST too short, not enough values. TIME_BAD_DEV_INDEX: PLIST values corrupted. TIME_INVALIDBEAM: PLIST values corrupted. TIME_ACTTOOBIG: Timing value is too big. The T_MATRIX is not changed. TIME_ACTTOOSMALL: Timing value is too small. The T_MATRIX is not changed. TIME_SENDFAIL: Message service error sending timing data to the micro(s). The T_MATRIX has been updated. NOTE: When beam is ALL*, there will be N_BEAMS data values taken from the DLIST, one for each beam, for that DUPCD. This means that the DLIST and PLIST may be different lengths.
GENERAL UTILITIES Page 10-4610.6.11 TMPCD TMPCD is used to obtain PCD information for a DUPCD. The PCD information most needed is PCD type, which determines the valid set of timing values for the DUPCD. A DUPCD is activated or triggered by a pulse from a particular PCD channel at a particular time. Part of the DUPCD's timing value is stored in the PCD, so it will generate a pulse at a time such that it will trigger the DUPCD at a time equal to its timing value in the T_MATRIX. iss = TMPCD (PRIM, MICRO, UNIT, PCDT, PCDU, DUPCDC, PCDP) ---- ---- ------ ---- This function will return the PCD type, unit number, channel number, and primary for the DUPCD specified by PRIMary, MICRO, and UNIT. The information is obtained from the T_MATRIX structure and is returned in the corresponding arguments, if present. ARGUMENTS: (required) PRIM I*4 DUPCD primary name. Cannot be ALL*. MICRO I*4 DUPCD micro name. Cannot be ALL*. UNIT I*4 DUPCD ASCII or binary unit number. Cannot be ALL*. RETURNS: (optional) PCDT I*4 PCD type number. PCDU I*4 PCD unit number. DUPCDC I*4 PCD channel number of the DUPCD. PCDP I*4 PCD primary name. FUNCTION RETURNS: TIME_OKOK: success. TIME_BADMICRO: micro name was invalid. TIME_BADPRIM: primary name is not a DUPCD primary.
GENERAL UTILITIES Page 10-47 TIME_NOMATCH: DUPCD primary/unit was not found.
GENERAL UTILITIES Page 10-4810.6.12 TMPUT TMPUT takes timing values from an array which is treated as a list like the DataBase lists and puts them into the T_MATRIX. Use TMPUT when repeated access to the same timing values is not needed. If a get or repeated put's are to be done, use TMLIST, TMLGET, and TMLPUT, which make efficient use of an access list. iss = TMPUT (DLIST, PRIM, MICRO, UNIT, BEAM) This function will put the timing values in DLIST for the specified DUPCD on the specified BEAM into the T_MATRIX. This routine calls TMLIST and then TMLPUT. ARGUMENTS: (required) DLIST: I*2 array a list from which values will be taken. PRIM I*4 DUPCD primary name. Cannot be ALL*. MICRO I*4 DUPCD micro name. Cannot be ALL*. UNIT I*4 DUPCD ASCII or binary unit number. Can be ALL*. BEAM I*4 ASCII or binary beam number. Can be ALL*. RETURNS: None. FUNCTION RETURNS: TIME_OKOK: success. TIME_BADMICRO: invalid micro name. TIME_INVALIDBEAM: beam number out of range [1..N_BEAMS]. TIME_NOMATCH: PRIM, MICRO, UNIT not found in T_MATRIX. TIME_LISTSHORT: DLIST too short, not enough data or too many devices/beams specified. NOTE: When BEAM is ALL*, each DUPCD specified by PRIM, MICRO, UNIT, including ALL* units, must have N_BEAMS timing values, one for each beam.
GENERAL UTILITIES Page 10-4910.6.13 TM_REACTIVATE TM_REACTIVATE restores timing values in the T_MATRIX that were deactivated using TM_DEACTIVATE. TM_REACTIVATE will have no effect on timing values that are already activate values. iss = TM_REACTIVATE (PRIM, MICRO, UNIT, BEAM) This function will get the timing values for the specified DUPCD and beam from the T_MATRIX, clear the deactivate bit, and put the values back into the T_MATRIX (and update the micro). ARGUMENTS: (required) PRIM I*4 DUPCD primary name. Cannot be ALL*. MICRO I*4 DUPCD micro name. Cannot be ALL*. UNIT I*4 DUPCD ASCII or binary unit number. Can be ALL*. BEAM I*4 ASCII or binary beam number. Can be ALL*. RETURNS: None. FUNCTION RETURNS: This function returns the values returned by: TMLIST TMLGET TMLPUT
GENERAL UTILITIES Page 10-5010.6.14 TM_REACTIVATE_KLYS INTEGER*4 FUNCTION TM_REACTIVATE_KLYS(MICR,UNIT,BEAM,NOTIFY) In addition to reactivating klystron(s) specified by MICR,UNIT on BEAM, this routine checks klystron and BEAM TMSKs for compatibility. If a klystron specified by MICR,UNIT does not have a solid state subbooster, this routine tries to reactivate the subbooster in MICR on BEAM. If subbooster reactivates, the routine then reactivates klystron(s) specified by MICR,UNIT on BEAM. Arguments: (required) MICR I*4 DUPCD micro name (cannot be ALL*) UNIT I*4 DUPCD unit number (can be ALL*) BEAM I*4 Beam number (cannot be ALL*) NOTIFY L*4 Flag telling whether to put out informational messages when SBST is reactivated or fails to reactivate. Function returns: Values returned by other timing utilities
GENERAL UTILITIES Page 10-5110.6.15 TMUNITS TMUNITS is used to obtain a list of unit numbers, in T_MATRIX order, for a given primary and micro. This list is then used to decode the order of data returned or used by the other Timing Utility routines when unit is specified as ALL*. It is worth noting that a TMBEAMS routine is not needed since beam numbers are always the set of numbers in the range [1,N_BEAMS] when beam is specified as ALL*. iss = TMUNITS (DLIST, PRIM, MICRO) This function will get the unit numbers from the T_MATRIX structure for the given primary and micro and return them in DLIST in the order they occur in the T_MATRIX structures. This list of unit numbers will correspond to the order of values returned by Timing Utilities when ALL* is specified for UNITS. The returned unit numbers will be I*2. ARGUMENTS: (required) DLIST I*2 array list into which the unit numbers will put. PRIM I*4 primary name for the units desired. Cannot be ALL*. MICRO I*4 micro name for the units desired. Cannot be ALL*. RETURNS: The second word of DLIST is updated with the new active list length and the I*2 unit numbers will be appended into the list. FUNCTION VALUES: TIME_OKOK: success. TIME_BADMICRO: invalid micro name. TIME_BADPRIM: primary name is not a DUPCD primary. TIME_LISTSHORT: DLIST was too short for all the data.
GENERAL UTILITIES Page 10-5210.6.16 TNOMINAL TNOMINAL is used to get the sector nominal time. This is just a sector wide timing offset for a particular beam. This time is used along with the values returned by GET_TREF for displaying relative times of a DUPCD instead of absolute times. iss = TNOMINAL (BEAM, MICRO, TNOMVAL) This function will return in TNOMVAL the nominal timing value for the specified MICRO on the specified BEAM. ARGUMENTS: (required) MICRO I*4 DUPCD micro name. Cannot be ALL*. BEAM I*4 binary beam number. Cannot be ALL*. RETURNS: (required) TNOMVAL I*4 sector micro nominal time. FUNCTION RETURNS: TIME_OK: success. TIME_INVALIDBEAM: BEAM is not in the range [1, N_BEAMS]. TIME_BADMICRO: invalid micro name.
GENERAL UTILITIES Page 10-5310.6.17 TRIG_RATE TRIG_RATE returns a DUPCD's total triggered rate. A DUPCD's trigger rate depends on which beams it is active (has a valid activate value in the T_MATRIX) and on the rates of those beams. The beam rates are determined by the MPG according to beam priorities and scheduling. So, the DUPCD's total triggered rate is the sum of the beam rates on which it is active. iss = TRIG_RATE (PRIM, MICRO, UNIT, RATE) ARGUMENTS: (required) PRIM I*4 DUPCD primary name. Cannot be ALL*. MICRO I*4 DUPCD micro name. Cannot be ALL*. UNIT I*4 ASCII or binary unit number of DUPCD. Cannot be ALL*. RETURNS: (required) RATE I*4 trigger rate for DUPCD, in hertz. FUNCTION RETURNS: Message service errors. Errors from TMPCD and TMGET.
GENERAL UTILITIES Page 10-5410.6.18 T_VAL_IS_DEACT T_VAL_IS_DEACT determines if a given timing value is a valid activate or deactivate value or if it is an invalid value. The type of timing value is indicated by the function's return value. iss = T_VAL_IS_DEACT (VALUE, PCD_TYPE) ARGUMENTS: (required) VALUE I*4 supposed timing value to check. PCD_TYPE I*4 a PCD type (such as that returned by TMPCD). RETURNS: None. FUNCTION RETURNS: TIME_VALID_ACT: VALUE is a valid activate timing value. This return code is logically .FALSE. TIME_VALID_DEACT: VALUE is a valid deactivate timing value. This return code is logically .TRUE. TIME_INVALID_VALUE: VALUE is invalid as a timing value. This return code is logically .FALSE.