Research Division EED/Controls Software

Design Note #112.6

Epicure Distributed Database System

DB Report Server/UTI Specification

David M. Kline

Contents

• Contents
• Revisions
• Introduction
• Report Server
  • Message Format
  • Search Key List
  • Return Data List
  • Return Data Format
  • Search Keys & Data
  • Statistics/Accumulators
  • User Login List
• User Task Interface
• Example Application: Acquiring device data
• Example Application: Device updates

Revisions

V112.0

April 30, 1992 - Initial release.

V112.1

May 12, 1992 - Incorporated suggestions from RD EED/Controls group members.

V112.2

June 10, 1992 - Modified UTI routines calling sequences.

V112.3

June 25, 1992 - DB report UTI V1.0 completed.

V112.4

July 22, 1992 - Modified document to reflect the implementation more accurately.

V112.5

August 7, 1992 - Combined routines and tuned UTI.

V112.6

February 3, 1993 - Modified document to reflect requested changes.

Introduction

Report Server

Client applications request searches by using the UTI to build a list of search keys. Search keys are a subset of device properties and attributes available from the central database . They represent properties, attributes, or components of attributes. Attribute components are individual fields which make up a device attribute and are represented as mnemonics. Search data may be specified individually or as a list of either values or fixed length strings, thus allowing clients to specify a complex search criteria.

The data returned, by default, is a list of device DIs that have satisfied the search criteria. Client applications can specify a return data list and the order of the data. The data returned is limited to the return data codes supported by the UTI and are a subset of the possible properties & attributes that may be assigned to a device. The number of devices returned is dependent on the return data size. The report server places as many devices as possible into a return buffer. Since the report server can only return so many devices in a return buffer, the client application must interact iteratively with the report server. Later sections describe the process.

The report server communicates with the UTI & client applications by using the Epicure sns_ routines. The UTI uses non-transparent DECnet to establish communication between client applications and the report server. And uses the $QIO() system service to queue I/O request packets to the network software driver to communicate search requests.

In order to access data efficiently, the report server implements a memory cache and uses the VMS paging subsystem to reference device data. The cache consists only of the search keys supported by the report server, thus reducing the memory requirements and increasing access performance. The cache is organized as an array with DIs in ascending order. At initialization, the report server determines the size of the cache and compensates for additions, thus keeping memory pages close together and reducing any overhead associated with memory expansion.

Other functions are supported by the report server to maintain a consistent view of device property and attribute information. Whenever the central database is modified , the report server receives a message to modify the cache. The report server uses a binary search algorithm to locate the device and modify its contents.

The report server maintains other data that may be of interest to clients. Averages and accumulators are maintained and can be acquired using the dbrpt_get_status_ptr() UTI routine. In addition, a list of users who are logged in and information about them is maintained and can be acquired by the dbrpt_get_login_ptr() UTI routine. The ``statistics'' & ``user task interface'' sections describe these routines and their calling sequences.

A file is used to log any errors that the report server may encounter while executing search requests and other VMS related exceptions . The log file contains messages for a given day and a new one is created every night. Before a new log file is created, final statistic & accumulative values are written that can be reviewed for analysis and audits.

Message Format

Figure 2 represents the details of the SNS data management/server control portion of the message packet. The data management area contains information needed by SNS to communicate with client applications. The server control area contains fields that provide a means to access the search key and return data lists. The ``offset to search key list'' & ``offset to return data list'' fields contain values that are used to locate the lists by adding them to the beginning pointer of the message packet. The calculated pointers access search criteria and identify the return data. The last cache index field allows the report server to continue searching the cache for devices which satisfy the search criteria.

Initially, the last cache index field is set to zero. When the report server is ready to send data back to the client application, the field is set to the next cache element index. The client application can then send a request to continue the search given the search criteria. The report server uses the field as a point of reference into the cache. This process continues as long as the client application sends the message packet to the report server with the correct field value. The format of the packet is described below:

Both search and return data lists are composed of message and data packets. The packets have been organized similarly and aligned on longword boundaries to efficiently increment through memory pages.

Search Key List

