Program Object Specification

All attributes, specifications, and ODT (object definition table) formats for each non-bound program object in the MI Instruction Set are discussed. Charts illustrate the combinations of attributes and specifications. The detailed formats for the ODV (ODT directory vector) and the OES (ODT entry string) are also specified.

Instruction Operands

Each Non-Bound Program (NBP) instruction requires from zero to four operands. Each operand may consist of one or more fields that contain either a null operand specification, an immediate data value, or a reference to an ODT object. The size of the operand field depends on the version of the program template. If the version number is 0, the size of the operand field is 2 bytes. If the version number is 1, the size of the operand field is 3 bytes.

Null Operands

Certain instructions allow certain operands to be null. In general, a null operand means that some optional function of the instruction is not to be performed or that a default action is to be performed by the instruction. Note that a null operand is not the same thing as a null pointer value. A null operand is an operand that is specified in the instruction stream as being omitted. The use of a null operand is detectable when the program is being created. In contrast, a null pointer value represents the condition a pointer does not exist at this location. The CMPPTRT instruction can be used to test for a null pointer value. Null pointer values cannot be detected until run time.

Immediate Operands

The value of this type of operand is encoded in the instruction operand. Immediate operands may have the following values:

Signed binary-representing a binary value of negative 4,096 to positive 4,095.
Unsigned binary-representing a binary value of 0 to 8,191.
Byte string-representing a single byte value from hex 00 to hex FF.
Absolute instruction number-representing an instruction number in the range of 1 to 8,191.
Relative instruction number-representing a displacement of an instruction relative to the instruction in which the operand occurs. This operand value may identify an instruction displacement of negative 4,096 to positive 4,095.

ODT Object References

This type of operand contains a reference (possibly qualified) to an object in the ODT. Operands that are ODT object references may be simple operands or compound operands.

Simple Operands

The value encoded in the operand refers to a specific object defined in the ODT. Simple operands consist of a single 2-byte operand entry.

Compound Operands

A compound operand consists of a primary (2-byte) operand and a series of one to three secondary (2-byte) operands. The primary operand is an ODT reference to a base object while the secondary operands serve as qualifiers to the base object.

A compound operand may have the following uses:

Subscript references
An individual element of a data object array, a pointer array, or an instruction definition list may be referenced with a subscript compound operand. The operand consists of a primary reference to the array and a secondary operand to specify the index value to an element of the array.
Substring references
A portion of a character scalar data object may be referenced as an instruction operand through a substring compound operand. The operand consists of a primary operand to reference the base string object and secondary references to specify the value of an index (position) and a value for the length of the substring.

The length secondary operand field can specify whether to allow or not allow for a null substring reference (a length value of zero).
Explicit base references
An instruction operand may specify an explicit override for the base pointer for a based data object or a based addressing object. The operand consists of a primary operand reference to the based object and a secondary operand reference to the pointer on which to base the object for this operand. The override is in effect for the single operand. The displacement implicit in the ODT definition of the primary operand and the addressability contained in the explicit pointer are combined to provide an address for the operand.

The explicit base may be combined with either the subscript or the substring compound operands to provide a based subscript compound operand or a based substring compound operand.

General ODT Description

A program template is composed of a header followed by several components, including an instruction stream component and an object definition table (ODT) component. The ODT contains the views of all objects referred to in the instruction stream other than those objects that are immediate value operands in the instructions. The following objects are ODT definable:

Data object
- Scalar data object
- Pointer data object
Constant data object
Entry point
Branch point
Instruction definition list
Operand list
Exception description

The ODT entry consists of the ODV and the OES.

ODV

The ODV is a vector of 4-byte character string entries in a standard format. An ODV entry describes an object completely or partially. If the ODV entry does not completely describe the object, it must contain an offset into the OES where the object is described completely.

An ODV entry is required for each object described in the ODT. The index value for a particular object ODV entry is used as an operand for instructions that operate on the object. An ODT can contain 8,191 entries in template version 0 and 65,526 entries in template version 1. The first entry has an index value of 1.

The structure of the ODV is designed to allow a complete definition of commonly used objects. An object that cannot be completely described in an ODV entry must have an OES entry to complete its definition.

Each ODV entry generally consists of the following:

Type information
- The first 2 bytes of each ODV entry contain information identifying the type and general attributes of the object.
OES offset or attribute information
- The last 2 bytes of each ODV entry contain either detailed attribute information or an offset into the OES where the detailed attribute information is found. The OES contains a 4-byte OES length entry at the beginning of the OES component. This means that the minimum valid offset is 4 bytes.

Object references in the MI instructions consist of instruction operands that contain index values into the ODV.

OES

The OES consists of a series of variable-length entries that complete an object's description.

If an OES entry exists for an object, its offset value into the OES is specified in the ODV entry for that object.

Several ODV entries for different objects with identical definitions can share the same OES entry. OES entries do not exist for those objects that can be completely described in the ODV.

Each OES entry consists of the following:

OES header
- One byte indicating which OES appendages are present. A bit is included for each possible OES appendage. A binary 0 value for the bit means the appendage is not present. A binary 1 value for the bit means the appendage is present.
OES header extension
- One byte indicating which OES appendages are present. A bit is included for each possible OES appendage. A binary 0 value for the bit means the appendage is not present. A binary 1 value for the bit means the appendage is present. The presence of this header extension is indicated by a bit in the OES header. If the header extension is specified it follows immediately after the OES header.
OES appendages
- A series of variable-length fields each containing a specific collection of information about the object.

The following are examples of object attributes specified in an OES entry.

Object names
Length/number of elements
Explicit bases
Explicit positions
Initial values
OES header extension

