Research Division EED/Controls Software<P> Design Note #113.0<P> Epicure Distributed Database System<P> DB Scanner Server<P> User Task Interface

Research Division EED/Controls Software

Design Note #113.0

Epicure Distributed Database System

DB Scanner Server

User Task Interface

David M. Kline

Contents

Revisions

V113.0
May 11, 1992 - Initial release.

Introduction

This document describes the DB Scanner Server User Task Interface (UTI). The DB Scanner Server is a VAX-based process that is responsible for monitoring the DB server processes. Periodically, it monitors both the Optimized Access (OA) and Look Aside List (LAL) section database serial numbers for consistency between DB server processes and the master version. In addition to this function, it is responsible for distributing the OA & LAL section databases to remote destinations. The DB scanner maintains a list that contains the node names which OA and LAL databases are distributed and monitored. The list is generated by reading a configuration file containing the node names .

When a database distribution begins, the DB scanner places the destination name in the distribution list. After completion, remote destinations acknowledge by sending a message and it removes the name from the list. Similarly, when a DB server process has an inconsistent database, its node name is placed in the OA or LAL error list, depending on the type of database. Information contained in these lists can be retrieved by using the dbscn_get_list() UTI routine. The DB scanner can be set up to return this information on a periodic basis. The freq parameter is used to specify the return rate in 10 millisecond intervals. A minimum of 200 or 2 seconds is allowed.

The User Task Interface (UTI) is responsible for establishing communication to the DB scanner process and managing requests made by an application. The logical RDCS$DBSCN_CONNECTION_NODES resides in the system logical table and provides a search list of nodes where a DB scanner is expected to be running. The UTI provides a set of routines that allows an application to send commands to remote DB servers, send OA & LAL section databases, set up operating parameters, interrogate server status, and retrieve list data.

User Task Interface Routines

This section describes the routines available to applications to communicate with the DB Scanner Server. Applications that want to use these routines need to include the header file ``dbscnuti.h''. All routines return a VMS condition code. Communication with the scanner is by synchronous and asynchronous I/O. Optional parameters are enclosed in brackets [ ].

status = dbscn_connect()

Opens a communication channel to the DB Scanner Server (DBSCN). When a connection is established, in addition to opening a channel, the UTI initializes data structures that will be used to construct request messages. No parameters are required.

status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_disconnect()
This routine releases all dynamic memory used to manage request messages and deassigns the channel to the scanner. No parameters are required.

status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_send_dest_db( db_type [,name_list
[,final_status] [,efn] [,ast] [,astprm])]

This requests that an OA or LAL section database be distributed to either a specific node, destination, or all destinations. The application will be notified when the distribution has completed either by the efn, or ast and astprm parameters. Passing a zero (NULL) value is equivalent to omitting the parameter.

db_type:
Value indicating database type. Passed by value.

DBSCN_C_OA:
OA section database.
DBSCN_C_LAL:
LAL section database.
name_list:
List of nodes or destinations to send a database. If parameter is absent, distribution will occur on all destinations. Optional parameter passed by reference.
final_status:
Status of the request. Applications can poll this parameter to test if data has arrived. Optional parameter passed by reference.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__INVDEST:
Error. Invalid destination.
DBSCN__NORSP:
Error. No response from remote destinations.
DBSCN__TMOEX:
Error. Destination response timeout exceeded.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from scanner.
DBSCN__UNSUPPORTED:
Error. Unsupported request from scanner.
DBSCN__INPROG:
Informational. Request in progress.
DBSCN__NOTALL:
Warning. No all destinations received a database.
Others:
From VMS $QIO system service and server process.
efn:
Event flag to set when data returns. Optional parameter passed by value.
ast:
AST routine to execute when data returns. Optional parameter passed by reference.
astprm:
Parameter passed to AST routine when data returns. Optional parameter passed by value.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request send.
DBSCN__INVTYPE:
Error. Invalid type specified.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_send_dbsrv_remap( [name_list
[,final_status] [,efn] [,ast] [,astprm])]

This routine requests that the scanner send a message to the specified DB server processes to remap the look-aside-list (LAL). When all DB servers have reported back to the scanner, the application will be signaled by either the efn, or ast and astprm parameters. Passing a zero (NULL) value is equivalent to omitting the parameter.