The search key is composed of a search data list that contains the search criteria. The list is used to compare and determine whether the search criteria has been satisfied. It is organized as a linked list using offsets to connect the individual data elements. The data list format is presented in figure 4:

Return Data List

Return Data Format

The last_cache_index is used internally by the UTI to direct the report server to begin searching at the point which it left off. The count value is the number of devices returned and is place in the ret_data parameters as specified by the UTI routines.

Search Keys & Data

Some search keys are components of device attributes and require a unique mnemonic to identify them (i.e. crate/slot). The table below lists both attributes and attribute components that can be selected:

The application must specify a property code that directs the search across multiple or individual properties. The table below lists the valid property mnemonics:

If the application wants more than just the device device index returned, a list of return data codes must be specified. The table below lists the valid return data codes:

Typically the client application specifies the search key and a list of data that the report server will use to search through the cache. When multiple search keys are specified, the report server requires that all search keys match the given device. However, the device may satisfy any of the search key data. Therefore, the report server ANDs the search keys for whatever data was specified. For example, the name search key data may be specified as ``M00*'' & ``N00*''. Any device which begins with a M00 OR N00 satisfies the condition. When individual property codes are specified, the report server ORs between them. If the search key ``crate'' was specified for both the reading or status property codes, the report server would return devices which satisfy the crate data for either property code. In the case where the property code DBRPT_C_PRP_ALL is specified, the report server will AND the data across every property.

After the client has specified the search key(s) and return data list, the appropriate UTI routine is executed to send the list to the report server. Message operations will be described in later sections.

Statistics/Accumulators

Startup time

- This is the time the report server started.

Server state

- Indicates the state of the server. Possible states are: DBRPT__BUSY, DBRPT__IDLE, & DBRPT__OPTWAIT.

Actual device count

- The number of devices that are presently in the cache. Initially, the count is acquired when the cache is initializing using the dbsa_ UTI routines. As device additions & deletions are made, the count will adjust accordingly.

Cache device count

- This count is the maximum number of devices that can be held in the cache.

Total logins

- This counter keeps track of how many client applications have logged in since server startup.

Current logins

- This counter indicates the number of client applications that are currently logged in.

Rating value

- Value that indicates the server eligibility for client log ons. The rating value is calculated using the machine type and the value of current_logins.

Maximum search time

- This is the maximum time it took for the report server to search through the cache (per request) in 100mS intervals.

Minimum search time

- This is the minimum time it took for the report server to search through the cache (per request) in 100mS intervals.

Node name

- Node name that the report server is running on. The data is a NULL terminated text string.

Command freq

- This indicates the frequency of the different types of commands that the report server has executed since startup.

Uptime

- This indicates the number of days, hours, minutes, & seconds the report server has been running.

Request counts

- This value indicates the number of times a search key was requested.

The return statistics data format is described in figure 7:

A feature of the UTI routines is that it can be set up to return data only once or at specified intervals. Refer to the ``User Task Interface'' section for more details.

User Login List

Node

- The current node name. Same information as in the statistics data.

Login count

- Number of currently logged in.

Login list

- List of information about users.

The user information contained in the login list is as follows:

Tcid

- Task connection identification. The is used by the Epicure sns_ services to maintain network connections.

Login time

- The time the user logged into the report server.

User name

- Name of user.

Node name

- Node name of where the client is from.

The login data formats are described in figure 8:

A feature of the UTI routines is that it can be set up to return data only once or at specified intervals. Refer to the ``User Task Interface'' section for more details.

User Task Interface

The UTI provides a set of routines that allows the client application to build and manage the search key and return data lists. The client application specifies the search keys and its data. The UTI enters them into an internal list. Similarly, return data is specified and the UTI enters the information into the return data list of the message packet. When the client application is finished specifying the search keys and return data, it will execute one of the dbrpt_process_*() routines that send a search request packet to the report server. The UTI will either wait until the report server replies or execute an AST routine that was specified by the client application.

