EPICURE Design Note 99.2

DB Serial Access Server (DBSA)

User Task Interface

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

Fri Mar 29 09:18:07 CST 1996

This document describes the DBSA Server (DB Serial Access Server) UTI (User Task Interface). The DBSA Server is a server process which receives database transaction requests from other applications and executes them on the RMS databases on behalf of the requestor. The reader should refer to EPICURE design note 95.x for a description of the RMS databases. The UTI described here provides a simple interface to the DBSA Server. Services provided include:

• Setting up and maintaining a channel to the DBSA Server on whatever node it is running;
• Sending and receiving messages to and from the DBSA 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).

The term device will be used to refer to both devices and templates unless the context implies otherwise. Note that the DBSA Server may restrict the operations that a particular user may perform. In particular, authorization to modify templates will be severely restricted, if allowed at all.

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 additional data needed by the UTI. Transaction buffers are created in two ways: when the application makes a request to retrieve a device, and when the application asks to make a copy of an existing transaction buffer. When a transaction buffer is created the application is given a handle for the buffer; this handle must be used 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.

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 DBSA 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 deleted from the DBSA Server when a commit request is made. The application may also request that the DBSA Server execute a build (currently the application can only request an immediate LAL build).

If the DECnet channel to the DBSA 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 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 Server will not necessarily be on the same node as the old one.

The UTI maintains a journal file of modified devices. Whenever a transaction buffer is created or modified a copy of the buffer is placed in the journal file. The buffer will be deleted from the file when it is successfully committed or canceled. If the application terminates unexpectedly, the user may use the journal file to recover any modified, but uncommitted, devices he may have been editing. The file will be located in sys$login:dbsauti.jnl, and will be deleted if the user disconnects normally. Note that the journal 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 -- after that 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'':

• If the DBSA 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.
• Any pointers into 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.
• 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.
• The UTI is not AST reentrant. Applications use the UTI at AST level 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.

All of the DBSA UTI interface routines return a VMS condition code. Communication with the DBSA Server process is done via synchronous I/O. The routines described here will be part of epicurelib, but will not be described or made available to general users. The header file defining these routines is dbsauti.h. The header files defining the format of the RMS records for the devices are dbsa_rms_defs.h, dbuser.h and daps.h. Optional arguments are enclosed in [ ].

status = dbsa_request_session( )

Open a channel to the DBSA Server. The logical RDCS$DBSA_SERVER_NODE in the system logical name table is expected to define search list of nodes on which a server might be running. A connection is made to the first node running a server. 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 DBSA 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__NONET:

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

Others:

From assorted VMS system service and LIB$ routines.

status = dbsa_disconnect_session( )

Disconnect from the DBSA 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. 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 DBSA 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 DBSA Server. See the file dbsanet.h for the contents and definition of the structure. 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 structure containing the statistics. Passed by reference (i.e a pointer to a pointer).

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NONET:

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

Others:

From VMS $QIO system service and DBSA Server.

status = dbsa_name_to_di( name, di )

Return the DI of a device given its name. This routine queries the DBSA Server directly; therefore the DI returned by this routine will not reflect any changes that may be in uncommitted buffers.

name:

Fixed length string descriptor of the name of the device. Passed by reference.

di:

Returns the DI of the device named above. Passed by reference.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NONET:

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

DBSA__NODEVICE:

Error. No device exists with the given name.

Others:

From VMS $QIO system service and DBSA Server.

status = dbsa_di_to_name( di, name )

Return the name of a device given its DI. This routine queries the DBSA Server directly; therefore the name returned by this routine will not reflect any changes that may be in uncommitted buffers.

di:

The DI of a device. Passed by value.

name:

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

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NONET:

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

DBSA__NODEVICE:

Error. No device exists with the given DI.

Others:

From VMS $QIO system service and DBSA Server.

status = dbsa_report_name( name, handle_ptr )

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 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 DBSA Server and a new handle is returned. If this routine returns an error condition code (other than DBSA__BADDEV) then no transaction buffer has been created and the handle is invalid.

name:

Fixed length string descriptor of the name of the device to be retrieved from the DBSA Server. Passed by reference.

handle_ptr:

Returns the handle to be used in all future references to this buffer. Longword 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__NONET:

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

DBSA__NODEVICE:

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

