FINDC: Find a file record

Use this general macro to read a record from a file into storage. 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 can be in the virtual file access (VFA) area.

Last updated

Changed in 2024.
Changed in 2021.
Changed in 2020.
Changed for PUT14 (information only; no code change).
Changed for PUT05 (information only; no code change).
Changed for PUT02.
Changed for PUT00.

Format

E-type program

C-type program

label

A symbolic name that can be assigned to the macro statement.

datalevel

An entry control block (ECB) data level (D0 - DF) that identifies the file address and core block information for the I/O request.

DECB

Is the data event control block (DECB), which specifies the file address and core block information for the I/O request.

reg: The general register that contains the address of the data event control block (DECB).

label1: The label that contains the address of the data event control block (DECB).

GDS

Specifies one of the following values:

N: Specifies that the file address in the specified ECB data level or DECB is for a record from the online database.
Y: Specifies that 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.

VFAFILL

Specifies one of the following values:

YES: Specifies that the data record that is requested in the specified ECB data level or DECB uses all the features of VFA if the record ID is defined in the record ID attribute table (RIAT) as a VFA candidate.
NO: Specifies that the data record that is requested in the specified ECB data level or DECB uses the copy of the record resident in VFA if the record ID is defined in the RIAT as a VFA candidate. However, if the data record is not in VFA, the request for the data record is treated as a non-VFA candidate and retrieved from file storage, and a copy of the record is not placed in VFA. This parameter is used only by utilities such as recoup.

DECRYPT

Specifies whether to decrypt the data record that is returned on the ECB data level or in the DECB if the data record was encrypted when it was filed.

YES: Decrypts the data record.
NO: Does not decrypt the data record.

DKN

Specifies whether to return the decryption key name in the DECB field IDECDKN if a DECB was used to find the data record and the found data record was encrypted when it was filed.

NO: Does not return the decryption key name. If this value is specified, the IDECDKN field is not initialized.
YES: Returns the decryption key name. If this value is specified but the data record is not decrypted, the IDECDKN field is initialized to hexadecimal zero.

PIA

Specifies the address of an entry point to be given control when the request has completed.

entry_point: Specifies that the address of the entry point is specified by the name of the entry point if it is internal to this routine.
reg2: Specifies that the address of the entry point is in a register. You must use a register if the entry point is external to this routine.

Entry requirements

For E-type programs:
- 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 FARW for the specified ECB data level (datalevel) or DECB.
- The GDSRC macro must be run to set up the file address before the FINDC macro is used to access a general data set record.

Return conditions

For E-type programs:
- Control is returned to the next sequential instruction.
- The contents of R14 and R15 are unknown. The contents of all other registers are preserved across this macro call.
- On return from this macro, the condition code is unknown.
- The status of the operation is unknown.
- The contents of the CBRW at the specified ECB data level (datalevel) or DECB is unknown.
- The file address reference word (FARW) at the specified ECB data level (datalevel) or DECB is unchanged.
For C-type programs:
- 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 z/TPF system state on entry:
    - Address Mode - 64-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.
    - 00 - I/O completed without errors (block returned)
    - 40 - Record ID error or record code check error (block returned)
    - 80 - DASD (hardware) I/O error (block not 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

For information about macro register conventions, see Register conventions.
This macro can be run on any I-stream.
For E-type programs:
- 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 if 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 verified with the RCC in the record. This check is not made if the specified RCC is zero. If either check fails, an error code is indicated in the ECB. (See WAITC–Suspend processing for ECB I/O completion for more information.)
- To ensure that the operation was completed, a WAITC macro must be run. After a WAITC macro, the CBRW at the specified ECB data level or DECB contains the storage address of the record.
- After a WAITC macro, if an error occurs and SUD is set to CXSGIE - ID check failure or CXSGRE - RCC check failure, the record will be on the specified ECB data level or DECB.
- You cannot call the FINDC macro on a record that is part of the suspended commit scope for an ECB. The following sequence will cause a system error:
  1. TXBGC
  2. FILEC record x
  3. TXSPC
  4. FINDC record x.
- z/TPF transaction services processing affects FINDC macro processing in the following ways:
  - If a system error occurs because of one of the previous considerations, processing ends as if a TXRBC macro was called. The DASD surface remains unchanged.
  - 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 z/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 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.
- The trace data that is collected for this macro includes the following macro-unique data:
  - The data level or DECB address, and the file address
  - An indication that the record was read from the VFA area or from DASD
For C-type programs:
- A control program (CP) caller must do several things:
  1. Allocate a DECB and fill in the required values.
  2. Allocate a storage block to hold the specified record and store the storage block's address in the DECB.
  3. 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.
  4. 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 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.
A find request with a record ID of 0 queues the request to the prime module instead of using least queuing. This might lead to performance problems. Validate your need to use record ID 0 and use the correct record ID when possible.

Examples

The following example shows that a record is read from a file into storage; the file address and core block information are contained in ECB data level D1.

FINDC D1

The following example shows that R1 contains the address of the DECB. The address of the entry point is in R0.

FINDC DECB=(R1),PIA=(R0)

The following example shows that R1 contains the address of the DECB; the file address and core block information are contained in the DECB. If the record ID is defined in the RIAT as a VFA candidate and a copy of the record is in VFA, that copy of the record is returned to the caller. However, if the record is not in VFA, the request is changed to a non-VFA candidate, and the record is read from the file and returned to the caller. The record is not saved in VFA.

FINDC DECB=(R1),VFAFILL=NO

The following example shows that a data record is read from a file and copied into memory. The file address and core block information are in the DECB that is pointed to by R1. The data record that is returned is not decrypted if it was encrypted when it was filed.

FINDC DECB=(R1),DECRYPT=NO

The following example shows that a data record is read from a file into storage. The file address and core block information are in the DECB that is pointed to by R1. If the data record was decrypted, the DECB field IDECDKN contains the decryption key name that was used to decrypt the record. If the data record was not decrypted, the IDECDKN field is set to hexadecimal zero.

FINDC DECB=(R1),DKN=YES