GOFF

The GOFF (Generalized Object File Format) specification was developed for IBM's MVS operating system to supersede the IBM OS/360 Object File Format to compensate for weaknesses in the older format. ^[1]

Background

The original IBM OS/360 Object File Format was developed in 1964 for the new IBM System/360 mainframe computer. The format was also used by makers of plug compatible and workalike mainframes, including the Univac 90/60, 90/70 and 90/80 and Fujitsu B2800. The format was expanded to add symbolic records and expanded information about modules, plus support for procedures and functions with names longer than 8 characters. While this helped, it did not provide for the enhanced information necessary for today's more complicated programming languages and more advanced features such as objects, properties and methods, Unicode support, and virtual methods.

The GOFF object file format was developed by IBM approximately in 1995 as a means to overcome these problems. ^[2] The earliest mention of this format was in the introductory information about the new High Level Assembler. ^[3] Note that the OS/360 Object File Format was simply superseded by the GOFF format, it was not deprecated, and is still in use by assemblers and language compilers where the language can withstand the limitations of the older format.

Conventions

This article will use the term "module" to refer to any name or equivalent symbol, which is used to provide an identifier for a piece of code or data external to the scope to which it is referenced. A module may refer to a subroutine, a function, Fortran Common or Block Data, an object or class, a method or property of an object or class, or any other named routine or identifier external to that particular scope referencing the external name.

The terms "assembler" for a program that converts assembly language to machine code, as well as to "assemble" as the process of using one, and to "compile," as the process of using a "compiler," which does the same thing for high-level languages, should, for the purposes of this article. be considered interchangeable; thus where "compile" and "compiler" are used, substitute "assemble" and "assembler" as needed.

Numbers used in this article are expressed as follows: unless specified as hexadecimal (base 16), all numbers used are in decimal (base 10). When necessary to express a number in hexadecimal, the standard mainframe assembler format of using the capital letter X preceding the number, expressing any hexadecimal letters in the number in upper case, and enclosing the number in single quotes, e.g. the number 15deadbeef₁₆ would be expressed as X'15DEADBEEF'.

A "byte" as used in this article, is 8-bits, and unless otherwise specified, a "byte" and a "character" are the same thing; characters in EBCDIC are also 8-bit. When multi-byte character sets (such as Unicode) are used in user programs, they will use two (or more) bytes.

Requirements and restrictions

The format is similar to the OS/360 Object File Format but adds additional information for use in building applications. ^[4]

• GOFF files are either fixed- or variable-length records.
• A GOFF record must completely fit within a single record of the underlying file system. A GOFF file is not a stream-type file.
• Fixed-length records must be 80 bytes. The minimum size of a variable-length record is 56 bytes. In the case of fixed-length records, there will be unused bytes at the end of a record. These bytes must be set to binary zero.
• The program reading (or writing) GOFF records is not to make assumptions about the internal format of records, the operating system is presumed to be able to provide fixed- or variable-length records without the program reading them needing to be aware of the operating system internal file management. The length of a record is not part of the record itself.
• Binary values are stored in big endian format, e.g. the value 1 is X'01' for an 8-bit value, X'0001' for a 16-bit value, X'00000001' for a 32-bit value, and X'0000000000000001' for a 64-bit value.
• Bits are counted from left to right; bit 0 is the left-most bit in a byte or word.
• Fixed-length records are required for GOFF files deployed on Unix systems.
• A record may be continued on a subsequent record. Where a record is continued, no intervening record(s) shall occur between the record being continued and the continuation record.
• A GOFF object file starts with an HDR record and ends with an END record. The END record should include the number of GOFF records (not the number of physical records) in the file.
• A language compiler or assembler can produce multiple GOFF files in one compilation/assembly, but the individual GOFF files must be separate from each other. This means that a module or compilation unit, consisting of an HDR record, intervening ESD, TXT and others, finishing with an END record, may then be followed by another compilation unit starting with HDR and ending with END, and so on, as needed.
• Module and Class names are case sensitive. A module named "exit" (as used by the C language) need not be the same as "EXIT" used by the Fortran language.
• Some conventions applicable to the OS/360 Object File Format are carried over to the GOFF Object File Format, including:
  • Unless otherwise specified, all characters are in the EBCDIC character set, except for external names, as stated below.
  • ESD items (Main programs, subroutines, functions, FORTRAN Common, methods and properties in objects) must be numbered starting with 1 and each new item is to have the next number in sequence, without any 'gaps' in the numbering sequence.
  • An ESD item must be defined before any other record (such as a TXT or RLD record) references it.
  • Each ESD record contains exactly one ESD item. (This is different from the old format, which permitted up to 3 ESD items in each ESD record.)
  • An RLD record (relocation dictionary ^[5] ) may contain one or more items, and an RLD record may be continued to a subsequent record.
  • To ensure future compatibility, fields indicated as 'reserved' should be set to binary zero.
  • Character sets used for external names are not defined by the GOFF standard, but there is a provision for a file to indicate what character set is being used. (This is to support double-byte character set Unicode-based module names.) Some IBM products, however, only allow characters for external names and other identifiers to a restricted range, typically (EBCDIC) hexadecimal values of X'41' through X'FE' plus the shift-in and shift out characters, X'0F' and X'0E', respectively.
