Machine Interface Introduction

Machine Interface Introduction

• Overview
• What's New for IBM i 7.2
• Instruction Format Conventions Used
• Reserved and Obsolete Fields
• NBP Operand Syntax
• Names
• Character Constants
• Standard Time Format
• Time-of-Day (TOD) Clock
• Storage Terminology
• Storage Limitations
• Atomicity
• Shared Storage Access Ordering
• External Standards
• Logical Partitioning

Overview

This web page contains the following:

• Detailed descriptions of the IBM i machine interface instruction fields and the formats of these fields
• A description of the format used in describing each instruction
• A list of the terms in the syntax that define the characteristics of the operands
• A discussion of some pervasive topics that apply to a wide range of instructions.

You should read this web page in its entirety before attempting to write instructions.

What's New for IBM i 7.2

This section gives an overview of some of the changes to the MI Architecture for IBM i 7.2.

1. Several MI instructions were updated to support an extended fractional second precision. In the past a fixed 6 fractional precision digits were supported. As of IBM i 7.2 anywhere from 0 through 12 fractional precision digits are supported. The default number of fractional precision digits is 6. The following instructions were affected by this change:
   • Compute Timestamp Duration (CTSD)
   • Convert Timestamp (CVTTS)
   • Decrement Time (DECT)
   • Decrement Timestamp (DECTS)
   • Increment Time (INCT)
   • Increment Timestamp (INCTS)
2. Changes were made to several instructions to retrieve a non-unique time of day. This is a performance improvement, as the retrieval of a unique time of day is comparatively expensive. The following instructions were affected by this change:
   • Dequeue (DEQ)
   • Materialize System Object (MATSOBJ)
   • Materialize Process Message (MATPRMSG)
   • Materialize Queue Messages (MATQMSG)
3. Materialize Context (MATCTX) was updated to support type/subtype ranges as input.
4. There were several changes to the Materialize Machine Attributes (MATMATR) instruction. Options 01E1 and 01E2 were added to support retrieval of information on virtual partitions. Option 0220 was updated with a new field: hardware instruction count and processor virtual time attribute. If this field is set then hardware instruction count and processor virtual time are supported on the processor. Options 0224 and 0228 contained updates related to partition suspend and resume.
5. There were several changes to the Materialize Process Attributes (MATPRATR) instruction. In the "Hex 10 = Maximum temporary auxiliary storage allowed" materialization option clarifications were made to the definitions for the maximum temporary auxiliary storage allowed in bytes and maximum temporary auxiliary storage allowed in megabytes fields. In the "Hex 21 = Process resource usage attributes" materialization option three new fields were added: temporary storage accounting identifier, peak temporary storage, and Hardware instructions run. A new hardware instructions run field was added to the "Hex 23 = Thread performance attributes" materialization option. In the "Hex 24 = Execution status attributes" three new fields were added: temporary storage, peak temporary storage, and hardware instructions run. A new "Hex 40 = Processor resource priority" materialization option was added to allow process resource priority settings to be materialized.
6. There were several changes to the Materialize Resource Management Data (MATRMD) instruction. Updates were made to option "Hex 39 = Materialize disk attributes" and option "Hex 3B = Materialize IOA Cache Battery information". A new option "Hex 3A = Materialize geographic mirroring information" was added. Small updates related to option "Hex 3A" were added to options "Hex 12", "Hex 20", and "Hex 30". New fields for tmporary storage event thresholds were added to options "Hex 12" and "Hex 20". A flag to detect the partial vary on of a mirror copy ASP was added to options "Hex 12" and "Hex 20". Fields to support materializing information on HyperSwap disk units was added to options "Hex 12", "Hex 20", and "Hex 30". Additional processor mode status information was made available in option "Hex 18". Fields supporting the materialization of the hardware instruction count and processor virtual time attribute were added to options "Hex 26" and "Hex 28".
7. Changes were made to the Materialize User Profile (MATUP) instruction to support the materialization of large storage authorizations for user profiles.

Instruction Format Conventions Used

The user must be aware that not every instruction uses every field described in this section. Only the information pertaining to the fields that are used by an instruction is provided for each instruction.

