RD Controls Software Release Note 101.10

Central Database (CDB) Server

User Task Interface

Cynthia A. Chopp, Ed Dambik, John DeVoy, David M. Kline

April 13, 1993

This document describes the CDB (Central Database) Server UTI (User Task Interface). The Central Database Server is a server process which receives database transaction requests from other applications and executes them on the central database on behalf of the requestor. The reader should refer to RD Controls Software release notes 102.x and 103.x for a description of the central database. The UTI described here provides a simple interface to the CDB Server. Services provided include:

• Setting up and maintaining a channel to the CDB Server on whatever node it is running;
• Sending and receiving messages to and from the CDB Server;
• Maintaining buffers in which device and template records are stored;
• Giving the application controlled access to the devices and templates;
• Allowing the application to copy, modify and delete existing devices and templates;
• Allowing the application to recover from crashes (journaling).

For each device that the application wishes to access the UTI maintains a transaction buffer. A transaction buffer contains a copy of the RMS record for the device plus some data needed by the UTI and the CDB Server. Transaction buffers are created in two ways: when the application makes a request to retrieve a device from the CDB Server, and when the application asks to create a new device by making a copy of an existing transaction buffer. When a transaction buffer is created a (longword) handle that uniquely identifies the buffer is returned to the application; this handle will be needed by the UTI in all subsequent references to the transaction buffer. Note that the application cannot access the contents of the transaction buffer directly, but must go through the UTI.

Whenever the UTI sends a modified device to the CDB Server, it includes with the device a set of bit masks indicating which properties and/or attributes have been modified. The CDB Server can use this information to track the changes made to a device.

Once a transaction buffer is created the application may request that the UTI access and/or modify the various properties and attributes of the device. Details are provided in the individual routine descriptions below. If a device has been modified (or created via a copy request) the application can send the changed (or created) device to the CDB Server by making a commit request. If the application has asked that the UTI mark a transaction buffer for deletion then the corresponding device will be removed from the CDB Server when a commit request is made. The application may also request that the CDB Server perform a build.

If the DECnet channel to the CDB Server goes down for any reason, the UTI will assume that the Server has stopped running. When this happens the UTI will broadcast a message to the user's terminal announcing that the CDB Server has gone away and will start up a timer driven routine that will try to reestablish the connection. The application will be placed in a hibernate state until the new connection is made. When the connection is reestablished the UTI will broadcast another message and retry the transaction that was in progress when the channel went down. Note that the new CDB Server will not necessarily be on the same node as the old one.

The UTI maintains a record of modified (but not committed) devices in a journal file named sys$login:dbsauti.jnl. Whenever a transaction buffer is created or modified a copy of the buffer is placed in the journal file. The transaction buffer will be deleted from the file when the device is successfully committed or canceled. If the application terminates unexpectedly, the user may use the file to recover any modified devices that the application had not yet committed or canceled. The file will be deleted if the user disconnects normally. Note that the file is used only as needed -- if the application does not modify or create any devices, then no journal file is created. If the UTI encounters any errors while creating or maintaining the journal file, it will broadcast a message to the user's terminal. Only one message will be broadcast until the internal error flag is cleared by the application calling dbsa_disconnect_session(). While in an error state the journaling feature is essentially turned off. The recommended procedure in this case is for the user to stop the application, correct the problem, and restart.

Some known ``gotchas'':

• GIGO. If the application gives the UTI data that is inconsistent, it should not be surprised if the UTI and/or the Server get confused, and the database gets scrambled. In particular, the UTI assumes that the length fields of all properties and attributes are correct.
• In most cases, when the application specifies the name of a device, the name is converted to upper case and padded with spaces to the correct length. The exception to this rule is dbsa_search_di().
• If the CDB Server goes down in the middle of an operation, the UTI could get confused.
• If the application tries to retrieve a device a second time (without an intervening cancel), the UTI will return a second handle for the same transaction buffer. There is a possibility for confusion if the application and/or user is not aware of this.
• The status alarm property does not have its own copy of a bitnames attribute; instead, it contains a pointer to (or to be more precise, the offset of) the bitnames attribute of the status property. There is a possibility for confusion if the application and/or user is not aware of this.
• Any pointers to a specific property or attribute within a transaction buffer become invalid after the buffer is modified or canceled.
• If two users try to access the same device at the same time, the UTI may get confused.
• If the application tries to create a template with the same name as a device, the UTI may get confused.
• When the UTI makes a sanity check on a device, if a property or attribute has both length and count fields, the count field is not checked.
• When dbsa_copy_dev() overwrites an existing device, it ignores the template parameter (see the description of dbsa_copy_dev() for more details).
• The UTI is not AST reentrant. Applications that use the UTI at AST level do so at their own risk.
• When a device is recovered from a journal file, the UTI does not check to see if a transaction buffer containing that device already exists. There is therefore a possibility of confusion.
• If the application exits without calling dbsa_disconnect_session(), the journal file (if any) will not be deleted.

status = dbsa_request_session( )

