Description

The requirements for the caller are:

Before issuing IARSUBSP, the caller must obtain storage for the subspace by using the STORAGE or GETMAIN macro. See the RANGLIST parameter description for the required attributes of this storage. The caller must not release this storage until after issuing IARSUBSP UNIDENTIFY.

None.

Before issuing the IARSUBSP macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

None.

The standard form of the IARSUBSP macro is written as follows:

The IDENTIFY, CREATE, ASSIGN, UNASSIGN, DELETE, and UNIDENTIFY parameters designate the services of the IARSUBSP macro, and are mutually exclusive.

The parameters are explained as follows:

IDENTIFY

Identifies the ranges of storage specified on the RANGLIST parameter as eligible to be assigned to a subspace. When the IDENTIFY function successfully completes, the storage specified on the RANGLIST parameter cannot be referenced by a program running in a subspace until that storage is assigned to that subspace.

When you issue the IARSUBSP macro with IDENTIFY, you must specify the RANGLIST parameter. The NUMRANGE parameter is optional.

CREATE

Requests that the system create a subspace, and return an STOKEN by which a program can identify the subspace.

When you issue the IARSUBSP macro with CREATE, the NAME and STOKEN parameters are required. The GENNAME and OUTNAME parameters are optional.

ASSIGN

Requests that the system associate the range of storage specified on the RANGLIST parameter with the subspace indicated by the STOKEN parameter. When the range of storage has been assigned to the subspace, a program can reference the storage by issuing the BSG instruction.

When you issue the IARSUBSP macro with ASSIGN, you must specify the STOKEN and RANGLIST parameters. The NUMRANGE parameter is optional.

UNASSIGN

Requests that the system disassociate the storage identified by the RANGLIST parameter from the subspace identified by the STOKEN parameter. When the request is complete, the range of storage cannot be referenced by a program running in a subspace.

When you issue the IARSUBSP macro with UNASSIGN, you must specify the STOKEN and RANGLIST parameters. The NUMRANGE parameter is optional.

DELETE

Requests that the system delete the subspace indicated by the STOKEN parameter. The subspace can be deleted only by the task that created it.

When you issue the IARSUBSP macro with DELETE, you must specify the STOKEN parameter. Do not code any other parameters.

UNIDENTIFY

Identifies the ranges of storage specified on the RANGLIST parameter as ineligible to be assigned to a subspace.

If a range of storage specified on the RANGLIST parameter is still assigned to a subspace, the system will perform the UNASSIGN function before performing the UNIDENTIFY function.

When you issue the IARSUBSP macro with the UNIDENTIFY parameter, you must specify the RANGLIST parameter. The NUMRANGE parameter is optional.

,RANGLIST=ranglist_addr

Specifies the address of a fullword input variable containing the address of the range list. The range list is a list of 8-byte entries in contiguous storage that indicate the ranges of storage to be:

• Made eligible or ineligible to be assigned to a subspace, when specified with the IDENTIFY or UNIDENTIFY functions
• Associated with or disassociated from a subspace, when specified with the ASSIGN or UNASSIGN functions.

Each entry in the range list is 2 fullwords long. The first fullword contains the address of the beginning of the range of storage. The second fullword contains the number of 4-kilobyte (4096 bytes) pages that comprise the range of storage.

When RANGLIST is specified with the IDENTIFY or UNIDENTIFY parameter, the address in the first fullword must begin on a segment boundary. A segment is 1 megabyte (1,048,576 bytes) long. The value of the second fullword must be a multiple of 256.

When RANGLIST is specified with the ASSIGN or UNASSIGN parameters and the storage specified is above 16 megabytes, the requirements for the range list entries are the same as when RANGLIST is specified with IDENTIFY or UNIDENTIFY.

When RANGLIST is specified with the ASSIGN or UNASSIGN parameters and the storage specified is below 16 megabytes, the address in the first fullword must begin on a page boundary. A page is 4096 bytes. The value of the second fullword indicates the number of pages below 16 megabytes that are to be assigned to a subspace.

Each storage range must reside in a single subpool.

