JOUT 55 - manipulate job output.

Usage:

drl    jout
zero   function,L(arglst)
zero   L(status),L(sydkin)

Where:

function

Defines the JOUT subfunction to be performed.

1: Access job output (mark JOUT busy).
2: Allocate a PAT body.
3: Update the PAT to point to a specific sysout link.
4: Direct output to central site.
5: Direct output to remote id.
6: Discard the job (JOUT command RELEASE).
7: Deaccess job (JOUT command HOLD.)
8: Deallocate PAT.
9: Special update JOUT PAT.
10: Make arbitrary sysout queue entry.
11: Fetch JOT and blink info for job.

arglst

Points to a work area used to pass information for both input and output. The exact format and length depends on the particular function being performed. See below in the individual function descriptions.

status

Points to a single output status return word. The interpretation depends on the particular function.

sydkin

Normally this should be zero. However, for function 2 (allocate PAT), it can point to a three output area where DRL JOUT will store some information about the characteristics of the disk holding the first sysout spool area.

Description:

DRL JOUT is primarily used to by the JOUT subsystem to manipulate batch job output in the system spool area. The usual sequence of events is:

Mark the job busy (function 1).
Allocate a PAT (function 2) to use when reading the output data.
Update the PAT to point to individual links of the spooled output (function 3), and use DRL PDIO to read the data in those links. This is repeated as often as needed.
Deaccess the job with one of the calls that specifies a job disposition (functions 4, 5, 6, 7, or possibly 10).
Deallocate the PAT (function 8).

In addition, function 10, may be used to accomplish specific actions by sending almost arbitrary queue entries to GEOT. Function 11, is used to obtain a copy of the JOT entry, and a list of starting blinks for this job.

Besides its use in manipulating sysout, DRL JOUT can be used along with DRL PDIO to access arbitrary locations on disk. In this case just the allocate PAT, special update, and deallocate PAT functions would be used. See the special PAT update description below.

Function 1, access job

This function sends a queue entry to GEOT requesting a job be marked busy. It then waits for a reply from GEOT. The 3 word reply message is returned to the subsystem in registers X6, X7 A and Q. Because this function uses the allocated PAT field of the UST (.LACPT), it must be issued BEFORE function 2 (allocate PAT).

arglst

is a two word input area that identifies the job being accessed. Usually the job is identified by the SNUMB, but since that is not always unique, the J* blink number can be used instead. A zero in the blink number field indicates that DRL JOUT should use the SNUMB instead to look up the job. Note that the Sysout ID (SID) used for some GEOT commands is the J* blink number times 10.

arglst null
snumb  bci     1,SSSSS    Bits 30-35 ignored
jobid  zero    blink,0    J* blink in bits 3-17

status

-1: GEOT queue is full, no action taken.
0: this should mean that the request was successful, and other information is in X6, A and Q. However, there is a bug in TSS, and it just means that the detailed status in X6 should be checked.
>0: status values greater than zero are indicate that the job has not yet been passed to sysout (still executing etc.). The values should be the same as those returned by DRL JSTS. Note that in sr5.0, and prior releases this is not done properly, so you should use DRL JSTS instead.

X6

The upper half of the first reply queue word from GEOT is returned in X6. For this reason the upper 6 bits are usually 9 (octal 11).

bits 0-11, status

0002: request rejected, .LJSNB is non-zero, no queue entry was sent to GEOT. That is, this TSS session already has a job marked busy. The job identified by .LJSNB in the UST should be freed first.
1101: snumb not found in JOT.
1102: job is already marked busy by some other user.
1103: job found in JOT, but the output has already been released.
1104: job successfully marked busy in JOT, and .LJSNB set in UST.
1105: job found in JOT, but belongs to another user.
1106: This status should not occur, and indicates something unknown happened inside GEOT.

bits 12-17, urgency

if the job was successfully marked busy (status 1104), then this will be the output urgency of the job. In all other cases these bits will be set to zero.