In order to service multiple clients efficiently, the UTI and report server perform a handshake operation. The UTI sends a message packet to the report server which searches its cache for matching criteria. The report server returns to the client application as many devices as it can given the limitation of the network buffer size and which return data was specified. Since there are probably more devices that satisfy the criteria, the report server returns a status code that indicates that more devices can be returned. The client application sends the message packet back to the report server and it picks up where it left off. The report server returns a status code indicating that it has finished searching the cache. The client application must interact with the report server this way in order to retrieve all devices that satisfy the specified search criteria. A worst case scenario is for the report server to traverse the entire cache. Bench marks have proved that on a VAX-3XXX class machine, it takes on average 3.786 seconds.

The routines described in this section are not part of EPICURELIB presently. Refer to the section Example Program for directions on how to use the user task interface. The remainder of this section describes the calling sequences of the UTI routines.

status = dbrpt_connect( [efn

[,ast ,astprm])]

The routine executes a load balancing algorithm that places the client on the optimal report server. Each report server maintains a rating given the number of users logged in and the CPU type. The rating is updated every 500mS. The routine scans every report server for the rating and determines which report server to attach to. All remaining channels are deassigned. The completion of the load balancing is signaled by the efn parameter or the routine specified by the ast parameter.

efn:

Event flag to set when load balancing is complete. Optional unsigned shortword passed by value.

ast:

AST routine executed when load balancing is complete. Optional parameter passed by reference.

astprm:

Parameter passed to AST routine when. If this parameter is present, ast parameter must be specified. Optional unsigned longword passed by value.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__NET:

Success. Connection established.

DBRPT__OPTWAIT:

Warning. Indicates load balancing is still is progress.

DBRPT__NOLOGIN:

Fatal. Maximum logins exceeded.

Others:

From the VMS system services or DECnet.

status = dbrpt_disconnect()

This routine deallocates all buffers used to manage search request lists and deassigns the channel to the report server. No parameters are required.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__NONET:

Error. The channel to the server was closed or never opened.

DBRPT__ACTIVE:

Warning. Function can not be executed because of request list state.

Others:

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

status = dbrpt_initialize_list( total_search_keys)

This routine initializes the search request list. The application must call this routine before any search key setup or process routine. Additionally, it must be called after completion of a previously setup search request list. If the application is retrieving all devices, the total_search_keys parameter should be set to zero.

total_search_keys:

Anticipated number of search keys and property code combinations in the request list. Unsigned longword passed by value.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__NONET:

Error. The channel to the server was closed or never opened.

DBRPT__ACTIVE:

Warning. Function can not be executed because of request list state.

Others:

From VMS LIB$ dynamic memory routines.

status = dbrpt_add_key_data( handle, key_code, prp_code, key_data, length)

This routine adds data to a search key. Multiple calls to this routine using the same key & property code combination modifies any previous call. The number of search keys is limited by the application virtual page count, network buffer size, & the parameter passed to the dbrpt_initialize_list() routine.

handle:

Value associated with search key. Unsigned longword passed by reference.

key_code:

Search key code value. Unsigned shortword passed by value.

prp_code:

Property key code value. Unsigned shortword passed by value.

key_data:

Array of data elements used as search criteria. The code implies specific data type. For example, DBRPT_C_KEY_CLASS assumes an array of unsigned bytes, whereas DBRPT_C_KEY_NAME implies an array of fixed-length NULL terminated strings. Search key datatypes and sizes are defined in the include file epicure_inc:dbrptuti.h. Passed by reference.

length:

Length of key_data in bytes. Unsigned shortword passed by value.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__INVKEY:

Error. Invalid key passed.

DBRPT__INVLEN:

Error. Invalid data length passed.

DBRPT__INVPRP:

Error. Invalid property passed.

DBRPT__NOHNDL:

Error. No handle passed.

DBRPT__NODATA:

Error. No data passed.

Others:

From VMS LIB$ dynamic memory and internal UTI routines.

status = dbrpt_cancel_key( handle)

This routine removes a search key and compresses the internal memory where it resided. The handle is set to a zero (NULL) value.

handle:

Value associated with search key. Unsigned longword passed by reference.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__INVHNDL:

Error. Invalid handle passed.

DBRPT__NOHNDL:

Error. No handle passed.

DBRPT__NOKEY:

Error. Key has not been setup.

Others:

From VMS LIB$ dynamic memory and internal UTI routines.

