|
|
All Static Database commands are designed to work against a single table. Each of the commands requires the client to fill in a data structure describing the details of the command. This information is stored in the data section of the shared region and will normally be over-written by the data resulting from the command. Since the structures contain a number of variable size (and even type) members, actual, usable definitions are left up to the client. However, some skeleton structures are available in the file SDBUSER.H along with the command ID numbers and result codes.
The first command listed is a stand-alone, one-shot type of command. Useful for getting a specific record (or set of records) with one command. When a number of records/transactions are to be performed, the use of the cursor commands (which follow) is encouraged.
Query SDB_QUERYDATA
This is a one-shot request for data. Multiple records may be retrieved by specifying a list of key values. If a key is not located, then all data retrieved up to the missing key will be returned, along with a result code specifying the condition, and the key that failed.
Field Name Data Type Description Table ID WORD from the file TABLES.H, this field determines which static data table the query will be performed against. For example, TBL_POINT. Key Field ID WORD from the file SDB-DEF.H, this field determines which column in the table contains the key to be search in this query. For example: PNT_NAME. Key Value Count WORD this is the number of key values which follow. If you need information for four points, you would place a 4 here, and then list all four point names (for example) in the Key Value list. Requested Field ID list WORDs from the file SDB-DEF.H, this list contains the ID for each field desired, in the order desired. The resultant record will contain all of the requested fields packed together in sequence. The LAST ID listed must be SDB_ENDOFLIST to signal the end of the list. Key Value list varying - the size of each entry in this list is exactly equal to the size of the field specified by the Key Field ID. These are the keys for which the query routine will be searching. String keys must be exactly the length specified for the field in SDB-DEF.H and do not require NULL terminators when the contents are exactly the same length as the field. Otherwise, you should pad the field with NULLs to ensure accurate matching.
Returns
SDB_ERR_SUCCESS all of the specified records were fetched. SDB_ERR_SEARCH at least one of the keys was not found. SDB_ERR_INVALIDTABLE the specified table ID is invalid SDB_ERR_INVALIDFIELD the specified field ID is invalid. The wAuxiliary member will be the index of the offending field. SDB_ERR_INVALIDKEY the specified field ID is invalid. SDB_ERR_NOKEYS the Key Value Count is zero. SDB_ERR_NOMEMORY insufficient memory to allocate the control buffers required to process this request. SDB_ERR_TOOMANYFIELDS the request contains more fields than the table. SDB_ERR_CANTLOCK internal error when attempting to lock the database. SDB_ERR_NOMATCH no match was found for one of the specified keys. SDB_ERR_NOTAKEY the specified key field is not a key for this table.
Database cursors are pointers into a data table which may be associated with a particular client. They allow the client to move through the records in a table according to a specified key value and to perform relative positioning along the specified key axis. A client may even keep multiple cursors into the same table using the same or different keys. Many cursor commands include a Fetch Flag. Clients should be careful to set this field to either zero or one only. In the future, this field will determine the number of records which should be returned, from zero to n, therefore clients should specifically request one record when they are coded to expect and process only one record. If your client is capable of processing from 0 to n records, then feel free to use any values, but remember, SDB will only return zero or one record at this time.
Create SDB_CURSORCREATE
Field Name Data Type Description Table ID WORD from the file TABLES.H, this field determines which static data table the query will be performed against. For example, TBL_POINT. Key Field ID WORD from the file SDB-DEF.H, this field determines which column in the table contains the key to be search in this query. For example: PNT_NAME. Requested Field ID list WORDs from the file SDB-DEF.H, this list contains the ID for each field desired, in the order desired. The resultant record will contain all of the requested fields packed together in sequence. The LAST ID listed must be SDB_ENDOFLIST to signal the end of the list.
Returns
SDB_ERR_SUCCESS a new cursor was created, the wAuxiliary member contains the cursor s ID, which must be used in all commands relating to this cursor. SDB_ERR_TOOMANYCURSORS this client already has eight cursors. SDB_ERR_INVALIDTABLE the specified table ID is invalid SDB_ERR_INVALIDFIELD the specified field ID is invalid. The wAuxiliary member will be the index of the offending field. SDB_ERR_INVALIDKEY the specified field ID is invalid. SDB_ERR_NOMEMORY insufficient memory to allocate the control buffers required to process this request. SDB_ERR_TOOMANYFIELDS the request contains more fields than the table.
Delete SDB_CURSORDELETE
Free the resources allocated for the specified cursor. SDB automatically does this when a client's region is closed. If a client wants to use more than eight cursors without creating a new region, then this command must be used to explicitly free a cursor.
Field Name Data Type Description Cursor ID WORD the value returned when the cursor was created.
Returns
SDB_ERR_SUCCESS the specified cursor no longer exists.
First SDB_CURSORFIRST
Position the cursor to the first record in the table, as defined by the cursor's key field. This command may optionally return the first record also.
Field Name Data Type Description Cursor ID WORD the value returned when the cursor was created. Fetch Flag WORD when non-zero, the first record will be returned, otherwise, the cursor is simply positioned at the first record.
Returns
SDB_ERR_SUCCESS the function succeeded. SDB_ERR_CANTLOCK an internal error occurred when attemption to lock the database. SDB_ERR_KEYFIRST an internal error occurred in the cbkeyfirst function. SDB_ERR_NORECORDS the specified table is empty SDB_ERR_WONTFIT the data retrieved will not fit in the area specified to receive it.
Next SDB_CURSORNEXT
Moves the cursor forward from zero to n records and optionally fetches the record from that position. When a record is fetched, the cursor is moved to the point following the record.
Field Name Data Type Description Cursor ID WORD the value returned when the cursor was created. Fetch Flag WORD when non-zero, the next record will be returned, otherwise, the cursor is simply positioned at the next record. Skip Count WORD the number of records to skip forward.
Returns
SDB_ERR_SUCCESS the function succeeded. SDB_ERR_CANTLOCK an internal error occurred when attemption to lock the database. SDB_ERR_KEYFIRST an internal error occurred in the cbkeyfirst function. SDB_ERR_KEYFIRST an internal error occurred in the cbkeynext function. SDB_ERR_NONEXT there is no record following the current record. SDB_ERR_WONTFIT the data retrieved will not fit in the area specified to receive it.
Last SDB_CURSORLAST
Position the cursor to the last record in the table, as defined by the cursor's key field. This command may optionally return the last record also.
Field Name Data Type Description Cursor ID WORD the value returned when the cursor was created. Fetch Flag WORD when non-zero, the last record will be returned, otherwise, the cursor is simply positioned at the last record.
Returns
SDB_ERR_SUCCESS the function succeeded. SDB_ERR_CANTLOCK an internal error occurred when attemption to lock the database. SDB_ERR_KEYFIRST an internal error occurred in the cbkeylast function. SDB_ERR_NORECORDS the specified table is empty. SDB_ERR_WONTFIT the data retrieved will not fit in the area specified to receive it.
Previous SDB_CURSORPREVIOUS
Moves the cursor backward from zero to n records and optionally fetches the record from that position. When a record is fetched, the cursor is moved to the point following the record.
Field Name Data Type Description Cursor ID WORD the value returned when the cursor was created. Fetch Flag WORD when non-zero, the previous record will be returned, otherwise, the cursor is simply positioned at the previous record. Skip Count WORD the number of records to skip backward.
Returns
SDB_ERR_SUCCESS the function succeeded. SDB_ERR_CANTLOCK an internal error occurred when attemption to lock the database. SDB_ERR_KEYFIRST an internal error occurred in the cbkeyfirst function. SDB_ERR_KEYFIRST an internal error occurred in the cbkeyprev function. SDB_ERR_NOPREVIOUS there is no record previous to the current record. SDB_ERR_WONTFIT the data retrieved will not fit in the area specified to receive it.
Locate SDB_CURSORLOCATE
Attempts to position the cursor at the record defined by the specified key value. If a non-exact match is located (and allowed) then the cursor is positioned there. When a record is fetched, the cursor is moved to the point following the record. If a locate command fails, then the current cursor position should be considered undefined.
Field Name Data Type Description Cursor ID WORD the value returned when the cursor was created. Fetch Flag WORD when non-zero, the matching record will be returned, otherwise, the cursor is simply positioned at the matching record. Exact Flag WORD when TRUE, the key located must match the key specified exactly (except for case), otherwise, the next larger key value may be considered a match. Key Value varies by Key Field ID the key value which is to be located. The exact size and data type of this field is determined by the key for which the specified cursor was created.
Returns
SDB_ERR_SUCCESS the function succeeded. SDB_ERR_CANTLOCK an internal error occurred when attemption to lock the database. SDB_ERR_NOEXACTMATCH an exact match was requested, but none was found. SDB_ERR_SEARCH there was an internal error in the function cbkeysrch SDB_ERR_WONTFIT the data retrieved will not fit in the area specified to receive it.
Goto SDB_CURSORGOTO
This function is not currently implemented.
Field Name Data Type Description Cursor ID WORD the value returned when the cursor was created. Fetch Flag WORD when non-zero, the first record will be returned, otherwise, the cursor is simply positioned at the first record. Target Record Number WORD index number of the target record, as counted from zero along the current key.
Returns
SDB_ERR_SUCCESS the function succeeded.
|
|