• The new format supports Class names, of which there are two types, reserved and user supplied or non-reserved. All class names have a maximum length of 16 characters.
• Reserved Class names consist of a single letter, an underscore, and 1 to 14 characters. Reserved Class names beginning with B_ are reserved for the binder; Reserved Class names beginning with C_ marked as loadable are reserved for programs created for use with IBM's Language Environment (LE). Class names beginning with C_ which are not marked as loadable, as well as classes beginning with X_, Y_ or Z_ are available for general use as non-reserved.
• User Supplied class names may be lower-case.
• Class names are not external symbols.

The following classes used by the binder may be referenced if needed for compilation purposes:

B_ESD	External Symbol Dictionary Class
B_TEXT	Text Class
B_RLD	Relocation Dictionary Class
B_SYM	Internal Symbol Table Class
B_IDRL	Language-Translator Identification Data Class
B_PRV	Pseudo-Register Class
B_IDRU	User-specified Identification Data Class

The following class names are reserved by the binder and are not accessible to user applications:

B_IDRB	Binder Data Information
B_IDRZ	SUPER-Zap Data Information
B_IMPEXP	Import-Export Table
B_LIT	Loading Information Table
B_MAP	Mapping Data

• The SYM object file symbolic table information from the 360 Object File format record is not available for GOFF object files; the ADATA record (sub-record to TXT) must be used instead.

Size limit

According to the Users Guide for z/OS XL C/C++ User's Guide, "The maximum size of a GOFF object is 1 gigabyte." ^[6]

Record Types

Similarly to the older OS/360 format, object file records are divided into 6 different record types, some added, some deleted, some altered:

• HDR record (this is new) must occur first, it defines the header for the object file.
• ESD records define main programs, subroutines, functions, dummy sections, Fortran Common, methods and properties, and any module or routine that can be called by another module. They are used to define the program(s) or program segments that were compiled in this execution of the compiler, and external routines used by the program (such as exit() in C, CALL EXIT in Fortran; new() and dispose() in Pascal). ESD records should occur before any reference to an ESD symbol.
• TXT records have been expanded, and in addition to containing the machine instructions or data which is held by the module, they also contain Identification Data (IDR) records (20 or more types), Associated Data (ADATA) records, and additional information related to the module.
• RLD records are used to relocate addresses. For example, a program referencing an address located 500 bytes inside the module, will internally store the address as 500, but when the module is loaded into memory it's bound to be located someplace else, so an RLD record informs the linkage editor or loader what addresses to change. Also, when a module references an external symbol, it will usually set the value of the symbol to zero, then include an RLD entry for that symbol to allow the loader or linkage editor to alter the address to the correct value.
• LEN records are new, and supply certain length information.
• END records indicate the end of a module, and optionally where the program is to begin execution. This must be the last record in the file.

Format

GOFF records may be fixed or variable length; the minimum length when using variable-length records is 56 characters, although most records will be longer than this. Except for module and class names, all characters are in the EBCDIC character set. Unix-based systems must use fixed-length (80-byte) records. Records in fixed-length files that are shorter than the fixed length should be zero-filled. To distinguish GOFF records from the older OS/360 object format (where the first byte of a record is X'02') or from commands that may be present in the file, the first byte of each GOFF record is always the binary value X'03', while commands must start with a character value of at least space (X'40'). The next 2 bytes of a GOFF record indicate the record type, continuation and version of the file format. These first 3 bytes are known as the PTV field.

PTV

The PTV field represents the first 3 bytes of every GOFF record.

PTV Field