When an OES entry is required to complete an object's description, its appendages must be in the same order as are the bits that indicated their presence in the OES header.

For example, assume the following OES header:

The name appendage must immediately follow the OES header, and the initial value appendage must immediately follow the name appendage.

The OES may consist of 0 to 16,776,191 bytes. Because the OES offset value may be a maximum of 65,535 bytes, a means is provided to address an OES offset beyond this maximum. A special object type value (binary 1111) in the ODV denotes an object description in which:

A 3-byte offset to the OES entry is specified.
The entire object description is specified in the OES entry (ODV, the OES header, and OES appendages).

See "References to OES Offsets Greater Than 64 K - 1" for a detailed description of this format.

ODT Entries in Detail

In this section, the detailed definitions for the various ODT entries are discussed by object type. Each object type description contains the following information about its respective objects:

Attribute combination charts–Summarize both the attributes of a given object and the valid combination of those attributes.
In the attribute combination charts, the following rules are used:
- A combination of attributes is allowed if the attributes lie on a single path that progresses from left to right through the diagram. For example:
  
  The attribute A can be used with B and C, B and D, B and E, or E only; but C cannot be used with D or E.
- Optional attributes are noted where a solid line bypasses one or more attributes.
ODV Format–Describes the various bit settings of the 4-byte ODV entry relative to the specific object type.
OES Format–Describes the various OES header bit settings relative to the specific object type.
Notes–Describe any unique characteristics concerning the specifications of the object.

Note: Reserved bits are those bits not being used currently and should always be set to binary 0.

Combinations of attributes not defined in these specifications cause a create program exception-invalid ODT exception to be signaled when the program is created.

Data Object

Data objects provide operational and, possibly, representational characteristics to data in a space. Scalar data objects and pointer data objects are the two basic categories of data contained in the space.

Scalar data objects provide operational and representational characteristics for numeric and character data contained in a space.

Pointer data objects provide operational characteristics for pointer data contained in a space.

The following chart shows the general characteristics of data objects.

Scalar Data Object

Attribute Combinations

ODV Format

Bits

Meaning

0-3

Object type

0000 =: Scalar data object (Group 1)
1001 =: Scalar data object (Group 2)

4

OES present

0 =

OES is not present.

1 =

OES is present because one or more of the following is true:

Object is named and external.
Object has initial value (not system default).
Object has based or defined addressability.
Object has direct addressability with explicit position.
Object is an array.

5-7

Addressability type

000 =: Direct static
001 =: Direct automatic
010 =: Based
011 =: Defined
100 =: Parameter
101 =: Based on PCO (process communication object) space pointer

All others reserved

8

Optimization of value

0 =: Normal value (can be optimized across several instructions)
1 =: Abnormal value (cannot be optimized for more than a single reference because the value may be modified in a manner not detectable when the program is created).

9-11

Boundary

000 =: None
001 =: Multiple of 2
010 =: Multiple of 4
011 =: Multiple of 8
100 =: Multiple of 16

101-111 = Reserved

Boundary is assumed to be specified for indirectly addressed program objects. A higher boundary alignment can improve performance when the program object is referenced.

12

System default initial value

0 =

Do not use the system default initial value.

1 =

Use the system default initial value.

Numeric zero value for binary, packed, zoned, or floating-point
Blank character value (hex 40) for character strings

13-15

Scalar type (Group 1)

000 =: Signed binary
001 =: Floating-point
010 =: Zoned decimal
011 =: Packed decimal
100 =: Character string
101-111 =: Reserved

13-15

Scalar type (Group 2)

000 =: Unsigned binary

Note: The Group 2 scalar data type bits correspond to the Group 1 scalar data type in that corresponding types have the same values ( e.g. Signed binary and Unsigned binary = 0000 ).

001-111 = Reserved

16-31

OES offset or scalar length

If bit 4 of the ODV is 1 (OES is present), then bits 16-31 specify the offset to the OES entry for this object.
If bit 4 of the ODV is 0 (OES not present), bits 16-31 represent the scalar length of the object as follows:
If signed or unsigned binary, then:
Bits

Meaning

16-31
Byte Length
- Hex 0002 = 2
- Hex 0004 = 4
- All others reserved
If floating-point, then:
Bits 16-31

Precision in bytes
Hex 0004 = 4
Hex 0008 = 8
All others reserved

If zoned or packed decimal, then:
Bits

Meaning

16-23

Digits (D) to the right of assumed decimal point, where 0 <= D <= T

24-31

Total digits (T) in field, where 1 <= T <= 31

If character string scalar, then:
Bits

Meaning

Bits 16-31

String length(L), where 1 <= L <= 32,767
Note: Strings whose length is greater than 32K are specified using the OES Scalar Length appendage to indicate that Extender Scalar length is the format in the OES Header Extension.

OES Format

OES Header

Bits

Meaning

0

Name and external

0 =: Object is not named and is not externally accessible.
1 =: Object is named and is externally accessible.

1

Scalar length present

1 =: Length is present (required).

2

Array information present

0 =: Array information is not present.
1 =: Array information is present.

3

Base present

0 =: Base is not present.
1 =: Base is present.

4

Position present

0 =: Position is not present (required if boundary is specified).
1 =: Position is present.

5

Initial value present in OES

0 =: Initial value is not present.
1 =: Initial value is present in OES.

6

Replications present in OES

0 =: No replications in initial value.
1 =: Replications in initial value (bit 5 = 1).

7

OES Header Extension present

0 =: OES Header Extension is not present.
1 =: OES Header Extension is present in OES.

OES Header Extension Appendage

Bits

Meaning

0

Reserved

1

Extended Scalar Length

0 =: Extended scalar length is not present.
1 =: Extended scalar length is present in Scalar Length appendage.

