Set Access State (SETACST)

Instruction Syntax

Op Code (Hex) Operand 1
0341 Access state template
Operand 1: Space pointer.

Bound Program Access 
Built-in number for SETACST is 70.
SETACST (
         access_state_template   : address
)

Description:

The instruction specifies the access state (which specifies the desired speed of access) that the issuing thread has for a set of objects or subobject elements in the execution interval following the execution of the instruction. The specification of an access state for an object momentarily preempts the machine's normal management of an object.

Note: This instruction should be used with caution when the pointer to object whose access state is to be changed field in the template below points to a process space (i.e. static storage, automatic storage, and activation group-based heap space storage). These process spaces may be shared by other programs, so explicit access management may affect those other programs. This instruction should be used with caution when the pointer to object whose access state is to be changed field in the template below points to handle-based heap space storage. Handle-based heap space storage may be shared by other threads in the process, so explicit access management may affect programs in those other threads.
CAUTION: MI system objects can be implemented with one or more storage structures for the functional part (encapsulated part) of the object. Unless explicitly noted otherwise, if a system pointer is specified for pointer to object whose access state is to be changed, the SETACST operations only act on the first (base) storage structure of an MI object's functional part and the object's primary associated space. The MI objects that are implemented with multiple storage structures are:
  • Cursor
  • Byte stream file
  • Byte string space
  • Data space
  • Data space index
  • Dump space
  • Independent index
  • Journal space
  • Module
  • Program
  • Queue
  • Queue space
  • User profile

The access state template must be aligned on a 16-byte boundary. The format is:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Number of objects to be acted upon Bin(4)
4 4 Reserved (binary 0) Char(12)
16
10
Access state specifications
(repeated as many times as necessary)
[*] Char(32)
16 10
  • Pointer to object whose access state is to be changed
  • Space pointer or System pointer
32 20
  • Access state code
  • Char(1)
33 21
  • Reserved (binary 0)
  • Char(3)
36 24
  • Access state parameter
  • Char(12)
36 24
    • Access pool ID
    • Char(4)
40 28
    • Space length
    • Bin(4)
44
2C
    • Operational object size
      Note: This value is returned for some of the access state code options.

    • Bin(4)
*
*
--- End ---
 
The number of objects field specifies how many objects are potential candidates for access state modification. An access state specification is included for each object to be acted upon.

The pointer to object field identifies the object or space which is to be acted upon. For the space associated with a system object, the space pointer may address any byte in the space. This pointer is followed by parameters that define in detail the action to be applied to the object.

The access state code designates the desired access state. The allowed values are as follows:

Access State Code (Hex)   Function and Required Parameter
00 No operations are performed.
01 Associated object is moved into main storage (if not already there) synchronously with the execution of the instruction.
02 Associated object is moved into main storage (if not already there) asynchronously with the execution of the instruction.

This operation will be applied to all internal storage areas for queue objects.

03 Associated object is placed in main storage without regard to the current contents of the object. This causes access to secondary storage to be reduced or eliminated. For this access state code, a space pointer must be provided.
04 Associated object is removed from main storage in a manner which reduces or eliminates access to secondary storage. Content of the object is unpredictable after this operation. For this access state code, a space pointer must be provided.
10 The object is synchronously ensured (changes written to auxiliary storage) and then removed from main storage. If the system pointer points to an object whose type is not a cursor, data space, data space index, program, or space then an object not eligible for operation (hex 2204) exception is signaled.

This option returns a number in the operational object size field. The unit assumed is the machine minimum transfer size (page size). The value returned is the total size of the operational parts of the object examined/processed, including the associated space (if there is one).

Note: This number is not the number of pages written or removed, but rather, is the total size of the object being processed. Some, all or none of the object may be in mainstore prior to the execution of the instruction.

The space length field must be zero for this operation. The entire associated space, if any, will be processed with the rest of the object's storage.

The access pool ID field is ignored for this operation.