name_list:
List of nodes or destinations to send the remap command. If parameter is absent, all DB server processes are sent the command. Optional parameter passed by reference.
final_status:
Status of the request. Applications can poll this parameter to test if data has arrived. Optional parameter passed by reference.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__INVDEST:
Error. Invalid destination.
DBSCN__NORSP:
Error. No response from remote destinations.
DBSCN__TMOEX:
Error. Destination response timeout exceeded.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from scanner.
DBSCN__UNSUPPORTED:
Error. Unsupported request from scanner.
DBSCN__INPROG:
Informational. Request in progress.
DBSCN__NOTALL:
Warning. No all destinations received a database.
Others:
From VMS $QIO system service and server process.
efn:
Event flag to set when data returns. Optional parameter passed by value.
ast:
AST routine to execute when data returns. Optional parameter passed by reference.
astprm:
Parameter passed to AST routine when data returns. Optional parameter passed by value.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request sent.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_send_dbsrv_restart( [name_list
[,final_status] [,efn] [,ast] [,astprm])]

This routine requests that the scanner send a message to the specified nodes to restart the DB server processes. Restarting the DB server will update any OA or LAL databases that are present. When all DB servers have reported back to the scanner, the application will be signaled by either the efn, or ast and astprm parameters. Passing a zero (NULL) value is equivalent to omitting the parameter.

name_list:
List of nodes or destinations to send the restart command. If parameter is absent, all DB server processes are sent the command. Optional parameter passed by reference.
final_status:
Status of the request. Applications can poll this parameter to test if data has arrived. Optional parameter passed by reference.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__INVDEST:
Error. Invalid destination.
DBSCN__NORSP:
Error. No response from remote destinations.
DBSCN__TMOEX:
Error. Destination response timeout exceeded.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from scanner.
DBSCN__UNSUPPORTED:
Error. Unsupported request from scanner.
DBSCN__INPROG:
Informational. Request in progress.
DBSCN__NOTALL:
Warning. No all destinations received a database.
Others:
From VMS $QIO system service and server process.
efn:
Event flag to set when complete. Optional parameter passed by value.
ast:
AST routine to execute when complete. Optional parameter passed by reference.
astprm:
Parameter passed to AST routine when complete. Optional parameter passed by value.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request sent.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_set_db_dir( directory_name)

This routine requests the scanner redirect the location of the master OA and LAL section databases. The routine will wait until the request has been executed by the scanner.

directory_name:
A fixed-length string descriptor of the directory the OA and LAL section databases are located. Passed by reference.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__INVDSC:
Error. Invalid descriptor.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_set_monitor_off()

This routine requests that the DB server processes not be monitored.

status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_set_monitor_on()

This routine requests that the DB server processes be monitored.

status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_set_process_rundown()

This routine requests the scanner terminate itself. The scanner will gracefully exit by closing all open files and links, write a conclusion message to the log file, and call the sys$exit() system service. If any exit handlers have been declared, they are executed at this time.

status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_set_dist_done( db_type, dest_name)

This routine is used by applications on remote nodes to signal completion of an OA or LAL distribution. The scanner removes the name supplied by the dest_name parameter from the distribution list.

the scanner to remove the destination name from its destination list.

db_type:
Value indicating database type. Passed by value.

DBSCN_C_OA:
OA section database.
DBSCN_C_LAL:
LAL section database.
dest_name:
A fixed-length string descriptor of the destination name. Passed by reference.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__INVTYPE:
Error. Invalid type specified.
DBSCN__INVDEST:
Error. Invalid destination.
DBSCN__INVDSC:
Error. Invalid descriptor.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_set_list_clr( list_type)

This routine requests the scanner clear the contents from the list specified by the list_type parameter.

list _type:
Value indicating list type. Passed by value.

DBSCN_C_OA:
OA error list.
DBSCN_C_LAL:
LAL error list.
DBSCN_C_DIST:
Distribution list.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NOTEMPTY:
Successful. List not empty.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__INVTYPE:
Error. Invalid type specified.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_set_monitor_rate( rate)

This routine requests the scanner monitoring rate be altered.

rate:
A fixed-length string descriptor of the monitoring rate. Passed by reference.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__INVDSC:
Error. Invalid descriptor.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_set_list_size( size)

This routine requests the OA, LAL, & distribution lists size be set as specified by the size parameter.

size:
Request size of the lists. Passed by value.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__INVDSC:
Error. Invalid descriptor.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_set_destinations()

This routine requests the DB scanner read the monitor and OA/LAL destination lists from the configuration file. This routine should be called after any modification to the configuration file. No parameters are required.

status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NOAUTH:
Error. Not authorized to execute request.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_get_status( status_data [,freq
[,final_status] [,efn] [,ast] [,astprm])]

This routine requests status information from the scanner. The routine returns immediately and return data is signaled either by the efn, or ast and astprm parameters. The freq parameter specifies a rate for periodic updates. This is useful for applications that want to receive status updates for displays. Passing a zero (NULL) value is equivalent to omitting the parameter.

