__getthent (BPX1GTH, BPX4GTH) — Get thread data

Function

The __getthent callable service obtains data that describes the status of a process and its threads. This data includes, but is not limited to, running time, reasons for waiting, syscalls made, files open, and signal information. The caller can access one process on each request, with from none to all of its threads.

You can invoke this service in several ways:

For the first accessible (by SAF standards) process (the lowest relative process in the system)
For a specific process, if the process ID is known and the process is accessible
For a specific thread within a specific accessible process, if both IDs are known
For the next accessible process or thread after one just returned
For a specific address space ID or user ID

Requirements

Operation	Environment
Authorization:	Problem program or supervisor state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1GTH):	31-bit
AMODE (BPX4GTH):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	No latches should be held
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL  BPX1GTH,(Input_length,
               Input_address,
               Output_length,
               Output_address,
               Return_value,
               Return_code,
               Reason_code)

AMODE 64 callers use BPX4GTH with the same parameters. All parameter addresses and addresses in parameter structures are doublewords.

Parameters

Input_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of the fullword that contains the value PGTHA#LEN.

Input_address

Supplied parameter

Type:: Address
Length:: Fullword (doubleword)

The name of the fullword (doubleword) that contains the address of an area mapped by PGTHA; see BPXYPGTH — Map the __getthent input/output structure. The input area must be initialized to hex zeros and then the requested options must be set in the PGTHA section.

Output_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of the fullword that contains the length of the output buffer. Some requests could be satisfied by the minimum buffer size of 128 bytes; whereas a request for all options of a process with maximum resources could exceed half a million bytes.

Output_address

Supplied parameter

Type:: Address
Length:: Fullword (doubleword)

The name of the fullword (doubleword) that contains the address of an area mapped by PGTHB and other PGTH sections; see BPXYPGTH — Map the __getthent input/output structure.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

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

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the __getthent service stores the return code. The __getthent service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The __getthent service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EFAULT	The input_addr (to input_length) or the output_addr (to output_length) contains the address of storage that the caller is not authorized to access (JrBadInputError or JrBadOutputError).
EINVAL	One of the following occurred: The input area (PGTHA) contains a value that is not valid (JrPidBad, JrBadOptions) The input_address is zero (JrBadInputBuffAddr) The output_address is zero (JrBadOutputBuffAddr) The input_length is incorrect (JrInvParmLength) The output_length is too small (JrBuffTooSmall)
EAGAIN	PGTHAPID is undergoing changes, and the z/OS UNIX control blocks are not properly connected (JrBlocksInFlux).
EACCES	PGTHAPID is not accessible to the caller (JrInaccessible).
ESRCH	PGTHAPID was not found (JrPIDNotFound); or PGTHATHID was not found (JrThreadNotFound).
ENOBUFS	The __getthenent service could not obtain a local work area (JrNoBufStorage).

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the __getthent service stores the reason code. The __getthent service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

The system extracts fields PgthJTTime and PgthJLoginName from the TCB and OTCB of the target process by scheduling an SRB to run in that process's address space. If the address space is terminating, the SRB might not run, and these fields are returned as zero.
If this information is not required, you can set option PgthAThreadFast. This action can improve performance on a very busy system because the SRB will not be scheduled. An indication of the thread being in an MVSWAIT is also extracted from the TCB. If the thread is in an MVS™ WAIT, then PgthJStatus is set to Y. When the SRB is not scheduled, then this field is not seen as Y. If the thread is not in any other kernel wait, then PgthJStatus2 is set to R, which indicates running or non-kernel wait.
Typically a user starts with PGTHAPID=PGTH#FIRST, processes the data, and sets PgthAContinue=PgthBContinue to continue with the next thread or the next process, until a Return_value of -1 is reached.
The setting of PgthBContinue steps the caller to the next process or thread. If this action is not desirable, do not use PgthAContinue.
The Output_length required varies with the PGTHAFLAGs selected and the characteristics of the process and its threads. Most processes should fit in 4000 bytes. If a process has 65 000 files opened, 3/4 of a million bytes would be needed. An arbitrary minimum size of 128 bytes is necessary to avoid an error of EINVAL (JrBuffTooSmall).
EINVAL (JrBuffTooSmall) can also indicate that there is insufficient room for at least one PgthJ area. This could happen even with a buffer in excess of 4000 bytes.
Field PgthJWTime indicates how long the thread has been in most waits that are internal to z/OS UNIX. It is meaningful only if it is nonzero.
The high-memory values for the process that are returned in PgthCMemUsage and PgthCMemPages are described in bytes. Each value can be displayed as a 4-byte number or as a 3-byte value followed by a qualifier (for example, 50M for fifty megabytes). High-memory values are described with the truncated value of the exact system state; the real values might be slightly higher. The maximum number of bytes that can be returned in PgthCMemUsage and PgthCMemPages is 16383 petabytes.
Flag PGTHCRESPAWN indicates that the process was started with the respawn attribute. See spawn (BPX1SPN, BPX4SPN) — Spawn a process for more information about the respawn attribute.
Flag PGTHCBLOCKING indicates a shutdown-blocking process and flag PGTHCPERM indicates a permanent process.
When the command or argument data is not terminated by a null character, the command or argument is terminated with a null character by the __getthent service.
If PgthACommand is ON and PgthACommandLong is OFF, the maximum length returned in the PGTHF area is 1024. If PgthACommand is OFF and PgthACommndLong is ON, the length returned in the PGTHF area can be greater than 1024. If both bits are on, the new setting, PgthACommndLong, is honored.
Together, the PgthE output area (for path) and the PgthF output area (for the command and arguments) can take up to 2048 bytes space. When PgthACommand is specified, 1024 bytes are reserved for the PgthE section (path name) and 1024 bytes are reserved for the PgthF section (the command and arguments). Up to only 1024 bytes of data are returned for the PgthF section.
When PgthACommandLong is specified, it indicates that the PgthF section can be greater than 1024 bytes. If path is requested (PgthAPath), then the PgthE section is filled in and the remainder of the 2048 bytes can be used for the PgthF section. (The PgthF section length will be 2048 bytes less the length of the PgthE section returned). If path is not requested, then the PgthF section can be up to 2048 bytes.

If PgthACommand and PgthACommandLong are both specified, PgthACommandLong is honored.
PgthaFilePath must be specified with PgthaFileData. If it is not, then PgthaFilePath is ignored. If PgthaFilePath is specified, a significant amount of data might be returned if the process has many open files. Information is not returned if more than 16MB is required or if the input buffer is too small. The path names that are returned are full, relative, or partial and is intended for diagnostic use. If a partial path name is returned, the PgthHPathTrunc bit is set.

Related services

w_getpsent (BPX1GPS) — Get process data

Characteristics and restrictions

None.

Examples

For an example using this callable service, see BPX1GTH (__getthent) example.