Use this system macro to obtain contiguous storage in the entry control
block (ECB) virtual memory (EVM).
Format
- label
- A symbolic name can be assigned to the macro statement.
- STORAGE=Rx
- This parameter specifies the number of contiguous 4 K byte pages to be
allocated. You must use the general register R0 through R7, R14, or
R15.
- SAVREG
- The specified volatile registers will be saved by the macro in
the stack area or in the registers specified by the WKREG parameter. Up
to 3 registers can be specified. Those registers are R0, R1, R2.
If this keyword is omitted, none of the 3 registers will be saved. You
should not save a volatile register if you expect it to contain an output
parameter. The register will be overwritten with its original contents,
since the reload is the last thing performed by the macro.
- WKREG
- The specified symbolic register names are free to be used by the macro to
save the volatile registers coded on the SAVREG parameter.
Up to 3 registers can be specified, but the standard linkage registers R13
through R2 cannot be used here. This parameter is used in conjunction
with the SAVREG parameter to generate efficient code and enhance the
performance of the macro. The number of registers specified by WKREG
should be less than or equal to the number of registers specified by
SAVREG. If this parameter is omitted or not used to its maximum
capacity, code optimization is sacrificed.
Entry Requirements
- This macro can be run from the entry control block (ECB) virtual memory
(EVM) or the system virtual memory (SVM).
- This macro is for use in the control program (CP) only while running key 0
and in supervisor state.
- R9 must point at the ECB that will use the contiguous storage.
Return Conditions
- On output, if there is sufficient virtual storage available, the register
specified as the STORAGE parameter will contain the address of the start of
the allocated storage.
- Note:
- The storage acquired will be allocated in the EVM as part of the total ECB
unique storage available to the ECB. It may be located above the 16
megabyte boundary. This address returned will be valid in the 31 bit
addressing mode only.
- The STORAGE register will contain X'00000000' if there is
insufficient virtual storage available for allocation. Control is
returned to the NSI.
- When main storage blocks are exhausted, a catastrophic system error
results, since insufficient real storage exists to satisfy the request.
Control is not returned.
- If corruption is detected in the heap, a catastrophic system error is
issued and the ECB exits immediately. Control is not returned.
Programming Considerations
- This macro can be run on any I-stream, however it must be processed on the
same I-stream specified in the CE1ISN field in the associated ECB.
- This macro is restricted to control program (CP) use only. The
analogous general use macros are MALOC, CALOC, and RALOC for assembler
programs and the malloc, calloc, and realloc
library functions for C language programs.
- $GMNBC storage is not contiguous in the SVM.
- The amount of virtual storage available for use as ECB unique storage is
limited.
- Storage acquired by using the $GMNBC macro is returned automatically at
ECB exit (EXITC) time. Storage can also be returned at any time by
using the $RMNBC macro from the control program (CP).
- Use of the $RMNBC macro can have a substantial negative performance impact
on a TPF system in a multi-processor (tightly coupled) configuration so use of
this macro should be limited.
Examples
None.