Open a channel to the CDB Server. The logical RDCS$DBSA_SERVER_NODE is expected to define a search list of nodes on which a Server might be running. A connection is made to the first node running a Server. If the Server reports that either builds or the entire database is locked, it will be indicated by the condition code returned. If the database later becomes unlocked, the user will be notified via a broadcast message (a message will also be broadcast if the database becomes locked after this routine is called.) As well as opening a channel, this routine will create a virtual memory zone from which the transaction buffers will be allocated. If this routine is called a second time, then the previous connection to the CDB Server will be dropped and a new one attempted; any transaction buffers will be unaffected and all valid handles will remain valid. This routine must be called before any other DBSA_\ routine.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success. The caller will be authorized to modify devices (but not necessarily templates) and to request LAL builds.

DBSA__NOBUILD:

Success. The caller will be authorized to modify devices but will not be able to request a build.

DBSA__READONLY:

Success. The caller does not have authorization to modify devices or request builds.

DBSA__BLDLCKD:

Warning. Builds a currently locked out. A broadcast message will inform the user when builds are unlocked.

DBSA__CDBLCKD:

Warning. The database is currently locked. A broadcast message will inform the user when the database is unlocked.

DBSA__NONET:

Error. Unable to translate the logical, or unable to open a channel to a CDB Server on any of the specified nodes.

Others:

From assorted VMS system service and LIB$ routines.

status = dbsa_disconnect_session( )

Disconnect from the CDB Server. The channel to the Server is closed and the virtual memory zone created by dbsa_request_session() is reset. The journal file, if it exists, is deleted, and the error flag is reset. If the application does not call this routine before it exits, then the journal file will not be deleted. This routine implicitly calls dbsa_cancel_all(). No DBSA_ routine other than dbsa_request_session() may be called after this one.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $DASSGN system service and LIB$ dynamic memory routines.

status = dbsa_get_statistics( stat_ptr )

Returns a pointer to a structure containing statistics on the CDB Server. The pointer that is returned references a static buffer; this buffer will be overwritten by the next call to this routine.

stat_ptr:

Returns a pointer to a DBSA_STATS_ACCUM structure. Pointer passed by reference (i.e., a pointer to a pointer). The DBSA_STATS_ACCUM structure is defined in the file dbsa_rms_defs.h.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $QIO system service and CDB Server.