Each instruction is formatted with the instruction name followed by its base mnemonic.

Following this, for instructions supported by Non-Bound Programs (NBP), is the operation code (op code) in hexadecimal and the number of operands with their general meaning.

Example:

ADD NUMERIC (ADDN)

This information is followed by the operands and their syntax. See "DEFINITION OF THE NBP OPERAND SYNTAX" for a detailed discussion of the syntax of instruction operands.

Example:

Operand 1: Numeric variable scalar.

Operand 2: Numeric scalar.

Operand 3: Numeric scalar.

For instructions that are supported in Bound Programs (BP), a bound program access box is provided that describes the operands and return values associated with the instruction in bound programs. For example:

Built-in number for ALCHSS is 111.
ALCHSS (
        heap_identifier            : signed binary(4) OR
                                     unsigned binary(4) OR
                                     null operand
        size_of_space_allocation   : signed binary(4)
) :   space pointer(16) to a space allocation

A description of the parameters for bound program access to the instruction is given. See the corresponding programming language reference manual for details as to how this information should be interpreted for a given language.

If an operand is passed by reference, the data type of the operand is preceded by the word address. If an operand is passed by value, the data type of the operand is not preceded by the word address. A local form address, which is a type of address that can only refer to teraspace, can be used on any instructions that specify an address operand unless explicitly prohibited.

An address is the value contained in any space pointer, the location of a data object or the result of an address computation.

If the built-in function has a return value, it is specified following the closing ') :' characters. Not all built-in functions have a return value. If the built-in function has a return value, it may be returned either by address or by value and will state which method is used.

Description

A detailed description and a functional definition of the instruction is given.

When an instruction takes a template (data structure) as input or provides a template as output, the format of the template is defined as a series of fields. Each field is given a name and an associated data type. The valid data types are:

Bin(1)

Signed 1-byte binary (not valid if template is used by a non-bound program instruction).

UBin(1)

Unsigned 1-byte binary (not valid if template is used by a non-bound program instruction).

Bin(2)

Signed 2-byte binary

UBin(2)

Unsigned 2-byte binary

Bin(4)

Signed 4-byte binary

UBin(4)

Unsigned 4-byte binary

Bin(8)

Signed 8-byte binary (not valid if template is used by a non-bound program instruction).

UBin(8)

Unsigned 8-byte binary (not valid if template is used by a non-bound program instruction).

Bit x

A 1-bit field occupies position x. Bits are numbered from the highest most position being 0 (left-most) and the lowest most position being n (right-most).

Bit y-z

A series of 1-bit fields that occupy positions x through z inclusive. Bits are numbered from the highest most position being 0 (left-most) and the lowest most position being n (right-most).

Char(n)

Fixed length string of "n" 1-byte characters. Char(1) is also used to represent 1-byte binary values. Char(8) is used to represent 8-byte binary. The character string may be redefined to be series of 1 or more other data types.

Char(*)

Variable length string of 1-byte characters. The character string may be redefined to be series of 1 or more other data types.

Float(4)

A 4-byte binary floating-point number.

Float(8)

An 8-byte binary floating-point number.

DFlt(8)

An 8-byte decimal floating point number (not valid if template is used by a non-bound program instruction).

DFlt(16)

A 16-byte decimal floating point number (not valid if template is used by a non-bound program instruction).

Data pointer

A 16-byte area that contains a data pointer (must be on a 16-byte boundary).

Instruction pointer

A 16-byte area that contains an instruction pointer (must be on a 16-byte boundary).

Invocation pointer

A 16-byte area that contains an invocation pointer (must be on a 16-byte boundary).

Label pointer

A 16-byte area that contains a label pointer (must be on a 16-byte boundary).

Procedure pointer(16)

A 16-byte area that contains a procedure pointer (must be on a 16-byte boundary).

Procedure pointer(8)

An 8-byte area that contains a local pointer that identifies an active instance of a procedure (not valid in a template for a non-bound program)

Space pointer(16)

A 16-byte area that contains a space pointer (must be on a 16-byte boundary).

Space pointer(8)

