Create Space (CRTS)


Op Code (Hex) Operand 1 Operand 2

0072 Pointer for space addressability Creation template

Operand 1: System pointer.

Operand 2: Space pointer.

Bound program access
Built-in number for CRTS is 25.
CRTS (
      pointer_for_space_addressability   : address of system pointer
      creation_template                  : address
)

Description

A space object is created with the attributes that are specified in the space creation template specified by operand 2, and addressability to the created space is placed in a system pointer that is returned in the addressing object specified by operand 1.

Space objects, unlike other types of system objects, are used to contain a space and serve no other purposes.

The template identified by operand 2 must be 16-byte aligned in the space. The following is the format of the space creation template:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Template size specification
Char(8) +
0 0
Size of template
Bin(4) +
4 4
Number of bytes available for materialization
Bin(4) +
8 8
Object identification
Char(32)
8 8
Object type
Char(1) +
9 9
Object subtype
Char(1)
10 A
Object name
Char(30)
40 28
Object creation options
Char(4)
40 28
Existence attribute
Bit 0



0 = Temporary
1 = Permanent



40 28
Space attribute
Bit 1



0 = Fixed-length
1 = Variable-length



40 28
Initial context
Bit 2



0 = Addressability is not inserted into context
1 = Addressability is inserted into context



40 28
Access group
Bit 3



0 = Do not create as member of access group
1 = Create as member of access group



40 28
Reserved (binary 0)
Bits 4-5
40 28
Public authority specified
Bit 6



0 = No
1 = Yes



40 28
Initial owner specified
Bit 7



0 = No
1 = Yes



40 28
Reserved (binary 0)
Bits 8-11
40 28
Set public authority in operand 1
Bit 12



0 = No
1 = Yes



40 28
Initialize space
Bit 13



0 = Initialize
1 = Do not initialize



40 28
Automatically extend space
Bit 14



0 = No
1 = Yes



40 28
Hardware storage protection level
Bits 15-16



00 = Reference and modify allowed for user state programs
01 = Only reference allowed for user state programs
10 = Invalid (yields template value invalid  (hex 3801) exception)

The MODS instruction can be used to change the hardware storage protection level to 10.

11 = No reference or modify allowed for user state programs



40 28
Process temporary space accounting
Bit 17



0 = The temporary space will be tracked to the creating process
1 = The temporary space will not be tracked to the creating process



40 28
Reserved (binary 0)
Bits 18-20






40 28
Always enforce hardware storage protection of space
Bit 21



0 = Enforce hardware storage protection of this space only when hardware storage protection is being enforced for all storage.
1 = Always enforce hardware storage protection of this space.



40 28
Reserved (binary 0)
Bits 22-31






44 2C
Recovery options
Char(4)
44 2C
Reserved (binary 0)
Char(2)
46 2E
ASP number
Char(2)
48 30
Size of space
Bin(4)
52 34
Initial value of space
Char(1)
53 35
Performance class
Char(4)
53 35
Space alignment
Bit 0



0 = The space associated with the object is allocated to allow proper alignment of pointers at 16-byte alignments within the space. If the size of space field is zero, this value must be specified.
1 = The space associated with the object is allocated to allow proper alignment of pointers at 16-byte alignments within the space as well as to allow proper alignment of input/output buffers at 512-byte alignments within the space.
The value of this field is ignored when a value of 1 is given for the machine chooses space alignment field.


53 35
Clear the space into main memory during creation
Bit 1



0 = Only a minimum amount (up to 4K) of the space will be in main storage upon completion of the instruction.
1 = Most of the space, with some limits enforced by the machine, will be in main storage upon completion of the instruction.



53 35
Spread the space object among storage devices
Bit 2



0 = The space should be created on one storage device, if possible.
1 = The space should be created spread among available storage devices, if possible. All extensions to the space object will also be spread unless this attribute is changed using the Modify Space Attributes (MODS) instruction.



53 35
Machine chooses space alignment
Bit 3



