Kevin Yacoben
January 7, 1997

The APPDS Library Routines
The Application Data Storage (APPDS) Library Routines is a set of "C" function calls designed to be used in conjunction with APPDS data tables. Through the APPDS library routines user applications can:

• Set table interaction parameters
• Add, Update record(s)
• Retrieve record(s)
• Delete record(s)
• Set and retrieve an APPDS database connection information

APPDS Table Interaction
One of the major feature of the APPDS facility is the users ability to address APPDS tables in three different formats: Sequential, Indexed and Keyed. Further more, the facility allows APPDS tables to be set as Read Only or Read Writable. This functionality is what is referred to as an APPDS tables interaction mode. Every APPDS table has a default interaction mode which is set via the APPDS Manager. The interaction mode for an APPDS table is defined by the following table parameters:

• Access mode, [Sequential,Indexed,Keyed]
• Read/Write mode, [Read Only, Read & Write]
• Overwrite, [Yes, No]
• Table Lock, [Enabled, Disabled]

The Access Mode parameter defines how the tables is referenced. For a table which has an access mode of Sequential data records are referenced in a linear fashion starting from a given point an continuing toward the last record in the table. When a table has an access mode of Indexed data records are referenced by record IDs. Lastly, table that have Keyd access are referenced by a data key value. The key value of a tables record structure is the first element in the structure. Further more when the first element of a records structure is an array Keyed access is not allowed. The Read/Write Mode parameter defines whether a tables data records can only be read or read and written. For tables which are access by Indexed mode the Overwrite parameter is used to define if existing record data can be overwritten, for more information refer to section Index Write. The last parameter, Table Lock, allows the user to inhibit applications from overriding a tables default interaction mode.

When an APPDS table is first accessed by any of the APPDS library routines its default interaction mode information is read into working memory. To retrieve a tables interaction data the APPDS routine appds_get_inter_mode can be used. If the table specified in the appds_get_inter_mode call has not been referenced before, the default interaction mode is retrieved, otherwise the data in working memory is returned. A call to appds_get_inter_mode returns an APPDS_TABLE_INFO structure that describes the interaction mode and the store record format. The following is information found in the APPDS_TABLE_INFO structure:

• Lock status
• Lock owner, if any
• Overwrite
• Access mode
• Read/Write mode
• Retry wait timeout in seconds
• Maximum record count limit
• Record size in bytes
• Record element count
• An array of record element information structures (APPDS_DATA_INFO)

• Data type
• Data lenght
• Element count

Table Status
For any APPDS table an user application can retrieve table status information through the appds_get_table_status library routine. This routine returns the following table information:

• Last record ID
• Record count
• Last access date
• Last access date logging status

Key Match Count
On any APPDS table a user appliction can determine the number of records that match a given key. This feature is provided through the appds_key_match_count routine. For parameter information about appds_key_match_count refer to the appds_key_match_count entries in the CLIB Function Description online help.

Retrieving Record Data
The APPDS facility provides data record retrieval for all access modes through one routine, appds_read_record. Record selection is based on the current interaction mode for the table and the parameters passed to the routine. The routine places all retrieved data into the user supplied buffer along with the number of records retrieved. For each type of access mode the routine retrieves data records differently. For parameter information refer to the appds_read_record entry in the CLIB Function Description online help.

Sequential Read
For tables that have their access mode set to Sequential the appds_read_record routine retrieves records in a sequential fashion that is based on the order that the records were written. In this mode the routine starts retrieving records from a given location until the number of records requested has been met or the last record has been read. To perform this operation the routine uses the notion of a read/write pointer. The read/write pointer always points to the last record referenced, with the next record to be read being the record following the read/write pointer. Initially the pointer is set to the top of the table, before the first record in the table.

Shown below, Figure 1.0, is an example of a table that is set for sequential access which has its read/write pointer set to the top of the table. If an appds_read_record request for one record is issued on this table the routine would retrieve and return the data for "record A" and move the read/write pointer so that it points to "Record A". If another request is made for another record, then the data for "Record B" is return and the pointer is advanced. However, if the user wishes to again retrieve the data for "Record D" the data for "Record C" must first be read. Once the data for the last record is retrieved, in the example that is "Record D", the next call to the appds_read_record routine must be passed a non-NULL value for the select_value parameters so that the read/write pointer is returned to the top of the table. Also once are record has been read and the read/write pointer has been advanced the only way to re-read that record is to reset the read/write pointer and start reading from the top again.

