Space Object Tools

0.2.16

Go back to main page of i5/OS Programmer's Toolkit.

Introduction to Space Object Tools

Space Object Tools is a subproject of i5/OS Programmer's Toolkit. This subproject is designed to help IBM i programmers to operate space objects more conveniently. As you know, IBM provides neither CL command to allow users to display or modify the attributes of a space object interactively, nor CL command to change the content of a space object interactively. This is why the subproject is designed.

Tools and how-tos about space objects provided by this subproject include:

• The Change User Space (CHGUSRSPC) Command
• MI Space Objects
• How to Retrieve Space Attributes of an MI Space Object
  • Retrieve Space Attributes of an MI Space Object via the DMPOBJ or DMPSYSOBJ Commands
  • Retrieve Space Attributes of an MI Space Object via the MATS Instruction
• How to Recognize Pointers in the Content of a Space Object

MI Space Objects

The MI object type code of an MI space object is hex 19. On IBM i, many types of external objects are MI space objects. For example, a *FILE object is an MI space object with type code and subtype code hex 1901. The following simple CL program can help you discover the relationship between MI space objects with different subtype code and corresponding external objects, cl007.clp.

             PGM
             DCL        VAR(&OPT) TYPE(*CHAR) LEN(10) +
                          VALUE('*HEXTOSYM')
             DCL        VAR(&EXTYP) TYPE(*CHAR) LEN(10)
             DCL        VAR(&MITYP) TYPE(*UINT) LEN(2) VALUE(X'1900')
             DCL        VAR(&EC) TYPE(*CHAR) LEN(16)
             DCL        VAR(&ECLEN) TYPE(*UINT) STG(*DEFINED) LEN(4) +
                          DEFVAR(&EC)
             DCL        VAR(&ECRTN) TYPE(*UINT) STG(*DEFINED) LEN(4) +
                          DEFVAR(&EC 5)
             DCL        VAR(&MSG) TYPE(*CHAR) LEN(16)
             DCL        VAR(&NIBLEN) TYPE(*UINT) LEN(4) VALUE(4)

             CHGVAR     VAR(&ECLEN) VALUE(16)
 LOOP:       CHGVAR     VAR(&MITYP) VALUE(&MITYP + 1)
             IF         COND(&MITYP *GT 6655) THEN(GOTO +
                          CMDLBL(SEEYOU)) /* when &MITYP > x'19FF' */
             CALL       PGM(QLICVTTP) PARM(&OPT &EXTYP &MITYP &EC) +
                          /* Convert MI object type code to +
                          external object type name */
             IF         COND(&ECRTN *NE 0) THEN(GOTO CMDLBL(LOOP))
             CALL       PGM(CVTHC) PARM(&MSG &MITYP &NIBLEN)
             CHGVAR     VAR(%SST(&MSG 7 10)) VALUE(&EXTYP)
             SNDPGMMSG  MSG(&MSG)
             GOTO       CMDLBL(LOOP)

 SEEYOU:     ENDPGM

Remarks:

CVTHC is an OPM MI program that converts each hex digit (4-bit value) in the source character string to a character (8-bit value) in the receiver character string.

Call CL007, the output is the following:

1901  *FILE  
1902  *MSGQ  
1903  *JOBD  
1904  *CLS   
1905  *CMD   
1906  *TBL   
1907  *PRTIMG
1908  *EDTD  
1909  *SBSD  
190A  *DTAARA
190B  *CLD   
190C  *GSS   
190D  *CHTFMT
190E  *DOC   
190F  *DOCL  
1910  *IGCTBL
1911  *QRYDFN
1912  *FLR   
1913  *EXITRG
1914  *NTBD  
1915  *PNLGRP
1916  *MENU  
1917  *SVRSTG
1918  *CFGLO 
1919  *S36   
191A  *IGCSRT
191B  *PRDDFN
191C  *MEDDFN
191D  *PRDLOD
191E  *IPXD  
191F  *SQLUDT
1920  *DTADCT
1921  *LOCALE
1922  *CSPMAP
1923  *CSPTBL
1924  *M36CFG
1925  *PSFCFG
1926  *FNTRSC
1927  *PAGSEG
1928  *FORMDF
1929  *OVL   
192A  *NODGRP
192B  *FNTTBL
192C  *CRG   
192D  *MGTCOL
192E  *IMGCLG
192F  *TIMZON
1930  *PDG   
1931  *QMQRY 
1932  *QMFORM
1933  *PRDAVL
1934  *USRSPC
1935  *CSI   
1936  *PAGDFN
1937  *BNDDIR
1938  *WSCST 
1939  *NWSCFG

