gtpa2m3f | Application Programming |
Following is a summary of the find and file functions or macros, listed in
alphabetic order. Basic and higher-level function types are so
noted.
Table 22. File Reference Functions or Macros
Function or Macro
| Summary
| Type
|
filec
| File a Record -- Causes the TPF system programs to write a record
to file. Both copies of the record will be updated if the record is
duplicated.
The application program supplies the file address, record identification,
and record code check in the ECB data level FARW specified in the function
call. The block of storage is returned to the appropriate storage pool
following the I/O operation. No waitc should be used with
this function; once filec is called, the application program
cannot determine the status of the operation, and so cannot know whether I/O
is complete.
| Basic
|
file_record (C language only)
| File a Record -- Causes the TPF system programs to write a record
to file. Both copies of the record are updated if the record is
duplicated.
The application program supplies the file address, record identification,
and record code check in the function call, in addition to the data level of
the CBRW that points to the record to be filed and the type of hold status to
be associated with the record. One of 3 disposition types may be
applied:
- Type
- Disposition
- NOHOLD
- The record written was not previously in hold status, and its associated
block of storage will be returned to the appropriate storage pool following
the I/O operation.
- UNHOLD
- The record's file address must have been held by the issuing ECB prior
to the function call. Upon return, the record written will be removed
from hold status, and its associated block of storage will be returned to the
appropriate storage pool.
- NOREL
- The record written was not previously in hold status, and its associated
working storage block will not be returned to the system.
A programmer must code a waitc after a function call of this
type only to determine the status of the file operation; the
status of the operation cannot be determined for NOHOLD and
UNHOLD calls, so waitc should not be used for these
cases.
| Higher-level
|
filnc
| File a Record with No Release -- Causes TPF to write a record to
file storage like filec, and requires the same application program
input as filec. However, TPF does not return the block of
storage containing the record to the storage pool, which leaves the block
available to the application program after completion of the write.
Because this function, unlike all other file functions, does not release the
storage block, you must call waitc to ensure completion of the
operation.
If an error occurs during filing, TPF returns control to the system error
routine.
| Basic
|
filuc
| File and Unhold a Record -- Provides the same function as
filec. However, the record is unheld before it is written to
file storage. If another request to hold the record is pending, then a
TPF system program effects a main-storage-to-main-storage move that saves a
file access. (However, if the hold request is from another TPF system
in a loosely coupled environment, then the record will be filed just as though
there had been no hold request.)
| Basic
|
findc
| Find a File Record -- Reads a record from file storage into main
storage. The application program places the file address, and,
optionally, the record identification and record code check, in the ECB data
level FARW specified in the function instruction. A block of storage is
obtained as a read-in area by TPF system programs and reference to the block
is placed in the appropriate CBRW. You must call waitc to
ensure completion of the I/O operation.
| Basic
|
find_record (C language only)
| Find a File Record -- Reads a record from file storage into main
storage. A block of storage is obtained as a read-in area by TPF system
programs and reference to the block is placed in the appropriate CBRW.
This function performs the equivalent of a waitc call, which
ensures completion of the I/O operation.
The application program supplies in the function argument the file address,
and, optionally, the record identification and record code check, in addition
to a CBRW and FARW data level for system use, and the intended hold status for
the record. Either of 2 types of hold may be applied:
- Type
- Disposition
- NOHOLD
- The record address will not be placed in the record hold table following
the I/O operation.
- HOLD
- The record address will be placed in the record hold table following the
I/O operation. The application is responsible for ensuring that the
record is removed from the record hold table prior to calling the
exit function.
| Higher-level
|
finhc
| Find and Hold a File Record -- Performs the same function as the
findc function, in addition to including the record hold feature,
which reserves a data record for the exclusive use of an entry during an
update of the record.
| Basic
|
finwc
| Find a File Record and Wait -- Performs the same function as the
findc function while including an additional
waitc. Thus, the application program need not call a
separate waitc function to ensure completion of the I/O
operation. TPF returns control to the system error routine on an error
or abnormal I/O operation.
| Basic
|
fiwhc
| Find a File Record, Wait, and Hold -- Includes all of the
functionality of finhc with an additional waitc, as
described for finwc, above.
| Basic
|
unfrc
| Unhold a File Record -- Causes the system service routines to
unhold a record whose file address is contained in the ECB data level FARW
specified in the function call. This function does not cause any
records to be accessed.
| Basic
|
In assembler language, all file reference macros require the ECB data level
or DECB referencing the transfer as a parameter. In addition, the
combination macros that
include a WAITC must specify a label in the application program to which
control will be transferred in any abnormal I/O operations. The
application must then contain the logic to test the I/O indicators in the ECB
(CE1SUG) to determine the nature of the abnormality and to specify the action
to be taken.
Here are some macro coding examples:
FINDC D1 Find record, data level 1
WAITC ERROR1
FINWC D1,ERROR1 Find record, & wait, data level 1
FIWHC D2,ERROR2 Find record, & wait, hold file address,
data level 2
FILEC D6 File record, data level 6
FILNC D6 File record, do not release main storage
WAITC ERROR block, data level 6
FILUC D6 File record, unhold file address, data
level 6
UNFRC D6 Unhold file address, data level 6
- Note:
- Two specialized file retrieval macros--FNSPC (find a special record)
and FDCTC (file data chain transfer)--do not examine the VFA area when
searching for records. Therefore, when VFA delayed-filing is active,
these 2 macros may retrieve records from file storage when more recently
updated copies of the records exist in VFA. See the TPF Database Reference for more information about virtual
file access.
The following TARGET(TPF) example retrieves a data record from file on
level D1 or aborts if the retrieve is unsuccessful.
#include<tpfio.h>
·
·
·
findc(D1);
if (waitc())
{
serrc_op(&EXIT.,0x1234,"I/O ERROR OCCURRED",NULL);
/* serrc_op replaced the TARGET(TPF) exit: */
/* errno = 0x1234; */
/* perror("I/O ERROR OCCURRED"); */
/* abort(); */
}
The following example retrieves a data record from a general file onto
level D2. The file address has already been computed and
resides in the level D2 FARW. Control is returned to the
operational program when the I/O has completed and the record has been
attached to the specified level.
#include<tpfio.h>
struct im0im *inm;
·
·
·
inm = finwc_ext(D2,FIND_GDS);
The following example retrieves a data record from file on level
D2 with hold. The file address has already been computed and
resides in the level D2 FARW. TPF returns control to the
operational program when the I/O has completed and the record has been
attached to the specified level.
#include<tpfio.h>
struct im0im *inm;
·
·
·
inm = fiwhc(D2);
The following example writes the data in the working storage block on level
D6 to a general data set, bypasses the record header update, and
releases the block.
#include<tpfio.h>
·
·
·
filec_ext(D6,FILE_GDS|FILE_NOTAG);
The following TARGET(TPF) example writes the data in the working storage
block on level D6 to file or aborts if the retrieve is
unsuccessful. The working storage block remains attached to the data
level.
#include<tpfio.h>
·
·
·
filnc(D6);
if (waitc())
{
serrc_op(&EXIT.,0x1234,"I/O ERROR OCCURRED",NULL) ;
}
The following example writes the data in the working storage block on level
D6 to file, bypasses the record header update, and releases the
block. The file copy of the record is available to other ECB's on
return.
#include<tpfio.h>
·
·
·
filuc_ext(D6,FILE_NOTAG)
The following example finds a message block on level 6 with hold and then
removes the address from the record hold table.
#include<tpfio.h>
#include<c$am0sg.h>
struct am0sg *PRIME, *chain; /* Pointers to message blocks */
·
·
·
PRIME = ecbptr()->ce1cr1; /* Base prime message block */
/* Read first chain record with hold */
chain = find_record(D6,(unsigned int *)&(PRIME->am0fch),
"OM",'\0',HOLD);
unfrc(D6); /* Now remove the chain address from the */
/* record hold table. */