status = dbsa_get_dirange( dilow, dihigh [,templatelow, templatehigh)

Returns the lowest and highest device DI values currently in the CDB Server. Optionally also returns the lowest and highest template DI values. These values do not reflect any data that may be in uncommitted buffers. Note that while the templatelow and templatehigh parameters are both optional, they must be supplied or omitted as a pair. Supplying the value zero (NULL) has the same effect as omitting a parameter.

dilow:

Returns the lowest device DI value in the CDB Server. Integer passed by reference.

dihigh:

Returns the highest device DI value in the CDB Server. Integer passed by reference.

templatelow:

Returns the lowest template DI value in the CDB Server. Integer passed by reference.

templatehigh:

Returns the highest template DI value in the CDB Server. Integer passed by reference.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $QIO system service and CDB Server.

status = dbsa_name_to_di( name, di [,prop_mask

[,prop_list, attr_masks] )] Return the DI of a device given its name. The optional property mask parameter returns a bit mask indicating which properties are contained in the device (i.e., have non-zero offsets). The optional property list parameter specifies a list of properties for which the UTI should return an attribute mask. An attribute mask is a bit mask indicating which attributes are present in a given property. The optional attribute masks parameter returns a list of attribute masks corresponding to the properties specified in the property list parameter. The fixed length properties are by definition always present, and the fixed length attributes are by definition always present if the corresponding property is present. Note that while the property list and attribute masks parameters are both optional, they must be supplied or omitted as a pair. Supplying the value NULL for the optional parameters has the same effect as omitting them. Also note that if the mask parameters are omitted this function is much more efficient than dbsa_report_name().

name:

The name of the device. The name will be converted to upper case and padded with spaces to the correct length. Fixed length string descriptor passed by reference.

di:

Returns the DI of the device named above. Integer passed by reference.

prop_mask:

If supplied, returns a bit mask indicating which properties are contained in the device. A zeroed bit indicates that the corresponding property is not contained in the device. A DB_PRP_MASK structure passed by reference. This structure is defined in the file dbsa_rms_defs.h.

prop_list:

If supplied, specifies a list of properties. An array of integers passed by reference. The first element contains an integer count of the number of properties being specified. The remaining elements specify the properties. The file dbuser.h defines the following constants as meaningful property specifiers:

DB_C_PRP_READING:

Analog reading.

DB_C_PRP_SETTING:

Analog setting.

DB_C_PRP_STATUS:

Digital reading.

DB_C_PRP_CONTROL:

Digital setting.

DB_C_PRP_READING_ALARM:

Alarm for analog reading.

DB_C_PRP_STATUS_ALARM:

Alarm for digital reading.

attr_masks:

If supplied, returns a list of attribute masks corresponding to the properties specified above. An array of DB_ATR_MSK structures passed by reference. This structure is defined in the file dbsa_rms_defs.h. The attribute masks will be returned in the same order that they were specified. A zeroed bit indicates that the corresponding attribute is not contained in the property. All of the bits in the attribute mask will be zeroed if the corresponding property is not present in the device, or was not specified by one of the above constants.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NODEVICE:

Error. No device exists with the given name.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $QIO system service and CDB Server.

status = dbsa_di_to_name( di, name [,prop_mask

[,prop_list, attr_masks] )] Return the name of a device given its DI. Otherwise, the same as dbsa_name_to_di().

di:

The DI of the device. Integer passed by value.

name:

Returns the name of the device having the above DI. Fixed length string descriptor passed by reference.

prop_mask:

If supplied, returns a bit mask indicating which properties are contained in the device. A zero bit indicates that the corresponding property is not contained in the device. A DB_PRP_MASK structure passed by reference. This structure is defined in the file dbsa_rms_defs.h.

prop_list:

If supplied, specifies a list of properties. An array of intgers passed by reference. The first element contains an integer count of the number of properties being specified. The remaining elements specify the properties. The file dbuser.h defines the following constants as meaningful property specifiers:

DB_C_PRP_READING:

Analog reading.

DB_C_PRP_SETTING:

Analog setting.

DB_C_PRP_STATUS:

Digital reading.

DB_C_PRP_CONTROL:

Digital setting.

DB_C_PRP_READING_ALARM:

Alarm for analog reading.

DB_C_PRP_STATUS_ALARM:

Alarm for digital reading.

attr_masks:

If supplied, returns a list of attribute masks corresponding to the properties specified above. An array of DB_ATR_MSK structures passed by reference. This structure is defined in the file dbsa_rms_defs.h. The attribute masks will be returned in the same order that they were specified in the property list parameter. A zeroed bit indicates that the corresponding attribute is not contained in the property. All of the bits in the attribute mask will be zeroed if the corresponding property is not present in the device, or was not specified by one of the above constants.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NODEVICE:

Error. No device exists with the given DI.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $QIO system service and CDB Server.

status = dbsa_report_name( name, handle_ptr [,create_date

[,modify_date] )] Create a transaction buffer containing the device indicated. A handle is returned that must be used in all subsequent references to this transaction buffer. If a transaction buffer containing this device already exists, then a second copy of the handle for the existing buffer is returned, otherwise the device is retrieved from the CDB Server and a new handle is returned. The creation date and modification date of the device are also returned if the corresponding optional parameters are supplied. If this routine returns an error condition code (other than DBSA__BADDEV) then no transaction buffer has been created and the handle is invalid. Supplying the value NULL for the optional parameters has the same effect as omitting them.

name:

The name of the device to be retrieved from the CDB Server. The name will be converted to upper case and padded with spaces to the correct length. Fixed length string descriptor passed by reference.

handle_ptr:

Returns the handle to be used in all future references to this buffer. Void pointer passed by reference.

create_date:

If supplied, returns the creation date of the device. Quadword passed by reference.

modify_date:

If supplied, returns the modification date of the device. Quadword passed by reference.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success. The caller is authorized to modify this device or template.

DBSA__READONLY:

Success. The caller is not authorized to modify this device or template.

DBSA__NODEVICE:

Error. No device with this name exists within the CDB Server.

DBSA__BADDEV:

Error. The device is not internally consistent.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $QIO system service, LIB$ dynamic memory routines, and CDB Server.

status = dbsa_report_di( di, handle_ptr [,create_date

[,modify_date] )] Same as dbsa_report_name() except that the device is specified by DI rather than by name.

di:

DI of the device to be retrieved from the CDB Server. Integer passed by value.

others:

Same as dbsa_report_name().

status = dbsa_get_data( handle [,buffer

[,length] [,ret_length] [,prop] [,attr] )] Copy the indicated property or attribute from the device in the transaction buffer into the buffer provided by the caller. All of the parameters except the handle are optional; in all cases supplying the value zero (NULL) has the same effect as omitting the parameter.

handle:

Handle of the transaction buffer containing the device we are copying. Void pointer passed by value.

buffer:

Buffer into which the property or attribute will be copied. If the property or attribute is less than one longword in length then it will be padded out (with null's) up to the size of a longword. Passed by reference (or a pointer passed by value). If this parameter is not supplied then no data will be copied.

length:

Size of buffer provided above. Integer passed by value. If this parameter is not provided then there is assumed to be enough room for the entire property or attribute.

ret_length:

Returns the actual amount of data copied into the buffer provided above. If the buffer parameter was not provided then this is the amount of data that would have been copied. Thus the caller can determine the size of the data without having to allocate a buffer for it. Integer passed by reference.

prop:

Property code of the desired property. If this parameter is not supplied then the entire device is assumed. Integer passed by value.

attr:

Attribute code of the desired attribute of the above property. If the property has no attributes then this parameter must be omitted or specified as DB_C_ATR_NONE. If the property does have attributes then this parameter must be specified. (Note that it is possible for this routine to provide an entire device, but not (in general) an entire property. This is because the offsets used to indicate the location of an attribute within a property only have meaning in the context of an entire device.) Integer passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__TRUNC:

Success. The data was too large to fit in the buffer and was truncated. The ret_length parameter will contain the actual amount of data copied.

DBSA__PROPNOEX:

Warning. The specified property is not currently present in the device. Will be returned if the property was deleted from or never added to the device.

DBSA__ATTRNOEX:

Warning. The specified attribute is not currently present in the specified property. Will be returned if the attribute was deleted from or never added to the property.

DBSA__UNDEFATTR:

Error. The specified property cannot have the specified attribute.

DBSA__NEEDATTR:

Error. No attribute (or DB_C_ATTR_NONE) was specified for a property that has attributes (see the description of the attribute parameter above.)

DBSA__HASNOATTR:

Error. An attribute code other than DB_C_ATR_NONE was specified for a property that has no attributes.

DBSA__INVPROP:

Error. The property code is undefined.

DBSA__INVATTR:

Error. The attribute code is undefined.

DBSA__INVHANDLE:

Error. The handle is invalid.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

status = dbsa_get_data_ptr( handle [,buffer

[,ret_length] [,property] [,attribute] )] Return a pointer to the indicated property or attribute of the device in the transaction buffer. The data in the transaction buffer must be treated as read-only. Any pointer returned by this routine may be rendered invalid by a call to dbsa_modify_dev() or dbsa_copy_prop(); this is due to the fact that when a device is modified the location of the properties and attributes within the device may change. All of the parameters except the handle are optional; in all cases supplying the value zero (NULL) has the same effect as omitting the parameter.

handle:

Handle of the transaction buffer containing the device we are copying. Void pointer passed by value.

buffer:

If supplied, returns a pointer to the property or attribute in the device. The data in the buffer should be treated as read-only. Pointer passed by reference (i.e., a pointer to a pointer.)

ret_length:

If supplied, returns the length of the data pointed to by the buffer parameter. Valid even if the buffer parameter is not supplied. Integer passed by reference.

property:

Property code of the desired property. If this parameter is not supplied then the entire device is assumed. Integer passed by value.

attribute:

Attribute code of the desired attribute of the above property. If the property has no attributes then this parameter must be omitted or specified as DB_C_ATR_NONE. If the property does have attributes then this parameter must be specified. (Note that it is possible for this routine to provide an entire device, but not (in general) an entire property. This is because the offsets used to indicate the location of an attribute within a property only have meaning in the context of an entire device.) Integer passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__PROPNOEX:

Warning. The specified property is not currently present in the device. Will be returned if the property was deleted from or never added to the device.

DBSA__ATTRNOEX:

Warning. The specified attribute is not currently present in the specified property. Will be returned if the attribute was deleted from or never added to the property.

DBSA__UNDEFATTR:

Error. The specified property cannot have the specified attribute.

DBSA__NEEDATTR:

Error. No attribute (or DB_C_ATTR_NONE) was specified for a property that has attributes (see the description of the attribute parameter above.)

DBSA__HASNOATTR:

Error. An attribute code other than DB_C_ATR_NONE was specified for a property that has no attributes.

DBSA__INVPROP:

Error. The property code is undefined.

DBSA__INVATTR:

Error. The attribute code is undefined.

DBSA__INVHANDLE:

Error. The handle is invalid.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

status = dbsa_cancel( handle )

Free the transaction buffer indicated by the handle. Any changes to the device since the last commit will be lost. The handle and any pointers into the buffer that were returned by dbsa_get_data_ptr() become invalid if this routine returns sucessfully. If the journal file contains a copy of the device, the device will be deleted from the journal file.

handle:

Handle of the transaction buffer we are cancelling. Void pointer passed by value. This handle will become invalid if this routine returns successfully.

status:

Returns a VMS condition code:

SS$_NORMAL

Success.

DBSA__INVHANDLE:

Error. The handle is invalid.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From LIB$FREE_VM routine.

status = dbsa_cancel_all( )

Free all of the transaction buffers. Any changes to any devices since they were committed will be lost. All handles and all pointers returned by dbsa_get_data_ptr() become invalid if this routine returns successfully.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From LIB$RESET_VM_ZONE routine.

status = dbsa_search_di( key, data [,di_list

[,count] [,keyqualifier] )] Return a list of the DI's of all the devices in the database that match the given data. The caller must specify both data and a key. The key determines which field within the device (e.g. name property, source class attribute, crate number, etc.) is compared with the specified data. If the data in the device matches the data specified then the DI of the device is included in the returned list. Some key values may be ambiguous; an optional key qualifier may be used to specify the key more precisely in these cases. The list of DI's is returned as a pointer to a buffer allocated as a static array; subsequent calls to this routine, or to dbsa_more_di(), will cause any data in the buffer to be overwritten. An optional count parameter can be used to return the number of DI's in the list, but a value of zero will always follow the last DI. If there are more DI's in the list than will fit in the buffer, then DBSA__MOREDEVICES will be returned as the status value. Dbsa_more_di() can be used to obtain the overflow. The data in the buffer must be treated as read only. Supplying the value zero (NULL) for the optional parameters has the same effect as omitting them.

key:

Determines the field within the device that is to be compared with the data (see below.) Integer passed by value. The files dbsa_rms_defs.h and dbuser.h define the following constants as legal values for this parameter:

DB_C_PRP_NAME:

Device name. The name is allowed to contain embedded wildcards (``*'' or ``%''.)

DBSA_K_CRATE_SLOT_SRC:

Addressing crate, slot and source.

data:

The data to match against the field specified by the key parameter. An array of four longwords passed by reference. The UTI will cast a pointer to this array into a pointer to the appropriate type.

di_list:

If supplied, returns a pointer to a (statically allocated) array of DI's. The array will be terminated with a zero. Since successive calls to this routine re-use the same buffer, this parameter is only required for the first call. The data in the buffer should be treated as read only. Pointer passed by reference (i.e., a pointer to a pointer.)

count:

If supplied, returns the number of DI's placed in the above array. Integer passed by reference.

keyqualifier:

If supplied, specifies the key more precisely. Integer passed by value. The file dbuser.h defines the following constants as legal values for this parameter:

DB_C_PRP_READING:

Analog reading.

DB_C_PRP_SETTING:

Analog setting.

DB_C_PRP_STATUS:

Digital reading.

DB_C_PRP_CONTROL:

Digital setting.

DB_C_PRP_READING_ALARM:

Alarm for analog reading.

DB_C_PRP_STATUS_ALARM:

Alarm for digital reading.

Note that the key qualifier parameter is applicable only when the key is specified as DBSA_K_CRATE_SLOT_SRC.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success. The list of DI's of devices matching the data has been put into the buffer. There was no overflow.

DBSA__MOREDEVICES:

Success. The entire list of DI's would have overflowed the buffer. As many as will fit have been placed in the array. The rest can be obtained by calling dbsa_more_di().

DBSA__NODEVICE:

Error. No devices matched.

DBSA__INVKEYCODE:

Error. The specified key was not recognized by the CDB Server.

DBSA__INVKEYQUAL:

Error. The specified key qualifier was not recognized by the CDB Server.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $QIO system service, and CDB Server.

status = dbsa_more_di( [di_list

[,count] )] This routine can only be called after the value DBSA__MOREDEVICES has been returned from either dbsa_search_di(), or from a previous call to this routine. It returns a list of the remaining DI's when the list generated by dbsa_search_di() overflows the buffer. The list of DI's is returned as a pointer to a buffer allocated as a static array (the same buffer that is used by dbsa_search_di()); subsequent calls to this routine, or to dbsa_search_di(), will cause any data in the buffer to be overwritten. An optional count parameter can be used to return the number of DI's in the list, but a value of zero will always follow the last DI. The count is not cumulative; it reflects only the number of DI's currently in the buffer. If there are more DI's still remaining in the list than will fit in the buffer, then this routine should be used repeatedly to obtain the overflow. Note that each time this routine is called, the previous contents of the buffer are destroyed. The data in the buffer must be treated as read only. Supplying the value zero (NULL) for the parameters has the same effect as omitting them.

di_list:

If supplied, returns a pointer to a (statically allocated) array of DI's. The array will be terminated with a zero. The buffer used to contain the array is the same buffer used by dbsa_search_di(), and successive calls to this routine will re-use the buffer. The data in the buffer should be treated as read only. Pointer to an array of integers passed by reference (i.e., a pointer to a pointer.)

count:

If supplied, returns the number of DI's returned in the above array. Integer passed by reference.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success. The remainder of the list of DI's of devices matching the data specified in the call to dbsa_search_di() has been put into the buffer. There was no overflow.

DBSA__MOREDEVICES:

Success. The remainder of the list of DI's would have overflowed the buffer. As many as will fit have been placed in the array. The rest can be obtained by calling this routine again.

DBSA__NODEVICE:

Error. Either dbsa_search_di() was never called, or the value DBSA__MOREDEVICES was not returned from the last call to this routine or from dbsa_search_di().

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $QIO system service, and CDB Server.

NOTE: The remaining routines all have the potential to affect the central database maintained by the CDB Server. Consequently they should be considered ``dangerous'' and used only by system programmers.

status = dbsa_copy_dev( handle, name, handle_ptr [,template

)] Create a copy of the transaction buffer indicated by the handle. The device in the new transaction buffer will be the same as the device in the first transaction buffer except for the name and DI properties; the name provided by the second parameter will copied into the name property of the new transaction buffer and the CDB Server will assign a new DI if and when the new device is added to the Server. By default, the new device is created as a device, as opposed to a template. The optional template parameter can be used to override the default. Specifying zero or FALSE for the template parameter has the same effect as omitting it. If this device already exists in the CDB Server, a commit will cause the old device (in the Server) to be overwritten by the new device (in the new transaction buffer). Note that in this case the template parameter has no effect: if the old device was a template, it will remain a template; if the old device was a device, it will remain a device. A handle is returned that must be used in all subsequent references to the new transaction buffer. The new device will be written to the journal file. If this routine returns an error condition code (other than DBSA__BADDEV) then no transaction buffer has been created and the handle is invalid.

handle:

Handle of the transaction buffer containing the device we are copying. Void pointer passed by value.

name:

The name to be given to the device in the new transaction buffer. The name will be converted to upper case and padded with spaces to the correct length. Fixed length string descriptor passed by reference.

handle_ptr:

Returns the handle to be used in all future references to the new buffer. Void pointer passed by reference.

template:

Specifies whether to create a device or template. Integer passed by value. The file dbsauti.h defines the following constants as legal values for this parameter:

DBSA_C_MAKE_DEVICE:

Create a device. This is the default if the template parameter is omitted.

DBSA_C_MAKE_TEMPLATE:

Create a template.

If the device already exists in the CDB Server, then this parameter has no effect.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success. A device does not already exist with this name; if a commit is done on this buffer then a new device will be created.

DBSA__WILLCLOBBER:

Warning. A device already exists with this name; if a commit is done on this buffer then an older device with this name will be overwritten.

DBSA__NOAUTH:

Error. The user is not authorized to create or modify devices.

DBSA__BADDEV:

Error. The device is not internally consistent.

DBSA__INVHANDLE:

Error. The handle is invalid.

DBSA__INVNAME:

Error. The name provided by the second parameter contains non-printing characters.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $QIO system service, LIB$ dynamic memory routines, and CDB Server.

status = dbsa_modify_dev( handle, buffer [,property

[,attribute] )]

Overwrite the property or attribute of the device in the transaction buffer with the data in the buffer supplied by the caller. If the length of the property or attribute has changed then the entire device will be repacked. It is assumed that data supplied by the caller is valid; in particular that the length field (if applicable) is correct. The property and attribute parameters are optional. In both cases supplying the value zero has the same effect as omitting the parameter. If the property parameter is omitted then the buffer parameter is assumed to point to the beginning of a DBSA_DEV structure (defined in dbsa_rms_defs.h). In this case all of the fixed length properties are copied except the name, DI and length fields. In other routines omitting the property parameter implies a request for the entire device; here it is only the fixed length part. The modified device will be written to the journal file. Note that this routine cannot be used to add a property that has attributes to a device. These properties are: reading, setting, control, status, reading alarm and setting alarm. Dbsa_copy_prop() must be used to add these properties. Also note that the application is not allowed to change the DI of a device.

handle:

Handle of the transaction buffer containing the device we are modifying. Void pointer passed by value.

buffer:

Buffer containing the new data. This data will be copied into the device, overwriting the indicated property or attribute. Passed by reference (or a pointer passed by value).

property:

Property code of the desired property. If this parameter is not supplied then the fixed length part of the device (excluding the name and DI properties) is assumed. Since only the fixed length part of the buffer is accessed in this case, the remainder need not be allocated. Integer passed by value.

attribute:

Attribute code of the desired attribute of the above property. If the property has no attributes then this parameter must be omitted or specified as DB_C_ATR_NONE. If the property does have attributes then this parameter must be specified. (Note that it is not possible to modify an entire device, or an entire property if it has attributes. This is because some properties and attributes are located by offsets that only have meaning in the context of an entire device. Therefore, these properties and attributes must be modified individually.) Integer passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__INVPROP:

Error. The property code is undefined.

DBSA__INVATTR:

Error. The attribute code is undefined.

DBSA__HASNOATTR:

Error. An attribute code other than DB_C_ATR_NONE was specified for a property that has no attributes.

DBSA__UNDEFATTR:

Error. The specified property cannot have the specified attribute.

DBSA__NEEDATTR:

Error. No attribute (or DB_C_ATTR_NONE) was specified for a property that has attributes (see the description of the attribute parameter above.)

DBSA__CANNOTCREPROP:

Error. The specified property does not exist in the device, and it is one of those listed above that cannot be added.

DBSA__NOMODDI:

Error. DB_C_PRP_DI was specified as the property code. The DI of a device cannot be changed.

DBSA__DUPNAME:

Error. The caller tried to change the name of the device to a name that is already in use.

DBSA__INVNAME:

Error. The caller tried to change the name of the device to one containing non-printing characters.

DBSA__NOAUTH:

Error. The user is not authorized to modify this device.

DBSA__BADDEV:

Error. The device is not internally consistent.

DBSA__INVHANDLE:

Error. The handle is invalid.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

status = dbsa_copy_prop( target_handle, source_handle, property [,attribute

)] Copy the indicated property or attribute from the source device into the target device. If the property or attribute already exists in the target device, it will be overwritten and the device repacked. The attribute parameter is optional; supplying the value zero has the same effect as omitting it. If the attribute is not supplied, or specified as DB_C_ATR_NONE, then the entire property is copied, including all of the attributes of the property (if any). The modified device will be written to the journal file. Special case: If the status alarm property is copied, the bitnames attribute is not copied. Instead the bitnames attribute from the status property (if it exists) in the target device is used. Note that the name and DI properties cannot be copied.

target_handle:

Handle of the transaction buffer containing the device we are modifying (the target device.) The indicated property or attribute will be copied into this device. Void pointer passed by value.

source_handle:

Handle of the transaction buffer containing the device containing the property or attribute to be copied (the source device.) This device is not modified. Void pointer passed by value.

property:

Property code of the desired property. Integer passed by value.

attribute:

Attribute code of the desired attribute of the above property. If this parameter is omitted or specified as DB_C_ATR_NONE, then the entire property is copied. Otherwise, only the specified attribute of the property is copied. If the property has no attributes then this parameter must be omitted or specified as DB_C_ATR_NONE. Integer passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__PROPNOEX:

Warning. The specified property is not currently present in the source device. Will be returned if the property was deleted from or never added to the device. Note that the corresponding property in the target device will be unchanged.

DBSA__ATTRNOEX:

Warning. The specified attribute is not currently present in the specified property of the source device. Will be returned if the attribute was deleted from or never added to the property. Note that the corresponding attribute in the target device will be unchanged.

DBSA__UNDEFATTR:

Error. The specified property cannot have the specified attribute.

DBSA__NOMODDI:

Error. The caller tried to copy the DI property.

DBSA__DUPNAME:

Error. The caller tried to copy the name property.

DBSA__HASNOATTR:

Error. An attribute code other than DB_C_ATR_NONE was specified for a property that has no attributes.

DBSA__INVPROP:

Error. The property code is undefined.

DBSA__INVATTR:

Error. The attribute code is undefined.

DBSA__NOAUTH:

Error. The user is not authorized to modify this device

DBSA__BADDEV:

Error. The modified device is not internally consistent.

DBSA__INVHANDLE:

Error. One of the handles is invalid.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

status = dbsa_delete_prop( handle, property [,attribute

)] Delete a variable length property or attribute from the device in the transaction buffer. The offset of the property or attribute is set to zero and the device is repacked. The attribute parameter is optional; supplying the value zero has the same effect as omitting it. If the attribute is not supplied, or specified as DB_C_ATR_NONE, then the entire property is deleted. Otherwise, only the specified attribute is deleted from the property. The modified device will be written to the journal file. Special case: The bitnames attribute of the status and status alarm properties is shared. Therefore, if the status property is deleted, or the bitnames attribute of the status property is deleted, then the bitnames attribute of the status alarm property will also be deleted. Directly deleting the bitnames attribute of the status alarm property has no effect, due to the way in which the device is repacked (the offset of the bitnames attribute of the status property is automatically copied into the status alarm property, thus negating the effect of deleting it.) Note that the fixed length properties and attributes cannot be deleted from a device.

handle:

Handle of the transaction buffer containing the device we are modifying. The indicated property or attribute will be deleted from this device. Void pointer passed by value.

property:

Property code of the property to delete, or the property from which we are deleting an attribute. Integer passed by value.

attribute:

Attribute code of the attribute to delete from the above property. If this parameter is omitted or specified as DB_C_ATR_NONE, then the entire property is deleted. Otherwise, only the specified attribute of the property is deleted. If the property has no attributes then this parameter must be omitted or specified as DB_C_ATR_NONE. Integer passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__PROPNOEX:

Warning. The specified property is not currently present in the device. Will be returned if the property was already deleted from or never added to the device.

DBSA__ATTRNOEX:

Warning. The specified attribute is not currently present in the specified property. Will be returned if the attribute was already deleted from or never added to the property.

DBSA__UNDEFATTR:

Error. The specified property cannot have the specified attribute.

DBSA__HASNOATTR:

Error. An attribute code other than DB_C_ATR_NONE was specified for a property that has no attributes.

DBSA__NODELPROP:

Error. The specifed property has a fixed length and cannot be deleted.

DBSA__NODELATTR:

Error. The specifed attribute has a fixed length and cannot be deleted.

DBSA__INVPROP:

Error. The property code is undefined.

DBSA__INVATTR:

Error. The attribute code is undefined.

DBSA__NOAUTH:

Error. The user is not authorized to modify this device

DBSA__BADDEV:

Error. The modified device is not internally consistent.

DBSA__INVHANDLE:

Error. One of the handles is invalid.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

status = dbsa_commit( handle )

Send the device in the transaction buffer to the CDB Server. The UTI keeps track of whether this should be a request to add, update or delete the device. Before the device is sent a sanity check is performed to make sure that the offsets and length fields of the properties and attributes are consistent and reasonable. If the device is a new device (i.e., it was created by a call to dbsa_copy_dev() ) then the DI that was assigned by the CDB Server will be copied into the alarm property DAPs and the device will be re-sent to the Server. If the commit(s) succeeds, then the device will be deleted from the journal file.

handle:

Handle of the transaction buffer containing the device we are sending. Void pointer passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NOMODIFY:

Warning. The transaction buffer was not sent to the CDB Server because there were no changes made to the device.

DBSA__NODEVICE:

Error. No device with this name exists within the CDB Server.

DBSA__NONAME:

Error. The device has not been given a name (or the length of the name is zero).

DBSA__NOAUTH:

Error. The caller is not authorized to perform the requested transaction.

DBSA__BADDEV:

Error. The device failed the sanity check.

DBSA__INVNAME:

Error. The name field of the device contains non-printing characters.

DBSA__INVHANDLE:

Error. The handle is invalid.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $QIO system service, and CDB Server.

status = dbsa_commit_all( )

Call the function dbsa_commit() for each transaction buffer that has been modified or marked for deletion. If any call to dbsa_commit() generates a status more severe than warning, then that status will returned immediately and the remaining devices (if any) will be uncommitted.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

Others:

From dbsa_commit() function.

status = dbsa_delete_dev( handle )

Mark the device in the transaction buffer for deletion. When this device is committed it will be deleted from the CDB Server. The marked device will be written to the journal file.

handle:

Handle of the transaction buffer containing the device we are deleting. Void pointer passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NOAUTH:

Error. The user is not authorized to modify this device.

DBSA__INVHANDLE:

Error. The handle is invalid.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

status = dbsa_undelete_dev( handle )

Unmark the device in the transaction buffer for deletion. If the device has been marked for deletion, but not committed then this routine will undo the effect of dbsa_delete_dev(). If the device has already been committed then the next commit will cause the device to be added to the CDB Server (however, it is likely that the Server will assign the device a new DI). The device will be written to the journal file.

handle:

Handle of the transaction buffer containing the device we are undeleting. Void pointer passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__INVHANDLE:

Error. The handle is invalid.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

status = dbsa_build( [type

)]

Send a request to the CDB Server to start a database build. The caller may optionally specify the type of build (OA or LAL). Supplying the value zero for the type parameter has the same effect as omitting it.

type:

Value specifying whether an OA build or LAL build should be started. Integer passed by value. The file dbsauti.h defines the following constants as legal values for this parameter:

DBSA_C_LAL:

Start a LAL build. This is the default if the type parameter is omitted.

DBSA_C_OA:

Start an OA build.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__UNSUPPORT:

Error. One or both of the parameters does not have a legal value.

DBSA__NOAUTH:

Error. The caller is not authorized to make a build of the requested type.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $QIO and $GETTIM system services, and CDB Server.

status = dbsa_recover_dev( handle_ptr )

Recover a single transaction buffer from an existing journal file (that is, a journal file left by a previous session). A handle is returned that must be used in all subsequent references to the recovered transaction buffer. The first time this routine is called the journal file is opened and the first device (if any) is read. Each subsequent call will cause the next device to be read until DBSA__NODEVICE is returned. At this time the journal file will be closed and deleted. If the application terminates before all of the devices have been recovered from the journal file, then the file will not be deleted and the remaining devices can be recovered at a later time. All of the recovered transaction buffers will be written to the current session's journal file until they are committed or cancelled. If this routine returns an error condition code (other than DBSA__BADDEV) then no transaction buffer has been created and the handle is invalid. Subsequent calls to dbsa_recover_dev() will return the same error code. Note that the UTI does not check to see if a transaction buffer containing a device with the same name as the recovered device already exists. It is therefore suggested that the application call this routine before calling any routine that creates or modifies a transaction buffer.

handle_ptr:

Returns the handle to be used in all future references to this buffer. Void pointer passed by reference.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NODEVICE:

Error. The journal file contains no more devices. The file will be deleted.

RMS$_FNF:

Error. No journal file from a previous session can be found.

DBSA__BADDEV:

Error. The recovered device is not internally consistent.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS RMS routines and LIB$ dynamic memory routines.

status = dbsa_mgr_fnc( code [,modifier

)]

Send a request to the CDB Server. The caller must specify the function code, and may specify the function code modifier. If the function code modifier is not specified, then DBSA_C_NONE will be used (supplying the value zero will have the same effect). See the file dbsanet.h for the legal values for the function code and modifier. Note that this routine is supplied for use by system programmers, who use it for various arcane and mysterious purposes.

code:

Function code to be sent to the CDB Server. Integer passed by value.

modifier:

Function code modifier to be sent to the CDB Server. If this parameter is not supplied then DBSA_C_NONE will be used. Integer passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NOAUTH:

Error. The caller is not authorized to make the specified request.

DBSA__NONET:

Error. The channel to the CDB Server was closed or never opened.

Others:

From VMS $QIO system service, and CDB Server.

Keywords: RDCS, EPICURE, database, CDB, CDBUTI, DBSA, DBSAUTI,

Distribution: normal