(LOGO.JPG) Python for OpenVMS

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


GETQUIW - Get Queue Information


This routine allows the programmer to receive a single or several items of queue information. The vms_lib.getqui() routine provides support for only a single item, but uses a much simpler interface. On the other hand, for repeated access to the same object one has to 'freeze' the context.

Note: the 'vms_quidef' module contains bitmasks and constants that are defined in '$QUIDEF'. Access to the item codes ("QUI$_name") is possible via the 'pyvms' module.
Format:

    dict = vms_sys.getquiw ([efn], func, [context], [itmlst], \
                            [iosb], [astadr], [astprm])
Returns:
dict
A dictionary that has the following keys:
'status'
The condition value returned from SYS$GETQUIW. Note that this code only tells whether the system service started successfully. The final status code is in the 'iosb'.
'context'
Number of a context stream when wildcard processing is done. This key is only present when the 'context' argument below has been used.
'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.
'QUI$_name'
Any output item that has been specified in the item-list and that is supported by SYS$GETQUIW.
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$GETQUIW 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$GETQUIW returns the requested information. If 'None' instead of a number is passed, then EFN 0 is used.
func
Function code specifying the function that SYS$GETQUIW is to perform.
context
Use 'None' to indicate that no context stream is to be used or -1 to create a new context stream. After a call the updated value is returned as key 'context' in the dictionary 'dict'.
itmlst
Item list specifying which information is to be returned. You must specify a tuple of strings/ tuples. See the examples below.

It is possible to put an item tuple - e. g.: ('QUI$_ACCOUNT',None) - instead of a single string - e. g.: 'QUI$_ACCOUNT' -, 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$GETQUIW and returns the object in 'dict'!

astadr
This argument is ignored.
astprm
This argument is ignored.
special notes about some item codes:
QUI$_FILE_IDENTIFICATION
This item is stored in the (28-byte) buffer of the OpenVMS item list and returned to Python by a 'converter function'. The data is stored in a 3-item tuple with the following format:
device
The device name is a string with a maximum length of 15 characters. This is internally stored as an ASCIC - the first byte is the length.
fid
The file identification is returned as a 3-item tuple where each item is a 16-bit integer. Internally this is stored as an array of 3 words. The first item is the file-number. the second item is the sequence numer. The third item is the relative volume number.
did
The directory file identification is returned as a 3-item tuple where each item is a 16-bit integer. Internally this is stored the same way as the 'fid' that is described above.
An example of how to use the QUI$_FILE_IDENTIFICATION item code is shown in the examples section.

Examples:

>>> import vms_sys

---------------