0 = The space alignment indicated by the space alignment field is performed.

Usage note: On all current and foreseen implementations of the machine, a substantial performance penalty is incurred by any access to space data in the first (partial) page of a space created with this value. This value should only be used when absolutely required for space capacity needs.

1 = The machine will choose the space alignment most beneficial to performance, which may reduce maximum space capacity. When this value is specified, the space alignment field is ignored, but the alignment chosen will be a multiple of 512. The maximum capacity for a space object for which the machine has chosen the alignment is returned by option Hex 0003 of MATMDATA. The maximum space capacity for a particular space object is returned by MATS.



53 35
Reserved (binary 0)
Bit 4
53 35
Main storage pool selection
Bit 5



0 = Process default main storage pool is used for object.
1 = Machine default main storage pool is used for object.



53 35
Transient storage pool selection
Bit 6



0 = Default main storage pool (process default or machine default as specified for main storage pool selection) is used for object.
1 = Transient storage pool is used for object.



53 35
Obsolete
Bit 7



This field is no longer used and will be ignored.



53 35
Unit number
Bits 8-15 +
53 35
Reserved (binary 0)
Bits 16-23
56 38
Expanded transfer size advisory
Char(1)
57 39
Reserved (binary 0)
Char(1)
58 3A
Public authority
Char(2)
60 3C
Extension offset
Bin(4)
64 40
Context
System pointer
80 50
Access group
System pointer
96 60
--- End ---

Note: The instruction ignores the values associated with template fields annotated with a plus sign (+).
A template extension must be specified for the initial owner specified creation option. Also, the template extension must be specified (extension offset must be nonzero) to specify any of the other template extension fields (those other than the initial owner user profile) as input to the instruction.

The template extension is located by the extension offset field. The template extension must be 16-byte aligned in the space. The following is the format of the template extension:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
User profile
System pointer
16 10
Largest size needed for space
Bin(4)
20 14
Domain assigned to the object
Char(2)



Hex 0000 = The domain will be chosen by the machine.
Hex 0001 = The domain will be 'User'.
Hex 8000 = The domain will be 'System'.


22 16
Reserved (binary 0)
Char(42)
64 40
--- End ---

If the created object is permanent, it is owned by the user profile governing thread execution. The owning user profile is implicitly assigned all private authority states for the object. The storage occupied by the created object is charged to this owning user profile. If the created object is temporary, there is no owning user profile, and all authority states are assigned as public. Storage occupied by the created space is charged to the process.

Permanent space objects cannot be created by user state programs when the system security level is 40 or above.

The object identification specifies the symbolic name that identifies the space within the machine. An object type of hex 19 is implicitly supplied by the machine. The object identification is used to identify the object on materialize instructions as well as to locate the object in a context that addresses the object. The object subtype must be hex EF.

The existence attribute specifies whether the space is to be created as temporary or permanent. A temporary space, if not explicitly destroyed by the user, is implicitly destroyed by the machine when machine processing is terminated. A permanent space exists in the machine until it is explicitly destroyed by the user.

The space attribute specifies whether the size of the space can vary. The space may have a fixed size or a variable size. The initial allocation is as specified in the size of space field. The machine allocates a space of at least the size specified. The actual size allocated depends on an algorithm defined by a specific implementation. A fixed size space of zero length causes a template value invalid  (hex 3801) exception to be signaled.

If the initial context creation attribute field indicates that addressability is inserted into context, the context field must contain a system pointer that identifies a context where addressability to the newly created space is to be placed. If addressability is not inserted into a context, the context field is ignored.

If the access group creation attribute field indicates that the space is to be created in an access group, the access group field must be a system pointer that identifies the access group in which the space is to be created. If the space is being created as a member of an access group, the existence attribute field must be temporary (bit 0 equals 0). If the space is not to be created into an access group, the access group field is ignored.

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