status = dbrpt_get_all_devices( count, ret_data [,length

[,time])]

This routine retrieves all devices in the cache. It provides the most efficient method of returning information about all devices in the central database. If a return data list was not specified, only device DIs are returned.

count:

Number of devices returned. Unsigned shortword passed by reference.

ret_data:

Address pointer of return data. Passed by reference.

length:

Length of ret_data in bytes. Optional unsigned longword passed by reference.

time:

Retrieval time in 100mS intervals. Optional unsigned longword passed by reference.

status:

VMS condition code returned as a longword.

DBRPT__FINISHED:

Success. Device information complete.

DBRPT__MORE:

Success. Device information has returned successfully however more device are possibly available.

DBRPT__SUCCESS:

Successful completion of request.

DBRPT__INVARG:

Error. Invalid arguments passed.

DBRPT__NOARG:

Error. No arguments passed.

DBRPT__NODEVICES:

Error. No devices found.

DBRPT__NONET:

Error. The channel to the report server was closed or never opened.

DBRPT__CRASH:

Fatal. Server is crashing due to fatal error.

Others:

From VMS $QIO system service, LIB$ dynamic memory routine, and report server process.

status = dbrpt_get_more_all_devices( count, ret_data [,length

[,time])]

This routine works in conjunction with the dbrpt_get_all_devices() routine to continue retrieving all devices in the cache. It provides the most efficient method of returning information about all devices in the central database. If return data was not specified, only device DIs are returned.

count:

Number of devices returned. Unsigned shortword passed by reference.

ret_data:

Address pointer of return data. Passed by reference.

length:

Length of ret_data in bytes. Optional unsigned longword passed by reference.

time:

Retrieval time in 100mS intervals. Optional unsigned longword passed by reference.

status:

VMS condition code returned as a longword.

DBRPT__FINISHED:

Success. Device information complete.

DBRPT__MORE:

Success. Device information has returned successfully however more device are possibly available.

DBRPT__SUCCESS:

Successful completion of request.

DBRPT__INVARG:

Error. Invalid arguments passed.

DBRPT__NOARG:

Error. No arguments passed.

DBRPT__NODEVICES:

Error. No devices found.

DBRPT__NONET:

Error. The channel to the report server was closed or never opened.

DBRPT__CRASH:

Fatal. Server is crashing due to fatal error.

Others:

From VMS $QIO system service, LIB$ dynamic memory routine, and report server process.

status = dbrpt_process_wait( count, data [,length

[,time])]

This routine sends the search request to the server for processing. The routine will not return until a reply has been received from the report server.

count:

Number of devices returned. Unsigned shortword passed by reference.

data:

Address pointer of return data. Passed by reference.

length:

Size of return data in bytes. Optional unsigned longword passed by reference.

time:

Retrieval time in 100mS intervals. Optional unsigned longword passed by reference.

status:

VMS condition code returned as a longword.

DBRPT__FINISHED:

Success. Device information complete.

DBRPT__MORE:

Success. Device information has returned successfully however more devices are possibly available.

DBRPT__INVARG:

Error. Invalid argument passed.

DBRPT__NOARG:

Error. No arguments passed.

DBRPT__NONET:

Error. The channel to the report server was closed or never opened.

DBRPT__CRASH:

Fatal. Server is crashing due to fatal error.

Others:

From VMS $QIO system service, LIB$ dynamic memory routine, and report server process.

status = dbrpt_get_more_wait( count, data [,length

[,time])]

This routine can be called only if the status code DBRPT__MORE was returned after the call of the dbrpt_process_wait() or a previous call of this routine.

count:

Number of devices returned. Unsigned shortword passed by reference.

data:

Address pointer of return data. Passed by reference.

length:

Size of return data in bytes. Optional unsigned longword passed by reference.

time:

Retrieval time in 100mS intervals. Optional unsigned longword passed by reference.

status:

VMS condition code returned as a longword.

DBRPT__FINISHED:

Success. Device information complete.

DBRPT__MORE:

Success. Device information has returned successfully however more are available.

DBRPT__SUCCESS:

Successful completion of request.

DBRPT__INVARG:

Error. Invalid argument passed.

