Modify Space Attributes (MODS)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2
0062 System object Size or space modification template

Operand 1: System pointer.

Operand 2: Binary scalar or character(28) scalar.

Bound Program Access 
Built-in number for MODS1 is 28.
MODS1 (
       system_object  : address of system pointer
       size           : address of signed binary(4)  OR
                        address of unsigned binary(4)
)
  -- OR --
Built-in number for MODS2 is 29.
MODS2 (
       system_object                 : address of system pointer
       space_modification_template   : address
)

Description:

The attributes of the space associated with the system object specified for operand 1 are modified with the attribute values specified in operand 2.

At any security level, if the thread execution state is user state and the object addressed by operand 1 has secondary associated spaces, an attempt to truncate or delete any of the associated spaces of the addressed object will result in an invalid space modification (hex 3602) exception.

If the thread execution state is user state and the machine security level attribute has a value of hex 40 or greater then

  • If operand 1 addresses a program object, the associated spaces of the program object can not be modified and an invalid space modification (hex 3602) exception is signaled.
  • If the hardware storage protection of the object addressed by operand 1 is not read/write from user state, the associated spaces of the addressed object can not be modified and a space extension/truncation (hex 3601) exception is signaled.

The operand 2 space modification template is specified with one of two formats. The abbreviated format, operand 2 specified as a binary scalar, only provides for modifying the size of space attribute. The full format, operand 2 specified as a character scalar, provides for modifying the full set of space attributes.

When operand 2 is a binary value, it specifies the size in bytes to which the space size is to be modified. The current allocation of the space is extended or truncated accordingly to match as closely as possible the specified size. The modified space size will be of at least the size specified. The actual size allocated is dependent upon the algorithm used within the specific implementation of the machine.

When operand 2 is a character scalar, it specifies a selection of space attribute values to be used to modify the attributes of the space. Associated spaces can be modified, created or destroyed by this instruction. Not all attributes can be modified for existing associated spaces, so some template fields apply only when an associated space is being created, i.e. when a primary associated space of fixed length size zero is modified or when a secondary associated space is created. More detail is provided below within descriptions of individual fields.

The operand 2 character scalar must be at least 28 bytes long and have the following format:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Modification selection Char(4)
0
0
  • Modify space length attribute
    0 = No
    1 = Yes
  • Bit 0
0
0
  • Modify size of space
    0 = No
    1 = Yes
  • Bit 1
0
0
  • Modify initial value of space
    0 = No
    1 = Yes
  • Bit 2
0
0
  • Modify space alignment
    0 = No
    1 = Yes

    This field must have a value of 0 if an existing space is being modified. Otherwise an invalid space modification (hex 3602) exception is signaled.
  • Bit 3
0
0
  • Modify initialize space attribute
    0 = No
    1 = Yes
  • Bit 4
0
0
  • Reinitialize space
    0 = No
    1 = Yes
  • Bit 5
0
0
  • Modify automatically extend space attribute
    0 = No
    1 = Yes
  • Bit 6
0
0
  • Create secondary associated space
    0 = No
    1 = Yes

    If the thread execution state is user state, this field must be 0. Otherwise an invalid space modification (hex 3602) exception is signaled. This restriction applies at all system security levels.
  • Bit 7
0 0
  • Reserved (binary 0)
  • Bit 8
0
0
  • Modify hardware storage protection enforcement
    0 = No
    1 = Yes

    If the thread execution state is user state, this field must be 0. Otherwise an invalid space modification (hex 3602) exception is signaled. This restriction applies at all system security levels.


    If the object is not an independent index, process control space, or a space, this field must be 0. Otherwise an invalid space modification (hex 3602) exception is signaled.
  • Bit 9
0
0
  • Modify expanded transfer size advisory
    0 = No
    1 = Yes
  • Bit 10
0
0
  • Modify spreading the space object
    0 = No
    1 = Yes
  • Bit 11
0 0
  • Reserved (binary 0)
  • Bits 12-31
4 4 Indicator attributes Char(4)
4 4
  • Reserved (binary 0)
  • Bit 0
4
4
  • Space length
    0 = Fixed length
    1 = Variable length
  • Bit 1
4
4
  • Initialize space
    0 = Initialize
    1 = Do not initialize
  • Bit 2
4
4
  • Automatically extend space
    0 = No
    1 = Yes
  • Bit 3
4
4
  • Reserved (binary 0)
  • Bits 4-14
4
4
  • Hardware storage protection level
    00 = Reference and modify allowed for user state programs
    01 = Only reference allowed for user state programs
    10 = Invalid (undefined)
    11 = No reference or modify allowed for user state programs
  • Bits 15-16