X7

The lower half of the first reply queue word is returned here. Currently this has no useful information.

A

The second word of the reply queue is returned here.

bits 0-8, job trademark: This is a check value that can be tested against some of the spooled data on disk. It is only meaningful on a successful reply (status 1104).
bits 9-17: undefined
bits 18-35, UST address: this was echoed back by GEOT so TSS could match the reply from GEOT with the TSS user making the request.

Q

This is the third queue reply word. For a successful request, it is a copy of the J.JOBL word of the JOT entry. In particular, bits 3-17 have the SID (J* blink number) for the job. This value can be used to read the sysout data, and should be used instead of the snumb for subsequent calls about this job.

Function 2, allocate a PAT

This function allocates a PAT for subsequent use with DRL PDIO. There is no exchange of queue messages with GEOT.

arglst

is a one word output area where TSS will store an identifier (handle) for the allocated PAT. This handle is then used with DRL PDIO, and in the 'update PAT', and 'release PAT' functions of DRL JOUT. Bits 0-17 are set to the offset in the PAT segment of the PAT pointer word, and bits 24-35 contain a generated file code used for 'sanity checks'.

status

0: PAT allocated and handle stored in arglst.
-1
-3: request rejected, this UST already has a JOUT PAT allocated.

sydkin

This optional buffer is a three word output area where TSS will store some SYsout DisK INformation. The area must be double word aligned. Currently TSS always stores the same values so the area will be set like.

       even
sydkin zero    0,12   number of llinks per link
       zero    12,0   number of llinks per link
       zero    0,4    number of llinks per "fence"

It is not known if any calls to DRL JOUT ever request this information since it is always constant. At one time (under GcosIII) the "fence" value might be returned as a 12, but today no one recalls what the significance of a "fence" was.

Function 3, regular PAT update

This function updates the device and offset fields of the JOUT PAT to point to a specific link in the sysout spool area.

arglst

is a two word input area with the PAT handle, the link number, and an optional pointer to an output sector size word.

arglst null
handle dec     *-*       result from func 2
       zero    link#,    put the link number here
       etc     L(secsiz) point to sector size word

secsiz

This is an optional one word output area. If specified, TSS will store the size of a sector in words into the upper 18 bits. Since this value is always 64, it is normally not requested. (I.e. bits 18-35 of arglst+1 are zero.)

status

zero: PAT successfully updated.
non-zero: update failed. PAT handle not valid.

Function 4, direct to central site

Clears the .LJSNB field in the UST, and sends a queue entry to GEOT. The queue entry asks GEOT to clear the "JOUT busy" and "JOUT hold" state bits, and send the output to the central site printers. Any output originally destined for remote stations will be redirected to the central site. Currently no reply is requested from GEOT, and DRL JOUT keeps retrying if the GEOT queue is full.

arglst

is a two word area identifying the job by snumb or J* blink. This is formatted the same as the arglst for function 1 (access job). It is is probably best to use the J* blink number returned from function 1.

arglst null
snumb  bci     1,SSSSS    Bits 30-35 ignored
jobid  zero    blink,0    J* blink in bits 3-17

status

is set to zero.

Function 5, direct to remote site

This behaves almost the same as function 4, but all output is redirected to a specific remote station.

arglst

is a three input word area that identifies the the job and remote station. The first 2 words are the same as functions 1 and 4 though 7; the third gives the remote station id.