An 8-byte area that contains a local pointer to teraspace (not valid in a template for a non-bound program)

Suspend pointer

A 16-byte area that contains a suspend pointer (must be on a 16-byte boundary).

Synchronization pointer

A 16-byte area that contains a synchronization pointer (must be on a 16-byte boundary).

System pointer

A 16-byte area that contains a system pointer (must be on a 16-byte boundary).

Open pointer

A 16-byte area that contains a pointer with an unspecified type (must be on a 16-byte boundary).

Example:

This hypothetical template is composed of:

1. An 8-byte character string which is defined to be composed of 2 unsigned 4-byte binary values.
2. A 32-byte character string which is defined to be composed of three fields: a 1-byte character field, another 1-byte character field, and lastly a 30-byte character field.
3. A 4-byte character string which is defined to be reserved for future use and that will contain a value of binary zeroes.
4. A 4-byte character string which is defined to be composed of a series of bit fields: 1-bit fields are defined for positions 0, 5, 6, and 7; a 4-bit field is reserved in positions 1 through 4; an 8-bit field is defined in positions 8 through 15; and a 16-bit field is defined as being reserved in positions 16-31.
5. A system pointer to a context object. This pointer is on a 16-byte boundary with respect to the beginning of the template. The architecture assumes that the template begins on a 16-byte boundary.
6. The template is 64 bytes in length.

When a template field represents an array or repeating structure, the field data type will be proceeded by a "dimension" which indicates the number of elements in the array or the number of times the structure is repeated.

Example:

In this example, there is:

1. Twelve occurrences of a signed 4-byte binary number.
2. Four occurrences of a 4-byte structure which is composed of 3 fields; 2 1-byte character strings and 1 signed 2-byte binary number.
3. Three occurrences of a 16-byte space pointer.
4. Five occurrences of a variable length character string. Normally the instruction will provide additional information regarding how to determine the length of each occurrence.
5. A variable number of occurrences of a variable length character string. Normally the instruction will provide additional information regarding how to determine the number of occurrences and the length of each occurrence.

When terms are defined or fields in a template are described, they are highlighted as follows: term definition. When a term is referenced or a value of a field is referred to, it is highlighted as follows: term reference.

Fields in a template are generally described in the same order as they are defined in the template. However, some fields are more appropriately described with other related fields, so they may not appear in exact order.

Limitations (Subject to Change)

These are the limits that apply to the functions performed by the instruction. These limits are subject to change.

Resultant Conditions

These are the conditions that can be set at the end of the standard operation in order to perform a conditional branch or set a conditional indicator.

Authorization Required

A list of the object authorization required for each of the operands in the instruction or for any objects subsequently referenced by the instruction is given.

Lock Enforcement

Describes the specification of the lock states that are to be enforced during execution of the instruction.

The following states of enforcement can be specified for an instruction:

• Enforcement for materialization

  Access to a system object is allowed if no other thread is holding a locked exclusive no read (LENR) lock on the object. In general, this rule applies to instructions that access an object for materialization and retrieval.

• Enforcement for modification

  Access to a system object is allowed if no other thread is holding a locked exclusive no read (LENR), locked exclusive allow read (LEAR), or locked shared read only (LSRO) lock. In general, this rule applies to instructions that modify or alter the contents of a system object.

• Enforcement of object control

  Access is prohibited if another thread is holding any lock on the system object. In general, this rule applies to instructions that destroy or rename a system object.

Error Conditions

For those instructions supported in bound programs that return a completion value, this section lists the possible values that can be returned.

Exceptions

The exceptions sections contain a list of exceptions that can be caused by the instruction. Exceptions related to specific operands are indicated for each exception by the exception under the heading operand. An entry under the word, other, indicates that the exception applies to the instruction but not to a particular operand.

Reserved and Obsolete Fields

Reserved Fields

Fields in an instruction template that are specified as being reserved must contain binary 0s on input and will usually contain binary 0s on output. In most cases, specifying a value other than zero may cause an exception or unpredictable results.

As the MI Architecture evolves and responds to new and changing requirements, it is necessary to make use of reserved fields to support new function. The MI user must be aware that on subsequent releases

• a formerly reserved field may not return binary 0s
• a reserved field that was not checked for binary 0s may begin to have binary 0 values enforced on input
• a formerly reserved field may begin to accept nonzero values in support of a new or expanded function.

So, for example, if a template byte had the first six bits used, followed by two reserved bits, code that relies on having all the defined bits turned on should check the bits individually instead of comparing the whole byte to hex FC.

Obsolete Fields

As the MI Architecture evolves and responds to new and changing requirements, it is necessary sometimes to remove support for an existing field in a template. When this occurs, the field will remain in the template to provide compatibility with existing instances of the instruction but the field will be marked as obsolete.

Values provided by the MI user in obsolete fields will be ignored by the machine.

Definition of the NBP Operand Syntax

Syntax consists of the allowable choices for each instruction operand. The following are the common terms used in the syntax and the meanings of those terms:

• Numeric: Numeric attribute of binary, packed decimal, zoned-decimal, or floating-point.
• Character: character attribute
• Scalar:
  • Scalar data object that is not an array (see note 1)
  • Constant scalar object
  • Immediate operand (signed or unsigned)
  • Element of an array of scalars (see notes 1 and 2)
  • Substring of a character scalar or a character scalar constant data object (see notes 1 and 3)
• Data Pointer Defined Scalar:
  • A scalar defined by a data pointer
  • Substring of a character scalar defined by a data pointer (see notes 1 and 3)
• Pointer:
  • Pointer data object that is not an array (see note 1)
  • Element of an array of pointers (see notes 1 and 2)
  • Space pointer machine object
• Array: An array of scalars or an array of pointers (see note 1)
• Variable Scalar: Same as scalar except constant scalar objects and immediate operand values are excluded.
• Data Pointer: A pointer data object that is to be used as a data pointer.
  • If the operand is a source operand, the pointer storage form must contain a data pointer when the instruction is executed.
  • If the operand is a receiver operand, a data pointer is constructed by the instruction in the specified area regardless of its current contents (see note 4).
• Open pointer: specifies that all 16-byte pointer types are supported by the instruction. When a new pointer type is added to the architecture, the instruction's implementation doesn't require any updates.

  However, if an instruction lists all of the defined 16-byte pointer types as valid data types for an operand, that instruction's implementation may have to be updated when a new pointer type is defined.

• Space Pointer: A space pointer data object or a space pointer machine object.
• Space Pointer Data Object: A pointer data object that is to be used as a space pointer.
  • If the operand is a source operand, the pointer storage form must contain a space pointer when the instruction is executed.
  • If the operand is a receiver operand, a space pointer is constructed by the instruction in the specified area regardless of its current contents (see note 4).
• System Pointer: a pointer data object that is to be used as a system pointer.
  • If the operand is a source operand, the specified area must contain a system pointer when the instruction is executed.
  • If the operand is a receiver operand, a system pointer is constructed by the instruction in the specified area regardless of its current contents (see note 4).
• Relative Instruction Number: Signed immediate operand. (NBP only)
• Instruction Number: Unsigned immediate operand. (NBP only)
• Instruction Pointer: A pointer data object that is to be used as an instruction pointer. (NBP only)
  • If the operand is a source operand, the specified area must contain an instruction pointer when the instruction is executed.
  • If the operand is a receiver operand, an instruction pointer is constructed by the instruction in the specified area regardless of its current contents (see notes 4 and 5).
• Invocation Pointer: A pointer data object that is to be used as an invocation pointer.
  • If the operand is a source operand, the specified area must contain an invocation pointer when the instruction is executed.
  • If the operand is a receiver operand, an invocation pointer is constructed by the instruction in the specified area regardless of its current contents (see note 4).
• Procedure Pointer: A pointer data object that is to be used as a procedure pointer.
  • If the operand is a source operand, the specified area must contain a procedure pointer when the instruction is executed.
  • If the operand is a receiver operand, a procedure pointer is constructed by the instruction in the specified area regardless of its current contents (see note 4).
• Label Pointer: A pointer data object that is to be used as an label pointer.
  • If the operand is a source operand, the specified area must contain a label pointer when the instruction is executed.
  • If the operand is a receiver operand, a label pointer is constructed by the instruction in the specified area regardless of its current contents (see note 4).
