Support This Project Get i5/OS Programmer's Toolkit at SourceForge.net. Fast, secure and Free Open Source software downloads

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:

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:

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

chgusrspc-scalar.png

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.

chgusrspc-syp.png

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:

chgusrspc-spp.png

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               

Support This Project
Generated on Wed Jul 20 00:25:09 2011 for i5/OS Programmer's Toolkit: Space Object Tools by  doxygen 1.5.9