Skip to content

Latest commit

 

History

History
183 lines (160 loc) · 6.91 KB

hercjos.md

File metadata and controls

183 lines (160 loc) · 6.91 KB

hercjos: Hercules Job Output System

Table of content

Synopsis

  hercjos [OPTIONS]...

Description

hercjos is yet another sockdev printer for Hercules. Simple, open source, and at this point handling only JES2 output as generated by MVS 3.8J as distributed in the tk4- system. The basic operation is

  • connect to a printer sockdev device (see -a option) or open an input file (see -i option)
  • scan the input for a banner page
  • extract job type. job number, job name, user name, printer name and the time stamp from the banner page
  • open a file with a configurable naming pattern (see -p option) and write the job output into this file, the banner and trailer pages can be omitted (see -db and -dt options).
  • run optionally a post-processing command (see -c option)

The net effect is that the printer output stream is split into a set of files, containing one job each, with naming pattern like

2018-04-07-07:55:27_J0032_PERF-ASM.prt
2018-04-07-08:00:19_J0033_PERF-ASM.prt
2018-04-07-08:05:02_J0034_PERF-ASM.prt
...
2018-04-07-11:47:47_S0046_MF1.prt
2018-04-07-11:59:23_J0062_SHUTDWN.prt
2018-04-07-12:00:13_S0047_TSO.prt

Options

Option Description
-a nam:port sockdev address, default localhost:14030
-i file use file as input source
-p pat set file name pattern
-db drop banner pages
-dt drop trailer pages
-c post processing command
-t trace input
-h print help text

-a nam:port

hercjos uses as default address localhost:14030, often used when the primary printer is setup as a sockdev device. The -a option allows to specify a different address in the formats

  • port (only digits; host defaults to localhost)
  • host (port defaults to 14030)
  • host:port

-i file

Will use file as input source instead of connecting to a sockdev device. Can be used to convert existing files like prt00e.txt.

-p pat

Defines the file name pattern used to generate the file names for individual jobs. Default is %D_%J_%N.prt. The available specifiers are

Spec Content
%T job type, either JOB, TSO, or STC
%J job number in the form Jxxxx, Txxxx, or Sxxxx
%N job name
%U user name
%R room name
%P printer name
%D date/time in the format yyyy-mm-dd:hh:mm:ss

All fields are sanitized, #, @ and $ are first mapped to -, all characters other than letters, digits and - are discarded. The pattern can contain / characters, in that case the job files will be organized in directories, which will be created as needed.

-db

Banner pages will no be written to the job output files. Since all relevant information contained in the banner page is usually encoded already in the file name there is in practice little need to keep them.

-dt

Trailer pages will no be written to the job output files. Since trailer pages are fully redundant and serve no purpose after the printer stream has been split into job output files there is in practice no need to keep them.

-c cmd

Will execute cmd for each received job. cmd must be a valid shell command and will be called with a single argument, the name of the job output file. Some job attributes, which were extracted from the banner page, are passed as environment variables

Environment Spec Content
HERCJOS_JOBTYP %T job type, either JOB, TSO, or STC
HERCJOS_JOBNUM %J job number in the form Jxxxx, Txxxx, or Sxxxx
HERCJOS_JOBNAM %N job name
HERCJOS_USER %U user name
HERCJOS_ROOM %R room name
HERCJOS_PRINTER %P printer name
HERCJOS_DATE %D date/time in the format yyyy-mm-dd:hh:mm:ss

-t

Trace input to stdout. Useful for debugging.

-h

Print a brief help text and exit. All other options and arguments will be ignored.

Usage

Read from sockdev, create per job files without banner

The most common usage in the context of a tk4- system is to connect hercjos to the default printer 00E. As first step set this printer up as sockdev device

  devinit 00E 14030 sockdev

than start hercjos, e.g. like

  hercjos -db -dt

The job files will be written into the current working directory without the banner and trailer page (due to -db and -dt options). The default file name pattern %D_%J_%N.prt is used, and can be changed with the -p option.

Hercjos will print some trace information to STDOUT, like

hercjos-I: head  'A JOB   55 PERF#ASM WFJM                 2018-04-07-09:44:51'
hercjos-I: write '2018-04-07-09:44:51_J0055_PERF-ASM.prt'
hercjos-I: close written   9p,   518l; dropped   2p,    66l
...
hercjos-I: head  'A JOB   62 SHUTDWN  WFJM                 2018-04-07-11:59:23'
hercjos-I: write '2018-04-07-11:59:23_J0062_SHUTDWN.prt'
hercjos-I: close written   5p,    75l; dropped   2p,    66l
hercjos-I: head  'A STC   47 TSO                           2018-04-07-12:00:13'
hercjos-I: write '2018-04-07-12:00:13_S0047_TSO.prt'
hercjos-I: close written   1p,    30l; dropped   2p,    66l
hercjos-I finished after  1685474 byte,  23677 lines,  516 pages,   48 jobs

Post-process file with external command

When hercjos is started with

  hercjos -db -dt -c postcmd

the command postcmd will be executed for each received job file. The example command

#!/bin/bash
echo $1
printenv | grep HERCJOS_

will just print the job file name and the job parameters which are accessible as environment variables.

Bugs

Job files are currently closed when the next banner page is detected. Post processing commands (see -c option are therefore executed when the next job file is received, which could be a considerable and confusing delay.

See also