The CSVAPF macro allows you to determine the format and contents
of the APF-authorized library list. You can issue CSVAPF to: - Determine whether or not a library is in the APF list
- Determine the current format (dynamic or static) of the APF list
- Obtain a list of all library entries in the APF list.
You can issue CSVAPF to perform any of the listed functions on
either a dynamic or static APF list.
Environment
The requirements for the caller are:
Environmental factor |
Requirement |
---|
Minimum authorization: |
Problem state and any PSW key. |
Dispatchable unit mode: |
Task |
Cross memory mode: |
Any PASN, any HASN, any SASN |
AMODE: |
For a QUERY or QUERYFORMAT request, 31-bit. For
a LIST request, 24- or 31-bit. |
ASC mode: |
For a QUERY request, primary. For all other requests,
primary or access register (AR). |
Interrupt status: |
Enabled for I/O and external interrupts |
Locks: |
No locks held |
Control parameters: |
Control parameters must be in the primary address
space or, for AR-mode callers, must be in an address/data space that
is addressable through a public entry on the caller's dispatchable
unit access list (DU-AL). |
Programming requirements
If you code the LIST option on the REQUEST parameter, you must
include the CSVAPFAA mapping macro (see z/OS MVS Data Areas in
z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.
For all other requests, you can optionally include the CSVAPFAA mapping
macro to define variables and values for: - Return and reason codes returned by CSVAPF
- The APF list format, which is returned by CSVAPF when you specify
REQUEST=QUERYFORMAT.
Input register information
Before issuing the CSVAPF macro, the caller must ensure that the
following general purpose registers (GPRs) contain the specified information: - Register
- Contents
- 13
- For a QUERY request, the address of a standard 72-byte save area
Output register information
When control returns to the caller, the GPRs contain: - Register
- Contents
- 0
- If REQUEST=QUERYFORMAT is not specified, and the value in register
15 is not 0, reason code; otherwise, used as a work register by the
system
- 1
- Used as a work register by the system
- 2-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- For a QUERYFORMAT request, used as a work register by the system;
for all other requests, return code
When control returns to the caller, the access registers (ARs)
contain: - Register
- Contents
- 0-1
- Used as a work register by the system
- 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 CSVAPF macro is written as follows:
Syntax |
Description |
---|
|
|
name |
name: symbol. Begin name in
column 1. |
|
|
␢ |
One or more blanks must precede CSVAPF. |
|
|
CSVAPF |
|
|
|
␢ |
One or more blanks must follow CSVAPF. |
|
|
|
Valid parameters (Required parameters are underlined): |
REQUEST=QUERY |
DSNAME, VOLTYPE, VOLUME, RETCODE, RSNCODE |
REQUEST=QUERYFORMAT |
FORMAT |
REQUEST=LIST |
ANSAREA, ANSLEN, RETCODE, RSNCODE |
|
|
,DSNAME=libname |
libname: RS-type address or
address in register (2) - (12). |
|
|
,VOLTYPE=SMS |
Default: VOLTYPE=SMS |
,VOLTYPE=ANY, |
VOLUME is required with VOLTYPE=ANY. |
VOLUME=volume |
volume: RS-type or address
in register (2) - (12). |
|
|
,FORMAT=format |
format: RS-type address or
address in register (2) - (12). |
|
|
,ANSAREA=ansarea |
ansarea: RS-type address or
address in register (2) - (12). |
|
|
,ANSLEN=anslen |
anslen: RS-type address or
address in register (2) - (12). |
|
|
,RETCODE=retcode |
retcode: RS-type address or
register (2) - (12). |
|
|
,RSNCODE=rsncode |
rsncode: RS-type address or
register (2) - (12). |
|
|
,MF=S |
|
|
|
Parameters
The parameters are explained as follows:
- REQUEST=QUERY
- REQUEST=QUERYFORMAT
- REQUEST=LIST
- Specifies the type of service to be performed on the list of APF-authorized
program libraries. Specify one of the following:
- QUERY
- Determine if a particular library is in the APF list.
- QUERYFORMAT
- Determine the current format (dynamic or static) of the APF list.
The system returns information to the one byte field specified on
the FORMAT parameter. If the output is 00, the list is static; if
the output is 01, the list is dynamic. When you specify this parameter,
you cannot specify the RETCODE, RSNCODE, and MF parameters. The system
does not provide return and reason codes for a QUERYFORMAT request.
- LIST
- Request a list of the libraries in the APF list. The system returns
the list to the area specified by the ANSAREA parameter. See the
description of the ANSAREA parameter for information on how to read
the entries in the list.
Note: The list will include those libraries
that are defined or defaulted to be APF-authorized. The definition
could be via IEAAPFxx or PROGxx parmlib members, the CSVAPF macro,
or the SETPROG APF system command. Note that programs that are marked
as coming from an authorized library could have come from one of these
libraries or from the link pack area.
- ,DSNAME=libname
- Specifies a field (or a register containing the address of a field)
containing a 44-character name of an APF-authorized library. If the
library name is less than 44 characters, it must be left-justified
in a 44-character field and padded with blanks.
You can specify
an alias of an APF authorized library instead of the actual library
name. However, the CSVAPF service considers an alias to be APF-authorized
only when it is defined in the APF list.
Note: Usually,
you do not need to define the alias of an APF-authorized library in
the APF list. IBM's data management services (for example, OPEN processing)
map an alias to the actual library name, and therefore does not require
the alias to be defined in the APF list. An alias must be defined
in the APF list only when the alias is to be used as input to the
CSVAPF QUERY macro request, or on the SETPROG APF or DISPLAY PROG,APF
operator commands.
- ,VOLTYPE=SMS
- ,VOLTYPE=ANY,VOLUME=volume
- Specifies the status of the library specified on the DSNAME parameter,
which is one of the following:
- SMS
- The library is managed by the storage management subsystem (SMS).
- ANY
- The library may or may not be SMS-managed. The library is located
on volume volume, which specifies the address of
a 6-character volume serial number; for an ADD request, you can also
specify ****** (six asterisks) to indicate the current sysres
volume, or *MCAT* to indicate the volume on which the master
catalog resides. If volume is all zeros, the system
assumes that the library is SMS-managed.
Note: The return code on a Query is determined by whether
the match is exact or inexact. A return code of 0
indicates an exact match which could be: - You coded DSNAME=d and VOLTYPE=ANY and VOLUME=v and
there is an entry in the APF list that matches both the data set and
the volser.
- You coded DSNAME=d and an indication of “SMS-managed”
(VOLTYPE=SMS) and there is an entry in the APF list that matches the
data set and indicates “SMS-managed”.
A return code of 4 with a reason code = 0401 indicates
an inexact match which is: - You coded DSNAME=d and VOLTYPE=ANY and VOLUME=v and
there is no exact match, but there is an entry in the APF list that
matches the data set and indicates “SMS-managed”.
- ,FORMAT=format
- Specifies a 1-byte field (or a register containing the address
of a field) for output that the system is to use to indicate the current
format of the APF list.
- ,ANSAREA=ansarea
- Specifies an area (or a register containing the address of an
area) where the system is to store the current list of APF-authorized
libraries. Use the CSVAPFAA mapping macro to map this area. Specify
the length of this area on the ANSLEN parameter.
The system returns
a header that indicates the total number of libraries in the list
and the offset to the first library entry. To find the next entry,
add the value in the length field (APFELEN) to the address of the
current entry.
For each library entry, the volume identifier
in field APFEVOLUME is valid only when the library is not SMS-managed
(the bit APFESMS in field APFEFLAGS is off). If the library is SMS-managed,
field APFEVOLUME contains “*SMS* ”.
- ,ANSLEN=anslen
- Specifies a fullword (or a register containing the address of
a fullword) that contains the length of the area where the system
is to return the current APF list. This value must be equal to or
greater than the length of the APFHDR structure in the CSVAPFAA mapping
macro.
If the area is not long enough to contain the entire APF
list, the system returns as many entries as it can provide. The system
indicates the length that is currently required to contain all the
information in field APFHTLEN in the CSVAPFAA mapping macro.
- ,RETCODE=retcode
- Specifies a fullword (or a register) where the system is to store
the return code. The return code is also in general purpose register
(GPR) 15. Do not specify this parameter on a QUERYFORMAT request.
- ,RSNCODE=rsncode
- Specifies a fullword (or a register) where the system is to store
the reason code. The reason code is also in general purpose register
(GPR) 0. Do not specify this parameter on a QUERYFORMAT request.
- ,MF=S
- Specifies the standard form of the CSVAPF macro. Do not specify
this parameter on a QUERYFORMAT request.
Return and reason codes
When the CSVAPF macro returns control to your program, GPR 15 (and retcode)
contains a return code. When the value in GPR 15 is not zero, GPR
0 (and rsncode) contains a reason code. xxxx indicates
internal information. If you specified the QUERYFORMAT option, CSVAPF
does not return any return or reason code to your program.
Table 1. Return and Reason Codes for the
CSVAPF MacroHexadecimal Return Code |
Hexadecimal Reason Code |
Meaning and Action |
---|
00 |
— |
Meaning: The CSVAPF request completed successfully.
The result depends on the option: - QUERY - The system found the library in the APF list.
- LIST - The system returned a list of all the libraries in the
APF list.
Action: None.
|
04 |
xxxx0401 |
Meaning: For a QUERY request, the library is in the
list, and is SMS-managed. Action: None.
|
04 |
xxxx0402 |
Meaning: For a QUERY request, the library
is not in the APF list. Action: None.
|
04 |
xxxx0403 |
Meaning: Program error. For a LIST request,
the value specified on the ANSLEN parameter is not large enough to
contain the entire list of APF-authorized libraries. Action:
Check the answer area field APFHTLEN in the CSVAPFAA mapping macro
to see how much space is required to return the APF list. Issue the
CSVAPF macro again, specifying, on the ANSLEN parameter, a fullword
containing a value large enough to contain the entire APF list.
|
08 |
xxxx0801 |
Meaning: Program error. The system could
not access the parameter list that the CSVAPFAA macro created. Action:
Ensure that the parameter list is addressable.
|
08 |
xxxx0804 |
Meaning: Program error. The caller is
not authorized to issue the CSVAPF macro for the specified request. Action:
See the authorization requirements described in the Environment section
for this macro.
|
08 |
xxxx0805 |
Meaning: Program error. The system could
not perform the function because the home address space is different
from the primary address space. Action: For the specified
request, do not issue the CSVAPF macro while running in cross memory
mode.
|
08 |
xxxx0806 |
Meaning: Program error. The ALET of the
area specified on the ANSAREA parameter is not correct. Action:
Ensure that the ALET is 0, or that the ALET represents a valid entry
on the DU-AL. If you specified register notation “(n),” make sure
that the ALET in register n is correct.
|
08 |
xxxx0807 |
Meaning: Program error. The system found
an error when accessing the answer area specified on the ANSAREA parameter. Action:
Ensure that the answer area address specified on the ANSAREA parameter
is valid.
|
08 |
xxxx0808 |
Meaning: Program error. For a QUERY request,
the length of the answer area specified on the ANSLEN parameter is
not equal to or greater than the length of the APFHDR structure in
the CSVAPFAA mapping macro. Action: On the ANSLEN parameter,
specify a fullword containing a value that is equal to or greater
than the length of the APFHDR structure in the CSVAPFAA mapping macro.
|
08 |
xxxx0809 |
Meaning: Program error. The request type
is not valid. Action: Check for a possible overlay in the
parameter list that the CSVAPFAA mapping macro created.
|
08 |
xxxx080A |
Meaning: Program error. The CSVAPF macro
could not establish an ESTAEX recovery routine. xxxx is
the return code from the ESTAEX service. Action: See the
description of the ESTAEX macro for the action associated with the xxxx return
code.
|
08 |
xxxx080B |
Meaning: Program error. A reserved field
is not zero in the parameter list that the CSVAPFAA macro created. Action:
Check for a possible overlay in the parameter list that the CSVAPFAA
macro created.
|
08 |
xxxx080C |
Meaning: Program error. The library name
specified on the DSNAME parameter is not valid. The first character
is blank. Action: On the DSNAME parameter, specify a library
name that does not include a blank as the first character.
|
08 |
xxxx080D |
Meaning: Program error: The system found
an error in the access list entry token (ALET) for the parameter list
that the CSVAPFAA macro created. Action: Ensure that the
ALET is 0 or that the ALET represents a valid entry on the DU-AL.
|
08 |
xxxx080E |
Meaning: Program error. The system found
an incorrect version number in the parameter list that the CSVAPF
macro created. Action: Verify that your program is not overwriting
the parameter list, and that the execute form of the macro correctly
addresses the parameter list. If you are using the modify form of
the macro, make sure that you specified the COMPLETE option on at
least one invocation.
|
10 |
xxxx1001 |
Meaning: System error. An internal error
occurred. Action: Contact the system programmer. Provide
the return code, the reason code, and the explanation of the error.
|
Example 1
Determine the current format of the APF list: CSVAPF REQUEST=QUERYFORMAT,FORMAT=LFORMAT
CLI LFORMAT,CSVAPFFORMATDYNAMIC
BE LAB1
* Format is static
.
.
LAB1 DS 0H Format is dynamic
.
.
LFORMAT DS X Output Format
CSVAPFAA , Include CSVAPFAA mapping
Example 2
Change a program to use the CSVAPF macro to access the APF list
(this program uses the LIST function as an example of one way to access
the APF list): L 15,X'10' Get CVT address
TM CVTDCB-CVTMAP(15),CVTOSEXT OS Extension present
BZ OLDLIST No, old (static) list
TM CVTOSLV1-CVTMAP(15),CVTDYAPF Is dynamic APF present?
BZ OLDLIST No, old (static) list
MVC APAALEN,=AL4(4096) Assume length is 4K
L 2,APAALEN Get length
GETMAIN RU,LV=(2) Get storage for answer area
ST 1,APAA@ Save answer area address
LAB1 DS 0H
L 4,APAA@ Get answer area address
CSVAPF REQUEST=LIST,ANSAREA=(4),ANSLEN=APAALEN, *
RETCODE=LRETCODE,RSNCODE=LRSNCODE
CLC LRETCODE,=AL4(CSVAPFRC_OK) Success?
BE LAB3 Yes, process data
CLC LRETCODE,=AL4(CSVAPFRC_WARN) Warning?
BNE LAB2 No, Process other return codes
NC LRSNCODE,=AL4(CSVAPFRSNCODEMASK) Clear high order bits
CLC LRSNCODE,=AL4(CSVAPFRSNNOTALLDATARETURNED) More data?
BNE LAB2 No, Process other return codes
L 3,APAALEN Get current length
L 2,APFHTLEN-APFHDR(4) Get required length
ST 2,APAALEN Save total required length
FREEMAIN RU,LV=(3),A=(4) Free previous area
GETMAIN RU,LV=(2) Get storage for answer area
ST 1,APAA@ Save answer area address
B LAB1 Re-do LIST request
LAB2 DS 0H Process other return codes
.
.
OLDLIST DS 0H
* Current code to process static format APF list
.
.
B LAB9
LAB3 DS 0H
* New code to scan return information from CSVAPF
.
.
L 4,APAA@
L 3,APAALEN
FREEMAIN RU,LV=(3),A=(4) Release APAA
LAB9 DS 0H End of processing
.
.
APAA@ DS A Address of APF answer area
APAALEN DS F Length of APF answer area
LRETCODE DS F Return code
LRSNCODE DS F Reason code
CSVAPFAA , Include CSVAPFAA mapping
|