The associated pointer to the object must be a system pointer.

This operation will be applied to all internal storage areas for queue objects.

18 This operation essentially combines the functions of a 10 code followed by asynchronously bringing the operational parts of the object into main storage. The object is brought into the main storage pool identified by the access pool ID field. If the system pointer points to an object whose type is not a cursor, data space, data space index, program, or space then an object not eligible for operation (hex 2204) exception is signaled.
Note: Because this function first removes the object from main storage and then brings it into main storage, this can be used to move an object from one main storage pool to another.

This option returns a number in the operational object size field. The unit assumed is the machine minimum transfer size (page size). The value returned is the total size of the object processed.

Note: If this value is larger than the size of the main storage pool being used, unpredictable parts of the object will be resident in the main storage pool following processing.

A preceding access code of 40 is ignored for this operation.

The space length field must be zero for this operation. The entire associated space, if any, will be processed with the rest of the object's storage.

The access pool ID field must be specified for this access code. It must be one of the storage pools existing in the machine as defined by the machine attribute.

The associated pointer to the object must be a system pointer.

This operation will be applied to all internal storage areas for cursor, data space and data space index objects.

20 Associated object attributes are moved into main storage synchronous with the instruction's execution. The associated attributes are the attributes that are common to all system objects. The associated pointer to object must be a resolved system pointer.

The space length field is ignored for this access code.

21 Associated object attributes are moved into main storage asynchronous with the instruction's execution. The associated attributes are the attributes that are common to all system objects. The associated pointer to object must be a resolved system pointer.

The space length field is ignored for this access code.

22 Common associated object attributes plus some specified amount of object-specific attributes are moved into main storage synchronous with the instruction's execution. The common associated attributes are the attributes that are common to all system objects. The object-specific attributes are attributes that vary from one object type to another. The amount of these attributes brought into main storage is controlled by the space length field.
Note: This use of space length is not consistent with the name of the field. For this code, the space length field does not control the size of any associated space processing, it controls the length of object-specific attributes processed.

The space length field works in the following manner: it specifies the amount of storage above and beyond the common object attributes which will be synchronously brought into storage. Therefore, a space length of 0 is valid, and results in an operation identical to access code 20.

The associated pointer to object must be a resolved system pointer.

23 Common associated object attributes plus some specified amount of object-specific attributes are moved into main storage asynchronous with the instruction's execution. The common associated attributes are the attributes that are common to all system objects. The object-specific attributes are attributes that vary from one object type to another. The amount of these attributes brought into main storage is controlled by the space length field.
Note: This use of space length is not consistent with the name of the field. For this code, the space length field does not control the size of any associated space processing, it controls the length of object-specific attributes processed.

The space length field works in the following manner: it specifies the amount of storage above and beyond the common object attributes which will be asynchronously brought into storage. Therefore, a space length of 0 is valid, and results in an operation identical to access code 21.

The associated pointer to object must be a resolved system pointer.

30 The associated space of the object is moved into main storage (if not already there) synchronously with the execution of the instruction. The space lengthfield is honored for this operation. The associated pointer to the object must be a system pointer.
31 The associated space of the object is moved into main storage (if not already there) asynchronously with the execution of the instruction. The space length field is honored for this operation. The associated pointer to the object must be a system pointer.
40 Perform no operation on the associated object. The main storage occupied by this object is to be used, if possible, to satisfy the request in the next access state specification entry. Either a space or system pointer may be provided for this access state code.

This operation will be applied to all internal storage areas for queue objects.

41 Wait for any previously issued but incomplete hex 81 or hex 91 access state code operations to complete. This includes all previous hex 81 and hex 91 operations that may have been performed on previous Set Access State instructions within the current thread as well as those that may have been issued in previous access state specification entries in the current instruction. The pointer is ignored for this access state code entry.

This operation will be applied to all internal storage areas for queue objects.

