gtpa2m3d | Application Programming |
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:
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.
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.*/