Description

Description

z/OS MVS Programming: Assembler Services Reference ABE-HSP
SA23-1369-00

Use CSVINFO to obtain information about modules:

Loaded into the link pack area (LPA): specify FUNC=LPA
Loaded into the job pack area (JPA): specify FUNC=JPA
Loaded by a specific task using the LOAD macro: specify FUNC=TASKLOAD
Running under all program request blocks (PRBs) and supervisor request blocks (SVRBs) associated with a specific task, including those that received control through the LINK(X), ATTACH(X), or XCTL(X) macro; or through the z/OS UNIX System Services EXEC command: specify FUNC=TASKALL
Running under a specific PRB or SVRB: specify FUNC=RB
Copied from the parent address space into the job pack area under the z/OS UNIX System Services fork process: specify FUNC=JPA.

When providing information about a loaded module, CSVINFO returns information separately for each of the following types of entry points:

The major entry point
Each entry point created using the IDENTIFY macro
Each minor entry point specified on a LOAD, LINK(X), ATTACH(X), or XCTL(X) invocation the system is processing while CSVINFO is running
The z/OS UNIX System Services entry point (including its file name), if the loaded module is an z/OS UNIX System Services module.

The CSVINFO macro can return information about one loaded module (such as the module running under a specific PRB) or group of loaded modules (such as all modules in LPA). The CSVQUERY macro, which also provides information about loaded modules, returns information about only one particular loaded module at a time.

CSVINFO obtains information about one loaded module at a time, stores the information in the CSVMODI data area, and passes the data area to a user-written module information processing routine (MIPR). The MIPR examines this data and returns control to CSVINFO, either requesting information about an additional loaded module or indicating that no more information is needed. For instance, if you request information for all modules loaded by a particular task, CSVINFO calls the MIPR multiple times, passing information about each loaded module of interest. CSVINFO continues to pass loaded module information to the MIPR until either of the following occurs:

CSVINFO has returned all available information.
The MIPR indicates that no more information is needed by returning a nonzero return code to CSVINFO.

You can issue the CSVINFO macro from a program to obtain information about loaded modules in system storage, or from an IPCS exit to search a dump for information about loaded modules.

References

For detailed information about any of the following, see the program management topic in z/OS MVS Programming: Assembler Services Guide:

How the CSVINFO macro compares with the CSVQUERY macro
How to use the CSVINFO macro
How to code a MIPR
Load modules and their characteristics

End of References

Typically, a pathname returned from CSVINFO is prefixed by a slash (/); however, if that pathname was returned in response to a load (BPX1LOD), exec (BPX1EXC) or spawn (BPX1SPN) call where the HFS program was found in the current working directory, the pathname will not be prefixed with a "/". To determine the full pathname of the HFS program in this case, call BPX1GCW to obtain the current working directory name that was used to locate the program. You can then use this directory pathname as returned from BPX1CGW to prefix the pathname returned by CSVINFO to determine the full pathname of the HFS program.

For information about the CSVMODI data area, see z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.

Environment

Requirements for the caller:

Environmental factor	Requirement
Minimum authorization:	Problem state with any PSW key See additional information under Programming requirements.
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN=SASN
AMODE:	31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	Supervisor state and PSW key 0 callers may hold the LOCAL and the CMS locks. Other callers may not hold any locks.
Control parameters:	Must be in the primary address space

Programming requirements

If you are requesting information about loaded modules in common storage or if multi-tasking is taking place in your address space, the module information you request might be changing while the CSVINFO service is retrieving information unless serialization has been obtained.

If your program runs in supervisor state and invokes the CSVINFO macro, the CSVINFO service obtains the appropriate locks if your program does not already hold them.

Other callers might receive incorrect data or end abnormally if the CSVINFO service accesses a data area that is being updated.

Restrictions

The TCB specified with the TCBADDR keyword must reside in the caller's primary address space unless the CSVINFO macro is being issued from an IPCS exit.

When you issue the CSVINFO macro from an IPCS exit, CSVINFO does not:

Provide serialization
Establish a recovery environment before passing control to your MIPR.

Input register information

Before issuing the CSVINFO 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 GPRs contain:

Register: Contents
0: Reason code
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as work registers 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

If you require information about a specific loaded module, use the CSVQUERY macro to obtain better performance.

Syntax

The standard form of the CSVINFO macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede CSVINFO.

CSVINFO

␢	One or more blanks must follow CSVINFO.

