![[SLAC Controls Department]](/grp/cd/soft/images/logo_cd.gif){kind=logo}
![[SLAC Home Page]](/grp/cd/soft/images/logo_slac.gif){kind=logo}
16.1 INTRODUCTION . . . . . . . . . . . . . . . . . . 16-1
16.2 CRITERIA . . . . . . . . . . . . . . . . . . . . 16-1
16.3 EVALUATION OF CRITERIA . . . . . . . . . . . . . 16-2
16.4 CONTENTS OF THE X DESCRIPTOR . . . . . . . . . . 16-2
16.4.1 Summary . . . . . . . . . . . . . . . . . . . 16-3
16.5 ALTERNATIVE SOLUTIONS AND RECOMMENDATION . . . . 16-3
16.6 DEVICE I/O USING THE DEVICE DESCRIPTOR. . . . . 16-4
16.6.1 Summary . . . . . . . . . . . . . . . . . . . 16-5
16.7 THE VALUE DESCRIPTOR . . . . . . . . . . . . . . 16-5
16.7.1 Valid I/O Operations For The Different Device
16.8 ASSOCIATED CONSIDERATIONS FOR DEVICE I/O . . . . 16-6
16.9 UTILITY ROUTINES . . . . . . . . . . . . . . . . 16-7
16.10 ADDENDUM: SOFTWARE STATUS (JUNE 1985) . . . . . 16-8
16.11 SUGGESTIONS FOR FUTURE DEVELOPMENT . . . . . . . 16-9 L*8, but typically database variables are REAL*4.
16.3 EVALUATION OF CRITERIA If supplementary data were generated for each access, the routines would have limited application, due to inefficiency. Let this data be called the 'X descriptor' (X-extra). A means of constructing the X descriptor for a device descriptor must be provided, and ideally its inclusion should have as little impact as possible. The X descriptor would only need to be re- generated whenever the contents of its associated device descriptor are modified. It would be convenient to supply several device descriptors per call to an I/O routine. It would seem natural to pass these as a contiguous array to the routine, and indicate the no. of descriptors with an (optional) argument. This obviates the effort and manipulation of any 'list header'. It is worth considering whether lists of X descriptors should be built, then manipulated (like data base CLISTS). Indeed the X descriptor for a database variable, would be its actual CLIST entry. Thus for a list containing only database devices, the list of X descriptors degenerates to a CLIST which can be used with optimal efficiency by DBLGET, and DBLPUT. The problem here is that for mixed device types in a list (as is often the case), it is no longer possible. A set of different lists would be required, and the format of such lists for other devices (e.g. Triggered devices, BPM's) would need specification now. This task is perhaps too onerous for present purposes. It would seem appropriate to have other AP_ utility routines to abstract a CLIST of all database devices in a set of mixed descriptors. The CLIST would be used specifically with DBLGET/DBLPUT. Other device types would be separately treated, using the present routines until future list oriented ones become available. It would be a modular future addition to have routines which generate separate X descriptor lists from a mixed list, and perform the appropriate I/O using each. Updating devices (5) would fit naturally into an arrangement of separate lists, as the operations required are very dependent on device type.
16.4 CONTENTS OF THE X DESCRIPTOR The following list indicates what information should be in the X descriptor for the current device types. The name in brackets, prefixed by X_ e.g. (X_DBPTR), denotes a reference index within the X descriptor:-
DEVICE ACCESS USING THE DEVICE DESCRIPTOR. Page 16-3 1. Database Devices. 1 integer*4 word containing the database pointer. (X_DBPTR). 2. Triggered Devices. 2 integer*4 words. The T Matrix Column (X_TCOL) and device PCD type (X_PCDTYPE) can both be contained in an integer*4 (by equivalencing with two integer*2 words). Also required is the 'T Matrix offset' (X_TOFF). It is the value of :- TREF + T_NOMINAL + PDUT/PSUT). 3. BPM's/Toroids. 1 integer*4 word for a pointer into the appropriate BPM common block array. (X_BPMINDEX) 4. Analog Status Devices. 2 integer*4 words. A node pointer, and a Sub-block pointer (X_ASTSDBNOD, X_ASTSUBLK) From the above it is evident that two integer*4 words are required by an X descriptor.16.4.1 Summary The following list summarises the different X descriptor indices for the various device types:- Database Devices X_DBPTR Triggered Devices X_TCOL, X_PCDTYPE, X_TOFF Analog Status Devices X_ASTSDBNOD, X_ASTSUBLK Special Sampled/Step Variables:- ZERO, TIME, SAMP, KNOB None required. (Values derived by the DTIZ None required. Corr. Plot program). BPM X_BPMINDEX TORO X_BPMINDEX
16.5 ALTERNATIVE SOLUTIONS AND RECOMMENDATION For purposes of unifying the current software (Correlation Plots and Multi-device knob utility), a practical yet flexible solution is needed. To accommodate future changes in the addressing mechanism for the X descriptor, it is convenient to have its contents accessed via function calls. The simplest place for the X descriptor is within the device descriptor itself. The advantages in terms of manipulation and simplicity are obvious. The disadvantage is that the amount of reserved storage must always be large enough for the maximum size of X
DEVICE ACCESS USING THE DEVICE DESCRIPTOR. Page 16-4 descriptor for any device. This does not currently present any problem, but in future if one device type has an inordinately large X descriptor compared to any other, storage inefficiency results. There is another arrangement which at the cost of somewhat increased complexity, overcomes possible storage inefficiency (as always). It has the same advantage as the previous possibility, in that the X descriptor is transparent. In the scheme, the device descriptor has an entry which contains the address of its X descriptor so the latter can always be found from the former. The routine which fills in the X descriptor would also allocate its space efficiently, according to its device type. It would seem logical to adopt the simplest solution (the first). If in future it became unsatisfactory, then only the routines which access the X descriptor would require additional code. (The structure of the device/X descriptors would also need alteration). Application code would remain unaffected.16.6 DEVICE I/O USING THE DEVICE DESCRIPTOR. As noted above, an I/O routine does not necessarily perform its function for all device types, because it may be meaningless. In cases of misuse the routines return an error. It should be noted that error codes from several facilities can be returned. Three routines will enable basic I/O to be done:- 1. X_SET_DESCR(AP_DEV). This function sets up the X descriptor for the device named in AP_DEV. It returns a status indicating that it could successfully construct the descriptor. 2. AP_DEVGET(AP_DEV, AP_VAL, N_DEVS, AP_ERR). Read device control values for the single or array of devices given in AP_DEV. The corresponding array of values read is passed back in AP_VAL. The last two arguments are optional. N_DEVS indicate the no. of devices supplied in AP_DEV and AP_ERR returns the individual read status for each device. This function returns OP_OKOK if all the individual reads were OK, otherwise the status of the last bad read. 3. AP_DEVPUT(AP_DEV, AP_VAL, N_DEVS, AP_ERR). Write device control values for the single or array of devices given in AP_DEV. The corresponding array of values read is passed back in AP_VAL. The last two arguments are optional. N_DEVS indicate the no. of devices supplied in AP_DEV and AP_ERR returns the individual write status for each device. This function returns OP_OKOK if all the individual writes were OK, otherwise the status of the last bad write.
DEVICE ACCESS USING THE DEVICE DESCRIPTOR. Page 16-516.6.1 Summary The following list indicates the location to which the device control values are read/written. Database Devices The database Triggered Devices The T Matrix Analog Status Devices The database Special Sampled/Step Variables:- ZERO, TIME, SAMP, KNOB Corr. Plot Common block DTIZ Corr. Plot Common block BPM BPM Common Block TORO BPM Common Block
16.7 THE VALUE DESCRIPTOR It should be noted that the AP_VAL argument used with AP_DEVGET and AP_DEVPUT is an array of two integer*4 words for each value. Its contents must be interpreted in different ways according to device type. Database devices values are real*4, but T matrix values require real*8 (to maintain precision in Nsec). BPM data consists of two real*4 words, one for the value, and the other for the error in its measurement. A 'Value descriptor' has been provided (as an include file) to enable application programs to equivalence data correctly from the AP_VAL argument. The contents are shown below:- * VDESC.TXT * * The V descriptor enables applications to interpret the * value parameter used by the AP_DEVGET/AP_DEVPUT routines. * Depending upon the primary name, the value must be * interpreted differently. * For a database value it is a REAL*4 (V_DB) * * Triggered devices are REAL*8 * * Bpm/Toroid values are 2 REAL*4: * Value and Error. (V_BPMVAL, V_BPMERR) * * Here a global array is declared which application programs * can use, to enable different types of data equivalencing. * INTEGER*4 V_DESC(2) REAL*4 V_R4VAL(2) REAL*8 V_R8VAL EQUIVALENCE (V_DESC, V_R4VAL) EQUIVALENCE (V_DESC, V_R8VAL)
DEVICE ACCESS USING THE DEVICE DESCRIPTOR. Page 16-6 * * Access indices * INTEGER*4 V_DB, V_BPMVAL, V_BPMERR PARAMETER (V_DB = 1, V_BPMVAL = 1, V_BPMERR = 2)16.7.1 Valid I/O Operations For The Different Device Types. For certain devices, read or write operations are not meaningful. Consideration of the following list will make this fact self-evident:- Database Devices Read/Write Triggered Devices Read/Write Analog Status Devices Read only Special Sampled/Step Variables:- BPM Read only TORO Read only ZERO, TIME, SAMP, DTIZ Read only (Values derived by the Corr. Plot program) KNOB None. (used by the Corr. Plot program) It should be noted in the above that certain primaries (i.e. ZERO, TIME, SAMP, DTIZ, KNOB) are recognised as valid, but for which the I/O routines take no action at all. The reason for this is that they are only meaningful in the context of a particular application (the Correlation Plots) and its environment. It is thus appropriate to cater for them there. They are integrated into the general arrangement because the application can then benefit from the use of the utility routines (mentioned later), for parsing and display, without special handling.
16.8 ASSOCIATED CONSIDERATIONS FOR DEVICE I/O There are two important aspects of device I/O which are not within the scope of the I/O routines themselves:- 1. Ensuring that the most recent device control values are read. 2. Ensuring that the physical device is updated to its control value. When a list of many devices is involved in an acquisition/ control operation, it is not practical to perform the above two tasks on a device by device basis as it would take a long time. What is typically required is that the device list is separated into different
DEVICE ACCESS USING THE DEVICE DESCRIPTOR. Page 16-7 classes (magnets, klystrons, triggered devices etc.). These classes are then treated separately with their appropriate special handling. It is not within the current scope of support by the AP_ routines to do this. Please refer to the sections 2.2-Criteria, 2.3-Evaluation of criteria and 2.11-Future suggestions. For devices whose control values are contained in the database (database and ASTS devices), these operations have a characteristic form. A 'message sync.' (MSG_SYNC) is made to the appropriate micros with a given function code. This ensures that the database is updated before a read, or the micros are updated after a write. For triggered devices, the AP_ I/O routines access only the T Matrix. For reading, the T Matrix is considered the correct source. After writing to the T Matrix, micros must be updated (e.g. using the AP_TMAT_UPDAT function). The values for BPM's and Toroids are obtained from common block arrays (in BPMSCP.TXT). In order to get a fresh data sample the function BPM_AVG must be called prior to reading the arrays.16.9 UTILITY ROUTINES The set of utility routines which perform operations using device descriptors are listed below:- 1. AP_DEV_TO_BUT(AP_DESC, BUTTON). A subroutine which writes the name of a device on a button. 2. AP_DEV_TO_STR(AP_DESC). A character function which returns the name of a device in a string. 3. AP_DEVGET(AP_DESC, VALUE). A function which returns the current value of the device. 4. AP_DEVPUT(AP_DESC, VALUE). A function which writes a value to a device. (Other device dependent operations may be required, e.g. to update a micro). 5. X_SET_DESCR(AP_DEV). This function sets up the X descriptor for the given application descriptor. 6. X_GET(AP_DEV, X_INDEX, X_VAL). A function which enables the contents of the X descriptor to be read. Its major use is by the above AP_ routines. 7. X_PUT(AP_DEV, X_INDEX, X_VAL). A function which enables the contents of the X descriptor to be set. Its major use is by the above AP_ routines. 8. AP_PARSE(PARSE_LINE, NEW_DEV, CURR_DEV). A subroutine to parse a line of character text, and construct a device descriptor (NEW_DEV) from it (and where necessary, combine
DEVICE ACCESS USING THE DEVICE DESCRIPTOR. Page 16-8 parts of an existing name CURR_DEV). It is used in conjunction with an interactive input routine. 9. AP_TMAT_OFFSET(AP_DEV, TMAT_OFFSET). A function which finds the T matrix offset for a triggered device. I.E:- TREF + T_NOMINAL + PDUT(or PSUT). 10. AP_TMAT_UPDAT(AP_DEV). Write the T matrix value defined by AP_DEV to its associated Micro. 11. AP_GET_TMATCOL(AP_DEV, COLUMN). This subroutine finds the T matrix column for the triggered device defined by AP_DEV. 12. AP_GET_PCDTYPE(AP_DEV, PCD_TYPE). A function which finds the PCD type for the triggered device defined by AP_DEV. 13. AP_VFY_TMATVAL(AP_DEV, AP_VAL, TOO_LOW, TOO_HIGH, DEV_DEACT). A function which checks the validity of a value (AP_VAL) for the triggered device AP_DEV. It indicates if the value is below the minimum T matrix value or above the maximum value permissible for this PCD type. (AP_VAL is adjusted appropriately if necessary). It also indicates whether the device is currently de-activated. 14. AP_DBGET(AP_DEV, VALUE). A function which reads a single REAL*4 database device, WITHOUT using the device X descriptor.16.10 ADDENDUM: SOFTWARE STATUS (JUNE 1985) At present the source code for the software proposed above has been written and incorporated within the Correlation Plots and Multi-device Knob Utility. It is present in SLCSYS and (when appropriate) development versions can be found in [JMK.APP]. The files involved are:- 1. APDESC.RNO: The RUNOFF source for this document. 2. APDESC.TXT: The Definition of the Device and X descriptors, and associated information. 3. APVDEMDEF.TXT: Declarations for the interface to the VDEM software. 4. APPSUPP.FOR: The Main source code for the 'Application Support'. 5. APPARSE.FOR: The source code for the interactive parsing routines.
DEVICE ACCESS USING THE DEVICE DESCRIPTOR. Page 16-9 6. VDESC.TXT: The definition of the Value descriptor.16.11 SUGGESTIONS FOR FUTURE DEVELOPMENT Briefly, the application support routines would benefit particularly from development in the following respects:- 1. More instructive error code returns (perhaps from an AP_ facility). At present they are either from the OPDEF facility or a facility corresponding to a given device type. 2. A simplified non-interactive version of the parsing routine. It would fill in a device device descriptor from a charcters string containing a device name. 3. Routines to split a list of mixed device types into separate lists each containing devices of a given 'class' (E.g. magnets, klystrons triggered devices etc). The latter may take the form of X descriptors rather than device descriptors, for efficient list-oriented I/O. 4. List-oriented routines to aid in the updating of various micros. E.g. for building micro-lists for use with MSG_SYNC, from a list of devices of a particular class. %RUNOFF-W-COR, Can't open required file "doc$0:poop.rnx" on output page 16-9; on input line 40 of page 1 of file "DOC$:[000000.POOP]POOP.RNO;5"