w_getpsent (BPX1GPS) — Get process data

Function

The w_getpsent callable service provides data describing the status of a process. This data includes, but is not limited to, running time, user IDs (UIDs), groups IDs (GIDs), and invocation parameters. Data is returned for the processes that the caller can access.

Note: There is no 64-bit version of the w_getpsent callable service. To get equivalent function, use __getthent (BPX1GTH, BPX4GTH) — Get thread data in 64-bit mode.

Requirements

Operation Environment
Authorization: Problem program or supervisor state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE: 31-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

The syntax format is as follows:

Parameters

Process_token
Returned parameter
Type:
Integer
Length:
Fullword

The name of the fullword containing the process token that identifies the relative position of a process in the system. Zero represents the first process in the system.

Buffer_length
Supplied parameter
Type:
Integer
Length:
Fullword

The name of the fullword containing the value PGPS#LENGTH.

Buffer_address
Supplied parameter
Type:
Address
Length:
Fullword
The name of the fullword containing the address of the buffer. For the mapping of these options, see BPXYPGPS — Map the response structure for w_getpsent. Several fields in this buffer should be initialized:
PGPSCONTTYBLEN    Length of PGPSCONTTYBUF
PGPSCONTTYPTR     Address of PGPSCONTTYBUF(Len¬=0)
PGPSPATHBLEN      Length of PGPSPATHBUF
PGPSPATHPTR       Address of PGPSPATHBUF (Len¬=0)
PGPSCMDBLEN       Length of PGPSCMDBUF
PGPSCMDPTR        Address of PGPSCMDBUF (Len¬=0)
Return_value
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the w_getpsent service returns the process token or 0 if the request is successful, or -1 if it is not successful.
Value Explanation
Process Token The process token of the next logical process in the system.
0 End of file. There are no active processes at or following the requested process which the user is allowed access.
-1 Error. See Return_code for an explanation.
Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the w_getpsent service stores the return code. The w_getpsent 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 w_getpsent service can return one of the following values in the Return_code parameter:
Value Explanation
EFAULT An input parameter contained the address of storage where the invoker is not authorized.
EINVAL The process_token is not in the valid range.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

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

Usage notes

  1. Only those processes are returned for which RACF® allows the user access based on its EUid, RUid, or SUid.
  2. The normal user starts with Process_token at zero, and continues calling BPX1GPS with the process token returned in Return_value until the value of 0, end of file, is reached.
  3. PGPSSTARTTIME is in seconds since the Epoch (00:00:00 on 1 January 1970).
  4. PGPSUSERTIME and PGPSSYSTIME are task-elapsed times in 1/100ths of seconds.
  5. The CONTTY, PATH, and CMD input fields are initialized by the BPXYPGPS macro when it is expanded in the program CSECT for a non-reentrant program.
  6. If Buffer_length does not match that used by the callable service, the task sets PGPSLENERR on. This can reflect a change in BPXYPGPS caused by the addition of functions in later releases. This could be intentional: data is returned up to the length specified in Buffer_length. If the length specified is less than the offset of PGPSCONTTYBLEN, BPX1GPS treats the request as if the three BLEN fields were zero.
  7. PGPSSYSTIME reports the system CPU time consumed for the address space that the process is running in. When only one process is running in the address space, this time represents the accumulated system CPU time for that process. However, when more than one process is running in an address space, the information that is returned is actually the accumulated system CPU time consumed by all of the work running in the address space.

Characteristics and restrictions

None.

Examples

The following example starts with the first process (relative process zero) and reports the status for all processes for which the invoker is allowed access (by the security access facility).

The program is reentrant and should be link-edited with RENT in the IEWL PARM. 
BOOKSAM4 CSECT ,                     Reentrant linkage
BOOKSAM4 AMODE 31
BOOKSAM4 RMODE ANY
         USING *,R15                 Program addressability
@BEGIN0  B     @BEGIN1               Branch around program header
         DROP  R15
         DC    C'Sequential w_getpsent'
         DS    0H
