Analyzing Program Attributes

The MATPG instruction allow us to retrieve either program-attribute information of an OPM MI program. These attributes are important for understanding the behaviour of an MI program. They're also necessary when you are going to re-complie an MI program from disassembled MI source. Attributes of an MI program can be categorized into the following categories:

Attributes of an MI Program

To retrieve the attributes of an MI program, you need to invoke MI instruction MATPG on a system pointer to a OPM program. The receiver template for instruction MATPG has been defined as DS matpg_tmpl_t in mih52.rpgleinc, and as SPC matpg-t in mip-h.emi, for ILE RPG language and MI language respectively.

See also:: Declaration of MATPG's Receiver Template in ILE RPG
Declaration of MATPG's Receiver Template in MI

Todo:: links

In the following discussion, elements of SPC object matpg_t will be cited for simpilicity.

Runtime Attributes

The following table lists runtime program attributes and corresponding MIC options.

Attribute Value and Meaning QPRCRTPG Option Comment

Adopt owner's authority pgm-attr.bit 0 = 0. Do NOT adopt program owner's user profile on invocation. *USER You can set this attribute to yes by either creating a program with the parameter USRPRF(*OWNER) or changing a program by CL command CHGPGM with parameter USRPRF(*OWNER)

pgm-attr.bit 0 = 1. Adopt program owner's user profile on invocation. *ADOPT

Array constraint pgm-attr.bit 1 = 0. Arrays are constrained. *SUBSCR This requests additional run-time checks to ensure that references to array elements are not outside the bounds of the declare statement. This option causes the resulting program to run slower.

pgm-attr.bit 1 = 0 AND expgm-attr.bit 0 = 0. Does not constrain arrays. *NOSUBSCR The results of references to array elements outside the bounds of the declare statement are not defined.

pgm-attr.bit 1 = 0 AND expgm-attr.bit 0 = 1. Fully unconstrained. *UNCON This ensures that references to array elements outside the bounds of the declare statement act as if the array element actually exists.

String constraint pgm-attr.bit 2 = 0. Strings are constrained. *SUBSTR This requests additional run-time checks to ensure that references to character strings are not outside the bounds of the declare statement. This option causes the resulting program to run slower.

pgm-attr.bit 2 = 1. Strings are NOT constrained. *NOSUBSTR The results of substring references outside the bounds of the declare statement are not defined.

Adopted user profile propagation pgm-attr.bit 4 = 0. Adopted user profile authorities are not propagated to external invocations. When *ONWER is not specified. Note that IBM provides neither a CL command nor a application programming interface to change this attribute of a program. It is automatically set or changed to the same value with the adopt-owner-authority attribute for a non-IBM program.

pgm-attr.bit 4 = 1. Adopted user profile authorities are propagated to all subinvocations. *OWNER

Initialize static storage pgm-attr.bit 5 = 0. Initialize storage to binary 0. *CLRPSSA Static storage is allocated the first time a program is called. It remains allocated until explicitly deallocated.

*CLRPSSA = Initializes static storage. This code clears the program static storage area (PSSA) on entry using the Call External (CALLX) MI instruction.
*NOCLRPSSA = Does not initialize the PSSA.

pgm-attr.bit 5 = 1. Do NOT initialize storage to binary 0. *NOCLRPSSA

Initialize automatic storage pgm-attr.bit 6 = 0. Initialize storage to binary 0. *CLRPASA Automatic storage is allocated each time a program runs and automatically deallocated when no longer needed.

*CLRPASA = Initializes automatic storage. This code clears the program automatic storage area (PASA) on entry using the Call External (CALLX) MI instruction.
*NOCLRPASA = Does not initialize the PASA.

pgm-attr.bit 6 = 1. Do NOT initialize storage to binary 0. *NOCLRPASA

Associated journal entry pgm-attr.bit 7 = 0. Program name is recorded in journal entries. - The associated journal entry field controls which program is associated with a journal entry. As a journal entry is made, a newest-to-oldest interrogation of the invocation stack is performed. The first program encountered that has the associated journal entry field set to program name is recorded in journal entries is associated with the journal entry by a record of the program name in the journal entry. If a program is encountered for which the associated journal entry field is set to program name is not recorded in journal entry, the program is ignored unless the program is on the top of the invocation stack. If the program is on the top of the invocation stack, it is associated with the journal entry by a record of the program name in the journal entry.
For example, this attribute of APIs that operate database files (e.g. QDBOPEN, QDBPUT) is 1; while this attribute of user programs is always 0.

