Retrieve User Space

RtvUsrSpace

The RtvUsrSpace procedure retrieves data from a *USRSPC (user space) object. Unlike the GetUsrSpace procedure, RtvUsrSpace retrieves the user space data and stores it in a parameter variable.

The RtvUsrSpace procedure can be used to retrieve data from an existing user space object. A the substring parameters allow the entire user space to be retrieved or a portion. The retrieve user space procedure may only retrieve or delete/remove text from an existing character field. The original data is not modified by the procedure but is returned to the caller as the return value for the procedure call.

nBytes-returned  RtvUsrSpace(
 szUserSpace     21A    Const 
 nStart          10I 0  Const 
 nLength         10I 0  Const  
 szRtnData    32766A    Options(*VARSIZE)    
)

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.

 

nStart

[input Int(4) const]  The starting position within the user space where the data is retrieved. This parameter must be less than the length of the user space and greater than zero.

 

nLength

[input Int(4) const]  The number of bytes to be retrieved from the user space. If the actual number of bytes returned is the lesser of the value specified for parameter and the length of the user space minus the start position.

 

szRtnData

[input Char(*) ]  A field used as the return buffer for the retrieved information. The retrieved data from the user space is copied to this field. It must be at least as long as the nLength parameter, but no longer than 32766 bytes.

Return Value

The number of bytes retrieved from the user space.

If the function fails, check the XT_ERROR data structure's subfield XT_ERRMSGID for the error message ID indicating why the user space was not created.

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 szUS            C                   Const('CONTROLS  QGPL')

     D szNextCust      S              7A

     D nNextCust       S              7P 0

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

     C                   callP     RtvUsrSpace(szUS:1:7:szNextCust)

     C                   eval      nNextCust = CharToNum(szNextCust) + 1

     C                   callp     ChgUsrSpace(szUS:1:7 : %EditC(nNextCust:'X'))

The call to RtvUsrSpace() retrieves the first 7 bytes of the user space named CONTROLS in the QGPL library. The second line of code converts that value to numeric and assigns it to the numeric field named nNextCust. Then the user space is updated with the new value.