gtpc2m3r | C/C++ Language Support User's Guide |
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
- 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 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 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.