SEND/RJE Routeback System Manager's Guide November 1989 This document describes how to manage and maintain the RJE Routeback software (SEND) developed at Corning. Supersession/Update Information: This is a new manual. Operating System and Version: VMS V4.6 and later Software Version: SEND V2.0 1 RJE Routeback System Overview The SEND/RJE routeback system allows RJE PRINT output from a VMS/SNA RJE Workstation to be routed by any of the following means: - Output may be directed to a user specified file specification. (SEND/OUTPUT=FILE=filespec) - Output may be directed to a user specified printer queue. (SEND/OUTPUT=SPOOL="print qualifiers") - Output may be MAILed to one or more users. In this instance, after mailing, the files are deleted for security reasons. Note that the record format of the output file is converted from NONE (each record has embedded carriage-controls) to standard text format. (SEND/OUTPUT=MAIL="address(es)") - Output may cause a batch job to be submitted to SYS$BATCH. In this case, the RJE output file specification will be passed to the batch job as parameter P1. (SEND/OUTPUT=BATCH=filespec) - If no routeback entry exists, the output file is printed to a default system printer queue. Another queue may be selected by editting the site-specific parameter file. Note that PUNCH output cannot be reliably routed - the banner line which is used for some of the routeback information is meaningless. Routeback information is maintained in a system-wide RJE routeback queue named: SYS$MANAGER:SNARJE$ROUTEBACK.DAT Routeback entries contain - the jobname and room-code that identify the RJE output - the username associated with the entry - the type of routeback desired: SPOOL, FILE, MAIL, BATCH - a notification flag - a flag indicating the entry is a temporary entry - the date and time the entry was created Non-privileged users can create queue entries specific to their own account. The username and room-code will always be set to the default values (user's username and user's initials). Suitably privileged users (those holding the OPER privilege) can create entries for any user as well as specify a non-default roomcode Routeback is effected by matching the jobname and the room-code. Suitably privileged users can also create a routeback entry for just a JOBNAME by entering an asterisk (*) for the room. Note that, in this case, ALL jobs matching the jobname which do not have a specific room entry in the routeback queue will be routed via the contents of this entry. Routeback can also occur for special Human Resource Management reports that are generated from the CICS environment. See the section on HRM routing for further information. This routing happens prior to any other routing. Routeback is enabled for a given remote and printer channel by assigning the printer channel to a special routeback account whose login command file performs the routeback processing. 2 Sequence of Routeback Processing RJE output is routed via DECnet through the designated account in the following scenario: When RJE output is ready on a print channel on the IBM system, the SNA Gateway creates a DECnet link to the VAX node using the information in the SNARJE workstation assignments. This creates a network process under the account assigned to the print channel (by SNARJE.EXE). As part of process creation, the login command file SYS$MANAGER:ROUTE_PRINT.COM is executed. The following tasks are performed: · FAL is run to receive the RJE output file. Both FAL logging and output are used to capture the exact file specification received. · The following information is determined: Item Source Jobname Name of RJE output file Room Contained in banner Formname Filetype of RJE output file CICS-ID Contained in banner · If the first six characters of the jobname are HPADSC and two sets of three asterisks are at columns 54 and 67, then the job is an HRM job and is appropriately routed. See HRM Routing for further information. · If the routeback queue contains an entry for the exact ROOM and JOBNAME, the appropriate routeback specified is done. · If the routeback queue contains an entry for the exact ROOM and matches the first seven characters of an eight character JOBNAME, the appropriate routeback specified is done. · If the routeback queue contains an entry for ROOM=* and the JOBNAME, the appropriate routeback is done. · If the routeback queue contains an entry for the ROOM=* and matches the first seven characters of an eight character JOBNAME, the appropriate routeback specified is done. · If no routeback entry was matched, the output is printed to the default print queue using the default qualifiers. See chapter on Site Customizations for information on changing the default print queue and qualifiers. The /NOFLAG qualifier is also used. 3 Setting up Routeback The system manager must create at least one VMS account which will be used as the target of the RJE output. This account must be defined with the following parameters: Account name: RMTrr_PRn where rr is the remote number and n is the printer number UIC: Manager's choice (not a system UIC) Default device: Manager's choice Default directory: [RMTrr.PR] where rr is the remote number LGICMD SYS$MANAGER:ROUTE_PRINT.COM Access NETWORK only! PRCLM=2 Required for MAIL to function properly. BYTLM=20000 Minimum required to avoid MAIL routeback failure. The following additional privileges are also required: CMKRNL Allows batch jobs to be submitted for another user. OPER Allows notification messages to be broadcast . SYSPRV Allows access to the routeback database and logfile. A sample account would be created by the following commands: UAF> ADD RMT12_PR1 - /UIC=[100,100] - /DEVICE=DISK$RJE/DIRECT=[RMT12.PR1] - /LGICMD=SYS$MANAGER:ROUTE_PRINT.COM - /NOLOCAL/NOREMOTE/NOBATCH/NODIALUP - /PRCLM=2 - /BYTLM=20000 - /PRIVILEGE=(NETMBX,TMPMBX,CMKRNL,OPER,SYSPRV) - /DEFPRIVILEGE=(NETMBX,TMPMBX,CMKRNL,OPER,SYSPRV) - /NOPASSWORD The account is normally created with a null password. However, if for additional security a password is defined, it must also be specified in the workstation assignments. e.g. SNARJE> ASSIGN nodename"RMT12_PR1 password":: PR1 /NOSPOOL The default device and directory will be the location where RJE output will be initially placed. Hence the recommendation of [RMTrr.PRn]. The device should not be the system device (SYS$SYSDEVICE) to avoid the risk of consuming all free space on the system disk. The system manager may choose to create a separate account/directory for each printer channel. For example, assume that the remote is RMT12 and has three printers defined. The manager could create the following accounts: Account Directory Usage/reason RMT12_PR1 [RMT12.PR1] for print channel PR1 RMT12_PR2 [RMT12.PR2] for print channel PR2 RMT12_PR3 [RMT12.PR3] for print channle PR3 The following commands would be issued under SNARJE to enable routeback for the above accounts/printers: $ RUN SYS$SYSTEM:SNARJE USE RMT12 ASSIGN nodename"RMT12_PR1"::/NOSPOOL PR1 ASSIGN nodename"RMT12_PR2"::/NOSPOOL PR2 ASSIGN nodename"RMT12_PR3"::/NOSPOOL PR3 EXIT Each account could have a customized version of ROUTE_PRINT.COM to enable different actions for each printer channel. Note that the /NOSPOOL qualifier is used to prevent printing of all output received on the output channel. 4 Routeback of HRM Reports The routeback system also supports routeback of Human Resource Management (HRM) reports from the IBM CICS system. The special routeback file HRM_ROUTING:HRM_PRINTERS.DAT is used for this purpose. A sample of this file is left in the [.CGW_SEND_KIT] subdirectory. Note that HRM routeback depends upon proper detection of HRM RJE print jobs based on the print banner. Currently,the banner contains the string "*** CICS-ID ***". Any change in this banner will cause the routeback to fail. Note that due to the sensitive nature of HRM reports, any routeback failure results in the file being deleted. Always check file NETSERVER.LOG for the cause of the routeback failure. 5 Security The routeback procedure uses the image GETUIC.EXE to determine the UIC, default device, and default directory of the username associated with the routeback entry. The routeback procedure sets its UIC to the user's and drops the SYSPRV privilege before performing the routeback. Hence, routeback will fail if the user does not have proper access to the directory or files being used. Since use of the /USERNAME or /ROOM qualifiers can compromise security, use of these qualifiers is restricted to users holding the OPER privilege (with the exception of the SEND/INITIALS command which will process any username). In addition, the routeback of output to a file is restricted to usernames which do NOT have a system UIC (group must be greater than sysgen parameter MAXSYSGROUP). The routeback accounts should only have NETWORK access enabled. The DCL command file ROUTE_PRINT.COM, which performs the routeback, appropriately drops and raises privileges when needed. 6 Site Customizations The ROUTE_PRINT.COM command file uses a site-specific file that enables the following site-specific parameters to be set. The file is referenced by logical name SNARJE$ROUTEBACK_SITE. If the logical name is not defined, the default filename is SYS$MANAGER:SNARJE$ROUTEBACK_SITE.COM. Note that all DCL symbols MUST be global symbols (i.e. use "=="). The default print queue can be changed by altering the definition of the DCL symbol DEFAULT_PRINT_QUEUE in the command file. The default batch queue can be changed by editting the definition of the DCL symbol DEFAULT_BATCH_QUEUE in the ROUTE_PRINT.COM command file. Site-specific qualifers may be specified for PRINT and BATCH submissions by editting the definition of the variables SITE_PRINT_QUALIFIERS and SITE_BATCH_QUALIFIERS. The default form used in printing is specified by the DCL symbol DEFAULT_PRINT_FORM. This can be set any site-specific value. The symbols DEFAULT_PRINT_QUEUE, DEFAULT_BATCH_QUEUE, DEFAULT_PRINT_FORM, SITE_PRINT_QUALIFIERS and SITE_BATCH_QUALIFIERS are applied to the SUBMIT or PRINT command prior to the user-specified parameters. This allows the users to over-ride the default actions. As a further enhancement each routeback account can have its own specific version of the ROUTE_PRINT.COM command file. This will enable each printer channel to have its own, specific, default printer and batch queues. The routeback command file determines the formname of the job and inserts it into the symbol FORMNAME. The routeback software currently does not use this symbol for any actions, but it is included so that site-specific code may utilize it. 7 Routeback failure problem determination Routeback failure can be caused by: - A missing routeback entry. - An incorrect routeback entry by a user such as entering an invalid file specification or an incorrent mail address. - Removal of the username associated with a routeback entry (this includes usernames specified for MAIL routeback). - A user specifying a routeback file location to which the user does not have write access. - An invalid qualifier specified for SPOOL or BATCH routeback. - A change in the format of the RJE banner. The software will locate the ROOM code if it has moved, but cannot route output if the ROOM field is missing. - A suitably authorized user (OPER privilege) creating an entry for a username whose UIC is a system UIC. The primary method of determining the reason for a routeback failure is inspection of the NETSERVER.LOG file created in the routeback account's default directory. Failures are indicated by any unusual error messages. 8 RJE Routeback Logfile A logfile is maintained for each routeback account. Each routeback attempt causes an entry to be placed in this logfile. The logfile file name is the username of the routeback account and the file type is RJELOG. Individual sites may choose to rename the logfile on a daily or weekly basis. If the logfile does not exist, it is automatically created. Each entry consists of the following: Column Contents.... 1-16 Date/time stamp in form YYYY-MM-DD HH:MM. 18-25 The JCL jobname of the RJE output. 26-29 Contents of the ROOM field in the banner line. 30-37 The form-type associated with the RJE output. 38-42 Defines the action performed (PRINT, SPOOL, FILE, MAIL, BATCH). 43-80 The information used for routeback of the output. Contents varies based upon the action performed: Action Contents/meaning of field ------ --------------------------------------------------- PRINT Print queue used (no routeback records existed for this job, so it printed by default). SPOOL Username, followed by a vertical line, followed by the user-specified print qualifiers. FILE Username, followed by a vertical line, followed by the user-specified output file. MAIL Username, followed by a vertical line, followed by the mail address(es) specified by user. BATCH Username, followed by a vertical line, followed by the user-specified file to be submitted as a batch job. Note that only first 38 characters will appear. A sample entry of each type: 1989-06-28 16:35 STDLABEL1234STD PRINTSYS$PRINT 1989-06-28 17:33 KENSRPT REP STD SPOOLREPORTS|/QUEUE=MPRO02_NW 1989-06-29 13:02 MONTHDATJJD STD FILE DOE_JJ|JOHNS_MONTHLY.RPT 1989-06-29 14:11 LIST PS STD MAIL DOE_JJ|SMITH_AB,JONES_CD 1989-06-30 20:24 HPAB01 1000STD BATCH SMITH_AB|FORMAT_REPORT.COM Note that jobname/room are the fields used to determine the routeback location. When customizing ROUTE_PRINT.COM, you can insert messages into the log file by calling the subroutine LOG_EVENT with the following parameters: Max Param Length Contents.................................... P1 8 Job-name P2 8 Form-name P3 4 Room P4 5 Type of routeback done P5 38 Output spec 9 Restrictions Routeback account BYTLM setting. The BYTLM of all routeback accounts should be set to a minimum of 20000 to avoid a failure due to insufficient BYTLM when attempting to route output via VMS mail. Use of the /REMOTE qualifier. The use of the /REMOTE qualifier when specifying BATCH as the output destination is not supported and will cause routeback failure. Changes in RJE banner page. Changes made in the banner produced by the IBM RJE system may cause routeback failure. The command file looks for the word ROOM to locate the room identifier. If the word ROOM is removed from the banner, then routeback failures can occur. 10 chapter