Friedkiwi: Document the MI *PGM object: segments, SLS pointers, header chain, and where the instruction stream lives (via create-page on MediaWiki MCP Server)

2026-08-09T11:54:41Z

Document the MI *PGM object: segments, SLS pointers, header chain, and where the instruction stream lives (via create-page on MediaWiki MCP Server)

New page

A '''<code>*PGM</code>''' is a Machine Interface ''program object''. It is not a file with a text section and a symbol table. It is a set of single-level store '''segments''', chained together by 8-byte SLS pointers, with the executable instructions embedded in the first segment among the metadata that describes them.

This page describes enough of that structure to walk a program object offline — that is, without a console session and without printing a storage dump for every object of interest. The bytes can come from a [[File Formats:SAVF|save file]], which makes any distribution medium, PTF or backup a source of real program objects to examine.

Everything below is big endian, and text fields are EBCDIC.

== Addressing ==
Pointers are 8 bytes: a 40-bit segment identifier in the high bits and a 24-bit offset in the low bits, so a segment is 16 MiB. This is the same split used throughout the machine, including by the DST ''Display/Alter storage'' panel and by the SLS address field of a [[Data Structures:LID|LID]] directory record.

<pre>
segment = pointer >> 24
offset = pointer & 0xFFFFFF
</pre>

An all-zero pointer means the object has no data for that structure. That is precisely what the <code>###INFO: OBJECT DOES NOT CONTAIN DATA FOR THIS SECTION</code> line in a Display/Alter/Dump printout is reporting.

Some fields are not pointers but '''<code>SEGOFF</code>''' pairs: a 4-byte segment ''index'', counting from one into the object's own segment table, followed by a 4-byte offset. These appear where a genuine pointer would have to be relocated when the object moves.

The segments of one program have unrelated segment identifiers. A decoder therefore needs the whole set: a single segment cannot resolve its own pointers.

== Segments ==
A single-module bound program typically has four segments, distinguished by the type field in each segment's own header:

{|class="wikitable"
!Type
!Role
|-
|<code>0x0001</code>
|The program object proper: all headers, tables, and the instruction stream.
|-
|<code>0x0022</code>
|Module constants and the module string directory.
|-
|<code>0x0018</code>
|Static storage.
|-
|<code>0x0028</code>
|Trace-back and mapping data.
|}

Note that a program's segment table records a segment ''use'' code, while each segment's own header records a ''type''. They are different numberings and should not be conflated.

=== Segment header ===
Every MI segment opens with a header, called <code>YYSGHDR</code> in IBM's own dump formatting.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|2
|Segment type
|-
|<code>+0x02</code>
|2
|Size, in 512-byte units
|-
|<code>+0x04</code>
|1
|New flags
|-
|<code>+0x05</code>
|1
|Flags
|-
|<code>+0x08</code>
|8
|Address of the owning object
|-
|<code>+0x18</code>
|8
|Space address
|}

=== Object header ===
Immediately after it, at <code>+0x20</code> of the first segment, sits the object header, <code>YYEPAHDR</code>. Offsets below are relative to it.

{|class="wikitable"
!Offset
!Size
!Field
!Notes
|-
|<code>+0x02</code>
|1
|MI object type
|Together with the next byte, <code>0x0201</code> for a program.
|-
|<code>+0x03</code>
|1
|MI object subtype
|
|-
|<code>+0x04</code>
|30
|Object name
|EBCDIC.
|-
|<code>+0x24</code>
|4
|Space size
|
|-
|<code>+0x30</code>
|8
|Creation timestamp
|
|-
|<code>+0x38</code>
|8
|Owning user profile
|A pointer to the profile object.
|-
|<code>+0x48</code>
|8
|Context
|That is, the library.
|-
|<code>+0x50</code>
|8
|Object space
|'''The pointer to the program header.''' Everything else hangs off this.
|-
|<code>+0x5A</code>
|2
|ASP
|
|-
|<code>+0x60</code>
|8
|Last-modified timestamp
|
|}

The type and subtype pair uses the same code space as the item descriptors in a save file, so one table of MI type codes serves both.

