Virtel JES Writer program
Note
This program is an internal development project and is very much a POC idea. It is not officially supported.
The Virtel JES Writer utility extracts JES2 output and writes to a Virtel printer relay tasks via a Virtel transaction. The JES output is converted to a PDF by an input scenario and the PDF can then be printed or saved at the user’s workstation.
Installation
Download VJRS.TRS from the Virtel FTP Server.
Upload to the mainframe into a dataset with the following DCB attributes:-
LRECL=1024,BLKSIZE=6144,RECFM=FB,DSN=HLQ.VJRS.TRS
Run the following JCL. This will unterse the file and install the VJRS load library. Here is a sample of what I use. Change accordingly.
//jobcard JOB 9000,'ED...HOLT...',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//S01 EXEC PGM=IEFBR14
//DDA DD UNIT=SYSDA,
// DSN=HLQ.VJRS.TEMP,DISP=(MOD,DELETE),
// SPACE=(TRK,0)
//S02 EXEC PGM=TRSMAIN,PARM=UNPACK
//SYSPRINT DD SYSOUT=*
//INFILE DD DSN=HLQ.VJRS.TRS,DISP=SHR
//OUTFILE DD UNIT=SYSDA,
// DSN=HLQ.VJRS.TEMP,DISP=(,CATLG),
// SPACE=(CYL,(10,10),RLSE)
//S03 EXEC PGM=ADRDSSU,REGION=0M,COND=(0,NE)
//SYSPRINT DD SYSOUT=*
//IN DD DSN=HLQ.VJRS.TEMP,DISP=SHR
//OUT DD UNIT=SYSDA,VOL=SER=VVVVVV,DISP=SHR
RESTORE INDDNAME(IN) -
OUTDD(OUT) -
DATASET(INCLUDE(**)) -
RENAMEU( -
(SPTHOLT.**,HLQ.**) -
) -
CATALOG BYPASSACS(**) NMC NSC CANCELERROR
Authorise the load library. Use the following command:-
SETPROG APF,ADD,DSNAME=hlq.VJRS.LOAD,VOL=vvvvvv
Add the following JCL to SYS1.PROCLIB:-
//VJRS PROC MAXTASKS=02
//STEP1 EXEC PGM=VJES0100,PARM='MAXTASKS=&MAXTASKS'
//STEPLIB DD DSN=hlq.VJRS.LOAD,DISP=SHR
//SYSUDUMP DD SYSOUT=*
//SYSIN DD DSN=SYS1.PARMLIB(VJRSPRNT),DISP=SHR
Add the following VTAMLST as member APPLVJRS definition for VJRP:-
APPLVJRS VBUILD TYPE=APPL
* -----------------------------------------------------------------
*
* Product : Virtel Printer *
* Description : Main ACB for Virtel Printer Application *
* -----------------------------------------------------------------
*
VJRS APPL ACBNAME=VJRS,AUTH=ACQ
Add the following configuration statements to SYS1.PARMLIB as member VJRSPRNT
*----------------------------------------------------------------------------*
*- PRINTER CONTROL STATEMETS FOR VJRS UTILITY. -*
*- -*
*- COL 1 JES DESTID -*
*- COL 10 VIRTEL LU RELAY PRINTER -*
*- COL 19 PRINTER TYPE -*
*- S = SCS PRINTER. LU TYPE 1 -*
*----------------------------------------------------------------------------*
* * *
EDSPRT REHIM000 S
EDSPRT1 REHIM001 S
EDSPRT2 REHIM002 S
Concatenate the hlq.VJRS.LOAD to the SERVLIB DD statement in the VIRTEL proc.
......
//SERVLIB DD DISP=SHR,DSN=hlq.VJRS.LOAD
// DD DISP=SHR,DSN=hlq.VIRTEL.SERVLIB
......
9. Assemble the VJRS scenarios into the VIRTEL load library using the sample hlq.VJRS.SAMPLIB(ASMSCEN). This job assemble the two VJRS scenarios SCVJRS00 and SCVJRS01 into the VIRTEL loadlib.
Virtel Configuration
To use VJRS you must create a transaction(s) in Virtel which provides a printer interface that converts the JES output to a PDF. This is done by adding an input scenario to an existing transaction. The input scenario will convert the JES output to a PDF by calling MAKEPDF through the $VIRSV interface. In our example we are using the sample scenario SCVJRS01 which can be found in hlq.VJRS.SAMPLIB. In our case we are using a TSO transaction as the recipient of the output stream from VJRS. SCVJRS01 is a scenario that produces landscape print. Scenario SCVJRS00 produces portrait output.
Example of Virtel TSO transaction with PDF input scenario:-
MAKEPDF configuration
The PDF page format and layout are controlled by text files used by the ZMAKEPDF program. The following files, found in vjrs.zip distribution file, must be uploaded to the Virtel W2H directory through the standard Virtel upload process.
Portrait files
scenvjrs-docopt.txt
scenvjrs-layout.txt
scenvjrs-input.txt
Landscape files
scenvjrs-docopt\_l.txt
scenvjrs-layout\_l.txt
scenvjrs-input\_l.txt
Details about the format of the files can be found in the CASI CICS2PDF Installation and Reference manual. These files are passed through to ZMAKEPDF through the calling of the service program VJRS0200. The service program is invoked from within the scenario by a VIRSV$ call statement.
Print controls
Print control is basic. Any detected ASA control characters are stripped off and replaced by a blank. Line count is controlled by the PDF-LINES-PER-PAGE tag.
Session establishment
To support printing any 3270 session can be used as long as an associate printer relay is defined. In my case I am using a TSO session to establish a printer connection. In the screen shot below a TSO session has been initiated. The LU associated with this session are REHVT000, the terminal session, and REHIM000 the printer session. VJRS will establish a VTAM session with REHIM000. Also, in the URL the transaction name of TSO1A has been defined. This associates the input scenario SCVJRS01 with the session.
URL: http://192.168.170.30:41002/w2h/WEB2AJAX.htm+TSO1A
Note that there are two VIRTEL relays associated with this session. The terminal session, REHVT000 and an associated SCS printer relay REHIM000. The printer relay LU is used by VJRS to transmit the data from JES to VIRTEL.
Using VJRS
Activate the VTAM node
Issue the following z/OS command to activate the VJRS VTAM definition:-
V NET,ACT,ID=APPLVJRS
Start the VJRS printer tasks
S VJRS
The output from the started task should look like this:-
V NET,INACT,ID=APPLVJRS,I
IST097I VARY ACCEPTED
IST105I APPLVJRS NODE NOW INACTIVE
V NET,ACT,ID=APPLVJRS
IST097I VARY ACCEPTED
IST093I APPLVJRS ACTIVE
S VJRS
$HASP100 VJRS ON STCINRDR
IEF695I START VJRS WITH JOBNAME VJRS IS ASSIGNED TO USER START2
, GROUP SYS1
$HASP373 VJRS STARTED
IEF403I VJRS - STARTED - TIME=13.37.47
VJRS001I - VIRTEL JES WRITER READY
Create some output in JES2 by running a batch job. Output should go to one of the defined destinations that VJRS is serving. Example batch job:-
//SPTHOLTP JOB 'JRPTEST1',CLASS=A,MSGCLASS=Z,NOTIFY=SPTHOLT
//STEP1 EXEC PGM=IEBGENER
//SYSPRINT DD DUMMY
//SYSUT2 DD SYSOUT=A,DEST=EDSPRT
//SYSUT1 DD DSN=SPTHOLT.VJESPRT.ASM(TESTPRNT),DISP=SHR
//SYSIN DD DUMMY
Note
The MSGCLASS=Z ensures that only the Class A output is left on the JES queue with an associated destination of EDSPRT for the submitted job.
After the job has run, output will appear on JES with a DESTID of EDSPRT. This will be captured by VJRS, via the JES2 SAPI interface, and sent to the associated Virtel LU relay. In this case LU REHIM000
Virtel will indicate that Print Output is available by presenting the user with a Printer ICON in the Operator Interface Area or Taskbar on the Virtel Terminal screen.
Pressing the printer ICON will kick off the input scenario SCENFPDF which will convert the output to a PDF and then issue the ADOBE option window to open or save the file.
Select the printer ICON and the input scenario will drive the “MAKEPDF” program which will convert the output to a PDF.
From here the user can open or save the PDF. In our example we choose to open the PDF.
Once you have finished with the PDF close the window and the Virtel Print Notification dialog. Note that you are still left with the Printer ICON in the taskbar. This enables you to reopen the print if required. Once you press Enter or initiate another application action (PFx) the Printer Icon will disappear and the Virtel session is now ready for the next print request.
Using VJRS and VIRTEL message log off load
In Virtel 4.54 (not available until 2015/Q1) the LOG feature enables the VIRTEL log to be spun off to JES2. VJRS can capture the log from JES2 and send it directly to the LU relay printer and in the process convert it to a PDF.
Setting up VIRTEL to use the LOG sysout facility requires a change to the TCT definition to direct WTOs to a SYSOUT dataset. In the TCT code the following statement:-
LOG=(SYSOUT,class,destination)
For example, LOG=(SYSOUT,A,EDSPRT)
This directs all WTOs to a SYSOUT dataset rather than the system console log (SYSLOG). If you want WTO messages going to both the system console and a SYSOUT dataset than issue the following VIRTEL command:-
F VIRTEL,LOG=BOTH
The LOG feature in Virtel 4.54 is controlled by the TCT parameters and a new LOG command. The new LOG command has the following format:-
F VIRTEL,LOG=CONSOLE \| SYSOUT \| BOTH \| SPIN
LOG=CONSOLE routes all WTO message to the system console. This isthe default action.
LOG=SYSOUT routes all WTO messages to a VIRTEL SYSOUT dataset whichis dynamically allocated.
LOG=BOTH routes all WTO messages to both the system console and a dynamically allocated SYSOUT dataset.
LOG=SPIN forces Virtel to release the current SYSOUT dataset for further processing and allocates a new SYSOUT dataset.
Virtel will direct messages to an allocated SYSOUT data set and | or the console (default). If SYSOUT processing is being used you will see a dynamically allocated dataset in the SDSF display panel.
Issue a “?” next to the VIRTEL started task.
Here we can see that VIRTEL has allocated a DDNAME SYS00001. If we select this dataset in SDSF we can see that it is the VIRTEL message log that would normally be written to the system console log.
Assuming that VJRS is running, if we spin this dataset off using the LOG=SPIN command, VIRTEL will release the SYSOUT dataset to JES2. VJRS will then capture it and send it to its destination which is EDSPRT. EDSPRT just happens to be the relay LU defined in VIRTEL and associated with the printer REHIM000.
In the VIRTEL 3270 session issue the command:-
F VIRTEL,LOG=SPIN
In the top right of the VIRTEL window, next to the language indicator, a printer box will appear:-
Pressing the printer icon will process the capture message log from VIRTEL and convert it to a PDF file through MAKEPDF. The PDF file will then be display. The message log can then be saved as a PDF file.
Messages and Abends
Module VJES0100
VJRS001I - VIRTEL JES WRITER READY
VJRS has established a SAPI interface with JES2 and is ready to receive output.
Action: None
VJRS002E – (XXXX:YYYY) PRINTER TASK FAILED
VJRS attached printer task YYYY has failed to print print request
YYYY. The attached task has terminated.
Action: Check SYSLOG for the cause of the attached printer task
failure. Send dump to support. Stop and restart VJRS.
VJRS008I – VIRTEL JES WRITER CLOSED
VJRS is closing due to an operator STOP command being issued.
Action: None
VJRS009W – PRINTER TABLE FULL
VJRS can only support 100 printer destinations.
Action: VJRS terminates with return code 4. Reduce the number of
printer control statements.
VJRS010W – PPPPPPPP:LLLLLLLL – LU already defined in printer TTTTTTTT
While reading in the control statements VJRS has detected that LU
relay LLLLLLLL is already associated with destination TTTTTTTT and
cannot be defined to destination PPPPPPPP.
Action: VJRS ignores the control statement.
VJRS011W – PPPPPPPP:LLLLLLLL – Waiting for printer task to complete
VJRS is shutting down and is waiting for printer PPPPPPPP on relay
LLLLLLLL to complete.
Action: None
Module VJRES0101
VJRS103I - (RRRR:TTTT) JES WRITER STARTING FOR XXXXXXXX JJJJJJJJ:NNNNNNNN)
VJRS printer task has established a VTAM session with Virtel relay
XXXXXXXX. RRRR is the printer request and TTTT is the printer task
ID.
Action: None
VJRS104I - (RRRR:TTTT) JES WRITER ENDED FOR XXXXXXXX
VJRS has complete writing the JES output to the Virtel relay session
XXXXXXXX. RRRR is the printer request and TTTT is the printer task
ID.
Action: None
VJRS105W - (RRRR:TTTT) XXXXXXXX RC=XX RTNCD=XX FDBK2=XX
VJRS has incurred a SNA error in establishing a VTAM session with
Virtel relay print LU XXXXXXX.
Action: Session will be retried up to 10 times and if it still fails
to establish a session the printer will be disabled from further
prints. Investigate Virtel LU relay. Issue a D NET command against
the Virtel LU printer relay and make sure it is in an ACTIVE state.
VJRS106W - (RRRR:TTTT) SSENSEI=XX SSENSMI=XX USENSEI=XXXX
Second part of VTAM session failure.
Action: See message VJRS105W
VJRS107E - (RRRR:TTTT) VTAM SEND FAILED FOR XXXXXXXX
VJRS has failed to send data to the Virtel LU printer relay. RRRR is
the printer request and TTTT is the printer task ID
Action: Printer task Abends U807
VJRS108E - LU XXXXXXXX NOT AVAILABLE
VJRS printer task is unable to contact the Virtel LU printer relay
XXXXXXXX. The RPLRTNCD code has returned X’0008’.
Action: Session will be retried up to 10 times and if it still fails
to establish a session the printer will be disabled from further
prints. Investigate Virtel LU relay. Issue a D NET command against
the Virtel LU printer relay and make sure it is in an ACTIVE state.
VJRS109E - LU XXXXXXXX INVALID
VJRS printer task is unable to establish a session with the Virtel
LU printer relay XXXXXXXX. The RPLRTNCD code has returned X’1453’.
Action: Session will be retried up to 10 times and if it still fails
to establish a session the printer will be disabled from further
prints. Investigate Virtel LU relay. Issue a D NET command against
the Virtel LU printer relay and make sure it is in an ACTIVE state.
VJRS110E - LU XXXXXXXX DISABLED. ERROR COUNT EXCEEDED
VJRS has attempted to establish a session with the Virtel LU printer
relay but after 10 attempts this has still failed: The printer will
be disabled for further prints.
Action: Investiagte the status of the Virtel LU printer. It must be
in an ACTIVE state to accept sessions from VJRS.
Abends
U800 VJES0101 Dynamic allocation error.
U801 VJES0101 I/O Error reading JES2 dataset.
U802 VJES0100 VTAM ACB failed to open.
U803 VJES0101 VTAM OPNDST failed.
U804 VJES0101 VTAM OPNDST/ACQUIRE failed.
U805 VJES0101 VTAM SIMLOGON failed.
U806 VJES0101 VTAM CLSDST failed.
U807 VJES0101 VTAM SEND failed.
U808 VJES0100 SSOB SAPI failed.
U810 VJES0101 VTAM GENCB NIB failed.
U811 VJES0101 VTAM GENCB RPL failed.
Bugs and Restrictions
Release 0.0
VJRS doesn’t recover from VTAM or network issues. SNA sense code 087D0001.
$HASP373 VJRS STARTED
IEF403I VJRS - STARTED - TIME=13.44.35
VJRS001I - VIRTEL JES WRITER READY
VJRS103I - (0001:0001) JES WRITER STARTING FOR EDSPRT (SPTHOLTP:JOB05920)
IST663I INIT OTHER REQUEST FAILED, SENSE=087D0001 223
IST664I REAL OLU=SPNET.VJRS ALIAS DLU=SPNET.REHIM000
IST889I SID = CA7B8B52BA578A48
IST1705I SORDER = APPN FROM START OPTION
IST1705I SSCPORD = PRIORITY FROM START OPTION
IST894I ADJSSCPS TRIED FAILURE SENSE ADJSSCPS TRIED FAILURE SENSE
IST895I ISTAPNCP 08400007
IST314I END
VJRS105W - (0001:0001) REHIM000 RC=04 RTNCD=10 FDBK2=01
VJRS106W - (0001:0001) SSENSEI=08 SSENSMI=7D USENSEI=0001
P VIRTEL
VIR0009I APPLHOLT : SHUT DOWN IN PROGRESS
Solution:
Stop Virtel
Stop VJRS
Delete any output on JES2 that is targeted for Virtel
Restart VIRTEL
Establish LU relays – sign on to application
Start VJRS
Run print job again.
VJRS doesn’t recover from Virtel Timeout. When Virtel terminal session times out VJRS fails to reconnect successfully to printer.
Solution:
See problem number 1.
Abend0C7 on Startup
Solution:
MAXTASKS must be two digits. 01 through to 99. Default is 05.
Fix multi page support
Release 0.1 11/2014
1. MakePDF doesn’t support x’00’ in the data stream and issues an error meesage “End of block marker not found”. VJRS now checks data stream before sending to Virtel.
2. Documentation updated. Includes description of how to incorporate Virtel syslog capture with VJRS.
Release 0.2 02/2015
1. VJRS0200 recompiled with MAKEPDF version 1.2. This MAKEPDF version has been modified so that the watermark is not printed.