How to Retrieve Space Attributes of an MI Space Object

To retrieve space attributes of an MI space object, you can either issue the DMPOBJ or DMPSYSOBJ commands directly on an MI space object, or use the MATS (Materialize Space Attributes) instruction in an OPM MI or ILE program.

Remarks:

The DMPXXX commands are really very handy when being used to check object attributes or the content or an MI object, but using them requires the *ALLOBJ special authority.

Retrieve Space Attributes of an MI Space Object via the DMPOBJ or DMPSYSOBJ Commands

To retrieve space attributes of an MI space object, you can issue the the DMPOBJ or DMPSYSOBJ commands directly on it, and then check the SPACE ATTRIBUTES section in the result spooled file. The format of the 116-byte SPACE ATTRIBUTES section is exactly the same with the instruction template of MATS. This instruction template is defined as mats_tmpl_t in mih-spc.rpgleinc and mats-tmpl-t in mih-spc.cblleinc.

From section MI Space Objects, you can see that an external object of type *FILE or *SBSD (Subsystem Description) is an MI space object. The MI object type code and subtype code for a *FILE or *SBSD object is hex 1901 and hex 1909 respectively. Say that you have a *FILE object AUG0B and a *SBSD object OCT in a library called SOMELIB. You can dump them like the following:

/* Dump file object SOMELIB/AUG0B */
DMPOBJ OBJ(SOMELIB/AUG0B) OBJTYPE(*FILE)
/* or */
DMPSYSOBJ OBJ(AUG0B) CONTEXT(SOMELIB) TYPE(19) SUBTYPE(01)

/* Dump *SBSD object SOMELIB/OCT */
DMPOBJ OBJ(SOMELIB/OCT) OBJTYPE(*SBSD)
/* or */
DMPSYSOBJ OBJ(OCT) CONTEXT(SOMELIB) TYPE(19) SUBTYPE(09)

The 116-byte SPACE ATTRIBUTES sections of them might like the following:

• *FILE SOMBLIB/AUG0B

   SPACE ATTRIBUTES-
     000000   00FFF000 00000074 1901C1E4 C7F0C240   40404040 40404040 40404040 40404040  *  0      AUG0B                 *
     000020   40404040 40404040 E0060000 00000000   00001000 00100000 00000000 00000000  *        $                       *
     000040   00000000 00000000 01111305 F1000400   00000000 00000000 00000000 00000000  *            1                   *
     000060   00000000 00000000 00000000 00000000   00FFF000                             *                  0             *
  

• *SBSD SOMBLIB/OCT

   SPACE ATTRIBUTES-
     000000   00FFF000 00000074 1909D6C3 E3404040   40404040 40404040 40404040 40404040  *  0      OCT                   *
     000020   40404040 40404040 A0000000 00000000   00001000 00110000 00000000 00000000  *        ~                       *
     000040   00000000 00000000 01111305 F1000400   00000000 00000000 00000000 00000000  *            1                   *
     000060   00000000 00000000 00000000 00000000   00001000                             *                                *
  

According to documentation on the instruction template of MATS, you can find out the space attributes of these two space objects.

Offset (Hex)	Field	*FILE SOMBLIB/AUG0B		*SBSD SOMBLIB/OCT
		Value	Meaning	Value	Meaning