>>> # a simple call and analysis of returned data
>>> #
>>> # Note: no IOSB was specified, but the interface routine creates
>>> #       one anyway and returns it in 'dict'.
>>> itmlst  = ( ("QUI$_SEARCH_NAME",'*'), ("QUI$_QUEUE_NAME") )
>>> context = -1
>>> dict    = vms_sys.getquiw (None, "QUI$_DISPLAY_QUEUE", \
...                            context, itmlst)
>>>
>>> # 'status' only tells if $GETQUIW 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))
>>>
>>> for key in dict.keys():
...   print key, '=', dict.get(key)
... #-for
...
QUI$_QUEUE_NAME = BATQ_BACKUP
context = 1
iosb = <vmsobj_iosb, IOSB at 0x0022da88>
status = 1
>>>
>>> # The final status code of $GETQUIW is in the first longword
>>> #  of the iosb (I/O status block).
>>> iosb         = dict.get ('iosb')
>>> status_final = iosb.l0           # status is in first longword
>>> print status_final
262145
>>> print vms_sys.getmsg (status_final)
('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>
>>> print dict.get ('QUI$_QUEUE_NAME')
BATQ_BACKUP
>>>
>>> # The context must be fed as argument to the next call
>>> #  when using a loop.
>>> context = dict.get ('context')
>>> print context
1
>>>


>>> # Release this context and use an explicit IOSB.
>>> #
>>> # 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()
>>> print iosb
<vmsobj_iosb, IOSB at 0x0022da10>
>>>
>>> dict = vms_sys.getquiw (None, 'QUI$_CANCEL_OPERATION', \
...                         context, None, iosb)
>>>
>>> for key in dict.keys():
...   print key, '=', dict.get(key)
...
iosb = <vmsobj_iosb, IOSB at 0x0022da10>
context = 1
status = 1
>>>
>>> iosb   = dict.get ('iosb')
>>> status = iosb.l0
>>> print vms_sys.getmsg (status)
('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>
>>> print iosb
<vmsobj_iosb, IOSB at 0x0022da10>
>>> # same memory address ^^^^^^^^^
>>>

--------------------

>>> # loop over all queues and show their names and
>>> #  description texts
>>>
>>> import vms_sys
>>>
>>> itmlst = (("QUI$_SEARCH_NAME",'*'),
...           ("QUI$_QUEUE_NAME"),
...           ("QUI$_QUEUE_DESCRIPTION")
...          )
>>> context = -1
>>>
>>> while (1):
...   dict = vms_sys.getquiw (None, "QUI$_DISPLAY_QUEUE", \
...                           context, itmlst)
...   status = dict.get ('status')
...   if not (status & 1):
...     print '*', vms_sys.getmsg (status)
...     break                               # abort loop
...   else:
...     iosb = dict.get ('iosb')
...     status = iosb.l0
...     if not (status & 1):
...       print vms_sys.getmsg (status)
...       break                             # abort loop
...     else:
...       queue_name        = dict.get ('QUI$_QUEUE_NAME')
...       queue_description = dict.get ('QUI$_QUEUE_DESCRIPTION')
...       print "%s (%s)" % (queue_name, queue_description)
...       context = dict.get ('context')    # feed into next call
...
BATQ_BACKUP ()
BATQ_BATCH ()
BATQ_RAYTRACE01 ()
BATQ_RAYTRACE02 ()
BATQ_SYSTEM ()
HERE_BACKUP ()
HERE_BATCH ()
HERE_PRINT ()
HERE_RAYTRACE01 (Raytracing, PRIO:1)
HERE_RAYTRACE02 (Raytracing, PRIO:2)
HERE_SYSTEM ()
UUCP_BATCH (UUCP Daemons and Administrative Processing)
('%JBC-E-NOMOREQUE, no more queues found', (0, 0, 0, 0))
>>>

---------------

>>> # This code loops over all queues, all jobs in all queues and
>>> #  all files of all jobs.
>>> #
>>> # The prompt characters are not included to save some width
>>> #  for the printed documentation

import vms_quidef, vms_sys
#
itmlst_queue = (("QUI$_SEARCH_NAME",'*') \
                ,"QUI$_QUEUE_NAME"       \
                ,"QUI$_QUEUE_DESCRIPTION"
               )

itmlst_job   = (("QUI$_SEARCH_FLAGS",                  \
                     vms_quidef.QUI_M_SEARCH_ALL_JOBS+ \
                     vms_quidef.QUI_M_SEARCH_WILDCARD) \
                ,"QUI$_JOB_NAME"                       \
                ,"QUI$_ENTRY_NUMBER"                   \
                )

itmlst_file  = (("QUI$_SEARCH_FLAGS",                  \
                     vms_quidef.QUI_M_SEARCH_WILDCARD) \
                ,"QUI$_FILE_IDENTIFICATION"            \
                ,"QUI$_FILE_SPECIFICATION"             \
               )

context = -1    # create a new wildcard context
while 1:
  dict = vms_sys.getquiw (None, "QUI$_DISPLAY_QUEUE", \
                          context, itmlst_queue)
  status = dict.get ('status')
  if not (status & 1):
    print '[q1]',vms_sys.getmsg (status)
    break
  else:
    iosb   = dict.get ('iosb')
    status = iosb.l0
    if not (status & 1):
      print '[q2]',status, vms_sys.getmsg (status)
      break
    else:
      queue_name        = dict.get ('QUI$_QUEUE_NAME')
      queue_description = dict.get ('QUI$_QUEUE_DESCRIPTION')
      print "%s (%s)" % (queue_name, queue_description)
      context = dict.get ('context')    # feed into next call
      #
      while (1):
        dict = vms_sys.getquiw (None, "QUI$_DISPLAY_JOB", \
                                context, itmlst_job)
        status = dict.get ('status')
        if not (status & 1):
          print '[j1]',vms_sys.getmsg (status)
          break
        else:
          iosb   = dict.get ('iosb')
          status = iosb.l0
          if not (status & 1):
            print '[j2]',status, vms_sys.getmsg (status)
            break
          else:
            job_name        = dict.get ('QUI$_JOB_NAME')
            job_entry       = dict.get ('QUI$_ENTRY_NUMBER')
            print "%d (%s)" % (job_entry, job_name)
            context = dict.get ('context')    # feed into next call
            #
            while (1):
              dict = vms_sys.getquiw (None, "QUI$_DISPLAY_FILE", \
                                      context, itmlst_file)
              status = dict.get ('status')
              if not (status & 1):
                print '[f1]',vms_sys.getmsg (status)
                break
              else:
                iosb   = dict.get ('iosb')
                status = iosb.l0
                if not (status & 1):
                  print '[f2]',status, vms_sys.getmsg (status)
                  break
                else:
                  file_ident = dict.get ('QUI$_FILE_IDENTIFICATION')
                  file_spec  = dict.get ('QUI$_FILE_SPECIFICATION')
                  print file_ident
                  print file_spec
                  context = dict.get ('context') # feed into next call
                  #
            # while (file)
      # while (job)
# while (queue)

** This is the output - the example was run on a different system
**  than which is normally used for development so you see
**  other queue / device names.

BATQ_BACKUP ()
[j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0))
BATQ_BATCH ()
[j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0))
BATQ_SYSTEM ()
[j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0))
FM_TE_LA (HP Laserjet 4+)
[j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0))
NET1_PS (HP Laserjet 5/via PS-converter)
[j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0))
NET_1 (HP Laserjet 5)
[j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0))
ROCH_BACKUP ()
[j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0))
ROCH_BATCH ()
2 (DEMO1)
('_ROCH$DKC300', (15393, 22, 0), (21027, 9, 0))
_ROCH$DKC300:[USER.ZESSIN.WWW]DEMO1.COM;1
[f2] 295314 ('%JBC-E-NOMOREFILE, no more files found', (0, 0, 0, 0))
[j2] 295330 ('%JBC-E-NOMOREJOB, no more jobs found', (0, 0, 0, 0))
ROCH_LN15 ()
[j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0))
ROCH_SYSTEM ()
3 (DEMO1)
('_ROCH$DKC300', (15393, 22, 0), (21027, 9, 0))
_ROCH$DKC300:[USER.ZESSIN.WWW]DEMO1.COM;1
('_ROCH$DKC300', (9206, 34, 0), (21027, 9, 0))
_ROCH$DKC300:[USER.ZESSIN.WWW]DEMO2.COM;1
[f2] 295314 ('%JBC-E-NOMOREFILE, no more files found', (0, 0, 0, 0))
4 (DEMO1)
('_ROCH$DKC300', (15393, 22, 0), (21027, 9, 0))
_ROCH$DKC300:[USER.ZESSIN.WWW]DEMO1.COM;1
('_ROCH$DKC300', (9206, 34, 0), (21027, 9, 0))
_ROCH$DKC300:[USER.ZESSIN.WWW]DEMO2.COM;1
[f2] 295314 ('%JBC-E-NOMOREFILE, no more files found', (0, 0, 0, 0))
[j2] 295330 ('%JBC-E-NOMOREJOB, no more jobs found', (0, 0, 0, 0))
SYS$BATCH ()
[j2] 294978 ('%JBC-E-NOSUCHJOB, no such job', (0, 0, 0, 0))
[q2] 295338 ('%JBC-E-NOMOREQUE, no more queues found', (0, 0, 0, 0))
>>>

--------------------

>>> dict = vms_sys.getquiw ('BADEFN', 'QUI$_DISPLAY_JOB')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 1: efn - must be integer or None
>>>


>>> dict = vms_sys.getquiw (None, 'QUI$_QUEUE_NAME')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 2: func - not a function code:QUI$_QUEUE_NAME
>>>


>>> dict = vms_sys.getquiw (None, 'QUI$_DISPLAY_JOB', 'BADCTX')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 3: context - must be integer or None
>>>


>>> itmlst = ( 'QUI$_ERR', )
>>> dict = vms_sys.getquiw (None, 'QUI$_DISPLAY_JOB', \
...                         None, itmlst)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: itmlst - unknown item code: QUI$_ERR
>>>


>>> itmlst = ( 'QUI$_ENTRY_NUMBER', )
>>> dict = vms_sys.getquiw (None, 'QUI$_DISPLAY_JOB', \
...                         None, itmlst, 'X')
>>> # IOSB or None expected ---------------^
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 5: iosb - must be vmsobj_iosb or None
>>>

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

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

31-MAY-1999 ZE.