DBRPT__NOARG:

Error. No arguments passed.

DBRPT__NONET:

Error. The channel to the report server was closed or never opened.

DBRPT__CRASH:

Fatal. Server is crashing due to fatal error.

Others:

From VMS $QIO system service, LIB$ dynamic memory routine, and report server process.

status = dbrpt_process_nowait( [efn

[,ast ,astprm])]

This routine sends the search request to the server for processing and returns immediately. Data arrival is signaled either by setting an event flag as specified by the efn parameter or executing the routine specified by the ast parameter. The efn and ast parameters are optional but one or the other must be specified. Passing a zero (NULL) value is equivalent to omitting the parameter.

efn:

Event flag number set when data returns. Optional unsigned shortword passed by value.

ast:

AST routine executed when data returns. Optional parameter passed by reference.

astprm:

Parameter passed to AST routine when data returns. If this parameter is present, ast parameter must be specified. Optional unsigned longword passed by value.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__ACTIVE:

Warning. Function can not be executed because of request list state.

DBRPT__INVARG:

Error. Invalid arguments passed.

DBRPT__NOARG:

Error. No arguments passed.

DBRPT__NOLIST:

Error. No request list present.

DBRPT__NONET:

Error. The channel to the report server was closed or never opened.

DBRPT__CRASH:

Fatal. Server is crashing due to fatal error.

Others:

From VMS LIB$ dynamic memory and internal UTI routines.

status = dbrpt_get_more_nowait( [efn

[,ast ,astprm])]

This routine can be called only if the status code DBRPT__MORE was returned after the call of the dbrpt_process_nowait() or a previous call of this routine. Data arrival is signaled either by setting an event flag as specified by the efn parameter or executing the routine specified by the ast parameter. The efn and ast parameters are optional but one or the other must be specified. Passing a zero (NULL) value is equivalent to omitting the parameter.

efn:

Event flag number set when data returns. Optional unsigned shortword passed by value.

ast:

AST routine executed when data returns. Optional parameter passed by reference.

astprm:

Parameter passed to AST routine when executed. If this parameter is present, ast parameter must be specified. Optional unsigned longword passed by value.

status:

VMS condition code returned as a longword.

DBRPT__FINISHED:

Success. Device information complete.

DBRPT__MORE:

Success. Device information has returned successfully however more are available.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__ACTIVE:

Warning. Function can not be executed because of request list state.

DBRPT__INVARG:

Error. Invalid arguments passed.

DBRPT__NOARG:

Error. No arguments passed.

DBRPT__NODATA:

Error. No reply message allocated.

DBRPT__NOLIST:

Error. No request list present.

DBRPT__CRASH:

Fatal. Server is crashing due to fatal error.

Others:

From VMS LIB$ dynamic memory and internal UTI routines.

status = dbrpt_add_reqdata( ret_code, length [,rec_size

)]

This routine requests specific data returned from the report server. If the routine is not called, only device DIs are returned.

ret_code:

Array of shortwords containing requested return data. Passed by reference.

length:

Length of ret_code in bytes. Unsigned shortword passed by value.

rec_size:

Return record length in bytes. Unsigned longword passed by reference.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__INVLEN:

Error. Invalid length passed.

DBRPT__INVRETDAT:

Error. Invalid return data code passed.

Others:

From VMS LIB$ dynamic memory and internal UTI routines.

status = dbrpt_get_reqdata( count, ret_data [,length

[,time])]

This routine retrieves the count and copies the data returned by the report server. These values should be read only after successful completion of the *_nowait() UTI routines.

count:

Number of devices returned. Unsigned shortword passed by reference.

ret_data:

Address pointer of return data. Passed by reference.

length:

Length of ret_data in bytes. Optional unsigned longword passed by reference.

time:

Retrieval time in 100mS intervals. Optional unsigned longword passed by reference.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__NOARG:

Error. No arguments passed.

Others:

From internal UTI routines.

status = dbrpt_get_reqdata_ptr( count, ret_data [,length

[,time])]

This routine retrieves the count and the pointer to the data returned by the report server. These values should be read only after successful completion of the *_nowait() UTI routines.

count:

