Get Pointer to User Space

GetPtrUS

The GetPtrUS procedure retrieves a pointer to a user space (*USRSPC) object.

The GetPtrUS procedure can be used to retrieve a pointer to a user space. The pointer may then be used within RPG IV to read or modify the data in the user space.

ptr-to-UserSpace  GetPtrUS(
 szUserSpace  21A    Const
)

Parameters

szUserSpace

[input Char(21) const]  User Space name. This parameter consists of two parts (1) in the first 10 positions, the name of the user space, and (2) in the second 10 positions, the name of the library containing the user space 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       '

 

The qualified user space name is MYSPACE in the QTEMP library. Either syntax is acceptable.

 

Return Value

The a pointer to the user space named in the szUserSpace parameter.

If the function fails, check the XT_ERROR data structure's subfield XT_ERRMSGID for the error message ID which may indicate why the pointer was not returned. The XT_ERRRLen subfield can be used to easily determine if an error occurred. If XT_ERRRLen is zero, no error occurred, and other value indicates an error condition, and you should inspect the XT_ERRMsgID field for the specific error.

Remarks

There are various names for this this procedure. The recommended name is GetPtrUS, however you may also call this procedure using any of the following alias names.

• GetUsrSpacePtr
• GetPtrUsrSpace
• GetPtrUserSpace
• GetPtrUS

If name collision occurs with a procedure name that you have written, you may remove the prototype for any of these procedures from the SPACE include source member, except GetUserSpacePtr which is the actual procedure name.

Example

If a pointer to the user space is retrieved, the user space may be used as storage for variables in your program, thus reducing the memory requirements for the program.

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

     D CustSalesTot    S              7P 2 Dim(32766) Based(pArr)

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

     C                   eval      CrtUsrSpace('QTEMP/YEAREND')

     C                   eval      pArr = GetPtrUS('QTEMP/YEAREND')

     C                   eval      CustSalesTot(1500) = 100.00

This call to GetPtrUS() retrieves the pointer to the user space named YEAREND in the QTEMP library. The pointer is stored in the pArr variable on which the CUSTSALESTOT (Customer Sales Totals) array is based. This causes the storage for the array to be the user space instead of real memory. Effectively this creates a dynamic, automatically extendable array.