== The program header ==
Found through the object header's object-space pointer; in practice it sits at offset <code>0x1000</code> of the first segment.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|8
|Program attributes
|-
|<code>+0x08</code>
|8
|Pointer to the version table
|-
|<code>+0x10</code>
|8
|Pointer to the segment table
|-
|<code>+0x18</code>
|8
|Pointer to the activation header
|-
|<code>+0x20</code>
|8
|Pointer to the signature table
|-
|<code>+0x28</code>
|8
|Pointer to the program string directory
|-
|<code>+0x30</code>
|8
|Pointer to activation group information
|-
|<code>+0x40</code>
|8
|Activation start
|-
|<code>+0x48</code>
|8
|Activation end
|-
|<code>+0x50</code>
|8
|'''Activation and PEP end''' — the last byte of the code
|-
|<code>+0x58</code>
|2
|Flags
|-
|<code>+0x5C</code>
|2
|Program state
|-
|<code>+0x90</code>
|1
|Program type
|-
|<code>+0x94</code>
|4
|Program entry procedure module number
|-
|<code>+0x9C</code>
|4
|Program entry procedure string ID
|-
|<code>+0xA0</code>
|2
|Minimum parameters
|-
|<code>+0xA2</code>
|2
|Maximum parameters
|-
|<code>+0xD0</code>
|8
|Pointer to the program header extension
|-
|<code>+0xD8</code>
|8
|Pointer to the trace-back locator
|-
|<code>+0xE0</code>
|8
|Pointer to the module table
|-
|<code>+0xE8</code>
|8
|Pointer to observability information
|-
|<code>+0xF0</code>
|8
|Pointer to the maintenance header
|}

The header extension adds a pointer to the GLU code list, <code>SEGOFF</code> pairs for the program history and the segment table extension, and a 16-byte hardware feature set at <code>+0x50</code>.

