gtpc2m31 | C/C++ Language Support User's Guide |
This function reads a record and attaches the block of working storage
containing it to the specified data level of the ECB. The ECB must not
be holding a storage block on the specified level.
This service finds a record that resides either in VFA or on an external
device.
The control program queues this request if the record is being held by
another entry. All succeeding requests to hold this record are queued
until the record is unheld.
Format
#include <tpfio.h>
void *fiwhc_ext(enum t_lvl level, unsigned int ext);
- level
- One of 16 possible values representing a valid data level from the
enumeration type t_lvl, expressed as Dx, where x
represents the hexadecimal number of the level (0-F). The data
record being retrieved is attached to this level.
- ext
- Logical or (&or.) of the following bit flags which are defined in
tpfio.h.
- 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,
fiwhc_ext accesses the record on the online database.
- Note:
- If the flag is not needed, the default extended options flag, (FIND_DEFEXT)
should be coded. Consider using the find_record
function.
Normal Return
Pointer to the working storage block containing the retrieved record
image.
Error Return
NULL.
Programming Considerations
- The fiwhc_ext function cannot be issued on a record that is
part of the suspended commit scope of the ECB. The following sequence
will cause a system error:
- tx_begin()
- filec() record X
- tx_suspend_tpf()
- fiwhc_ext() record X.
- The specified CBRW is initialized to indicate that a block of storage is
attached to the specified data level. Specifying an invalid data level
results in a system error with exit.
- The TPF system checks to determine if the ECB is holding a block of
storage at the specified level and if the file address contained at the
specified level is valid. If either condition is violated, control is
transferred to the system error routine. In addition, the record ID on
the specified level, if nonzero, is compared with the record ID in the record
retrieved from file. The record code check on the specified level, if
nonzero, is also compared with the record code check in the record. If
either check fails, an error code is posted in the ECB level
indicators.
- Calling this service resets the 500-millisecond program time out.
- TPF transaction services processing affects fiwhc_ext
processing in the following ways:
- Additional checks need to be made to determine if the file address is held
at the program level or at the commit scope level. Requests for file
addresses held at the program level will be queued as usual. Requests
for file addresses held outside of the commit scope will be queued.
Requests for file addresses held in the commit scope will be serviced.
- If a system error occurs because of one of the previous considerations,
processing ends as if a rollback was issued.
- Finds from general files or general data sets are not considered part of
the commit scope and are not affected by commit scope processing.
- The TPF system will first search for the record in the commit
scope. If the record is not found, normal DASD retrieval will take
place from virtual file access (VFA) or the DASD surface.
- If a deadlock condition is detected on the ECB that issued this C
function, a deadlock user exit is called with the ECB address and input/output
block (IOB) address as an input. If the return code from the user exit
is 0, processing continues as if the user exit was never called. If the
return code from the user exit is 4, the ECB is scheduled to exit with dump
D9. If the return code from the user exit is 8, CE1SUD and CE1SUG of
the ECB will be set to CJCSUHRD and CJCSUDLK (that is, X'81') and the
waiting IOB is removed from the system.
Examples
The following example retrieves a data record from a general data set to
level D7. The file address has already been calculated and resides in
the level D7 FARW. Note that FACS is not used to calculate file
addresses for general files or general data sets.
#include <tpfio.h>
·
·
·
inm = fiwhc_ext(D7,FIND_GDS);
Related Information