IPCSDumpAccess (BPXGMPTR, BPXGMPT4) — PTRACE IPCS dump access service

Function

The IPCSDumpAccess service reads storage, registers, program attributes, and other information related to a process or thread in a dump that has been opened with the IPCSDump Open/Close service (BPXGMCDE, BPXGMCD4).

Requirements

Operation	Environment
Authorization:	Problem state, user PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPXGMPTR):	31-bit
AMODE (BPXGMPT4):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPXGMPTR,(Dcor_Request,
               OpenToken,
               Parm1Address,
               Parm2Address,
               Parm3Address,
               Return_value,
               Return_code,
               Reason_code)

AMODE 64 callers use BPXGMPT4 with the same parameters.

Parameters

Dcor_Request

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the integer value for the function requested. The functions are explained in the usage notes. The request integer values are defined in the BPXYDCOR macro. See BPXYDCOR — dbx cordump cache information.

OpenToken

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the open token returned by the BPXGMCDE (BPXGMCD4) Dcor_Open request.

Parm1Address

Supplied parameter

Type:: Address or Integer
Length:: Variable

The name of a required value that contains the first parameter described by the function requested. See BPXYDCOR — dbx cordump cache information.

Parm2Address

Supplied parameter

Type:: Address or Integer
Length:: Variable

The name of a required value that contains the second parameter described by the function requested. If a second parameter is not required, this value may be zero. See BPXYDCOR — dbx cordump cache information.

Parm3Address

Supplied parameter

Type:: Address or Integer
Length:: Variable

The name of a required value that contains the third parameter described by the function requested. If a third parameter is not required, this value may be zero. See BPXYDCOR — dbx cordump cache information.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the IPCSDumpAccess service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The address of a fullword in which the IPCSDumpAccess service stores the return code. The IPCSDumpAccess service returns Return_code only when the Return_value is -1 and the Reason_code is DcorPTR_RsnDcorError. The IPCSDumpAccess service can return one of the following values in the Return_code parameter:

Return_code	Explanation
Dcor_PTRrc_OK	The specified function completed successfully.
Dcor_PTRrc_AsidNotFound	An address space could not be found in the dump to satisfy this request.
Dcor_PTRrc_AsidNotSet	An ASID or PID has not been established for this session.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the IPCSDumpAccess service stores the reason code. The IPCSDumpAccess service returns Reason_code only if Return_value is 0. Reason_code further qualifies the Return_code value. The following reason codes can accompany the return code:

Reason_code	Explanation
RsnOkValue	The specified function completed successfully.
RsnDcorError	See Dcor return codes.
RsnMVSError	A getmain error probably occurred.
RsnIPCSError	Use the log data set to determine the cause of the error.

Usage notes

This table shows the constant options you can select for the Dcor_Request parameter. See BPXYDCOR — dbx cordump cache information.

Table 1. Dcor_Request options
Function request	Explanation
Dcor_ASID_LIST#	Return a list of ASIDs, and the number of ASIDs contained in the list. This list is described in BPXYDCOR as the AsidList_Map.
Dcor_SET_ASID#	Set the current address space ID to view in the dump. If a null parameter is provided, the home address space at the time the dump was taken will be returned. Changing the ASID may alter other values, such as the PID or the current thread.
Dcor_PID_LIST#	Return a list of PIDs, and the number of PIDs contained the list. This list is described in BPXYDCOR as the PidList_Map.
Dcor_SET_PID#	Set the current process ID to view in the dump. If a null parameter is provided, the active process at the time the dump was taken will be returned. The process requested must exist in the current address space. Changing the PID may also cause the current thread to change.
Dcor_LDINFO#	Return the loader data from the current thread.
Dcor_THREAD_LIST#	Return the list of threads contained in the current PID, and the number of threads in the list. The Thread_list mapping is described in BPXYPTRC as PtPxInfo.
Dcor_THREAD_CURRENT#	Return the value of the current thread.
Dcor_SET_THREAD#	Set the current thread ID to view in the dump.
Dcor_PSW#	Return the 16-byte PSW for the current thread.
Dcor_ERROR_PSW#	Return the 16-byte PSW that caused the dump to be taken.
Dcor_GPR_LIST#	Return the 64-bit GPRs for the current thread.
Dcor_ERROR_GPR_LIST#	Return the 64-bit GPRs active at the time of error.
Dcor_FLT_LIST#	Return the 64-bit FLTs for the current thread.
Dcor_ERROR_FLT_LIST#	Return the 64-bit FLTs active at the time of error.
Dcor_THREAD_STATUS#	Return the Thread_list entry of the current thread. The Thread_list mapping is described in BPXYPTRC as PtPxInfo.
Dcor_READ_D#	Retrieve dump data and place it in a buffer provided by the caller.
Dcor_CAPTURE#	Return the address of a buffer containing the requested dump data.
Dcor_CONDINFO#	Return the current abend information at the time of error. CondInfo is described in BPXYDCOR by the CondInfo_Map.
Dcor_IPCSCMD#	Pass a command to IPCS. The output is stored in an MVS™ sequential data set named 'userid.BPXGCOR.IPCSPRNT'.

