Materialize System Object (MATSOBJ)

Instruction Syntax

Operand 2: System pointer.

Built-in number for MATSOBJ is 91.
MATSOBJ (                                                                       
         receiver   : address                                                  
         object     : address of system pointer                                       
)                                                                               

Description:

This instruction materializes the identity and size of a system object addressed by the system pointer identified by operand 2. It can be used whenever addressability to a system object is contained in a system pointer.

The format of the materialization is:

Offset
Dec	Hex	Field Name	Data Type and Length
0	0	Materialization size specification	Char(8)
0	0	Number of bytes provided by the user	Bin(4)
4	4	Number of bytes available for materialization	Bin(4)
8	8	Object state attributes	Char(2)
8	8	Suspended state 0 = Not suspended 1 = Suspended	Bit 0
8	8	Damage state 0 = Not damaged 1 = Damaged	Bit 1
8	8	Partial damage state 0 = No partial damage 1 = Partial damage	Bit 2
8	8	Existence of addressing context 0 = Not addressed by a temporary context 1 = Addressed by a temporary context	Bit 3
8	8	Dump for previous release permitted 0 = Dump for previous release not permitted 1 = Dump for previous release permitted	Bit 4
8	8	Object compressed 0 = Object not compressed 1 = Object compressed (partially or completely)	Bit 5
8	8	ASP overflow 0 = No part of the object has overflowed its ASP 1 = Some part of the object has overflowed its ASP	Bit 6
8	8	Object requires conversion to be used on this machine 0 = No conversion is required 1 = Object must be converted before it can be used on this machine implementation	Bit 7
8	8	Object not in format required by this machine 0 = Object format is current. 1 = Object format is not current. The object must be converted before it can be used on this machine implementation.	Bit 8
8	8	Object not compatible with the common level of system 0 = Object is compatible with the common level of system supported by the version, release, and modification level the object was created for. 1 = Object is not compatible with the common level of system supported by the version, release, and modification level the object was created for.	Bit 9
8	8	Media preference 00 = No media preference 01 = High performance media preference	Bits 10-11
8	8	Reserved (binary 0)	Bits 12-15
10	A	Context identification	Char(32)
10	A	Context type	Char(1)
11	B	Context subtype	Char(1)
12	C	Context name	Char(30)
42	2A	Object identification	Char(32)
42	2A	Object type	Char(1)
43	2B	Object subtype	Char(1)
44	2C	Object name	Char(30)
74	4A	Timestamp of creation	Char(8)
82	52	Size of associated space	Bin(4)
86	56	Object size	Bin(4)
90	5A	Owning user profile identification	Char(32)
90	5A	User profile type	Char(1)
91	5B	User profile subtype	Char(1)
92	5C	User profile name	Char(30)
122	7A	Timestamp of last modification	Char(8)
130	82	Recovery options	Char(4)
130	82	Machine internal use	Char(2)
132	84	ASP number	Char(2)
134	86	Performance class	Char(4)
138	8A	Initial value of space	Char(1)
139	8B	Object audit attribute Hex 00 = No audit for this object Hex 02 = Audit change for this object Hex 03 = Audit read and change for this object Hex 04 = Audit read and change for this object if the user profile is being audited Hex FF = User not allowed to materialize object audit attribute In order to materialize the object audit attribute the thread must either be running in system state, or be running in user state with the effective user profile for the thread having either of the following special authorities: all object authority, auditor authority. Otherwise the object audit attribute is set to Hex FF.	Char(1)
140	8C	Sign state Hex 00 = Object not digitally signed Hex 01 = Object digitally signed	Char(1)
141	8D	Signed by a system-trusted source Hex 00 = Object not digitally signed by a system-trusted source Hex 01 = Object digitally signed by a system-trusted source	Char(1)
142	8E	Object authority list (AL) status 0 = Object not in an authority list 1 = Object in an authority list	Bin(2)
144	90	Authority list identification	Char(48)
144	90	Authority list (AL) status 0 = Valid authority list 1 = Damaged authority list 2 = Destroyed authority list (no name below)	Bin(2)
146	92	Reserved	Char(14)
160	A0	Authority list type	Char(1)
161	A1	Authority list subtype	Char(1)
162	A2	Authority list name	Char(30)
192	C0	Dump for previous release reason code	Char(8)
200	C8	Maximum possible associated space size	Bin(4)
204	CC	Timestamp of last use of object	Char(8)
212	D4	Count of number of days object was used	UBin(2)
214	D6	Program or module attributes	Char(2)
214	D6	State provided 0 = No program/module state value 1 = Program/module state value present	Bit 0
214	D6	Program executable portion compression status 0 = Program's executable portion is not compressed 1 = Program's executable portion is compressed	Bit 1
214	D6	Program extended observability storage area existence 0 = Program's extended observability storage area does not exist or can no longer be materialized 1 = Program's extended observability storage area does exist and can be materialized	Bit 2
214	D6	Program extended observability storage area compression status If the compression status of the extended observability storage area of the program is uncompressed, it is not a guarantee that the extended observability storage area exists.  The extended observability storage area existence should be checked first to ensure that it currently exists in the program. 0 = Program's extended observability storage area is not compressed 1 = Program's extended observability storage area is compressed	Bit 3
214	D6	Reserved (binary 0)	Bits 4-7
215	D7	Type of program Hex 00 = Non-bound program Hex 01 = Bound program Hex 02 = Bound service program Hex 04 = Java program	Char(1)
216	D8	Domain of object	Char(2)
218	DA	State for program or module	Char(2)
220	DC	MI-supplied information	Char(8)
228	E4	Earliest compatible release	Char(2)
228	E4	Reserved	Bits 0-3
228	E4	Version	Bits 4-7
228	E4	Release	Bits 8-11
228	E4	Modification level	Bits 12-15
230	E6	Object size in basic storage units	UBin(4)
234	EA	Primary group identification	Char(32)
234	EA	Profile type	Char(1)
235	EB	Profile subtype	Char(1)
236	EC	Profile name	Char(30)
266	10A	Hardware storage protection	Char(1)
266	10A	Obsolete (binary zero)	Bits 0-1
266	10A	Hardware storage protection of associated space	Bits 2-3
266	10A	Creation hardware storage protection	Bits 4-5
266	10A	Hardware storage protection always enforced for object 0 = Hardware storage protection of this object's encapsulated part is enforced only when hardware storage protection is enforced for all storage. 1 = Hardware storage protection of this object's encapsulated part is enforced at all times.	Bit 6
266	10A	Hardware storage protection always enforced for associated space 0 = Hardware storage protection is enforced for this object's primary associated space only when hardware storage protection is enforced for all storage. 1 = Hardware storage protection is enforced for this object's primary associated space at all times.	Bit 7
267	10B	Reserved	Char(1)
268	10C	File identifier	UBin(4)
272	110	Generation identifier	UBin(4)
276	114	Program or module optimizing translator level	UBin(2)
278	116	Reserved	Char(10)
288	120	Parent of attached object	System pointer
304	130	Number of signers	UBin(4)
308	134	Temporary storage accounting identifier	UBin(4)
312	138	Reserved	Char(32)
344	158	--- End ---

