Change User Space Data

ChgUsrSpace

The ChgUsrSpace procedure changes data in a *USRSPC (user space) object.

The ChgUsrSpace procedure can be used to change the data in an existing user space object. The substring parameters allow the entire user space to be changed or only a portion to be changed.

user-space-data  ChgUsrSpace(
 szUserSpace  21A    Const 
 nStart       10I 0  Const OPTIONS(*OMIT) 
 nLength      10I 0  Const OPTIONS(*OMIT) 
 szData    32766A    Const VARYING
)

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  [optional ] DFT(1)

[input Int(4) const]  The starting position within the user space where the data is changed. This parameter must be less than the length of the user space and greater than zero. If *OMIT is specified for this parameter, it defaults to 1.

 

nLength  [optional] DFT( %len(szData))

[input Int(4) const]  The number of bytes to change in the user structure. If the parameter is less than zero the length used is that of the szData parameter. If this value is greater than the length of the szData parameter, the additional positions are padded (on the right) with blanks. If *OMIT is specified for this parameter, the length of the user space is used.

szData

[input VChar(*) const]  The data to insert into the user space. This parameter contains the data that is to be written to the user space. The value specified for this parameter may be either a traditional character field or a character field with the VARYING keyword. In addition, the %SUBST built-in function may be useful in specifying the data for this parameter.

Return Value

If the user space is changed, *ON is returned, otherwise *OFF is returned.

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 changed.

Remarks

Use caution when calling this procedure without a second or third parameter. The following statement, for example, will cause the entire user space to be cleared.

     C                   callp     ChgUsrSpace(szUS : *OMIT : *OMIT : ' ')

Example

A user space may be used in place of a data area or a "control" file. A user space may be up to 16 megabytes in length; far surpassing the maximum length of a data area.

.....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                   eval      szNextCust = GetUsrSpace(szUS:1:7)

     C                   eval      nNextCust = CharToNum(szNextCust) + 1

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

This example calls the ChgUsrSpace() procedure to change the first 7 bytes of the user space named CONTROLS in the QGPL library.