Download Using the SAS® System for Data Collection under the VMS'" Operating System

Using the SAS· System for Data Collection under the VMS" Operating System
Ed Blair, SAS Institute Inc., Cary, NC
ABSTRACT
Physical Pmcess
Physical Phenomena &
Sensors
This paper discusses functionality provided by the SAS" System and
l
the VMS~ operating system that enables real-time or pseudo-realtime data collection. An abstract data acquisition system model is
developed and discussed. The concepts established in the model
~----------------
are applied to the development of a prototype set of user-written
OAT A step functions designed to support the DataMyte~ Corporation 762 series data acquisition controllers. The resulting set of func-
Signal Acquisition
Signal Conditioning & Conversion
tions represents a fully functional data collection tool kit. In the
interest of setting the framework. for further development. the discussion remains abstract and general except for those areas where
specific interface characteristics are required.
Controller and Communications Interlace
INTRODUCTION
The demand for integrated data collection and analysis tools in
manufacturing and laboratory automation is ever increasing. The
availability of powerful, low-cost VAX' workstation systems, continued development of distributed computing technology, and intelligent data acquisition controllers are important factors in driving this
demand. The SAS System has long been recognized for the
strength of its data analysis capabilities. The area of data acquisition
interfacing directly into the SAS System remains largely unexplored.
The enormous variety of data acquisiton hardware available in the
marketplace today, along with the lack of standardized interface
protocols across the spectrum, adds a level of complexity to the
problem of creating a homogeneous data collection environment
that can function with all such devices. Standards exist for defining
modular instrumentation interfaces. For more information, see
REFERENCES later in this paper. These have been widely used in
scientific applications, and to some extent in manufacturing applications. Even with such standards, there remains a large body of hardware utilizing vendor-specific interface protocols that must be dealt
with on a per case basis. All data collection systems have similarities
when approached from a suitable level of abstraction. In order to
systematize and structure a data collection system, an abstract
model of the data collection problem must first be developed.
Figure 1 Data System Model
DATA ACQUISITION SYSTEM MODEL
PHYSICAL PROCESS
SAS OAT A step Interlace Communications Device Layer
I
Controller Protocol Layer
I
Data Conversion Layer
t
, - - - - - - - - - - - - - - - - - - SAS Data Step
Data AnalYSIS, ReductIon, and DispOSItion
y
SAS Data
Sets
SAS/ACCESS$
OBI
Detailed discussion of physical processes is beyond the scope of
this paper-In an abstract sense, the data system derives its external
stimulus from some physical source. The physical process and sensors are inextricably coupled in most views of the data acquisition
system. The physical process stimulates the sensors to produce
measurable signals in the form of voltage or current that can be captured by the proper interfacing of signal conditioning and signal conversion electronics. Mathematical models for sensor behavior must
be used to reverse the transformation of the physical stimulus (for
example, heat, pressure, strain, stress, dimensional measurement,
weight) into an electrical voltage or current.
Figure 1 depicts the model in block-diagram form. It shows the various stages of the signal acquisition flow. Subsequent sections
describe these areas in terms of how SAS data collection software
should address them.
SIGNAL ACQUISITION
The signal conditioning stage of the model is again only of interest
in the abstract. This stage of the signal flow may not be present
in many systems or may be included physically as part of the signal
conversion/controller system hardware. Frequently, an electrical
signal emitted from a sensor will need to be transformed in some
manner to be compatible with the requirements of an AID converter
888
in the signal conversion system. A common requirement is that the
signal will undergo a simple linear transformation to offset or boost
(or both) the sensor output into the voltage range accepted by a
given AID converter. Such signal conditioning can also boost a signal with an inherently small voltage range to span the complete
range of the AiD converter to improve the resolution of the physical
measurement. More complicated kinds of signal conditioning are
applied in some systems that need to acquire time-series data. This
conditioning generally takes the form of an anti-aliasing filter to
remove unwanted frequency components of the signal.
hardware. For example, a set of DATA step functions designed to
support the DataMyte 762 controller can also be made to support
other DataMyte 700/800/2000 series devices in such a manner that
the same DATA step programming interface can be used for all of
these controllers (SAS Institute Inc. 1988).
As Figure 1 depicts, the model allows access to the different levels
of the DATA step interface as required to control and efficiently
acquire data from the external system. This imposes no restrictions
on the design of routines, nor does it require artificial, extraneous
call-through routines in order to keep a strict layering of access.
First and foremost, the signal conversion stage interprets the conditioned electrical signal and converts it into a digital form. The interpretation depends on the type of converter present in this stage of
the signal model. In some cases, the desire may be to count electrical pulses that exceed a certain voltage threshold. In other cases,
the desire may be to perform an A/D conversion yielding a digital
representation of the original analog voltage that can be processed
by host software. The selection of the proper acquisition hardware
to interpret the Signal is dependent on the sensor type and the
desired use of the resulting digital information.
DEVICE COMMUNICATIONS LAYER
CONSIDERATIONS
The device communications layer establishes and manages device
connections that are largely independent of the actual data acquisition controller itself. Connection-oriented approaches work well at
this layer and mimic the underlying functionality of most current OS
I/O systems. I/O sequences consisting of open, read/write, and
close fit with the level of abstraction desired at this level in the
model. The routines contained in this layer must focus on providing
the necessary I/O system interface to support reliable datagram
exchange with the controller. The routines in this layer should provide a functional I/O interface that isolates the controller layer from
the need to interact with operating system I/O services. This helps
to achieve a portable set of controller and data conversion functions.
The controller stage provides the intelligence to manage and control
access to the signal conversion hardware. It provides a communications path for interacting with signal conversion hardware. It also
imptements the packet assembly/disassembly support to interact
with the host system. This level transforms the information received
from or transmitted to the host into the necessary control signals
and/or representation to interact with signal conversion hardware.
The format of the digital data resulting from the signal conversion
depends on the sophistication of the controller stage and the way
the signal acquisition hardware interacts with the controller. The raw
digital format as produced by the signal conversion may be format
output by the controller. In other cases, the controller presents the
acquired data converted to the proper physical units. This is a function of the particular choice of controller and signal acquisition hardware.
CONTROLLER LAYER CONSIDERATIONS
The controller layer provides the necessary functionality for transporting data and commands to and from the data acquisition controller. It embodies such operations as controller datagram
assembly and disassembly, data transport integrity, error recovery
policy, and procedure for failures that cannot be handled at the
device communications level. This layer uses the underlying device
communications layer as a device driver to isolate the system and
device-specific aspects of performing I/O from the controllerspecific aspects of command and data transport.
This communications interface stage implements the necessary protocols and device control functions to communicate to the host system over the associated physical link. A given physical-link level
protocol such as RS-232 may be used as the communications interface by a variety of data acquisition controller vendors, yet these
individual controllers have different datagram formats and data
exchange protocols. Further, some controllers are offered with a
variety of physical communications interfaces. For example,
CAMAC crate controllers are available for RS-232/422, IEEE-488,
paralle/(A lIA2). and seria~L2) CAMAC highway standards. The
crate controller protocols used to interact with CAMAC modules are
the same, only the data-link packet formats and physical-link transmission protocols change from one to another. In all cases, the
CAMAC crate-level operations are driven by the same station
address, sub-address, function-code, and data information.
The relationship between these layers must be defined and driven
by considering aspects of the controller and device communications
interfaces. These include timing requirements, data throughput
rates, device and controller buffering capacities, 110 system utilization efficiency. and datagram delivery protocols. For example, the
DataMyte 762 controller uses a simple ACKlENQ/NAK protocol to
respectively acknowledge, reject, or request retransmission of a
datagram. A question of design arises regarding the best layer to
position protocol handling and error recovery. From one point of
view, handling this low-level transmission protocol at the device
layer improves efficiency of execution and allows for some optimization of the I/O sequence. The disadvantage is that the device layer
becomes somewhat customized for the DataMyte controller protocols. Retransmission of failed datagrams can similarly be controlled
at the device level for efficiency, but at the expense of loss of generality. These are design choices that must be analyzed when considering how best to layer functionality.
SAS DATA STEP INTERFACE
The SAS DATA step interface represents a layering of interface
functions designed to splice the higher level acquisition processing
incorporated into SAS DATA step code into the external data acquisition hardware system. The level of abstraction presented by this
interface layer should allow the data acquisition hardware to be
treated as a "black boxH from which elements of data are extracted
for further interpretation, analysis, reduction, and storage. This
interface endeavors to encapsulate the under1ying characteristics
of the communications and controller protocols used to transport
the data to or from the data acquisition hardware. Dealing with the
hardware at this level of abstraction simplifies the DATA step code
and potentially allows the investment in data analysis and reduction
code to be preserved and applied across different data acquisition
DATA CONVERSION LAYER FUNCTIONS
This layer incorporates any of the functions necessary to massage
the acquired data into a format suitable for presentation to and use
by the SAS DATA step code. The SAS DATA step deals in character
and numeric data types. On the VAX, as well as most other hosts,
numeric means the double precision floating-point representation.
Character data of course means an alphanumeric text string
889
where the scale factor M is the full-range AID converter input voltage range divided by the full-range binary output range of the converter. The base XO is included to allow for various excess-type
binary representations, and the offset YO is included to allow for
voltage offsets applied in the converter to boost the signal into a
more appropriate range before digitizing.
encoded using the appropriate character codes (ASCII or EBCDIC).
For most data acquisition hardware available today, same transformation of data is required to convert from transmission format into
SAS System format.
At the lowest level, data must be extracted from the controller datagram. This process involves scanning through the datagram and
extracting transmitted values from the syntactic information contained there. This process may be as simple as indexing by a fixed
number of storage units for each item of information to be extracted.
Still simple, but a little more time consuming, are those formats that
require scanning for a repeating delimiter character in datagram and
extracting the intervening bytes as elements of data. More complicated datagram formats might require the interpretation of variable
length sub-packet formats imbedded in the datagram. These formats require sequential scanning and evaluation to interpret the
sub-packet type in order to determine the content and starting location of the next sub-packet. All of these operations have as a common goal the elimination of controller specific syntax for the
representation of transmitted information. For example, a DataMyte
controller transmits all of its information in ASCII encoded text (SAS
Institute Inc. 1988). Once the bracketing transmission protocol is
extracted, the remaining datagram consists of a sequence of data
elements delimited by ; characters.
The effects of signal conditioning electronics on the AID input voltage must be reversed in order to obtain the voltage emitted from
the sensor. Mathematically, this amounts to applying the inverse of
the signal conditioning transformation to obtain the voltage originally
present as the input to the signal conditioning stage. Frequently,
these operations can be represented by a simple linear transformation that must be reversed in order to obtain the true sensor voltage/current.
Conversion of the sensor output voltage to equivalent physical units
is usually the most difficult part of the signat flow model inversion
process. A mathematical description of the sensor's behavior is necessary for the construction of inverse transformation to convert the
signal value from this point back into meaningful physical units. In
some cases, the signal acquisition system has sensor models built
into the resident sofware/firmware to support most if not all of this
conversion. These support common industrial sensors that have
known models and fixed calibration constants. In the SAS data collection interface, this support should be incorporated at the DATA
step programming level when needed. The SAS language provides
a sufficiently rich set of mathematical operators and functions to
support any sensor models (SAS Institute Inc. 1988). User-written
OAT A step functions provide another means for implementing sensor unit conversions for more complicated sensor types.
Knowledge of how a particular data element should be interpreted
poses another problem. The question must be resolved as to
whether the next data element should be interpreted as a character
string or as a time stamp, as an error code or a data value. In the
case of the DataMyte 762, this requires knowledge about the command or commands executed to invoke the reply contained in the
datagram as well as parametric information about the current DataMyte setup. For example, the ?DATA/ITEM=n command which
returns data points for item n generates a reply of the following format:
DATAMYTE INTERFACING: A PROTOTYPE FOR
DEMONSTRATING THE MODEL
<STX><T imeStamp 1>; <Open; <Mach>; <Cause>; <Data 1>; ... ; <Da taM>;
<TimeStamp2>; ....•• .:TimestampP>; ..••• (EOT>
The DataMyte 762 controller functions as a slave to a master communcations system. In this case, the master is the SAS System running a set of DataMyte interface functions from a SAS DATA step
program. The DataMyte controllers implement a simple bracketing
protocol around a logical datagram. This applies to transmissions
to and from the master. Logical datagrams are composed of one
or more physical datagrams. Each physical datagram begins with
a single sentinel character (an ASCII <STX> character) followed
by a 2-byte, ASClt-encoded character count, followed by the datagram text, followed by a 2-byte, ASCII-encoded check sum. The last
physical datagram in the logical transmission contains a trailer sentinel character(an ASCII <EDT» immediately preceding the 2-byte
check sum transmission. The check sum represents the encoding
of the single byte exclusive OR operation on all of the bytes in the
datagram beginning with the <STX> sentinel up to, but not including, the check sum bytes. To visualize a typical datagram transmission, the following diagram is useful:
The reply groups data into subgroups of M points each for a total
of P subgroups. The values M and P must be determined from sampling the ?SETUP information contained in the DataMyte unit or by
generating a specific lSETUP operation from the DATA step code
prior to starting the data collection phase.
A controller may transmit tags with the data items to identify how
the data should be interpreted, or the semantics may be implicit by
the nature of the data acquisition hardware involved. For example,
the format of a data stream resulting from reading data points from
a CAMAC transient data recorder module is implied by the module
type Involved. The module design dictates that it stores and transmits 8-, 12-, or 16-bit binary digital values that are sign extended
to the word size requested in the CAMAC transaction. Knowing the
module type alone dictates how to correctly interpret the stream of
data resulting from the module read operation.
Datagram
Format
.:STX> (CC 1> <CC2> ( .•. Data str ing ..• HCS 1> <CS2>
.:S'l'X> (CC 1>.:CC2> (. .. Data str ing ... >.:CS 1>.:CS2>
Dealing with binary data from hardware such as a CAMAC transient
data recorder is simple compared to the interpretation/conversion
of this data in the context of the signal flow that produced the data.
The oonversion of these measured data values into physical units
represents the most complex challenge to be addressed by the data
conversion layer. The extraction of individual data element values
generated from such a module is usually a matter of indexing
through a linear array of binary values of the same atomic data type.
The problem lies in the association of parameters to convert the
binary representation into a value that has meaningful physical units.
For example, the conversion of the binary value into an equivalent
voltage usually requires a simple linear transformation:
.:STX>.:CC 1> <CC2>< ... Data string ... ><EOT> <CS 1><CS2>
Following each physical datagram transmission, the transmitting
party must wait for a single byte transmission from the receiving
party. This must be one of the three following ASCII character
codes:
<ACK>
Y~M'(X-XO)+YO
890
indicates the datagram was received and
validated. For an intermediate datagram,
it indicates the transmiSSion was received
and verified. For the <EDT> datagram,
DMGMSG
it indicates the specified. operation can be
successfully executed. The <ACK> for
a valid data request command is
transmitted before the reply datagram
sequence generated to satisfy the
request.
<NAK>
indicates that the datagram was received
in error. Retransmission of the same
datagram is appropriate.
<ENQ>
indicates that the DataMyte is unable to
execute the command or satisfy the data
request. Causes are. a bad parameter in
the command, a parameter inconsistent
with the current device state, or a bad
command name. In general, no recovery
is possible until the condition is corrected.
All of the DataMyte access functions generate a numeric return
code that indicates the success of the requested operation. The
return code uses a value of 0 to indicate success. A value of -1
returned means that the data supply at the requested level has been
exhausted. In particular, -1 return codes from the DMGETR,
DMGETC, and DMGETN routines can be expected and indicate that
no more replies are available for the specified DMCB or that no more
data items are available for the current reply within the DMCB context. Other nonzero return codes translate into message text by
using the DMGMSG routine.
DEVICE COMMUNICATIONS LAYER FUNCTIONS
The DataMyte controllers currently provide RS-232 interfaces to
support master node communications. for a VAX-based implementation, it is desirable to provide access to hard-wired RS-232 ports
and reverse LAT ports to provide DataMyte access through the LAN
via DECserver terminal servers. for this implementation, routines
contained in this layer are completely isolated from DATA step
access, since establishing a DataMyte connection context implicitly
performs device connection and management as required. A separate context called the DataMyte Device Control Block (DMDCB)
retains all of the information required to support the RS-232 port
operations. This structure includes the VMS 110 channel, device
mode control block, and termination character masks for use with
various 010 read requests. The functions provided in this layer
include the following:
All of the DataMyte commands conform to the following syntax:
[H!" I II?" I <Command> I / <Pao:<Value> ••• II ; <Data>; ...•• I
The "!" commands direct the DataMyte to store information passed
through the command parameters (delimited by the I separators) or
the data values (delimited by the; separators). The ~T commands
request infonnation from the DataMyte and result in reply datagrams sent from the DataMyte back to the master. These datagrams generally have the following syntax:
<Val tie 1>; <Value2> ; ..•...•
These syntax specifications must of course be enveloped by the
appropriate protocol and checksum characters before transmisSion
to the DataMyte controller for evaluation.
DATAMYTE DATA STEP INTERFACE FUNCTIONS
DMSEND
sends commands to a specified DataMyte
controller.
DMREAD
extracts and classifies items of
information from a DataMyte reply list.
DMGETR
establishes an active DataMyte reply
context for subsequent CHARACTER and
NUMERIC data item extraction.
DMGETN
extracts NUMERIC data items from the
active DataMyte reply context.
DMGETC
extracts CHARACTER data items from
the active DataMyte reply context.
DMCLOSE
DMTERM
DMIOXMIT
transmits a message to the DataMyte
receives messages from the DataMyte
762.
DMIOCLOSE
closes the VMS 110 channel and releases
the DMCB storage.
CONTROLLER LAYER FUNCTIONS
All DataMyte access revolves around the connection context called
the DataMyte Control Block (DMCB) established by the DMOPEN
function. The DMOPEN func~ion returns a handle or 10 value for the
DMCB when the connection is successfully established. This value
must be used in all subsequent OM function operations that communicate with and extract data from the DataMyte controller. The
DMeB carries along with it the information necessary to classify the
controller model, and the device-independent information about the
state of the connection. It also carries information linking the controller to the device communcations layer of the data system model.
The DMCB also retains information returned from the DataMyte in
response to query commands. It becomes the vehicle for the OM
functions to pass information and isolate the DATA step cade from
the details of interacting with the DataMyte controller. The DATA
step function performing the connection accepts a parameter string
that supplies information about the DataMyte controller and the
communications device to be used for accessing it. The controller
connection routine examines this information, extracting the pieces
of information that it finds meaningful, and then passes this same
information to the device connection routine where it extracts those
pieces that it finds meaningful.
performs one-time initialization of the
DataMyte API.
establishes connection to a DataMyte
controller unit.
creates the DMCDB and opens a VMS
1/0 channel to the device.
762.
Here is a list of the prototype DataMyte functions by name and a
brief description of each:
DMOPEN
DMIOOPEN
DMIORECV
The DATA step functions designed to fit the data collection model
layering are connection oriented. Each DataMyte controller must be
explicitly opened before it can be accessed for any purpose. The
DataMyte generates datagrams to the master when queried for the
current values of certain parameters and acquired data points.
When using the DataMyte controller, the application environment
dictates the proper command sequences to be transmitted. The
DATA step interface does not dictate the policy for how the controller is used, but rather provides the tools necessary to allow flexibility
in designing an application around the DataMyte functionality.
DMYTE
translates a DataMyte return code into
message text.
A single DATA step function DMSEND supports all DataMyte command transfers, both for directive and query type operations. The
function supports multiple commands in the same SAS character
string variable. These commands are delimited by the ASCII line-
terminates an open DataMyte connection.
terminates all open DataMyte
connections.
891
feed character. As the DMSEND function formats and transmits
DataMyte command datagrams, it uses the functionality of the
device communications layer to send these messages and to support the required data exchange and integrity protocols. The DMCB
carries along the information to associate the DataMyte controller
with the proper device-layer class driver. DMSEND also interprets
the DataMyte command stream sent to the controller to determine
which command transfers will generate DataMyte replies. When it
issues a DataMyte request-type command, DMSEND must change
modes and become a receiver for a period while the OataMyte
responds with the datagram sequence generated to satisfy the
request DMSEND constructs a reply context for each query command that retains the datagram sequence generated from the DataMyte. When the DataMyte satisfies the query command, OMS END
adds the reply context to the list of pending replies in the DMCB.
This allows multiple query commands to be executed in sequence
before any of the replies are examined to extract data. An unrecoverable error on a particular DataMyte command in a sequence
aborts that sequence. Any replies generated by successful commands up to the point of the failure remain part of the DMCB and
may be interrogated using the DMREAD, DMGETR, DMGETC, and
DMGETN functions.
This prototype supports two models for reading replies generated
from the execution of DataMyte query commands. The DMREAD
interface extracts, classifies, and returns a single reply data element
on each request. The DMGETR function, used in conjunction with
the DMGETC and DMGETN functions, provides a more sophisticated and efficient method for extracting multiple reply data elements with a single request. Both methods are simple to use, and
both require knowledge of reply semantics in order to make the
proper determination about the conversion and use of reply elements extracted_ Generally DMGETA, used together with the
DMGETC and DMGETN functions, presents the most simple
method for extracting reply elements, since most of the elements
returned require numeric interpretation. DMREAD and
DMGETR/DMGETC/DMGETN operations can be intermixed freely
during the course of interrogating reply contexts associated with a
given DMCB.
For the first method, DMREAD establishes an implicit active reply
context if one does not already exist. Reply elements are extracted
from this context sequentially until they are exhausted. At this time,
DMREAD attempts to advance to the next reply context If no more
reply contexts exist for the specified DMCB, DMREAD returns a -1
value to indicate the end of data for the DMCB. For each reply element extracted, OM READ attempts to classify the element based
on its content alone. If the data are alphanumeric, DMREAD classifies the element as 'C' type and returns the value as CHARACTER
If the data matches a DataMyte timestamp format, OM READ classifies the element as 'T' type and retums the value as CHARACTER.
If the data matches a OataMyte numeric string([+I- ]<DIGITS>[.<DIGITS>
OM READ classifies the element as 'N' type, converts the value to the DATA step numeric representation, and
returns that value as NUMERIC. Every OM READ request returns
the first eight characters of the DataMyte command that generated
the reply and the user-defined tag value for the command if one was
specified.
The DMSEND function supports another concept called tagging.
With the capability to mix a stream of DataMyte query commands
into a single DMSEND operation, associating the reply contexts to
something meaningful in the application context becomes important. To this end, a tag value may be aSSOciated with each DataMyte
command. The tag may consist of a string of 1-8 numeric characters
that precede the U?H or "I" DataMyte command type classifier.
DMSEND recognizes such a character sequence prefixing the type
classifier and converts the numeric string to an equivalent binary
representation. DMSEND stores the tag value in the reply context
generated from the datagram sequence received from the DataMyte
when the query command is executed. For example, the tag may
be encoded into the command string as the array index for a conversion factor to be used for scaling the values returned from interrogating a particular DataMyte data item. Similarly, the tag value may
be used to differentiate multiple occurrences of the same DataMyte
commands executed with a DMSEND command stream. Tags represent a user-defined value that is carried along with the reply by
the OM functions; DMSEND imposes no other requirements on the
value other than that it be composed of numeric characters.
n,
The second method of interrogating reply contexts requires the use
of the three functions DMGETR, DMGETC. and DMGETN in a cooperative fashion to extract reply elements. DMGETR establishes an
active reply context and returns the tag value, if any, along with the
first eight characters of the DataMyte command executed to generate the reply. If the command is fewer than eight characters in
length, DMGETR blank pads the returned value to that length. You
may advance the active reply context at any time during an interrogation cycle by simply calling the DMGETR function for the associated DMCB. This discards the remainder DataMyte datagrams for
the current active reply and locates the next reply context with valid
datagrams to interrogate. Note that once you advance past a given
reply, the data associated with' that reply are discarded and must
be read again from the DataMyte controller. Repeated use of the
DMGETR request is one way to flush all of the queued reply contexts from a given DMCB. When no valid reply context remains for
the DMCB, DMGETR returns a -1 value to indicate the end of valid
data for that DMCB.
DMCLOSE and DMTERM functions both terminate open controller
contexts. You use DMCLOSE to terminate a specific DMCB, and
you use DMTERM to terminate all of the open controller contexts
at once. If you use DMCLOSE to explicitly close an open DMCB,
the variable passed to the DMCB request wilt be set to a 0 value
upon successful completion of the request.
DATA CONVERSION LAYER FUNCTIONS
As discussed previously, the DMCB retains a list of reply contexts
generated from the execution of DataMyte query commands. A set
of functions enables you to interrogate these reply contexts to
extract information to process within the DATA step code itself. The
reply element represents an atomic unit of information in a reply context Physically, a reply element is the amount of information contained between two successive DataMyte reply datagram delimiters
(for example, the character string terminated by the ";H and
<EOT> characters in the reply). Reply elements are fundamentally
ASCII character strings. A DATA step apptication may interpret reply
elements within the context of the command that generated the
reply and request that they be converted to NUMERIC representation based on knowledge that certain reply elements are expected
to be numeric.
Once an active reply context is established, DMGETN and DMGETC
operations return one or more occurrences of NUMERIC and
CHARACTER reply elements from the active reply context These
two functions are very similar in their use, the only difference being
that DMGETN converts reply elements to NUMERIC representation,
while DMGETC returns CHARACTER representations for the reply
elements. Both of these functions accept a variable number of trailing NUMERIC or CHARACTER variables to be extracted and filled
with reply elements. Each of these functions requires a NUMERIC
parameter NUMARG specifying the maximum number of reply elements to be extracted. SeHing the value of this parameter to a negative number causes the function to attempt to extract as many reply
892
elements as there are variable arguments. Each routine requires a
NUMERIC argument NUMRET that receives the actual number of
reply elements extracted. Each routine terminates the reply element
extraction when one of the following three conditions is met:
Arguments:
DMCB
A NUMERIC variable containing the OataMyte
control block handle returned from the
DMOPEN function. If this variable does not
contain a valid DMCB handle, an error return is
generated.
NUMSTR A NUMERIC value defining the number of
CHARACTER string type variables from the
array of CHARACTER strings to process for
sending DataMyte commands. A value of -1
specifies that all of the passed CHARACTER
string variables are to be processed.
DMCSTR One or more occurrences of a CHARACTER
string type variable containing a sequence of
DataMyte comands to be executed. The string
may contain multiple commands delimited by
ASCII line-feed characters. Query and directive
commands may be freely intermixed in the
command string. DataMyte replies generated
from the execution of query commands are
stored in the DMCS for later retrieval through
Ihe DMGETR/DMGETN/DMGETC funclions.
• the next consecutive reply element does not exist or has the
wrong type to convert to the requested representation
• the number of extracted reply elements meets the NUMARG
value if specified as a positive quantity
• all the NUMERIC variables passed as arguments in the
DMGETN function request are filted with reply elements.
In any case, you can expect the NUMRET variable to contain the
actual reply element count extracted from the active reply context.
If the DMGETC/DMGETN request exhausts the data supply in the
active reply context. the active reply context is discarded. Any subsequent attempt to perform a DMGETC/DMGETN function on the
DMCB resutts in a -1 return code to indicate that no more data exist
in the current active reply context. Another DMGETR request must
be executed for the DMCB to establish the next active reply context
before continuing to extract reply elements.
RC
All of these functions except DMGMSG return a NUMERIC value
indicating the completion status of the request. A value of zero indicates that the request was successfully completed. A value of -1
Indicates that an end of data condition exists in the data stream for
the attempted request. This is an informational return and should
be acted upon accordingly. Other nonzero values require message
translation via DMGMSG.
RC ~ DMYTE ( );
Abstract:
Performs one-time initialization of the DataMyte
API.
Arguments: None.
RC ~ DMOPEN (PARSTR, DMCB);
Abstract:
Establishes connection to a DataMyte controller
unit.
Arguments:
PARSTR A CHARACTER string specifying the
connection parameters to be used to establish
a OataMyte controller connection. This string
uses a keyword syntax with comma delimiters
between the keyword values. Spaces or tabs
between keyword values are permitted. Spaces
within a keyword are not allowed. Spaces in
the value specified for a keyword are
interpreted within the context of the value
conversion as appropriate. This value may be a
constant string or a CHARACTER type
variable.
A NUMERIC variable to receive the DMCB 10
DMCB
returned from the successful execution of the
DMOPEN operation.
DMSEND (DMCB, NUMSTR, [DMCSTR I
OF DMCSTR (') 1);
Abstract:
Sends commands to a specified DataMyte
controller.
RC
~
DMREAD (DMCB, DMCMD, DMDTYPE, DMTAG,
DMNUM, DMCHAR);
Abstract:
Extracts and classifl6s items of information from a
DataMyte reply list
Arguments:
DMCB
A NUMERIC variable containing the DataMyte
control block handle returned from the
DMOPEN function. If this variable does not
contain a valid DMeB handle, an error return is
generated. If the DMCB does not contain any
valid reply contexts, OMREAD returns a value
of -1 to indicate the end of data condition.
DMCMD A CHARACTER variable to receive the first
eight characters of the DataMyte command
executed to generate the reply being
interrogated. DMREAD pads the string to eight
characters if the command is shorter than eight
characters or truncates if longer.
DMOTYPE A CHARACTER variable to receive a single
character return code indicating the class of
the data item extracted from the current reply
context. Expected return values for this code
include:
'C' indicates a CHARACTER value was
returned to the DMCHAR variable.
'T' indicates DataMyte timestamp was
returned to the DMCHAR variable.
'N' indicates a NUMERIC value was
converted and returned to the
DMNUM variable.
'M' indicates a blank token was extracted
from the DataMyte reply context
interrogated by this request.
DMTAG
A NUMERIC variable to receive the tag value
saved by DMSEND for the query command
that generated the reply being interrogated.
DMREAD returns a value of 0 if no tag was
specified for the command.
DMNUM
A NUMERIC variable to receive the converted
numeric value for 'N' data type returns.
DETAILED DATAMYTE FUNCTION INTERFACE
DESCRIPTIONS
~
893
DCHAR
DMNUM
A CHARACTER variable to receive the
extracted character string value for 'C' or 'T'
type returns. If the extracted value does not fit
lnto the CHARACTER variable, the DMREAD
truncates the result to the CHARACTER
variable length. DMREAD sets the
CHARACTER variable current to match the
exact return length.
One or more occurrences of a NUMERIC type
variable to receive converted NUMERIC values
from the active DataMyte reply context.
DMGETN returns values beginning with the
first NUMERIC variable, continuing through
successively increasing indices until one of the
three conditions described under the NUMRET
variable is encountered.
RC ~ DMGETC (DMCB, NUMARG, NUMRET, [DMNUM I
OF DMNUM{'l]);
Abstract:
Extracts CHARACTER data items from the active
DataMyte reply context.
Arguments:
A NUMERIC variable containing the DataMyte
DMCB
control block handle returned from the
DMOPEN function. If this variable does not
contain a valid DMCB handle, an error return is
generated. If the DMCB does not contain an
active reply context from previous execution of
a DMREAD or DMGETR function, DMGETN
returns a value of -1 to indicate the end of
data condition.
NUMARG A NUMERIC value defining the maximum
number of CHARACTER type variables from
the array to fill with extracted character data
elements from the active reply context. A value
of -1 specifies that values are to be converted
for all of the passed NUMERIC variables.
NUMRET A NUMERIC variable to receive the number of
CHARACTER data elements returned. This
value is limited by the minimum of the following
three conditions: the number of remaining data
elements from the active reply context, the
NUMARG v~ue if specified as a positive
quantity, and the actual number of
CHARACTER variables passed as arguments
in the DMGETC function request.
DMCHAR One or more occurrences of CHARACTER
string type variables to receive character data
elements extracted from the active DataMyte
reply context. DMGETC returns values
beginning with the first CHARACTER variable,
continuing through successively increasing
indices until one of the three conditions
described under the NUMRET variable is
encountered. For each CHARACTER variable
retumed, DMGETC sets the CHARACTER
variable length to match the exact character
count returned to the variable.
RC ~ DMGETR (DMCB, DMCMD, DMTAG);
Abstract:
Establishes an active reply context for
DMGETC/DMGETR calls.
Arguments:
A NUMERIC variable containing the DataMyte
DMCB
control block handle returned from the
DMOPEN function. If this variable does not
contain a valid DMCB handle, an error return is
generated. If the DMCB does not contain any
valid reply contexts, DMREAD returns a value
of -1 to indicate the end of data condition.
DMCMD A CHARACTER variable to receive the first
eight characters of the DataMyte command
executed to generate the reply being
interrogated. DMREAO pads the string to eight
characters if the command is shorter than eight
characters or truncates if longer.
DMTAG
A NUMERIC variable to receive the tag value
saved by DMSEND for the query command
that generated the reply being interrogated.
DMREAD returns a value of a if no tag was
specified for the command.
RC ~ DMGETN (DMCB, NUMARG, NUMRET, [DMNUM I
OF DMNUM{'I]);
Abstract:
Extracts NUMERIC data items from the active
DataMyte reply context.
Arguments:
A NUMERIC variable containing the DataMyte
DMCB
control block handle returned from the
DMOPEN function. If this variable does not
contain a valid DMCB handle, an error return is
generated. If the DMCB does not contain an
active reply context from previous execution of
a DMREAD Of DMGETR function, DMGETN
returns a value of -1 to indicate the end of
data condition.
NUMARG A NUMERIC value defining the maximum
number of NUMERIC type variables from the
array to fill with converted numeric data
elements from the active reply context. A value
of -1 specifies that values are to be converted
for all of the passed NUMERIC variables.
NUMRET A NUMERIC variable to receive the number of
converted NUMERIC values. This value is
limited by the minimum of the following three
conditions: the number of consecutive numeric
values from the active reply context. the
NUMARG value if specified as a positive
quantity, and the actual number of NUMERIC
variables passed as arguments in the DMGETN
function request.
RC ~ DMCLOSE (DMCB);
Abstract:
Terminates an open DataMyte connection.
Arguments:
A NUMERIC variable containing the DataMyte
DMCB
control block handle returned from the
DMOPEN function. If this variable does not
contain a valid DMCB handle, an error return is
generated. DMCLOSE sets this variable to a 0
value upon the successful completion of the
close operation.
RC ~ DMTERM ( );
Abstract:
Terminates all open DataMyte connections.
Arguments: None.
894
MSGSTR -
DMMSG (ERRC);
Abstract:
Translates a DataMyte return code into message
REFERENCES
text.
Arguments:
ERRC
MSGSTR
DataMyte Corporation (1988). DataMyte 76x/86x Communications
Functional Specification (Version 1.3). Minnetonka, MN: OataMyte
Corporation.
A NUMERIC variable containing an efror code
generated from the execution of a OataMyte
function request. DMGMSG converts the error
code into a CHARACTER string and returns its
value to the caller.
A CHARACTER string variable to receive the
message text generated from the specified
error message code.
IEEE (1982), CAMAC Book 1982, Doc. No. SH08482, New York:
IEEE.
IEEE (1982), CAMAC Serial Highway System and Serial Crate Con1rol/er Type L2, Std. No. 595, New York: IEEE.
IEEE (1982), A Modular Instrumentation System tor Data Handling,
Std. No. 583, New York; IEEE.
IEEE (1982) Organization of Multi~Crate Systems (Parallel Branch
Highway), Std. No. 683, New York: IEEE.
CONCLUSION
DATA step functions represent a convenient method to interface
data acquisition hardware into the SAS environment. This method
capitalizes on the power of the DATA step programming language
for providing data analysis, conversion, and reduction support. The
DATA step interface functions isolate and encapsulate the external
data system communtcations protocols and datagram formatting to
provide a flexible tool kit. Using the data acquisition signal model
as a starting point, a set of prototype OAT A step interface functions
is described for supporting the DataMyte Corporation 762 series
controllers. These functions represent a tully~functional data collection interface for the 762 unit capable of supporting a variety of data
collection applications.
SAS Institute Inc. (1988). SAS Language Guide, Release 6.03
tion, Cary, NC: SAS Institute Inc.
.
Edi~
SAS and SAS!ACCESS are registered trademarks of SAS Institute
Inc., Cary, NC.
VMS and VAX are trademarks of Digital Equipment Corporation.
OataMyte is a registered trademark of OataMyte Corporation.
895