getfc: Obtain file pool address

This function obtains a file address (and optionally, a working storage block) based on attributes associated with a record ID.

Last updated

  • Changed for PUT14 (information only; no code change).
  • Changed for PUT05.

Format

#include     <tpf/tpfio.h>
unsigned int getfc(enum t_lvl level, int type, const char *id, int block,
                   int error, ... );
or 
#include     <tpf/tpfio.h>
TPF_FA8      getfc(TPF_DECB *decb, int type, const char *id, int block,
                   int error, ...);
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). This parameter represents an available file address reference word (FARW) location where the file address will be placed.
decb
A pointer to a data event control block (DECB). This parameter represents an available FARW location where the file address will be placed.
type
Specify a pool type attribute with the defined terms GETFC_TYPE0 through GETFC_TYPE9 associated with the id in the record ID attribute table (RIAT). The defined terms GETFC_PRIME and GETFC_OVERFLOW are still supported for migration purposes only. GETFC_PRIME corresponds to GETFC_TYPE0, and GETFC_OVERFLOW corresponds to GETFC_TYPE1.
id
A pointer to a 2-character string bearing the record ID for which this file allocation is to take place. This ID is used to scan the RIAT table for a match to determine record size and pool type.
block
Whether or not a working storage block is to be simultaneously obtained whose characteristics are determined by the RIAT table. Code GETFC_BLOCK to obtain a block and a file address, or GETFC_NOBLOCK to obtain only a file address.

Additionally, when GETFC_BLOCK is specified, you can code one or both of the terms GETFC_COMM and GETFC_FILL. If you code more than one term for the block parameter, you must separate them with a logical OR (|) sign. See the example that follows. GETFC_COMM indicates that a common block is to be acquired for the GETFC_BLOCK option. GETFC_FILL along with GETFC_BLOCK indicates that the block acquired should be initialized with the fill character, FILLC, specified as the first optional parameter. GETFC_NOCOMM and GETFC_NOFILL, meaning not common block and no fill, respectively, are the defaults and need not be coded.

If the GETFC_FILL option is not specified, the storage block contents are unpredictable, unless the SYSTC tag SBCLEAR is set on. If SBCLEAR is set on, the system clears all blocks with zeros when the blocks are assigned to the ECB. The GETFC_FILL option has priority over the SBCLEAR setting.

error
Whether or not control is to be returned to the operational program in the event of an error. Code GETFC_SERRC to transfer control to the system error routine (with exit) if the file or core storage cannot be obtained, as requested. Code GETFC_NOSERRC to have control returned to the caller.
...
The character used to initialize the block if GETFC_BLOCK and GETFC_FILL are both specified. (The fill character may be specified in hexadecimal.)

Normal return

Unsigned integer value representing a file address, or an 8-byte file address defined as type TPF_FA8.

Error return

Integer value of zero if GETFC_NOSERRC is coded; otherwise, loss of control and system error with exit.

Programming considerations

  • The record ID specified as parameter id must exist in the RIAT table.
  • The CBRW specified by the level or the decb parameter must be unoccupied if GETFC_BLOCK is coded.
  • Use of this function may result in the equivalent of a waitc.
  • File pool addresses that are acquired in a global transaction (that is, after a tx_begin function call but before a tx_commit or tx_rollback function call) will be released if the transaction is rolled back using a tx_rollback function call.
  • 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 the CTAD library.
  • Use the ZGFSP GFI command to turn on or turn off get file initialization (GFI) processing.

Examples

The following example obtains file storage for a message block on level D2 and obtains a working storage block of the appropriate size on the same level. 
#include <tpf/tpfio.h>
#include <tpf/c_am0sg.h>
struct am0sg *amsg               /* pointers to message blocks    */
⋮
amsg = ecbptr()->ce1cr1;         /* Base prime message block      */
if (!(amsg->am0fch = getfc(D2,GETFC_TYPE1,"OM",GETFC_BLOCK|GETFC_FILL,
                              GETFC_NOSERRC,' ')))
  exit(0x33001);                 /* Dump w/exit if getfc() failed */
The following example obtains file storage for a message block on the DECB and obtains a working storage block of the appropriate size on the same DECB. 
#include <tpf/tpfio.h>
#include <tpf/c_am0sg.h>
TPF_FA8 address;
TPF_DECB     *decb;
⋮
if (!(address = getfc(decb,GETFC_TYPE1,
                      "OM",(int)(GETFC_BLOCK+GETFC_FILL),
                      GETFC_NOSERRC,' ')))
   exit(0x33001);                 /* Dump w/exit if getfc failed */