The public authority specified creation option controls whether or not the space is to be created with the public authority specified in the template. When yes is specified, the space is created with the public authority specified in the public authority field of the template. When no is specified, the public authority field is ignored and the space is created with default public authority. The default public authority depends on the value of the existence attribute: An existence attribute value of temporary results in a default public authority of all authority; an existence attribute value of permanent results in a default public authority of no authority.

The initial owner specified creation option controls whether or not the initial owner of the space is to be the user profile specified in the template. When yes is specified, initial ownership is assigned to the user profile specified in the user profile field of the template extension. When no is specified, initial ownership is assigned to the thread user profile and the user profile field in the template extension is ignored. The initial owner user profile is implicitly assigned all authority states for the object. The storage occupied by the created space is charged to the initial owner. If yes is specified for this creation option when the existence attribute specifies temporary, a template value invalid  (hex 3801) exception will be signaled.

The set public authority in operand 1 creation option controls, when the public authority specified creation option has also been specified as yes, whether or not the public authority attribute for the space is to be set into the system pointer returned in operand 1. When yes is specified, the specified public authority is set into operand 1. When no is specified, public authority is not set into operand 1. When the public authority specified creation option is set to no, this option can not be specified as yes (or else a template value invalid  (hex 3801) exception will be signalled) and the authority set into operand 1 is the default of no authority for a permanent or all authority for a temporary object (as specified by the existence attribute).

The initialize space creation option controls whether or not the space is to be initialized. When initialize is specified, each byte of the space is initialized to a value specified by the initial value of space field. Additionally, when the space is extended in size, this byte value is also used to initialize the new allocation. When do not initialize is specified, the initial value of space field is ignored and the initial value of the bytes of the space are unpredictable.

When do not initialize is specified for a space, internal machine algorithms do ensure that any storage resources last used for allocations to another object which are reused to satisfy allocations for the space are reset to a machine default value to avoid possible access of data which may have been stored in the other object. To the contrary, reusage of storage areas previously used by the space object are not reset, thereby exposing subsequent reallocations of those storage areas within the space to access of the data which was previously stored within them.

The automatically extend space creation option controls whether the space is to be extended automatically by the machine or a space addressing violation  (hex 0601) exception is to be signaled when a reference is made to an area beyond the allocated portion of the space. When yes is specified, the space will automatically be extended by an amount determined through internal machine algorithms. When no is specified, the exception will result. Note that an attempt to reference an area beyond the maximum size that a space can be allocated, will always result in the signaling of the space addressing violation  (hex 0601) exception independently of the setting of this attribute. The automatically extend space creation option can only be specified when the space attribute has been specified as variable length. Invalid specification of the automatically extend space option results in the signaling of the template value invalid  (hex 3801) exception.

Usage of the automatically extend space function is limited. Predictable results will occur only when you ensure that the automatic extension of a space will not happen in conjunction with modification of the space size by another thread. That is, you must ensure that when a thread is using the space in a manner that could cause it to be automatically extended, it is the sole thread which can cause the space size to be modified. Note that in addition to implicit modification through automatic extension, the space size can be explicitly modified through use of the Modify Space Attributes (MODS) instruction.

The hardware storage protection level can be used to restrict access to the contents of the space by user state programs. It is possible to limit the access of the space by user state programs into 1 of three levels:

Process temporary space accounting can be used to detect when temporary space objects, created within a process, still exist at process termination time. Temporary spaces that are created with the process temporary space accounting field set to 0 will be "tracked" to the process which created them. Temporary spaces that are created with the process temporary space accounting field set to 1 will not be "tracked" to the creating process.

At process termination time, any tracked spaces that exist may cause the machine to attempt to destroy the existing tracked spaces. If this is done, the destroy attempts would be performed as if an MI program issued a Destroy Space (DESS) instruction for each of the existing spaces.

