Description
The ALESERV macro manages the contents of access lists. An access list is a table in which each entry identifies an address space, a data space, a subspace, or a hiperspace to which programs have access. Access list entry tokens (ALETs) index the entries in the access list.
On the ALESERV macro, address spaces, data spaces, subspaces, and hiperspaces are identified through STOKENs, an identifier similar to an address space identifier (ASID). z/OS MVS Programming: Extended Addressability Guide describes STOKENs, ALETs and how to pass them, access lists, and the EAX-checking that might occur when you issue the ALESERV macro to add an entry for an address space.
You access data spaces and address spaces, and reference subspaces, through assembler instructions. You access hiperspace through the HSPSERV macro.
- Add an entry to a DU-AL or PASN-AL for a SCOPE=SINGLE data space, a SCOPE=ALL data space, or a hiperspace (ADD parameter)
- Add an entry to a DU-AL for a subspace (ADD parameter)
- Add an entry to all PASN-ALs for a SCOPE=COMMON data space (ADD parameter)
- Add the primary address space to the DU-AL (ADDPASN parameter)
- Delete an entry from a DU-AL or PASN-AL (DELETE parameter)
- Obtain a STOKEN for a specified ALET (EXTRACT parameter)
- Locate an ALET for a specified STOKEN (SEARCH parameter)
- Obtain the STOKEN of the home address space (EXTRACTH parameter).
ALESERV is also described in z/OS MVS Programming: Assembler Services Reference ABE-HSP, except for the CHKEAX parameter.
Environment
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Problem state, with any PSW key. To request the following
ALESERV services, the program must be supervisor state or PSW key 0 - 7:
|
Dispatchable unit mode: | Task or SRB |
Cross memory mode: | Any PASN, any HASN, any SASN |
AMODE: | 24- or 31- bit |
ASC mode: | Primary or access register (AR) |
Interrupt status: | Enabled for I/O and external interrupts for ADD, ADDPASN, and DELETE requests. Enabled or disabled for I/O and external interrupts for requests other than ADD, ADDPASN, and DELETE |
Locks: | No locks held for ADD, ADDPASN, and DELETE requests. For requests other than ADD, ADDPASN, and DELETE, the caller is not required to hold locks. |
Control parameters: | Must exist in an addressable area |
Programming requirements
To add a subspace entry to a DU-AL, the caller must be running under the task that created the subspace.
Restrictions
None.
Input register information
Before issuing the ALESERV macro, the caller does not have to place information into any register unless they use it in register notation for a particular parameter, or use it as a base register.
Output register information
- Register
- Contents
- 0
- Reason code associated with the return code for SEARCH and EXTRACT requests; otherwise, used as a work register by the system.
- 1
- Address of the ALESERV parameter list.
- 2-13
- Unchanged
- 14
- Used as a work register by the system.
- 15
- Return code.
- Register
- Contents
- 0
- Used as a work register by the system.
- 1
- ALET for the parameter list.
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system.
Some callers depend on register contents to remain the same before and after they issue a service. If the system changes the contents of registers on which the caller depends, the caller must save them before they issue the service, and restore them after the system returns control.
Performance implications
None.
Syntax
The standard form of the ALESERV macro is written as follows:
Syntax | Description |
---|---|
name | name: Symbol. Begin name in column 1. |
␢ | One or more blanks must precede ALESERV. |
ALESERV | |
␢ | One or more blanks must follow ALESERV. |
Valid parameters (required parameters are underlined): | |
ADD | AL, STOKEN, ACCESS, ALET, CHKEAX, CHKPT, RELATED |
ADDPASN | ALET, CHKPT, RELATED |
DELETE | ALET, CHKEAX, RELATED |
EXTRACT | ALET, STOKEN, RELATED |
SEARCH | AL, ALET, STOKEN, RELATED |
EXTRACTH | STOKEN, RELATED |
,ACCESS=PUBLIC | Default: ACCESS=PUBLIC |
,ACCESS=PRIVATE | |
,AL=WORKUNIT | Default: AL=WORKUNIT |
,AL=PASN | |
,ALET=alet-addr | alet-addr: RX-type address
or register (2) - (12). Note: If you specify register notation, the
register contains the ALET, rather than the address of the ALET.
|
,STOKEN=stoken-addr | stoken-addr: RX-type address. |
,CHKEAX=YES | Default: CHKEAX=YES. |
,CHKEAX=NO | |
,CHKPT=FAIL | Default: CHKPT=FAIL |
,CHKPT=IGNORE | |
,RELATED=any-value | any-value: Any valid macro parameter specification. |
Parameters
The parameters are explained as follows:
- ADD
- Requests that the system add an entry to the access list and return the ALET. You are required
to use two parameters:
- STOKEN specifies the space for which the entry is to be added
- ALET specifies the address of the location where the system returns the ALET.
You can also specify whether the access list is DU-AL or PASN-AL (AL parameter), for address spaces, whether the entry is PUBLIC or PRIVATE (ACCESS parameter). The defaults are DU-AL and PUBLIC.
A subspace access list entry must be added to the DU-AL as a public entry.
To add an entry for a SCOPE=COMMON data space to all PASN-ALs in the system, use the AL=PASN parameter on ALESERV ADD.
To add an entry for an address space, the problem state, PSW key 8 - F caller must have EAX-authority to the target address space. The supervisor state or PSW key 0 - 7 caller can use the CHKEAX=NO parameter, which adds an entry for the address space without requiring the caller to have EAX-authority.
To ensure the integrity of data spaces and hiperspace, the system has certain rules for adding entries for data spaces and hiperspace to access lists. The following two tables summarize the rules for problem state programs with PSW key 8 - F and supervisor state or PSW key 0 - 7 programs.
Table 1. Rules for Adding Entries for Data Spaces to Access Lists Function Type of data space A problem state program with PSW key 8 - F: A supervisor state or key 0-7 program: Add entries to the DU-AL SCOPE=SINGLE Can add entries for the data spaces it owns or creates. Can add entries if the caller's home and owner's home address space is the same. Add entries to the DU-AL SCOPE=ALL and
SCOPE=COMMONCannot add entries. Can add entries. Add entries to the PASN-AL SCOPE=SINGLE Can add entries if the caller owns or creates the data space and the data space is not already on the PASN-AL through the actions of a problem state program with PSW key 8 - F. Can add entries if PASN-AL is the same as the PASN-AL of the owner's home address space. Add entries to the PASN-AL SCOPE=ALL and
SCOPE=COMMONCannot add entries. Can add entries for SCOPE=COMMON data spaces. Can add entries for SCOPE=ALL data spaces if no unauthorized program can run in the primary address space. Table 2. Rules for Adding Entries for Hiperspace to Access Lists Function Type of hiperspace A problem state program with PSW key 8 - F: A supervisor state or key 0-7 program: Add entries to the DU-AL Nonshared standard Can add entries for the hiperspaces it owns. Can add entries if the caller's home and owner's home address space is the same. Add entries to the DU-AL Shared standard
and ESOCannot add entries. Can add entries. Add entries to the PASN-AL Nonshared standard Cannot add entries. Can add entries if PASN-AL is the same as the PASN-AL of the owner's home address space. Add entries to the PASN-AL Shared standard
and ESOCannot add entries. Can add entries for shared standard hiperspace. Can add entries for ESO hiperspace if no unauthorized program can run in the primary address space. An access list entry for an ESO hiperspace might not be available to an unauthorized program.
The following notes are for users of data-in-virtual and hiperspaces.- Once you add an entry for a standard hiperspace, you cannot use that hiperspace as a data-in-virtual object
- If a DIV ACCESS is in effect for a standard hiperspace, you cannot add an entry for that hiperspace.
- ADDPASN
- Requests that the system add the primary address space to the DU-AL without requiring a user to have EAX-authority to the address space. The entry is a public entry. ALET, required with ADDPASN, receives the ALET that identifies the entry.
- DELETE
- Requests that the system delete an entry from the DU-AL or the
PASN-AL. ALET, required with DELETE, identifies the entry to be deleted.
To delete an entry for an address space, the problem state program with PSW key 8 - F must have EAX-authority to the target address space. The supervisor state or PSW key 0 - 7 caller can use the CHKEAX=NO parameter, which deletes an entry for the address space without requiring the caller to have EAX-authority.
When the request is for a SCOPE=COMMON data space, ALESERV deletes the entry from all PASN-ALs in the system.
- EXTRACT
- Requests that the system find the STOKEN associated with the specified ALET. The caller can obtain the STOKEN for any space that is represented by a valid entry on the current access list. STOKEN is a required parameter.
- SEARCH
- Requests that the system search through the DU-AL or PASN-AL for an ALET that corresponds to a specified STOKEN. Specify whether the search is to be through the DU-AL or the PASN-AL. (AL=WORKUNIT is the default.) ALET and STOKEN are required parameters.
- EXTRACTH
- Requests that the system find the STOKEN of the home address space. STOKEN is a required parameter.
- ,ACCESS=PUBLIC
- ,ACCESS=PRIVATE
- Specifies whether the access list entry you are adding is PUBLIC or PRIVATE. You cannot add a PRIVATE entry for a data space, subspace, or hiperspace. The default is ACCESS=PUBLIC.
- ,AL=WORKUNIT
- ,AL=PASN
- Specifies whether the access list is a DU-AL (WORKUNIT) or a PASN-AL (PASN). The default is
AL=WORKUNIT.
For the ADD request, AL identifies the type of access list. To add entries for data spaces and hiperspace to the DU-AL and PASN-AL, see the rules described in Table 1 and Table 2.
For the SEARCH request, AL specifies whether the system is to search through the DU-AL or the PASN-AL.
When you add or search for a subspace access list entry, you must specify AL=WORKUNIT.
- ,ALET=alet-addr
- Specifies the 4-byte ALET that either you provide or the system
returns, depending on the other parameters you specify on ALESERV.
When you use RX-type notation, alet-addr specifies
the address of the 4-byte field that contains the ALET. When you
use register notation, alet-addr specifies a register
that contains the ALET itself, rather than the address of the ALET.
For the ADD and ADDPASN requests, the system returns the ALET of the added entry.
For the DELETE request, you provide the ALET for the access list entry to be deleted. Do not specify an ALET of 0, 1, or 2.
For the EXTRACT request, you provide the ALET whose STOKEN you require. The system returns the STOKEN in stoken-addr. When you specify ALET 0, the system returns the caller's primary address space STOKEN. Do not specify ALET 1 on an EXTRACT request.
For the SEARCH request, you specify where in the access list the system is to begin the search:- If you specify minus one (-1), the system starts searching at the beginning of the DU-AL or PASN-AL.
- If you specify a valid ALET, the system starts searching with the next ALET in the access list.
- ,STOKEN=stoken-addr
- Specifies an 8-byte identifier of an address space, data space,
subspace, or hiperspace. For ADD processing, STOKEN identifies the
space that the program wants to access.
For the EXTRACT request, the system returns the STOKEN that corresponds to the specified ALET.
For the SEARCH request, STOKEN identifies the STOKEN for which the system is to return the corresponding ALET.
For the EXTRACTH request, the system returns the STOKEN of the home address space.
- ,CHKEAX=YES
- ,CHKEAX=NO
- Specifies that ALESERV does (CHKEAX=YES) or does not (CHKEAX=NO) check the EAX authority of the caller to the address space to be added to or deleted from the access list. The default is CHKEAX=YES.
- ,CHKPT=FAIL
- ,CHKPT=IGNORE
- Specifies how the system is to process a checkpoint request made through the CHKPT macro,
relevant to the access list entry being added. If you specify CHKPT=IGNORE, the system ignores the
access list entry added (DU-AL or PASN-AL) and processes the checkpoint operation. If you specify
CHKPT=FAIL, the system rejects the checkpoint operation. The default is CHKPT=FAIL. Note: This keyword does not apply to an access list entry being added for a SCOPE=COMMON data space. Access list entries for SCOPE=COMMON data spaces are always ignored by the system on a checkpoint request.
If you specify CHKPT=IGNORE, you assume full responsibility of managing the data space, subspace, or hiperspace storage. For more information, z/OS MVS Programming: Extended Addressability Guide.
- ,RELATED=any-value
- Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information which is specified are at the discretion of the user, and can be any valid coding values.
ABEND codes
None.
Return codes
When control is returned from ALESERV ADD, register 15 contains one of the following hexadecimal return codes. A return code of 8 or more means the system rejects the request.
Hexadecimal Return Code | Meaning and Action |
---|---|
00 | Meaning: ALESERV ADD complete successfully. Action: None. |
08 | Meaning: Program error. The caller is not
EAX-authorized to the specified space; the entry is not added. The
ALET returned is incorrect. Action: Verify that the intended STOKEN is specified. |
0C | Meaning: Environmental error. The current access list cannot be expanded.
There are no free access list entries and the maximum size is reached.
Action: Delete unused entries and reissue the request. |
10 | Meaning: Environmental error. ALESERV might not obtain storage for an
expanded access list. Action: Retry the request. |
18 | Meaning: Program error. A problem-state
caller with PSW key 8 - F tried to add an entry to the PASN-AL for
a space other than a SCOPE=SINGLE data space. Action: Change the request to add the data space as SCOPE=SINGLE or change your program to run in supervisor state or key 0-7. |
1C | Meaning: Program error. The caller is
holding a lock. Action: Release all locks before calling ALESERV. |
20 | Meaning: Program error. The caller is inactive. Action: Enable your program before it issues ALESERV. |
24 | Meaning: Program error. AR 1 contained
an ALET of 1 on input or contained an ALET for the PASN-AL. Action: Verify that AR 1 contains either an ALET of 0 or the ALET for the caller's DU-AL. |
38 | Meaning: Program error. The input STOKEN
is not valid. Action: Verify that the specified STOKEN is a valid STOKEN. |
4C | Meaning: Program or environmental error. The space which is represented
by the input STOKEN is not valid for cross memory access. Action: None required. However, you might want to take action based on your application. |
50 | Meaning: Program error. The ALESERV parameter list is not valid.
Action: Verify that your program is not overwriting the parameter list and the execute form of the macro correctly addresses the parameter list. |
54 | Meaning: Program error. The caller tried
to add a data space, hiperspace, or subspace to an access list as
a private entry. Action: Specify ACCESS=PUBLIC instead of ACCESS=PRIVATE. |
5C | Meaning: Program error. The caller was
not authorized to add a data space or a hiperspace to an access list. Action: Correct your program to specify STOKENs for spaces for which your program is authorized. |
60 | Meaning: System error. An unexpected error
occurred. The request was not completed. Action: Retry the request. |
62 | Meaning: Program error. A previous error in your program left the access
list in an unexpected format. The error occurs because the SRB environment
was not valid when the system dispatched an SRB. The system did not perform
the ALESERV ADD request. Action: Determine the cause of the error that preceded the ALESERV ADD request. Correct the error and rerun the program. |
64 | Meaning: Program error. A problem-state
caller with PSW key 8 - F tried to add an entry using CHKEAX=NO. Action: Specify CHKEAX=YES. |
68 | Meaning: Program error. The caller attempted to add a hiperspace under
conditions, which are not allowed. See Table 2 for a
summary of the rules for adding hiperspaces to an access list.
Action: Verify that the options which are specified on your ADD request do not violate the rules specified in Table 2. |
6C | Meaning: Program error. The caller tried
to add an entry for a SCOPE=COMMON data space to a DU-AL. Action: Change your program to request the ADD to be made to the PASN-AL. |
70 | Meaning: Environmental error. Action: Modify your program to use the HSPSERV macro to access the data in the hiperspace. |
74 | Meaning: Program error. A problem-state
program with PSW key 8 - F has already added an entry for the data
space to the PASN-AL. Action: Change your program's logic so that it does not request the second ADD. |
78 | Meaning: Program error. A problem-state program with PSW key 8 - F tried
to add an entry to the PASN-AL. The caller is not the owner or the creator
of the data space. Action: Change your program's logic so that it does not add a data space it did not create or does not own. |
80 | Meaning: Program error. The caller attempted
to add a subspace access list entry to the PASN-AL. Action: Change the request to add the subspace access list entry to the DU-AL. |
84 | Meaning: Program error. The caller tried
to add a subspace access list entry to the DU-AL, but the caller is
not running under the task that owns the subspace. Action: Ensure that your program is running under the task that created the subspace, or check that you are supplying the correct STOKEN. |
When control is returned from ALESERV ADDPASN, register 15 contains one of the following hexadecimal return codes.
Hexadecimal Return Code | Meaning and Action |
---|---|
00 | Meaning: ALESERV ADDPASN completes successfully. Action: None. |
0C | Meaning: Environmental error. The current access list cannot be expanded.
There are no free ALEs and the maximum size is reached. Action: Delete unused entries and reissue the request. |
10 | Meaning: Environmental error. ALESERV might not obtain storage for an
expanded access list. Action: Retry the request. |
1C | Meaning: Program error. The caller is holding
a lock. Action: Release all locks before calling ALESERV. |
20 | Meaning: Program error. The caller is disabled. Action: Enable your program before it issues ALESERV. |
24 | Meaning: Program error. AR 1 contained
an ALET of 1 on input or contained an ALET for a PASN-AL. Action: Verify that AR 1 contains either an ALET of 0 or the ALET for the caller's DU-AL. |
50 | Meaning: Program error. The ALESERV parameter
list is not valid. Action: Verify that your program is not overwriting the parameter list and that the execute form of the macro correctly addresses the parameter list. |
60 | Meaning: System error. An unexpected error
occurred. The request was not completed. Action: Retry the request. |
62 | Meaning: Program error. A previous error in your program left the access
list in an unexpected format. The error occurs because the SRB environment
was not valid when the system dispatched an SRB. The system did not perform
the ALESERV ADDPASN request. Action: Determine the cause of the error that preceded the ALESERV ADD request. Correct the error and rerun the program. |
When control is returned from ALESERV DELETE, register 15 contains one of the following hexadecimal return codes.
Hexadecimal Return Code | Meaning and Action |
---|---|
00 | Meaning: ALESERV DELETE completes successfully. Action: None. |
08 | Meaning: Program error. The caller is not
EAX-authorized to the address space specified by the ALET. The entry
is not deleted. Action: Verify that the intended STOKEN is specified. |
14 | Meaning: Program or environmental error.
The input ALET corresponds to an access list entry that is not valid. Action: Verify that the specified ALET is valid. |
1C | Meaning: Program error. The caller is holding
a lock. Action: Release all locks before calling ALESERV. |
20 | Meaning: Program error. The caller is disabled. Action: Enable your program before it issues ALESERV. |
24 | Meaning: Program error. AR 1 contained
an ALET of 1 on input or an ALET for the caller's PASN-AL. Action: Verify that AR 1 contains either an ALET of 0 or the ALET for the caller's DU-AL. |
28 | Meaning: Program error. The caller specified
an ALET that is not valid. Action: Verify that the input ALET is valid. |
2C | Meaning: Program error. The caller attempted to delete ALET 0, 1, or 2.
Action: Verify that the specified ALET is not ALET 0, 1, or 2. |
30 | Meaning: Program error. A problem-state
caller with PSW key 8 - F attempted to delete an entry from the PASN-AL
for a space other than a SCOPE=SINGLE data space. Action: Verify that the ALET supplied represents the intended space. |
60 | Meaning: System error. An unexpected error
occurred. The request was not completed. Action: Retry the request. |
64 | Meaning: Program error. A problem-state caller with PSW key 8 - F tried
to delete an entry with CHKEAX=NO. Action: Specify CHKEAX=YES. |
78 | Meaning: Program error. A problem-state caller with PSW key 8 - F tried
to delete an entry from the PASN-AL. The caller is not the creator or the
owner of the data space, or the PSW key of the caller did not match the
storage key of the data space. Action: Change your program's logic so that it does not have to try to delete a data space it did not create or own. |
When control is returned from ALESERV EXTRACT, register 15 contains one of the following hexadecimal return codes.
Hexadecimal Return Code | Meaning and Action |
---|---|
00 | Meaning: ALESERV EXTRACT completes successfully. Register 0 contains one
of the following hexadecimal reason codes:
Action: None. |
14 | Meaning: Program or environmental error.
The input ALET corresponds to an access list entry that is not valid. Action: Verify that the specified ALET is valid. |
24 | Meaning: Program error. AR 1 contained
an ALET of 1 on input or contains an ALET for the caller's PASN-AL. Action: Verify that AR 1 contains either an ALET of 0 or the ALET for the caller's DU-AL. |
28 | Meaning: Program error. The caller specified
an ALET that is not valid. Action: Verify that the input ALET is valid. |
3C | Meaning: Program error. The caller specified
an ALET value of 1. Action: Verify that the specified ALET is other than 1. |
40 | Meaning: Program or environmental error. The space which is associated
with the input ALET is not valid for cross memory access. Action: None required. However, you might want to take action based on your application. |
44 | Meaning: Environmental error. The ALE associated with the input ALET
represents addressing capability to a deleted or terminated space.
Action: None required. However, you might want to discard the specified ALET and possibly take action based on your application. |
50 | Meaning: Program error. The ALESERV parameter
list is not valid. Action: Verify that your program is not overwriting the parameter list and that the execute form of the macro correctly addresses the parameter list. |
58 | Meaning: Program and environmental error. The ALET the caller which is
specified represents an STOKEN for a data space that is no longer
accessible. Action: None required. However, you might want to discard the specified ALET and possibly take action based on your application. |
60 | Meaning: System error. An unexpected error
occurred. The request was not completed. Action: Retry the request. |
When control is returned from ALESERV SEARCH, register 15 contains one of the following hexadecimal return codes.
Hexadecimal Return Code | Meaning and Action |
---|---|
00 | Meaning: ALESERV SEARCH completes successfully. Register 0 contains one
of the following hexadecimal reason codes:
Action: None. |
24 | Meaning: Program error. AR 1 contained
an ALET of 1 on input or an ALET for the caller's PASN-AL. Action: Verify that AR 1 contains either an ALET of 0 or the ALET for the caller's DU-AL. |
28 | Meaning: Program error. The caller specified
an ALET that is not valid. Action: Verify that the input ALET is valid. |
34 | Meaning: Program error. The caller specified
an STOKEN not represented on the specified access list. Action: Verify that the specified STOKEN is on the referenced access list. |
48 | Meaning: Program error. The caller specified
AL=WORKUNIT but the input ALET indexes into the PASN-AL, or the caller
specified AL=PASN and the ALET indexes into the DU-AL. Action: Change the AL or the ALET parameters to specify the correct AL and ALET combination. |
60 | Meaning: System error. An unexpected error
occurred. The request was not completed. Action: Retry the request. |
When control is returned from ALESERV EXTRACTH, register 15 contains one of the following hexadecimal return codes.
Hexadecimal Return Code | Meaning and Action |
---|---|
00 | Meaning: ALESERV EXTRACTH completes successfully. Action: None. |
24 | Meaning: Program error. AR 1 contained
an ALET of 1 on input or contains an ALET associated with the caller's
PASN-AL. Action: Verify that AR 1 contains either an ALET of 0 or the ALET for the caller's DU-AL. |
60 | Meaning: System error. An unexpected error
occurred. The request was not completed. Action: Retry the request. |
Example
ALESERV ADD,STOKEN=DSPCSTKN,ALET=DSPCALET
*
DSPCSTKN DS CL8 DATA SPACE STOKEN
DSPCALET DS F DATA SPACE ALET