Byte	Bits	Value	Purpose
0	All	03	Indicates start of a GOFF record
1	0-3	0	ESD (External Symbol) record
		1	TXT (Text) record
		2	RLD (Relocation) record
		3	LEN (Length) record
		4	END (End) record
		X'5'-X'E'	Reserved
		X'F'	HDR (Header) record
	4-5		Reserved
	6-7	00	Initial record that is not continued on the next record. This should be the only value used for variable-length GOFF records
		01	Initial record which is continued on next record
		10	Continuation record not continued on next record
		11	Continuation record which is continued on the next record
2	All	00	Version Number of the object file format. All values except X'00' are reserved

HDR

The HDR record is required, and must be the first record.

HDR Record

Byte(s)	Size	Field	Value	Purpose
0-2	3	PTV	X'03F000'	Only allowed value; HDR record currently cannot be continued
3-47	45		0	Reserved
48-51	4	Architecture Level	Binary 0 or 1	GOFF Architecture level; all values except 0 and 1 are reserved
52-53	2	Module Properties Size	binary	Length of Module Properties Field
54-59	6		0	Reserved
60-	0+	Module Properties		Module Properties List (optional)

ESD

An ESD record gives the public name for a module, a main program, a subroutine, procedure, function, property or method in an object, Fortran Common or alternate entry point. An ESD record for a public name must be present in the file before any reference to that name is made by any other record.

ESD Record

Byte(s)	Size	Field	Value (or bits)	Purpose
0-2	3	PTV	X'030000'	ESD record with no continuations
			X'030100'	ESD record which is continued on next record
3	1	Symbol Type	00	SD - Section Definition; This is used for the former SD, CM (Common) and PC (Private Code, an SD whose name is blank) values. The "Parent" ESDID value must be 0. This is used to define a main program, a subroutine or function for which the code is part of this file. Also used for Fortran Common.
			01	ED - External Definition. "Parent" ESDID must be non-zero, and be the value of an SD entry that references this external symbol. If an RLD value refers to a class this entry belongs to, the Class that this element refers to must be specified in the External Name field. This is used to name a called procedure or function.
			02	LD - Label Definition. "Parent" ESDID must be non-zero, and be the value of an SD entry that defines this symbol within itself. This can be used to create an alias for the module or to expose a portion of it as a separate routine. For example, the run-time library for a particular programming language might have certain features it has to use itself, but which are useful by programs written using that language, and so a feature could be given a label so it can be called directly. For example, there may be a complete mathematics package as a single module, and all of the standard functions (Sine, Cosine, Square Root, etc.) could be named entry points in that module.
			03	PR - Part Reference or Pseudo Register. Distinguished by Name Space ID field. "Parent" ESDID must be non-zero, and be the value of an SD entry that defines this symbol within itself.
			04	ER and WX - External Reference / Weak External Reference. Distinguished between by the "Binding Strength" value of the "Attributes" field. WX is used where the foreign routine may be missing. For example, if a calculator program had a fast high-performance math package that was optional, it could be called as a WX, and if it was missing or not available, the program could downgrade to a lesser math package.
4-7	4	ESDID	Binary	ESDID identifier starting with 1. Each new ESDID must be exactly 1 higher than the previous entry.
8-11	4	Parent ESDID	binary	This is the ESDID of the object that defines this entry, if it is part of another object. It is 0 if it has no parent.
12-15	4		0	Reserved
16-19	4	Offset	Binary	Address of this symbol within its Parent ESDID for LD or ED entries; zero otherwise.
20-23	4		0	Reserved
24-27	4	Length	Binary	Length of this item for ED and PR types; zero otherwise. If the actual length value is deferred; this value is set to -1.
28-31	4	Extended Attribute ESDID	Binary	ESDID of element that contains extended attribute information for ED and LD types; typically used where DLLs are supported for symbols which are resolved at run time (like virtual methods). Zero otherwise.
32-35	4	Extended Attribute Offset	Binary	Address where extended attributes can be found for the previous field, used for ED and LD records having extended attributes; zero otherwise.
36-39	4		0	Reserved
40	1	Name Space ID	Identifies the name space this belongs to
			0	Reserved for Program Management Binder
			1	Normal Name
			2	Pseudo Register
			3	Parts (External entries allocated space including items containing initialized static data)
