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.
- 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.