The Retrieve Memory Allocation Info (RTVMEMAXCL) command retrieves information concerning a memory allocation.
This function is also available with command RTVMEMALC in library VC2XCL. Any use of this alternative command name should be library qualified in case the i operating system were to use this command name in a future release.
Pointer (PTR)
When the NAME parameter is specified the PTR parameter is not used to identify the memory allocation to be retrieved. Rather the pointer value associated with the named memory allocation is returned. If there is no memory allocation associated with the NAME value the pointer value returned is set to null.
When the NAME parameter is not specified the PTR parameter is used to identify the memory allocation to be retrieved. In this case the value of the PTR parameter must be the same as the value returned by the most recent CRTMEMAXCL or CHGMEMAXCL command that referenced the memory allocation.
- character-value
- When the NAME parameter is not used specify a CL pointer variable whose value addresses the first byte of the previously allocated storage. When the NAME parameter is used specify the variable to receive a pointer value addressing the first byte of the memory allocation.
Size (SIZE)
Returns the currently allocated size for the memory allocation identified by either the NAME or PTR parameter.
If NAME is specified and no memory allocation by that name is active a size of 0 is returned.
If NAME is not specified and no memory allocation is active for the provided PTR value message XCL5019 is sent.
Examples for RTVMEMAXCL
Example 1: Retrieving the Original Pointer Value
Dcl Var(&Chr_Ptr) Type(*Char) Len(16)
Dcl Var(&Pointer) Type(*Ptr) Stg(*Defined) +
DefVar(&Chr_Ptr)
CrtMemAXCL Ptr(&Chr_Ptr) Name(MyName)
ChgVar Var(%ofs(&Pointer)) Value(%ofs(&Pointer) + 5)
/* Additional processing is done */
RtvMemAXCL Ptr(&Chr_Ptr) Name(MyName)
This example creates a memory allocation with the name MyName and the pointer variable &Pointer is set to the first byte of the memory allocation. This is done with the CRTMEMAXCL command.
Following this the program changes the value of CL variable &Pointer so that it addresses the sixth byte of the memory allocation. After additional processing the program wants to reset the value of variable &Pointer such that it addresses the first byte of the memory allocation. The RTVMEMAXCL command resets &Pointer (by use of the &Chr_Ptr definition) to the first byte of the named memory allocation MyName.
Example 2: Determining the Allocated Size of a Memory Allocation
Dcl Var(&Size) Type(*Int)
RtvMemAXCL Name(MyStorage) Size(&Size)
This example retrieves the current size in bytes of the memory allocation named MyStorage.