41	1	Flags
		Fill Present	Bit 0	0	No Fill
				1	Fill Byte Present (only valid for ED types)
		Mangled	Bit 1	0	Symbol is not mangled
				1	Symbol may be mangled
		Renameable	Bit 2	0	Cannot be renamed (same as 'mapped' flag in XOBJ)
				1	Symbol can be renamed (Can participate in Language Environment (LE) type renaming)
		Removable Class	Bit 3	0	(Default) Not Removable
				1	This Class can optionally be deleted without affecting the program's operation (Only valid for ED types)
			Bits 4-6	Reserved
		Reserve Extra Space	Bit 7	0	No Extra Space Reserved
				1	Reserve 16 bytes of space at the beginning of the Class (MRG class ED type only)
42	1	Fill Value		Value of Fill byte, if Fill Present flag is set
43	1		0	Reserved
44-47	4	Associated Data	Binary	Used for ID of environment or static area for LD items using XLINK
48-51	4	Priority	Binary	Sort order of PR items
52-59	8		0	Reserved
60-69	10	Behavioral Attributes		Behavior Attributes for this item (See Behavior Attributes table below)
70-71	2	Name Length	Binary	Length of this item's name; cannot be zero
72-		Name	Text	Name of this item with trailing blanks truncated. Must be at least one character; Private Code consists of a single blank. Name is case sensitive.
REM			0	Trailer: Unused space if needed for fixed-size records; must be zero filled. Not needed in variable-length records.

Continuation

In the case of fixed-length records where the name requires continuation records, the following is used:

ESD Continuation Record

Byte(s)	Size	Field	Value	Purpose
0-2	3	PTV	X'030200'	ESD continuation record with no further continuations
			X'030300'	ESD continuation record which is continued on next record
3-		Name	Text	The rest of the name if this record is not continued, or the next 77 bytes of the name if continued.
REM			0	Remainder for a fixed-length record longer than the data supplied. It contains the trailing bytes if this is the last record for this name and the name is shorter than the record size; must be 0 filled. This field is not present in variable-length records.

Behavior Attributes

Behavioral Attributes Field (bytes 60-69 of ESD record)

Offset	Size (Bytes)	Bits	Field	Value	Purpose
0	1		Addressing Properties	Addressing mode associated with this external symbol. These values are also used by the AMODE field of the END record.
				00	AMODE not specified (defaults to AMODE (24))
				01	AMODE(24)
				02	AMODE(31)
				03	AMODE(ANY) (24 or 31)
				04	AMODE(64)
				10	AMODE(MIN) (Use the smallest AMODE used by all modules)
1	1		Residence Properties	External Symbol's Associated Residence Mode
				00	RMODE not specified (defaults to RMODE (24))
				01	RMODE(24)
				03	RMODE(31) (Equivalent to RMODE(ANY))
				04	RMODE(64)
2	1	0-3 (4)	Text Record Style	Style of text for this class (ED and PR types only) All text must be the same style
				0000	Byte-oriented
				0001	Structured data (Binder Oriented)
				0010	Structured data (user defined)
		4-7 (4)	Binding Algorithm	Data Binding Method
				0000	Concatenate all items one after another
				0001	Merge (all identically named items will be located at the same space, using the largest size specified, and most restrictive alignment). Differently named items will be concatenated. This is the usual practice for CM and PR types.
3	1	0-2 (3)	Tasking Behavior	Indication whether module is reentrant and/or reusable
				000	Unspecified
				001	Neither Reusable nor Reentrant (NON-REUS)
				010	Serially Reusable (REUS)
				011	Reentrant (RENT), also implies (REUS)
		3		0	Reserved
		4	Read Only	0	Not Read Only
				1	Read Only
		5-7 (3)	Executable	000	Not Specified
				001	Not Executable (Data only)
				010	Executable (Code or Code and data)
4	1	0-1 (2)		0	Reserved
		2-3 (2)	Duplicate Symbol Severity	Level of error a duplicate symbol should raise (PR type records only)
				00	Binder determines severity
				01	Minimum 4 (Warning)
				10	Minimum 8 (Error)
				11	Reserved
		4-7 (4)	Binding Strength	Weak references will not search other libraries; Strong references will search other libraries for the symbol. Strong Definitions can be resolved to any reference; this is the default.
				0000	Strong
				0001	Weak
