ALLOC: Allocate space on the application stack

Use this general macro to allow an application to acquire more space on the application stack.

Last updated

  • Changed for PUT15 (information only; no code change).
  • Changed for PUT14.
  • Added for PUT00.

Format

Read syntax diagramSkip visual syntax diagram ALLOC SIZE=value,ADDR= addrreg( sizereg),ADDR= addrreg ,ERROR= label
SIZE
Specifies the size of the application stack area in bytes, where:
value
The number of contiguous bytes of storage to be allocated.
(sizereg)
A general register (R1 - R8 or R10 - R13) that contains a value. To specify this value, you must enclose the register with parentheses.
ADDR=addrreg
Specifies the address of the allocated application stack area, where addrreg is a general register (R1–R8 or R10–R13) that contains a value. This parameter is required when the SIZE parameter is coded as a value. This parameter is optional when the size of the application stack area is passed in a register. If you do not specify this parameter, the address is returned in the SIZE register.
ERROR=label
Specifies an error routine, where label is the label to branch to if the ALLOC macro call could not be completed. An ALLOC macro call will not be completed for the following reasons:
  • The value specified for the SIZE parameter is zero.
  • The value specified for the SIZE parameter is a negative number.
  • There is not enough space in the application stack to satisfy the request.

Entry requirements

  • R9 must equal the entry control block (ECB) address.
  • The register specified on the SIZE and ADDR parameter cannot be one of the defined program base registers.

Return conditions

  • The register specified by the SIZE parameter contains the address at the beginning of the allocated storage.
  • When an error occurs, the register specified by the SIZE or ADDR parameter contains X'00000000' if:
    • The ERROR parameter is coded. If the ERROR parameter is not coded, a system error is issued and the ECB exits.
    • The value specified for the SIZE parameter is zero.
    • The application stack area does not contain enough storage to satisfy the allocation request and it cannot be extended any more.
  • The contents of R10 and R13 - R15 are unknown. All other registers are preserved with the exception of those used by the SIZE parameter.

Programming considerations

  • For information about macro register conventions, see Register conventions.
  • Using the ALLOC macro in C shared object (CSO) assembler code and the BEGIN macro coded with the TPFISOC=YES parameter, affects stack addressability in code in the following ways:
    • z/TPF prolog macros PRLGC and TMSPC initialize a register with the address of the base of the current stack frame. The ALLOC macro establishes a new location for the beginning of the application stack and loads the new address into the stack register. If you have used the stack register for something other than the stack pointer, you must save and restore it across the ALLOC macro call.
    • Using the ALLOC macro establishes a new address for the stack frame so that the space allocated with the FRAMESIZE parameter (coded on the PRLGC macro) is no longer available at ICST_PAR after the ALLOC macro is called. Ensure that you save the address of the additional space before you run ALLOC.
  • Do not issue the ALLOC macro after an ALASC macro on the same nesting level in a program. Otherwise, register 7 (R7) does not point to the auto-storage area when processing returns from the ENTRC macro that is run after the ALLOC macro.

Examples

  • The following example allocates 100 bytes of area that you can use on the application stack. 
    ALLOC SIZE=100,ADDR=R3,ERROR=NO_SPACE
  • The following example allocates an area that you can use on the application stack based on a work DSECT. 
    LA     R5,WORK_LEN
ALLOC  SIZE=(R5)
USING  WORK,R5