DBSA__BADDEV:

Error. The device is not internally consistent.

Others:

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

status = dbsa_report_di( di, handle_ptr )

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 DBSA Server. Passed by value.

handle_ptr:

Returns the handle to be used in all future references to this buffer. Longword 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__NONET:

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

DBSA__NODEVICE:

Error. No device with this DI exists within the DBSA Server.

DBSA__BADDEV:

Error. The device is not internally consistent.

Others:

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

status = dbsa_copy_dev( handle, name, handle_ptr )

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 argument will copied into the name property of the new transaction buffer and the DBSA Server will assign a new DI if and when the new device is added to the server. A handle is returned that must be used in all subsequent references to the new transaction buffer. If this device already exists in the DBSA Server, a commit will cause the old device (in the server) to be overwritten by the new device (in the new transaction buffer). The UTI will keep a copy of the new device in the journal file until it is 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.

handle:

Handle of the transaction buffer containing the device we are copying. Passed by value.

name:

Fixed length string descriptor of the name to be given to the device in the new transaction buffer. Passed by reference.

handle_ptr:

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

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__NONET:

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

DBSA__INVHANDLE:

Error. The handle is invalid.

DBSA__BADDEV:

Error. The device is not internally consistent.

Others:

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

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 arguments except the handle are optional; in all cases supplying the value zero (NULL) has the same effect as omitting the argument.

handle:

Handle of the transaction buffer containing the device we are copying. 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 nul's) up to the size of a longword. Passed by reference (or a pointer passed by value). If this argument is not supplied then no data will be copied.

length:

Size of buffer provided above. Passed by value. If this argument 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 argument 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. Longword passed by reference.

prop:

Property code of the desired property. If this argument is not supplied then the entire device is assumed. Passed by value.

attr:

Attribute code of the desired attribute of the above property. If the property has no attributes then this argument must be omitted or specified as DB_C_ATR_NONE. If the property does have attributes then this argument 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.) 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 argument will contain the actual amount of data copied.

DBSA__NODATA:

Warning. The specified property/attribute is defined for this device but the data area in the record is empty (length zero).

DBSA__INVPROP:

Error. The property code is undefined.

DBSA__INVATTR:

Error. The property specified does not have the specified attribute, or the attribute code is undefined. Also returned if the property specified has attributes and no attribute was specified.

DBSA__NONET:

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

DBSA__INVHANDLE:

Error. The handle is invalid.

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(); 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 arguments except the handle are optional; in all cases supplying the value zero (NULL) has the same effect as omitting the argument.

handle:

Handle of the transaction buffer containing the device we are copying. Passed by value.

buffer:

Returns a pointer to the property or attribute in the device. The data pointed to should be treated as read-only. Passed by reference (i.e. a pointer to a pointer). If this argument is not supplied then no attempt will be made to return the pointer.

ret_length:

Returns the length of the data pointed to by the buffer argument. Valid even if the buffer argument is not supplied. Longword passed by reference.

property:

Property code of the desired property. If this argument is not supplied then the entire device is assumed. Passed by value.

attribute:

Attribute code of the desired attribute of the above property. If the property has no attributes then this argument must be omitted or specified as DB_C_ATR_NONE. If the property does have attributes then this argument 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.) Passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NODATA:

Warning. The specified property/attribute is defined for this device but the data area in the record is empty (length zero).

DBSA__INVPROP:

Error. The property code is undefined.

DBSA__INVATTR:

Error. The property specified does not have the specified attribute, or the attribute code is undefined. Also returned if the property specified has attributes and no attribute was specified.

DBSA__NONET:

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

DBSA__INVHANDLE:

Error. The handle is invalid.

status = dbsa_modify_dev( handle, buffer [,property

[,attribute] )]

