gtpc2m30 | 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(enum t_lvl level);
- 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.
Normal Return
Pointer to the working storage block containing the retrieved record
image.
Error Return
NULL.
Programming Considerations
- The fiwhc function cannot be issued on a record that is part of
the suspended commit scope of an ECB. The following sequence will cause
a system error:
- tx_begin()
- filec() record X
- tx_suspend_tpf()
- fiwhc() 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 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.
- The TPF system will first search for the record in the commit
scope. If it 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 file on level D2 with
hold. The file address has already been calculated and resides in the
level D2 FARW. Control is returned to the operational program when the
I/O is complete and the record has been attached to the specified
level.
#include <tpfio.h>
struct im0im *inm;
·
·
·
inm = fiwhc(D2);
Related Information