gtpc2m2w | 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 entry control block
(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 DASD.
The TPF system 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 finhc(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
Void.
Error Return
Not applicable.
Programming Considerations
- The finhc 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()
- finhc() 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 the record code check in the record. If
either check fails, an error code is posted in the ECB level
indicators.
- To ensure completion of the I/O, the requesting program must call
waitc following finhc.
- TPF transaction services processing affects finhc 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 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 file on level D2 with
hold. The file address has already been calculated and resides in the
level D2 FARW.
#include <tpfio.h>
·
·
·
finhc(D2);
if (waitc())
{
serrc_op(SERRC_EXIT,0x12345,"I/O ERROR OCCURRED",NULL);
/*
In TARGET(TPF) this used to be done with:
errno = 0x1234;
perror("I/O ERROR OCCURRED");
abort();
*/
}
Related Information