Design Specification
for the
EPICURE Central Database
Transaction Sequencer V1.01
Research Division Controls Software Design Note 67.1
David M. Kline
Contents
Related Documents
For additional material regarding the EPICURE data acquisition system, Central
Database, or VAX-Rdb/VMS; refer to the following document list.
- ``An Overview Of EPICURE Architecture'', EPICURE Design Note 14.1.
- ``EPICURE User's Guide, Volume IV'', Release Note 37.0.
- ``EPICURE Central Database'', Design Note 61.0.
- ``VAX-Rdb/VMS RDML Referance Manual'', Order Number: AA-JL07B-TE.
- ``VAX-Rdb/VMS Guide to Programming'', Order Number: AA-N038D-TE.
Introduction
The transaction sequencer is a function that interfaces an application program with the EPICURE
Central Database. It was designed to provide a consistent method of accessing the central database and perform
the required Rdb
commands to implement the
add, modify, delete, and reporting transactions
. An application can request a transaction by building a sequencer
execution list (SEL) by provided support functions. After the list is built it is passed to the sequencer to
verify and execute. If the verification process was successful, the sequencer will accept the list and execute
the transactions sequentially until the end of the list is reached. Otherwise the sequencer will abort the SEL
and return both the completion status and transaction identifier value to the application program. Furthermore,
each transaction will return a text string representation of the status code.
The transaction sequencer will be implemented using a combination of VAX-C
and the VAX-Rdb/VMS
Relational Data Manipulation Language (RDML)
calls. RDML is a preprocessor which statements are embedded into
an application language. When the RDML preprocessor executes the statements are converted into
Digital Standard Relational Interface (DSRI) calls. Through these calls, an application program
instructs VAX-Rdb/VMS to manipulate data.
Sequencer Execution List
The sequencer execution list (SEL) is a singly linked list of data packets
that have been dynamically allocated and bound together through provided support functions. The data packets
provide the sequencer with the required information or storage area to execute a transaction
on the central database.
The SEL is composed of different types of data packets that are configured to define
which transaction to execute. At the beginning of the list is a head node. It serves
as the entry point and provides information about the entire list. The head node points to the
first transaction node data packet. Transaction nodes are used to specify the type of
transaction the sequencer will execute. They can be chained together thereby allowing multiple
transactions in the same SEL. The last transaction node is linked back to the head node to
form a circular list. Detail ``A'' illustrates the SEL.
A SEL transaction node contains pointers to property node data packets. Property
nodes can either contain device property or device property attribute information.
The following lists the property nodes and which properties and/or attributes they contain.
- device summary data packet
- - The device name, heterogeneous,
beamline, class, text, save/restore, location, devicetype, moduletype,
xtext, controllertype, history, moduleloc, and list property information
is located in this data packet.
- history data packet
- - The device history property data packets are
attached to the device summary data packet in order to implement multiple
history entries within the database for the report and delete sequencer
functions.
- reading property data packet
- - The source class, frontend computer, pdb, constant pairs, function,
rate, size, read protection, and addressing property attribute information is contained in this
data packet.
- setting property data packet
- - The source class, frontend computer, pdb, constant pairs, rate, size,
read protection, write protection, and addressing property attribute information is contained
in this data packet.
- status property data packet
- - The source class, pdb, bitname, rate, size, read protection,
and addressing property attribute information is contained in this data packet.
- control property data packet
- - The source class, pdb, rate, ctlname, size, write protection,
and addressing property attribute information is contained in this data packet.
- reading alarm property data packet
- - Currently not defined.
- status alarm property data packet
- - Currently not defined.
The reading, setting, status, control, reading alarm, and status alarm property nodes
contain a attribute mask field that provides a summary of the device attributes that will be
added, modified, or reported by the sequencer.
Detail ``B'' illustrates the relation between a transaction node and a property node.
Each property node data packet contains pointers to either the device property information
or an attribute node. These nodes provide the device property attribute information such as bitname,
ctlname, or synthetic function code/constants. The following lists the attribute node data packets and
their contents.
- synthetic constants/code attribute data packet
- - The synthetic function code and the constants that
are associated with the function components are provided by this data packet. This data packet was intended
to work in conjunction with the synthetic DAP data packet. The DAP will list the device components such as
or . Whereas this data packet identifies the synthetic
function and the constants associated with the components. Furthermore, the index of the constant array will
identify the component it is associated with.
- ctlname attribute data packet
- - The control property property node data packet contains a
pointer to the ctlname attribute node data packet. Each ctlname attribute node provides the space for one
ctlname, however additional space is provided to link another ctlname attribute node to it, allowing for multiple
ctlname attribute nodes. The node on the list that contains a null pointer value identifies the end of the ctlname
attribute nodes.
- bitname attribute data packet
- - The status property property node data packet contains a pointer to
the bitname attribute node data packet. Each bitname attribute node provides the space for one bitname, however
additional space is provided to link another bitname attribute node to it, allowing for multiple bitname attribute
nodes. The node on the list that contains a null pointer value identifies the end of the bitname attribute nodes.
The reading, setting, status, and control property node data packets require the addressing
device property attribute to access the device. For the sequencer to support this, another data packet is needed
by the property nodes. The data packet is a DAP block that contains a DAP code which identifies the DAP
to use and a pointer to the required DAP data
, additional information and packet formats are provided in a later section.
Detail ``C'' illustrates a sequencer execution list and how the
head node, transaction nodes, and property nodes connect together. Additional
sections are provided to describe these data packets and their format in detail.
The following sections provide more information and data formats of the head node,
transaction node, property nodes, and attribute nodes.
Head Node Data Format
The sequencer is passed a pointer to a head node which is an entry point and
a summary of the SEL. The contents of the head node will be verified and if successful, the
sequencer will accept the SEL and continue to process the data packets. However, if the
verification fails, the sequencer aborts the entire SEL and returns an error status code
to the application program. The following is a diagram of the head node data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the data packet as a head node.
- transaction pointer
- - Pointer to the first transaction node. If the SEL is
empty, the pointer is the address of the head node.
- number of transactions
- - Count of the transaction nodes in the list.
Transaction Node Data Format
The head node transaction pointer field allows the processing to continue by
providing a pointer to the first transaction node. Transaction nodes are data packets
which identify the transaction to execute on the database and provide the sequencer with the
required information or storage area. Initially the data packet type field
will be read and verified that a transaction node exists. If the verification was
successful, the sequencer will process the information, otherwise an error status code is placed
into the completion status code field and the equivalent text string is copied into the
transaction node datapacket. The sequencer will read the transaction pointer field and
determine whether to execute the next transaction node or exit the SEL. The following outlines
the data format and defines the fields which compose a transaction node.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the data packet as a transaction node.
- transaction pointer
- - Pointer to the next transaction node or the head node.
- transaction id
- - Uniquely identifes the transaction for logging and auditing purposes.
- function code
- - Identifies a database add, modify, delete, or report operation.
- function code modifier
- - Augments the function code.
- property mask
- - Identifies which properties are to be added, modified, or reported.
- di property
- - Device di property.
- name property
- - Device name property.
- device summary
- - Address of the device summary data packet.
- reading property
- - Address of the reading property data packet.
- setting property
- - Address of the setting property data packet.
- status property
- - Address of the status property data packet.
- control property
- - Address of the control property data packet.
- reading alarm property
- - Address of the reading alarm property data packet.
- status alarm property
- - Address of the status alarm property data packet.
- completion status code
- - Identfies the condition of the transaction at its completion.
- completion status message
- - Provides the text string equivalent of the completion status code.
Property Node Data Formats
The transaction node contains the di and name device properties and
pointers to property nodes where the reading, setting, status, control, reading alarm,
or status alarm device property information resides. Within the property nodes are the device
property attribute information. However, the device summary property node contains only property
information such as the name, heterogeneous, beamline, class, text, save/restore, location, devicetype, moduletype,
xtext, controllertype, history, moduleloc, and list device property information. Additionally
the reading, setting, status, control, reading alarm, and status alarm property nodes
contain an attribute mask that summarizes which attributes to add, modify, or report from the
property node. The following sections identify the data packet types and describe the fields that are
contained in the property nodes.
Device Summary Data Format
The device summary is a data packet providing the additional device property information
that does not appear in a transaction node. Note that the name device property appears again in this
data packet. This was for algorithm convenience to implement the modify transaction easily. The following is a
diagram of the device summary data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the propery node as the device summary data packet.
- property mask
- - Identifies which properties are to be added, modified, or reported.
- di property
- - The device di property used with the report sequencer function.
- name property
- - The device name property used with the modify or report
sequencer functions.
- heterogeneous property
- - Indicates whether an array device is heterogeneous, homogeneous, or scaler.
- beamline property
- - Identifies which beamline(s) the device belongs to.
- class property
- - The class property categorizes the device as NORMAL, SYNTHETIC,
COMPOUND, or NONDEVICE.
- text property
- - Descriptive text for the device.
- save/restore property
- - Device settings can be saved and restored.
- location property
- - The device beamline location information.
- devicetype property
- - Device type represented as a type and modifier number.
- moduletype property
- - Describes the device as a CAMAC module type.
- xtext property
- - Extended descriptive text.
- controllertype property
- - Currently not implemented.
- history property
- - Maintenance history for the device.
- moduleloc property
- - Building name where the device is located.
- device template property
- - Text string of the device template used to create the device.
- list property
- - List of the di property(s) present for only COMPOUND devices.
History Property Data Format
This property node is a data packet providing the device history property information. The following
is a diagram of the data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the property node as the history property data packet.
- history property pointer
- - Address of the next history property data packet. The link is terminated
by a null pointer.
- history id
- - Identifies the history data entry.
- date and time
- - Time and data stamp when the transaction occurred.
- history
- - History text string.
Reading Property Data Format
This property node is a data packet providing the device reading property information. The following
is a diagram of the data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the property node as the reading property data packet.
- attribute mask
- - Identifies which property attributes to add, modify, or report.
- array offset
- - Data offset for array devices.
- frontend computer
- - Identifies the frontend computer used.
- source class attribute
- - Identifies the data source class name.
- pdb attribute
- - Analog scaling attribute data for the device property.
- constant pairs
- - Constant pairs used by the analog scaling attribute.
- synthetic function code
- - Identifies the function to use for synthetic devices.
- rate attribute
- - Rate attribute default sample rates.
- size attribute
- - Size attribute returned data size for the device and property.
- read protection attribute
- - Read protection device property attribute.
- addressing attribute
- - Information needed to address the device.
Setting Property Data Format
This property node is a data packet providing the device setting property information. The following
is a diagram of the data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the propery node as the setting property data packet.
- attribute mask
- - Identifies which property attributes to add, modify, or report.
- array offset
- - Data offset for array devices.
- frontend computer
- - Identifies the frontend computer used.
- source class attribute
- - Identifies the data source class name.
- pdb attribute
- - Analog scaling attribute data for the device property.
- constant pairs
- - Constant pairs used by the analog scaling attribute.
- rate attribute
- - Rate attribute default sample rates.
- size attribute
- - Size attribute returned data size for the device and property.
- read protection attribute
- - Read protection device property attribute.
- write protection attribute
- - Write protection device property attribute.
- addressing attribute
- - Information needed to address the device.
Status Property Data Format
This property node is a data packet providing the device status property information. The following
is a diagram of the data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the propery node as the status property data packet.
- attribute mask
- - Identifies which property attributes to add, modify, or report.
- array offset
- - Data offset for array devices.
- frontend computer
- - Identifies the frontend computer used.
- source class attribute
- - Identifies the data source class name.
- pdb attribute
- - Status scaling attribute data for the device property.
- rate attribute
- - Rate attribute default sample rates.
- bitnames attribute
- - Device property bitnames attribute.
- size attribute
- - Size attribute returned data size for the device and property.
- read protection attribute
- - Read protection device property attribute.
- addressing attribute
- - Information needed to address the device.
Control Property Data Format
This property node is a data packet providing the device control property information. The following
is a diagram of the data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the propery node as the control property data packet.
- attribute mask
- - Identifies which property attributes to add, modify, or report.
- array offset
- - Data offset for array devices.
- frontend computer
- - Identifies the frontend computer used.
- source class attribute
- - Identifies the data source class name.
- pdb attribute
- - Control scaling attribute data for the device property.
- rate attribute
- - Rate attribute default sample rates.
- ctlnames attribute
- - Device property ctlnames attribute.
- size attribute
- - Size attribute returned data size for the device and property.
- write protection attribute
- - Write protection device property attribute.
- addressing attribute
- - Information needed to address the device.
Reading Alarm Property Data Format
This property node is a data packet providing the device reading alarm property information. The following
is a diagram of the data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the propery node as the reading alarm property data packet.
- attribute mask
- - Identifies which property attributes to add, modify, or report.
- spare
- - Reserved for future use.
Status Alarm Property Data Format
This property node is a data packet providing the device status alarm property information. The following
is a diagram of the data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the propery node as the status alarm property data packet.
- attribute mask
- - Identifies which property attributes to add, modify, or report.
- spare
- - Reserved for future use.
Attribute Node Data Formats
Attribute nodes are data packets which provide the device property attribute
information that are used by the add, modify, or report transactions. The following sections
provide a diagram of the attribute nodes data format and descriptions of the fields
which compose the data packets.
Ctlname Attribute Data Format
This attribute node is a data packet providing the device property attribute ctlnames. These
data packets are linked together and terminated by a null pointer to identify the end of the list. The following
is a diagram of the data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the attribute node as the ctlname attribute data packet.
- ctlname attribute pointer
- - Address of the next ctlname attribute data packet. The link is
terminated by a null pointer.
- ctlname sequence number
- - Uniquely identifies a ctlname attribute.
- ctlname
- - Ctlname text string.
- value
- - Value or bit mask for operations.
Bitname Attribute Data Format
This attribute node is a data packet providing the device property attribute bitnames. These
data packets are linked together and are terminated by a null pointer to identify the end of the list. The following
is a diagram of the data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the attribute node as the bitname attribute data packet.
- bitname attribute pointer
- - Address of the next bitname attribute data packet. The link is
terminated by a null pointer.
- bit number
- - Value of the bit number.
- short bitname
- - Short bitname text string.
- color 0
- - ``Color'' for bit = 0 state.
- color 1
- - ``Color'' for bit = 1 state.
- state 0 text
- - Text string for bit = 0 state.
- state 1 text
- - Text string for bit = 1 state.
- long bitname
- - Long bitname text string.
Sequencer Support Structures
This section provides the data formats and field descriptions of the data packets that
support the sequencer with its operations.
DAP Block Data Format
This support data packet is used by the application program or sequencer to identify
the type of DAP used and a pointer to the data to address the device. The following is a
diagram of the data format.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the data packet as the DAP block.
- DAP code
- - Identifies the DAP type which is used to address the
device
.
- DAP ptr
- - Pointer to where the DAP data resides.
Sequencer Processing List Data Format
The Sequencer Processing List (SPL) instructs the sequencer which data packet
to process during a single transaction. For each SPL element, the process data packet field is read.
The field identifies which data packet to process during the transaction. The sequencer
determines the operation to perform by adding the process data packet, function code,
and function code modifier offsets together. The result is mapped into the function table
array which determines the function to execute. The following is the data format for one element of the SPL.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the data packet as the sequencer processing list element.
- process data packet
- - Identifies the data packet to process.
Function Table Data Format
This support data packet determines which sequencer function
to execute. The function table index is calculated by the below formula.
Each of the elements are offsets which are summed to determine i, the location of the
function to execute.
The following is a diagram of the data format for one function table element.
The individual fields of the data packet are described below.
- data packet type
- - Identifies the data packet as the function table data packet.
- function
- - Address of the function that the sequencer will execute to
process the data packet.
Sequencer Operations
The sequencer supports add, modify, delete and report operations
on the central database. Initially the sequencer will verify the head node pointer passed to it
by the application program. If the value is null, an error status code is returned to the
application program. Additionally the data packet type, transaction node pointer,
and number of transactions fields of the head node are checked for any invalid
values. If any one of these are invalid, and error status code is returned and the entire
transaction list is aborted.
After the head node has been verified, the sequencer will begin to process the information
contained in the transaction node(s). But before any device property or attribute data is processed,
the data packet type
and transaction pointer fields are verified. If any values are found to be
invalid, the sequencer aborts the SEL and places the status and its text string equivalent into the transaction
node completion status code and completion status message fields respectively. After these checks
are made and the data has been processed, the sequencer proceeds to the next transaction node.
The operation performed by the sequencer is determined by the function code and
function code modifier fields, and values present in the SPL
. The data that the sequencer is to add or modify
is specified in the transaction node property mask and the property node attribute mask
fields. If a database read is requested, the transaction node di and name fields, and
property and attribute masks are required. Initially the application program should only request the
device summary data packet. Then after the data is retrieved and processed, additional requests can
be made by setting the bits in the mask fields.
The addition of a device to the database requires that the application program supply all the
necessary information in the transaction node. The sequencer will read the transaction node
property mask field to determine which database constructs to access. After this, the
mask will be read bit by bit until the end is reached. At that time the data is assumed to
be entered into the database and the status of the operation is placed into the transaction node
completion status code field and the text string equivalent is copied into the completion status message
field. Any further additions to the device will be considered a database modification.
A modification to the database is similar to an addition but the property mask and
attribute mask fields determine which properties or attributes to modify. The
addition of a new property or attribute is determined by comparing the propery mask or
attribute masks supplied by the application prorgam with the values in the database. If the
values are different, the new data will be added.
Deleting a device from the database requires that only the corresponding property and attribute
bits be set in the masks. The sequencer will only delete the requested properties or attributes as identified
within the masks. Before the property or attribute is deleted, the data is read and placed into the appropriate
property or attribute datapacket.
Reading a device from the database requires the application program must supply the transaction node,
property mask, and the property node attribute mask fields. The sequencer will be responsible for
allocating the required data packets for the attribute nodes and retrieving the information from the database.
However, the application will be responsible for invoking the support functions which deallocate the
dynamic memory used for the data packets.
Sequencer Implements
The sequencer supports several functions and symbols that are used to setup the SEL and perform
the VAX-Rdb database manipulations. The next sections describe them briefly.
Sequencer Symbols
The symbols used by the application program are passed to the sequencer support functions
to implement a database transaction. Below describes them.
- Sequencer Functions
- - Below lists the symbols which are passed to the start_transaction()
support function to request the desired database transaction.
- CDB_FNC_ADD
- - Requests an add database transaction to be performed.
- CDB_FNC_MODIFY
- - Requests a modify database transaction.
- CDB_FNC_DELETE
- - Requests that a delete be performed on the database.
- CDB_FNC_REPORT
- - Requests a read operation.
- Available Properties
- - Below lists the device properties that are available to the application
program.
- CDB_C_PRP_DI
- - Device Index property.
- CDB_C_PRP_NAME
- - Name property.
- CDB_C_PRP_CLASS
- - Device class property.
- CDB_C_PRP_TEXT
- - Device text property.
- CDB_C_PRP_READING
- - Device reading property.
- CDB_C_PRP_SETTING
- - Device setting property.
- CDB_C_PRP_STATUS
- - Device status property.
- CDB_C_PRP_CONTROL
- - Device control property.
- CDB_C_PRP_READINGALARM
- - Device reading_alarm property.
- CDB_C_PRP_STATUSALARM
- - Device status_alarm property.
- CDB_C_PRP_SAVERESTORE
- - Save_restore property.
- CDB_C_PRP_BEAMLINE
- - Beamline property.
- CDB_C_PRP_LOCATION
- - Device location property.
- CDB_C_PRP_DEVTYPE
- - Device_type property.
- CDB_C_PRP_LIST
- - Device list property.
- CDB_C_PRP_XTEXT
- - Device xtext property
- CDB_C_PRP_DEVTEMPLATE
- - Device_template property.
- CDB_C_PRP_MODULELOC
- - Moduleloc property.
- CDB_C_PRP_HISTORY
- - Device history.
- CDB_C_PRP_CONTROLLERTYPE
- - Controllertype property.
- CDB_C_PRP_MODULETYPE
- - Moduletype property.
- CDB_C_PRP_HETEROGENEOUS
- - Device heterogeneous property.
- CDB_C_PRP_DELEVERYPRP
- - Delete every property for the specified device.
- Available Attributes
- - Below lists the device property attributes that are available to the application
program.
- CDB_C_ATR_NONE
- - No attribute used for the given property.
- CDB_C_ATR_SIZE
- - Size attribute.
- CDB_C_ATR_SOURCECLASS
- - Sourceclass attribute.
- CDB_C_ATR_RATE
- - Rate property attribute.
- CDB_C_ATR_READPROTECTION
- - Read protection attribute.
- CDB_C_ATR_WRITEPROTECTION
- - Write protection property attribute.
- CDB_C_ATR_FUNCTION
- - Synthetic function/constants attribute.
- CDB_C_ATR_BITNAMES
- - Status property bitnames attribute.
- CDB_C_ATR_DISPLAY
- - Not implemented.
- CDB_C_ATR_MODULETYPE
- - Moduletype attribute.
- CDB_C_ATR_CTLNAMES
- - Control property ctlnames attribute.
- CDB_C_ATR_ARRAYOFFSET
- - Arrayoffset property attribute.
- CDB_C_ATR_ANALOGSCALING
- - Reading and setting property scaling attribute.
- CDB_C_ATR_CONTROLSCALING
- - Control property scaling attribute.
- CDB_C_ATR_STATUSSCALING
- - Status property scaling attribute.
- CDB_C_ATR_FRONTENDCOMPUTER
- - Frontend computer attribute.
- CDB_C_ATR_CONSTANTPAIRS
- - Analog scaling attribite constant pairs.
- CDB_C_ATR_DELEVERYATR
- - Delete every attribute for the given property.
- CDB_C_ATR_CAMAC_DAP
- - Addressing attribute CAMAC DAP.
- CDB_C_ATR_CAMAC_14_17_DAP
- - Addressing attribute CAMAC 014/017 DAP.
- CDB_C_ATR_SAFETY_DAP
- - Addressing attribute safety DAP.
- CDB_C_ATR_TESTCAMAC_DAP
- - Addressing attribute test CAMAC DAP.
- CDB_C_ATR_CRYO_DAP
- - Addressing attribute cryo DAP.
- CDB_C_ATR_SYNTHETIC_DAP
- - Addressing synthetic DAP.
- CDB_C_ATR_ADDRESSING
- - This attribite is used only for read and delete sequencer functions.
Support Functions
The functions that are available for an application program to construct a sequencer execution list
and implement a database transaction are listed below.
- hn = init_SEL( STATUS )
- - The init_SEL() function allocates, initializes, and returns
the pointer to the SEL head node.
- Where:
- hn
- - Pointer to the SEL head node.
- STATUS
- - Identifies the function completion condition.
- tid = start_transaction( HN, DI, NAME, FC, FCM, STATUS )
- - The
start_transaction() function allocates, initializes, and attaches
a transaction node to the SEL. It will return a transaction id that
is used by the application program to identify the transaction for adding,
modifying, deleting, or reporting information. The
function parameters are listed below.
- Where:
- tid
- - Transaction node identification.
- HN
- - Pointer to the SEL head node.
- DI
- - The DI property to place into transaction node.
- NAME
- - The NAME property to place into transaction node.
- FC
- - The sequencer function code.
- FCM
- - The sequencer function code modifier.
- STATUS
- - Identifies the function completion condition.
- status = modify_transaction( HN, TID, DI, NAME, FC, FCM )
- - The
modify_transaction() function changes the transaction node
function code, function code modifier, di, and
name fields specified by the TID parameter. The function parameters
are listed below.
- Where:
- status
- - Identifies the function completion condition.
- HN
- - Pointer to the SEL head node.
- TID
- - Transaction node identification.
- DI
- - The DI property to place into transaction node.
- NAME
- - The NAME property to place into transaction node.
- FC
- - The sequencer function code.
- FCM
- - The sequencer function code modifier.
- status = delete_transaction( HN, TID )
- - The
delete_transaction() function deallocates the space that
has been alloted for the transaction specified by the TID
parameter.
- Where:
- status
- - Identifies the function completion condition.
- HN
- - Pointer to the SEL head node.
- TID
- - Transaction node identification.
- status = add_device( HN, TID, PRP, ATR, DATA )
- - The
add_device() function is called to specify the device
property or attribute information to add, modify, or report in the database.
A status code is returned that identifies whether the operation completion
succesfully or failed. The function requires several parameters which are
described below.
- Where:
- status
- - Identifies the function completion condition.
- HN
- - Pointer to the SEL head node.
- TID
- - Transaction node identification.
- PRP
- - Device property number.
- ATR
- - Device property attribute number.
- DATA
- - Pointer to where data resides.
- bitname_ptr = alloc_BITNAME( STATUS )
- - Allocates a bitname attribute data packet.
- Where:
- bitname_ptr
- - Pointer to the BITNAME data packet.
- STATUS
- - Identifies the function completion condition.
- ctlname_ptr = alloc_CTLNAME( STATUS )
- - Allocates a ctlname attribute data packet.
- Where:
- ctlname_ptr
- - Pointer to the CTLNAME data packet.
- STATUS
- - Identifies the function completion condition.
- history_ptr = alloc_HISTORY( STATUS )
- - Allocates a history property data packet.
- Where:
- history_ptr
- - Pointer to the HISTORY data packet.
- STATUS
- - Identifies the function completion condition.
- DAP_ptr = alloc_DAPtyp( DAPTYP, STATUS )
- - Allocates a DAP attribute data packet.
- Where:
- DAP_ptr
- - Pointer to a DAP data packet.
- DAPTYP
- - Identifies the DAP type to allocate.
- STATUS
- - Identifies the function completion condition.
- status = dealloc_DP( PTR )
- - Deallocates the datapacket specified by the
passed pointer.
- Where:
- status
- - Identifies the function completion condition.
- PTR
- - Pointer to the datapacket to deallocate.
- bytecnt = cpy_padstr( DEST, SRC, SIZE )
- - Copies the SRC string into the DEST string and
pads the rest of the DEST with space characters.
- Where:
- bytecnt
- - The count if bytes copied.
- DEST
- - The destination string.
- SRC
- - The source string.
- SIZE
- - Size of the DEST string.
- bytecnt = cpy_byte( DEST, SRC, SIZE )
- - Copies the SRC into the DEST on a byte-by-byte basis.
- Where:
- bytecnt
- - The count if bytes copied.
- DEST
- - Destination.
- SRC
- - Source.
- SIZE
- - Size of the DEST.
- status = bit_clr( BITNUM, MASK )
- - Clears the bit specified by BITNUM in the MASK.
- Where:
- status
- - Function completion status.
- BITNUM
- - Bit number to operate on.
- MASK
- - Data to operate on.
- status = bit_set( BITNUM, MASK )
- - Sets the bit specified by BITNUM in the MASK.
- Where:
- status
- - Function completion status.
- BITNUM
- - Bit number to operate on.
- MASK
- - Data to operate on.
- condition = bit_test( BITNUM, MASK )
- - Tests the value of the bit specified by BITNUM in the MASK.
- Where:
- condition
- - Value of bit.
- BITNUM
- - Bit number to operate on.
- MASK
- - Data to operate on.
Status Codes
The status codes returned by the support and internal functions identify the
condition of the function upon completion. These codes can be used to execute different code paths
within database editor or application programs. Below lists the codes and their meaning.
- Success severity
- - The below status codes are of the the success severity.
- CDB$_NORMAL
- - Support function successful completion.
- Error severity
- - The below status codes are of the error severity.
- CDB$_DAPERR
- - Data Access Packets function error.
- CDB$_DIORNAMREQ
- - DI or NAME property required.
- CDB$_GENSSFERR
- - The gen_* support function error.
- CDB$_PARAMERR
- - Support function parameter error.
- Fatal severity
- - The below status codes are of the fatal severity.
- CDB$_DATAMISMATCH
- - Property/attribute data expected.
- CDB$_DTYPERR
- - Datapacket datatype error.
- CDB$_DEVTYPERR
- - Device CLASS type error.
- CDB$_NOEXEFNC
- - No table execution function exists.
- CDB$_NOMEMALL
- - Dynamic memory allocation failed.
- CDB$_NOMEMDEALL
- - Dynamic memory deallocation failed.
- CDB$_TNCNTERR
- - Transaction node count error.
- Warning severity
- - The below status codes are of the warning severity.
- CDB$_DATAERR
- - Data passed contains error(s).
- CDB$_DIPRPREQ
- - DI property required.
- CDB$_NAMPRPREQ
- - NAME property required.
- CDB$_NOATR
- - Attribute not supported.
- CDB$_NODATAFOUND
- - Requested data not found in database.
- CDB$_NODEVSUM
- - No DEVICE SUMMARY datapacket exists.
- CDB$_NOCONTROL
- - No CONTROL datapacket exists.
- CDB$_NOFNC
- - Sequencer function code not supported.
- CDB$_NOFCM
- - Sequencer function code modifier not supported.
- CDB$_NOHISTORY
- - No HISTORY datapacket exists.
- CDB$_NOHN
- - No head node datapacket exists.
- CDB$_NOPRP
- - Property not supported.
- CDB$_NOREADING
- - No READING datapacket exists.
- CDB$_NOREADINGALARM
- - No READING ALARM datapacket exists.
- CDB$_NOSETTING
- - No SETTING datapacket exists.
- CDB$_NOSTATUS
- - No STATUS datapacket exists.
- CDB$_NOSTATUSALARM
- - No STATUS ALARM datapacket exists.
- CDB$_NOTN
- - No transaction node datapacket exists.
- CDB$_RANGERR
- - Support function internal range exceeded.
- CDB$_TNFNCERR
- - Transaction node function code error.
Security, Privacy, Legal
rwest@fsus04.fnal.gov