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.
- What are the plans for device class COMPOUND. The server
needs to assign DIs differently than for normal devices. Are compound
devices going to be supported in the near future.
- Presently, the DIs are not being checked for an overflow
condition. I think that the server should check for it and
respond accordingly with a status code of DBSA__DIOVF.
- Should we implement a finer method of tracking the properties
and attributes which have been modified by a particular user. The use
of masks could work quite nicely.
- Are there any devices that are presently defined which are of the
``softdevice'' class?
- Are templates added by the editor being processed correctly by the
UTI? How does the UTI know if a device or template is being passed? This
is important since templates reside in a different database.
- What about placing devices that have to deleted in another
database for historical reasons. Possibly if users re-add the device,
the same DI can be preserved.
- Is COA and AOA now DOA?
- It would be nice if the DBSA Server kept other statistics about
the database, such as averages for user interaction and device operations.
The server keeps a list that contains the users who are logged in presently,
it would be nice if the editor had a screen to display the information.
- The DBScanner should log more failure information than it does
presently. This would be helpful for diagnostic reasons.
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