4
4
  • Reserved (binary 0)
  • Bits 17-20
4
4
  • Always enforce hardware storage protection of this space
    0 = Enforce hardware storage protection of this space only when hardware storage protection is being enforced for all storage.
    1 = Enforce hardware storage protection of this space at all times.
  • Bit 21
4
4
  • Reserved (binary 0)
  • Bits 22-31
8
8
Maximum size of secondary associated space

This field is ignored when create secondary associated space is 0.



Bin(4)
12 C Size of space Bin(4) or UBin(4)
16 10 Initial value of space Char(1)
17 11 Performance class Char(4)
17
11
  • Space alignment
    0 = The space associated with the object is modified to allow proper alignment of pointers at 16-byte alignments within the space.
    1 = The space associated with the object is modified to allow proper alignment of input/output buffers at 512-byte alignments within the space. Note that this also allows proper 16-byte alignment of pointers. The value of this field is ignored when the machine chooses space alignment field has a value of 1.
  • Bit 0
17
11
  • Reserved
    There is no modification selection option for the field in CRTS that corresponds to this bit. So, currently this bit is ignored.
  • Bit 1
17
11
  • Spread the space object
    0 = All extensions to the space object should be on one storage device, if possible.
    1 = All extensions to the space object should be spread across multiple storage devices, if possible.
  • Bit 2
17
11
  • Machine chooses space alignment
    0 = The space alignment indicated by the space alignment field is performed.
    1 = The machine will choose the space alignment most beneficial to performance, which may reduce maximum space capacity. When the modify space alignment field has a value of 1 and this value is specified, the space alignment field is ignored, but the alignment chosen will be a multiple of 512.
  • Bit 3
17
11
  • Reserved
    There are no modification selection options for the fields in CRTS that correspond to these bits. So, currently these bits are ignored.
  • Bits 4-23
20 14
  • Expanded transfer size advisory
  • Char(1)
21 15 Reserved (binary 0) Char(1)
22
16
Secondary associated space number

If the thread execution state is user state, this field must be 0. Otherwise an invalid space modification (hex 3602) exception is signaled. This restriction applies at all system security levels.


UBin(2)
24 18 Size of space after modification Bin(4)
28
1C
--- End ---
 

The modification selection indicator fields select the modifications to be performed on the space.

The modify space length attribute modification selection field controls whether or not the space length attribute is to be modified. When yes is specified, the value of the space length indicator is used to modify the space to the specified fixed or variable length attribute. When no is specified, the space length indicator attribute value is ignored and the space length attribute is not modified.

The modify space length attribute modification selection field may not be set to yes for a packed secondary associated space. An attempt to do so will result in an invalid space modification (hex 3602) exception.

The modify size of space modification selection field controls whether or not the allocation size of the space is to be modified. When yes is specified, the current allocation of the space is extended or truncated accordingly to match as closely as possible the specified size in the size of space field. The modified size will be at least the size specified. The actual size allocated is dependent upon the algorithm used within the specific implementation of the machine. When no is specified, the current allocation of the space is not modified and the size of space field is ignored. The size of space after modification field is an output field that will contain the current size of the space. This field will be set even if the modify size of space field is set to no.

Modification of the size of space attribute for a space of fixed length can only be performed in conjunction with modification of the space length attribute. In this case, the space length attribute may be modified to the same fixed length attribute or to the variable length attribute. An attempt to modify the size of space attribute for a space of fixed length without modification of the space length attribute results in the signaling of the space extension/truncation (hex 3601) exception. Modification of the size of space attribute for a space of variable length can always be performed separately from a modification of the space length attribute.

When the size of space attribute is to be modified, if the value of the size of space field is negative or specifies a size larger than that for the largest space that can be associated with the object, the space extension/truncation (hex 3601) exception is signaled.

The modify size of space modification selection field may not be set to yes for a packed secondary associated space. An attempt to do so will result in an invalid space modification (hex 3602) exception.

The modify initial value of space modification selection field controls whether or not the initial value of space attribute is to be modified. When yes is specified, the value of the initial value of space field is used to modify the corresponding attribute of this space. This byte value will be used to initialize any new space allocations for this space due to an extension to the size of space attribute on the current execution of this instruction as well as any subsequent modifications. When no is specified, the initial value of space field is ignored and the initial value of space attribute is not modified.

The modify initial value of space modification selection field may not be set to yes for a packed secondary associated space. An attempt to do so will result in an invalid space modification (hex 3602) exception.

The modify space alignment modification selection field controls whether or not the space alignment and machine chooses space alignment attributes of the specified system object are to be modified. When yes is specified, the values of the space alignment and machine chooses space alignment fields are used to modify the space alignment of the specified system object. When no is specified, the space alignment attributes of the specified system object are not modified.