Number of devices returned. Unsigned shortword passed by reference.

ret_data:

Address pointer of return data. Passed by reference.

length:

Length of ret_data in bytes. Unsigned longword passed by reference.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__NOARG:

Error. No arguments passed.

Others:

From internal UTI routines.

status = dbrpt_cancel_reqdata()

This routines clears the return data list and initializes it to return device DI's only.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

Others:

From VMS LIB$ dynamic memory and internal UTI routines.

status = dbrpt_get_login_ptr( ctl, repcnt, stsref, login_data [,efn

[,ast ,astprm])]

The routine requests user login information from the report server as specified by the ctl parameter. The repcnt parameter specifies the interval at which the data will be returned. If the parameter is zero, the data is returned immediately and once. If the parameter is a positive non-zero value, the data is returned at the interval specified (i.e. 2 is two seconds). The stsref parameter is the location of the completion status, reference counter, and the node that has returned its data. Return data is signaled by either efn, or ast parameters. The astprm parameter is a value which is passed to the routine specified by the ast parameter. The efn and ast parameters are optional but one or the other must be specified. Passing a zero (NULL) value is equivalent to omitting the parameter. It is not required to execute the routine dbrpt_connect(), all network connections are maintained separately from search requests. Therefore, search requests and login data may be acquired simultaneously.

ctl:

This parameter controls where the data will be acquired. Presently there are two valid symbols: DBRPT_C_USE_LOGICAL & DBRPT_C_USE_DATAFILE. The first tells the routine to connect to all report servers as specified by the connection logical. The logical may reside in either the process or system name tables. The routine will search the process name table first then the system. The other specifies to use the logical that points to a data file that contains a list of all VAX nodes running report servers. Unsigned shortword passed by value.

repcnt:

Repeat count. Unsigned longword passed by value.

stsref:

Address of pointer to the status/reference data structure. Passed by reference.

login_data:

Returns a pointer to a list of user logged in. Passed by reference.

efn:

Event flag number to set when data returns. Optional unsigned shortword 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. If this parameter is present, ast parameter must be specified. Optional unsigned longword passed by value.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Successful completion of request.

DBRPT__INVARG:

Error. Invalid arguments passed.

DBRPT__NOARG:

Error. No arguments passed.

DBRPT__NOAUTH:

Error. Not authorized to execute routine.

Others:

From internal UTI routines.

status = dbrpt_cancel_repeat_login()

This routine cancels the repeat read set up by the dbrpt_get_login_ptr() and must be called to stop acquiring data from the report server.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__NOAUTH:

Error. Not authorized to execute routine.

Others:

From VMS $QIO and internal UTI routines.

status = dbrpt_get_status_ptr( ctl, repcnt, stsref, stat_data [,efn

[,ast ,astprm])]

The routine requests status information from the report server as specified by the ctl parameter. The repcnt parameter specifies the interval at which the data will be returned. If the parameter is zero, the data is returned immediately and once. If the parameter is a positive non-zero value, the data is returned at the interval specified (i.e. 2 is two seconds). The stsref parameter is the location of the completion status, reference counter, and the node that has returned its data. Return data is signaled by either efn, or ast parameters. The astprm parameter is a value which is passed to the routine specified by the ast parameter. The efn and ast parameters are optional but one or the other must be specified. Passing a zero (NULL) value is equivalent to omitting the parameter. It is not required to execute the routine dbrpt_connect(), all network connections are maintained separately from search requests. Therefore, search requests and status data may be acquired simultaneously.

ctl:

This parameter controls where the data will be acquired. Presently there are two valid symbols: DBRPT_C_USE_LOGICAL & DBRPT_C_USE_DATAFILE. The first tells the routine to connect to all report servers as specified by the connection logical. The logical may reside in either the process or system name tables. The routine will search the process name table first then the system. The other specifies to use the logical that points to a data file that contains a list of all VAX nodes running report servers. Unsigned shortword passed by value.

repcnt:

Repeat count. Unsigned longword passed by value.

stsref:

Address of pointer to the status/reference data structure. Passed by reference.

stat_data:

Returns a pointer to a list of statistics. Passed by reference.

efn:

