Description

Description

z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
SA23-1372-00

The CSVAPF macro allows you to determine the format and contents of the APF-authorized library list. You can issue CSVAPF to:

Change the format of the APF list (from dynamic to static, and vice versa)
Add or delete the library entries in a dynamic APF list (without having to reIPL the system)
Determine whether or not a library is in the APF list
Obtain a list of all library entries in the APF list
Determine the current format (dynamic or static) of the APF list.

The CSVAPF macro is also described in the z/OS MVS Programming: Assembler Services Reference ABE-HSP, with the exception of the REQUEST=ADD, REQUEST=DELETE, and REQUEST=DYNFORMAT parameters.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and any PSW key. For the ADD, DELETE requests: RACF® UPDATE authority to the FACILITY class entity CSVAPF.`libname`. For a DYNFORMAT request: RACF authority to the FACILITY class entity CSVAPF.MVS.SETPROG.FORMAT.DYNAMIC. If no RACF profile is defined or RACF is not available, one of the following: Supervisor state PSW key 0-7 PKM allowing key 0-7 APF-authorized
Dispatchable unit mode:	For the ADD, DELETE, and DYNFORMAT requests, task mode. For the QUERY, QUERYFORMAT, and LIST requests, task or SRB mode.
Cross memory mode:	For the ADD, DELETE, and DYNFORMAT requests, PASN = HASN = SASN. For the QUERY, QUERYFORMAT, and LIST requests, any PASN, any HASN, any SASN.
AMODE:	For a QUERY or QUERYFORMAT request, 31-bit. For all other requests, 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:	For the QUERY, QUERYFORMAT, and LIST requests, the local and CMS locks may be held, but are not required. For all other requests, no locks may be 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.

Restrictions

None.

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.

Performance implications

None.

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=ADD	DSNAME, VOLTYPE, VOLUME, RETCODE, RSNCODE
REQUEST=DELETE	DSNAME, VOLTYPE, VOLUME, RETCODE, RSNCODE
REQUEST=DYNFORMAT	RETCODE, RSNCODE
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=ADD

REQUEST=DELETE

REQUEST=LIST

REQUEST=DYNFORMAT

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.
ADD: Add a library to the dynamic APF list. To use this parameter, the format of the APF list must be dynamic.
DELETE: Delete a library from the dynamic APF list. To use this parameter, the format of the APF list must be dynamic.
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.
DYNFORMAT: Change the format of the APF list from static to dynamic. Before you make the change, contact the system programmer to validate that all programs and vendor products are converted to use dynamic APF services and that the proper program products are installed.

,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.
Defining only the alias data set does not authorize either the real or the alias data set. A real data set name must be specified.

,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.

,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.

ABEND codes

None.

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 Macro
Hexadecimal 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. ADD - The system added the specified library to the APF list. DELETE - The system deleted the specified library from the APF list. LIST - The system returned a list of all the libraries in the APF list. DYNFORMAT - The format of the APF list is changed (from static to dynamic). Action: None.
04	xxxx0401	Meaning: The CSVAPF request completed successfully. The result depends on the option: For a QUERY request, the library is in the APF list, and is SMS-managed. For an ADD request, the library is already in the APF list. Action: None.
04	xxxx0402	Meaning: One of the following: For a QUERY request, the library is not in the APF list For a DELETE 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	xxxx0802	Meaning: Program error. A program running in SRB mode entered a request that required task mode. Action: For the specified request, avoid issuing the CSVAPF macro while running in SRB mode.
08	xxxx0803	Meaning: Program error. A program issued the CSVAPF macro while running disabled for I/O and external interrupts. Action: Issue the CSVAPF macro while running enabled for I/O and external interrupts.
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 Environment 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.
08	xxxx080F	Meaning: Program error. For an ADD, DELETE, or DYNFORMAT request, the caller holds a lock. Action: Release any held locks before issuing CSVAPF with the specified request.
0C	xxxx0C01	Meaning: Environmental error. The function is not available. The APF list format is static. Action: If desired, issue the CSVAPF macro with the REQUEST=DYNFORMAT parameter to change the format of the APF list to dynamic (contact the system programmer to ensure that all the required software products are updated and all vendor products are converted). Then try the function again.
0C	xxxx0C02	Meaning: Environmental error. The function is not available. DFSMS/MVS 1.1 is not installed. Action: Contact the system programmer. Provide the return code, the reason code, and the explanation of the error.
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

Add SMS-managed library MY.LIBRARY.NAME to the list of APF-authorized libraries:

         CSVAPF REQUEST=ADD,DSNAME=MYLIB,VOLTYPE=SMS,
               RETCODE=LRETCODE,RSNCODE=LRSNCODE
   .
   .
MYLIB    DC    CL44'MY.LIBRARY.NAME'
LRETCODE DS    F               Return code
LRSNCODE DS    F               Reason code
         CSVAPFAA ,            Include CSVAPFAA mapping macro

Example 2

Add library MY.LIBRARY.NAME on volume 861234 to the list of APF=authorized libraries,

         CSVAPF REQUEST=ADD,DSNAME=MYLIB,VOLUME=MYVOL,VOLTYPE=ANY,
               RETCODE=LRETCODE,RSNCODE=LRSNCODE
   .
   .
MYLIB    DC    CL44'MY.LIBRARY.NAME'
MYVOL    DC    CL6'861234'
LRETCODE DS    F               Return code
LRSNCODE DS    F               Reason code
         CSVAPFAA ,            Include CSVAPFAA mapping macro

Example 3

Change the format of the APF list from static to dynamic:

         CSVAPF REQUEST=DYNFORMAT,RETCODE=LRETCODE,RSNCODE=LRSNCODE
   .
   .
LRETCODE DS    F               Return code
LRSNCODE DS    F               Reason code
         CSVAPFAA ,            Include CSVAPFAA mapping

Example 4

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 5

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