2

Array bounds information present

0 =: Array bounds information is not present.
1 =: Array bounds information is appended to Array appendage.
Note: The Array Information Present bit must be set in the OES header in order to specify this bit.

3-7

Reserved

Name Appendage

Bytes: Meaning
0-1: Length (L) of name, where 1 <= L <= 32
2-L: L characters of symbolic name
Note: Names of external data objects must be unique.

Scalar Length Appendage

If Extended Length is not specified in the OES header extension then,

Bytes 0-1

Scalar length

If signed or unsigned binary, then:

Bits

Meaning

0-15

Byte Length

Hex 0002 = 2
Hex 0004 = 4

All others reserved

If zoned or packed decimal, then:

Byte: Meaning
0: Digits (D) to the right of assumed decimal point, where 0 <= D <= T
1: Total digits (T) in field, where 1 <= T <= 31

If floating-point, then:

Byte: Meaning
Bytes 0-1:: Precision
Hex 0004 = 4
Hex 0008 = 8
All others reserved

If character string scalar, then:

Byte: Meaning
Bytes 0-1:: String length (L), 1 <= L <= 32,767

If Extended Length is specified in the OES header extension then,

Bytes: Meaning
0-3: Length (L) of long character string, where 1 <= L <= 16,776,191, except for external strings, where 1 <= L <= 65,535.
On prior versions of the machine, longer external strings could be defined, but the apparent length when used (via data pointer reference) was L modulo 65,536.

Array Appendage

Bytes: Meaning
0-3: Number (N) of elements in the array, where 1 <= N <= 16,776,191
4-5: Array element offset
If the array element offset attribute is specified (bytes 4-5 are nonzero), this field specifies the offset between initial bytes of the elements of a defined on array.
6-9: Lower bound of array (LB),
10-13: Upper bound of array (UB),
The lower bound must be less than or equal to the upper bound. The number of elements in the array is equal to the (UB+1-LB) which must be less than or equal to 16,776,191.

Note: The Lower and Upper bound information is only present if the Array Bounds bit is set in the OES extended header. Arrays of scalar character data objects are only allowed for character data elements whose length is less than or equal to 32,767 characters.

Base Appendage

Bytes 0-1:

ODT reference for:

Position Appendage

Bytes 0-3

Position value for:

Direct if not defaulting to next available byte or if no boundary defined
Based if not 1
Defined if not 1

Note: Position value is in terms of bytes with the first byte in position 1.

Initial Value Appendage

Bytes 0-L:: Initial value in format and length as determined by scalar type

In the initial value appendage, a noncharacter string scalar must have an initial value of the proper size and format (for example, 2-byte binary value for a 2-byte binary scalar).

For arrays and character strings, if the replication bit in the OES is binary 1, the initial value portion must consist of one or more three field components of the following form:

2 bytes:: Number of replications of Associated Value
2 bytes:: Length (L) of Associated Value
L bytes:: Associated Value

Note: When the above form is used for specifying the initial values for arrays, the number in the replications field represents the number of array elements to be given the Associated Value.

The entire object may be initialized contiguously ignoring array element boundaries and byte by byte using the initial value form below.

If the replication bit for an array or a character string whose length is greater than or equal to 32K bytes is binary 0, the initial value appendage must have the following form:

4 bytes:: Length of initial value (less than or equal to the total number of bytes in the array or long character string)
L bytes:: The initial value of proper size and format to specify the initial values for each element of the array that is to be initialized

If the replication bit for a character string whose length is less than 32K bytes is binary 0, the initial value appendage must be a byte string with a length equal to the object length.

Note:

Scalar data objects with the external attribute must be mapped (direct or defined on direct) onto the static space. The names must be unique within the program template.
When used for address resolution, the name of an external data object is implicitly padded to 32 bytes by extending on the right with blank characters (hex 40).
See "Data Object Notes" for general notes concerning data objects.

Pointer Data Objects

Attribute Combinations

ODV Format

Bits

Meaning

0-3

Object type

0001 =: Pointer data object

4

OES present

0 =: OES is not present.
1 =: OES is present because the object has initial value, base, position, or the object is an array.

5-7

Addressability type

000 =: Direct static
001 =: Direct automatic
010 =: Based
011 =: Defined
100 =: Parameter
101 =: Based on PCO (process communication object) space pointer

All others reserved

8

Optimization of value