arglst null 
snumb  bci     1,SSSSS    Bits 30-35 ignored
jobid  zero    blink,0    J* blink in bits 3-17
stnid  vfd     24/0,h12/** BCD remote id

Function 6, discard output

This behaves much the same as function 4, but the output is discarded.

arglst: is a two word input area identifying the job. It is formatted the same as function 4.

Function 7, deaccess job

This behaves like function 4, but GEOT only clears the "JOUT busy" state bit, and the output is left as is. The "hold for JOUT" state bit is left set.

arglst: is a two word area identifying the job. It is formatted the same as function 4.

Function 8, deallocate PAT

This releases the JOUT PAT allocated by function 2. This should always be done before exiting the subsytem, or calling another subsystem. Failure to deallocate the JOUT PAT can result in TSS running out of PAT space.

arglst

is a 1 word input area with the data returned by function 2.

status

0: PAT released.
-4: bad PAT handle in arglst
-5: PAT already released.

Function 9, special update PAT

This works something like function 3, except that the caller is not restricted to the areas of disk used for sysout spooling. The caller specifies a disk SCT and a starting location; the JOUT PAT is updated to point to that area.

For AU oriented devices (ASD disks), the starting location is expressed in allocation units, and the extent size will be set to the larger of 1 AU, or 12 llinks. For all other disks, the starting location is expressed in llinks, and the extent size always be 12 llinks.

Although DRL JOUT will allow you to point the PAT anywhere, if you point the PAT at location zero, the seek address used for DRL PDIO may not refer to sectors 0 to 4. I.e. you may not access the label llink of the disk.

arglst

is a two word input area which specifies the PAT. the SCT of the disk, and the starting location.

arglst null
handle dec     *-*       result from func 2
       zero    sct,      SCT for the disk
       etc     start     starting llink or au

status

0: PAT updated successfully.
1: update failed, PAT handle not valid.

Function 10, make GEOT queue entry

This function is a generalized method of sending requests to GEOT, and can be used instead of functions 4 to 7, and to make other requests such as a partial redirect. In particular, it is the only method of requesting that GEOT unbusy a job from JOUT, and send the output to the destination(s) requested by the JCL. (I.e. don't redirect it all to a specific site.)

It is possible to perform functions that wait for a reply from GEOT. If so the reply will be returned in registers X6, X7, and the AQ as described for function 1. For example, you could access a job this way instead of using function 1, and TSS would update the appropriate UST fields. However, this approach is NOT recommended.

arglst

This is a 6 word area with an image of the GEOT queue entry. See the system tables manual, and the GEOT listing for details of the fields. Although TSS wants a full 6 words, only the first 4 are used. The last two words (fields G.4QUE and G.5QUE) of the entry actually sent will be the userid from .LUID in the UST.

status

0: Queue entry sent.
-1: GEOT queue full, try later.

Function 11, get job info

This function returns a copy of the JOT entry for a job, and a list of blink information words (SD.SBT entries) for the job. Only the blink words marked with BT.1ST are returned, so it is not clear if any useful information can be obtained from them. There is no exchange of queue messages with GEOT.

No explicit indication is given if the returned data is truncated because the buffer is too small. However, since there will be 1 blink word for each JOT destination word in the JOT, the required buffer size can be computed from the JOT field JC.SIZ.

arglst

This is a two word input area that identifies the job, and describes the output buffer. The first word identifies the job by either the snumb, or the J* blink. The second word describes the buffer.

arglst null
snumb  vfd     h30/SNUMB,
       etc     2/0,1/1,3/0 Bit 32-> SNUMB
       zero    L(buffer),  Point to buffer
       etc     bwords      length in words
  or
arglst null
jobid  vfd     3/0,15/blink, J* blink #
       etc     15/0,1/1,2/0  bit 33 -> blink
       zero    L(buffer),  Point to buffer
       etc     bwords      length in words

status

0: JOT data stored into buffer.
-1: SD.JOT table is busy, try later.
-2: No matching entry found in SD.JOT.

JOUT 55 - manipulate job output.

Usage:

Where:

Description:

Function 1, access job

Function 2, allocate a PAT

Function 3, regular PAT update

Function 4, direct to central site

Function 5, direct to remote site

Function 6, discard output

Function 7, deaccess job

Function 8, deallocate PAT

Function 9, special update PAT

Function 10, make GEOT queue entry

Function 11, get job info

See Also: