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

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.

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.

• Object names

• Length/number of elements

• Explicit bases

• Explicit positions

• Initial values

• OES header extension

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

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.

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

ODV Format

OES Format

OES Header

OES Header Extension Appendage

Name Appendage

Scalar Length Appendage

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

Hex 0002 = 2
Hex 0004 = 4
All others reserved

Hex 0004 = 4
Hex 0008 = 8
All others reserved

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

Array Appendage

Base Appendage

Position Appendage

Initial Value Appendage

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:

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:

Notes:

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

2. 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).

3. See "Data Object Notes" for general notes concerning data objects.

Pointer Data Objects

Attribute Combinations

ODV Format

OES Format

OES Header

OES Header Extension Appendage

Array Appendage

Base Appendage

Position Appendage

Initial Value Appendage

If ODV bits 12-15 indicate instruction pointer:

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

If ODV bits 12-15 indicate data pointer:

If ODV bits 12-15 indicate space pointer:

• 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 ---

Notes:

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

2. 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.

3. 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.

4. A pointer data object defining an array may not be initialized. See "Data Object Notes".

5. 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.

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

Notes:

1. Any specification of position uses position 1 as the first position in storage. A position value of 0 is invalid.

2. 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.

3. 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

OES Format

OES Header

Instruction Stream Breakpoint Appendage

Parameter Appendage

Initial Value Appendage

Notes on Entry Points

Notes:

1. Only one external entry point may be defined.

2. If no external entry point is declared, the first instruction is assumed to be the external entry point with no parameters.

3. 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.

4. 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.

5. An internal entry point and an external entry point cannot reference the same instruction.

6. More than one internal entry point can reference the same instruction.

7. 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

OES Format

No OES is needed for branch points.

Instruction Definition List

Attribute Combinations

ODV Format

OES Format

OES Header

Initial Value Appendage

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

.
.
.

.
.
.

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

Operand List

Attribute Combinations

ODV Format

OES Format

OES Header

Initial Value Appendage

.
.
.

Notes:

1. Operand list entries must be either scalar data objects or pointer data objects.

2. An operand list cannot be both an argument list and a parameter list.

3. Argument lists referenced on Call Internal instructions must be fixed length.

4. Parameter lists referenced by internal entry points must be fixed-length internal parameter lists.

5. Internal parameter lists and argument lists used on internal calls can only be fixed-length.

6. A program may have only one external parameter list.

7. The same object cannot appear in more than one parameter list (internal or external) in a program template.

8. All the ODT entries for the elements of an operand list must appear before the ODT entry for that operand list.

9. Variable-length lists must define ODT references for every entry in the list.

10. Objects referenced in a parameter list must have the parameter attribute.

Constant Data Object

Attribute Combination

ODV Format

OES Format

OES Header

Length Information Appendage

Value Appendage

Exception Descriptions

Attribute Combinations

ODV Format

OES Format

Target Appendage

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

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

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

User Data Appendage

Compare Value Appendage

Exception Number Appendage

Notes:

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

2. 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)

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

OES Header

Pointer Machine Object

Attribute Combinations

ODV Format

OES Format

OES Header

Initial Value Appendage

If ODV bits 12-15 indicate space pointer:

Optimization Priority Appendage

.
.
.

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

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.