 |
The ALESERV macro manages the contents of access lists. An access
list is a table in which each entry identifies an address space, data
space, or hiperspace to which a program (or programs) has access.
Access list entry tokens (ALETs) index the entries in the access
list. Use the ALESERV macro to: - Add an entry to a DU-AL for an address space, data space, or nonshared
standard hiperspace (ADD parameter)
- Add an entry for the primary address space to the DU-AL (ADDPASN
parameter)
- Add an entry for a SCOPE=SINGLE data space to the PASN-AL.
- Delete an entry from a DU-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).
A problem state program can use ALESERV to create an entry associated
with an address space only if it is running with an appropriate extended
authorization index (EAX) value. To set up EAX-authorization, a program
must be in supervisor state. Information on EAX-authorization appears
in the books that are available to system programmers who write programs
in supervisor state.
On the ALESERV macro, address spaces, data spaces, and hiperspaces
are identified through STOKENs, an identifier similar to an address
space identifier (ASID).
For information about access lists, ALETs, data spaces, and hiperspaces,
see appropriate chapters in z/OS MVS Programming: Assembler Services Guide.
That book contains many examples of using ALESERV.
Environment
The requirements for the caller are:
| Environmental factor |
Requirement |
|---|
| Minimum authorization: |
Problem state with any PSW key. |
| 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 may hold
locks, but is not required to hold any. |
| Control parameters: |
Can reside in any addressable area |
Programming requirements
For ADD and DELETE requests, the caller of the ALESERV macro must
be one of the following: - The owner or creator of the data space
- The owner of the hiperspace.
Input register information
Before issuing the ALESERV 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.
Output register information
When control returns to the caller, the general purpose registers
contain: - 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
When control returns to the caller, the access registers contain: - 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 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.
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, CHKPT,
RELATED |
| ADDPASN |
ALET, CHKPT, RELATED |
| DELETE |
ALET, RELATED |
| EXTRACT |
ALET, STOKEN, RELATED |
| SEARCH |
ALET, STOKEN, AL, 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. |
| |
|
| |
|
| ,CHKPT=FAIL |
Default: CHKPT=FAIL |
| ,CHKPT=IGNORE |
|
| |
|
| ,RELATED=any-value |
|
| |
|
Parameters
The parameters are explained as follows:
- ADD
- Requests that the system add an entry to the access list. You
are required to use two parameters:
- STOKEN specifies the address space, data space, or hiperspace
that the entry represents
- ALET specifies the address of the location where the system returns
the ALET.
For access list entries that represent an address space,
you can also specify whether an entry is public or private (ACCESS
parameter). To add an entry for an address space, the caller must
have EAX-authority to the target address space.
For access
list entries that represent a data space or hiperspace, the entry
must be public.
A problem state program can add an entry for
a SCOPE=SINGLE data space to the PASN-AL if both of the following
are true: - The caller owns or created the data space.
- An entry for the data space is not already on the PASN-AL through
the action of another problem state program.
- ADDPASN
- Requests that the system add an entry for the primary address
space to the DU-AL without requiring a user to have EAX-authority
to the address space. ALET, required with ADDPASN, receives the ALET
that indexes into the entry. The entry is a public entry.
- DELETE
- Requests that the system delete an entry from the DU-AL. ALET,
required with DELETE, identifies the entry to be deleted.
- EXTRACT
- Requests that the system find the STOKEN of the specified ALET.
The caller can obtain the STOKEN for any address space, data space,
or hiperspace that is represented by a valid entry on the DU-AL or
PASN-AL. ALET and STOKEN are required parameters.
- SEARCH
- Requests that the system search through the DU-AL or PASN-AL for
an ALET that corresponds to a specified STOKEN. ALET and STOKEN are
required parameters. AL is an optional parameter; AL=DU-AL is the
default.
- 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 or hiperspace.
- ,AL=WORKUNIT
- ,AL=PASN
- Specifies whether the access list is a DU-AL (WORKUNIT) or a PASN-AL
(PASN). For the ADD request, AL identifies the type of access list.
For
the SEARCH request, AL specifies whether the system is to search through
the DU-AL or the PASN-AL.
- ,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.
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.
The system then returns the searched-for ALET, if present.
Otherwise, alet-addr is unchanged and register
15 contains a return code that specifies that an ALET for the STOKEN
is not on the access list.
- ,STOKEN=stoken-addr
- Specifies the 8-byte identifier of an address space, data space,
or hiperspace. For the ADD request, 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.
- ,CHKPT=FAIL
- ,CHKPT=IGNORE
- Specifies how the system is to process a checkpoint request made
through the CHKPT macro, in relation 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.
If you specify CHKPT=IGNORE, you assume
full responsibility of managing the data space or nonshared standard
hiperspace storage. See z/OS MVS Programming: Assembler Services Guide for
more information on using checkpoints with data spaces and hiperspaces.
- ,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 specified are at the discretion
of the user, and may be any valid coding values.
Return and reason codes
When control is returned from ALESERV ADD, register 15 contains
one of the following hexadecimal return codes. A return code of 8
or greater means the system rejects the request.
| Hexadecimal Return Code |
Meaning and Action |
|---|
| 0 |
Meaning: ALESERV ADD has completed successfully. Action:
None.
|
| 8 |
Meaning: Program error. The caller was
not EAX-authorized to the specified space. The entry is not added. 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 has been reached. Action: Delete unused
entries and reissue the request.
|
| 10 |
Meaning: Environmental error. ALESERV could
not obtain storage for an expanded access list. Action:
Retry the request.
|
| 18 |
Meaning: Program error. The caller in problem
state 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 disabled. Action:
Enable your program before it issues ALESERV.
|
| 24 |
Meaning: Program error. AR 1 contained
an ALET of 1 on input, or a PASN-AL ALET. 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 represented by the input STOKEN is not valid for cross memory
access. Action: None required. However, you may want to
take some action based upon 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.
|
| 54 |
Meaning: Program error. The caller tried
to add a data space or hiperspace to an access list as a private entry. Action:
Specify ACCESS=PUBLIC instead of ACCESS=PRIVATE.
|
| 5C |
Meaning: Program error. The caller tried
to add a data space or a hiperspace to an access list without proper
authority. 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 might have occurred 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 that is not a nonshared standard hiperspace owned
by the caller. Action: Verify that the options specified
on your ADD request do not violate the rules for adding entries for
hiperspaces to access lists.
|
| 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. The caller
attempted to add a hiperspace to an access list. 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 and the entry still exists. 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 program is neither the owner nor 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 |
|---|
| 0 |
Meaning: ALESERV ADDPASN has completed
successfully. Action: None.
|
| C |
Meaning: Environmental error. The DU-AL
cannot be expanded. There are no free ALEs, and the maximum size has
been reached. Action: Delete unused entries and reissue
the request.
|
| 10 |
Meaning: Environmental error. ALESERV could
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: Environmental error. AR 1 contained
an ALET of 1 on input, or a PASN-AL ALET. 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 might have occurred 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 |
|---|
| 0 |
Meaning: ALESERV DELETE has completed successfully. Action:
None.
|
| 8 |
Meaning: Program error. The caller is not
EAX-authorized to the address space specified by the ALET, or the
space specified by the ALET is not the primary address space. 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 ALE 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 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.
|
| 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 tried to delete an entry for a space other
than a SCOPE=SINGLE data space. Action: Verify that the
ALET supplied represents the intended space.
|
| 40 |
Meaning: Program or environmental error.
The space associated with the input ALET is not valid for cross memory
access. Action: None required. However, you may want to
take some action based upon 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
may want to discard the specified ALET and possibly take some action
based upon your application.
|
| 60 |
Meaning: System error. An unexpected error
occurred. The request was not completed. Action: Retry the
request.
|
| 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 neither the owner nor the creator 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 |
|---|
| 0 |
Meaning: ALESERV EXTRACT completed successfully.
Register 0 contains one of the following reason codes: - 00 - The access list entry is a public entry.
- 04 - The access list entry is a private entry.
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 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.
|
| 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 associated with the input ALET is not valid for cross memory
access. Action: None required. However, you may want to
take some action based upon your application.
|
| 44 |
Meaning: Environmental error. The access
list entry (ALE) associated with the input ALET represents addressing
capability to a deleted or terminated space. Action: None
required. However, you may want to discard the specified ALET and
possibly take some action based upon 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 or environmental error.
The ALET the caller specified represents an STOKEN for a data space
that is no longer accessible. Action: None required. However,
you may want to discard the specified ALET and possibly take some
action based upon 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 |
|---|
| 0 |
Meaning: ALESERV SEARCH completed successfully.
Register 0 contains one of the following hexadecimal reason codes: - 00 - The access list entry is a public entry.
- 04 - The access list entry is a private entry.
Action: None.
|
| 24 |
Meaning: Program error. AR 1 contained
an ALET of 1 on input or 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.
|
| 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 that is 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 but 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 |
|---|
| 0 |
Meaning: ALESERV EXTRACTH has completed
successfully. Action: None.
|
| 24 |
Meaning: Program error. AR 1 contained
an ALET of 1 on input, or 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 of adding an entry to a DU-AL
To add an entry to a DU-AL for a data space, issue the following: ALESERV ADD,STOKEN=DSPCSTKN,ALET=DSPCALET
*
DSPCSTKN DS CL8 DATA SPACE STOKEN
DSPCALET DS F DATA SPACE ALET
|
z/OS MVS Programming: Assembler Services Reference ABE-HSP
Copyright IBM Corporation 1990, 2014