This table shows the PTRACE service options for the Dcor_Request parameter. For each option, the meanings of the Parm1, Parm2, and Parm3 parameters are shown. The terms in the table are described in BPXYDCOR — dbx cordump cache information.

Table 2. PTRACE service options for the Dcor_Request parameter
Function request	Parm1	Parm2	Parm3
Dcor_ASID_LIST#	The address of a fullword location to receive the list address	The address of a fullword location to receive the count of ASIDs	0
Dcor_SET_ASID#	The address of a 16-bit location that contains 0 or an ASID value	0	0
Dcor_PID_LIST#	The address of a fullword location to receive the list address.	The address of a fullword location to receive the count of PIDS.	0
Dcor_SET_PID#	The address of a fullword location that contains 0 or a PID value.	0	0
Dcor_LDINFO#	The address of a fullword location to receive the address of the loader information	0	0
Dcor_THREAD_LIST#	The address of a fullword location to receive the address of the GPR list	0	0
Dcor_THREAD_CURRENT#	The address of an 8-byte location that contains a null value or a thread ID	0	0
Dcor_SET_THREAD#	The address of an 8-byte location that contains a null value or a thread ID	0	0
Dcor_PSW#	The address of a 16-byte location to receive the PSW	0	0
Dcor_ERROR_PSW#	The address of a 16-byte location to receive the PSW	0	0
Dcor_GPR_LIST#	The address of a fullword location to receive the address of the GPR list	The address of a fullword location to receive the length of the GPR list	0
Dcor_ERROR_GPR_LIST#	The address of a fullword location to receive the address of the GPR list	The address of a fullword location to receive the length of the GPR list	0
Dcor_FLT_LIST#	The address of a fullword location to receive the address of the FLT list	The address of a fullword location to receive the length of the FLT list	0
Dcor_ERROR_FLT_LIST#	The address of a fullword location to receive the address of the FLT list	The address of a fullword location to receive the length of the FLT list	0
Dcor_THREAD_STATUS#	The address of a fullword location to receive the address of the thread list	The address of a fullword location to receive the length of the thread list
Dcor_READ_D#	The fullword (for AMODE 31 callers) or doubleword (for AMODE 64 callers) input value of virtual storage in the dump	The fullword (for AMODE 31 callers) or doubleword (for AMODE 64 callers) input value of the number of bytes to return	The fullword (for AMODE 31 callers) or doubleword (for AMODE 64 callers) address that contains the address of the caller's input buffer
Dcor_CAPTURE#	The fullword (for AMODE 31 callers) or doubleword (for AMODE 64 callers) value of virtual storage in the dump	The fullword (for AMODE 31 callers) or doubleword (for AMODE 64 callers) value of the number of bytes to return	The fullword (for AMODE 31 callers) or doubleword (for AMODE 64 callers) address to return the output buffer address
Dcor_CONDINFO#	The fullword (for AMODE 31 callers) or doubleword (for AMODE 64 callers) address to return the address of the CondInfo data	The fullword (for AMODE 31 callers) or doubleword (for AMODE 64 callers) address to return the length of the CondInfo data	0
Dcor_IPCSCMD#	The address of the text of an IPCS command, or the word 'LOG'. LOG causes the diagnostic information that is active in the session to be written to an MVS sequential output data set.	A fullword input value, of the length of the IPCS command.	A fullword input value that contains the LRECL to use when allocating the sequential MVS data set `userid.BPXGCORE.IPCSPRNT`, which contains the output of the IPCS command.

Related services

IPCSDumpOpenClose (BPXGMCDE, BPXGMCD4) — MVS IPCS dump open/close service

Characteristics and restrictions

There are no restrictions on the use of the IPCSDumpAccess service.