Allocate/extend/return storage in user stack

DSA allocation code sequences must be used whenever a DSA is required and/or needs to be extended. The generated code and the Language Environment and member libraries use code sequences such as the following examples. Rules which must be followed are:

A DSA allocated in the Language Environment user stack must be in the Language Environment format. Storage management expects the CEEDSANAB field to be located at offset X'4C' from the start of the DSA. Figure 1 shows the format of a Language Environment DSA.
Stack storage must be requested in doubleword increments, and is obtained from the stack in doubleword increments. This ensures that a DSA begins on a doubleword.

Figure 1 shows an example of the code sequence to allocate a DSA in the user stack when the calling routine is known to pass the Language Environment Anchor Area address in R12. R13 points to a valid DSA containing the current next available byte address, CEEDSANAB. Note that R13 is set to point to the new DSA only after the new DSA has been completely constructed.

Figure 2 shows an example of a code sequence that gets additional storage appended to the DSA in the user stack. Note that the DSA extension is not guaranteed to be contiguous with the DSA.

Figure 3 shows an example of a code sequence freeing a DSA extension. The code sequence depends upon the proper initialization of CEEDSAPNAB (prolog NAB) before the DSA is extended. Member languages can save the prolog NAB in CEEDSAPNAB or elsewhere. The NAB value is the DSA address as it has been acquired by prolog code and before it is extended. There is no Language Environment requirement to use the CEEDSAPNAB field for this purpose when allocating user stack extensions. However, there is a Language Environment requirement to use CEEDSAPNAB when allocating from the Library stack.

Note: If the STACK(,,,FREE) runtime option is in effect, empty user stack segments are returned to the operating system at the next stack overflow request, or at termination.

The DSA stack storage in the current user stack segment is automatically freed when R13 is updated by the L 13,4(,13) instruction at procedure or block termination. Freeing stack storage occurs because the current NAB is always accessed from the DSA pointed to by R13 when a routine is entered.

The registers do not need to be those shown in the examples as long as the interface to the stack overflow routine, whose address is contained in CEECAAGETS, adheres to the following conditions:

The stack overflow routine is called with a BALR instruction. R15 contains the entry point address of the stack overflow routine and R14 the address of the next sequential instruction in the caller routine.
R0 contains the newly generated NAB address from the BALR instruction. That is, it would have been the NAB address if the segment were long enough. This value and the information in the DSA allows the stack overflow routine to determine the minimum amount of storage to obtain for the next stack segment.
R13 contains the address of the last DSA in the stack and this DSA contains a valid NAB value.