Create User Space for Dynamic Memory, Get Pointer

CrtUsrSpcPtr

The CrtUsrSpcPtr procedure creates a *USRSPC (user space) object in the QTEMP library (unless specified otherwise) and returns a pointer to the user space.

The CrtUsrSpcPtr procedure can be used to create a user space object and immediately retrieve a pointer to the user space. This procedure allows you to use the user space for dynamic memory within RPG IV and C programs more easily. It provides a simplified interface verses using multiple CRT/GET/RTV procedures to accomplish the same task. The user space may be used for any purpose, and is not limited to dynamic memory applications.

ptr-to-user-space   CrtUsrSpcPtr(
 szUserSpace    21A    Const OPTIONS(*NOPASS : *OMIT)
 nSize          10I 0  Const OPTIONS(*NOPASS : *OMIT)
)

Parameters

szUserSpace [ optional ]

[input Char(21) const]  This optional parameter consists of two parts (1) in the first 10 positions, the name of the user space being created, and (2) in the second 10 positions, the name of the library in which the user space is to be created.  For example:

 

 *...v....1....v....2

'MYSPACE   QTEMP     '

 

An alternative syntax is also supported for the user space parameter. The alternate syntax allows you to specify the user space name similar to that of an OS/400 CL command, that is it may be qualified using qualified name syntax, as follows:

 *...v....1....v....2

'QTEMP/MYSPACE       '

 

In this example, the user space name is MYSPACE in the QTEMP library. Either syntax is acceptable.

 

nSize  [optional] DFT(65535)

[input Int(4) const]  The initial size of the user space. The permissible values range from 1 to 16Meg. If this parameter is not specified 65535 is used.

Return Value

If the user space is created, a valid pointer to the user space is returned, otherwise *NULL is returned.

If the function fails, *NULL is returned.

Example

Normally, the command and user space name are the only values that need to be specified. For example:

.....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++

     D ptr             S               *   

     D array           S             10A   DIM(30000) BASED(ptr)

     D szUS            C                   Const('QTEMP/MEMORY')

.....CSRn01..............OpCode(ex)Extended-factor2+++++++++++++++++++++++++++

     C                   eval      ptr = CrtUsrSpcPtr()

     C                   eval      ptr = CrtUsrSpcPtr(szUS : 2000000)

The first call to CrtUsrSpcPtr() creates a user space named QRTK00001 in the QTEMP library, and returns a pointer to that user space into the PTR variable.

The second call to CrtUsrSpcPtr() creates a user space named MEMORY in the QTEMP library and sizes it at 2 megabytes.

Since the ARRAY field (which is an array) contains the BASED keyword, these CrtUsrSpcPtr() calls return a pointer to a user space and maps ARRAY's memory to that user space. This provides dynamic array sizing capabilities.