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

Function

The IPCSDumpOpenClose service opens (and closes) a dump that has been captured with an SVC dump, a SYSMDUMP, or the DUMP command. Once the dump has been opened, it can be processed with the BPXGMPTR callable service, which reads storage, registers, program attributes, and other dump-related information.

Requirements

Operation	Environment
Authorization:	Problem state, user PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPXGMCDE):	31-bit
AMODE (BPXGMCD4):	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

The syntax format is as follows:

CALL BPXGMCDE,(Dcor_Open,
              LevelIndicator,
              DumpDataSetName,
              LogDataSetName,
              ExecDataSetName,
              ClistDataSetName,
              DDIRStr,
              ErrorMsgPtr,
              Return_code,
              Return_Value1,
              Return_Value2,
              Return_Value3)

CALL BPXGMCDE,(DCOR_Close,
              OpenToken)

AMODE 64 callers use BPXGMCD4 with the same parameters.

Parameters

Dcor_Open

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the constant for an open request, DCOR_OPEN. The value of this constant is defined in the BPXYDCOR macro (see BPXYDCOR — dbx cordump cache information). If the open request is completed successfully, the BPXGMCDE (BPXGMCD4) service returns a nonzero open token in register 15. This token is used by the BPXGMCDE (BPXGMCD4) close function and the BPXGMPTR (BPXGMPT4) callable service.

If the open request is not successful, the BPXGMCDE (BPXGMCD4) service returns a token value of zero, with explicit failure information in the Return_code, Return_value1, Return_value2, and Return_value3 fields.

LevelIndicator

Parameter supplied and returned

Type:: Address
Length:: Fullword

The name of a fullword that contains the release level of the DCOR services. The level number is defined in BPXYDCOR.

DumpDataSetName

Supplied parameter

Type:: Character string
Length:: Variable