Indexed Read
To retrieve specific record from an APPDS table the appds_read_record routine can be called with the access mode of the table set to Index. When a call is made to the routine the user can pass an array of record IDs for each record to retrieve. Record IDs are positional record references references; e.g. Record ID 1 is the first record in the table.

The record IDs specified in the array passed by the user can be in any order. However, the appds_read_record routine will sort the record data in ascendingending order based on record ID before it is returned. It should also be noted that if the your specifies record IDs that reference record which do not contain data, NULL data will be returned. Unlike sequential reads, Indexed reads are not bound to the position of the read/writer pointer. However, the read/write pointer will be set to the last record accessed.

Example:
In Figure 1.1 the user passed to the appds_read_record routine a array with records IDs [1,3,4,2,5] and on return from that call the user buffer contains: "Record A" "Record B" "NULL Data" "NULL Data" "Record C"

Keyed Read
For APPDS tables that have their access mode set to Keyed the appds_read_record routine retrieves records based on a key values. The APPDS facility interprets the first element of a records structure to be the key. When multiple records are returned the routine will sort the return records in ascending order using record IDs. Like Indexed read Keyed reads are not bound to the read/write pointer, however, the read/write pointer is set to the last record accessed.

Example:
In Figure 1.2 passes to the appds_read_record routine to select records that have a key value of "123". Based on the key value the routine places the data from "Record A" and "Record C" into the user buffer.

Writing Record Data
The writing of APPDS table data is performed through the appds_write_record library routine. This routine supports two types of record writing, ADD and UPDATE. An ADD write implies that new records are going to be inserted to the table, where as, an UPDATE will replace existing data records. Furthermore, the appds_write_routine uses the current access mode for the APPDS table to determine how ADDs and UPDATEs are to be performed.

As part of the calling sequence the user specifies if the requested record write is an ADD or an UPDATE. This is also referred to as the "write type" for the routine call. For parameter information refer to the appds_write_record entry in the CLIB Function Description online help.

Sequential Write
When a tables current access mode is set to Sequential the appds_write_record routine appends record data when the requested write type is ADD. After the new records are added to the table the routine set to the read/write pointer to the top of the table.

In Figure 2.0 is an example of what an APPDS table looks like before and after a call has been made to appds_write_record to ADD new records. In the example the appds_write_record adds the two records from the user buffer to the APPDS table.

When an UPDATE request is made the routine writes the data based on the location of the read/write pointer. The routine uses the read/write pointer for the location of the first record to update and the next record in the sequence for multiple record updates. After updating the routine set the read/write pointer to the record following the last updated record.

An example of a Sequential UPDATE is shown in figure 2.1. In this example the read/write pointer is pointing to "Record B" before the update, which will be the first record updated. After the update the contents of "Record B" and "Record C" have been replaced with the data from the user buffer and the read/write pointer now points to "Record D". When updating a table Sequentially caution should be taken so the number of records to be updated is not greater than the number of records available to update. For instance, using the figure 2.2, if after the update another request is made to update two more records, the request would fail. The reason the request fails is that there is only one record available to be updated "Record D". In this situation the appds_write_record would return an APPDS_READEND error since the routine would attempt to update the record following "Record D", which does not exist.

Indexed Write
To write record data to a specific record location in an APPDS table the appds_write_record can be called with the access mode for the table set to Indexed. Like an appds_read_record call the user specifies were record data is to be written through the use of record IDs. To ADD or UPDATE a single record the user needs to pass the routine the record ID for the record to modify. When processing multiple records the appds_write_record routine uses the given record ID as the location of the first record to modify with the others following sequentially. Also when ADDing record data a NULL value can be passed to the routine to indicate that all new records be added starting after the last record in that table that contains data.

