Use this system macro to read a record from a file into storage. The
record can be in the virtual file access (VFA) area.
Format
- label
- A symbolic name can be assigned to the macro statement.
- DECB=area_label|(Rx)
- The address of a data event control block (DECB) must be specified either
by any register (other than R0) or by the label. The label is the
address of the DECB, not an address to a pointer of the DECB.
- PIA=entry_point|(Ry)
- The address of an entry point to be given control when the request has
completed. The address can be specified either by a register or by the
name of the entry point if it is internal to this routine. If the entry
point is external to this routine, a register must be used.
Entry Requirements
- The DECB address must have the following fields set in the IDECB
DSECT:
- IDECECB
- 0
- IDECDBI
- Set to the database ID (DBI) of the subsystem
- IDECSSU
- Set to the correct subsystem user (SSU) for the file address
- IDECDAD
- Address of the storage area to hold the record
- IDECDLH
- Length of the storage area
- IDECRID
- Record ID of the record
- IDECRCC
- Record code check (RCC) value
- IDECFA
- File address for the record.
- The TPF system state must be:
- Address Mode
- 31-bit
- Address State
- SVM
- PSW KEY
- 0
- PSW MASK
- I/O disabled
- System State
- Privileged.
- Register 0 cannot be used to pass the DECB address.
Return Conditions
- $FINDC return:
- Control is returned to the next sequential instruction.
- R14 contains the address of the next sequential instruction.
- The contents of R0 and R1 are destroyed across this macro call. The
contents of all other registers are preserved.
- PIA entry point
- Register contents on entry:
- R1
- DECB address
- R2
- PIA entry point address
- R14
- Return address (CPU loop).
- The TPF system state on entry:
- Address Mode
- 31-bit
- Address State
- SVM
- PSW KEY
- 0
- PSW MASK
- I/O Disabled
- System State
- Privileged.
- In the post-interrupt routine, control is returned on the same I-stream in
which the $FINDC macro was run.
- The IDECSUD field shows the success or failure of the request.
- Error codes
- Descriptions
- X'00'
- I/O completed without errors (block returned)
- X'40'
- DASD (hardware) I/O error (block not returned)
- X'80'
- Record ID error or record code check error (block returned)
- If the macro returns normally, the storage block contains the specified
record. If there is an End-of-File condition or a software or hardware
error, the contents of the specified storage block cannot be predicted.
Programming Considerations
- This macro can be run on any I-stream.
- This macro is for use in the control program (CP) only.
- The control program (CP) caller must do several things:
- Allocate a DECB and fill in the required values.
- Allocate a storage block to hold the specified record and store the
storage block's address in the DECB.
- Issue a $FINDC macro to cause the DASD support to read the specified
record from file into the specified storage area.
On return from the macro, the requested operation has only been
accepted. When the request has completed, the entry point specified in
the PIA parameter is given control and the success or failure of the request
is indicated in the DECB.
- In the post-interrupt routine, control is returned in the same I-stream on
which the $FINDC macro was run.
- Various error conditions can occur:
- A check is made by the control program (CP) to determine whether the DECB
is now active. If the DECB is active, control is transferred to the
system error routine.
- If the file address contained in the DECB is not valid, an error code
(X'02') is indicated in the DECB.
- The control program (CP) verifies that the specified record ID matches the
ID in the record. If the record ID specified is zero, this check is not
made. If the match fails, an error code is indicated in the
DECB.
- The specified record code check is verified with the record code check in
the record. This check is not made if the specified record code check
is zero. If the check fails, an error code is indicated in the
DECB.
Examples
None.