FUNC=LPA
FUNC=JPA,TCBADDR=`tcbaddr`
FUNC=TASKLOAD,TCBADDR=`tcbaddr`
FUNC=TASKALL,TCBADDR=`tcbaddr`	`tcbaddr`: RS-type address or address in register (2) - (12).
FUNC=RB,RBADDR=`rbaddr`	`rbaddr`: RS-type address or address in register (2) - (12).

,ENV=MVS
,ENV=IPCS,ABDPLPTR=`abdplptr`,ASID=`asid`	`abdplptr`: RS-type address or address in register (2) - (12).
	`asid`: RS-type address or address in register (2) - (12).

,MIPR=`mipr`	`mipr`: RS-type address or address in register (2) - (12).

,USERDATA=`userdata`	`userdata`: RS-type address.

,COM=`com`	`com`: Comment text enclosed in single quotation marks.

,RETCODE=`retcode`	`retcode`: RS-type address or address in register (2) - (12).

,RSNCODE=`rsncode`	`rsncode`: RS-type address or address in register (2) - (12).

Parameters

The parameters are explained as follows:

FUNC=LPA

FUNC=JPA,TCBADDR=tcbaddr

FUNC=TASKLOAD,TCBADDR=tcbaddr

FUNC=TASKALL,TCBADDR=tcbaddr

FUNC=RB,RBADDR=rbaddr

A required parameter that specifies the function CSVINFO is to perform.

FUNC=LPA requests that CSVINFO place into the CSVMODI data area information about link pack area (LPA) modules. The search order for LPA modules is the active link pack area (MLPA and FLPA), followed by PLPA. If CSVINFO encounters more than one copy of a loaded module, CSVINFO provides information about each copy.

FUNC=JPA,TCBADDR=tcbaddr requests that CSVINFO place into the CSVMODI data area information for modules in the job pack area for the job step task TCB specified by tcbaddr. When you specify FUNC=JPA, CSVINFO retrieves information for:

All modules in the private area known to the specified job step task
All modules in common storage that have been loaded by an authorized task running under the specified job step task, using the LOAD macro with the GLOBAL parameter.

FUNC=TASKLOAD,TCBADDR=tcbaddr requests that CSVINFO place into the CSVMODI data area information about all modules loaded by the task specified by tcbaddr, using the LOAD macro. Only modules that have not yet been deleted are processed.

FUNC=TASKALL,TCBADDR=tcbaddr requests that CSVINFO place into the CSVMODI data area information about all modules running under PRBs and SVRBs under the task specified by tcbaddr, including all modules that have received control through the LINK(X), ATTACH(X), or XCTL(X) macro. FUNC=TASKALL returns information on LPA modules as well as private modules. If CSVINFO encounters more than one copy of a loaded module, CSVINFO provides information about each copy.

TCBADDR=tcbaddr specifies the address of a required 4-byte field that contains the address of the TCB about which you want information.

FUNC=RB,RBADDR=rbaddr requests that CSVINFO place into the CSVMODI data area information about the module running under the PRB or SVRB specified by rbaddr.

RBADDR=rbaddr specifies the address of a required 4-byte field that contains the address of the PRB or SVRB about which you want information.

,ENV=MVS

,ENV=IPCS,ABDPLPTR=abdplptr,ASID=asid

A required parameter that specifies whether you are issuing CSVINFO from a program (to search system storage) or from an IPCS exit (to examine a dump).

ENV=MVS specifies that you are issuing CSVINFO from a program and that you want CSVINFO to examine system storage.

ENV=IPCS specifies that you are issuing CSVINFO from an IPCS exit to search a dump. When you specify ENV=IPCS you must also specify ABDPLPTR=abdplptr and ASID=asid.

ABDPLPTR=abdplptr specifies the address of the ABDUMP parameter list (ABDPL) that is currently in use. When your IPCS exit routine gets control, GPR 1 contains the address of the ABDUMP parameter list. CSVINFO passes the address of the ABDPL to the caller's MIPR in the input parameter list mapped by the CSVMODI mapping macro.

ASID=asid identifies the address space id (ASID) in the dump from which the requested module information is to be obtained. asid contains the address of a 16-bit address space identifier. The specified address space identifier is stored in the ADPLASID field of the ABDPL, and the ADPLASID field contains this value when CSVINFO passes control to your MIPR.

,MIPR=mipr

A required parameter that contains the address of the caller's module information processing routine (MIPR).

,USERDATA=userdata