pgm-attr.bit 7 = 1. Program name is NOT recorded in journal entries. -

Update PASA stack pgm-attr.bit 8. - This field is now obsolete. It will be ignored.

Suppress decimal data exception pgm-attr.bit 9 = 0. Decimal exceptions are NOT to be suppressed *NOIGNDEC -

pgm-attr.bit 9 = 1. Decimal exceptions are to be suppressed *IGNDEC

Template extension existence pgm-attr.bit 10 = 0. Template extension does NOT exist - The template extension existence field indicates whether or not there is an extension (matpg.expgm-attr) to the program template.

pgm-attr.bit 10 = 1. Template extension exists -

Suppress previously adopted user profiles pgm-attr.bit 11 = 0. Do not suppress previously adopted user profiles *ADPAUT To set the suppress-previously-adopted-user-profiles attribute of a program to yes, issue CHGPGM command on the program with parameter USEADPAUT (*NO).

pgm-attr.bit 11 = 1. Suppress previously adopted user profiles *NOADPAUT

Template version pgm-attr.bits 12-15 = 0000. Version 0 - The template version is important in the following ways:

For version 0, size of an operand in the instruction stream is 2 bytes, while, for version 1, size of an operand in the instruction stream is 3 bytes.
Template version 0 limits the number of instructions to a maximum of 65,532 and the number of ODV entries to a maximum of 8,191. Programs that exceed one of these maximums cannot be created with template version 0. Template version 1 limits the number of instructions to a maximum of 65,532 and the number of ODV entries to a maximum of 65,526. Programs that exceed one of these maximums cannot be created with template version 1.

pgm-attr.bits 12-15 = 0001. Version 1 -

Code-generation Attributes

Attribute	Value and Meaning	QPRCRTPG Option	Comment
Performance optimization	gen-opt.bit 0 = 0. No optimization	*NOOPT	This does not optimize the program. This requests the normal level code optimization when you create the program.
Performance optimization	gen-opt.bit 0 = 1. Perform optimization	*OPT	This optimizes the program. In most instances, this produces the smallest and best running program. Occasionally, the source program may signal a MCH2802 escape message during processing. If this occurs, you should not optimize the program.
Space pointer machine objects	gen-opt.bit 1 = 0. Disallow space pointer machine objects in ODV component.	-	-
Space pointer machine objects	gen-opt.bit 1 = 1. Allow space pointer machine objects in ODV component.	-	-
Coincident operand overlap	gen-opt.bit 2 = 0. Do not assume coincident operand overlap.	*NOOVERLAP	Does not support coincident operands. If you specify *NOOVERLAP, you guarantee that coincident operand overlap will not occur while running the instruction. Therefore, the system can use the receiver on an instruction as a work area during operations performed to produce the final result. Using the receiver as a work area does not use as much processor resource as would be required to move the final result from an internal work area to the receiver.
Coincident operand overlap	gen-opt.bit 2 = 1. Assume coincident operand overlap.	*OVERLAP	Supports coincident operands. If you specify *OVERLAP, the operands on an MI instruction may overlap. Therefore, the system cannot use the receiver on an instruction as a work area during operations that produce the final result. This can require more processor resource for running the instruction but it ensures valid results if an overlap occurs.
Teraspace capable	gen-opt.bit 5 = 0. Do not generate teraspace capable program.	-	User programs can NOT be created as teraspace-capable.
Teraspace capable	gen-opt.bit 5 = 1. Generate teraspace capable program.	-	User programs can NOT be created as teraspace-capable.
Executable part compression	gen-opt.bit 6 = 0. Do not compress executable part.	-	-
Executable part compression	gen-opt.bit 6 = 1. Compress executable part.	-	-
Observation part compression	gen-opt.bit 7 = 0. Do not compress observation part.	-	-
Observation part compression	gen-opt.bit 7 = 1. Compress observation part.	-	-

Observation Attributes

Attribute	Value and Meaning
Instruction stream	obs-attr.bit 0 = 0. Not materializable.
	obs-attr.bit 0 = 1. Materializable.
ODT Directory Vector (ODV)	obs-attr.bit 1 = 0. Not materializable.
	obs-attr.bit 1 = 1. Materializable.