Event flag number to set when data returns. Optional unsigned shortword 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. If this parameter is present, ast parameter must be specified. Optional unsigned longword passed by value.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Successful completion of request.

DBRPT__INVARG:

Error. Invalid arguments passed.

DBRPT__NOARG:

Error. No arguments passed.

DBRPT__NOAUTH:

Error. Not authorized to execute routine.

Others:

From internal UTI routines.

status = dbrpt_cancel_repeat_status()

This routine cancels the repeat read set up by the dbrpt_get_status_ptr() and must be called to stop acquiring data from the report server.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Success. Function completed successfully.

DBRPT__NOAUTH:

Error. Not authorized to execute routine.

Others:

From VMS $QIO and internal UTI routines.

status = dbrpt_get_state()

This routine returns the current state of the UTI

status:

VMS condition code returned as a longword.

DBRPT__BUSY:

Informational. UTI is processing search request.

DBRPT__IDLE:

Informational. UTI ready for next request.

DBRPT__OPTWAIT:

Warning. UTI load balancing in progress.

usage = dbrpt_get_memory_usage()

This routine returns the dynamic memory usage of the UTI.

usage:

Value indicates number of bytes used by the UTI to build search request lists and other internal data areas.

status = dbrpt_update_cache( function, device_data, [,ast ,astprm

)]

A privileged routine that is used to update the report server cache. It sends the command specified by the function parameter and the data to all report servers. Client applications that want to use this routine require the resource identifier DBRPT__ACCESS and may request it from the Epicure system management group.

function:

Function server is to execute. Unsigned shortword passed by value.

device_data:

Device update data record. Passed by reference.

ast:

AST routine to execute when complete. Optional parameter passed by reference.

astprm:

Parameter passed to AST routine when data returns. If this parameter is present, ast parameter must be specified. Optional unsigned longword passed by value.

status:

VMS condition code returned as a longword.

DBRPT__SUCCESS:

Successful completion of request.

DBRPT__INVARG:

Error. Invalid arguments passed.

DBRPT__NOAUTH:

Error. Not authorized to execute routine.

Others:

From VMS $QIO system service, LIB$ dynamic memory routine, and report server process.

The ast routine is passed two parameters, the one specified by astprm and a pointer to an array of node status. The node status is defined by the data structure ``struct DBRPT_NODE_DATA'' as declared in the header file epicure_inc:dbrptuti.h. The node status array consists of the completion status & the name of the node. The array is terminated by the status equal to zero. See the section ``Examples Application: Device updates'' for implementation details.

Example Application: Acquiring device data

   $ CC/DEBUG/NOOPT DEMO
   $ LINK /DEBUG DEMO,-
     EPICURE_ROOT:[WORK.DBRPT.RELEASES]DBRPTUTI/LIBRARY,-
     RDCS$LIB:EPICURELINK/OPT

/*
 * Fermi National Accelerator
 * Research Division/EED Controls
 * Epicure Control System
 *
 * This application retrieves devices which names begin
 * which M00*. The program instructs the report server
 * to return the name, template type, and DAP type
 * properties.
 *
 * Author: David M. Kline			21-Jul-92
 *
 */

/*
 Include files:
*/
#include stdio
#include ssdef
#include descrip
#include descrip2

#include "epicure_inc:dbrptuti.h"
#include "epicure_inc:dbrptmsg.h"

#define EXIT_ON_ERROR(s) {if((s&1)==0)sys$exit(s);}
#define CHECK_STATUS(s) {if((s&1)==0)lib$signal(s);}

unsigned short return_data[] = {
                                 DBRPT_C_RET_NAME,
                                 DBRPT_C_RET_TEMPLATE_TYPE,
                                 DBRPT_C_RET_DAP_TYPE
                                };
unsigned char names[][DB_S_NAME+1] = {
                                     "M00*"
                                     };

float seconds;
unsigned long sts;
unsigned long handle = 0;
unsigned short count;

struct {
       unsigned long di;
       unsigned char name[DBRPT_S_RET_NAME];
       unsigned char tpl[DBRPT_S_RET_TEMPLATE_TYPE];
       unsigned long dap_type;
       } (*data)[];

void ret_data();