Overwrite the property and 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 any) is correct. The property and attribute arguments are optional. In both cases supplying the value zero has the same effect as omitting the argument. If the property argument is omitted then the buffer argument as assumed to point to the beginning of a device structure (struct DBSA_DEV, 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 argument 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 the UTI forbids the application from adding a property or attribute to a device. ``Adding'' a property is defined as attempting to modify a property or attribute that does not exist or exists but has length zero. 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. 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 argument 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, the remainder need not exist. Passed by value.

attribute:

Attribute code of the desired attribute of the above property. If the property has no attributes then this argument must be omitted or specified as DB_C_ATR_NONE. If the property does have attributes then this argument must be specified. Passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NOAUTH:

Error. The user is not authorized to modify devices.

DBSA__INVPROP:

Error. The property code is undefined or the device does not have specified property (or it has length zero). Also returned if the DI property was specified.

DBSA__INVATTR:

Error. The property specified does not have the specified attribute, (or it has length zero) or the attribute code is undefined. Also returned if the property specified has attributes and no attribute was specified.

DBSA__NONET:

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

DBSA__INVHANDLE:

Error. The handle is invalid.

DBSA__DUPNAME:

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

DBSA__BADDEV:

Error. The device is not internally consistent.

status = dbsa_commit( handle )

Send the device in the transaction buffer to the DBSA 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 commit succeeds, then the device will be deleted from the journal file.

handle:

Handle of the transaction buffer containing the device we are sending. Passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NOMODIFY:

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

DBSA__NONET:

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

DBSA__INVHANDLE:

Error. The handle is invalid.

DBSA__NONAME:

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

DBSA__BADDEV:

Error. The device failed the sanity check.

DBSA__NOAUTH:

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

DBSA__NODEVICE:

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

Others:

From VMS $QIO system service, and DBSA 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 DBSA Server. The marked device will be written to the journal file.

handle:

Handle of the transaction buffer containing the device we are deleting. Passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NOAUTH:

Error. The user is not authorized to modify devices.

DBSA__NONET:

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

DBSA__INVHANDLE:

Error. The handle is invalid.

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 DBSA 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. Passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NONET:

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

DBSA__INVHANDLE:

Error. The handle is invalid.

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 returned by dbsa_get_data_ptr() become invalid after this routine is called. If the journal file contains a copy of the device, it will be deleted.

handle:

Handle of the transaction buffer we are cancelling. Passed by value.

status:

Returns a VMS condition code:

SS$_NORMAL

Success.

DBSA__NONET:

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

DBSA__INVHANDLE:

Error. The handle is invalid.

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 after this routine is called. The journal file will emptied if the routine succeeds.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NONET:

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

Others:

From LIB$RESET_VM_ZONE routine.

status = dbsa_build( [type

[,time] )]

Send a request to the DBSA Server to start a database build. The caller may specify the time of the build as well as the type of build (OA or LAL). The time and type arguments are optional. In both cases supplying the value zero has the same effect as omitting the argument.

NOTE: Currently, (Fri Mar 29 09:18:07 CST 1996 ), the time parameter is not supported

type:

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

DBSA_C_RQLALBLD:

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

DBSA_C_RQOABLD:

Start an OA build.

time:

Value specifying the time the build is to be started. Passed by value. The file dbsauti.h defines the following constants as legal values for this parameter:

DBSA_C_BLD_NOW:

Start the build immediately. This is the default if the time argument is omitted.

DBSA_C_BLD_1ST:

Start the build within the first shift.

DBSA_C_BLD_2ND:

Start the build within the second shift.

DBSA_C_BLD_3RD:

Start the build within the third shift.

DBSA_C_BLD_B4OA:

Start the build when convenient, but before the scheduled nightly 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__NONET:

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

DBSA__NOAUTH:

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

Others:

From VMS $QIO and $GETTIM system services, and DBSA 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.

handle_ptr:

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

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

RMS$_FNF:

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

DBSA__NODEVICE:

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

DBSA__NONET:

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

DBSA__BADDEV:

Error. The recovered device is not internally consistent.

Others:

From VMS RMS routines and LIB$ dynamic memory routines.

status = dbsa_mgr_fnc( code [,modifier

)]

Send a request to the DBSA 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.

code:

Function code to be sent to the Server. Passed by value.

modifier:

Function code modifier to be sent to the Server. If this argument is not supplied then DBSA_C_NONE will be used. Passed by value.

status:

Returns a VMS condition code:

DBSA__SUCCESS:

Success.

DBSA__NONET:

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

DBSA__NOAUTH:

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

Others:

From VMS $QIO system service, and DBSA Server.

Keywords: Epicure, program, database, DBSA, DBSAUTI, editor, OA, LAL, RMS

Distribution: normal