gtpc2m2u | C/C++ Language Support User's Guide |
This function retrieves a record from VFA or DASD. The CBRW
specified by level must be unoccupied when find_record
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.
For HOLD-type calls, 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(enum t_lvl level, const unsigned int *address,
const char *id, unsigned char rcc, enum t_act type);
- level
- One of 16 possible values representing a valid 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 FARW and CBRW for use by the system.
- address
- A pointer to a file address from which the record will be
retrieved.
- id
- A pointer to a 2-character ID string that must match the ID characters in
the record to be retrieved.
- 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 argument 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. The programmer is responsible for ensuring that the record
is removed from the record hold table before calling the exit
function.
Normal Return
Pointer to the working storage block containing the record image following
I/O completion.
Error Return
Integer value of zero. Detailed error information can be found in
the detail error byte (ecbptr()->ce1sud[x]), where x
corresponds to the indicated data level.
Programming Considerations
- The find_record 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() 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.
- An error code is posted in the ECB level indicators if the values
specified in arguments id and rcc do not match their
corresponding fields in the retrieved record. Coding the id
as RECID_RESET and coding the 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 level is already in a pre-initialized state
(from a previous call to FACE or FACS, or general data set input), the
programmer may want to bypass initializing the FARW values. If this is
desired, code arguments id and address as NULL.
- TPF transaction services processing affects find_record
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.
- 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.
Examples
The following example retrieves a forward chain IM record (rcc = 0) on D6
with hold.
#include <tpfio.h>
struct im0im
{
char im0bid[2]; /* record ID */
unsigned char im0rcc; /* record code check */
unsigned char im0ctl; /* control byte */
char im0pgm[4]; /* program stamp */
unsigned long int im0fch; /* forward chain */
unsigned long int im0bch; /* backward chain */
short int im0cct; /* byte count */
.
(data fields)
.
} *inm, *inm_chain;
.
.
.
inm = ecbptr()->ce1cr5; /* Base first in chain */
if(!(inm_chain = find_record(D6,
(const unsigned int *)&(inm->im0fch),
"IM",
'\0',
HOLD)))
{
exit(0x12345); /* Issue dump & exit if error */
}
else
{
. /* Normal processing path */
.
.
}
Related Information