gtpc2m2m | C/C++ Language Support User's Guide |
This service files a record to either VFA or DASD.
Format
#include <tpfio.h>
void file_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). The
working storage block on this core block reference word (CBRW) level is the
record to be filed.
- address
- A pointer to the file address indicating where the record will be
filed.
- id
- A pointer to the 2-character record ID.
- rcc
- An unsigned character that represents the value to be assigned to the
record code check field of the record being filed.
- type
- The disposition of the record's hold status, or the associated
working block. This argument must belong to the enumeration type
t_act, defined in tpfio.h.
- NOHOLD
- The record is not in hold status and the associated working storage block
can be returned to the system.
- UNHOLD
- The record is in hold status and the associated working storage block can
be returned to the system.
- NOREL
- The record is not in hold status and the associated working storage block
should not be returned to the system.
Normal Return
Void. The associated working storage buffer block has been made
unavailable to the operational program. For NOREL calls, the
buffer block will be available to the operational program following a
subsequent waitc call.
Error Return
Not applicable.
Programming Considerations
- The file_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()
- file_record() record X.
- On NOHOLD and UNHOLD calls the status of the
operation can never be determined. You must code a waitc
call to determine the status of the file action on an NOREL
request.
- The CBRW of the data level named as the first argument must be occupied by
a working storage block of the same size as the file record. This block
will be considered the image of the record to be filed.
- The FARW of the data level named as the first argument is changed by this
function with the address, id, and rcc
arguments. If either the address or id arguments
are coded with the defined term NULL, initialization of the
indicated FARW with the null item is not performed. If the defined term
RECID_RESET is specified for the id argument, the record
id in the FARW will be set to binary zeros.
- For UNHOLD requests, the file address must have been held by
the issuing ECB. This address is removed from the record hold table
following I/O completion.
- For NOREL and NOHOLD requests, if the file address
is present in the record hold table, it will remain there through this
call.
- This function may be used for general file output, provided that the file
address has been calculated by use of the gdsnc, gdsrc,
or raisa functions. General file users should be aware that
argument address should be coded as NULL, as the file
address is placed on the FARW level by all of the previous functions.
- Control is transferred to the system error routine if the id
and rcc values specified do not match the corresponding fields in
the record image. Coding the rcc as \0 causes this check to
be bypassed.
- TPF transaction services processing affects file_record
processing in the following ways:
- Hardening to the DASD surface will only occur at commit time.
- When rollback occurs, filec changes are discarded and hardening
does not occur. The DASD surface remains unchanged.
- If a system error occurs because of an ID or record code check (RCC),
processing ends as if a rollback was issued.
- waitc processing does not report hardware errors for
NOREL when the waitc function is issued in the commit
scope.
- When the file address returns from the NOREL file, it appears
to be unheld from the point of view of the program. For requests from
outside the commit scope, the file address still appears to be held.
When the commit has completed successfully, the file address will be unheld
and any waiting requests will be serviced.
Examples
The following example files a record from D6 with id set to IM,
the rcc set to zero, and the file address taken from the forward
chain field of another record.
#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;
.
.
.
file_record(D6,(const unsigned int *)&(inm->im0fch),"IM",'\0',NOHOLD);
Related Information