gtpa2m3fApplication Programming

Summary of File Reference Functions and Macros

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

Using Assembler Language File Reference Macros

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.

Using C Language File Reference Functions

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. */