Materialize System Object (MATSOBJ)


Op Code (Hex) Operand 1 Operand 2

053E Receiver Object

Operand 1: Space pointer.

Operand 2: System pointer.

Bound program access
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
Bit 0



0 = Not suspended
1 = Suspended


8 8
Damage state
Bit 1



0 = Not damaged
1 = Damaged


8 8
Partial damage state
Bit 2



0 = No partial damage
1 = Partial damage


8 8
Existence of addressing context
Bit 3



0 = Not addressed by a temporary context
1 = Addressed by a temporary context


8 8
Dump for previous release permitted
Bit 4



0 = Dump for previous release not permitted
1 = Dump for previous release permitted


8 8
Object compressed
Bit 5



0 = Object not compressed
1 = Object compressed (partially or completely)


8 8
ASP overflow
Bit 6



0 = No part of the object has overflowed its ASP
1 = Some part of the object has overflowed its ASP


8 8
Object requires conversion to be used on this machine
Bit 7



0 = No conversion is required
1 = Object must be converted before it can be used on this machine implementation


8 8
Object not in format required by this machine
Bit 8



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.


8 8
Object not compatible with the common level of system
Bit 9



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.


8 8
Reserved (binary 0)
Bits 10-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
Char(1)



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.

140 8C
Sign state
Char(1)



Hex 00 = Object not digitally signed
Hex 01 = Object digitally signed


141 8D
Signed by a system-trusted source
Char(1)



Hex 00 = Object not digitally signed by a system-trusted source
Hex 01 = Object digitally signed by a system-trusted source


142 8E
Object authority list (AL) status
Bin(2)



0 = Object not in an authority list
1 = Object in an authority list


144 90
Authority list identification
Char(48)
144 90
Authority list (AL) status
Bin(2)



0 = Valid authority list
1 = Damaged authority list
2 = Destroyed authority list (no name below)


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
Bit 0



0 = No program/module state value
1 = Program/module state value present


214 D6
Program executable portion compression status
Bit 1



0 = Program's executable portion is not compressed
1 = Program's executable portion is compressed


214 D6
Program extended observability storage area existence
Bit 2



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


214 D6
Program extended observability storage area compression status
Bit 3



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


214 D6
Reserved (binary 0)
Bits 4-7
215 D7
Type of program
Char(1)



Hex 00 = Non-bound program
Hex 01 = Bound program
Hex 02 = Bound service program
Hex 04 = Java program


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
Bit 6



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.


266 10A
Hardware storage protection always enforced for associated space
Bit 7



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.


267 10B
Reserved
Char(1)
268 10C
File identifier
UBin(4)
272 110
Generation identifier
UBin(4)
276 114
Reserved
Char(12)
288 120
Parent of attached object
System pointer
304 130
Number of signers
UBin(4)
308 134
Reserved
Char(36)
344 158
--- End ---

Additional Description

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. (1) 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.

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. The timestamp of creation field is implicitly set when an object is created.

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.

start of change 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.end of change

The timestamp of last modification 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.

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.

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.

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Program dump for previous release reason codes
Char(8)
0 0
Language version, release, and modification level reason
Bit 0



0 = Language version, release, and modification level is not a reason
1 = Language version, release, and modification level is one reason


0 0
Level of machine interface used reason
Bit 1



0 = The level of machine interface used is not a reason
1 = The level of machine interface used not available in the previous release


0 0
Program observability reason
Bit 2



0 = Lack of program observability is not a reason
1 = Program is not observable and must be to be moved to previous release


0 0
Program compressed reason
Bit 3



0 = Program compression is not a reason
1 = The program, of type non-bound program, is compressed and the previous release does not support compression of the non-bound program type of program

Note: This reason code does not apply to bound programs, bound service programs, or Java programs.



0 0
Bound program or bound service program reason
Bit 4



0 = The program type is not a reason
1 = Bound programs and bound service programs are not supported on the previous release


0 0
Bound program or bound service program retranslation reason
Bit 5



0 = Retranslation is not a reason
1 = Retranslation of bound programs and bound service programs are not supported on the previous release


0 0
Java program reason
Bit 6



0 = The program type is not a reason
1 = Java programs are not supported on the previous release


0 0
Target version, release, and modification level reason
Bit 7



0 = Target version, release, and modification level is not a reason
1 = Target version, release, and modification level is a reason

Note: This reason code applies only to programs whose target version, release, and modification level is hex 0510 or later.



0 0
Reserved
Bits 8-63
8 8
--- End ---

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

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Module dump for previous release reason codes
Char(8)
0 0
Language version, release, and modification level reason
Bit 0



0 = Language version, release, and modification level is not a reason
1 = Language version, release, and modification level is one reason


0 0
Level of machine interface used reason
Bit 1



0 = The level of machine interface used is not a reason
1 = The level of machine interface used not available in the previous release


0 0
Module observability reason
Bit 2



0 = Lack of module observability is not a reason
1 = Module is not observable and must be moved to previous release


0 0
Module reason
Bit 3



0 = The object type of module is not a reason
1 = Modules are not supported on the previous release


0 0
Module retranslation reason
Bit 4



0 = Retranslation is not a reason
1 = Retranslation of modules is not supported on the previous release


0 0
Target version, release, and modification level reason
Bit 5



0 = Target version, release, and modification level is not a reason
1 = Target version, release, and modification level is a reason

Note: This reason code applies only to modules whose target version, release, and modification level is hex 0510 or later.



0 0
Reserved
Bits 6-63
8 8
--- End ---

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 last two subfields indicate when hardware storage protection is enforced.

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 (parent object), 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.

Note: Referencing this pointer requires that the receiver (operand 1) be 16-byte aligned. The machine enforces only 4-byte alignment of the receiver.

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

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

0A Authorization

10 Damage Encountered

1A Lock State

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

2E Resource Control Limit

32 Scalar Specification

36 Space Management

38 Template Specification

44 Protection Violation

Footnotes:

(1) 'Previous release' refers to the previous mandatory release. This is release N-1, mod level zero when release N is the current release. (For version 2, release 1.1, the previous mandatory release is version 1, release 3.0.).