/********************
 * Main entry point *
 ********************/
main()
{
sts = dbrpt_connect( 2);

sys$waitfr( 2);

sts = dbrpt_initialize_list( 5);

sts = dbrpt_add_key_data( &handle, DBRPT_C_KEY_NAME, DBRPT_C_PRP_NONE, names, sizeof(names));

sts = dbrpt_add_reqdata( return_data, sizeof(return_data));

sts = dbrpt_process_nowait( 2, ret_data, 0);

sts = sys$hiber();

sts = dbrpt_disconnect();

printf( "Returned %d devices in %f seconds\n", count, seconds);
}

void ret_data( unsigned long PRM)
{
unsigned long idx;
unsigned long idx1;
unsigned long sts;
unsigned long time;

/*
 Get data
*/
sts = dbrpt_get_reqdata_ptr( &count, &data, 0, &time);

seconds = (float)time/10;

/*
 Finished?
*/
if ( sts == DBRPT__FINISHED)
    {
    for ( idx=0; idx<count; ++idx)
        {
        printf( "%x %s %s %d\n",
                (*data)[idx].di,
                (*data)[idx].name,
                (*data)[idx].tpl,
                (*data)[idx].dap_type
              );
        }

    printf( "Last of data!\n");
    sys$wake( 0, 0);
    return;
    }

/*
 More?
*/
if ( sts == DBRPT__MORE)
    {
    for ( idx=0; idx<count; ++idx)
        {
        printf( "%x %s %s %d\n",
                (*data)[idx].di,
                (*data)[idx].name,
                (*data)[idx].tpl,
                (*data)[idx].dap_type
              );
        }

    /*
     Get more data
    */
    sts = dbrpt_get_more_nowait( 2, ret_data, 0);
    return;
    }

/*
 Errors?
*/
if ( (sts & 1) == 0)
    {
    printf( "Errors present!\n");
    sys$exit( sts);
    }
}

Example Application: Device updates

/*
 * Fermi National Accelerator
 * Research Division/EED Controls
 * Epicure Control System
 *
 * This application is an example to request
 * updates to the report server cache. The application
 * requests data from the central database, modifies
 * the 'beamline' property, then sends the request
 * to the report server. Mainly, the example is used
 * to illustrate the parameters that are passed to the
 * 'ret_ast()' routine. In particular, the 'node_status'.
 *
 * Author: David M. Kline                       01-Feb-1993
 *
 */

/*
 Include files:
*/
#include stdio
#include ssdef
#include descrip
#include descrip2

#include "epicure_inc:dbrptuti.h"

void ret_ast();
unsigned long di;
unsigned long sts;
unsigned long idx;
char device_data[5000];
struct DB_BEAMLINES *beams;
struct DBSA_DEV *device_record = device_data;

/********************
 * Main entry point *
 ********************/
main()
{
sts = dbsa_connect_to_server();
if ( (sts&1) == 0)
    sys$exit( sts);

di = 4225823;
sts = dbsa_report( di, device_record);
if ( (sts&1) == 0)
    sys$exit( sts);

dbsa_disconnect_from_server();

beams = (char *)device_record + device_record->beamlines;
strncpy( &beams->beamlines[0], "UPD1", 4);

sts = dbrpt_update_cache( DBRPT_C_UPD_MOD, device_record, ret_ast, 3);
if ( (sts&1) == 0)
    sys$exit( sts);

sys$hiber();
}

void ret_ast( unsigned long prm, struct DBRPT_NODE_DATA (*node_status)[])
{
static unsigned short len;
static unsigned char msg[256];
static struct dsc$descriptor msg_dsc = { sizeof( msg)-1, DSC$K_DTYPE_T, DSC$K_CLASS_S, msg};

printf( "AST ROUTINE - %d\n", prm);
for ( idx=0; (*node_status)[idx].status != 0; ++idx)
    {
    sys$getmsg( (*node_status)[idx].status, &len, &msg_dsc, 0, 0);

    printf( "%2.2d  %8.8s   %*.*s\n", idx, (*node_status)[idx].name, len, len, msg);
    }

sys$wake( 0, 0);
}

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

Distribution: normal