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
- 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
- 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
The last two items, element count and array of record elements, describe the data that is stored
in each record. Each array item is an APPDS_DATA_INFO data struture which defines a single
data element, i.e. integer, float, character array. An APPDS_DATA_INFO strucutre has the
- Lock status
- Lock owner, if any
- 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)
The first field in the strucutre defines the data type of the element. The possible data types are
CNV_BYTE, CNV_SHORT, CNV_LONG, CNV_FLOAT, CNV_DOUBLE, CNV_CHAR and CNV_HEX_STRING.
For CNV_CHAR and CNV_HEX_STRING the data length defines the number of elements in the data string,
otherwise it is set to zero. If the stored data element represents an array data the element count
is set to the array size.
To change the interaction
mode of a table the APPDS facility provides the appds_set_inter_mode
routine. With this routine the user can set the Access Mode, Read/Write
Mode and Overwrite for any table. However, this routine will
only work on tables that have not been locked. If an attempt is made to
set a locked table an error will be returned. For parameter information
about these two routines refer to the appds_get_inter_mode
entries in the CLIB Function
Description online help.
- Data type
- Data lenght
- Element count
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
The status information is returned via the APPDS_TABLE_STATUS structure, which is
provided by the calling routine. The first two elements in the structure pertain to the number of records
in the table and the record ID for the last record. The next item is a text string containing the time
and date for the last read or modification performed on the table. The updating, logging, of the last access date can
be controled through the APPDS Manager. The last element
of the structure is a boolean flag indicating if the last access date is either on or off.
For parameter information about appds_table_status refer to the
appds_get_table_status entries in the
CLIB Function Description online help.
- 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
entry in the CLIB Function Description
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
Figure 1.0 Example Sequential record layout
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
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"
Figure 1.1 Example Index record layout
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.
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.
Figure 1.2 Example Keyed record layout
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
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.
Figure 2.0 Example of a Sequential record ADD
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.
Figure 2.1 Example of a Sequential record UPDATE
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.
Figure 2.2 Example Indexed 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".
Figure 2.3 Example of a Keyed Update
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
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".
Figure 3.0 Example of Sequential 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.
Figure 3.1 Example Indexed record 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.
Figure 3.2 Example Keyed record layout
APPDS Database Tunning
Within the APPDS routine is the ability to tune an APPDS database connection. Currently the following paramters are
- 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
entries in the CLIB Function Description
Last modified: Fri Feb 12 12:40:27 CST 1999