This instruction will tolerate a damaged object referenced by operand 2 when operand 2 is a resolved pointer. The instruction will not tolerate a damaged context(s) or damaged programs when resolving pointers. Also, as a result of damage or abnormal machine termination, this instruction can indicate that an object is addressed by a context, when in fact the context will not show this as an addressed object.

The existence of addressing context field indicates whether the previously (or currently) addressing context was (is) temporary. This field is 0 if the object was (is) not addressed by a temporary context.

The dump for previous release permitted field will indicate if the object is eligible for a dump for previous request.

¹ When this field indicates that the object is not eligible, the dump for previous release reason code can be used to determine why the object is not eligible.

The object compressed field indicates whether the encapsulated part of the object is either partially or completely compressed. The encapsulated part(s) of some object types can be compressed by object-specific create or modify instructions.

For program objects other than Java program objects, additional compression information is provided by the program executable portion compression status and the program extended observability storage area compression status fields. This program compression information is also available from the Materialize Program (MATPG) or the Materialize Bound Program (MATBPGM) instructions. However, the use of those instructions may cause the program object to be temporarily decompressed to obtain this compression information. By using the program compression information provided in this instruction instead of using Materialize Program (MATPG) or the Materialize Bound Program (MATBPGM) instructions, this temporary decompression of the program object can be avoided.

For Java program objects, additional compression information is not available.

For objects other than programs, use the object-specific materialization instruction to determine exactly which part(s) of the object are compressed.