Obtain your subspace storage by selecting a storage subpool with the storage attributes that subspaces require. The chapter on virtual storage in z/OS MVS Programming: Authorized Assembler Services Guide contains a table listing all subpools and the storage attributes associated with them. The following are the required and optional storage attributes for subspaces.

Table 1. Storage Attributes Required for Subspaces

Storage Attribute	Requirement	Comments
Location	Private	Subspace storage must be in high private or low private storage.
Fetch Protection	None	Subspace storage can be fetch-protected, but fetch-protection is not required.
Type	Pageable	Subspace storage must be pageable.
Owner	Task or job step	Subspace storage must be owned by the task creating the subspace, or a task higher in the task hierarchy.
Storage key	None	Subspace storage has no storage key requirements.

RANGLIST is a required parameter when you specify the IDENTIFY, UNIDENTIFY, ASSIGN, and UNASSIGN parameters.

,NUMRANGE=numrange_addr

Specifies the address of an optional fullword input variable that indicates the number of ranges in the range list. The number of ranges must be a least 1 and no more than 16. If you do not code NUMRANGE, the default number of ranges is 1, and the range list is limited to one entry.

NUMRANGE is an optional parameter when you specify the IDENTIFY, UNIDENTIFY, ASSIGN, or UNASSIGN parameters.

,NAME=name_addr

Specifies the address of the 8-byte variable or constant that contains the name of the subspace.

Subspace names are from 1 to 8 bytes long. They can contain letters, numbers, and @, #, and $, but they cannot contain embedded blanks. Names that are fewer than 8 bytes must be left-justified and padded on the right with blanks.

Unless you specify GENNAME=YES, the subspace name must begin with a letter or an @, #, or $ character. When you do not code GENNAME, or you specify either GENNAME=NO or GENNAME=COND, the name cannot begin with a number or be blank.

Subspace names must be unique within the home address space of the owning task. No two subspaces can have the same name. To ensure that the names for your subspaces are unique, code the GENNAME parameter to have the system generate a unique name. If you choose to let the system generate the subspace names for you, you must still supply three characters for the system to use.

NAME is a required parameter when you specify the CREATE parameter.

,GENNAME=NO

,GENNAME=COND

,GENNAME=YES

Specifies whether you want the system to generate a name for the subspace to ensure that all names are unique within the address space. The system generates a name by adding a 5-character prefix to the first three characters of the name you supply on the NAME parameter. For example, if you supply ‘XYZDATA’ on the NAME parameter, the name becomes 'cccccXYZ'. "ccccc" is the 5-character string generated by the system, and XYZ comes from the name you supplied on NAME.

The keywords that are valid for GENNAME and their meanings follow:

GENNAME=NO

The system does not generate a name. You must supply a name unique within the address space. GENNAME=NO is the default.

GENNAME=COND

The system generates a unique name only if you supply a name that is already being used. Otherwise, the system uses the name you supply.

GENNAME=YES

The system takes the name you supply on the NAME parameter and makes it unique. When you specify GENNAME=YES, the name you supply in the name parameter can begin with a numeric.

If you want the system to return the unique name it generates, use the OUTNAME parameter.

GENNAME is an optional parameter when you specify the CREATE parameter.

,OUTNAME=outname_addr

Specifies the address of the 8-byte variable into which the system returns the subspace name it generated, if you specify GENNAME=YES or GENNAME=COND. The OUTNAME parameter is optional when you specify the CREATE parameter.

,STOKEN=stoken_addr

Specifies the address of the 8-byte STOKEN for the subspace. The system returns an STOKEN value as output for a CREATE request. For other requests, you supply this returned value as input. STOKEN is a required parameter for the CREATE, ASSIGN, UNASSIGN, and DELETE requests.

IARSUBSP might abnormally end with abend code X'3C6'. See z/OS MVS System Codes for an explanation and programmer response.

When the IARSUBSP macro returns control to your program, GPR 15 contains one of the following hexadecimal return codes. GPR 0 contains one of the following hexadecimal reason codes.

For a complete example of creating, managing, and deleting subspaces, see the chapter on subspaces in z/OS MVS Programming: Extended Addressability Guide.