Specifies the address of an optional 16-byte input field that contains user data to be passed to the MIPR. The CSVINFO macro places the user data into the CSVMODI data area before it passes control to the MIPR.

,COM=com

Specifies an optional character input. You can use this keyword to produce a comment in the macro expansion. The comment string must be enclosed in single quotation marks if it contains lowercase characters.

,RETCODE=retcode

Specifies the location where the system is to store the return code. The return code is also in GPR 15. If you specify a storage location, it must be on a fullword boundary.

,RSNCODE=rsncode

Specifies the location where the system is to store the reason code. The reason code is also in GPR 0. If you specify a storage location, it must be on a fullword boundary.

ABEND codes

None.

Return and reason codes

When CSVINFO returns control to your program, GPR 15 (and retcode, if you coded RETCODE) contains the return code.

For a return code of X'8', GPR 0 (and rsncode, if you coded RSNCODE) contains a reason code set by the MIPR. For other return codes, the reason code is always 0.

Table 1. Return Codes for the CSVINFO Macro
Hexadecimal Return Code	Meaning and Action
0	Meaning: Successful completion. Action: None.
4	Meaning: Successful completion. Action: None. There was no information for CSVINFO to return.
8	Meaning: CSVINFO processing was ended by a nonzero return code from the caller's MIPR. GPR 0 (and `rsncode`, if you coded RSNCODE) contains a reason code from the MIPR. Action: Check the reason code from the MIPR and take appropriate action.
C	Meaning: Program error. CSVINFO was unable to obtain the local lock needed for serialization for a supervisor state caller. Action: Release the CML lock before invoking CSVINFO.
10	Meaning: Program error. A parameter specified for CSVINFO was inaccessible or not valid. Action: Correct the parameters and rerun the program.
14	Meaning: Environmental error. The CSVINFO service should have been available but wasn't. Action: Ask the system programmer to determine why the CSVINFO service is unavailable.
18	Meaning: System or program error. CSVINFO processing ended because the requested information could not be retrieved from the dump. This return code applies only when CSVINFO is issued from an IPCS exit. The message BLS18100I accompanies this return code. See z/OS MVS Dump Output Messages for further information about this message. Action: Ensure that you have not passed the CSVINFO service an incorrect address and rerun the program. If the program receives this return code again, either the necessary data areas are not in the dump or there might be an error in the control blocks used to keep track of loaded modules.
1C	Meaning: System error. This return code is for IBM® diagnostic purposes only. Action: Rerun the program one or more times. If the problem persists, record the return code and message text and supply it to the appropriate IBM support personnel.
20	Meaning: Environmental error. The CSVINFO service is not supported on this level of the system. Action: Check with your system programmer to determine which system your program should run on to use the CSVINFO service.
24	Meaning: Environmental error. The CSVINFO parameter list is not valid with the level of CSVINFO service on the system. Action: Record the return code and supply it to the appropriate IBM support personnel.
28	Meaning: System error. CSVINFO timed out after entering an infinite loop while accessing information about loaded modules. Action: If you specified ENV=MVS and your program was not in supervisor state, rerun the program. The error might have been temporary, resulting from a lack of serialization while accessing control blocks. If the error persists or CSVINFO was running with serialization when the error occurred, record the return code and supply it to the appropriate IBM support personnel.
2C	Meaning: Program error. The RB address specified using the RBADDR parameter on a FUNC=RB request is not the address of a PRB or an SVRB. Action: Ensure that you pass the address of a PRB or an SVRB. CSVINFO does not process requests for other types of RBs.
30	Meaning: Program error. The MIPR failed. Action: Ensure that the MIPR restores GPRs 2-13 before returning control to CSVINFO. If this was not the problem and the MIPR did not have its own recovery routine, your options depend on whether your program was running in an authorized state. CSVINFO's recovery routine issued an SVC dump if your program was authorized in at least one of the following ways: Supervisor state PSW key 0-7 APF authorization. If a dump was taken, examine it for information about why the MIPR might have failed. If your program was running in an unauthorized state, the information recorded in the job log at the time of the failure is the only information provided.
34	Meaning: System error. While processing the RB chain, CSVINFO entered an infinite loop, signalled by reaching 1000 iterations. The RB address specified on the RBADDR parameter for a FUNC=RB request caused a circular RB chain. Action: Ensure that you pass the address of a PRB or an SVRB. CSVINFO does not process requests for other types of RBs. If you passed a valid RB address, record the return code and supply it to the appropriate IBM support personnel.