When ADDing record(s) to a table there is a potential to overwrite existing data records. To control record overwriting during ADDs the appds_write_record routine uses the OVERWRITE setting from the tables interaction mode. If overwriting is allowed the routine will perform as an UPDATE. And when overwriting is not allowed the routine will only modify record IDs that do not contain any data and return an error if they do. Upon completion of the write operation the read/write pointer for the table is set to the top.

Shown below in figure2.2 is an example of a call to the appds_write_record routine requesting that two record be UPDATED, starting with record ID two. In the example before the UPDATE the table has data in record ID 2 and is empty in the next record, record ID 3. After the UPDATE request the contents of record IDs 2 & 3 are now replaced with the new record data. This result could also be achieved by sending an ADD request with record overwriting allowed.

Keyed Write
When a table has its access mode set to Keyed the appds_write_record will append record data for all ADD requests. For Update the routine uses the specified key value to determine which records to modify and only those records that have equal key values will be updated. The value given for the selection key value cannot be NULL.

Shown in figure 2.3 is an example of a Keyed update of an APPDS table. In this example the appds_write_record routine is called with a request UPDATE all records that have a key value of "123". Before the update has taken place the APPDS table has two records that meet the selection criteria: "Record A" & "Record C". After the update is complete the contents of these two records has been replaced the new record data, "Record Z".

Removing Record Data
The removal of data records from APPDS tables is performed through the appds_delete_record library routine. This routine can be called to remove individual and multiple data records. To determine which record(s) to remove the routine uses the user supplied information in conjunction with current interaction mode of the APPDS table. On return the routine returns the number for records deleted from the table. For parameter information refer to the appds_delete_record entry in the CLIB Function Description online help.

Sequential Delete
For tables that have their access mode set to sequential the appds_delete_record routine will remove record(s) based on the location of the read/write pointer. When removing multiple records the routine will start from the location of the read/write pointer and move through the table sequentially. After removing the record(s) the read/write pointer is set to the record previous to the first record that was removed, if one exists. The user can signal the routine to start deleting from the top of the file by passing a non-NULL value for the select_value parameter. The number of records delete is always equal to the number requested.

In the example below, figure 3.0, the user calls the appds_delete_record requesting that two records be deleted. Before the deletion process the read/write pointer is at "Record B" which will be the first record removed. Since the user requested two records to be delete, "Record C" will also be removed. After the record removal the APPDS table is shown with two less records and the read/write pointer now pointing at "Record A".

Indexed Delete
When and APPDS table is set to indexed mode the appds_delete_record routine allows the user to specify which records to delete. The user specifies which records to delete by passing a list of Record IDs to the routine. The record IDs in the given list do not have to contain data, the only rule is that they are within the bounds for the table. Also the number of records deleted from the table is not always equal to the number requested. Thus, records deleted count returned is equal to the number of records that contained data. When a record is deleted, the data that is at the Record ID location is deleted and the Record ID is not.

In the example below, figure 3.1, the user is passing to the appds_delete_record routine a list of Record IDs; 1,3,5. After the call to the routine the record data at Record IDs 1 & 5 has been deleted and since Record ID 3 did not contain data, no modification will happen there. Thus, the deleted record count is two.

Keyed Delete
The appds_delete_record routine performs record remove for tables with access modes set to Keyed by selecting records based on a given key value. Using this key the routine will compare the key value of each record with it and all those record that match are removed. The deleted record count is equal to the number of records that had matching key values and were deleted.

Shown below, figure 3.2, is an example of a user request to delete records that have a key value equal to "123". When processing the request the routine finds that records "Record A" and "Record C" have key values that match the user supplied value and are removed.

APPDS Database Tunning
Within the APPDS routine is the ability to tune an APPDS database connection. Currently the following paramters are tunable:

• Database connection timeout value

The routine appds_set_db_timeout & appds_get_db_timeout allow for the setting and retrieval of the connection timeout value. The specified timeout is given in seconds. When setting the timeout value the appds_set_db_routine will close the active connection to the database and reopen it with the new value. All tables that reside on this database will use the new timeout value.For parameter information refer to the appds_set_db_timeout or appds_get_db_timeout entries in the CLIB Function Description online help.

APPDS Introduction Document
APPDS Manager Documentation