The Change User Space (CHGUSRSPC) Command

The Change User Space (CHGUSRSPC) command changes the content of a User Space (USRSPC) object. A USRSPC object is MI space object with object type code/subtype code hex 1934. This command can be used either interactively or in a CL program. The key difference between CHGUSRSPC and the Change User Space (QUSCHGUS) API is that the QUSCHGUS API cannot preserve the of validity of pointers written into a USRSPC, while the CHGUSRSPC command can write system pointers or space pointers into a USRSPC and the pointers written into the USRSPC will remain valid. As we know that system pointers to permanent objects will remain valid even across IPLs, so do space pointers addressing associated spaces of permanent objects, so these pointers stored in a USRSPC can be re-used by other applications repeatedly, and with no relation to the job who wrote them into the USRSPC.

Parameters

Keyword	Description	Choices	Notes
USRSPC	User space	Qualified object name	Required, positional 1.
	Qualifier 1: User space	Name
	Qualifier 2: Library	Name, *LIBL
OFFSET	Offset into space	0 to 16M - 1Page	Optional
DTATYPE	Data type	SCALAR, PTR	Optional
DTA	Value of scalar data	Scalar data in character or hexadecimal format	Optional
DTALEN	Length of scalar data, *CALC	1 - 32767	Optional
PTRTYPE	Pointer type	SYP, SPP	Optional
SYSOBJ	System object	Qualified object name	Optional
	Qualifier 1: User space	Name
	Qualifier 2: Library	Name, *LIBL
OBJTYPE	Object type	ALRTBL AUTL BNDDIR CFGL CHTFMT CLD CLS CMD CNNL COSD CRG CRQD CSI CSPMAP CSPTBL CTLD DEVD DOC DTAARA DTADCT DTAQ EDTD EXITRG FCT FILE FLR FNTTBL FNTRSC FORMDF FTR GSS IGCDCT IGCSRT IGCTBL IMGCLG IPXD JOBD JOBQ JOBSCD JRN JRNRCV LIB LIND LOCALE MEDDFN MENU MODD MODULE MSGF MSGQ MGTCOL M36 M36CFG NODL NODGRP NTBD NWID NWSCFG NWSD OUTQ OVL PAGDFN PAGSEG PDFMAP PDG PGM PNLGRP PRDAVL PRDDFN PRDLOD PSFCFG QMFORM QMQRY QRYDFN RCT S36 SBSD SCHIDX SPADCT SQLPKG SQLUDT SRVPGM SVRSTG SSND TBL TIMZON USRIDX USRPRF USRQ USRSPC VLDL WSCST	Optional
SPPOFFSET	Offset value of space pointer	0 to 16M - 1Page	Optional

USRSPC

Sepecifies the user space the content of which to be changed.

Qualifier 1: User space

name Specify the name of the user space.

Qualifier 2: Library
Library in which the user space resides. Default to *LIBL.

OFFSET

Offset in the space object's associated space. Unlike the Start position parameter of the QUSCHGUS API, this offset value is start from 0, and should not be larger than 16M - 1Page.

Remarks:: When writing a pointer value into the target user space, the value specified for this paramter is automatically rounded to 16-byte boundary.

DTATYPE

Specifies the type of data to be written into the user space. Default to *SCALAR. Valiad values are:

*SCALAR Write scalar data into the target user space.
*PTR Write pointer data into the target usre space.

DTA

Scalar data in character or hexadecimal format that will be written into the target user space.

DTALEN

Length of the scalar data to be written into the target user space. Default to *CALC, in which case the length of the input scalar data will be calculated automatically.

PTRTYPE

Type of the pointer to be written into the target user space. Default to *SYP. Valid values are:

*SYP System pointer
When PTRTYPE(*SYP) is specified, CHGUSRSPC will try to write the system pointer to the object identified by parameter SYSOBJ.
*SPP Space pointer
The pointer to be written into the target USRSPC is a space pointer.

Remarks:: CHGUSRSPC now supports two type of pointers to be written into a user space object, system pointer and space pointer, which are the most commonly used pointer types in IBM i applications.

SYSOBJ