5	1	0-1 (2)	Class Loading Behavior	Determines whether the elements of a class will be loaded in the case of an Operating System LOAD request is used with respect to an object
				00	LOAD - Load this class
				01	DEFERRED LOAD - This class will probably be used and should be loaded
				10	NOLOAD - Do not load this class
				11	Reserved
		2	Common Flag		If 1, treat as "old" CM-type COMMON where multiple references set the size to the largest area being used by any reference. An SD type with the same name will keep the size and text. The only text type supported for this is B_TEXT.
		3	Direct vs. Indirect Reference	0	Direct References (for purposes of the Binder)
				1	For PR type, this is a linkage descriptor; for ER type, this is a reference to an XPLINK linkage descriptor
		4-7 (4)	Binding Scope	0000	Unspecified
				0001	Section scope (“local”)
				0010	Module scope (“global”)
				0011	Library scope
				0100	Import-Export scope
6	1	0-1 (2)		Reserved
		2	Linkage Type	For ER, LD, PD, and PR types
				0	Standard O/S linkage (default)
				1	XPLINK Linkage
		3-7 (5)	Alignment	Implied Alignment of this item
				00000	Byte
				00001	Halfword
				00010	Fullword
				00011	Doubleword
				00100	Quadword
				00101	4KB page
				All alignments shown are available for ED and PR types except PR cannot use page alignment
7-9	3			Reserved

ADATA records

ADATA ("associated data") records are used to provide additional symbol information about a module. They replaced the older SYM records in the 360 object file format. To create an ADATA record

• Create an ESD record of type ED for the class name that the records are part of
• Set all fields in the Behavioral Attributes record to 0 except
  • Class Loading (bits 0-1 of byte 5) is X'10'
  • Binding Algorithm is 0
  • Text Record Style (bits 0-3 of byte 2) is X'0010'
  • Optionally set the Read Only (bit 4 of byte 3) and Not Executable (bits 5-7 of byte 3) values if appropriate
• Create a TXT record for each ADATA item
  • Element ESDID is the value of the ADATA ED record for that particular ADATA entry
  • Offset is zero
  • Data Length is the length of the ADATA record
  • Data field contains the actual ADATA record itself

ADATA records will be appended to the end of the class in the order they are declared.

Class names assigned to ADATA records are translated by IBM programs by converting the binary value to text and appending it to the name C_ADATA, So an item numbered X'0033' would become the text string C_ADATA0033.

ADATA record types

TYpe	Description
X'0000' - X'7FFF'	Translator records (note that some values in the range 0-X'0130' are in use by some IBM language translator products including Assembler, Cobol and PL/I).
X'8000' - X'8FFF'	Program Management records
X'9000' - X'DFFF'	Reserved
X'E000' - X'EFFF'	Reserved for compilers and assemblers not released by IBM.
X'F000' - X'FFFF'	Available for User Records. IBM will not use these values.

TXT

TXT records specify the machine code instructions and data to be placed at a specific address location in the module. Note that wherever a "length" must be specified for this record, the length value must include any continuations to this record.

TXT Record

Byte(s)	Size	Field	Bits	Value	Purpose
0-2	3	PTV		X'031000'	TXT record with no continuations
				X'031100'	TXT record which is continued on next record
3	1		0-3 (4)		Reserved
		Style	4-7 (4)	All other values are reserved
				0000	Byte Oriented Data
				0001	Structured Data (currently the only structured data supported are the 19-byte IDR fields; see IDR Data Table)
				0010	Unstructured Data
4-7	4	Element ESDID	Binary number		ESDID that the contents of this record belong to
8-11	4				Reserved
12-15	4	Offset	Binary address		Address within ESDID where this data is to be placed. This should be 0 for structured and unstructured data.
16-19	4	Text field true length	binary value: 0 or full size after expansion		If Text Encoding field is 0, this must be 0. Otherwise this field is the full size of the text after decompression or unpacking
20-21	2	Text Encoding	binary value		0 if text does not require replication, unpacking, or decoding; nonzero to indicate text must be decoded, unpacked or expanded; see Compression Table
22-23	2	Data Length	binary value greater than zero		Total length of the data on this record in bytes as an unsigned value, and cannot be zero, however, this may be partially incorrect, as noted below in Caution.
24-		Data			Machine code and/or data to be inserted. If IDR data is included it is subject to special rules and requirements, see IDR Data Table
REM					Not present for variable-length records; remainder bytes for fixed record longer than remaining data, and must be binary zeroes

Caution

The data length in bytes 22-23 being an unsigned value may be incorrect. According to comments in the GOFF generator part of the LLVM Compiler suite,

