gtpc2m2v | C/C++ Language Support User's Guide |
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
- The find_record_ext 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()
- file_record() record X
- tx_suspend_tpf()
- find_record_ext() record X.
- The indicated CBRW must be unoccupied when the function is called.
If not, control is transferred to the system error routine.
- The indicated CBRW is occupied on return with a working storage block of
the same size as the file record if the operation was successful.
- All pending input operations are completed on return from this
function. Pending output operations may not be completed.
- For HOLD-type calls, the record address is placed in the record
hold table and is available only to the issuing ECB. If the indicated
record address is held by another ECB, the request is queued until the record
is made available.
- If a record hold was requested, the programmer is responsible for ensuring
that the record is removed from the record hold table before calling the
exit function.
- An error code is posted in the ECB data level or the DECB indicators if
the values specified in parameters id and rcc do not
match their corresponding fields in the retrieved record. Coding
id as RECID_RESET and coding rcc as \0 causes
this check to be bypassed.
- If the indicated record address is held by another ECB, this request is
queued until the record is made available.
- If a hardware error occurred, the system error routine issues a core dump
and notifies the computer room agent set (CRAS) terminal.
- If the FARW at the indicated ECB data level or DECB is already in a
pre-initialized state (from a previous call to FACE or FACS, or general data
set input), you may want to bypass initializing the FARW values. If so,
code parameters id and address as NULL.
- TPF transaction services processing affects find_record_ext
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.
- 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 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.
- Applications that call this function using DECBs instead of ECB data
levels must be compiled with the C++ compiler because this function has been
overloaded.
- This function is implemented in dynamic link library (DLL)
CTAD. You must use the definition side-deck for DLL CTAD to link-edit
an application that uses this function.
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.