@BEGIN1  STM   R14,12,12(13)         Save caller's registers
         LR    R2,13                 Hold address of caller's area
         LR    R3,R1                 Hold parameter register
         LR    12,R15                R12 program base register
         USING @BEGIN0,12            Program addressability
         L     R0,@SIZEDAT           Size this program's dynamic area
         GETMAIN RU,LV=(0)           Getmain dynamic storage
         LR    13,R1                 R13 -> this program's dynamic/save
         USING @DYNAM,13             Dynamic addressability
         ST    R2,@BACK              Save caller's save area pointer
         ST    13,8(,R2)             Give caller out save area
         LR    R1,R3                 Restore parameter register
@BEGIN2  EQU   *  *  *  *  *  *  *   End of the entry linkage code
         SPACE ,
         MVC   WTOHEAD,WTOCONS       Initialize WTO line
         MVI   DOT,C'.'
* If BPX1GPS has been link-edited with this program, the V-CON will be
* resolved; if not, BPX1GPS must be loaded.  In either case, the address
* of the module is stored.
         ICM   R0,B'1111',GPSVCON    BPX1GPS address if link edited
         BNZ   STGPSEP               Branch to store GPS entry point
         LOAD  EP=BPX1GPS            Load w_getpsent stub
STGPSEP  ST    R0,GPSENTRY           Store BPX1GPS entry point
* Initialize the variables and enter the loop.
         XC    PROCTOKEN,PROCTOKEN   Start with 1st process
         MVC   PGPSCONTTYBLEN,=A(L'PGPSCONTTYBUF)  Controlling TTY
         LA    R2,PGPSCONTTYBUF
         ST    R2,PGPSCONTTYPTR
         MVC   PGPSPATHBLEN,=A(L'PGPSPATHBUF)      Path name
         LA    R2,PGPSPATHBUF
         ST    R2,PGPSPATHPTR
         MVC   PGPSCMDBLEN,=A(L'PGPSCMDBUF)        Command
         LA    R2,PGPSCMDBUF
         ST    R2,PGPSCMDPTR
         LA    R2,PGPS               Address of PGPS buffer
         ST    R2,PGPSA
         SPACE ,
GETPS    L     R15,GPSENTRY          Address of BPX1GPS load module
         CALL  (15),                 Get process data                  +
               (PROCTOKEN,           Relative process token            +
               PGPSL,                Length of buffer                  +
               PGPSA,                Buffer, mapped by BPXYPGPS        +
               RETVAL,               Return value (next, eof or error) +
               RETCODE,              Return code                       +
               RSNCODE),             Reason code                       +
               VL,MF=(E,PLIST)       ----------------------------------
         SPACE ,  *  *  *  *  *  *   Test for end of file
         ICM   R2,B'1111',RETVAL     Load return value, set CCode
         BZ    RETURN                0 is end of file
         BL    RETURNRC              -1 is error
         ST    R2,PROCTOKEN          Store the next process token
         SPACE ,  *  *  *  *  *  *   Initialize WTO area & message
         MVI   XPID,C' '             Blank variable portion of line
         MVC   XPID+1(WTO#BLANK-1),XPID
* Convert the process ID to printable hex.
         L     R8,PGPSPID            R8 = process ID
         LA    R9,XPID               To be placed at message start
         LA    R15,8                 8 nibbles to convert (4 bytes)
         LA    R10,9                 For 0-9 / A-F compare
NIBBLE   LR    R11,R8                Target bits in 0-3     XYYYYYYZ
         SRL   R11,28                Bits 0-3 to 28-31      0000000X
         SLL   R8,4                  Drop bits 0-3 off end  YYYYYYZ0
         CLR   R11,R10               Are 4 bits 0-9 or A-F
         BC    B'0010',AF            Branch if A-F
         LA    R11,57(,R11)          Add for 0-9 (57+183=240 or F0)
AF       LA    R11,183(,R11)         Add for 0-F (183+10=193 or C1)
         STC   R11,0(,R9)            Store to results location
         LA    R9,1(,R9)             Increment R9 to next location
         BCT   R15,NIBBLE            Decrement half byte counter, loop
* Go after the state of the process
         MVI   THREAD,C'1'                Assume single task thread
         TM    PGPSSTATUS1,PGPSMULTHREAD  if multithread process
         BZ    NOTMULT
         MVI   THREAD,C'M'
NOTMULT  TM    PGPSSTATUS1,PGPSPTHREAD    if pthread_create task(s)
         BZ    NOTIPT
         MVI   THREAD,C'H'
NOTIPT   MVC   STATE,PGPSSTATUS3          Z, W, X, S, C, F, K, R
         TM    PGPSSTATUS0,PGPSSWAP       if swapped out
         BZ    NOTSWAP
         MVC   SWAPA,=CL4'SWAP'
NOTSWAP  TM    PGPSSTATUS1,PGPSSTOPPED    if stopped
         BZ    NOTSTOP
         MVC   STOPA,=CL4'STOP'
NOTSTOP  TM    PGPSSTATUS1,PGPSTRACE      if ptrace
         BZ    NOTTRAC
         MVC   TRACA,=CL4'TRAC'
NOTTRAC  EQU   *
         SPACE ,  *  *  *  *  *  *   Display message to operator
         WTO   MF=(E,WTOAREA)        Write to Operator
         SPACE ,  *  *  *  *  *  *   Loop back
         B     GETPS                 for the next Process data
         SPACE ,
* * * * *.* * *.* * * * * * * * * * *.* * * * * * * * * * * * * * * * *
RETURN   XR    R15,R15               Zero return code
RETURNRC L     R0,@SIZEDAT           Size this program's dynamic area
         LR    R1,13                 R1 -> this program's dynamic arae
         L     13,@BACK              R2 -> caller's save area
         DROP  13
         FREEMAIN RU,LV=(0),A=(1)
         L     R14,12(,13)           Restore caller's R14
         LM    R0,12,20(13)          Restore caller's R0-R12
         BSM   0,R14                 Branch back to caller
@SIZEDAT DC    A(@ENDYN-@DYNAM)      Size of dynamic storage
         SPACE ,  * * * * * * * * * *.* Program constants * * * * * * *
PGPSL    DC    A(PGPS#LENGTH)        Length of process data buffer
         WXTRN BPX1GPS               Weak to allow link edit or not
GPSVCON  DC    V(BPX1GPS)            Get Process data module
WTOCONS  DS    0CL8                  Constant value for WTOHEAD
         DC    AL2(WTO#LENGTH)         Length of area
         DC    AL2(0)                  WTO flags
         DC    CL4'PID='               Process ID =
         SPACE ,  *  *  *  *  *  *   Dynamic storage variables
@DYNAM   DSECT ,
@SAVE00  DS    0D                    Standard save area - 72 Bytes
         DS    A
@BACK    DS    A                     Backwards savearea pointer
@FORWARD DS    A                     Forwards savearea pointer
         DS    15A                   Regs 14,15,0-12
         SPACE ,
WTOAREA  DS    0F                    WTO message
WTOHEAD  DS    CL8                   Mapped by WTOCONS
XPID     DS    CL8                   Hex of process ID
         DS    CL1
THREAD   DS    CL1                   1, M or H
         DS    CL1
STATE    DS    CL1                   Z, W, X, S, C, F, K, R
         DS    CL1
SWAPA    DS    CL4                   SWAP or blank
         DS    CL1
STOPA    DS    CL4                   STOP or blank
         DS    CL1
TRACA    DS    CL4                   TRAC or blank
WTO#BLANK EQU   *-XPID               Length to blank
DOT      DS    CL1
WTO#LENGTH EQU *-WTOAREA             Length of WTO area
         SPACE ,
GPSENTRY DS    A                     Address of BPX1GPS
PROCTOKEN DS   F                     Relative process token
PLIST    DS    6A                    Calling parameter list
RETVAL   DS    F                     Return value - next PROCTOKEN
RETCODE  DS    F                     Return code
RSNCODE  DS    F                     Reason code
         SPACE ,
PGPSA    DC    A(PGPS)               ->Process data buffer
         BPXYPGPS DSECT=NO,          Place in current dsect            +
               VARLEN=(0,0,0)        ConTty=0,Path=0,Cmd=0
@ENDYN   EQU   *                     End of dynamic storage
         SPACE 3  * * * * * * * * * *.* Register equates  * * * * * * *
R0       EQU   0
R1       EQU   1                     Parameter list pointer
R2       EQU   2
R3       EQU   3
R4       EQU   4
R5       EQU   5
R6       EQU   6
R7       EQU   7
R8       EQU   8
R9       EQU   9
R10      EQU   10
R11      EQU   11
*              12                    Program base register
*              13                    Savearea & dynamic storage base
R14      EQU   14                    Return address
R15      EQU   15                    Branch location
         SPACE ,
         END
Parent topic: Callable services descriptions