"The maximum number of bytes that can be included in an RLD or TXT record and their continuations is a SIGNED 16 bit int despite what the spec says. The number of bytes we allow ourselves to attach to a card is thus arbitrarily limited to 32K-1 bytes." ^[7]

Continuation

TXT Continuation Record

Byte(s)	Size	Field	Bits	Value	Purpose
0-2	3	PTV	X'031200'		Continuation Record with no further continuations
			X'031300'		Continuation Record which is continued next record
3-					Data continued from previous record
REM					If remainder of record is longer than data; zero filled

Compression Table

A compression table is used if bytes 20-21 of the TXT record is nonzero. The R value is used to determine the number of times to repeat the string; the L value indicates the length of the text to be repeated "R" times. This could be used for pre-initializing tables or arrays to blanks or zero or for any other purpose where it is useful to express repeated data as a repeat count and a value.

Compression Table

Byte(s)	Size	Field	Value	Purpose
If value in bytes 20-21 of this TXT record is 0001
0-1	2	R	Repeat Count, an unsigned integer greater than 0		Number of times to repeat the string starting in byte 4.
2-3	2	L	Binary length, an unsigned integer greater than 0		Length of string starting in byte 4
4-		String			The string, of length "L" which is to be repeated "R" times.
All other values for bytes 20-21 are reserved

IDR Data Table

The IDR Table, which is located starting at byte 24 of the TXT record, identifies the compiler or assembler (and its version number) that created this object file.

IDR Field

Byte(s)	Size	Field	Value	Purpose
0	1		x'00'	Reserved
1	1	Type	Type of IDR field (note that Primary and Secondary identification refers to the first and second identification fields, respectively, appearing on the END card in the former OS/360 Object Module File Format.)
			00	Primary Identification; Old IDR format 1
			01	Secondary Identification; Old IDR format 1
			02	Extended Identification; IDR format 2
			03	Primary Identification; IDR format 3
			04	Secondary Identification; IDR format 3
2-3	2	Length	Binary number	Length of IDR data as unsigned integer greater than zero
4+				IDR data according to the specified format in byte 1 of this field; see the appropriate IDR Format table for details

IDR Format 1

Note that unlike most number values stored in a GOFF file, the "version", "release" and "trans_date" values are numbers as text characters instead of binary

Format 1 (old format)

Byte(s)	Size	Field	Value	Purpose
0-9	10	Translator	Any text	This value is what the assembler or compiler identifies itself as; IBM calls this the "PID value" or "Program ID value" from IBM's catalog numbers of various programs, e.g. the Cobol Compiler for OS/VS1 is called "IKFCBL00"
10-11	2	Version	two digits	This is the version number of the assembler or compiler, 0 to 99.
12-13	2	Release	two digits	This is the release number subpart of the version number above, also 0 to 99
14-18	5	Trans_Date	YYDDD	5 text characters indicating the 2-digit year, and the 3-digit day of the year this module was compiled or assembled; years 01-65 are presumed to be in the 21st Century, while year 00 or years greater than 65 are presumed to be in the 20th Century, e.g. 2000 or 1966-1999. The three digit day starts at 001 for January 1; 032 for February 1; 060 is March 1 in standard years and February 29 in leap years; and continuing through 365 for December 31 in standard years and 366 for leap years.

IDR Format 2

Normally compilers and assemblers do not generate this format record, it is typically created by the binder.

Format 2

Byte(s)	Size	Field	Value	Purpose
0-3	4	Date	Packed decimal form YYYYDDDF	Date module was assembled or compiled, with the year and day of the year
4-5	2	Data_Length	Binary value	Actual length of next field, an unsigned, nonzero value
6-85	80	IDR_Data		Format of this data has not been disclosed

IDR Format 3

All text in this item are character data; no binary information is used.

Format 3

Byte(s)	Size	Field	Value	Purpose
0-9	10	Translator		Any text value the compiler/assembler writer wishes to use to identify itself (see the Translator field in old IDR Format 1 above)
10-11	2	Version	00 to 99	Version number of the assembler or compiler
12-13	2	Release	00 to 99	Release number of above version
14=20	7	Compile_Date	YYYYDDD	Year and day of year the program was compiled or assembled (this would be the same format as the 'Trans Date' field from IDR Format 1 above, except the year is a full 4-digit year).
21-29	9	Compile_Time	HHMMSSTTT	Hour, minute, second and thousandth of second that the program was compiled or assembled

