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.
Characteristics and restrictions
None.