status_data:
Return the address of the pointer to the status data area. The pointer will remain a zero value until data arrives. Passed by reference.
freq:
A longword specifying a periodic update data return rate in 10 millisecond intervals . If parameter is absent, the data is returned immediately and only once. Optional parameter passed by reference.
final_status:
Status of the request. Applications can poll this parameter to test if data has arrived. Optional parameter passed by reference.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NORSP:
Error. No response from remote destinations.
DBSCN__TMOEX:
Error. Destination response timeout exceeded.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from scanner.
DBSCN__INPROG:
Informational. Request in progress.
Others:
From VMS $QIO system service and server process.
efn:
Event flag to set when data returns. Optional parameter passed by value.
ast:
AST routine to execute when data returns. Optional parameter passed by reference.
astprm:
Parameter passed to AST routine when data returns. Optional parameter passed by value.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request sent.
DBSCN__INVFREQ:
Error. Invalid frequency specified.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_get_versions( [OA_version
[,LAL_version])]

This routine requests that the scanner remap the OA and LAL section databases to obtain new serial numbers. The new serial numbers will be returned if one of the optional parameters are provided. This is useful after executing the dbscn_set_db_dir() routine.

OA_version:
New version returned after mapping. Optional parameter passed by reference.
LAL_version:
New version returned after mapping. Optional parameter passed by reference.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_get_db_dir( directory_name)

This requests the scanner return the current directory of the master OA and LAL section databases.

directory_name:
A fixed-length string descriptor of the directory the OA and LAL section databases are located. Passed by reference.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__INVDSC:
Error. Invalid descriptor.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_get_list( list_type, list_data [,freq
[,final_status] [,efn] [,ast] [,astprm])]

This routine requests the scanner return the contents of the list as specified by the list_type parameter. The node names contained in the list provide information depending on the context.

list_type:
Value indicating list type. Passed by value.

DBSCN_C_OA:
OA error list.
DBSCN_C_LAL:
LAL error list.
DBSCN_C_DEST:
Destination list.
DBSCN_C_DIST:
Distribution list.
list_data:
Return the address of the pointer to the list. The pointer will remain a zero value until data arrives. Passed by reference.
freq:
A longword specifying a periodic update data return rate in 10 millisecond intervals . If parameter is absent, the data is returned immediately and only once. Optional parameter passed by reference.
final_status:
Status of the request. Applications can poll this parameter to test if data has arrived. Optional parameter passed by reference.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NORSP:
Error. No response from remote destinations.
DBSCN__TMOEX:
Error. Destination response timeout exceeded.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from scanner.
DBSCN__INPROG:
Informational. Request in progress.
Others:
From VMS $QIO system service and server process.
efn:
Event flag to set when data returns. Optional parameter passed by value.
ast:
AST routine to execute when data returns. Optional parameter passed by reference.
astprm:
Parameter passed to AST routine when data returns. Optional parameter passed by value.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__INVTYPE:
Error. Invalid type specified.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
DBSCN__UNSUPPORTED:
Error. Unsupported request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

status = dbscn_get_logins( login_data [,freq
[,final_status] [,efn] [,ast] [,astprm])]

This routine requests the current logins from the scanner. The routine returns immediately and return data is signaled either by the efn, or ast and astprm parameters. The freq parameter specifies a rate for periodic updates. This is useful for applications which want to receive status updates for displays. Passing a zero (NULL) value is equivalent to omitting the parameter.

login_data:
Return the address of the pointer to the login data area. The pointer will remain a zero value until data arrives. Passed by reference.
freq:
A longword specifying a periodic update data return rate in 10 millisecond intervals . If parameter is absent, the data is returned immediately and only once. Optional parameter passed by reference.
final_status:
Status of the request. Applications can poll this parameter to test if data has arrived. Optional parameter passed by reference.

DBSCN__SUCCESS:
Successful. Request complete.
DBSCN__NORSP:
Error. No response from remote destinations.
DBSCN__TMOEX:
Error. Destination response timeout exceeded.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from scanner.
DBSCN__INPROG:
Informational. Request in progress.
Others:
From VMS $QIO system service and server process.
efn:
Event flag to set when data returns. Optional parameter passed by value.
ast:
AST routine to execute when data returns. Optional parameter passed by reference.
astprm:
Parameter passed to AST routine when data returns. Optional parameter passed by value.
status:
Returned VMS condition code.

DBSCN__SUCCESS:
Successful. Request sent.
DBSCN__INVFREQ:
Error. Invalid frequency specified.
DBSCN__NONET:
Error. The communication channel was closed or never opened.
DBSCN__UNIMPLEMENTED:
Error. Unimplemented request from UTI.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and server process.

Keywords: Epicure, controls, RDCS, database, EDDS, DBSA, DBSCN, EDBS

Distribution: normal

Security, Privacy, Legal

rwest@fsus04.fnal.gov