The ASP overflow field indicates whether any part of the object is stored in an ASP other than the ASP specified at the time the object was created. If any object created in one ASP has parts that are in a different ASP (due to lack of sufficient available storage in the original ASP), then none of the objects in the first ASP are protected in the event of a failure of any other ASP in the system. By deleting objects that have overflowed, however, it may be possible to eliminate the ASP overflow condition and restore the protection that ASPs provide. Use the object-specific materialization instruction for this type of object to determine what ASP was specified at the time the object was created.

The object requires conversion to be used on this machine field is set for program or module objects. For all other object types, the field will have a value of 0. This bit indicates whether the program or module is compatible with the current machine implementation or if the program or module must be converted. This bit is set when either the object is not in a format required by this machine, or the object is in a format required by this machine but it uses features not implemented by the machine. If this bit is set, the object is not compatible with the common level of system.

The object not in format required by this machine field is set for program or module objects. For all other object types, the field will have a value of 0. This bit indicates whether the program or module is in the correct format for the current machine implementation. An object can be in the correct format and not be compatible. If this bit is set, the object requires conversion to be used on this machine, and the object is not compatible with the common level of system.

The object not compatible with the common level of system is set for program or module objects. For all other object types, the field will have a value of 0. This indicates if the object can be used without conversion on any system compatible with the object's earliest compatible release. Specifically, this field is set to 0 if the object can be used without conversion on any system installed with the same release as the object's earliest compatible release. This field is set to 1 if the object may require conversion. This bit is always set when either the object requires conversion to be used on this machine, or the object is not in a format required by this machine.

The media preference field indicates the current media preference for the object. The following binary values can be returned:

00

Indicates no media preference. The machine decides which media to use.

01

Indicates high performance media is preferred. The machine decides whether the preference can be honored.

If the object addressed by the system pointer specifies that it is not addressed by a context or if the context is destroyed, the context type field is hex 00. If the object is addressed by the machine context, a context type field of hex 81 is returned. No verification is made that the specified context actually addresses the object.

Valid object type fields and their meanings are:

Value (Hex)

Object Type

01

Access group

02

Program

03

Module

04

Context

06

Byte string space

07

Journal space

08

User profile

09

Journal port

0A

Queue

0B

Data space

0C

Data space index

0D

Cursor

0E

Index

0F

Commit block

10

Logical unit description

11

Network description

12

Controller description

13

Dump space

14

Class of service description

15

Mode description

16

Network interface description

17

Connection list

18

Queue space

19

Space

1A

Process control space

1B

Authority list

1C

Dictionary

1D

Auxiliary server

1E

Byte stream file

21

Composite object group

23

Transaction control structure

The timestamp field is materialized as an 8-byte unsigned binary number. See Standard Time Format for additional information on the format of timestamps.

(local time)

If the object has an associated space, the maximum possible associated space size field will be returned with a value which represents the maximum size to which the associated space can be extended. This value depends on the internal packaging of the object and its associated space as well as (possibly) the maximum space size field as optionally specified during the create of the object.

The object size field will contain the size of the object in bytes up to a value of 2G-1 (2,147,483,647). If the object's size is greater than this, a value of zero will be returned in the object size field. In this case, the object size in basic storage units field should be used to get the object's actual size. This field will always contain the object's true size in number of basic storage units.

The owning user profile identification field contains the type, subtype, and name of the owning user profile for the object. The owning user profile identification field will be assigned a value of hex 00 if the object is a temporary object that is not owned.

The timestamp of last modification (local time) field is implicitly set, except for the objects restricted below, by any instruction or IMPL function that modifies or attempts to modify an object attribute value or an object state. The timestamp of last modification field is only ensured as part of the normal ensuring of objects.

Implicit setting of the timestamp of last modification field is restricted for the following objects and will only occur for generic, nonobject specific, operations on them.

• Logical unit description
• Controller description
• Network description
• Access group

No modification timestamp will be provided for the following objects and a value of zero will be returned in the materialization template for the modification timestamp.

• Process control space

The timestamp of last modification may not be unique (the uniqueness bits all set to zero) for the following objects. See Standard Time Format for additional information on the format of the timestamp of last modification field.

• Queue

ASP number uniquely identifies the auxiliary storage pool. The ASP number may have a value from 0 through 255. A value of 0 indicates the system ASP. A value of 2 through 255 indicates a user ASP. A value of 2 through 32 indicates a basic ASP. A value of 33 through 255 indicates an independent ASP.

Sign state indicates whether or not the object is digitally signed.