• Suspend Pointer: A pointer data object that is to be used as an suspend pointer.
  • If the operand is a source operand, the specified area must contain a suspend pointer when the instruction is executed.
  • If the operand is a receiver operand, a suspend pointer is constructed by the instruction in the specified area regardless of its current contents (see note 4).
• Synchronization Pointer: A pointer data object that is to be used as an synchronization pointer.
  • If the operand is a source operand, the specified area must contain a synchronization pointer when the instruction is executed.
  • If the operand is a receiver operand, a synchronization pointer is constructed by the instruction in the specified area regardless of its current contents (see note 4).
• Instruction Definition List Element: An entry in an instruction definition list that can be used as a branch target (NBP only). A compound subscript operand form must always be used (see note 5).

Alternate choices of NBP operand types and the allowable variations within each choice are indicated in the syntax descriptions as shown in the following example.

Operand 1: Numeric variable scalar.

Operand 2: Numeric scalar.

Operand 3: Instruction number, branch point or instruction pointer.

Operand 1 must be variable scalar. Operands 1 and 2 must be numeric. Operand 3 can be an instruction number, branch point or instruction pointer.

When a length is specified in the syntax for an NBP operand, character scalar operands must be at least the size specified. Any excess beyond that required by the instruction is ignored.

Scalar NBP operands that are operated on by instructions requiring 1-byte operands, such as pad values or indicator operands, can be greater than 1 byte in length; however, only the first byte of the character string is used. The remaining bytes are ignored by the instruction.

Names

The MI architecture treats names, unless explicitly stated otherwise, as a sequence of unencoded bytes. That is, the machine treats each byte of an object name as a sequence of bits which the machine stores and returns without modification.

Names, being unencoded, are not associated with any Coded Character Set Identifier (CCSID) or any other National Language Support information by the machine. The machine does not perform (unless explicitly stated) any character translations on names.

Character Constants

