Research Division EED/Controls Software<P> Design Note #105.2<P> Epicure Distributed Database System<P> DBSA Search Routine Proposal

Research Division EED/Controls Software

Design Note #105.2

Epicure Distributed Database System

DBSA Search Routine Proposal

David M. Kline

FORWARD: The section entitled ``Revisions'' lists the modifications made to the document since the last release.

Abstract

This paper contains my initial thoughts of the protocol used between applications and the DBSA Server process. Applications utilize the search function by calling the DBSA UTI routine dbsa_search_di(). The UTI uses parameters which are passed to construct a message buffer. The server receives the request and performs the search. The search is implemented by scanning the DI hash table and traversing each link in the chain of devices. The server compares the request with the data in its cache and places only the device DI property in the return buffer. When the return buffer fills, the server scans for the next device that satisfies the request. If there are no more devices, the server places the status and count of devices in the appropriate fields and returns the buffer to the application. If there are more devices, the server returns the status DBSA__MORE, the device count, and the DI hash table index to the UTI. The application can check for this condition and request additional lookups using the hndl_ptr parameter. On the next request, the UTI will pass the unmodified DI hash table index. The server will use it to start at the index in the search. Multiple request buffers are useful in the case where wildcard operations are required. The server maintains the start DI hash table index for applications when there are more than one return buffer required. The UTI will be responsible for the initial value (0) and the server will maintain the index until no more devices satisfy the condition. Another possibility is that *no* devices satisfy the conditions, in which case the server will return the status DBSA__NODEVICE. In either of the cases, the server will terminate the DI list with a zero. The server will transmit the minimum buffer size over the network. Consider the case where the UTI requests a large return buffer and the amount of devices have a much less size requirement, the server will truncate the buffer and return only what it has found. This should be more efficient by reducing the network buffer sizes.

Below describes the calling sequence and its parameters of the search routine :

status = dbsa_search_di( hndl_ptr, key_code [,key_qual
, key_data [,flags], ret_list [,ret_count])]

This routine requests that a search be performed for devices which have the key as specified by the key_data parameter.

hndl_ptr:
Either returns a handle of the transaction request or used to retrieve more devices if the return status was DBSA__MORE. Passed by reference.
key_code:
Property, attribute, or key code which specifies the data to search for. Passed by value.
key_qual:
Option parameter which qualifies the key_code parameter by directing the server to a more specific search path. Passed by value.
key_data:
Information used by the server as a key to perform the search. Passed by reference. All numeric data is passed as a longword integer whereas string data is passed as a fixed-length descriptor.
flags:
Determines the way the server will treat the data from the key_data parameter. The present implementation allows the application to specify how string data is treated. If flags is 1, the server will compare the string data directly, otherwise the server checks for the existence of the key_data. Optional parameter passed by reference.
ret_list:
Returned device DIs which have satisfied the requested search. Passed by reference.
ret_count:
Optional parameter returning the count of devices in the ret_list.

status:
Returned VMS condition code.

DBSA__SUCCESS:
Successful completion of request.
DBSA__MORE:
Successful completion however more devices may be returned.
DBSA__INVPRP:
Error. Invalid property code passed.
DBSA__INVATR:
Error. Invalid attribute code passed.
DBSA__INVKEY:
Error. Invalid key code passed.
DBSA__NONET:
Error. THe channel to the DBSA Server was closed or never opened.
DBSA__INVDSC:
Invalid fixed-length string descriptor passed.
Others:
From VMS $QIO system service, LIB$ dynamic memory routine, and DBSA server process.

Details

The key_code parameter specifies the property, attribute, or specific data that the server will be looking for. The key_qual parameter further specifies the key_code parameter. The property and attribute codes which are passed are the DB_C_PRP_* and DB_C_ATR_*. Ones which request more specific data, such as crate number, will have to be defined and placed into one of the header files. The codes which do not fit into one of the property or attribute codes may look like this: DBSA_C_KEY_CRATE, or something of the like.

There are several properties and attributes that could act as keys for searches. Here's a list of some of them:

One question in my mind is the granularity of the searching for some particular properties and attributes. For example, it would be nice to search for all devices in a particular crate. In that case, there is no direct attribute which describes this. Therefore, key codes would have to be used to specifically identify the search requirement. Another issue is the data for string descriptors. Should wildcard operations be supported in the string similarly to DCL? For example, the character ``*'' indicates a wildcard operation independent of position unless specified as right or left justified. Whereas the character ``%'' indicates a specific position in the string. Strings which are position independent are specified as ``*PS4'', ``PS4*'', ``*PS4*'', or ``*''. Whereas, strings which are position dependent are specified as ``%%PS4'', ``PS4%%'', or ``%%PS4%%''. All interpretation of these strings should be placed on the UTI as to relieve the server of the processing. The UTI would interpret the string and setup the appropriate codes for the given request type and send it to the server where the actual search would take place. By the user providing this information, the dbsa_seearch_di() routine flags parameter could be eliminated.

The network request data structure would be similar to the present implementation. A typical network message between the UTI and the server consists of a header, used by SNS, and a data portion where the UTI and server place request information and data. The message can be described generally in the following format:

The transaction request is partitioned into two areas. The request control and a pre-allocated area where the device DIs will be placed by the server which satisfy the conditions. The below data structure describes the request in general terms:

The transaction reply will return a status which identifies the condition of the request. A DBSA__SUCCESS status indicates that the operation completed successfully and there are no more devices. A status of DBSA__MORE indicates that there are more devices that satisfy the conditions and the application should execute the search routine again. The hash_index is internal to the server and shouldn't be modified by the UTI or returned to the application. The device count indicates the amount of devices in the reply. Finally, the return DI list are the device DIs represented as longword integers. Below is the proposed format of the reply buffer.

Other Issues

There are a few other issues which need to be addressed that are not necessarily associated with the search proposal but are with the database system. I listed a few of them that we need to discuss in a meeting.

Revisions

This section lists the revisions that have occurred to the document since the last release.

July 26, 1991
Initial release.
August 1, 1991
Added description of wildcard searches & provided more detailed explanation of the network message data structures.
August 14, 1991
Added more issues to ``Other Issues'' section.

Security, Privacy, Legal

rwest@fsus04.fnal.gov