Signed by a system-trusted source indicates whether or not the object is digitally signed by a system-trusted source. If signed by a system-trusted source is hex 01, sign state will also be hex 01.

The object authority list status field indicates whether or not the object is contained in an authority list. If it is, the authority list identification information provides the name of the authority list, except when the authority list is indicated as destroyed, in which case, the name information is meaningless.

The dump for previous release reason code can be used to determine why the object is not eligible according to the dump for previous release permitted field. Currently reason codes are architected for programs and for modules.

The reason codes are mapped as follows for program objects. Note that more than one reason may be returned.

The reason codes are mapped as follows for module objects. Note that more than one reason may be returned.

The timestamp of last use of object field and the count of number of days object was used field are set by the Call External (CALLX) or Transfer Control (XCTL) instructions on the objects first use on that day. The timestamp value is only good for the date. The time value obtained from this timestamp is not accurate.

The type of program field indicates the program model of a program object, which is determined by how the program was created. It is only present when operand 2 points to a program object. This field is necessary since the object type and object subtype do not provide enough information to identify the program model of a program object. Knowing the program type is useful in selecting appropriate program specific instructions.

The domain of object field contains the value of the state under which a program or procedure must be running to access this object.

The state for program or module field contains the state under which the program runs. It is only present when the state provided flag is on.

The MI-supplied information is simply an 8 byte character field which can be set into an object and materialized with the Materialize System Object (MATSOBJ) instruction. The machine has no knowledge or dependencies on the content of this field.

The earliest compatible release field contains the earliest release in which the object can be used.

The primary group identification field contains the type, subtype, and name of the primary group profile for the object. If the primary group for the object is not set, the type field will be set to a value of hex 00.

The hardware storage protection field contains the hardware storage protection of the object's associated space and the protection level requested when the object was created. Each 2-bit subfield contains a value whose meaning is defined as follows:

00 =

Reference and modify allowed for user state programs

01 =

Only reference allowed for user state programs

10 =

Only reference allowed for all programs

11 =

No reference nor modify allowed for user state programs

The file identifier, in combination with the generation ID, uniquely identifies the object within a file system. The file ID may be reused when the object is deleted.

The generation identifier uniquely identifies the generation of the usage of a file identifier. The generation ID for a given file ID is not reused.

If the object has not been assigned a file ID and generation ID, binary 0s will be returned.

If the object specified by operand 2 is attached to a byte stream file or a Composite Object Group the parent of attached object field returns a system pointer to the byte stream file or Composite Object Group Otherwise, a null pointer value is returned.

Number of signers indicates the number of digital certificates currently having signed the object.

Program or module optimizing translator level returns the level of the optimizing translator used to create the program or module. If an ILE program consists of more than one module, the optimizing translator level of the program is that of the module with the lowest optimizing translator level. For all other object types this field will return a value of zero.

Authorization Required

• Execute
  • Contexts referenced for address resolution

Lock Enforcement

• Materialize
  • Operand 2
  • Contexts referenced for address resolution

Exceptions

• 06 Addressing
  • 0601 Space Addressing Violation
  • 0602 Boundary Alignment
  • 0603 Range
• 08 Argument/Parameter
  • 0801 Parameter Reference Violation
• 0A Authorization
  • 0A01 Unauthorized for Operation
• 10 Damage Encountered
  • 1004 System Object Damage State
  • 1005 Authority Verification Terminated Due to Damaged Object
  • 1044 Partial System Object Damage
• 1A Lock State
  • 1A01 Invalid Lock State
• 1C Machine-Dependent
  • 1C03 Machine Storage Limit Exceeded
• 20 Machine Support
  • 2002 Machine Check
  • 2003 Function Check
• 22 Object Access
  • 2201 Object Not Found
  • 2202 Object Destroyed
  • 2203 Object Suspended
  • 2207 Authority Verification Terminated Due to Destroyed Object
  • 2208 Object Compressed
  • 220B Object Not Available
• 24 Pointer Specification
  • 2401 Pointer Does Not Exist
  • 2402 Pointer Type Invalid
• 2E Resource Control Limit
  • 2E01 User Profile Storage Limit Exceeded
• 32 Scalar Specification
  • 3201 Scalar Type Invalid
• 36 Space Management
  • 3601 Space Extension/Truncation
• 38 Template Specification
  • 3803 Materialization Length Invalid
• 44 Protection Violation
  • 4401 Object Domain or Hardware Storage Protection Violation
  • 4402 Literal Values Cannot Be Changed