RLD

RLD records allow a module to show where it references an address that must be relocated, such as references to specific locations in itself, or to external modules.

Relocation Directory

Byte(s)	Size	Field	Value	Purpose
0-2	3	PTV	X'032000'	Record is not continued
			X'032100'	Record continues on next record
3	1			Reserved
4-5	2	Length	Binary Number	Size of relocation data; unsigned and must be greater than zero
6-		Relocation_Data		The relocation data; see Relocation Data table
REM				Not present on variable-length records; remainder of record where record is longer than data, must be zero-filled

Relocation Data

Relocation Data Item

Byte(s)	Size	Field	Value	Purpose
0-5	6	Flags		Flags regarding this entry; see Flags table for values
6-7	2	Reserved
8-11	4	R_Pointer	ESDID of module (type ED or ER) to use as the target to relocate	This is the "distant" address, either in the same or a different module, that the program needs resolved. This field is omitted if bit 0 of byte 0 of the Flags field is 1.
12-15[A]	4	P_Pointer	ESDID of module that requires the address to be relocated	This is the module that wants its reference to a distant identifier to be altered to the correct value. This field is omitted if bit 1 of byte 0 of the Flags field is 1.
16-19[B]	4	Offset	Location within module specified by P_Pointer where the address to be adjusted is to be found.	This is the address to be relocated. This field is omitted if bit 2 of byte 0 of the Flags field is 1.
20-23[C]	4			Reserved
24-27[C]	4			Reserved

^[A] If R_Pointer (bit 0 of byte 0 of Flags field is 1) is omitted, this field starts 4 bytes lower, in bytes 8-11.
^[B] If R_Pointer or P_Pointer (bit 1 of byte 0 of Flags field is 1) is omitted, this field starts 4 bytes lower, in bytes 12-15. If both fields are omitted, this field starts 8 bytes lower, in bytes 8-11.
^[C] If R_Pointer, P_Pointer, or Offset (bit 2 of byte 0 of Flags field is 1) are omitted, this field starts 4 bytes lower. If any two of them are omitted, this field starts 8 bytes lower. If all of them are omitted, this field starts 12 bytes lower.

To clarify, if a module in a C program named "Basura" was to issue a call to the "exit" function to terminate itself, the R_Pointer address would be the ESDID of the routine "exit" while the P_Pointer would be the ESDID of "Basura". If the address was in the same module (like internal subroutines, or a reference to data within the same module) R_Pointer and P_Pointer would be the same.

Flags

RLD Item Flags

Byte(s)	Size	Field	Bits	Purpose
0	1	Same_R_ID	0	1 If the R_Pointer value for this entry is the same as the previous item in this record; if so, the R_Pointer value is omitted from this entry.
		Same_P_ID	1	1 If the P_Pointer value for this entry is the same as the previous item in this record; if so, the P_Pointer value is omitted from this entry.
		Same_Offset	2	1 If the Offset value for this entry is the same as the previous item in this record; if so, the Offset value is omitted from this entry.
			3-4	Reserved
			5	Reserved
		Offset_length	6	0 to indicate 4 byte length
		Addressing mode sensitivity	7	0 No Sensitivity
				1 Set the high bits of the address to the same as the R mode addressing mode of the R_Pointer address (applies only to V-type addresses)
1	1	R_Pointer_Indicators	0-3	Data Type of Second Operand of relocation address
				0 - R-address
				1 - Offset from start of R-address
				2 - R-Length (0 for LD items)
				6 - Relative immediate (to allow instructions to address external symbols)
				7 - R Constant (nonshared data area)
				9 - 20-Bit long displacement address
				All other values are reserved
			4-7	Type of item referring to the value needing to be relocated.
				0 - Label, R-ID is restricted to LD
				1 - Element, R-ID is restricted to ED
				2 - Class, R-ID is restricted to ED; Classes do not have external names so they do not have an ESDID
				3 - Part, R-ID is restricted to PR
				All other values are reserved
2	1	Action_or_Operation	0-6	Type of operation to use with second operand (the first operand would be 0) the result is a 32-bit signed value which replaces the first operand
				0 - Add second operand to first
				1 - Subtract second operand from first
				All other values are reserved
		Fixup Target Fetch/Store	7	Indicates whether to use or ignore target value
				0 - Use fixup/target field as first operand
				1 - Ignore value of target field use fixup value as first operand; if no fixup value, use 0
