This article includes a list of references, related reading or external links, but its sources remain unclear because it lacks inline citations. Please improve this article by introducing more precise citations.(March 2015)
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 (a procedure in an object that is not known which procedure is invoked until the program runs, because a later definition of a procedure with the same name in a descendant object replaces the original procedure in the ancestor object).
The GOFF object file format was developed by IBM as a means to overcome these problems. 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.
Note that 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, 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 format is similar to the OS/360 Object File Format but adds additional information for use in building applications.
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 characters. 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 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.
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.
Module and Class names are case sensitive. A module named "exit" (as used by the C language may 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.
Eash 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 data) 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, which consist of a single letter, an underscore, and 1 to 16 characters. Class names beginning with B_ are reserved for the binder; class names beginning with C_ marked as loadable are reserved for programs created for use with IBM's Language Environment (LE). Classes beginning with C_ which are not marked as loadable, as well as classes beginning with X_, Y_ or Z_ are available for general use.
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 Directory 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.
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, 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.
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 format 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.
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.
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 specified in the External Name field.
02
LD - Label Definition. "Parent" ESDID must be non-zero, and be the value of an SD entry that defines this symbol within itself.
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.
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 remaming)
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)
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.
0
Trailer: Unused space if needed for fixed-size records; must be zero filled. Not needed in variable-length records.
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 name up to the size of this record if continued.
0
Trailing bytes if this is the last record for this name and the name is shorter than the record size; must be 0 filled.
Addressing mode associated with this external symbol
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
Indicaton 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
Executable (Code or Code and data)
010
Not Executable (Data only)
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
John R. Ehrman, How the Linkage Editor Works: A Tutorial on Object/Load Modules, Link Editors, Loaders, and What They Do for (and to) You, IBM Silicon Valley (Santa Teresa) Laboratory, San Jose, 1994, 2001 ftp://ftp.boulder.ibm.com/software/websphere/awdtools/hlasm/s8169a.pdf (Retrieved July 29, 2013)