The modify space alignment modification selection field may not be set to yes for a packed secondary associated space. An attempt to do so will result in an invalid space modification (hex 3602) exception.

The modify initialize space attribute modification selection field controls whether or not the initialize space attribute is to be modified. When yes is specified, the value of the initialize space indicator attribute is used to modify that attribute of the specified space to the specified value. When no is specified, the initialize space indicator attribute value is ignored and the initialize space attribute is not modified.

Changing the value of the initialize space attribute only affects whether or not future extensions of the space will be initialized or not. That is, it is the state of this attribute at the time of allocation of the storage for a space that determines whether that newly allocated storage area will be initialized to the initial value specified for the space. Modifications of this attribute subsequent to the allocation of storage to a space have no effect on the value of that previously allocated storage area.

The modify initialize space attribute modification selection field may not be set to yes for a packed secondary associated space. An attempt to do so will result in an invalid space modification (hex 3602) exception.

The reinitialize space modification selection field controls whether the storage allocated to the space is to be reinitialized in its entirety. When no is specified, the space is not reinitialized. When yes is specified, the space is reinitialized. This re-initialization is performed after all other attribute modifications which may also have been specified on the instruction have been made. Thus changes to the size of the space, the initial value of the space, etc. will be put into effect and be considered the current attributes of the space for purposes of the re-initialization. The byte value used for the re-initialization is the current initial value for the space.

Note that specifying yes for the reinitialize space modification selection field for a space with current attributes of fixed length size zero results in no operation, because such a space has no allocated storage to reinitialize. Also, note that re-initialization of a space will have the side effect of resetting partial damage for a space object containing the space if the space object had previously been marked as having partial damage. This only applies to space objects; i.e. re-initialization of an associated space does not have the side effect of resetting partial damage for the MI object containing it.

The reinitialize space modification selection field may not be set to yes for a packed secondary associated space. An attempt to do so will result in an invalid space modification (hex 3602) exception.

The modify automatically extend space attribute modification selection field controls whether or not the automatically extend space attribute is to be modified. When yes is specified, the value of the automatically extend space indicator attribute is used to modify that attribute of the specified space to the specified value. When no is specified, the automatically extend space indicator attribute value is ignored and the automatically extend space attribute is not modified. The automatically extend space attribute can only be specified as yes when the space length attribute for the space is already variable length, or when the space length attribute is being modified to variable length. Invalid specification of the automatically extend space attribute results in the signaling of the invalid space modification (hex 3602) exception.

The modify automatically extend space modification selection field may not be set to yes for a packed secondary associated space. An attempt to do so will result in an invalid space modification (hex 3602) exception.

The create secondary associated space field indicates if a secondary associated space is to be created for the object. When this field is set to yes, most of the operand 2 template fields are used. However, all other modification selection fields are ignored, as are the spread the space, and always enforce hardware storage protection of this space fields. All secondary associated spaces are protected with hardware storage protection at all times.

The secondary associated space to be created is indicated by the secondary associated space number field. If the specified space already exists, or the object already has its maximum number of secondary associated spaces, the invalid space modification (hex 3602) exception is signalled.

The modify hardware storage protection enforcement selection field controls whether the enforce hardware storage protection of this space at all times attribute is to be modified. When yes is specified, the value of the enforce hardware storage protection of this space at all times field is used to control when hardware storage protection will be enforced for the primary associated space of a process control space, independent index, or space object that is being modified by this operation. When this attribute is selected and an existing space is being modified, the existing hardware storage protection level in effect for the space will be unchanged, but will either be enforced at all times, or only when hardware storage protection is enforced for all storage.

The modify expanded transfer size advisory selection field controls whether the expanded transfer size advisory attribute is to be modified. When yes is specified, the value of expanded transfer size advisory specifies the desired number of pages to be transferred between main store and auxiliary storage for implicit access state changes. This value is only an advisory; the machine may use a value of its choice for performing access state changes under some circumstances. For example, the machine may limit the transfer size to a smaller value than is specified. A value of zero is an explicit indication that the machine should use the machine default storage transfer size for this object.

Modification of the expanded transfer size advisory is only supported for space objects. Attempts to modify associated spaces of other system objects will cause the invalid space modification (hex 3602) exception to be signalled.

The modify spreading the space object attribute modification selection field controls whether or not the spread the space object attribute is to be modified. When yes is specified and spread the space object is binary 1, extensions to the space object will be spread across multiple storage devices, if possible. When yes is specified and spread the space object is zero, extensions to the space object will be contained on one storage device, if possible. When no is specified, the spread the space object field is ignored and the current attribute setting for the space object is unchanged. The actual storage devices used are dependent upon the algorithm used within the specific implementation of the machine. Only the new allocations of the space object are affected; the existing portion of the space object is not modified.