The purpose of process temporary space accounting is to identify objects which may be "lost" in the system (until the next IPL). It should not intentionally be used (by MI) as a method of cleaning up temporary space objects at process termination time. The machine does not guarantee that all spaces (that should be tracked) will indeed be tracked. Also, if the machine is attempting to destroy tracked spaces at process termination time, any failures in the deletion attempts (such as if a space is locked to another process) will be ignored (i.e. the space will not be destroyed) and no indication of this is presented to the MI user.

Process temporary space accounting only applies to temporary space objects. A value of 1 for the process temporary space accounting field when creating a permanent object will result in a template value invalid  (hex 3801) exception. This is in spite of the fact that a value of 1 for this field would result in the same actions as when creating a permanent object (i.e. the object would not be tracked to the process). The exception is presented because this field is undefined for permanent objects.

The always enforce hardware storage protection of space field is used to specify whether the hardware storage protection given in the hardware storage protection level field should be enforced at all times for this space, or only when hardware storage protection is being enforced for all storage.

The ASP number field specifies the ASP number of the ASP on which the unit is to be allocated. A value of 0 indicates an ASP number is not specified and results in the default of allocating the object in the system ASP. Allocation on the system ASP can only be done implicitly by not specifying an ASP number. The only non-zero values allowed are 2 through 255 which specify the user ASP on which the space object will be allocated. Independent ASPs have numbers 33 through 255. The ASP number must specify an existing ASP. An ASP number of 1 or greater than 255 results in a template value invalid  (hex 3801) exception being signalled. The given ASP number must be currently configured on the system otherwise an auxiliary storage pool number invalid  (hex 1C09) exception is signalled. If the ASP number identifies an independent ASP, there must be an existing active logical unit description for the independent ASP otherwise an independent asp varied off  (hex 1C11) exception is signalled. A temporary object cannot be created into a user ASP. If this is attempted, a template value invalid  (hex 3801) exception is signalled. If the ASP number identifies an independent ASP, or initial context indicates that addressability is to be inserted into a context that resides in an independent ASP, then both must indicate the same independent ASP or belong to the same ASP group or else a template value invalid  (hex 3801) exception is signalled. The ASP number attribute of an object can be materialized, but cannot be modified.

The size of space field specifies the amount of user-addressable storage being requested for this create.

The performance class fields provide information allowing the machine to more effectively manage the space object considering the overall performance objectives of operations involving the space.

The extension offset specifies the byte offset from the beginning of the operand 2 template to the beginning of the template extension. An offset value of zero specifies that the template extension is not provided. A negative offset value is invalid. A non-zero offset must be a multiple of 16 (to cause 16 byte alignment of the extension). Except for these restrictions, the offset value is not verified for correctness relative to the location of other portions of the create template.

The largest size needed for space field of the template extension specifies, when nonzero, a value in bytes that indicates the largest size that will be needed for the space. This field is different from the size of space field which indicates the size for the initial allocation of the space. This field can be used to communicate to the machine what the largest size needed for the space will be. Specification of a value larger than the maximum size space allowed for the space alignment chosen is invalid and results in signaling of the template value invalid  (hex 3801) exception. Specification of a nonzero value that is less than the size of space field also results in the signaling of the template value invalid  (hex 3801) exception. For more information on the maximum allowed, see "Limitations (Subject to Change)".

Specifying the largest size needed for space 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 needed for space 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. For more information on the effect of this option, see "Limitations (Subject to Change)".

The domain assigned field in the template extension allows the user of this instruction to override the domain for this object that would otherwise be chosen by the machine.

Any value specified for the domain assigned field other than those listed will result in a template value invalid  (hex 3801) exception being signalled.

Limitations (Subject to Change)

The following are limits that apply to the functions performed by this instruction. These limits may change on different implementations of the machine.

The maximum size of any space object for which the machine chose the alignment is returned by option Hex 0003 of MATMDATA. The maximum size of a particular space object is returned by the MATS instruction.

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

0A Authorization

0E Context Operation

10 Damage Encountered

1A Lock State

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

2E Resource Control Limit

36 Space Management

38 Template Specification

44 Protection Violation