This general macro reads a record from file into storage and holds
it. A block of storage is obtained by the control program and reference
to it is stored in the core block reference word (CBRW) at the specified entry
control block (ECB) data level or data event control block (DECB).
The requested record may be contained in virtual file access (VFA).
The control program will queue this request if the record is being held by
another ECB. All succeeding requests to hold this record are queued
until the existing record hold is released.
Format
- label
- A symbolic name can be assigned to the macro statement.
- datalevel
- An ECB data level (D0-DF) that identifies the file address and core
block information for the I/O request.
- DECB=(reg)|label1
- The label or general register (R0-R7) containing the address of the
DECB, which specifies the file address and core block information for the I/O
request.
- label2
- The label of an operational program error routine within the current
program segment must be specified.
- GDS
- Specify one of the following:
- N
- The file address in the specified ECB data level or DECB is for a record
from the online database.
- Y
- The file address in the specified ECB data level or DECB is for a record
on either a general file or a general data set.
Entry Requirements
- R9 must contain the address of the ECB being processed.
- A block of storage must not be held by the ECB at the specified ECB data
level (datalevel) or DECB.
- A file address, record ID, and record code check (RCC) must be contained
in the file address reference word (FARW) for the specified ECB data level
(datalevel) or DECB.
- The GDSRC macro must be executed to set up the file address before FIWHC
is used to access a general data set record.
- The entry must not be holding the record.
Return Conditions
- The contents of R14 and R15 are unknown. The contents of all other
registers are preserved across this macro call.
- The condition code that is returned from this macro cannot be
predicted.
- If no I/O hardware errors or unusual conditions have occurred, control is
returned to the next sequential instruction (NSI). Otherwise, control
is returned to the address specified by the variable label2.
- All pending input operations, including this request, are completed for
this ECB. The status of output requests (except the FILNC macro) is
unknown.
- The CBRW specified by datalevel or DECB contains the address of
the record.
- The requested file record is held. (It is available only to this
ECB until released).
- The FARW at the specified level (datalevel) or DECB is
unchanged.
- For I/O hardware errors, the system error routine has taken a core dump
and informed CRAS.
Programming Considerations
- This macro can be executed on any I-stream.
- A check is made by the control program to determine if the ECB is not
holding a block of storage at the specified ECB data level or DECB and the
file address contained at the specified ECB data level or DECB is
valid. If either condition is violated, control is transferred to the
system error routine. In addition, the control program verifies that
the record ID at the specified ECB data level or DECB is equal to the record
ID in the record. If the record ID specified is zero, this check is not
made. The RCC at the specified ECB data level or DECB is checked with
the RCC in the record. This check is not made if the specified RCC is
zero. If either check fails, control is transferred to the specified
operational program error routine (label2).
- An immediate return is made to the user program if all input/output
operations are completed at macro time.
- Following use of this macro, control may be transferred to the current
program segment for processing of another entry.
- Running this macro resets the 500-millisecond program time-out.
- If any I/O hardware errors or unusual conditions have occurred, detailed
information concerning the error has been stored in the ECB for each I/O level
and DECB.
- You cannot call the FIWHC macro on a record that is part of the suspended
commit scope for an ECB. The following sequence will cause a system
error:
- TXBGC
- FILEC record x
- TXSPC
- FIWHC record x.
- TPF transaction services processing affects FIWHC macro processing in the
following ways:
- Additional checks must 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 are queued as usual. Requests for
file addresses held outside of the commit scope are queued. Requests
for file addresses held within the commit scope are serviced.
- If a system error occurs because of one of the previous considerations,
processing ends as if a TXRBC macro was called.
- 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 first searches in the commit scope set for the
record. If the record is not found, normal DASD retrieval takes place
from VFA or the DASD surface.
- If a deadlock condition is detected on the ECB that issued this macro, 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 system
error dump CTL-0D9. If the return code from the user exit is 8, CE1SUD
or IDECSUD, 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.
- If the location of the data event control block specified by the DECB
parameter does not refer to a valid DECB, control is transferred to the system
error routine.
Examples
None.