0	Bin(4). Number of bytes provided for materialization	hex 00FFF000	-	hex 00FFF000	-
4	Bin(4). Number of bytes available for materialization	hex 00000074	116 bytes	hex 00000074	116 bytes
8	Char(32). Object identification	hex 1901C1E4..4040	MI object type is hex 1901. Object name is 'AUG0B'.	hex 1909D6C3..4040	MI object type is hex 1909. Object name is 'OCT'.
28	Char(4). Object creation options	hex E0060000	bit 0 = 1. Object is permanent bit 1 = 1. Space is variable-length bit 2 = 1. Addressability in context bit 13 = 1. Do not initialize space bit 14 = 1. Automatically extend space	hex A0000000	bit 0 = 1. Object is permanent bit 1 = 0. Space is fixed-length bit 2 = 1. Addressability in context bit 13 = 0. Initialize space bit 14 = 0. Do NOT automatically extend space
2E	Char(2). ASP number	hex 0000	Space object is allocate in the system ASP	hex 0000	Space object is allocate in the system ASP
30	Bin(4). Size of space	hex 00001000	4096 bytes	hex 00001000	4096 bytes
34	Char(1). Initial value of space	hex 00	-	hex 00	-
35	Char(4). Performance class	hex 10000000Performance class	Bit 3 = 1. Machine chooses space alignment. The alignment chosen is a multiple of 512.	hex 10000000Performance class	Bit 3 = 1. Machine chooses space alignment. The alignment chosen is a multiple of 512. Bit 7 = 1. Obsolete. This field is no longer used and will be ignored. Oops!
38	Char(1). Expanded transfer size advisory. [1]	hex 00	-	hex 00	-
40	System pointer to the context object	hex 00000000 00000000 01111305 F1000400	[2]	hex 00000000 00000000 01111305 F1000400	[2]
50	System pointer to the access group object	hex 00..00	Pointer not set	hex 00..00	Pointer not set
70	Bin(4). Maximum size of space	hex 00FFF000	16773120 bytes (16M - 1 Page). 1 page is 4K.	hex 00001000	4096 bytes

Notes

• [1] The expanded transfer size advisory specifies the desired number of pages to be transferred between main store and auxiliary storage for implicit access state changes. This value is only an advisory; the machine may use a value of its choice for performing access state changes under some circumstances. For example, the machine may limit the transfer size to a smaller value than is specified. A value of zero is an explicit indication that the machine should use the machine default storage transfer size for this object.
• [2] Byte 14 of a system pointer is the MI object type code of the MI object pointed to by the system pointer. Here, a value of hex 04 of byte 14 means this is a system pointer to a context (library) object.

Retrieve Space Attributes of an MI Space Object via the MATS Instruction

To retrieve space attributes of an MI space object in the MI way, use the MATS instruction. You can either use the MATS instruction in an OPM MI program, or in an ILE HLL program via the bound program access interface of it, _MATS.

Remarks:

Although there is an API called Retrieve User Space Attributes (QUSRUSAT), it cares about only one of all types of MI space object, the *USRSPC objects (with MI object type code and subtype code hex 1934). Furthermore, it returns only the space size, automatic extendibility, and intitial value attributes of a *USRSPC.

