gtpa2m3eApplication Programming

File Storage Access

Note:
In this section, FARW refers to an ECB data level or a DECB. See Data Event Control Blocks for more information about DECBs.

Whether fixed file or pools, all file accessing under TPF is done in a similar fashion. The TPF terms for file accessing are:

Term
Function Type

 find 
Read a record

 file 
Write a record.

There are many variations of these 2 basic operations, but the largest distinction exists between the "higher-level" and "basic" find and file functions. Higher-level functions allow an application programmer to read and write files without previously performing certain setup functions required for the basic functions. All basic find and file operations must be preceded by 2 application steps:

  1. The system file reference (symbolic file address) must be supplied in the FARW.
  2. The remainder of the FARW must be initialized according to the requirements of the function call used.

All higher-level functions must be supplied with the same information, but you must supply it in the argument list of the function itself.

Prerequisites for Basic Find and File Functions

The prerequisite information required by the basic find and file functions is as follows:

Step 1
The TPF system programs handle the details of obtaining the physical address of the record at the time of the find/file request. To enable this the application must supply the symbolic address in the low-order 4 bytes of the FARW. You can obtain this address in 1 of 3 ways:
  1. If the record resides on the fixed file, pass the record type and ordinal number as a parameter to FACE/FACS. If the program specifies the FARW of a data level as the location, FACE/FACS will store the address there, ready for the find/file function request.
  2. If a new pool record is to be used, use the getfc function to obtain the address and store it in the FARW.
  3. If the address is a previously used pool record, move the address from where the application has saved it to the FARW. In C language, use the ecbptr function to do this. In assembly language, move it directly.

Step 2
As pointed out in the discussion of the ECB, the FARW is an 8-byte control field for file activity related to any data level. The low-order word must contain the file address. The high-order 3 bytes are used for data integrity checks, which vary as follows (the fourth byte is not used):

For find requests:

For file requests:

Use of the Higher-Level C Language Find and File Functions

The prerequisite information required by the basic find and file operations is supplied to the associated higher-level functions by means of the following arguments, which must be listed in the order given below:

level or decb
level is a value of enumeration type t_lvl that specifies available core block reference word (CBRW) and FARW locations. decb is a value of structure type TPF_DECB*, which is a pointer to a DECB.

address
A file address that is typically obtained through a call to either the FACE and FACS programs or the FAC8C macro.

id
A 2-character string that must match the identification characters in the record image. For find_record, if the requested ID does not match the record's identification characters, the ECB error fields will indicate an identification check failure and control will return to the application at I/O completion. For file_record, if the requested ID does not match the record's identification characters, the system error routine will be activated and the ECB will be forced to exit. No comparison for either find_record or file_record will be made if the identification field is preinitialized to zero (X'0000') or is coded as RECIDRESET.

rcc
An unsigned character that must match the record control check (rcc) byte in the record to be retrieved (find_record) or filed (file_record). If the requested rcc does not match the record's rcc, then the system error routine will be activated and the ECB will be forced to exit. No comparison will be made if rcc is zero (X'00' or '\0').

type
One of the predefined terms enumerated in t_act that are used to indicate the record's hold status.

The following optional parameters may also be used with find and file functions:

FIND_GDS
Use FIND_GDS to specify that the record to be read resides in a general file or general data set. If FIND_GDS is not specified, findc_ext accesses the record on the online database.
Note:
If the flag is not needed default extended options flag, FIND_DEFEXT, should be coded. In this case user should consider using the findc function.

FILE_GDS
Use FILE_GDS to specify that the record to be filed resides in a general file or general data set. If FILE_GDS is not specified, filec_ext accesses the record on the online database.

FILE_NOTAG
The TPF system code that places the program identification in the record header is bypassed. This flag should only be used when the application updating the record has placed the required program identification in the header directly.
Note:
If neither of the above flags are needed default extended options flag, FILE_DEFEXT, should be coded. In this case user should consider using the filec function.

Record Hold Facility

All programs should hold file records before updating them. The TPF record hold facility is intended to reserve a file record for exclusive use of 1 entry during record update; this ownership ensures data integrity and proper sequencing of updates.

TPF maintains a record hold table that consists of a list of file addresses and the ECB of the holding entry. When an entry attempts to hold a record by calling a find-and-hold function (finhc, finwc, or find_record with HOLD specified as the last argument), TPF honors the find request only if the address of the requested record is not in the record hold table. If it is, TPF denies the entry access to the record. This does not prevent entries that simply call a find function from gaining access to and even updating the record. Only entries that properly use the hold facility are so restricted. Therefore, properly sequenced updates are only ensured if all programs cooperate in using the hold facility properly.

TPF's limitation of the hold feature to the individual record level is an important contribution to performance. Even so, misuse of the hold could have very serious effects on the system. A program should hold only 1 file record (or the unique first record of a chain of records) at a time; otherwise, a lockout condition may occur. (This is sometimes colloquially called horns lock, deadlock, or deadly embrace.) A program also should unhold a record as soon as possible--ideally, as soon as its update is complete.