gtpa2m3e | Application Programming |
- 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:
- The system file reference (symbolic file address) must be supplied in the
FARW.
- 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.
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:
- 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.
- If a new pool record is to be used, use the getfc function to
obtain the address and store it in the FARW.
- 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:
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.
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.