The Create Memory Allocation (CRTMEMAXCL) command creates a memory allocation providing additional storage for the CL program.

The program is responsible for deleting this memory allocation when it it no longer needed. To delete the memory allocation the program uses the Delete Memory Allocation (DLTMEMAXCL) command. The DLTMEMAXCL command requires that either the exact same PTR value returned by CRTMEMAXCL be passed to DLTMEMAXCL or that the same NAME value be used.

This function is also available with command CRTMEMALC 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.

Parameters

Pointer (PTR)

Specifies the CL variable to receive a pointer to the first byte of the allocated memory.

Due to CL commands not allowing CL variables of TYPE(*PTR) to be passed as a parameter the CL pointer variable must be passed indirectly by declaring the pointer variable as being defined on a character variable. The following demonstrates how to do this.

Dcl        Var(&Chr_Ptr) Type(*Char) Len(16)
Dcl        Var(&Pointer) Type(*Ptr) Stg(*Defined) +
             DefVar(&Chr_Ptr)
CrtMemAXCL Ptr(&Chr_Ptr)

After the CRTMEMAXCL command runs the pointer variable &Pointer will address the first byte of the allocated memory.

The defined on variable (DEFVAR) must be declared with a minimum length of 16 bytes. The CL pointer variable, declared with TYPE(*PTR), must be defined on a base 1 16-byte boundary of the DEFVAR variable.

character-value

Specify the name of the CL variable to receive the pointer value.

Name (NAME)

Specifies the name to be associated with this memory allocation. This name can be used with other commands such as Retrieve Memory Allocation (RTVMEMAXCL), Change Memory Allocation (CHGMEMAXCL), and Delete Memory Allocation (DLTMEMAXCL) to assist in managing the memory allocation.

character-value

Specify the name to be associated with the memory allocation.

Initial size (SIZE)

Specifies the number of bytes of memory to be allocated.

4096

4096 (4K) bytes of memory will be allocated.

integer

Specify the number of bytes to allocate.

Initialization value (INZVAL)

Specifies the initial value that the allocated memory is to be set to. If this parameter is not specified the memory is not initialized to any specific value.

character

Specify a one byte initial value to use for the created memory allocation.

Examples for CRTMEMAXCL

Example 1: Simple Command Example

Dcl        Var(&Chr_Ptr) Type(*Char) Len(16)
Dcl        Var(&Pointer) Type(*Ptr) Stg(*Defined) +
             DefVar(&Chr_Ptr)
CrtMemAXCL Ptr(&Chr_Ptr) Name(MyName)

This command creates a memory allocation of 4096 bytes. The memory allocation is named MyName and CL pointer variable &Pointer is set to address the first byte of this memory allocation.

Example 2: Complete Example Program

Member MEMAXMP of source file VC2XCL/QCLSRC contains a sample program demonstrating the use of CRTMEMAXCL, CHGMEMAXCL, and DLTMEMAXCL.

Error messages for CRTMEMAXCL

*ESCAPE Messages

XCL5016

Memory allocatin name &1 is in use.

XCL5017

The maximum of &1 memory allocations has been reached.

XCL9002

Function did not complete. See previously listed messages related to possible user errors.

XCL9003

Function did not complete. See previously listed messages for possible cause.

XCL9004

Function did not complete. See previously listed messages for possible cause.

XCL9005

Function did not complete. Contact your service provider.