3	1	Reserved
4	1	Target Length		Unsigned length of target field in bytes
5	1	Reserved

LEN

LEN records are used to declare the length of a module where it was not known at the time the ESD record was created, e.g. for one-pass compilers.

Field	Offset	Size	Description
PTV	0-2	3	Record Type X'033000'
	3-5	3	Reserved
Length	6-7	2	Length of items following this field; value must be non-zero
Elements	8-		Element length data; see Elements table below
REM			Trailing data to end of record for fixed-length records, must contain binary zeroes; not present for variable-length records.

Elements

A deferred-length element entry cannot be continued or split

Field	Offset	Size	Description
ESDID	0-3	4	ESDID of element this value applies to
	4-7	4	Reserved
Length	8-11	4	Length of the item referenced

END

END must be the last record for a module. An 'Entry Point' is used when an address other than the beginning of the module is to be used as the start point for its execution. This is used either because the program has non-executable data appearing before the start of the module (very common for older assembly programmers, as older versions of the assembler were much slower to assemble data stored in programs once instructions were specified), or because the module calls an external module first, such as a run-time library to initialize itself.

Field	Offset	Size	Bits	Description
PTV	0-2	3		X'034000' - Not-continued
				X'034100' - Continued on next record
	3	0-5	6	Reserved
Flags		6-7	2	Declarations regarding the presence or absence of an entry point
				00 - No entry point given; all other values in this record are invalid
				01 - Entry point specified by ESDID
				10 - Entry point specified by name
				11 - Reserved
AMODE	4	1		Addressing Mode value of entry point; the values are as specified in field 0 of the Behavior Attributes table in the ESD record.
	5-7	3		Reserved
Record Count	8-11	4		Number of GOFF records in this module (this is the number of "logical" records, i.e. not counting continuations)
ESDID	12-15	4		Value of ESDID if entry point is referenced by ESDID; binary zero if referenced by name
	16-19	4		Reserved
Offset	20-23	4		Address offset of module entry point; this cannot be specified for an external (ER) entry point
Name Length	24-25	2		Length of name, this must be zero if entry point was specified by ESDID.
Name	26-			The name of the external symbol used as the entry point for this module; is binary zeros if entry point was specified by ESDID; if this record is continued this is the initial 54 characters of the name. This is the only non-binary value in the record; it would be a text field representing the public name for the entry point
REM				Trailer extending to the end of the record; should be binary zeros to end of record for fixed-length records; omitted for variable-length

Continuation

If an entry-point name specified on a fixed-length END record is longer than 54 bytes or (if this record itself is also continued) is longer than an additional 77 bytes), the following continuation record is used.

Field	Offset	Size	Description
PTV	0-2	3	X'034200' - This continuation record is not-continued
			X'034300' - This continuation record is itself continued on the next record
Name	3-		The remaining part of the entry-point name, unless this record is continued, in which case it is the next 77 characters of the name.
REM			If this record is not continued, this is the trailing part of the record for fixed-length records and should be binary zeroes; not present for variable-length records

References

1. John R. Ehrman (March 1, 2001). "How the Linkage Editor Works: A Tutorial on Object/Load Modules, Link Editors, Loaders, and What They Do for (and to) You" (PDF). IBM Silicon Valley (Santa Teresa) Laboratory, San Jose. Retrieved September 8, 2019.^{[ permanent dead link ]}
2. OS/MVS Program Management: Advanced Facilities (PDF) (eighth ed.). Poughkeepsie, NY: IBM. September 2007. SA22-7644-07. Archived from the original (PDF) on October 19, 2021. Retrieved August 9, 2013.
3. IBM High Level Assembler for MVS & VM & VSE Release 2 Presentation Guide (PDF). December 1995. SG24-3910-01. Archived from the original (PDF) on 2016-01-23. Retrieved November 13, 2015.
4. High Level Assembler for z/OS & z/VM & z/VSE Programmer's Guide (PDF) (sixth ed.). San Jose, CA: IBM. July 2008. Appendix C. SC26-4941-05. Retrieved September 8, 2019.^{[ permanent dead link ]}
5. "RLD". www.ibm.com. IBM. 16 August 2013. Retrieved 10 July 2020.
6. "Lp64 | Ilp32". IBM .
7. "llvm/BinaryFormat/GOFF.h - GOFF definitions". LLVM.ORG. Retrieved August 16, 2024.