gtpc2m2n | C/C++ Language Support User's Guide |
This service files a record to either virtual file access (VFA) or
DASD.
Format
#include <tpfio.h>
void file_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 file_record_ext(TPF_DECB *decb, TPF_FA8 *fa8,
const char *id, unsigned char rcc,
enum t_act 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). The working storage block on this core block reference
word (CBRW) level is the record to be filed.
- decb
- A pointer to a data event control block (DECB). The working storage
block anchored off the CBRW of the DECB is the record to be filed.
- address
- A pointer to the file address indicating where the record will be
filed.
- fa8
- A pointer to an 8-byte file address indicating where the record will be
filed.
- id
- A pointer to a 2-character record ID string that must match the ID
characters in the record to be filed. This check can be bypassed by
coding the term RECID_RESET, defined in
tpfio.h.
- rcc
- An unsigned character that represents the value to be assigned to the
record code check (RCC) field of the record being filed.
- type
- The disposition of the record's hold status, or the associated
working block. This parameter 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.
- ext
- Logical or (|) of the following bit flags that are defined in
tpfio.h.
- FILE_GDS
- Use FILE_GDS to specify that the record to be filed resides in a general
file or general data set. If FILE_GDS is not specified,
file_record_ext accesses the record on the online database.
- FILE_NOTAG
- The TPF system code that places the program identification in the record
header is bypassed. This flag should only be used when the application
updating the record has placed the required program identification in the
header directly.
- Note:
- If flags FILE_GDS or FILE_NOTAG are not needed, code the default extended
options flag, FILE_DEFEXT. Consider using the file_record
function.
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_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_ext() record X
- tx_suspend_tpf()
- file_record_ext() record X.
- On NOHOLD and UNHOLD calls the status of the
operation can never be determined. The programmer must code a
waitc call to determine the status of the file action on an
NOREL request.
- The CBRW of the ECB data level or DECB named as the first parameter must
be occupied by a working storage block of the same size as the file
record. This block is considered the image of the record to be
filed.
- The FARW of the ECB data level or DECB named as the first parameter is
changed by this function with the address, fa8,
id, and rcc parameters. If either the
address, fa8, or id parameters 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 parameter, 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 using the gdsnc, gdsrc,
or raisa functions. General file users should be aware that
the address or fa8 parameter must be coded as
NULL, as the file address is placed on the FARW level or DECB 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.
- If you specify FILE_NOTAG, the TPF system bypasses the system code that
updates the record header with the program identification. If you omit
FILE_NOTAG, the TPF system places the program identification in the record
header.
- TPF transaction services processing affects file_record_ext
processing in the following ways:
- Hardening to the DASD surface will only occur at commit time.
- When rollback occurs, file_record_ext 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, processing
ends as if a rollback was issued.
- waitc processing does not report hardware errors for
NOREL when the waitc function is issued within 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 completes, the file address will be unheld and any waiting
requests will be serviced.
- Files to general files or general data sets are not considered part of the
commit scope and are not affected by commit scope processing.
- 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 writes the data in the working storage block on level
D7 to a general data set, bypasses the record header update, and releases the
block. The id is CD, the rcc is zero, and the
file address is taken from the forward chain field of another record.
On return, the file copy of the record is available to other ECBs.
·
·
·
file_record_ext(D7,(const unsigned int *)&(inm->im0fch),CD,'\0',
UNHOLD,FILE_NOTAG|FILE_GDS);
The following example writes the data in the working storage block on a
DECB and unholds the record. The file address and record
id are specified in the DECB.
#include <tpfio.h>
TPF_DECB *decb
·
·
·
file_record_ext(decb, NULL, NULL, '\0', UNHOLD, FILE_NOTAG);
Related Information
See TPF Application Programming for more
information about DECBs.