gtpc2m3rC/C++ Language Support User's Guide

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.

Format

#include     <tpfio.h>
unsigned int getfc(enum t_lvl level, int type, const char *id, int block,
                   int error, ... );

or

#include     <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 block, 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.

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

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 <tpfio.h>
#include <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 <tpfio.h>
#include <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 */

Related Information

See TPF Application Programming for more information about DECBs.