Here's an example ILE COBOL program that analyzes the create-option attributes of a *USRSPC object retrieved using the MATS instruction, cbl015.cblle, and then prints the result of analyzation to printer file QSYSPRT.

       process
           NOSTDTRUNC
           NOMONOPRC.

       id division.
       program-id. cbl015.

       environment division.
       configuration section.
       special-names.
           copy mih-lnktyp.

       input-output section.
       file-control.
           select spcattr-report assign to printer-QSYSPRT.

       data division.
       file section.
       fd spcattr-report.
       01 report-rec.
          05 attr-name  pic x(28).
          05 filler     pic x(2).
          05 attr-value pic x(50).

       working-storage section.
           copy mih-comp.
           copy mih-spc.
           copy mih-ptr.

       01 r-tmpl type rslvsp-tmpl-t.
       01 usrspc usage pointer.
       01 spc-attr type mats-tmpl-t.
       01 offset pic 9(9) usage comp-4.
       01 flag   pic 9(9) usage comp-4.
       01 mask     pic x(4) value x"01800000".
       01 str-flag pic x(4).

       linkage section.
       77 usrspc-name pic x(10).

       procedure division using usrspc-name.
       main-program.

       resolve-syp.
           move all x"00" to r-tmpl.
           move x"1934" to obj-type of r-tmpl.
           move usrspc-name to obj-name of r-tmpl.
           call "_RSLVSP2" using
                by reference usrspc
                by reference r-tmpl.

           move length of mats-tmpl-t to bytes-in of spc-attr.
           call "_MATS" using
                by reference spc-attr
                by reference usrspc.

       generate-report.
           open output spcattr-report.
           move "Attribute Name" to attr-name.
           move "Attribute Value" to attr-value.
           write report-rec.
           move "---------------" to attr-name.
           move "----------------" to attr-value.
           write report-rec.

           move 0 to offset.
           call "_TSTBTS" using
                by reference   crt-opt of spc-attr
                by value       offset
                returning into flag.
           if flag is equal to 1
              then
              move "Permanent" to attr-value
           else
              move "Temporary" to attr-value
           end-if.
           move "Existence attribute" to attr-name.
           write report-rec.

           move 1 to offset.
           call "_TSTBTS" using
                by reference   crt-opt of spc-attr
                by value       offset
                returning into flag.
           if flag is equal to 1
              then
              move "Variable-length" to attr-value
           else
              move "Fixed-length" to attr-value
           end-if.
           move "Space attribute" to attr-name.
           write report-rec.

           move 2 to offset.
           call "_TSTBTS" using
                by reference   crt-opt of spc-attr
                by value       offset
                returning into flag.
           if flag is equal to 1
              then
              move "Addressability in context" to attr-value
           else
              move "Addressability not in context" to attr-value
           end-if.
           move "Context" to attr-name.
           write report-rec.

           move 13 to offset.
           call "_TSTBTS" using
                by reference   crt-opt of spc-attr
                by value       offset
                returning into flag.
           if flag is equal to 1
              then
              move "Do not initialize" to attr-value
           else
              move "Initialize" to attr-value
           end-if.
           move "Initialize space" to attr-name.
           write report-rec.

           move 14 to offset.
           call "_TSTBTS" using
                by reference   crt-opt of spc-attr
                by value       offset
                returning into flag.
           if flag is equal to 1
              then
              move "Yes" to attr-value
           else
              move "No" to attr-value
           end-if.
           move "Automatically extend space" to attr-name.
           write report-rec.

       Bits_15-16.
           call "_ANDSTR" using
                by reference str-flag
                by reference crt-opt of spc-attr
                by reference mask
                by value     4.
           evaluate str-flag
               when x"00000000"
                    move "Reference and modify allowed for user state PGMs"
                         to attr-value
               when x"00800000"
                    move "Only reference allowed for user state programs"
                         to attr-value
               when x"01000000"
                    move "A value hex 10 is invalid for bits 15-16"
                         to attr-value
               when x"01800000"
                    move "No reference or modify allowed for user state PGMs"
                         to attr-value
           end-evaluate.
           move "Hardware storage protection" to attr-name.
           write report-rec.

           move 21 to offset.
           call "_TSTBTS" using
                by reference   crt-opt of spc-attr
                by value       offset
                returning into flag.
           if flag is equal to 1
              then
              move "At all times"
                   to attr-value
           else
              move "When hardware protection is enforced for all STG"
                   to attr-value
           end-if.
           move "Enforce hardware protection" to attr-name.
           write report-rec.

       see-you.
           stop run.
       end program cbl015.

Call CBL015 like the following (CBL014 is a *USRSPC object):

CALL CBL015 CBL014

The output of CBL015 might be like the following:

Attribute Name                Attribute Value                                 
---------------               ----------------
Existence attribute           Permanent                                       
Space attribute               Variable-length                                 
Context                       Addressability in context                       
Initialize space              Initialize                                      
Automatically extend space    Yes                                             
Hardware storage protection   Reference and modify allowed for user state PG  
Enforce hardware protection   When hardware protection is enforced for all STG

How to Recognize Pointers in the Content of a Space Object

The answer lies in the Materialize Pointer Locations (MATPTRL) instruction. The instruction template for it in ILE RPG and ILE COBOL and its system-builtin prototype in ILE RPG can be found in mih-ptr.rpgleinc and mih-ptr.cblleinc respectively. IBM's documentation on the MATPTRL instruction is here.

Now follow the simple demonstration steps showed bellow to see how to find out pointers in the content of a space object via the MATPTRL instruction.

