gtpa2m3dApplication Programming

Random Pool File Area

The dynamic requirements for file storage are maintained in an area called the random pool file area, or simply pools. Whereas the fixed file is allocated to static record types, the pools are allocated for random use and are dispensed on an as-needed basis. In other words, TPF manages the availability of each pool record. The application simply requests a pool record, uses it for as long as necessary, then returns it to the system.

Records in random pools are categorized by size (small, large, or 4 K), length of retention (short-term or long-term), and duplicate or single.

Pools are also categorized by file address size (4-byte or 8-byte).

Short-term records are intended for quick turnover, such as the life of a customer transaction, and are returned immediately to the pool when the application releases them. Long-term records are intended for a longer interval of use dictated by application needs, and may extend into months. When released by application programs, long-term record addresses are written to tape for offline return to the pool.

A typical example of the practical use of the fixed file and the pools is provided by the airline reservation system. Flight inventory records and indexes to the passenger names are maintained on the fixed file. Pool records contain the individual passenger name records. Because the flight is flown on a scheduled basis, the inventory and indexes, though modified, will be retained permanently. When the flight has flown, however, individual passenger records are not retained online; they are placed in a history file and the pool space is made available for use again.

Duplicate records are records that, at allocation, are assigned to 2 different disk modules in order to increase availability of those records. If a module on which a duplicate record resides should fail, the record can still be retrieved from the other module. When the record is filed, both copies of the record are updated automatically. This updating is transparent to the application.

Application use of pool storage is simple and straightforward: it amounts to requesting an address (1 per function call) and releasing an address (1 per function call). Good use of resources mandates that addresses be returned promptly.

The assembly language GETFC macro gets small, large, or 4 KB records by pool ID. The pool ID is a parameter on the macro and is used as an index into the record ID attribute table (RIAT), which specifies long or short term, single or duplicate, and small, large, or 4 KB.

All file storage pool record addresses are returned by running the RELFC (release file storage) macro. The file address that is being returned is contained in the ECB data level or the DECB FARW specified in the macro instruction. See Data Event Control Blocks for more information about DECBs.

Examples of these macros are as follows:

GETFC D6,,ID=AB          D6 specifies that the record address be
                         placed in the ECB level 6 FARW; AB is the
                         record ID, which is used in the RIAT.
 
RELFC D6                 D6 specifies that the record address, in the
                         level 6 FARW, is to be returned.  This is the
                         only parameter required.  The record size and
                         whether it is short or long term is determined
                         from the contents of the FARW.

The C language getfc (obtain file pool address) function gets a file address (and optionally, a working storage block) based on attributes associated with a pool identification. The following arguments, listed in the order given below, are associated with the getfc function:

level or decb
level is a value of enumeration type t_lvl that specifies an available ECB data level. decb is a value of structure type TPF_DECB*, which is a pointer to a DECB.

type
One of the predefined terms GETFCTYP0 through GETFCTYP9, which determine the size and pool types in the record identification attribute table (RIAT) associated with the id argument. GETFCPRIME and GETFCOVERF are still supported for migration purposes only.

id
A pointer to a 2-character string that contains the pool identification. The pool identification is used as an index into the RIAT, which specifies long or short term, single or duplicate, and small, large, or 4 K.

block
One of the predefined terms GETFCBLOCK or GETFCNOBLK, which determines whether or not a working storage block with characteristics specified by the RIAT is to be obtained simultaneously.

error
One of the predefined terms GETFCSERRC or GETFCNOSER, which determines whether or not control is to be returned to TPF in the event of an error. GETFCSERRC will cause control to be transferred to the system error routine (with exit) in the event that storage cannot be obtained as requested.

The getfc function returns the requested file address.

All file storage pool record addresses are returned to the TPF system by calling the relfc (release file pool storage) function. The file address that is being returned is contained in the ECB data level or the DECB FARW specified as the only argument of the function.

Examples of Using the Pool Storage Functions:

It is important to understand that the pool area has no access scheme; that is, it has no record type, ordinal number, or other identification enabling retrieval except the system address. Once the application gets an address, it must maintain its own future access by saving that address. The address may be saved in the fixed file, the ECB, the global areas, or wherever good design dictates, but it is an application responsibility.

Figure 42. Using Pool Storage Functions

  #include <tpfio.h>
  #include <c$am0sg.h>
  struct am0sg *amsg;                    /* Pointers to message blocks */

  ·
  ·
  ·
amsg = ecbptr()->ce1cr1; /* Base prime AAA record */ if (!(amsg->am0fch = getfc(D6,GETFCTYP3,"OM",GETFCBLOCK, GETFCNOSER))) /* D6 specifies that the record address be placed in the */ /* ECB level 6 FARW; pool type is 3; OM is the */ /* record ID used in the RIAT; BLOCK causes a block and */ /* file address to be obtained; NOSERRC does not cause */ /* an exit to the system error routine in the case of an */ /* error. */ serrc_op(&EXIT.,0x33001," ",NULL,NULL); /* Perform dump with exit */ /* if getfc() fails */
  ·
  ·
  ·
relfc(D6); /* D6 specifies that the record address, in the level 6 */ /* FARW, is to be returned. This is the only parameter */ /* required. The record size and whether it is short- or */ /* long-term is determined from the contents of the FARW.*/