gtpc2m3m | C/C++ Language Support User's Guide |
This function obtains and attaches a working storage block to the indicated
entry control block (ECB) data level or data event control block
(DECB).
Format
This function has four formats depending on the type of parameters
coded:
#include <tpfapi.h>
void *getcc(enum t_lvl level, enum t_getfmt format, spec1);
or
#include <tpfapi.h>
void *getcc(enum t_lvl level, enum t_getfmt format, spec1, spec2);
or
#include <tpfapi.h>
void *getcc(TPF_DECB *decb, enum t_getfmt format, spec1);
or
#include <tpfapi.h>
void *getcc(TPF_DECB *decb, enum t_getfmt format, spec1, spec2);
- level
- One of 16 possible values representing a valid 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 core block reference word (CBRW) on which
the requested working storage block will be placed.
- decb
- A pointer to a DECB. This parameter represents an available CBRW on
which the requested working storage block will be placed.
- format
- For this parameter you must specify at least one term of enumeration type
t_getfmt, defined in tpfapi.h, to determine how
storage is allocated. Additionally, you can code the terms GETCC_FILL
and GETCC_COMMON or GETCC_PROTECTED. If you code more than one term for
format, you must separate terms with a plus sign
(+). See the examples that follow.
The required term can be one of the following:
- GETCC_TYPE
- Use this term to specify a logical block type. Code the logical
block as the third parameter (spec1). The record ID
attribute table (RIAT) is not accessed for this request. Use one of
these predefined terms:
- L0
- 127 bytes
- L1
- 381 bytes
- L2
- 1055 bytes
- L4
- 4095 bytes.
- GETCC_SIZE
- Use this term to specify the number of bytes of storage you need.
Specify the number of bytes you need as an integer and as the third parameter
(spec1). The RIAT table is not accessed for this
request. The smallest available block size that satisfies the request
is used. Requests for working storage in excess of 4095 bytes result in
a system error with exit.
- GETCC_ATTR0,...GETCC_ATTR9, GETCC_PRIME, or
GETCC_OVERFLOW
- Use one of these terms to specify a 2-character record ID to be used to
scan the RIAT table for pool-type attributes specified by the ID for the ATTRx
definition. Specify the 2-character record ID as the third parameter
(spec1). GETCC_PRIME and GETCC_OVERFLOW are still supported
for migration purposes only. Their values correspond to GETCC_ATTR0 and
GETCC_ATTR1, respectively.
In addition, you can code one or both of the following terms:
- GETCC_FILL
- Code this term to initialize the allocated storage to a specified hex
value. Specify the hex value as the fourth parameter
(spec2). If GETCC_FILL is not coded, the storage is not
initialized.
- GETCC_COMMON
- Code this term to obtain storage from the pool of shared main
storage. If you do not code GETCC_COMMON or GETCC_PROTECTED, the
storage is not allocated from shared main storage.
- GETCC_PROTECTED
- Code this term to obtain storage from the pool of shared main
storage. The storage is key protected. If you do not code
GETCC_COMMON or GETCC_PROTECTED, the storage is not allocated from shared main
storage.
- spec1
- The getcc function always requires a third parameter depending
on what term is coded for format.
If GETCC_TYPE is coded, spec1 must be a logical block
type.
If GETCC_SIZE is coded, spec1 must be an integer indicating the
number of bytes of storage you need.
If one of GETCC_ATTR0 through GETCC_ATTR9, GETCC_PRIME, or GETCC_OVERFLOW
is coded, spec1 must be a 2-character record ID in double
quotes.
- spec2
- If GETCC_FILL is coded, you must code a fourth parameter specifying the
hex value to which you want storage initialized.
Normal Return
Pointer to the newly obtained working storage block.
Error Return
Not applicable.
Programming Considerations
- Only 1 storage block at a time can be obtained through this
function.
- The indicated ECB data level or DECB must be unoccupied when this function
is called.
- Working storage blocks should be released at the first possible
opportunity in order to avoid storage depletion.
- If there is no working storage, an incorrect RIAT ID is specified, an
incorrect block type is specified, or a working storage block is already
attached at the specified ECB data level or DECB, the result is a system error
with exit.
- 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 6 working storage blocks on levels D2, DC,
DF, D7, D9, and D3.
- The first is a RIAT-specified block of attribute 0.
- The second is a block-type call.
- The third is a self-defining size call for storage from the pool of shared
main storage.
- The fourth is block-type call initializing the block to blanks.
- The fifth is a block-type call for storage from the pool of shared main
storage, initializing the block to blanks.
- The sixth is a block-type call for storage from the pool of shared main
storage, setting the block to storage key protected and initializing the block
to zeros.
#include <tpfapi.h>
#include <c$am0sg.h>
struct am0sg *amsg1; /* pointers to message blocks */
char *work1, *work2, *work3, *work4, *work5;
·
·
·
amsg1 = (struct am0sg *) getcc(D2, GETCC_ATTR0, "OM");
work1 = (char *) getcc(DC, GETCC_TYPE, L2); /* Attaches 1055-byte block */
work2 = (char *) getcc(DF, (enum t_getfmt) (GETCC_SIZE+GETCC_COMMON), 1100);
/* Attaches from shared storage a
4095 byte block since the requested
size will not fit in a 1055/L2 block */
work3 = (char *) getcc(D7, (enum t_getfmt) (GETCC_TYPE+GETCC_FILL), L2, ' ');
/* Attaches a 1055 byte block
initialized to blanks */
work4 = (char *) getcc(D9, (enum t_getfmt) (GETCC_TYPE+GETCC_FILL+GETCC_COMMON), L4, ' ');
/* Attaches a 4095 byte block
from the pool of shared
main storage and initializes
it to blanks */
work5 = (char *) getcc(D3, (enum t_getfmt) (GETCC_TYPE+GETCC_PROTECTED+GETCC_FILL), L4,0x00);
/* Attaches a 4095 byte block
from the pool of shared main
storage, sets the block to
storage key protected and
initializes it to zeros */
The following example uses DECBs to get storage blocks instead of ECB data
levels.
#include <tpfapi.h>
#include <c$am0sg.h>
struct am0sg *amsg1; /* pointers to message blocks*/
TPF_DECB *decb1, *decb2, *decb3, *decb4, *decb5, *decb6;
char *work1, *work2, *work3, *work4, *work5;
·
·
·
amsg1 = (struct am0sg *) getcc(decb1, GETCC_ATTR0, "OM");
work1 = (char *)getcc(decb2, GETCC_TYPE, L2); /* Attaches 1055-byte block */
work2 = (char *)getcc(decb3,(enum t_getfmt)(GETCC_SIZE+GETCC_COMMON), 1100);
/* Attaches from shared storage a
4095 byte block since the requested
size will not fit in a 1055/L2 block */
work3 = (char *)getcc(decb4,(enum t_getfmt)(GETCC_TYPE+GETCC_FILL), L2, ' ');
/* Attaches a 1055 byte block
initialized to blanks */
work4 = (char *)getcc(decb5,(enum t_getfmt)(GETCC_TYPE+GETCC_FILL+GETCC_COMMON), L4, ' ');
/* Attaches a 4095 byte block
from the pool of shared
main storage and initializes
it to blanks */
work5 = (char *)getcc(decb6,(enum t_getfmt)(GETCC_TYPE+GETCC_PROTECTED+GETCC_FILL), L4,0x00);
/* Attaches a 4095 byte block
from the pool of shared main
storage, sets the block to
storage key protected and
initializes it to zeros */
Related Information
See TPF Application Programming for more
information about DECBs.