• Create an MI space object. For simplicity, here we create a *USRSPC object by calling the QUSCRTUS API.

  /* Create a *USRSPC called U_POINTERS in the current library */
  CALL PGM(QUSCRTUS)
       PARM('U_POINTERS*CURLIB'
            'MAY'                 /* Attribute */
            X'00000200'           /* Space size */
            X'00'                 /* Initial value */
            '*CHANGE'             /* Public authority */
            'Recognize PTRs')     /* Text */
  

• Write some scalar data and pointer data into the created space using the The Change User Space (CHGUSRSPC) Command.

  CHGUSRSPC USRSPC(*LIBL/U_POINTERS)
            OFFSET(0)
            DTA('Lyrics: Why do birds suddenly')
            DTALEN(*CALC)
  /* Write the system pointer to *CMD CHGUSRSPC itself into the space object */
  CHGUSRSPC USRSPC(*LIBL/U_POINTERS)
            OFFSET(32)
            DTATYPE(*PTR)
            PTRTYPE(*SYP)
            SYSOBJ(*LIBL/CHGUSRSPC)
            OBJTYPE(*CMD)
  

• Check what's in the space object now by dumping the space object. e.g. DMPOBJ OBJ(U_POINTERS) OBJTYPE(*USRSPC). The content of *USRSPC is the following. Note that the dump result indicates that there is a system pointer at offset hex 20 of the content of the space object U_POINTERS.

   SPACE-
     000000   D3A89989 83A27A40 E688A840 84964082   899984A2 40A2A484 84859593 A80F0000  *Lyrics: Why do birds suddenly   *
     000020   00000000 00000000 2D26C48D D3001900   00000000 00000000 00000000 00000000  *          DL                   *
     000040   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                                *
           LINES  000060    TO    000DFF  SAME AS ABOVE
   .POINTERS-
     000020   SYP 19 05 CHGUSRSPC                       04 01 I5TOOLKIT                       0000  0000  *CMD
  

• Find pointer locations in the content of U_POINTERS using the MATPTRL instruction. The following is an ILE COBOL example, cbl016.cblle.

       process
           NOSTDTRUNC
           NOMONOPRC.

       id division.
       program-id. cbl016.

       environment division.
       configuration section.
       special-names.
           copy mih-lnktyp.

       data division.
       working-storage section.

       01 r-tmpl     type rslvsp-tmpl-t.
       01 spc-obj    usage pointer.
       01 spp-ptr    usage pointer.
 Size of *USRSPC U_POINTERS is 512 bytes
       01 dta-len    pic 9(9) usage comp-4 value 512.
       01 test-tmpl  type matptrl-tmpl-t.
       01 bitmap-len pic 9(9) usage comp-4.
       01 i          pic 9(9) usage comp-4.
       01 bit-flag   pic 9(9) usage comp-4.
       01 ptr-pos    pic 9(9) usage comp-4.

       linkage section.
           copy mih-ptr.

       procedure division.
       main.
           move all x"00" to r-tmpl.
           move x"1934" to obj-type of r-tmpl.
           move "U_POINTERS" to obj-name of r-tmpl.
           call "_RSLVSP2" using
                by reference spc-obj
                by reference r-tmpl.

           call "_SETSPPFP" using
                by value       spc-obj
                returning into spp-ptr.

           move all x"00" to test-tmpl.
           move length of test-tmpl to bytes-in of test-tmpl.
           call "_MATPTRL" using
                by reference test-tmpl
                by value     spp-ptr
                by reference dta-len.

 set bitmap-len to number of bits to returned by MATPTRL
           compute bitmap-len = (bytes-out of test-tmpl - 8) * 8.
           perform test-for-ptr
                   test before
                   varying i from 0 by 1
                   until   i >= bitmap-len.

       see-you.
           stop run.

       test-for-ptr.
           call "_TSTBTS" using
                by reference   bitmap of test-tmpl
                by value       i
                returning into bit-flag.
           if bit-flag is equal to 1
              then
              compute ptr-pos = i * 16
              display "Pointer detected at offset: "
                      ptr-pos
           end-if.

       end program cbl016.

• Call CBL016 to find out pointers within the content of U_POINTERS. The result output is the following. The only pointer (system pointer to the CHGUSRSPC command) is detected at offset 32 in the space object.

  Pointer detected at offset: 0000000032