=== Version table ===
Forty bytes of packed version-release-modification halfwords, where <code>0x0740</code> reads as V7R4M0. Among them are the binder's internal and MI levels at <code>+0x02</code> and <code>+0x04</code>, the '''target''' release at <code>+0x06</code>, the '''created-on''' release at <code>+0x08</code>, the language release at <code>+0x10</code>, the CCSID at <code>+0x1E</code> and the low and high optimisation levels at <code>+0x20</code> and <code>+0x22</code>.

The target and created-on values here are what decide whether an object will restore onto a given release, so they are worth reading before attempting a restore that might fail.

=== Segment table ===
A header of allocated size, entry count and version, then the entries beginning at <code>+0x10</code>. '''Entries are a fixed 48 bytes'''; the size field is the allocation, not header plus count times entry, so deriving the stride from it gives the wrong answer.

Each entry holds the segment address at <code>+0x00</code>, a limbo address at <code>+0x08</code>, a declared page count at <code>+0x10</code>, and a one-byte ''segment use'' at <code>+0x12</code>: <code>0x01</code> static storage, <code>0x02</code> the program object, <code>0x04</code> constants, <code>0x06</code> trace-back.

A parallel ''segment table extension'', reached by a <code>SEGOFF</code> in the program header extension, records how much of each segment is actually used as opposed to allocated. Its entries begin at <code>+0x18</code> and are 24 bytes, of which the first four are the byte count.

=== Activation header ===
{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|8
|'''Program entry procedure entry point''' — the first instruction
|-
|<code>+0x08</code>
|4
|PBV size
|-
|<code>+0x10</code>
|8
|Pointer to the PBV relocation array
|-
|<code>+0x18</code>
|8
|Pointer to the static PBV array
|-
|<code>+0x20</code>
|4
|PBV relocation count
|-
|<code>+0x24</code>
|4
|Dependent service program count
|-
|<code>+0x28</code>
|8
|Pointer to the dependent service program array
|-
|<code>+0x4C</code>
|4
|Constant frame count
|-
|<code>+0x50</code>
|8
|Pointer to the constant frame definition array
|-
|<code>+0x58</code>
|8
|Pointer to the program export array
|-
|<code>+0x60</code>
|4
|Export count
|}

For a bound program with no exports most of these are zero. For a service program they are the published interface, and the dependent service program array is the object's dependency list — which makes it possible to work out what a program binds to without a machine to run <code>DSPPGM</code> on.

=== Maintenance header ===
Holds the copyright list size and count and a <code>SEGOFF</code> to the copyright text — a 4-byte length followed by EBCDIC — along with <code>SEGOFF</code> pairs for the external object list, static activation and export information, the last non-observable segment and size, and the lowest and highest PBV identifiers.

== Modules ==
The module table has the same shape as the segment table: header, then 48-byte entries from <code>+0x10</code>, each giving a pointer to a module header, a module domain and a module subtype.

A module header is a long run of pointers: to the program header it belongs to, the copyright table, the module version table, binding information, static information, the end-of-line table, observability information, the module string directory, the entry point table, the VLIC table, the procedure table, module constants, and the module header extension. It also carries the module type at <code>+0x01</code> — <code>0x01</code> for OPM and <code>0x03</code> for ILE — the module attributes at <code>+0xA8</code>, and the program entry procedure's dictionary ID, string ID, procedure number and parameter counts from <code>+0xAC</code> to <code>+0xBC</code>.

Two of its pointers characteristically leave the program segment: the module string directory and the module constants both live in the <code>0x0022</code> segment. When hunting for literal data referenced by the code — message identifiers, format names, table constants — that is the segment to search, and these two pointers give its exact extent.

=== Module version table ===
This is the most immediately informative structure in the whole object.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x02</code>
|2
|Language release
|-
|<code>+0x0A</code>
|2
|Instruction release
|-
|<code>+0x0C</code>
|2
|Target release
|-
|<code>+0x0E</code>
|2
|Created-on release
|-
|<code>+0x10</code>
|2
|Optimisation level
|-
|<code>+0x14</code>
|30
|Source module name
|-
|<code>+0x32</code>
|30
|Source module qualifier
|-
|<code>+0x50</code>
|20
|Compiler name
|-
|<code>+0x64</code>
|2
|Earliest compiler release
|}

Read the compiler name before spending any time on a disassembly. A module reporting <code>MX CONVERTED</code> was ''translated'' from an older object rather than compiled from source at this release, and the generated code will not resemble what a current compiler emits.

== The instruction stream ==
The code is a single contiguous run inside the first segment, bounded by two fields already listed above:

<pre>
start = activation header, program entry procedure entry point
end = program header, activation and PEP end (inclusive)
</pre>

It is 64-bit big-endian '''PowerPC AS'''. A stock disassembler invoked as <code>objdump -D -b binary -m powerpc:common64 -EB</code>, with the load address adjusted to the start offset, will produce a listing whose addresses line up with anything printed by Display/Alter/Dump.

Two caveats apply, and both matter.

PowerPC AS is not plain PowerPC. The tagged-pointer instructions and other AS-only operations have no encoding in a stock PowerPC disassembler and will appear as invalid, or worse, as an unrelated mnemonic that looks plausible. Treat such a listing as a starting point rather than as authority.

The run is also not pure code. Trace-back tables and constants are interleaved with instructions, so a linear sweep will decode data as code somewhere. For an object that still has its observability information, the trace-back locator and the module tables provide the boundaries needed to separate the two; for an object whose observability has been removed, they do not, and the separation has to be inferred from the code itself.

== Scope of this description ==
Field offsets were derived by lining a printed Display/Alter/Dump of a program object up against the same object's bytes extracted from a save file, and then checked by decoding the object independently and comparing every field against the printout. Structures that the dump prints but that were empty in the object used — the signature table, the export and import arrays, the service program tables and the secondary entry point table — are located by pointer but their contents are not described here; establishing those needs a service program to work from.

Only <code>*PGM</code> is covered. <code>*SRVPGM</code> and <code>*MODULE</code> share much of this layout but have additional tables of their own.

== See also ==
* [[File Formats:SAVF]] — how to get a program object's bytes off a machine or out of a distribution medium
* [[Data Structures:LID]] — the same single-level store address split, in a different container

[[Category: System Internals]]

File Formats:PGM - Revision history

Friedkiwi: Document the MI *PGM object: segments, SLS pointers, header chain, and where the instruction stream lives (via create-page on MediaWiki MCP Server)