ODT Entry String (OES)	obs-attr.bit 2 = 0. Not materializable.
	obs-attr.bit 2 = 1. Materializable.
Breakpoint Offset Mapping (BOM) table	obs-attr.bit 3 = 0. Not materializable.
	obs-attr.bit 3 = 1. Materializable.
Symbol table	obs-attr.bit 4 = 0. Not materializable.
	obs-attr.bit 4 = 1. Materializable.
Object Mapping Table (OMT)	obs-attr.bit 5 = 0. Not materializable.
	obs-attr.bit 5 = 1. Materializable.

Appendix

Declaration of MATPG's Receiver Template in ILE RPG

Please refer to mih52.rpgleinc for the current version of matpg_tmpl_t.

Todo:: link

Declaration of MATPG's Receiver Template in MI

Please refer to mip-h.emi for the current version of matpg_t.

dcl spc matpg-t bas(*)                              ;
        dcl dd matpg?bytes-in   bin(4)          dir ;
        dcl dd matpg?bytes-out  bin(4)          dir ;
        dcl dd matpg?pgm-id     char(32)        dir ;
        dcl dd matpg?pgm-type           char(2) def(matpg?pgm-id) pos(1) ;
        dcl dd matpg?pgm-name           char(30) def(matpg?pgm-id) pos(3) ;
        dcl dd matpg?crt-opt    char(4)         dir ;
        dcl dd *                char(4)         dir ;
        dcl dd matpg?spc-size   bin(4)          dir ;
        dcl dd matpg?spc-init-val char(1)       dir ;
        dcl dd matpg?perf-cls   char(4)         dir ;
        dcl dd *                char(7)         dir ;
        dcl sysptr matpg?ctx                    dir ;
        dcl sysptr matpg?ag                     dir ;
        dcl dd matpg?pgm-attr   char(2)         dir ;
        dcl dd matpg?gen-opt    char(1)         dir ;
        dcl dd matpg?obsv-attr  char(1)         dir ;
        dcl dd matpg?ss-size    bin(4) unsgnd   dir ; /* size of static storage */
        dcl dd matpg?as-size    bin(4) unsgnd   dir ; /* size of automatic storage */
        dcl dd matpg?num-inst1  bin(2) unsgnd   dir ; /* number of instructions (1). for version number x'0000' */
        dcl dd matpg?num-odv1   bin(2)          dir ; /* number of ODV entries (1). for version number x'0000' */
        dcl dd matpg?inss-off   bin(4)          dir ; /* offset (in bytes) from beginning of template to the instruction stream component */
        dcl dd matpg?odv-off    bin(4)          dir ; /* odv offset */
        dcl dd matpg?oes-off    bin(4)          dir ; /* oes offset */
        dcl dd matpg?bome-len   bin(4)          dir ; /* length of BOM entry */
        dcl dd matpg?bom-len    bin(4)          dir ; /* length of BOM component */
        dcl dd matpg?bom-off    bin(4)          dir ; /* bom offset */
        dcl dd matpg?symtble-len bin(4)         dir ; /* length of symbol table entry */
        dcl dd matpg?symtbl-len bin(4)          dir ; /* length of symbol component */
        dcl dd matpg?symtbl-off bin(4)          dir ; /* symbol table offset */
        dcl dd matpg?omt-off    bin(4)          dir ; /* omt offset */
        dcl dd matpg?num-inst2  bin(4)          dir ; /* number of instructions (2). for version number x'0001' */
        dcl dd matpg?num-odv2   bin(4)          dir ; /* number of ODV entries (2). for version number x'0001' */
        /* template extension */
        dcl dd matpg?expgm-attr char(4)         dir ; /* extended program attributes */
        dcl dd matpg?lang-vrm   char(2)         dir ; /* language VRM. V/R/M: bits 4-7/8-11/12-15 */
        dcl dd matpg?bom-flags  char(1)         dir ; /* bit 0: BOM format. bits 1-7: user data5A. */
        dcl dd matpg?udata5b    char(7)         dir ; /* user data5B */
        dcl dd matpg?pgm-vrm    char(2)         dir ; /* program VRM. */
        dcl dd matpg?retrns     char(1)         dir ; /* bit 0 = 1, All data required for machine retranslation is present. */
        dcl dd *                char(47)        dir ; /* reserved (binary 0) */
        /*
 Program data
    Instruction stream component
    ODV component
    OES component
 BOM table
 Symbol table
 Object mapping table
         */