NAME

rje − RJE (Remote Job Entry) to IBM

SYNOPSIS

/usr/rje/rjeinit
/usr/rje/rjehalt

DESCRIPTION

RJE is the communal name for a collection of programs and a file organization that allows a UNIX system, equipped with a KMC11-B, KMC11 driver, and associated Virtual Protocol Machine (VPM) software, to communicate with IBM’s Job Entry Subsystems by mimicking an IBM 360 remote multileaving work station. 

Implementation.

RJE is initiated by the command rjeinit and is terminated gracefully by the command rjehalt. While active, RJE runs in the background and requires no human supervision.  It quietly transmits, to the IBM system, jobs that have been queued by the send(1C) command, and operator requests that have been entered by the rjestat(1C) command. It receives, from the IBM system, print and punch data sets and message output.  It enters the data sets into the proper UNIX directory and notifies the appropriate user of their arrival.  It scans the message output to maintain a record on each of its jobs.  It also makes these messages available for public inspection, so that rjestat(1C), in particular, may extract responses.

Unless otherwise specified, all files and commands described below reside in directory /usr/rje (first exceptions: send and rjestat).

There are two sources of data to be transmitted by RJE from UNIX to an IBM System/370.  In both cases, the data is organized as files in the /usr/rje/squeue directory.  The first are files named co∗ which are created by the enquiry command rjestat(1C). The second source, containing the bulk of the data, are files named rd∗ or sq∗ which have been created by send and queued by the program rjeqer. On completion of processing send invokes rjeqer. Rjeqer and rjestat inform the program rjexmit that a file has been queued via the file joblog.  Upon successful transmission of the data to the IBM machine, rjexmit removes the queued file.  As files are transmitted and received, the program rjedisp writes an entry containing the date, time, file name, logname, and number of records in the file acctlog, if it exists.  This file can be used for local logging or accounting information, but is not used elsewhere by RJE.  The use of this information is up to the RJE administrator. 

Each time rjeinit is invoked, the joblog file is truncated and recreated from the contents of the /usr/rje/squeue directory.  During this time, rjeinit prevents simultaneous updating of the joblog file. 

Output from the IBM system is classified as either a print data set, a punch data set, or message output.  Print output is converted to an ASCII text file, with standard tabs.  Form feeds are suppressed, but the last line of each page is distinguished by the presence of an extraneous trailing space.  Punch output is converted to pnch(5) format. This classification and both conversions occur as the output is received. Files are moved or copied into the appropriate user’s directory and assigned the name prnt∗ or pnch∗, respectively, or placed into user directories under user-specified names, or used as input to programs to be automatically executed, as specified by the user.  This process is driven by the “usr=...” specification.  RJE retains ownership of these files and permits read-only access to them.  Message output is digested by RJE immediately and is not retained. 

A record is maintained for each job that passes through RJE.  Identifying information is extracted contextually from files transmitted to and received from the IBM system.  This information is stored and used by the rjedisp program for IBM job acknowledgements and delivery of output files. 

The IBM system automatically returns an acknowledgement message for each job it receives.  Other status messages are returned in response to enquiries entered by users.  All messages received by RJE are appended to the resp file.  The resp file is automatically truncated when it reaches 70,000 bytes.  Each enquiry is preceded and followed by an identification card image of the form “$UX<process id>”.  The IBM system will echo this back as an illegal command.  The appearance of process ids in the response stream permits responses to be passed on to the proper users. 

While it is active, RJE occupies at least the three process slots that are appropriated by rjeinit. These slots are used to run rjexmit, the transmitter, rjerecv, the receiver, and rjedisp, the dispatcher. These three processes are connected by pipes. The function of each is as follows:

rjexmit
Cycles repetitively, looking for data to transmit to the IBM system.  After transmission, rjexmit passes an event notice to rjedisp. If rjexmit encounters a stop file, (created by rjehalt), it exits normally. In the case of error termination, rjexmit reboots RJE by executing rjeinit.

rjerecv
Cycles repetitively, looking for data returning from the IBM machine.  Upon receipt of data, rjerecv notifies either rjexmit or rjedisp of the event (transfer information is sometimes passed to rjexmit). Rjerecv exits normally at the first appropriate moment when it encounters the file stop, or exits reluctantly when it encounters a run of errors. 

rjedisp Follows up event notices by directing output files, updating records, and notifying users.  Rjedisp references the system files /etc/passwd and /etc/utmp to correlate user names, numeric ids, and terminals.  Termination of rjerecv causes rjedisp to exit also. 

Rjeinit has the capability of dialing any remote IBM system with the proper hardware and software configuration. 

Most RJE files and directories are protected from unauthorized tampering.  The exception is the spool directory.  It is used by send(1C) to create temporary files in the correct file system. Rjeqer and rjestat(1C), the user’s interfaces to RJE, operate in setuid mode to contribute the necessary permission modes. 

Administration.

Some minimal oversight of each RJE subsystem is required.  The RJE mailbox should be inspected and cleaned out periodically.  The job directory should also be checked.  The only files placed there are output files whose destination file systems are out of space.  Users should be given a short period of time (say, a day or two), and then these files should be removed. 

The configuration table /usr/rje/lines is accessed by all components of RJE.  Each line of the table (maximum of 8) defines an RJE connection.  Its seven columns may be labeled host, system, directory, prefix, device, peripherals and parameters. These columns are described as follows:

host The name of a remote IBM computer (e.g., A B C).  This string can be up to 5 characters. 

system
The name of a UNIX system.  This name should be the same as the system name from uname(1).

directory
This is the directory name of the servicing RJE subsystem (e.g., /usr/rje1). 

prefix This is the string prefixed (redundantly) to several crucial files and programs in directory (e.g., rje1, rje2, rje3). 

device
This is the name of the controlling VPM device, with /dev/ excised. 

peripherals
This field contains information on the logical devices (readers, printers, punches) used by RJE.  Each subfield is separated by :, and is described as follows:
(1) Number of logical readers.
(2) Number of logical printers.
(3) Number of logical punches. Note: the number of peripherals specified for an RJE subsystem must agree with the number of peripherals which have been described on the remote machine for that line. 

parameters
This field contains information on the type of connection to make. Each subfield is separated by :.  Any or all fields may be omitted; however, the fields are positional.  All but trailing delimiters must be present.  For example, in

1200:512:::9-555-1212

subfields 3 and 4 are missing, but the delimiters are present.  Each subfield is defined as follows:

(1) space
This subfield specifies the amount of space (S) in blocks that RJE tries to maintain on file systems it touches.  The default is 0 blocks.  Send will not submit jobs and rjeinit issues a warning when less than 1.5S blocks are available; rjerecv stops accepting output from the host when the capacity falls to S blocks; RJE becomes dormant, until conditions improve.  If the space on the file system specified by the user on the “usr=” card would be depleted to a point below S, the file will be put in the job subdirectory of the connection’s home directory, rather than in the place that the user requested. 

(2) size
This subfield specifies the size in blocks of the largest file that can be accepted from the host without truncation taking place. The default is no truncation.

(3) badjobs
This subfield specifies what to do with undeliverable returning jobs. If an output file is undeliverable for any reason other than file system space limitations (e.g., missing or invalid “usr=” card) and this subfield contains the letter y, the output will be retained in the job subdirectory of the home directory, and login rje is notified.  If this subfield contains an n or has any other value, undeliverable output will be discarded.  The default is n. 

(4) console
This subfield specifies the status of the interactive status terminal for this line. If the subfield contains an i, all console status facilities are inhibited (e.g., rjestat(1C) will not behave like a status terminal). In all cases, the normal non-interactive uses of rjestat(1C) will continue to function. The default is y. 

(5) dial-up
This subfield contains a telephone number to be used to call a host machine. The telephone number may contain the digits 0 thru 9 and the character − which denotes a pause.  If the telephone number is not present, no dialing is attempted and a leased line is assumed. 

Sign-on is controlled by the existence of a signon file in the home directory.  If this file is present, its contents are sent as a sign-on message to the host system.  If this file does not exist, a blank card is sent.  Sign-off is controlled in the same way, except that the signoff file is sent by rjehalt if it exists.  If the signoff file does not exist, a “/∗signoff” card is sent.  These files should be ASCII text and no more than 80 characters. 

Send(1C) and rjestat(1C) select an available connection by indexing on the host field of the configuration table.  RJE programs index on the prefix field.  A subordinate directory, sque, exists in /usr/rje for use by rjedisp and shqer programs.  This directory holds those output files that have been designated as standard input to some executable file.  This designation is done via the “usr=...” specification.  Rjedisp places the output files here and updates the file log to specify the order of execution, arguments to be passed, etc.  Shqer executes the appropriate files. 

All RJE programs are shared text; therefore, if more than one RJE is to be run on a given UNIX system, simply link (via ln(1)) RJE2 program names to RJE names in /usr. 

SEE ALSO

rjestat(1C), send(1C), vpm(4), pnch(5), mk(8). 
UNIX Remote Job Entry User’s Guide by K. A. Kelleman. 
UNIX Remote Job Entry Administrative Guide by M. J. Fitton. 
Setting Up UNIX.

DIAGNOSTICS

Rjeinit provides brief error messages describing obstacles encountered while bringing up RJE.  They can best be understood in the context of the RJE source code.  The most frequently occurring one is “cannot open /dev/vpm?”.  This may occur if the VPM script has not been started, or if another process already has the VPM device open. 

Once RJE has been started, users should assist in monitoring its performance, and should notify operations personnel of any perceived need for remedial action.  Rjestat(1C) will aid in diagnosing the current state of RJE.  It can detect, with some reliability, when the far end of the communications line has gone dead, and will report in this case that the host computer is not responding to RJE.  It will also attempt to reboot RJE if it detects a prolonged period of inactivity on the ­KMC-11B. 

May 16, 1980