gtpc2m3mC/C++ Language Support User's Guide

getcc-Obtain Working Storage Block

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

Examples

The following example obtains 6 working storage blocks on levels D2, DC, DF, D7, D9, and D3.

#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.