The modify spreading the space object modification selection field may not be set to yes for a packed secondary associated space. An attempt to do so will result in an invalid space modification (hex 3602) exception. This field is ignored for a system object that is not a space object.

The hardware storage protection level field determines the type(s) of accesses that are allowed to the space. This field is only used when creating associated spaces. That is, it is only used when extending the size of a primary associated space of fixed length and size equal to zero, or creating secondary associated space(s). For all other modifications it is ignored.

Modification to or from the state of a space being fixed length of size zero can not be performed for the following objects:

  • Byte stream file
  • Cursor
  • Data space
  • Directory
  • Program (when attempted while in user state on a security level 40 or higher system).
  • Space

Modification to or from the state of a space being fixed length of size zero might not be permitted for the following objects if they were created with an internal format incompatible with this change, which could have occurred for these objects if they were created before V4R4:

  • Class of service description
  • Controller description
  • Logical unit description
  • Mode description
  • Network description
If such a modification is attempted for the objects listed above, under the circumstances described above, the invalid space modification (hex 3602) exception is signaled.

Specifying the largest size of space needed value allows the machine, under certain circumstances, to select usage of an internal storage allocation unit which best utilizes the internal addressing resources within the machine. Note that the internal storage allocation unit selected can alter the maximum modification size of the associated space for the object. However, the machine will always use an internal storage allocation unit that will allow for extension of the space to at least the value specified in the largest size of space needed field. The maximum size to which the space can be modified is dependent upon specific implementations of the machine and can vary with different machine implementations.

The secondary associated space number field is used to indicate which secondary space is to be created or modified. When this field is zero, the primary associated space of the space object is modified. If this field is not zero and no secondary associated spaces are allowed for the object, the scalar value invalid (hex 3203) exception will be signalled.

A fixed length space of size zero is defined by the machine to have no internal storage allocation. Due to this, a modification to or from this state is, in essence, the same as a destroy or create for the space associated with the specified system object. The effect of modifying to this state is similar to destroying the associated space in that address references to the space through previously set pointers will result in signaling of the object destroyed (hex 2202) exception. When a primary associated space is destroyed by using this method, any secondary associated spaces for the object are also destroyed. To the contrary, modifying the space attributes from this state is similar to creating an associated space in that the Set Space Pointer from Pointer (SETSPPFP) instruction can be used to set a space pointer to the start of storage within the associated space and the allocated space storage can be used to contain space data.

The extension and truncation of a space is always by an implementation-defined multiple of 256 bytes. This means that if, for example, the implementation defined multiple is 2 (or 512 bytes), any modification of the space size will be in increments of 512 bytes.

Authorization Required

  • Object management
    • Operand 1
  • Execute
    • Contexts referenced for address resolution

Lock Enforcement

  • Materialize
    • Contexts referenced for address resolution
  • Object control
    • Operand 1 (when operand 2 is binary)
  • Modify
    • Operand 1 (when operand 2 is character)

Exceptions

  • 06 Addressing
    • 0601 Space Addressing Violation
    • 0602 Boundary Alignment
    • 0603 Range
  • 08 Argument/Parameter
    • 0801 Parameter Reference Violation
  • 0A Authorization
    • 0A01 Unauthorized for Operation
  • 10 Damage Encountered
    • 1004 System Object Damage State
    • 1005 Authority Verification Terminated Due to Damaged Object
    • 1044 Partial System Object Damage
  • 1A Lock State
    • 1A01 Invalid Lock State
  • 1C Machine-Dependent
    • 1C03 Machine Storage Limit Exceeded
    • 1C04 Object Storage Limit Exceeded
    • 1C0E IASP Resources Exceeded
    • 1C11 Independent ASP Varied Off
  • 20 Machine Support
    • 2002 Machine Check
    • 2003 Function Check
  • 22 Object Access
    • 2201 Object Not Found
    • 2202 Object Destroyed
    • 2203 Object Suspended
    • 2207 Authority Verification Terminated Due to Destroyed Object
    • 2208 Object Compressed
    • 220B Object Not Available
  • 24 Pointer Specification
    • 2401 Pointer Does Not Exist
    • 2402 Pointer Type Invalid
    • 2403 Pointer Addressing Invalid Object Type
  • 2E Resource Control Limit
    • 2E01 User Profile Storage Limit Exceeded
  • 32 Scalar Specification
    • 3203 Scalar Value Invalid
  • 36 Space Management
    • 3601 Space Extension/Truncation
    • 3602 Invalid Space Modification
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed