gtpc2m2vC/C++ Language Support User's Guide

find_record_ext-Find a Record with Extended Options

This function retrieves a record from virtual file access (VFA) or DASD. The core block reference word (CBRW) specified by level or decb must be unoccupied when find_record_ext is called. If the operation is successful, the CBRW is occupied with a working storage block containing the record image at completion.

This function makes the equivalent of a waitc call unless otherwise requested.

For HOLD-type calls (including HOLD_NOWAIT and HOLD_WAIT), the record address is placed in the record hold table and is available only to the issuing ECB.

Format

#include   <tpfio.h>
void       *find_record_ext(enum t_lvl level, const unsigned int *address,
                            const char *id, unsigned char rcc,
                            enum t_act type, unsigned int ext);

or

#include   <tpfio.h>
void       *find_record_ext(TPF_DECB *decb, TPF_FA8 *fa8,
                            const char *id, unsigned char rcc,
                            enum t_find_decb find_type, unsigned int ext);

level
One of 16 possible values representing a valid entry control block (ECB) data level from the enumeration type t_lvl, expressed as Dx, where x represents the hexadecimal number of the level (0-F). This parameter specifies an available file address reference word (FARW) and CBRW for use by the system.

decb
A pointer to a data event control block (DECB). This parameter specifies a FARW and CBRW for use by the system.

address
A pointer to a file address from which the record will be retrieved.

fa8
A pointer to an 8-byte file address from which the record will be retrieved.

id
A pointer to a 2-character record ID string that must match the ID characters in the record to be retrieved. This check may be bypassed by coding the term RECID_RESET, defined in tpfio.h.

rcc
An unsigned character that matches the record control check byte in the record to be retrieved.

type
The record's intended hold status. This parameter must belong to the enumeration type t_act, defined in tpfio.h.

NOHOLD
The record address is not placed in the record hold table following I/O completion.

HOLD
The record address is placed in the record hold table following I/O completion.

find_type
The hold and wait status of the record. The value of this parameter must belong to enumeration type t_find_decb, defined in tpfio.h and is one of the following:

NOHOLD_NOWAIT
Do not wait for the I/O operation to be completed before returning to the calling program and the record address is not placed in the record hold table (RHT) following I/O completion. The status of the operation is unknown on return to the calling program. To ensure that the operation is completed, a waitc function must be called. After the waitc function, the CBRW at the specified DECB contains the storage address of the record.

HOLD_NOWAIT
Do not wait for the I/O operation to be completed before returning to the calling program and the record address is placed in the RHT following I/O completion. However, the status of the operation is unknown on return to the calling program. To ensure that the operation is completed, a waitc function must be called. After the waitc function, the CBRW at the specified DECB contains the storage address of the record.

NOHOLD_WAIT
The I/O operation is completed before returning to the calling program. The record will not be added to the RHT following I/O completion.

HOLD_WAIT
The I/O operation is completed before returning to the calling program. The record will be added to the RHT following I/O completion.

ext
Sum of the following bit flags, that are defined in tpfio.h.

FIND_GDS
Use FIND_GDS to specify that the record to be retrieved resides in a general file or general data set. If FIND_GDS is not specified, find_record_ext accesses the record on the online database.
Note:
If the flag is not needed, the default extended options flag (FIND_DEFEXT) should be coded. Consider using the find_record function.

Normal Return

A pointer to the working storage block containing the record image following I/O completion.

Error Return

An integer value of zero. Detailed error information can be found in detail error byte ecbptr()->ce1sud[x], where x corresponds to the indicated ECB data level, or the SUD field in the DECB.

Programming Considerations

Examples

The following example retrieves a data record (id = CD, rcc = 0) from a general data set to level D7.

#include <tpfio.h>
 
  unsigned file_ptr;
 

  ·
  ·
  ·
ecbptr()->ebcfa7 = 0x0d0002f5; /* general file address to read */ find_record_ext(D7,(const unsigned int *)&ecbptr()->ebcfa7, CD,'\0',NOHOLD,FIND_GDS);

The following example retrieves and holds a data record with the file address and record ID specified in a DECB.

#include <tpfio.h>
TPF_DECB	*decb

  ·
  ·
  ·
find_record_ext(decb, NULL, NULL, '\0', HOLD_WAIT, FIND_DEFEXT);

Related Information

See TPF Application Programming for more information about DECBs.