When DTATYPE(*PTR) is specified, the SYSOBJ parameter must be set to a valid objet name. If PTRTYPE(*SYP) is specified, a system pointer the the object specified by this paramter is to be written into the target user space. If PTRTYPE(*SPP) is specified, a space pointer addressing the associated space of the object specified by this parameter is to be written into the target user space. See SPPOFFSET for more information.

OBJTYPE

Specifies the object type of SYSOBJ.

Remarks:: Note that the OBJTYPE parameter expects an external object type. CHGUSRSPC will convert the external object type to the corresponding MI object type before resolving the system pointer to the target MI object. For example, CHGUSRSPC SYSOBJ(SOMELIB/SOMEFILE) DTATYPE(*PTR) PTRTYPE(*SYP) OBJTYPE(*FILE) will write the system pointer to the space object 'SOMEFILE SOMELIB' (with MI object hex 1901) into the target USRSPC.

SPPOFFSET

When both DTATYPE(*PTR) and PTRTYPE(*SPP) are specified, this parameter indicates the offset value of a space pointer addressing the primary associated space SYSOBJ.

Examples

Writing Scalar Data into a User Space Object

Creating a USRPSC via the QUSCRTUS API The following call to the QUSCRTUS API creates a user space named LIB_A/SPC38.

CALL PGM(QUSRCRTUS)
     PARM('SPC38     LIB_A'  /* Name and library of the USRSPC */
          'U38'              /* Attribute */
          X'00100000'        /* Initial length of the USRSPC: 1M */
          X'00'              /* Initial value of the USRSPC hex 00 */
          '*CHANGE'          /* Public authority */
          '..')              /* Text */

Writing a Greeting at the start of SPC38

Check the content of SPC38

To check the associate space of SPC38, you may dump the space object via CL command DMPOBJ or DMPSYSOBJ. For example,

DMPOBJ LIB_A/SPC38 *USRSPC
/* or via the DMPSYSOBJ command */
DMPSYSOBJ SPC38 LIB_A 19 34

The result would like the following:

*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+....9....+....0....+....1....+....2
SPACE-                                                                                                                  
  000000   D5898385 40A39640 948585A3 40A896A4   405EB05D 00000000 00000000 00000000  *Nice to meet you ;^)            *
  000020   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                                *

Writing Pointers into a User Space Object

Writing a system pointer into SPC38 Say that there is an OPM RPG program named SPR69 in library LIB_A. To store the system pointer to program SPR69 into SPC38 at offset 32, you can issue CHGUSRSPC command like the following.

Writing a SYP into SPC38

Check the content of SPC38 Dump SPC38 again and the result might like the following:

*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+....9....+....0....+....1....+....2
SPACE-                                                                                                                  
  000000   D5898385 40A39640 948585A3 40A896A4   405EB05D 00000000 00000000 00000000  *Nice to meet you ;^)            *
  000020   00000000 00000000 197C212E 8E000200   00000000 00000000 00000000 00000000  *         @                      *
  000040   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                                *
        LINES  000060    TO    100DFF  SAME AS ABOVE                                                                    
.POINTERS-                                                                                                              
  000020   SYP 02 01 SPR69                           04 01 LIB_A                           0000  8000  *PGM

Writing a space pointer into SPC38

Say that you want to write a space pointer addressing the primary associated space of an ILE program object SPR68, with offset value 64, issue the CHGUSRSPC command like the following:

Writing a SPP into SPC38

Check the content of SPC38 Dump SPC38 again and the result might like the following:

*...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+....9....+....0....+....1....+....2
SPACE-                                                                                                                  
  000000   D5898385 40A39640 948585A3 40A896A4   405EB05D 00000000 00000000 00000000  *Nice to meet you ;^)            *
  000020   00000000 00000000 079DC2C6 5B000200   80000000 00000000 3E47713D 3C001040  *          BF                   *
  000040   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                                *
        LINES  000060    TO    100DFF  SAME AS ABOVE                                                                    
.POINTERS-                                                                                                              
  000020   SYP 02 01 SPR68                           04 01 LIB_A                           0000  8000  *PGM             
  000030   SPP 02 01 SPR68                           04 01 LIB_A                           00000040  0000