CHAPTER 1 DATA SCALING SERVICES _____________________ 1.1 OVERVIEW Scaling services are available as library routines to allow the application programmer to easily and efficiently convert the data returned by the selective data acquisition system to appropriate formats for display and computation. The services are transparently available to console and central node applications. Each routine for a property's data requires a Process Data Block and the data upon which it is to operate. Any programmer may call these routines from any language which allows access to the R5 pass by reference calling sequence and the PDP-11 F77 function value register definitions as defined in Section 2.2.1 of the PDP-11 FORTRAN-77 ______ __________ Object Time System Reference Manual (V4.0, order number AA-1874C-TC). ______ ____ ______ _________ ______ Calling sequences used by a FORTRAN programmer and the data structures used by the scaling service routines are shown for each property. The type of operation requested as well as the type of the returned result is implicit in the name of the function. This frees the user from including extraneous symbol names and generally makes for a more readable program. Recall that the type of data returned from a device is specified by the property; the routine descriptions listed below are listed by the properties which return the data they operate upon. Each routine in a section, therefore, corresponds to a different method of processing the data returned by a property. The data structures are shown for illustrative purposes. A fully developed suite of library routines does not require knowledge of them. 1-1 DATA SCALING SERVICES _____________________ 1.2 PROCESSING READING AND SETTING PROPERTY DATA 1.2.1 The READING And SETTING PDB's The reading scaling services can operate on input data which is one, two, or four bytes in length and originates from either the READING property or the SETTING property. (Don't forget that the setting property of a device may be requested to obtain the current setting, therefore scaling the return or reading of the setting makes perfect sense.) Processed data is always returned as a two or four byte word-aligned value by the data collection system. A storage block has been defined to hold device-specific information for processing the data associated with a given device's READING or SETTING property data. These storage blocks are called Process Data Blocks or PDB's. The READING and SETTING property share a common PDB format though a separate PDB is required for each property. PDB's are generally defined as variable length structures. At this time the ones for the READING and SETTING properties have a maximum length of 36 bytes. The total length of the PDB is stored in the first byte of the PDB (including the first byte). The format of the READING and SETTING property PDBs is shown below. Length Symbolic (bytes) Offset ---------- -------- +-------------------------------------------+ 1 PDBLEN | length of PDB in bytes | |-------------------------------------------| 1 PDRSFL | MC | LS | DS | CS | | | IDL | |-------------------------------------------| 4 PDRSPU | primary units text ('Volt','Ohm_','Tick') | |-------------------------------------------| 4 PDRSCU | common units text ('Amp_','DegK','uSec') | |-------------------------------------------| 1 PDRSPT | primary transform index (raw to 'volts') | |-------------------------------------------| 1 PDRSCT | common transform index ('volts' to eng.u.)| |-------------------------------------------| 6*4 PDRSCC | common transform constants | +-------------------------------------------+ IDL Two bit field specifying the expected length of unprocessed input data. This field may only take on the values zero, one, and two (representing lengths of one, two and four bytes). All other values are undefined at this time. MC Bit defining whether this device should be treated as a motor controller for purposes of displaying its setting and calculating new setting requests or as a D/A (or other absolutely settable device). (0=D/A, 1=stepper motor controller) 1-2 DATA SCALING SERVICES _____________________ LS Bit defining the preferred precision for interactive display purposes. Short format implies that a six character display is sufficient while long requires 8 (or perhaps more) characters for output. The long format is intended to provide for output of 24-bit timer values. Most other data can use short format. (0=short, 1=long). DS Bit defining the default method of display for interactive users, either decimal or scientific notation (0=decimal, 1=scientific). CS Bit defining whether or not this property is considered to be a controlled setting. If it is a controlled setting (bit set), generic programs such as the parameter page should not support the setting of this property. PDB Format for the READING and SETTING Properties 1.2.1.1 Input Data Length - The IDL field in the flag byte is used to determine the number of bytes of input data. This quantity should be the same as the default data return length used by the selective data acquisition system. This is not a coded field though only three discrete values should ever appear in it; zero, one, or two. 1.2.1.2 The Primary Transform - The READING and SETTING PDB's contain information which describe the necessary processing to convert unprocessed data to the primary units of measure such as volts, clock ticks, ohms, etc. This is called the primary transform and is specified by the primary transform index which is an even-valued one byte number. This index is used by ___________ the scaling routines to index a jump table to select the proper primary transform code for execution. Any required constants of conversion are implicit in the index (ie. not stored in the PDB but in the code). Transforms 0 through 12 and 16 assume integer data which is signed (two's complement) and left justified in the specified input field (length as specified by IDL). The other tansforms operate on unscaled data which is special in some way or other. Four characters of text describing the units of the result of the transform are also available in the PDB. This text is always left justified and space filled ASCII. At this time the following primary transforms are defined: Index Transformation _____ ______________ 0. X = FLOAT(input) / 3200. ! 10.24 VFS A/D's 2. X = FLOAT(input) / 3276.8 ! 10.00 VFS A/D's 1-3 DATA SCALING SERVICES _____________________ 4. X = FLOAT(input) / 6553.6 ! 5.00 VFS A/D's 6. X = FLOAT(input) / 13107.2 ! 2.50 VFS A/D's 8. X = FLOAT(input) + 32768. ! 091 CAMAC timers 10. X = FLOAT(input) --> all DEC ! null transform FLTD 12. X = FLOAT(input) / 320.0 ! temperature resistors 14. X = CAMAC 2323 data handler 16. X = IEEE-DEC floating format ! (standard) 18. X = FLOAT(input) * .001040625 ! temperature resistors 20. X = 8/16-bit unsigned data handler 22. X = input ! null transform 24. X = IEEE-DEC floating format ! (byte-swapped for 68000) 26. X = FLOAT(ABS(input/256))/82.1865-0.310269935 28. X = FLOAT(input) --> 68000 I*4 ! null transform FLTD 30. X = FLOAT(lo byte of word) ! signed byte 32. X = FLOAT(hi byte of word) ! signed byte 34. X = FLOAT(ABS(lo byte of word)) ! unsigned byte 36. X = FLOAT(ABS(hi byte of word)) ! unsigned byte 38. X = FLOAT(ABS(lo byte of word))/82.1865-0.310269935 40. X = FLOAT(input)/256.0 ! unsigned byte 42. X = 16-bit unsigned 0 to 10V DAC handler 44. X = 7-digit BCD input handler 46. X = FLOAT(input) ! unsigned longword 48. X = (IEEE FP -> dec fp) / 0.036 50. X = IEEE to DEC conversion ! clamped to -10.24 to 10.235 52. X = FLOAT(input) ! raw data is byte swapped 54. X = FLOAT(input) * 0.000488296 + 4.0 ! 4-20 mA PLCs 56. X = (FLOAT(input)-32768.0)/3276.8 ! unsigned word 58. X = FLOAT(unsigned input) / 256.0 60. X = (IEEE FP -> DEC FP) * 500.0 62. X = 16-bit unsigned 0 -> 10.24V DAC handler 64. X = FLOAT(input) ! scaled to +/- 1.0 66. X = FLOAT(input) / 3200.0 ! input > 0 68. X = (not scalable - for special display types only) 70. X = FLOAT(input) / 1000.0 1.2.1.3 Common Units Transform - The READING and SETTING PDB's contain information which allows the result of a primary transform to be further processed to a value expressed in terms of the Common Units of measure for the device of interest. Input data is always the floating point result of the associated primary transform. An even-valued byte called the Common ___________ Transformation Index obtained from the PDB is used to index a jump table which dispatches to the appropriate code. Each PDB contains a potentially unique set of common transformation constants which may be used by the specified transformation. (The data-base may actually take advantage of duplicate entries, where possible, in central disk storage and in the return of information to requestors.) The following common transforms are currently defined: Index Transformation _____ ______________ 1-4 DATA SCALING SERVICES _____________________ 0. X' = X 2. X' = (C1 * X / C2) + C3 4. X' = (X - C1) / C2 6. X' = C1 * X / C2 8. X' = C4 + (C1 * X) / (C3 + C2 * X) 10. X' = C3 + (C2 / (C1 * X)) 12. X' = C5+(C4*X)+(C3*X**2)+(C2*X**3)+(C1*X**4) 14. X' = EXP(C5+(C4*X)+(C3*X**2)+(C2*X**3)+(C1*X**4)) - C6 16. X' = C2 * EXP(-X/C1) + C4 * EXP(-X/C3) 18. X' = C3 * EXP(C2*(X+C1)) + C6 * EXP(C5*(X+C4)) 20. X' = LOG(X)/(C1*LOG(X)+C2)**2 + C3 22. X' = C2 * (10.0**(X/C1)) 24. X' = C2*(C3*X+C4) -or- C2*EXP(C5*X+C6) for X<>C1 26. X' = C6+(C5*X)+(C4*X**2)+(C3*X**3)+(C2*X**4)+(C1*X**5) 28. X' = C3/(C2+C1*X) + C4 30. X' = C5+(C4*X)+(C3*X**2)+(C2*X**3) -or- X'=C6 on XC1 44. X' = C2*EXP(C3*X) on XC1 46. X' = C2*EXP(C3*X**2+C4*X) on XC1 54. X' = EXP(C2*X**2+C3*X+C4) on XN2, 1->He) 1.2.2 Routine Nomenclature The names of the various scaling routines (all are FORTRAN functions) operating on returned data are constructed in the following general form: value = PDxxyy( , , , ,....) Where 'xx' and 'yy' may take on the following literal values and meanings: xx/yy Meaning ----- ------- UD Unprocessed Data PU Primary Units CU Common Units Any combination of the values of 'xx' and 'yy' not resulting in the identity transform may be combined to yield the name of a supplied conversion routine. 1-5 DATA SCALING SERVICES _____________________ 1.2.3 Scaling To Common Units 1.2.3.1 Unprocessed Data To Common Units, PDUDCU - real*4_value = PDUDCU( INDATA, IPDB, IERR [,UNITS_TEXT] ) This function is used to scale the data returned by a DPGET call to a corresponding value in Common engineering Units. The function value always returns a single precision real value (REAL*4). The unprocessed data to be scaled is specified by INDATA. The appropriate Process Data Block for the device and property (READING or SETTING) must be supplied in the array IPDB. The Process Data Block is obtained from the System Data-base. IERR = 0 successful transformation =-1 illegal INDATA value for specified transform 1.2.3.2 Primary Units To Common Units, PDPUCU - real*4_value = PDPUCU( DATA, IPDB, IERR [,UNITS_TEXT] ) This function is used to scale the value of a reading or setting expressed in Primary Units to a corresponding value in Common engineering Units. The function value always returns a single precision real value (REAL*4). The value of the reading or setting in primary units to be scaled transformed is specified by the DATA argument (REAL*4). The appropriate Process Data Block for the device and property (READING or SETTING) must be supplied in the array IPDB. The Process Data Block is obtained from the System Data-base. IERR = 0 successful transformation =-1 illegal DATA value for conversion operation 1.2.4 Scaling To Primary Units 1.2.4.1 Unprocessed Data To Primary Units, PDUDPU - real*4_value = PDUDPU( INDATA, IPDB, IERR [,UNITS_TEXT] ) This function is used to scale the data returned by a DPGET call to the equivalent primary units (voltage). The function value always returns a single precision real value (REAL*4). The unprocessed data to be scaled is specified by INDATA (either one two or four bytes as required by the default data length). The Process Data Block for the device and property (READING or SETTING) must be supplied in the array IPDB. The Process Data Block is obtained from the System Data-base. IERR = 0 successful transformation 1-6 DATA SCALING SERVICES _____________________ 1.2.4.2 Common Units To Primary Units, PDCUPU - real*4_value = PDCUPU( DATA, IPDB, IERR [,UNITS_TEXT] ) This function is used to scale the value of a device expressed in Common Units to a value expressed in Primary Units. The function value always returns a single precision real value (REAL*4). The value expressed in Common Units is specified by the DATA argument (REAL*4). The Process Data Block for the device and property (READING or SETTING) must be supplied in the array IPDB. The Process Data Block is obtained from the System Data-base. IERR = 0 successful transformation 1.2.5 Scaling To Unprocessed Data Units 1.2.5.1 Common Units To Unprocessed Data, PDCUUD - integer_value = PDCUUD( DATA, IPDB, IERR [,UNITS_TEXT] [,MAXLEN] ) This function is used to scale a value expressed in Common Units to a corresponding value in Unprocessed Data units (eg. Amps to A/D counts). The function returns a value in the format which was expected for Unprocessed Data in the reverse transform, PDUDCU. The length is either one, two or four bytes as dictated by the value of IDL in the PDB for the device and property. The maximum length of the data returned may be limited to the number of bytes specified by the optional argument MAXLEN. If MAXLEN is specified as 4 bytes, 1 and 2 byte data will be extended to 4 bytes, possibly avoiding integer overflow errors. The Common Units value to be (reverse) scaled is specified by DATA (REAL*4). The appropriate Process Data Block for the device and property (READING or SETTING) must be supplied in the array IPDB. The UNITS_TEXT argument, if specified, will return 4 ASCII blank characters. The Process Data Block is obtained from the System Data-base. IERR = 0 successful transformation =-2 integer_value overflow 1.2.5.2 Primary Units To Unprocessed Data, PDPUUD - integer_value = PDPUUD( DATA, IPDB, IERR [,UNITS_TEXT] [,MAXLEN] ) This function is used to scale a value expressed in Primary Units to a corresponding value in Unprocessed Data units (eg. Volts to A/D counts). The function returns a value in the format which was expected for Unprocessed Data in the reverse transform, PDUDPU. The 1-7 DATA SCALING SERVICES _____________________ length is either one, two or four bytes as dictated by the value of IDL in the PDB for the device and property. The maximum length of the data returned may be limited to the number of bytes specified by the optional argument MAXLEN. If MAXLEN is specified as 4 bytes, 1 and 2 byte data will be extended to 4 bytes, possibly avoiding integer overflow errors. The Common Units value to be (reverse) scaled is specified by DATA. The appropriate Process Data Block for the device and property (READING or SETTING) must be supplied in the array IPDB. The UNITS_TEXT argument, if specified, will return 4 ASCII blank characters. The Process Data Block is obtained from the System Data-base. IERR = 0 successful transformation =-2 integer_value overflow 1.2.5.3 Default Unscaled Data Length, PDULEN - integer*2_value = PDULEN( IPDB, IERR ) This function is used to return the number of bytes of unprocessed data that scaling services will operate upon for a given device. The number of bytes (one, two or four) is returned in the integer function value. This function may be used to determine the number of bytes which will be returned by a reference to either the PDCUUD or PDPUUD functions. The length is either one, two or four bytes as dictated by the value of IDL in the PDB for the device and property. The Process Data Block is obtained from the System Data-base. IERR = 0 success 1.2.5.4 Maximum Common/primary Transform Indicies, PDIMAX - integer*2_value = PDIMAX() This function is used to return the maximum index value for both primary and common transforms. The maximum (high) primary index is returned in the low byte and the maximum common index is returned in the high byte. 1.3 PROCESSING BASIC_STATUS PROPERTY DATA The BASIC_STATUS property returns the status of a device. The returned data may be one, two or four bytes in length. The default length of the status return for a device's basic status is entered in the data-base PIB. Scaling services are available to operate on the returned data. Only four almost universally applicable status attributes are supported by these scaling services -- on/off, 1-8 DATA SCALING SERVICES _____________________ ready/tripped, remote/local and pospolarity/negpolarity. The scaling services operate on this data by applying mask values contained in the property PDB. The masks may be used to select one or a combination of the bits in the returned status to define each supported attribute. The PDB also contains sufficient information to define which of the attributes are actually supported for a particular device. 1.3.1 The BASIC_STATUS PDB The BASIC_STATUS PDB is a variable length structure. Length Symbolic (bytes) Offset ---------- -------- +-------------------------------------------+ 1 PDBLEN | length of PDB in bytes | |-------------------------------------------| 1 PDBSFD | alternate character |attribute definition | | definition flags (4)| flags (4) | |-------------------------------------------| 1 PDBSIF | status data invert flags (4) | |-------------------------------------------| 1 PDBSFL | | | | | | | IDL | |-------------------------------------------| 4 PDBSON | attribute mask: ON / ~ON (off) | |-------------------------------------------| 4 PDBSRD | attribute mask: READY / ~READY (tripped) | |-------------------------------------------| 4 PDBSRM | attribute mask: REMOTE /~REMOTE (local) | |-------------------------------------------| 4 PDBSPO | attribute mask: POS_POL / ~POS_POL (neg) | |-------------------------------------------| 2 PDBSAC | alternate ON character/color code | |-------------------------------------------| 2 | alternate ~ON character/color code | |-------------------------------------------| 2 | alternate READY character/color code | |-------------------------------------------| 2 | alternate ~READY character/color code | |-------------------------------------------| 2 | alternate REMOTE character/color code | |-------------------------------------------| 2 | alternate ~REMOTE character/color code | |-------------------------------------------| 2 | alternate POS_POL character/color code | |-------------------------------------------| 2 | alternate ~POS_POL character/color code | +-------------------------------------------+ 1-9 DATA SCALING SERVICES _____________________ IDL Two bit field specifying the expected length of unprocessed status data. This field may only take on the values zero, one, and two (representing lengths of one, two and four bytes). All other values are undefined at this time. BASIC_STATUS Property PDB The defined attribute flags determine whether or not a given attribute is defined for this device. If the flag bit is 1, then the attribute is defined. The flag in bit position zero defines the ON/~ON attribute. The alternate character definition flags are used by the DSTATX routine to determine whether a given attribute will be represented by the normal default characters/colors or with the alternate characters/colors. If the flag bit is 1, then the alternate characters/colors are used. The flag in bit position four defines the alternate character option for the ON/~ON attribute. The data invert flags allow the front-end programmer to specify that the status data returned be complemented before the mask operation. The flag in bit position zero defines the invert option for the ON/~ON attribute. The remainder of the PDB consists of a mask long word for each defined attribute and alternate character/color codes for each attribute which uses the alternate character option. The alternate character/color codes consist of an ASCII character in the low byte and color codes in the high byte. This is the format accepted by the TVMX routine. The PDB is fixed in format but variable length. That is, it may only be truncated at the end. This, of course, implies that the last defined attribute mask or alternate character/color code sets the length of the PDB. The scaling routines described below operate in the following manner: - if invert bit set, then complement input data - AND data word with mask word from PDB for requested attribute - if the result is not equal to the mask then .NOT. attribute 1.3.2 Device ON/OFF Status, LDVON logical value = LDVON( INDATA, IPDB, IERR [,UNITS_TEXT] ) 1-10 DATA SCALING SERVICES _____________________ This logical function operates on the status data returned by a DPGET call and returns .TRUE. if the device is on or .FALSE. if the device is off. The unprocessed status is specified in INDATA. The Process Data Block for the device and property (BSTATS) must be supplied in the array IPDB. The necessary Process Data Block is obtained from the system data-base. The optional units text field will return a four character string of "ON " or "OFF " as appropriate for the value of the function return. IERR = 0 successful transformation =-1 ON/OFF attribute not defined for this device 1.3.3 Device LOCAL/REMOTE Status, LDVREM logical value = LDVREM( INDATA, IPDB, IERR [,UNITS_TEXT] ) This logical function operates on the status data returned by a DPGET call and returns .TRUE. if the device is remotely controllable or .FALSE. if the device is in local control. The unprocessed status is specified in INDATA. The Process Data Block for the device and property (BSTATS) must be supplied in the array IPDB. The necessary Process Data Block is obtained from the System Data-base. The optional units text field will return a four character string of "REM " or "LOCL" as appropriate for the value of the function return. IERR = 0 successful transformation =-1 REMOTE/LOCAL status not defined for this device 1.3.4 Device READY/TRIPPED Status, LDVRDY logical value = LDVRDY( INDATA, IPDB, IERR [,UNITS_TEXT] ) This logical function operates on the status data returned by a DPGET call and returns .TRUE. if the device is ready or .FALSE. if the device has tripped (interlocks broken). The unprocessed status is specified in INDATA. The Process Data Block for the device and property (BSTATS) must be supplied in the array IPDB. The necessary Process Data Block is obtained from the System Data-base. The optional units text field will return a four character string of "RDY " or "TRIP" as appropriate for the value of the function return. IERR = 0 successful transformation =-1 READY/TRIPPED status not defined for this device 1-11 DATA SCALING SERVICES _____________________ 1.3.5 Device POS/NEG Polarity Status, LDVPOS logical value = LDVPOS( INDATA, IPDB, IERR [,UNITS_TEXT] ) This logical function operates on the status data returned by a DPGET call and returns .TRUE. if the device is configured for positive polarity operation or .FALSE. if the device is configured for negative polarity operation. The unprocessed status is specified in INDATA. The Process Data Block for the device and property (BSTATS) must be supplied in the array IPDB. The necessary Process Data Block is obtained from the system data-base. The optional units text field will return a four character string of "POS " or "NEG " as appropriate for the value of the function return. IERR = 0 successful transformation =-1 polarity POS/NEG status not defined for this device 1.3.6 4 Character Status, DSTATX CALL DSTATX( INDATA, IPDB, STEXT ) This routine is used to generate an abbreviated 4 character digital status display field. It is used by the parameter program. It operates on the status data returned by a DPGET call and returns 4 characters (with color codes) in the INTEGER*2 STEXT array. The characters are in a format suitable for display with the TVMX routine. The unprocessed status is specified in INDATA. The Process Data Block for the device and property (BSTATS) must be supplied in the array IPDB. The STEXT array is returned as follows: Char Position Attribute Defualt Characters 1 ON/OFF green "." / red "*" 2 READY/TRIPPED green "." / red "T" 3 REMOTE/LOCAL green "." / yellow "L" 4 POS_POL/NEG_POL cyan "+" / magenta "-" If an attribute is not defined, a white blank is placed in the appropriate character position. If alternate characters are defined for an attribute, then they are used instead of the default characters. 1.4 PROCESSING BASIC_CONTROL DATA The basic control property is actually used by the central data-base manager process. It allows the system a uniform way of issuing digital commands for major state changes to devices. It is not intended to cover all possible digital commands to all devices. 1-12 DATA SCALING SERVICES _____________________ Supported commands are ON, OFF, RESET and POLARITY REVERSE. Routines to "scale" this property's data are not provided at this time for the console systems. In fact, the only type of scaling that would make any sense is a "reverse" scaling from the desired state to the data necessary to send to a front-end to obtain that result. This is because setting a device to a major state like ON or OFF is not done repeatedly to the same device. The service does, however, make use of a PDB to obtain just this information. This is why the service is presently being discussed under the topics of PDB's and data scaling services. 1.4.1 Format Of A BASIC_CONTROL PDB Length Symbolic (bytes) Offset ---------- -------- +-------------------------------------------+ 1 PDBLEN | length of PDB in bytes | |-------------------------------------------| 1 PDBSDF | attribute definition flags (8) | |-------------------------------------------| 4 PDBCRS | attribute data: RESET a device | |-------------------------------------------| 4 PDBCON | attribute data: turn device ON | |-------------------------------------------| 4 PDBCOF | attribute data: turn a device OFF | |-------------------------------------------| 4 PDBCPO | attribute data: set device to POS polarity| |-------------------------------------------| 4 PDBCNG | attribute data: set device to NEG polarity| |-------------------------------------------| ~ ~ | up to two future attribute masks | +-------------------------------------------+ BASIC_CONTROL PDB Format The general method of use is as follows: - Get addressing information and default data length from device's BASIC_CONTROL PIB. Equivalent of a DBAREQ call if inside DBM. - Get the BASIC_CONTROL PDB. - Index into PDB based on function requested by caller to get actual data to send to front-end. 1-13 DATA SCALING SERVICES _____________________ - Make setting to front-end accordingly. These steps could be taken by the console application programmer or a _____ service routine running on the console. They could also be performed by the DBM process in a much more efficient manner. The processing would be essentially the same as that for the current DBSET for this property (which just stuffs data into the files). If DBM were to perform this service it could be done as simply as: - Whenever processing a DBSET check to see if it's for the BASIC_CONTROL property. If not then all done. - If BASIC_CONTROL then do not send the data word received in the DBSET request. Instead use it as an attribute index into the BASIC_CONTROL PDB for the device. - Send that data to the front-end. ____ This, of course, would presume that the "forward" flag has been set. [The data-base UTI on the console should not need to be modified at all! Instead, we write little routines which make calls to the DBSET service. All they do is plug in an attribute index based on the name of the routine entry point.] 1.5 PROCESSING DIGITAL ALARM BLOCK DATA 1.5.1 Digital Alarm Block PDB The Digital Alarm Block property PDB is undefined at this time as the following routines do not require one. 1.6 PROCESSING ANALOG ALARM BLOCK DATA 1.6.1 Analog Alarm Block PDB The reader may have noticed that no routines for scaling information in the Analog Alarm Block have been listed. The unprocessed values in the Analog Alarm Block are always in the same ______ format as the unprocessed READING data for every device. Scaling is accomplished by obtaining the PDB for the device (READING) and then calling PDUDPU or PDUDCU. Simply supply the unprocessed Analog Alarm Block value as input data. To obtain the unprocessed value of interest from the alarm block the following routines are provided: 1-14 DATA SCALING SERVICES _____________________ 1.6.2 Obtaining Alarm Values Definition, IAVDEF integer*2_value = IAVDEF( INDATA, IERR [,LEN] ) This function is used to return the nominal and tolerance field definitions as specified by the user when the analog alarm was created. It operates on the status data returned by a DPGET call requesting the Analog Alarm Block property and returns the decoded two-bit K1/K0 field where: 0 nominal and tolerance 1 nominal and percent tolerance 2 minimum and maximum values 3 undefined (and reserved) The unprocessed analog monitor status is specified in INDATA. The optional LEN field will return the meaningful default data length of the nominal and tolerance fields of the alarm block based on the decoded two-bit Q1/Q0 field, in bytes (one, two or four). Since this routine operates only on the first two bytes of the Analog Alarm Block, it is sufficient to only have collected those two bytes (data request length of INDATA) with the DPGET call. IERR = 0 successful status decoding 1.7 PROCESSING GENERAL ALARM BLOCK DATA 1.7.1 Alarm Abort Inhibit Monitor, LABINH logical_value = LABINH( INDATA, IERR [,UNITS_TEXT] ) This logical function operates on the status data returned by a DPGET call requesting the Analog or Digital Alarm Block property and returns .TRUE. if the ABORT INHIBIT condition is set or .FALSE. if it is not set. The unprocessed analog or digital monitor status is specified in INDATA. The optional units text field will return a four character ASCII string of "IABT" or "____" as appropriate for the value of the function return. Since this routine operates only on the first two bytes of the Analog or Digital Alarm Block, it is sufficient to only have collected those two bytes (data request length of INDATA). IERR = 0 successful status decoding 1.7.2 Alarm Abort Monitor, LABSEL logical_value = LABSEL( INDATA, IERR [,UNITS_TEXT] ) 1-15 DATA SCALING SERVICES _____________________ This logical function operates on the status data returned by a DPGET call requesting the Analog or Digital Alarm Block property and returns .TRUE. if the ABORT on alarm condition is set or .FALSE. if it is not set. The unprocessed analog or digital monitor status is specified in INDATA. The optional units text field will return a four character ASCII string of "ABT_" or "____" as appropriate for the value of the function return. Since this routine operates only on the first two bytes of the Analog or Digital Alarm Block, it is sufficient to only have collected those two bytes (data request length of INDATA). IERR = 0 successful status decoding 1.7.3 Alarm Status Monitor, LALARM logical_value = LALARM( INDATA, IERR [,UNITS_TEXT] ) This logical function operates on the status data returned by a DPGET call requesting the Analog or Digital Alarm Block property and returns .TRUE. if the ALARM condition is set or .FALSE. if it is not set. The unprocessed analog or digital monitor status is specified in INDATA. The optional units text field will return a four character ASCII string of "ALRM" or "____" as appropriate for the value of the function return. Since this routine operates only on the first two bytes of the Analog or Digital Alarm Block, it is sufficient to only have collected those two bytes (data request length of INDATA). IERR = 0 successful status decoding 1.7.4 Alarm Bypass Monitor, LBYPAS logical_value = LBYPAS( INDATA, IERR [,UNITS_TEXT] ) This logical function operates on the status data returned by a DPGET call requesting the Analog or Digital Alarm Block property and returns .TRUE. if the alarm monitoring is BYPASSED or .FALSE. if it is not. The unprocessed analog or digital monitor status is specified in INDATA. The optional units text field will return a four character ASCII string of "BYP_" or "____" as appropriate for the value of the function return. Since this routine operates only on the first two bytes of the Analog or Digital Alarm Block, it is sufficient to only have collected those two bytes (data request length of INDATA). IERR = 0 successful status decoding 1-16 DATA SCALING SERVICES _____________________ 1.7.5 Obtaining The Unprocessed Nominal, MINNOM integer*4_value = MINNOM( INDATA, IERR [,UNITS_TEXT] ) This function returns a four byte value of unprocessed NOMINAL or MINIMUM data from the Analog or Digital Alarm Block property returned by a DPGET call. In the case of the ANALALMB property, the returned value is suitable for processing by PDUDPU or PDUDCU. For the DGALBL property, the returned value is a nominal bit pattern. The necessary alarm block is specified in INDATA. The optional units text field will return a four character ASCII string of "NOM_" or "MIN_" as appropriate for the defined value (NOMinal value, NOMinal bits, MINimum value), or "____" for an undefined value. IERR = 0 successful data retrieval 1.7.6 Obtaining The Unprocessed Tolerance, MAXTOL integer*4_value = MAXTOL( INDATA, IERR [,UNITS_TEXT] ) This function returns a four byte value of unprocessed TOLERANCE or MAXIMUM data from the Analog or Digital Alarm Block property returned by a DPGET call. In the case of the ANALALMB property, the returned value is suitable for processing by PDUDPU or PDUDCU. For the DGALBL property, the returned value is a mask of monitored bits. The necessary alarm block is specified in INDATA. The optional units text field will return a four character ASCII string of "TOL_" or "MAX_" or "MASK" as appropriate for the defined value (TOLerance, MAXimum value, monitored bits MASK), or "____" for an undefined value. IERR = 0 successful data retrieval 1.8 DATA SCALING EXAMPLE PROGRAM This is a FORTRAN language example of the use of ACNET data services discussed above. It is not intended to provide a detailed tutorial on the usage of these services. Good practice dictates that error returns from these service routines be examined and exceptions handled. For clarity, the error checking and handling has been omitted. In addition some familiarity with console library routines is assumed (in particular the use and operation of INTYPE, UNLD, TVM and CVG). With the above caveats the following example shows a complete application program which: 1-17 DATA SCALING SERVICES _____________________ 1. initializes a selective data acquisition request for a device reading 2. accesses the data-base to obtain scaling information 3. scales the reading 4. displays the scaled reading to the console TV at one Hertz 1-18 DATA SCALING SERVICES _____________________ c Sample application program to demonstrate use of ACNET data c services by displaying the current reading of the device 'EXT' c on the TV and updating it at 1 Hz. c c V0.01 A D Thomas 3-Feb-82 c c V0.02 G C Johnson 8-Feb-82 c Correct bug in A2DENG call. c c V0.03 A D Thomas 2-Nov-82 BYTE proprd !byte for reading property BYTE text(20) !text output buffer INTEGER dsprow, dspcol !TV display position INTEGER iwork(100) !work area for data-base access INTEGER extpdb(64) !storage for EXT's reading PDB INTEGER*4 extinx !long integer for device index INTEGER*4 extdat !for unscaled 'EXT' reading REAL extscl !scaled 'EXT' reading DATA proprd/6/ !'reading' property index DATA extinx/394401/ !device index of 'EXT' DATA dsprow/2/, dspcol/20/ !TV display position DATA iftd/60/ !freq-time descriptor for 1 Hz DATA icount/0/ !1 Hz countdown variable DATA iperrt/15/ !periodic execution rate-update CALL intype( itype, irow, icol ) !determine init/term/etc. GOTO( 100, 99, 99, 400 ), itype !branch on entry type 99 CALL unld !all done for now c Initialization: c Start up the data collection 100 CALL dpreq( extinx, proprd, inxdat, ierr, iftd ) CALL dpproc( ierr ) !process request list c Get scaling info from system data-base CALL dbwain( iwork, ierr ) !initialize work area CALL dbrpdb( extinx, proprd, iwork, inxpdb, ierr ) CALL dbproc( iwork,, ierr ) !process request list CALL dbget( inxpdb, iwork, extpdb, ierr ) !save PDB c ...work area is now free for other uses GOTO 99 c Periodic Execution: 400 icount = mod( icount+1, iperrt ) IF( icount .ne. 0 ) GOTO 99 c one Hertz execution CALL dpget( inxdat, extdat, ierr ) !get the raw data extscl = pdudcu( extdat, extpdb, ierr ) !scale the reading CALL cvg( extscl, 6, text, 1 ) !convert to characters CALL tvm( dsprow, dspcol, text, 6 ) !display the reading GOTO 99 END 1-19