(LOGO.JPG) Python for OpenVMS

(go to: table of contents, index, list of vms_sys, prev: SHOW_INTRUSION, next: SUBSYSTEM)


SNDJBCW - Send to Job Controller


The 'vms_sjcdef' module contains bitmasks and constants that are defined in '$SJCDEF'. Access to the item codes ("SJC$_name") is possible via the 'pyvms' module.

Format:

    dict = vms_sys.sndjbcw ([efn], func, [nullarg], [itmlst], \
                            [iosb], [astadr], [astprm])
Returns:
dict
A dictionary that has the following keys:
'status'
The condition value returned from SYS$SNDJBCW. Note that this code only tells whether the system service started successfully. The final status code is in the 'iosb'.
'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.
'SJC$_name'
Any output item that has been specified in the item-list and that is supported by SYS$SNDJBCW.

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

Arguments:
efn
Number of the event flag to be set when SYS$SNDJBCW returns the requested information. If 'None' instead of a number is passed, then EFN 0 is used.
func
Function code ("SJC$_name").
nullarg
Placeholder argument whose value is ignored by the interface routine. You should pass the 'None' object.
itmlst
Item list that gives information for the function that was selected in the 'func' argument.
iosb
I/O status block. An IOSB should ALWAYS be 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$SNDJBCW and returns the object in 'dict'!

astadr
This argument is ignored.
astprm
This argument is ignored.
special notes about some item codes:
SJC$_FILE_IDENTIFICATION
This item is stored in the (28-byte) buffer of the OpenVMS item list by a 'converter function'. The data must supplied as a 3-item tuple in the following format:
device
The device name is passed as 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 passed as a 3-item tuple where each item must be 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 passed as a 3-item tuple where each item must be 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 SJC$_FILE_IDENTIFICATION item code is shown in the examples section.

Examples:


-- submit a batch job using file-specification

$ type SNDJBCW_EXAMPLE.COM
$ mail /subject= "Hello from batch job started by vms_sys.sndjbcw()" -
  NLA0: 'F$GETJPI(0,"USERNAME")'
$ exit
$

$python
>>> import vms_sys

>>> itmlst = ( \
...   ("SJC$_QUEUE",              "HERE_BATCH"), # input items
...   ("SJC$_FILE_SPECIFICATION", "SNDJBCW_EXAMPLE.COM"),
...   ("SJC$_JOB_NAME",           "SNDJBCW-DEMO"),
...   ("SJC$_PARAMETER_1",        "Param-1"),
...   ("SJC$_ENTRY_NUMBER_OUTPUT"),              # output
...   ("SJC$_JOB_STATUS_OUTPUT"),                #  items
...   ("SJC$_HOLD"),                             # boolean
...   ("SJC$_NOTIFY")                            #  items
...  )
>>>
>>> # Note: iosb will be created automatically ------v
>>> dict = vms_sys.sndjbcw (None, "SJC$_ENTER_FILE", None, itmlst)
>>>
>>> for key in dict.keys():
...   print key, '=', dict.get (key)
... #
...
SJC$_JOB_STATUS_OUTPUT = Job SNDJBCW-DEMO (queue HERE_BATCH,\
 entry 44) holding
iosb = <vmsobj_iosb, IOSB at 0x00231330>
SJC$_ENTRY_NUMBER_OUTPUT = 44
status = 1
>>>
>>> # 'status' only tells if SYS$SNDJBCW was started successfully
>>> status = dict.get ('status')
>>> vms_sys.getmsg (status)
('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>
>>> # the final status code of SYS$SNDJBCW is in the first longword
>>> #  of the iosb (I/O status block)
>>> iosb = dict.get ('iosb')
>>> status_final = iosb.l0
>>> print status_final
262145
>>> vms_sys.getmsg (status_final)
('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>

$ show ENTRY /FULL 44
 Entry  Jobname         Username     Blocks  Status
 -----  -------         --------     ------  ------
    44  SNDJBCW-DEMO    ZESSIN               Holding
        On idle batch queue HERE_BATCH
        Submitted 23-MAR-1999 14:05 /NOTIFY /PARAM=("Param-1")
        /PRIORITY=100
 File: _$99$DKA100:[PYTHON.PYTHON-1_5_1.VMS]SNDJBCW_EXAMPLE.COM;2
$

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

-- submit a batch job using file-identification

$ directory /file_id tstfid /notrailing

Directory DKA100:[PYTHON.PYTHON-1_5_1.VMS]

TSTFID.COM;1         (4852,12,0)
$

$ python
>>> import vms_sys
>>>
>>> device = '$99$DKA100:'
>>> fid    = (4852,12,0)
>>> did    = (0,0,0)
>>>
>>> itmlst = ( \
...   ("SJC$_FILE_IDENTIFICATION", (device,fid,did)),
...   ("SJC$_QUEUE",               "HERE_BATCH"),
...   ("SJC$_HOLD"),  # boolean item code, no data
...  )
>>>
>>> dict = vms_sys.sndjbcw (None, "SJC$_ENTER_FILE", None, itmlst)
>>>
>>> for key in dict.keys():
...   print key, '=', dict.get (key)
... #
...
iosb = <vmsobj_iosb, IOSB at 0x0022d2a8>
status = 1
>>>
>>> # 'status' only tells if SYS$SNDJBCW was started successfully
>>> status = dict.get ('status')
>>> vms_sys.getmsg (status)
('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>
>>> # the final status code of SYS$SNDJBCW is in the first longword
>>> #  of the iosb (I/O status block)
>>> iosb = dict.get ('iosb')
>>> status_final = iosb.l0
>>> print status_final
262145
>>> vms_sys.getmsg (status_final)
('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>

$ show entry /full
  Entry  Jobname         Username     Blocks  Status
  -----  -------         --------     ------  ------
     24  TSTFID          ZESSIN               Holding
         On idle batch queue HERE_BATCH
         Submitted 31-MAR-1999 23:29 /PRIORITY=100
         File: _$99$DKA100:[PYTHON.PYTHON-1_5_1.VMS]TSTFID.COM;1
$

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

-- initialize a batch queue

>>> import vms_sys

>>> itmlst = ( \
...   ("SJC$_QUEUE",              "PY_BATCH"),
...   ("SJC$_BATCH"),
...   ("SJC$_JOB_LIMIT",          5),
...   ("SJC$_QUEUE_DESCRIPTION",  "PYTHON-test-queue"),
...   ("SJC$_RETAIN_ERROR_JOBS"),
...   ("SJC$_SCSNODE_NAME",       "HERE"),
...   ("SJC$_WSQUOTA",            5000)
...  )
>>>
>>> # 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()
>>> 
>>> dict = vms_sys.sndjbcw (None, "SJC$_CREATE_QUEUE", iosb, itmlst)
>>>
>>> for key in dict.keys():
...   print key, '=', dict.get (key)
... #
...
iosb = <vmsobj_iosb, IOSB at 0x0022c778>
status = 1
>>> status = dict.get ('status')
>>> vms_sys.getmsg (status)
('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>
>>> iosb = dict.get ('iosb')
>>> status_final = iosb.l0
262145
>>> vms_sys.getmsg (status_final)
('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>

$ show QUEUE /FULL PY_BATCH
Batch queue PY_BATCH, stopped, on HERE::
  <PYTHON-test-queue>
  /BASE_PRIORITY=4 /JOB_LIMIT=5 /OWNER=[G1,SYSTEM]
  /PROTECTION=(S:M,O:D,G:R,W:S) /RETAIN=ERROR /WSQUOTA=5000
$

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

-- delete a job

>>> import vms_sys
>>>
>>> entry = 23
>>>
>>> itmlst = ( \
...   ("SJC$_ENTRY_NUMBER", entry),
...  )
>>>
>>> dict = vms_sys.sndjbcw (None, "SJC$_DELETE_JOB", None, itmlst)
>>>
>>> for key in dict.keys():
...   print key, "=", dict.get (key)
... #
...
iosb = <vmsobj_iosb, IOSB at 0x0022cc60>
status = 1
>>> status = dict.get ('status')
>>> vms_sys.getmsg (status)
('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>
>>> iosb = dict.get ('iosb')
>>> status_final = iosb.l0
>>> print status_final
262145
>>> vms_sys.getmsg (status_final)
('%JBC-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>

--------------------
-- errors

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

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

>>> itmlst = ('SJC$_BATCH',)
>>> dict = vms_sys.sndjbcw (None, "BAD_FUNC", None, itmlst)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 2: invalid function code: BAD_FUNC
>>>

>>> # SJC$_BATCH is an item code, not a function code
>>> itmlst = ('SJC$_BATCH',)   #   vvvvvvvvvv
>>> dict = vms_sys.sndjbcw (None, "SJC$_BATCH", None, itmlst)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 2: not a valid function code: SJC$_BATCH
>>>

@@ more SNDJBCW examples
>>>

(go to: table of contents, index, list of vms_sys, prev: SHOW_INTRUSION, next: SUBSYSTEM)

10-NOV-1999 ZE.