Use the IARSUBSP macro to create and delete subspaces. A subspace is a section of address space private area storage that you have set up to contain and protect a program and its data. Subspaces provide isolation between multiple programs running in a single address space by allowing a program that runs in the subspace to reference only certain storage in the address space private area. For more information about subspaces and how to use them, see z/OS MVS Programming: Extended Addressability Guide.
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | For the ASSIGN and UNASSIGN parameters, problem
state with any PSW key. For IDENTIFY, CREATE, DELETE, and UNIDENTIFY, supervisor state or PSW key 0 - 7. |
Dispatchable unit mode: | For IDENTIFY, CREATE, DELETE, and UNIDENTIFY,
task. For ASSIGN and UNASSIGN, task or SRB. |
Cross memory mode: | For IDENTIFY, CREATE, DELETE, and UNIDENTIFY,
PASN=HASN=SASN. For ASSIGN and UNASSIGN, PASN=HASN, any SASN. |
AMODE: | 31-bit |
ASC mode: | Primary or access register (AR) |
Interrupt status: | Enabled for I/O and external interrupts |
Locks: | The caller cannot hold locks. |
Control parameters: | Control parameters must be in the primary address space. |
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:
Syntax | Description |
---|---|
name | name: symbol. Begin name in column 1. |
␢ | One or more blanks must precede IARSUBSP. |
IARSUBSP | |
␢ | One or more blanks must follow IARSUBSP. |
Valid parameters (required parameters are underlined): | |
IDENTIFY | RANGLIST,NUMRANGE |
CREATE | NAME,STOKEN,GENNAME,OUTNAME |
ASSIGN | RANGLIST,STOKEN,NUMRANGE |
UNASSIGN | RANGLIST,STOKEN,NUMRANGE |
DELETE | STOKEN |
UNIDENTIFY | RANGLIST,NUMRANGE |
,RANGLIST=ranglist_addr | RS-type address, or address in register (2) - (12). |
,NUMRANGE=numrange_addr | RS-type address, or address in register (2) - (12). |
Default: 1 range | |
,NAME=name_addr | RS-type address, or address in register (2) - (12). |
,GENNAME=NO | Default: GENNAME=NO |
,GENNAME=COND | |
,GENNAME=YES | |
,OUTNAME=outname_addr | RS-type address, or address in register (2) - (12). |
,STOKEN=stoken_addr | RS-type address, or address in register (2) - (12). |
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:
When you issue the IARSUBSP macro with IDENTIFY, you must specify the RANGLIST parameter. The NUMRANGE parameter is optional.
When you issue the IARSUBSP macro with CREATE, the NAME and STOKEN parameters are required. The GENNAME and OUTNAME parameters are optional.
When you issue the IARSUBSP macro with ASSIGN, you must specify the STOKEN and RANGLIST parameters. The NUMRANGE parameter is optional.
When you issue the IARSUBSP macro with UNASSIGN, you must specify the STOKEN and RANGLIST parameters. The NUMRANGE parameter is optional.
When you issue the IARSUBSP macro with DELETE, you must specify the STOKEN parameter. Do not code any other parameters.
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.
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.
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 |
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 is an optional parameter when you specify the IDENTIFY, UNIDENTIFY, ASSIGN, or UNASSIGN parameters.
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.
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.
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.
Hexadecimal Return Code | Hexadecimal Reason Code | Meaning and Action |
---|---|---|
00 | None | Meaning: The IARSUBSP request completed
successfully. Action: None required. |
04 | xx0115xx | Meaning: IARSUBSP IDENTIFY completed successfully,
but some ranges of storage had already been identified. Action: None required. However, you might want to take some action based on your application. |
04 | xx0315xx | Meaning: IARSUBSP ASSIGN completed successfully,
but some of the storage specified on the RANGLIST parameter already
had been assigned to the subspace indicated by the STOKEN parameter. Action: None required. However, you might want to take some action based on your application. |
04 | xx0415xx | Meaning: IARSUBSP UNASSIGN completed successfully,
but one of the following conditions is true for some of the storage
specified on the RANGLIST parameter:
Action: None required. However, you might want to take some action based on your application. |
04 | xx0615xx | Meaning: IARSUBSP UNIDENTIFY completed
successfully, but one of the following conditions is true for some
of the storage specified on the RANGLIST parameter:
Action: None required. However, you might want to take some action based on your application. |
08 | xx0212xx | Meaning: Environmental error. IARSUBSP
CREATE failed. The system's set of generated names for subspaces
has been temporarily exhausted. Action: Reissue IARSUBSP CREATE, specifying a unique name on the NAME parameter and GENNAME=NO. Or, issue IARSUBSP UNASSIGN and IARSUBSP DELETE for any subspaces that are no longer required, and reissue the CREATE request. |
08 | xx0213xx | Meaning: Program error. IARSUBSP CREATE
failed. The name specified on the NAME parameter is not unique within
the address space. Action: Change the name specified on the NAME parameter to a unique name, or specify GENNAME=COND or GENNAME=YES, and reissue the request. |
08 | xxFF00xx | Meaning: Environmental error. IARSUBSP
failed. The system does not support subspaces. Action: Contact your system programmer to determine if the subspace group facility can be made available. |
0C | xx0114xx | Meaning: Environmental error. IARSUBSP
IDENTIFY failed. The system cannot perform any subspace services
because of a shortage of resources. Action: Reissue the request. If the problem persists, contact your system programmer. |
0C | xx0214xx | Meaning: Environmental error. IARSUBSP
CREATE failed. The system cannot perform any subspace services because
of a shortage of resources. Action: Reissue the request. If the problem persists, contact your system programmer. |
0C | xx0314xx | Meaning: Environmental error. IARSUBSP
ASSIGN failed. The system cannot perform any subspace services because
of a shortage of resources. Action: Reissue the request. If the problem persists, contact your system programmer. |
0C | xx0411xx | Meaning: System error. IARSUBSP UNASSIGN
failed. One or more pages of storage were not processed. Action: Reissue the request. If the problem persists, record the return and reason codes and supply them to the appropriate IBM® support personnel. |
For a complete example of creating, managing, and deleting subspaces, see the chapter on subspaces in z/OS MVS Programming: Extended Addressability Guide.