0 =: Normal value (can be optimized across several instructions)
1 =: Abnormal value (cannot be optimized for more than a single reference because the value may be modified in a manner not detectable

9-11

Reserved

12-15

Pointer type (ignored unless initial value)

0001 =: Space pointer
0010 =: System pointer
0011 =: Data pointer
0100 =: Instruction pointer

All others reserved. Other pointer types cannot have an initial value.

16-31

OES offset

If bit 4 of the ODV contains a binary 0, no OES is present, and bits 16-31 contain a value of binary 0.
If bit 4 of the ODV contains a binary 1, then an OES header is present in the OES at the offset specified in bits 16-31.

OES Format

OES Header

Bits

Meaning

0

Reserved

1

Initial value appendage modifier

0 =: Instruction pointer initial value has the basic format.
1 =: Instruction pointer initial value has the extended format.

2

Array information present

0 =: Array information is not present.
1 =: Array information is present.

3

Base Present

0 =: Base is not present.
1 =: Base is present.

4

Position present

0 =: Position is not present.
1 =: Position is present.

5

Initial value present

0 =: Initial value not present.
1 =: Initial value is present.

6

Reserved

7

OES Header Extension present

0 =: OES Header Extension is not present.
1 =: OES Header Extension is present in OES.

OES Header Extension Appendage

Bits

Meaning

0-1

Reserved

2

Array bounds information present

0 =: Array bounds information is not present.
1 =: Array bounds information is appended to Array appendage.
Note: The Array Information Present bit must be set in the OES header in order to specify this bit.

3

Optimization Appendage present

0 =: Optimization Appendage is not present
1 =: Optimization Appendage is present

4-7

Reserved

Array Appendage

Bytes: Meaning
0-3: Number (N) of elements in the array, where 1 <= N <= 1,000,000
4-5: Array element offset
If the array element offset attribute is specified (bytes 4-5 are nonzero), this field specifies the offset between initial bytes of the pointers of a defined array. Value must be a multiple of 16.
6-9: Lower bound of array (LB), where LB is a signed 4-byte integer, minimum value is -2,147,483,648.
10-13: Upper bound of array (UB), where UB is a signed 4-byte integer, maximum value is 2,147,483,647.
The lower bound must be less than or equal to the upper bound. The number of elements in the array is equal to the (UB+1-LB).

Note: The Lower and Upper bound information is present only when the Array Bounds bit is set in the OES Header Extension.

Base Appendage

Bytes 0-1:

ODT reference for:

Pointer data object or space pointer machine object, if based.
Data object or pointer object if defined. Resulting location must be a multiple of 16.

Position Appendage

Bytes 0-3:

Position value for:

Direct if not defaulting to next available byte (must be a multiple of 16)
Based if not 1
Defined if not 1

Initial Value Appendage

If ODV bits 12-15 indicate instruction pointer:

If the initial value appendage modifier equals 0, the basic format is:

Bytes 0-1:

Instruction stream reference; indirect or direct reference to an instruction number

If bit 0 is 0, then bits 1-15 specify an indirect reference that contains the ODV number of a branch point that specifies the instruction number to be referenced.
If bit 0 is 1, then bits 1-15 specify a direct reference that contains the instruction number to be referenced.

If the initial value appendage modifier equals 1, the basic format is:

Bytes 0-2:

Instruction stream reference; indirect or direct reference to an instruction number

If bit 0 is 0, then bits 8-23 specify an indirect reference that contains the ODV number of a branch point that specifies the instruction number to be referenced.
If bit 0 is 1, then bits 8-23 specify a direct reference that contains the instruction number to be referenced.

Bits 1-7 are reserved (binary 0).

If ODV bits 12-15 indicate data pointer:

Bytes 0-1:

Number of names in name list. One or two names may be specified as the initial value.

If one name is specified, it must be in the name specification of the data object in the following format:

Offset
Dec	Hex	Field Name	Data Type and Length
0	0	Number of names (value of 1)	Bin(2)
2	2	Scalar data object name length (N)	Bin(2)
4	4	Scalar data object name string, where 1 <= N <= 32	Char(N)
*	*	--- End ---

If two names are specified, the name of a program to be searched and the name of the external data object are specified as follows:

Offset
Dec	Hex	Field Name	Data Type and Length
0	0	Number of names (value of 2)	Bin(2)
2	2	Program type (hex 02)	Char(1)
3	3	Program subtype	Char(1)
4	4	Program name length (M)	Bin(2)
6	6	Program name string, where 1 <= M <= 30	Char(M)
*	*	Scalar data object name length (P)	Bin(2)
*	*	Scalar data object name string where 1 <= P <= 32	Char(P)
*	*	--- End ---

If ODV bits 12-15 indicate space pointer:

Bytes 0-1:: ODT number of a data object or pointer object that is direct or defined on direct.

If ODV bits 12-15 indicate system pointer, one or two names may be specified as the initial value.

If one name is specified, it must be the name specification of the object in the following format:

Offset
Dec	Hex	Field Name	Data Type and Length
0	0	Number of names (value of 1)	Bin(2)
2	2	Object type code	Char(1)
3	3	Object subtype code	Char(1)
4	4	Minimum authority code	Char(2)
6	6	Object name length (N)	Bin(2)
8	8	Object name string, where 1 <= N <= 30	Char(N)
*	*	--- End ---

If two names are specified, the entry must be a context name and an object name in the following format:

Offset
Dec	Hex	Field Name	Data Type and Length
0	0	Number of names (value of 2)	Bin(2)
2	2	Context type code (value of hex 04)	Char(1)
3	3	Context subtype code	Char(1)
4	4	Context name length (M)	Bin(2)
6	6	Context name string, where 1 <= M <= 30	Char(M)
*	*	Object type code	Char(1)
*	*	Object subtype code	Char(1)
*	*	Minimum authority code	Char(2)
*	*	Object name length (P)	Bin(2)
*	*	Object name string, where 1 <= P <= 30	Char(P)
*	*	--- End ---

Note:

The object type codes that may be specified for system pointer initial values are as follows:
Code (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

23

Transaction control structure

All other codes are reserved and, if specified, cause an exception to be signaled.
The minimum authority codes that may be specified for system pointer initial values are as follows:
Bit

Meaning

0

Object control

1

Object management

2

Authorized pointer

3

Space authority

4

Retrieve

5

Insert

6

Delete

7

Update

8

Ownership

9

Excluded

10

Authority list management

11

Execute

12

Alter

13

Reference

14-15

Reserved (binary 0)

A value of binary 1 indicates that the object must have the specified authority in order for resolution to be performed. Zero or more authority bits may be specified, and if any are specified, all must be satisfied.

Reserved bits must have a value of binary 0.

A pointer with based addressability need not have a base specified. If a base is specified, the pointer can, in turn, be based on another pointer. An exception is signaled if the final pointer in the chain is not direct, is not defined on a direct data object, is not a parameter, or is not defined on a parameter. An exception is signaled if a base pointer in the chain is based on a pointer that was previously specified in the chain of based pointers.
A static space pointer may not be initialized to an automatic scalar data or pointer object.
The last initialized pointer data object appearing in the ODT for a given storage location overlays all previous pointer object initial values for that location.
A pointer data object defining an array may not be initialized. See "Data Object Notes".
When the initial value specified for a system pointer or a data pointer is to be used for address resolution, the name string entry is implicitly extended to the standard length by padding with blank characters (hex 40). The standard length for system object names is 30 bytes and for external scalar data objects is 32 bytes.
See "Data Object Notes" for general notes concerning data objects.

Data Object Notes

The following notes apply to all declarations of data objects, scalars, and pointers. The term data object applies to either scalar data objects or pointer data objects unless explicitly qualified.

Note:

Any specification of position uses position 1 as the first position in storage. A position value of 0 is invalid.
Data objects that are defined on other data objects must follow (not necessarily immediately) their associated bases in the ODT. If any data objects in a chain of defined-on objects have an initial value, none of the objects in the chain can have based or parameter addressability, and the first object in the chain must be direct on the static or automatic space. An initial value associated with a defined data object overlays all initial values associated with data objects that preceded it in the chain. The portion of a scalar data object initial value that overlays any part of an initialized pointer data object is ignored.
If more than one data object initializes the same byte (or bytes) in a space, the value associated with the data object appearing last in the ODT overlays the others.
For data objects with the direct mapping type but no explicit position, provides default position (position in the static or automatic allocation) ODT information. ODT entries for defaulting direct objects must appear in the order desired. Declarations for other program objects can be interleaved with these defaulting direct data and pointer objects.
Two examples follow:

These ODT entries

Would be treated as these:

A Char(2) Direct Static

A Char(2) Direct Static Pos(1)

B Pkd(3,3) Direct Static

B Pkd(3,3) Direct Static Pos(3)

D Pointer Direct Static

D Pointer Direct Static Pos(17).

These ODT entries

Would be treated as these:

A Char(4) Direct Static

A Char(4) Direct Static Pos(1)

B Char(4) Direct Static Pos(20)

B Char(4) Direct Static Pos(20)

C Char(4) Direct Static

C Char(4) Direct Static Pos(24)

D Char(4) Direct Static Pos(10)

D Char(4) Direct Static Pos(10)

E Char(2) Defined B

E Char(2) Direct Static Pos(20)

F Char(3) Direct Static

F Char(3) Direct Static Pos(28).

The default value for the position depends on whether the boundary attribute is specified. Pointer objects always have a default boundary attribute that is a multiple of 16.

A boundary specification for a direct data object causes the data object to be located at the next available position having an offset value that is a multiple of the boundary specified. If boundary is specified, a value may not be specified for the position attribute. The boundary specification for a direct pointer object is always a multiple of 16. A position specified for a direct pointer object must be a multiple of 16.

If neither position nor boundary is specified for a direct data object, the object is located at the next available position without regard to boundary alignment.

The size for the static and automatic spaces can also be defaulted if the size of static (automatic) storage entry in the program template is 0. The value used is such that the space is large enough to contain all data objects with defaulted and explicit direct mapping. An exception is signaled if a size that is insufficient to contain defaulted and direct mapped data objects is specified.

To summarize, the rules related to positioning data objects and setting of the size through defaulted directed data objects are:

A defined-on data object may extend beyond the end of the data object it is defined on. It may not, however, extend beyond the total allocated space to which it maps.
Explicit positioning of a data object may be intermixed with implicit positioning. That is, for any ODT, a specification of the position for a data object does not preclude a succeeding data object requiring a default position.
A defaulted scalar data object is assigned to the highest assigned position for a direct data object plus 1. A defaulted pointer data object is assigned to the next available 16-byte aligned position beyond the highest assigned position. It is possible, through explicit positioning, to create a gap in a space. This gap is not filled in through default positioning of a following data object or pointer object. The defaulted object follows the explicitly positioned data object.

Entry Point

Attribute Combinations

ODV Format

Bits

Meaning

0-3

Object type

0010 =: Entry point

4

OES present

0 =: OES is not present
1 =: OES is present because of entry point parameters or the instruction stream breakpoint

5-14

Reserved (binary 0)

15

Scope

0 =: Internal
1 =: External

16-31

OES offset or entry point value OES offset if OES present (bit 4=1). Entry point value equals the instruction number if no entry point parameters are listed

OES Format

OES Header

Bits

Meaning

0

Instruction stream breakpoint

0 =: Appendage not present
1 =: Instruction stream breakpoint appendage present

1-2

Reserved (binary 0)

3

Parameter information present

0 =: Parameter information not present
1 =: Parameter information is present

4-6

Reserved (binary 0)

7

Initial value present

1 =: Initial value is required

Instruction Stream Breakpoint Appendage

Bytes 0-1: Instruction number for instruction stream breakpoint identifies first instruction of half of program that is not executed in the normal path

Parameter Appendage

Bytes 0-1: ODT reference for operand list describing entry point parameters

Initial Value Appendage

Bytes 0-1: Instruction number for entry point

Notes on Entry Points

Note:

Only one external entry point may be defined.
If no external entry point is declared, the first instruction is assumed to be the external entry point with no parameters.
If external parameters are declared in a program, an external entry point must be declared. If one is not declared, an ODT relational error exception is signaled when the program is created.
An instruction stream breakpoint can only be defined with an external entry point. The instruction number specified must be greater than that of the external entry point.
An internal entry point and an external entry point cannot reference the same instruction.
More than one internal entry point can reference the same instruction.
An internal entry point can only reference an internal parameter list; likewise, an external entry point can only reference an external parameter list.

Branch Point

Attribute Combinations

ODV Format

Bits

Meaning

0-3

Object type

0011 =: Branch point

4

OES present

0 =: OES is never present

5-15

Reserved (binary 0)

16-31

Value

Instruction number (N) of branch point, where 1 <= N <= 65,535.

OES Format

No OES is needed for branch points.

Instruction Definition List

Attribute Combinations

ODV Format

Bits

Meaning

0-3

Object type

0100 =: Instruction definition list

4

OES present

1 =: OES is present (always present to contain the list information)

5-15

Reserved (binary 0)

16-31

OES offset

OES Format

OES Header

Bits

Meaning

0

Reserved (binary 0)

1

Initial value appendage modifier

0 =: Initial value instruction references have the basic format.
1 =: Initial value instruction references have the extended format.

2-6

Reserved (binary 0)

7

Initial value present

1 =: Initial value is required

Initial Value Appendage

Bytes: Meaning
0-1: Number (N) of list elements, where 1 <= N <= 255

If the initial value appendage modifier equals 0, the basic format:

2-3: Instruction reference element 1

.
.
.

X-X+1: Instruction reference element N

If the initial value appendage modifier equals 1, the basic format:

2-4: Instruction reference element 1

.
.
.

X-X+1: Instruction reference element N

Note: An instruction reference element has the following formats:

If the initial value appendage modifier equals 0, the basic format is:

Bytes 0-1:

Instruction stream reference; indirect or direct reference to an instruction number

If bit 0 is 0, then bits 1-15 specify an indirect reference that contains the ODV number of a branch point that specifies the instruction number to be referenced.
If bit 0 is 1, then bits 1-15 specify a direct reference that contains the instruction number to be referenced.

If the initial value appendage modifier equals 1, the basic format is:

Bytes 0-2:

Instruction stream reference; indirect or direct reference to an instruction number

If bit 0 is 0, then bits 8-23 specify an indirect reference that contains the ODV number of a branch point that specifies the instruction number to be referenced.
If bit 0 is 1, then bits 8-23 specify a direct reference that contains the instruction number to be referenced.

Bits 1-7 are reserved (binary 0).

Operand List

Attribute Combinations

ODV Format

Bits

Meaning

0-3

Object type

0101 =: Operand list

4

OES present

1 =: OES is always present because it contains the operand list entries.

5

Argument list

0 =: Not used as argument list
1 =: Argument list (bits 6-7 must be binary 0)

6-7

Parameter list (if not binary 0, bit 5 must be binary 0)

00 =: Not parameter list
01 =: Reserved
10 =: Internal parameter list
11 =: External parameter list

8

Length attribute

0 =: Variable-length
1 =: Fixed-length

9-15

Reserved (binary 0)

16-31

OES offset

OES offset = OES is always present

OES Format

OES Header

Bits

Meaning

0-6

Reserved (binary 0)

7

Initial value present

1 =: Initial value is required

Initial Value Appendage

Bytes

Meaning

0-3

Number (N) of list elements, where 1 <= N <= 255

For fixed-length lists (argument or parameter)
Bytes

Meaning

0-1

Number (N) of elements, where 1 <= N <= 255

2-3

Reserved (binary 0)
For variable-length lists
Bytes

Meaning

0-1

Maximum number (N) of elements that the list can contain, where 1 <= N <= 255

2-3

For argument lists, the initial number (M) of elements to be passed on a Call External or Transfer Control instruction, where 0 <= M <= N
For parameter lists, the minimum number (M) of elements to be received on entry, where 0 <= M <= N

4-5

ODT reference 1

.
.
.

X-X+1: ODT reference N
N elements are required.

Note:

Operand list entries must be either scalar data objects or pointer data objects.
An operand list cannot be both an argument list and a parameter list.
Argument lists referenced on Call Internal instructions must be fixed length.
Parameter lists referenced by internal entry points must be fixed-length internal parameter lists.
Internal parameter lists and argument lists used on internal calls can only be fixed-length.
A program may have only one external parameter list.
The same object cannot appear in more than one parameter list (internal or external) in a program template.
All the ODT entries for the elements of an operand list must appear before the ODT entry for that operand list.
Variable-length lists must define ODT references for every entry in the list.
Objects referenced in a parameter list must have the parameter attribute.

Constant Data Object

Attribute Combination

ODV Format

Bits

Meaning

0-3

Object type

0110 =: Constant data object

4

OES present

0 =: OES is not present (value in bits 8-15).
1 =: OES is present because the value does not fit in bits 8-15, and the system default initial value is not used.

5

0 =

No system default initial value

1 =

Use system default initial value

Numeric 0 for binary, packed, zoned, or floating-point
Blank character value (hex 40) for character
Hexadecimal zeros (hex 00) for bit and first two bytes of varying length character strings (length field)

6

Value in bits 8-15

0 =: Value not in 8-15 in OES, or system default value is to be used.
1 =: Value to be propogated in each byte is in bits 8-15, and scalar type is character.

7

Reserved (binary 0)

8-15

Value specification

If bit 6 is 1, then this byte contains a value to be given to each byte in the constant.
If bit 6 is 0, then:
Bits

Meaning

8-10

Reserved (binary 0)

11-15

Scalar type
00000 =

Binary

00001 =

Floating-point

00010 =

Zoned decimal

00011 =

Packed decimal

00100 =

Character

00101-01001 =

Reserved

01010 =

Unsigned binary

01011-01111 =

Reserved

16-31

OES offset or scalar length

If bit 4 of the ODV is 1 (OES is present), then bits 16-31 represent the offset to the OES entry for this object.
If bit 4 of the ODV is 0 (OES is not present), bits 16-31 represent the scalar length of the object.
If signed or unsigned binary, then:
Bits

Meaning

16-31
Byte Length
- Hex 0002 = 2
- Hex 0004 = 4
- All others reserved
If floating-point, then:

Bits 16-31:

Precision
Hex 0004 = 4
Hex 0008 = 8
All others reserved

If zoned or packed decimal, then:

Bits

Meaning

16-23

Digits (D) to the right of assumed decimal point, where 0 <= D <=T

24-31

Total digits (T) in field, where 1 <= T <= 31

If character string scalar, then:

Bits

Meaning

Bits 16-31

String length(L), where 1 <= L <= 32,767

OES Format

OES Header

Bits

Meaning

0

Reserved (binary 0)

1

Length information present

1 =: Scalar length information (required if there is an OES)

2-5

Reserved (binary 0)

6

Value present

1 =: Value is present (required if there is an OES)

7

Replications present in OES

0 =: No replications in initial value
1 =: Replications in initial value (bit 6 = 1)

Length Information Appendage

Bytes

Meaning

0-1

Scalar length

If signed or unsigned binary, then:
Bits

Meaning

0-15
Byte Length
- Hex 0002 = 2
- Hex 0004 = 4
- All others reserved
If floating-point, then:
Bytes 0-1:

Precision
Hex 0004 = 4
Hex 0008 = 8
All others reserved
If zoned or packed decimal, then:
Bytes

Meaning

0

Digits (D) to the right of assumed decimal point, where 0 <= D <= T

1

Total digits (T) in field, where 1 <= T <= 31
If character string scalar, then:
Bytes 0-1:

String length (L) where 1 <= L <= 32,767

Value Appendage

Bytes 0-L:

Value in format and length as determined by constant data object scalar type.

For noncharacter scalars, a value of the proper size and format is required; for example, a 2-byte binary value is required for a 2-byte binary data object.
For character strings, if the replication attribute specified in the OES is binary 1, the value must consist of components of the following form:
2 bytes:

Number of replications of associated value

2 bytes:

Length (L) of associated value

L bytes:

Associated value

The total number of bytes specified through all replications must equal the length of the string (1 to 32,767).

If the replication attribute is binary 0, the value for a character constant view is a byte string of length equal to the object length.

Exception Descriptions

Attribute Combinations

ODV Format

Bits

Meaning

0-3

Object type

0111 =: Exception description

4

OES present

1 =: OES present (required for exception description)

5

Return exception data

0 =: Exception data is returned
1 =: Exception data is not returned

6-7

Reserved (binary 0)

8-9

Exception handler type

00 =: External entry point
01 =: Internal entry point
10 =: Internal branch point
11 =: Reserved

10-12

Exception handling action

000 =: Do not handle–ignore occurrence of exception and continue processing.
001 =: Do not handle–continue search for another exception description to handle the exception.
010 =: Do not handle–continue search for an exception description by resignaling the exception to the immediately previous invocation.
011 =: Reserved.
100 =: Defer handling–save exception data for later exception handling.
101 =: Pass control to the specified exception handler.

110-111 = Reserved

13-15

Reserved (binary 0)

16-31

OES offset (required)

OES Format

Bits

Meaning

0

Target

1 =: Present (always required for exception description)

1

Target appendage modifier

0 =: Target appendage for a branch point exception handler has the basic format.
1 =: Target appendage for a branch point exception handler has the extended format.

2-4

Reserved (binary 0)

5

Compare value

0 =: Compare value not present
1 =: Compare value present

6

User data

0 =: User data not present
1 =: User data present

7

Exception identifications

1 =: List of exception identifications (always present)

Target Appendage

For external and internal entry point exception handlers the target appendage modifier must be 0. The appendage has the following form:

Bytes 0-1:

ODT reference to

Pointer data object if the exception handler is an external entry point. This pointer data object must be either in the automatic or static storage of this program and must be directly referenced.
Internal entry point if the exception handler is an internal entry point.
Branch point if the exception handler is an internal branch point.

For branch point exception handlers the target appendage has the following form:

If the initial value appendage modifier equals 0, the basic format is:

Bytes 0-1:

Instruction stream reference; indirect or direct reference to an instruction number.

If bit 0 is 0, then bits 1-15 specify an indirect reference that contains the ODV number of a branch point that specifies the instruction number to be referenced.
If bit 0 is 1, then bits 1-15 specify a direct reference that contains the instruction number to be referenced.

If the initial value appendage modifier equals 1, the basic format is:

Bytes 0-2:

Instruction stream reference; indirect or direct reference to an instruction number.

If bit 0 is 0, then bits 8-23 specify an indirect reference that contains the ODV number of a branch point that specifies the instruction number to be referenced.
If bit 0 is 1, then bits 8-23 specify a direct reference that contains the instruction number to be referenced.

Bits 1-7 are reserved (binary 0).

User Data Appendage

Bytes 0-1

ODT reference to either

Pointer data object
Scalar data object

This data object must be in either the automatic or the static storage of this program and must be directly referenced.

Compare Value Appendage

Bytes: Meaning
0-1: Compare value length (maximum value of 32)
2-N: Compare value

Exception Number Appendage

Bytes: Meaning
0-1: Number (N) of exception numbers
2-(2n + 1): N 2-byte exception numbers

Note:

A pointer or scalar data object identified by the exception description (external exception handler or user data) must appear before the ODT entry for the exception description.
The exception descriptions are searched in the same order as they appear in the ODT when an exception has been signaled. Because of this, the first exception description that meets the conditions of the exception directs subsequent execution.

References to OES Offsets Greater Than 64 K - 1

ODV Format (References to OES Offset Greater Than 64 K - 1)

Bits

Meaning

0-3

Object type

1111 =: References to OES greater than 64 K - 1 (65,535)

4-7

Reserved (binary 0)

8-31

OES offset (3 bytes)

OES Format (Reference to OES Offset Greater Than 64 K - 1)

OES Header

Bytes: Meaning
0-1: First 2 bytes of standard ODV entry for this object
2: OES header for this object
3-N: OES appendages for this object

Pointer Machine Object

Attribute Combinations

ODV Format

Bits

Meaning

0-3

Object type

1000 =: Pointer machine object

4

OES present

0 =: OES is not present.
1 =: OES is present because an initial value, or optimization priority is specified.

5-11

Reserved (binary 0)

12-15

Pointer type(required)

0001 =: Space pointer

16-31

OES offset

If bit 4 of the ODV is 1 (OES is present), then bits 16-31 represent the offset to the OES entry for this object.
If bit 4 of the ODV is 0 (OES is not present), bits 16-31 contain a value of binary 0.

OES Format

OES Header

Bits

Meaning

0-4

Reserved (binary 0)

5

Initial value present

0 =: Initial value is not present
1 =: Initial value is present

6

Optimization priority value present

0 =: Priority value is not present
1 =: Priority value is present

7

Reserved (binary 0)

Initial Value Appendage

If ODV bits 12-15 indicate space pointer:

Bytes 0-1:: ODT number of a data object or pointer object that is direct or defined on direct.

Optimization Priority Appendage

Bytes

Meaning

0

Optimization priority value.

Hex FF =: Highest priority
.
.
.
Hex 00 =: Lowest priority

1-3

Reserved (binary 0)

This attribute should be used with caution. The beneficial effects of the normal machine optimizations can potentially be negated through incorrect prioritization of pointers relative to their influence on a program's performance.

Normally, optimizations are performed on pointers according to a priority established by a machine analysis of pointer usage within the program. The optimization priority attribute allows a space pointer machine object to be given a priority attribute which overrides the normal prioritization of space pointer machine objects performed by the machine when programs are created. Through this facility, space pointer machine objects can be specified as being of high optimization priority even though the analysis performed by the machine would determine the space pointer machine object to be of low usage within the program. Specifying a priority value indicates that the pointer is of higher priority than those with a lower value or those for which no value is specified. A particular priority value can be specified for multiple pointers to indicate that they are of equal priority relative to each other.

The number of space pointer machine objects for which special optimizations can be done is quite low, normally 2 or 3 (maximum of 12) depending on the particular program. The number of space pointer machine objects that can be specified in the program is limited by the amount of storage available for them in the internal work space associated with the program.

Space pointer machine objects are allowed in the ODV component of the program template only as an optimization option. This is because of the additional processing overhead necessary to provide support for them during program creation.

If no priority attribute is specified, the normal prioritization of space pointer data objects and space pointer machine objects controls the optimizations performed on them. When the priority attribute is specified, the effect it may have on the optimizations being performed is dependent upon the particular implementation of the machine. A beneficial effect may only be realized for some of the pointers carrying the attribute due to constraints on the optimizations which can be performed for a particular machine.

Abnormal modification of space pointer machine objects is not supported. That is, the abnormal attribute supported for space pointer data objects is not allowed for space pointer machine objects. Cases of abnormal pointer modification (those which can violate the addressability fetching optimizations performed by Create Program) can not be accomplished through use of a space pointer machine object. Such cases must be provided for through usage of a space pointer data object which has been defined with the abnormal attribute.

The particular area of exposure for usage of space pointer machine objects is the case of modification of the pointer value during the execution of an internal exception handler. In this case, resuming execution of the program after the exception handler returns may continue using the prior rather than the newly modified value of the pointer. Other abnormal modifications which apply to usage of space pointer data objects do not apply to space pointer machine objects. This is because defined on views of and external program modification of space pointer machine objects is not supported.

Operands and ODR Object References

Instruction Operands

Null Operands

Immediate Operands

The value of this type of operand is encoded in the instruction operand. Immediate operands may have the following values:

Signed binary-representing a binary value of negative 4,096 to positive 4,095.
Unsigned binary-representing a binary value of 0 to 8,191.
Byte string-representing a single byte value from hex 00 to hex FF.
Absolute instruction number-representing an instruction number in the range of 1 to 8,191.
Relative instruction number-representing a displacement of an instruction relative to the instruction in which the operand occurs. This operand value may identify an instruction displacement of negative 4,096 to positive 4,095.

ODT Object References

This type of operand contains a reference (possibly qualified) to an object in the ODT. Operands that are ODT object references may be simple operands or compound operands.

Simple Operands

The value encoded in the operand refers to a specific object defined in the ODT. Simple operands consist of a single 2-byte operand entry.

Compound Operands

A compound operand may have the following uses:

Subscript references
An individual element of a data object array, a pointer array, or an instruction definition list may be referenced with a subscript compound operand. The operand consists of a primary reference to the array and a secondary operand to specify the index value to an element of the array.
Substring references
A portion of a character scalar data object may be referenced as an instruction operand through a substring compound operand. The operand consists of a primary operand to reference the base string object and secondary references to specify the value of an index (position) and a value for the length of the substring.

The length secondary operand field can specify whether to allow or not allow for a null substring reference (a length value of zero).
Explicit base references
An instruction operand may specify an explicit override for the base pointer for a based data object or a based addressing object. The operand consists of a primary operand reference to the based object and a secondary operand reference to the pointer on which to base the object for this operand. The override is in effect for the single operand. The displacement implicit in the ODT definition of the primary operand and the addressability contained in the explicit pointer are combined to provide an address for the operand.

The explicit base may be combined with either the subscript or the substring compound operands to provide a based subscript compound operand or a based substring compound operand.