The name of a required null (X'00'-terminated) character string that provides the name of the dump that is to be opened. The name may be an MVS™ data set name or a z/OS UNIX file name. An MVS data set name must begin with a double slash (//); otherwise the name is considered to be the name of a file. To indicate that an MVS data set name is fully qualified, quotes should be used on each side of the data set name (//'MVS.DATA.SET'). When quotes are not used to fully qualify the data set name, the login user ID is prefixed to the data set name (userid.MVS.DATA.SET).

LogDataSetName

Supplied parameter

Type:: Character string
Length:: Variable

The name of an optional null (X'00'-terminated) character string that provides the name of a log data set. The name must be an MVS data set name; a z/OS UNIX file cannot be used as a log data set. The data set name is considered to be fully qualified; quotes may be used but they are not necessary.

TSO messages that are generated from running IPCS are written to the log data set. This log is useful in problem determination, especially when the IPCS environment does not get established.

ExecDataSetName

Supplied parameter

Type:: Character string
Length:: Variable

The name of an optional null (X'00'-terminated) character string that provides the name of the MVS PDS data set that is to be used in place of SYS1.SBPXEXEC, which is the default. SYS1.SBPXEXEC contains the REXX exec BPXTIPCS, which is used to create a dump directory and establish the IPCS environment.

The name must be an MVS data set name; z/OS UNIX files are not supported for this parameter. The data set name is considered to be fully qualified: quotes may be used, but they are not necessary.

ClistDataSetName

Supplied parameter

Type:: Character string
Length:: Variable

The name of an optional null (X'00'-terminated) character string that provides the name of the MVS PDS data set that is to be used in place of SYS1.SBLSCLI0, which is the default. SYS1.SBLSCLI0 contains IPCS CLISTs, including BLSCDDIR, which is used to allocate a temporary or permanent dump directory.

The name must be an MVS data set name; z/OS UNIX files are not supported for this parameter. The data set name is considered to be fully qualified: quotes may be used, but they are not necessary.

DDIRStr

Supplied parameter

Type:: Character string
Length:: Variable

The name of an optional null (X'00'-terminated) character string that is used to tailor the use of the IPCS dump directory on the invocation of the BLSCDDIR command. It may contain any of the parameters that are accepted by BLSCDDIR. (See z/OS MVS IPCS Commands.)

The name must be an MVS data set name; z/OS UNIX files are not supported for this parameter. The data set name is considered to be fully qualified: quotes may be used, but they are not necessary.

The BLSCDDIR command uses a VOLSER of VSAM01 to allocate a new dump directory if the VOL parameter is not provided here.

ErrorMsgPtr

Returned parameter

Type:: Character string
Length:: Variable (Fullword)

The name of a required fullword area that will be set to point to a string terminated by a null (X'00'-terminated) character string containing one or more messages that describe certain types of errors that can occur. This string can be sent to a standard error device or file by the caller, and used to inform the end user of the specific reasons for certain failures. If no messages are returned, the string is the null chaacter. Not all error cases return a message string.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the IPCSDumpOpenClose service returns the reason for the failure of the open request. This field is meaningful only when the open token returned in register 15 is 0. The value and meaning of Return_value1, Return_value2, and Return_value3 are dependent upon the nonzero value returned in the Return_code field. See BPXYDCOR — dbx cordump cache information for detailed information about these fields.

Return_code	Explanation
Dcor_CDErc_OK	The specified function completed successfully.
Dcor_CDErc_ParmErr	A parameter error was detected. Return_value1 determines the specific reason for the failure: Dcor_R1_ParmErr_FuncCodeErr — The function code is not supported. Dcor_R1_ParmErr_DumpDsnReq — The dump data set name is required.
Dcor_CDErc_ProcErr	A DCORE processing error occurred. Return_value1 determines the specific reason for the failure: Dcor_R1_ProcErr_SystemErrATC — An unexpected system error occurred while the IPCS environment was being established. Return_value2 contains the ABEND reason code.
Dcor_CDErc_IKJTSOEVErr	The system encountered an error while trying to establish a TSO environment with the IKJTSOEV service. See the return values for more information.
Dcor_CDErc_IKJEFTSRErr	The system encountered an error while trying to run the REXX exec with the IKJEFTSR service. See the return values for more information.
Dcor_CDErc_AllocateErr	The system encountered an error while trying to allocate one of the specified data sets. Return_value1 identifies the data set that caused the failure; Return_value2 contains the return code from dynamic allocation (DYNALLOC); and Return_value3 contains the reason code. Dcor_R1_AllocateErr_LogDsn — There was an error allocating the log data set. Dcor_R1_AllocateErr_ExecDsn — There was an error allocating the EXEC data set.

Return_value1, Return_value2, and Return_value3

Returned parameters

Type:: Integer
Length:: Fullword

The names of fullwords in which the IPCSDumpOpenClose service returns details of the error indicated by Return_code. See the mapping of BPXYDCOR for detailed information about these fields.

Dcor_Close

Supplied parameter

Type:: Integer
Length:: Fullword

The names of a fullword that contains the constant for a close request, DCOR_CLOSE. The value of this constant is 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) open request.

Usage notes

The routine to be executed receives control with the following attributes:
- Problem program state
- Key of the target pthread task
- AMODE 31
- Primary ASC mode
The register usage on entry to the specified routine is:
- R0: Undefined
- R1: Address of the parameter list, as specified by the caller of the IPCSDumpOpenClose service.
- R2–R12: Undefined.
- R13: Address of a 72–byte work area in the key that the routine gains control under.
- R14: The return address from the specified routine to the IPCSDumpOpenClose service. This address must be preserved by the invoked routine.
- R15: Address of the invoked routine.
Only tasks created with pthread_create or the IPT can invoke this service. If a task that is not an IPT or a pthread-created task requests this service, it receives an EACCES return code.
At any given time only one pthread can have this service request pending for a given target pthread. If a pthread requests this service for a given target pthread when another pthread already has this service pending for that target pthread, the last pthread receives an EAGAIN return code. It is the caller's responsibility to serialize the invocation of IPCSDumpOpenClose, or contain retry logic for cases in which the EAGAIN return code is received.
The EXITRTN assembler routine cannot issue callable services after it gains control under the target pthread.
The specified routine can establish its own recovery environment. However, even if recovery is not established, the IPCSDumpOpenClose service establishes its own recovery environment while running under the target pthread. For all recoverable errors, this recovery routine retries, returning the EFAULT return code to the requester. It also ensures that any recovery routine established by the target pthread itself is not entered unexpectedly.

Related services

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

Characteristics and restrictions

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