(PYVMS LOGO) Python on OpenVMS

(go to: table of contents, index, list of vms_sys, prev: FORMAT_ACL, next: GETMSG)


GETJPIW - Get Job/Process Information


This routine allows the programmer to receive a single or several items of information per call from the specified process. The vms_lib.getjpi() routine provides support for only a single item, but uses a much simpler interface.

Note: the 'vms_jpidef' module contains bitmasks and constants that are defined in '$JPIDEF'. Access to the item codes ("JPI$_name") is possible via the 'pyvms' module.

Format:

    dict = vms_sys.getjpiw ([efn] [,pidadr] [,prcnam], itmlst \
                            [,iosb] [,astadr] [,astprm])
Returns:
dict
A dictionary that has the following keys:
'status'
The condition value returned from SYS$GETJPIW. Note that this code only tells whether the system service started successfully. The final status code is in the 'iosb'.
'pidadr'
The process identification of the target process or a context value of a wildcard operation. See additional comments at the 'pidadr' argument below.
'iosb'
A 'vmsobj_iosb' object that provides storage for the OpenVMS IOSB (I/O status block). See the description of 'status' above and the 'iosb' argument below.
'JPI$_name'
Any output item that has been specified in the item-list and that is supported by SYS$GETJPIW.
Note that the 'data' that is returned can itself be a tuple for some items - see below.

It is only put into the dictionary, when SYS$GETJPIW returns a success status.

A 'counted ASCII string' (ASCIC) - which means that the first byte contains the string length - is returned as a normal string (one without the count byte at the beginning). You can use Python's len() function to find out how long the returned string is.

Arguments:
efn
Number of the event flag to be set when SYS$GETJPIW returns the requested information. If 'None' instead of a number is passed, then EFN 0 is used.
pidadr
Process identification (PID) of the target process or a pid-context that can be used for the next step in a wildcard lookup.

Note that vms_sys.process_scan() can be used to establish a context to select a subset of processes.

prcnam
Name of process to lookup. Normally 'pidadr' overrides 'prcnam'! Use 'pidadr' = 'None' to force usage of 'prcnam'.
itmlst
Item list specifying which information from the specified process is to be returned. You must specify a tuple of strings. See the examples below.

It is possible to put an item tuple - e. g.: ('JPI$_PRCNAM',None) - instead of a single string - e. g.: 'JPI$_PRCNAM' -, but this is not required for output-only items.

iosb
I/O status block. An IOSB should ALWAYS specified, because this is the only place that contains the status code AFTER the system service completed. 'status', as returned only gives information whether the system service has been started successfully.

The Python interface routine expects a vmsobj_iosb object. If the programmer specifies 'None' for the iosb argument, then the interface routine automatically generates a vmsobj_iosb object, passes the OpenVMS IOSB to SYS$GETJPIW and returns the object in 'dict'!

astadr
This argument is ignored.
astprm
This argument is ignored.
Examples:
>>> import vms_sys

>>> # Note: no IOSB is specified, but the interface routine creates
>>> #       one anyway and returns it in 'dict'.
>>> itmlst = ( ('JPI$_PRCNAM',), ('JPI$_ACCOUNT',) )
>>> # pidadr = 0 means current process
>>> #                             v
>>> dict = vms_sys.getjpiw (None, 0, None, itmlst)
>>> for key in dict.keys():
...   print key, '=', dict.get(key)
... #-for
...
JPI$_PRCNAM = ZESSIN_FTA14
pidadr = 341    <-- the real PID is always returned
iosb = <vmsobj_iosb, IOSB at 0x00218bd8>
JPI$_ACCOUNT = HOME
status = 1
>>>

>>> # 'status' only tells if $GETJPIW was started successfully
>>> status = dict.get ('status')
>>> print status
1
>>> print vms_sys.getmsg (status)
('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>

>>> # The final status code of $GETJPIW is in the first longword
>>> #  of the iosb (I/O status block).
>>> iosb = dict.get ('iosb')
>>> status_final = iosb.l0
>>> print status_final
1
>>> print vms_sys.getmsg (status_final)
('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>


>>> # Create an iosb object and pass it to the interface routine -
>>> #  the same object will be returned in 'dict'.
>>> import pyvms
>>> iosb = pyvms.vmsobj_iosb()
>>> 
>>> itmlst = ( ('JPI$_PRCNAM',), ('JPI$_ACCOUNT',) )
>>> dict = vms_sys.getjpiw (None, 0, None, itmlst, iosb)
>>> for key in dict.keys():
...    print key, '=', dict.get(key)
... #-for
...
JPI$_PRCNAM = ZESSIN_FTA14
pidadr = 341
iosb = <vmsobj_iosb, IOSB at 0x0021c208>
JPI$_ACCOUNT = HOME
status = 1
>>>
>>> # same id means same object
>>> id (iosb)
2209888
>>> dict_iosb = dict.get('iosb')
>>> id (dict_iosb)
2209888
>>>



>>> itmlst = ( ('JPI$_PRCNAM',), ('JPI$_ERR',) )
>>> dict = vms_sys.getjpiw (None, 0, None, itmlst)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: itmlst - unknown item code: JPI$_ERR
>>>

>>> itmlst = ( ('JPI$_PRCNAM',), ('JPI$_ACCOUNT',) )
>>>
>>> # vmsobj_iosb or None expected -----------------v
>>> dict = vms_sys.getjpiw (None, 0, None, itmlst, 'X')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 5: iosb - must be vmsobj_iosb or None
>>>

@@ more vms_sys.getjpiw() examples
>>>

(go to: table of contents, index, list of vms_sys, prev: FORMAT_ACL, next: GETMSG)

12-JUN-1999 ZE.