The character constants specified in an instruction (in the form 'X' where X represents a single character) are required by the machine to be from the EBCDIC invariant character set. This includes the following characters.

 
'A' = hex C1     'a' = hex 81     '0' = hex F0      ':' = hex 7A
'B' = hex C2     'b' = hex 82     '1' = hex F1      ';' = hex 5E
'C' = hex C3     'c' = hex 83     '2' = hex F2      '?' = hex 6F
'D' = hex C4     'd' = hex 84     '3' = hex F3
'E' = hex C5     'e' = hex 85     '4' = hex F4
'F' = hex C6     'f' = hex 86     '5' = hex F5
'G' = hex C7     'g' = hex 87     '6' = hex F6
'H' = hex C8     'h' = hex 88     '7' = hex F7
'I' = hex C9     'i' = hex 89     '8' = hex F8
'J' = hex D1     'j' = hex 91     '9' = hex F9
'K' = hex D2     'k' = hex 92     '+' = hex 4E
'L' = hex D3     'l' = hex 93     '>' = hex 6E
'M' = hex D4     'm' = hex 94     '=' = hex 7E
'N' = hex D5     'n' = hex 95     '<' = hex 4C
'O' = hex D6     'o' = hex 96     '%' = hex 6C
'P' = hex D7     'p' = hex 97     '@' = hex 7C
'Q' = hex D8     'q' = hex 98     '*' = hex 5C
'R' = hex D9     'r' = hex 99     ''' = hex 7D
'S' = hex E2     's' = hex A2     '"' = hex 7F
'T' = hex E3     't' = hex A3     '(' = hex 4D
'U' = hex E4     'u' = hex A4     ')' = hex 5D
'V' = hex E5     'v' = hex A5     ',' = hex 6B
'W' = hex E6     'w' = hex A6     '_' = hex 6D
'X' = hex E7     'x' = hex A7     '-' = hex 60
'Y' = hex E8     'y' = hex A8     '.' = hex 4B
'Z' = hex E9     'z' = hex A9     '/' = hex 61

Standard Time Format

The Standard Time Format is defined as a 64-bit (8-byte) unsigned binary value as follows:

The time field is a binary number which can be interpreted as a time value in units of 1 microsecond. A binary 1 in bit 51 is equal to 1 microsecond.

The uniqueness bits field may contain any combination of binary 1s and 0s. These bits do not provide additional granularity for a time value; they merely allow unique 64-bit values to be returned, such as when the value of the time-of-day (TOD) clock is materialized. When the uniqueness bits all contain binary 0s, then the 64-bit value returned is not unique. Unless explicitly stated otherwise, MI instructions which materialize the TOD clock return a unique 64-bit value.

A number of MI instructions define fields to contain a binary value which may represent a time stamp or time interval, or may specify a wait time-out period. Unless explicitly stated otherwise, the format of the field is the Standard Time Format.

Examples of binary values as time intervals:

     A hex value of...  Represents...
     0000000000001000   1 microsecond
     0000000000008000   8 microseconds
     00000000F4240000   1 second
     00000D693A400000   1 hour
     0008CD0E3A000000   1 week

Examples of binary values as Coordinated Universal Time (UTC) time stamps:

     A hex value of...  Represents...
     0000000000000000   08/23/1928 12:03:06.314752
     4A2FEC4C82000000   01/01/1970 00:00:00.000000
     8000000000000000   01/01/2000 00:00:00.000000
     DFFFFFFFFFFF8000   07/07/2053 20:57:40.263928
     EFFFFFFFFFFFF000   06/08/2062 16:27:16.974591

Time-of-Day (TOD) Clock

The time-of-day (TOD) clock is a machine facility which provides a consistent measure of elapsed time. The value of the TOD clock can be materialized in "STANDARD TIME FORMAT". The time field of the TOD clock is incremented by adding a binary 1 in bit 51 every microsecond. This gives the TOD clock a granularity of 1 microsecond. However, the observed granularity cannot be accurately predicted because retrieval latency depends on the current implementation of the machine facility and the workload on the machine when the request is made.

Depending upon the MI instruction used, the value of the TOD clock may be materialized either as the Coordinated Universal Time (UTC) for the system, with or without a time zone offset and year offset, or as the local time for the system.

Coordinated Universal Time (UTC) is a universally coordinated time scale that is kept by timing laboratories around the world and is determined using highly precise atomic clocks. The International Bureau of Weights and Measures makes use of data from the timing laboratories to provide the international standard UTC. UTC is the current term for what was commonly referred to as Greenwich Mean Time (GMT). Zero hours UTC is midnight in Greenwich, England, which lies on the zero longitudinal meridian. UTC values are based in the current Gregorian calendar year.

The time zone offset is a signed integer which is the difference between UTC and the local time for a time zone, including any adjustment for Daylight Saving Time, as measured in minutes of time westward from Greenwich, England. The time zone offset, along with the year offset, can be used to convert between UTC and local time values.

Year offset is a signed integer which is the difference, measured in years, between the UTC calendar year and the calendar year of local time for a time zone in a non-Gregorian calendar. Year offset is binary 0 when local time is in the Gregorian calendar year. When the local time is in a non-Gregorian calendar year, then year offset is a positive value when the non-Gregorian calendar year is greater than the UTC calendar year. The year offset, along with the time zone offset, can be used to convert between UTC and local time values.

A local time value is generated by applying a time zone offset and a year offset to the UTC value for the system.

• The local time value is for the system, Local System Time (LST), when the time zone offset and year offset for the system are applied to the UTC value.
• The local time value is for the process, Local Process Time (LPT), when the time zone offset and year offset for the process are applied to the UTC value.
• When the values of the time zone offset and year offset are both binary 0, then the UTC and the local time values are identical.

The value of the TOD clock as UTC for the system, the time zone offset for the system, and the year offset for the system can be materialized using the Materialize Time Of Day Attributes (MATTODAT) instruction.

The value of the TOD clock as either UTC or as local time for the system can be materialized using the Materialize Machine Data (MATMDATA) instruction.

The TOD clock machine facility guarantees that each request to materialize the value of the TOD clock will receive a unique, monotonically increasing value. However, the MI user must be aware that under the following conditions unique, monotonically increasing values may not be observed:

• Values across threads

  Each request may have a different latency between when the request is made and when the value is returned. Therefore, the values returned for requests from different threads may not be in the same order in which the requests are made.

• Modification of the TOD clock

  Modification of the TOD clock to an earlier value can result in the materialization of values which are not unique nor monotonically increasing as compared to values materialized before the modification.

• Conversion of the TOD clock

  Conversion of TOD clock values between local time and UTC values can result in creating values which are not unique as compared to materialized values.

• Time zone offset change

  A time zone offset change, such as when changing from Daylight Saving Time to Standard Time, can result in the materialization of local time values which are not unique nor monotonically increasing as compared to local time values materialized before the change.

• Uniqueness bits all contain binary 0s

  TOD clock values in which the uniqueness bits all contain binary 0s are not unique. TOD clock values materialized with an option to not get a unique value will have uniqueness bits which all contain binary 0s.

Storage Terminology

The term basic storage unit is defined to mean 512 bytes of storage. Basic storage units are commonly used to return the size information about MI objects.

The term page is defined to mean one or more basic storage units used by the machine to manage memory and DASD.

The term machine default page size is defined to mean the page size used by the machine in the absence of any other page size specification. The machine default page size can be determined with option hex 0005 of the Materialize Machine Data (MATMDATA) instruction.

The term machine minimum transfer size is defined to be the smallest number of bytes that may be transferred as a block to and from main storage. The number of bytes in the machine minimum transfer size can be determined with option hex 9 of the Materialize Resource Machine Data (MATRMD) instruction.

The term teraspace segment is defined to mean one or more pages that are treated as a unit when managing teraspace storage. A teraspace segment is aligned on an address boundary that is a multiple of its size, relative to the beginning of a process' teraspace address range. The number of bytes in a teraspace segment can be determined with option hex 0006 of the Materialize Machine Data (MATMDATA) instruction.

Storage Limitations

The following sub-sections describe data object size limits that are checked during module or program creation and storage limits that are checked when the program is activated or run. In some cases the creation-time limits are more generous than the run-time limits, so it's possible to create a program that will not run. The values in the following tables are in bytes.

Throughout this section, the following abbreviations are used:

K = 1024, M = 1048576, G = 1073741824, T = 1099511627776, page = page size.

See "Storage Terminology" for more details on the page size.

Size limits for data objects in bound programs

Size limits for data objects in non-bound programs

Machine managed storage limits

The maximum size of teraspace is approximately 64T.

Program managed storage limits

Thread Safety

A function is thread-safe if it can be started simultaneously in multiple threads within the same process. All MI instructions are thread-safe unless the instruction specifies otherwise.

Atomicity

Atomicity of MI Instructions

MI instructions are not atomic unless they explicitly state that they perform some function atomically. So, it is possible for the function performed by an MI instruction to be only partially completed from the viewpoint of a program in another thread, or within the same thread when an exception occurs.

When a program is being created, many hardware instructions may be generated that will perform one MI instruction's function at run time. Without the use of an external control mechanism such as a locking protocol, sequences of instructions cannot be atomic. Further, the set of hardware instructions that implement an MI instruction, generated when a module or program is created, can be changed over time to provide more efficient programs or to accommodate new hardware. Thus even those MI instructions for which the generated code appears to be atomic should not be assumed to be so unless they are specified as performing a function atomically.

Atomicity of Storage Operations

A storage operation reads data from storage or writes data to storage. An MI instruction's function may use from zero to very many storage operations. An individual storage operation may be atomic or not. An atomic storage operation is performed such that it appears to be either complete or not yet started to all possible observers (i.e. all threads, whether on the same or another processor). On the other hand, storage operations that are not atomic may appear to be partially performed to some observers.

Atomicity can affect the use of shared storage areas. If a program modifies shared data while holding a lock that guarantees exclusive access (only one reader or writer can concurrently access the data) then atomicity is not an issue. However, if programs do not have exclusive access, then the atomicity of storage operations may be important. For example, a program running in one thread may periodically update a value in a space, which is in turn read by a program running in another thread. If the operation used to store a new value is atomic, then the other threads will always observe either the old value or the new value. If the operation used to store a new value is not atomic, then the other threads may observe the old value, the new value, or some composite consisting of part of the old value and part of the new value.

The MI makes only these guarantees regarding the atomicity of storage operations.

• a storage operation on a 16 byte MI pointer is atomic
• a storage operation that directly¹ refers to a local pointer aligned on an 8 byte boundary is atomic
• a storage operation that directly¹ refers to a binary data object aligned on a boundary that is a multiple of its length is atomic
• a storage operation that directly¹ refers to a 4-byte or 8-byte decimal floating-point data object aligned on a boundary that is a multiple of its length is atomic
• the storage update performed by a Compare and Swap instruction is atomic
• the storage update performed by the Atomic Add instruction is atomic
• the storage update performed by the Atomic And instruction is atomic
• the storage update performed by the Atomic Or instruction is atomic
• the storage update performed by the Check Lock Value instruction is atomic
• the storage update performed by the Clear Lock Value instruction is atomic

Note that operations on character data are guaranteed to be atomic only when Compare and Swap is used. Also note that, even though individual storage operations on properly aligned binary data objects are atomic, MI instructions operating on such data are not atomic (unless their descriptions explicitly say that they are). For example, a CPYNV from one 4 byte binary data object to another, where both are aligned on 4 byte boundaries, is not guaranteed to be an atomic operation, even though the read of one data object and write of the other are each individually atomic.

Finally, note that a storage operation on a 16-byte decimal floating-point data not guaranteed to be atomic.

Shared Storage Access Ordering

Previous sections discussed atomicity of MI instructions and individual storage operations. For a related discussion of the ordering of multiple operations that access²

External Standards and Architectures

Some of the instructions may make reference to external standards and architectures. To fully understand the functions performed by those instructions, it may be necessary to obtain a copy of the pertinent document.

Logical Partitioning

Support for logical partitions has evolved since its initial release. Most MI instructions work the same in all logical partitions. However, a few MI instructions work differently depending on the logical partitioning environment. Any differences are described in the documentation for the MI instruction. MATMATR option 01E0 can be used to materialize the firmware level and other logical paritioning information.

The following list describes some of the terms used with logical partitioning:

Firmware level

The level of the Licensed Internal Code used by the hypervisor.

Full System Partition Mode

A physical machine with a single partition owning all system resources.

Hardware Management Console

Attached appliance designed to control the physical machine. It is used to define and manage logical partitions and other system wide functions. If the physical machine has Hardware Management Console, some system attributes must be set here. Hardware Management Console is not supported on all firmware levels.

Hypervisor

A hypervisor is a specialized portion of the machine that enables logical partitioning.

Logical partition

A subset of a single physical machine that contains resources (processors, memory, input/output devices). A logical partition operates as an independent system. If hardware requirements are met, multiple logical partitions can exist within a physical machine.

Logical Partition Mode

A physical machine with firmware level hex 10 and one or more partitions owning system resources. Hardware Management Console is used to enter and exit this mode.

Primary logical partition

A logical partition which provides certain general functions on which all logical partitions are dependent. A primary logical partition is not supported on all firmware levels.

Secondary logical partition

A logical partition which maintains a dependency on the primary logical partition. Otherwise, it operates as a stand-alone system. Secondary logical partitions are independent of each other. Secondary logical partitions are not supported on all firmware levels.

Service partition

The service partition is the logical partition on the system that has the authority to perform service-related functions on the system.

The following list describes the logical partitioning environments:

Physical machine with firmware level hex 00

A primary logical partition exists. Some system attributes must be set in the primary logical partition only. The physical machine may have zero or more secondary logical partitions.

Physical machine with firmware level hex 10, no Hardware Management Console

A primary partition does NOT exist. System attributes must be set in a partition. This environment is in Full System Partition Mode.

Physical machine with firmware level hex 10, Hardware Management Console attached

A primary partition does NOT exist. Some system attributes must be set in a partition and other system attributes must be set using Hardware Management Console. This environment may be in Full System Partition Mode or Logical Partition Mode.