80 Object should be written and it is not needed in main storage by issuing thread. Object is written to nonvolatile storage synchronously with the execution of the instruction. Any main storage that the object occupied is then marked as to make it quickly available for replacement.

This operation will be applied to all internal storage areas for queue objects.

81 Object should be written and it is not needed in main storage by issuing process. Object is written to nonvolatile storage asynchronously with the execution of the instruction. Any main storage that the object occupied is then marked as to make it quickly available for replacement.

If desired, the thread can synchronize with any outstanding hex 81 access state operation by issuing a hex 41 access state operation either within the current instruction or during a subsequent Set Access State instruction.

This operation will be applied to all internal storage areas for queue objects.

90 Associated object must be insured, but is still needed in main storage. Object is written to nonvolatile storage synchronously with the execution of the instruction. Unlike access state codes hex 80 and hex 81, this access state code does not mark any main storage occupied by the object as to make it quickly available for replacement.

This operation will be applied to all internal storage areas for queue objects.

91 Associated object must be insured, but is still needed in main storage. Object is written to nonvolatile storage asynchronously with the execution of the instruction. Unlike access state codes hex 80 and hex 81, this access state code does not mark any main storage occupied by the object as to make it quickly available for replacement.

If desired, the thread can synchronize with any outstanding hex 91 access state operation by issuing a hex 41 access state operation either within the current instruction or during a subsequent Set Access State instruction.

Access state codes hex 03 and hex 04 may be used for spaces only. The pointer to the object in the access state specification must be a space pointer. Otherwise, the pointer type invalid (hex 2402) exception is signaled.

Access state code hex 40 may be used in conjunction with access state codes hex 01, hex 02, or hex 03. The access state specification entry with access state code hex 40 must immediately precede the access state specification entry with access state code hex 01, hex 02, or hex 03 with which it is to be combined. The pointer to the object in both entries must be a space pointer. Otherwise, the pointer type invalid (hex 2402) exception is signaled. The access state parameter field in the access state specification entry with code hex 40 is ignored. The access pool ID and the space length in the entry with access state code hex 01, hex 02, or hex 03 are used.

The access pool ID field indicates the desired main storage pool in which the object is to be placed (0-64). The storage pool ID entry is treated as a 4-byte logical binary value. When a 0 storage pool ID is specified, the storage pool associated with the issuing thread is used.

The space length field designates the part of the space associated with the object to be operated on. If the pointer to the object entry is a system pointer, the operation begins with the first byte of the space. If the pointer to the object entry is a space pointer that specifies a location, the operation proceeds for the number of storage units that are designated. No exception is signaled when the number of referenced bytes of the space are not allocated. When operations on objects are designated by system pointers, this operation is performed in addition to the access state modification of the object. This entry is ignored for access state codes hex 20 and hex 21. This entry will be truncated to a maximum of 65,536 for access state codes immediately following access state code 40.

The operational object size field is a value which is ignored upon input to the instruction and is set by the instruction for access codes 10 and 18. It represents, in units of minimum machine transfer size, the total size of the object which could/did participate in the operation. The parts of an object which are considered operational are decided by the machine and does include the associated space, if any.

Authorization Required

  • Execute
    • Contexts referenced for address resolution

Lock Enforcement

  • Materialize
    • Contexts referenced for address resolution

Exceptions

  • 04 Access State
    • 0401 Access State Specification Invalid
  • 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
  • 20 Machine Support
    • 2002 Machine Check
    • 2003 Function Check
  • 22 Object Access
    • 2201 Object Not Found
    • 2202 Object Destroyed
    • 2203 Object Suspended
    • 2204 Object Not Eligible for Operation
    • 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
    • 2404 Pointer Not Resolved
  • 2E Resource Control Limit
    • 2E01 User Profile Storage Limit Exceeded
  • 36 Space Management
    • 3601 Space Extension/Truncation
  • 38 Template Specification
    • 3801 Template Value Invalid
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed