.EH "|\fI\\\\nP\fP||\fIRemote Job Entry User's Guide\fP|" .OH "|\fIRemote Job Entry User's Guide\fP||\fI\\\\nP\fP|" .PH .PF .tr ! .nr Pt 0 .TL \s-1UNIX\s0 Remote Job Entry User's Guide .AU "A. L. Sabsevitz" ALS PY 3646 7984 2E-210 .AU "K. A. Kelleman" KAK PY 3646 7311 2G-211 .MT 4 .H 1 PREFACE .P A set of background processes running under \s-1UNIX\s0* .FS * \s-1UNIX\s0 is a Trademark of Bell Laboratories. .FE support remote job entry to \s-1IBM\s0 System/360 and /370 host computers. \s-1RJE\s0 is the communal name for this subsystem.** .FS ** In this paper, RJE refers to the \s-1UNIX\s0 facilities and .I not to the Remote Job Entry feature of \s-1IBM\s0's \s-1HASP\s0 or \s-1JES\s0 subsystems. .FE \s-1UNIX\s0 communicates with \s-1IBM\s0's Job Entry Subsystem by mimicking an \s-1IBM\s0 360 remote multileaving work station. The .I "\s-1UNIX\s0 User's Manual" page .I rje (8) summarizes its design and operation. The manual also contains a description of the .I send (1) command, which is the user's primary method of submitting jobs to \s-1RJE\s0, and .IR rjestat (1), which allows the user to monitor the status of \s-1RJE\s0 and to send operator commands to the host system. This guide is a tutorial overview of \s-1RJE\s+1 and is addressed to the user who needs to know how to use the system, but does \fInot\fP need to know details of its implementation. The two following sections constitute an introduction to \s-1RJE\s0. .H 1 PRELIMINARIES .P To become a \s-1UNIX\s0 user, you must receive a login name that identifies you to the \s-1UNIX\s0 system. You should also get a copy of the .I "\s-1UNIX\s0 User's Manual" . This contains a fairly complete description of the system and includes the section .I "How to Get Started" , which introduces you to \s-1UNIX\s0; you should read that section before proceeding with this guide. .P In order to begin using \s-1RJE\s0, you need only become familiar with a subset of basic commands. You must understand the directory structure of the file system, and you should know something about the attributes of files: see \fIcd\fP\^(1), \fIchmod\fP\^(1), \fIchown\fP\^(1), \fIcp\fP\^(1), \fIln\fP\^(1), \fIls\fP\^(1), \fImkdir\fP\^(1), \fImv\fP\^(1), \fIrm\fP\^(1). You must know how to enter, edit, and examine text files: see \fIcat\fP\^(1), \fIed\fP\^(1), \fIpr\fP\^(1). You should know how to communicate with other users and with the system: see \fImail\fP\^(1), \fImesg\fP\^(1), \fIwho\fP\^(1), \fIwrite\fP\^(1). And, finally, you might have to know how to describe your terminal to the system: see \fIascii\fP\^(5), \fIstty\fP\^(1), \fItabs\fP\^(1). .H 1 "BASIC RJE" .P Let's suppose that you have used the editor, \fIed\fP\^(1), to create the file, .B jobfile , that contains your job control statements (\s-1JCL\s0) and input data. This file should look exactly like a card deck, except that for convenience alphabetic characters may be in either upper or lower case. Here is an example: .DS I N $ cat jobfile //gener job (9999\fB,\fPr740)\fB,\fPpgmrname\fB,\fPclass=x usr=(mylogin\fB,\fPmyplace) //step exec pgm=iebgener //sysprint dd sysout=a //sysin dd dummy //sysut2 dd sysout=a //sysut1 dd \(** .in +3n first card of data .sp -.5v .in +3n \0\fB.\fP .if t .sp -.5v \0\fB.\fP .if t .sp -.5v \0\fB.\fP .in -3n last card of data .in -3n /\(** .DE .ne 3 To submit this job for execution, you must invoke the \fIsend\fP\^(1) command: .DS I N $ send jobfile .DE The system will reply: .DS I N 10 cards Queued as /usr/rje/rd3125 .DE Note that .I send tells you the number of cards it submitted and reports the file name that contains your job in the queue of all jobs waiting to be transmitted to the host system. .tr ~ Until the transmission of the job actually begins, you can prevent the job from being transmitted by doing a .B "chmod 0" on the queued file to make it unreadable. For our example, you could say: .DS I N chmod 0 /usr/rje/rd3125 .DE .P When your job is accepted by the host system, a job number will be assigned to it, and an acknowledgement message will be generated. .tr ~~ This indicates that your job has been scheduled on the host system. Later, after the job has executed, its output will be returned to the \s-1UNIX\s0 system. You will be notified automatically of both of these events: if you are logged in when \s-1RJE\s0 detects these events, and if you are permitting messages to be sent to your terminal (see \fImesg\fP\^(1)\^). The following two messages will be sent to you (still using the example above) when the job is scheduled and when the output is returned, respectively: .ne 7 .DS I N .in +3m \fITwo bells\fP .in -3m 12:18:42 gener job 384 \-\- rd3125 acknowledged .DE .DS I N .in +3m \fITwo bells\fP .in -3m 12:21:54 gener job 384 \-\- /a1/user/rje/prnt0 ready .DE .P Two bells, with an interval of one second between them, precede each message. They should be interpreted as a warning to stop typing on your terminal, so that the imminent message is not interspersed with your typing. .P If you are not logged in when one of these events occurs, or if you do not allow messages to be sent to your terminal, then the notification will be posted to you via the \fImail\fP\^(1) command. You can prevent messages directly by executing the \fImesg\fP\^(1) command, or indirectly by executing another command, such as \fIpr\fP\^(1), which prohibits messages for as long as it is active. You may inspect (by invoking the \fImail\fP command) your mail file (/usr/mail/\fIlogname\fP) at any time for messages that have been diverted. Setting your .B \s-1MAIL\s0 variable to the name of your mail file will cause the shell to notify you when mail arrives. For this example, the mail might look as follows: .DS I N $ mail From rje Mon Aug 1 12\fB:\fP20\fB:\fP36 1977 12:18:42 gener job 384 \-\- rd3125 acknowledged .sp .5v ? d From rje Mon Aug 1 12\fB:\fP21\fB:\fP55 1977 12:21:54 gener job 384 \-\- /a1/user/rje/prnt0 ready .sp .5v ? d .DE .P The job acknowledgement message performs two functions. First, it confirms the fact that your job has been scheduled for eventual execution. Second, it assigns a number to the job in such a way that the number and the name together will uniquely identify the job for some period of time. .P The output ready message provides the name of a \s-1UNIX\s0 file into which output has been written and identifies the job to which the output belongs (see \fIls\fP\^(1)): .DS I N $ ls \-l prnt0 .cs 1 28 \-r\-\-r\-xr\-\- 1 rje 1184 Aug 1 12:21 prnt0 .cs 1 .DE .ne 6 Note that rje retains ownership of the output and allows you only read access to it. It is intended that you will inspect the file, perhaps extract some information from it, and then promptly delete it (see \fIrm\^\fP(1)): .DS I N $ rm \-f prnt0 .DE .P The retention of machine-generated files, such as \s-1RJE\s0 output, is discouraged. It is your responsibility to remove files from your \s-1RJE\s0 directory. \s-1RJE\s0 output files may be truncated if the output exceeds a set limit. This limit is tunable by the system administrator. Output beyond the current limit will be discarded, with no provision for retrieval. If the output were truncated in the previous example, the second notification message would have been: .ne 4 .DS I N .in +3m \fITwo bells\fP .in -3m 12:21:54 gener job 384 \-\- /a1/user/rje/prnt0 ready (truncated) .DE The user should also be aware that \s-1RJE\s0 attempts to keep a set number of blocks free on any file system it uses. This number is also tunable by the system administrator. Warning messages or suspension of certain functions will occur as this limit is approached. .P The most elementary way to examine your output is to \fIcat\fP it to your terminal. The Appendix of this document shows the result of listing the output of our sample job in this way. Because \s-1UNIX\s0 has no high volume printing capability, you should route to the host's printer any large listings of which you desire a hard copy. .P The structure of an output listing will generally conform to the following sequence: .DS I N \s-1HASP\s0 log jcl information data sets \s-1HASP\s0 end .DE .P Normally burst pages will not be present. Single, double, and triple spacing is reflected in the output file, but other forms controls, such as the skip to the top of a new page, are suppressed. Page boundaries are indicated by the presence of a blank (space character) at the end of the last line of each page. .P The big file scanner .I bfs (1) or the context editor .I ed (1) provide a more flexible method than .I cat (1) for examining printed output; .I bfs can handle files of any size and is more efficient than .I ed for scanning files. .P R\s-1JE\s0 is also capable of receiving punched output as formatted files (see \fIpnch\fP\^(5)\^); this format allows an exact representation of an arbitrary card deck to be stored on the \s-1UNIX\s0 machine. However, there are few commands that can be used to manipulate these files. You will probably want to route your punched output to one of the host's output devices. .H 1 "SEND COMMAND" .P The \fIsend\fP\^(1) command is capable of more general processing than has been indicated in the previous section. In the first place, it will concatenate a sequence of files to create a single job stream. This allows files of \s-1JCL\s0 and files of data to be maintained separately on the \s-1UNIX\s+1 machine. In addition, it recognizes any line of an input file that begins with the character .B \v'0.4m'\s+3~\s0\\v'-0.4m' as being a \fIcontrol\fP line that can call for the inclusion, inside the current file, of some other file. This allows you to .I send a top level skeleton that ``pulls'' in subordinate files as needed. Some of these may be ``virtual'' files that actually consist of the output of \s-1UNIX\s0 commands or Shell procedures. Furthermore, the \fIsend\fP command is able to collect input directly from a terminal, and can be instructed to prompt for required information. .P Each source of input can contain a format specification that determines such things as how to expand tabs and how long can an input line be. The manual page for .IR fspec (5) explains how to define such formats. When properly instructed, .I send will also replace arbitrarily defined keywords by other text strings or by \s-1EBCDIC\s0 character codes. (These two substitution facilities are useful in other applications besides \s-1RJE\s0; for that reason, .I send may be invoked under the name \fIgath\fP to produce standard output \fIwithout\fP submitting an \s-1RJE\s0 job.) .P Two options of .I send that everyone should be acquainted with are: the ability to specify to which host computer the job is to be submitted, and a flag that guarantees that a job will be transmitted to the host computer in order of submission (relative to other jobs submitted with the same flag). To run our sample job on a host machine known to \s-1RJE\s0 as .BR A , we would issue the command: .DS 1 0 $ send A jobfile .DE When no host is explicitly cited, .I send makes a reasonable choice. .P To insure that a job will be transmitted in order of submission, set the .B \-x flag: .DS 1 0 $ send \-x jobfile .DE This flag should be used sparingly. The complete list of arguments and flags that control the execution of .I send can be found in .IR send (1). .H 1 "JOB STREAM" .P It is assumed that the job stream submitted as the result of a single execution of .I send consists of a single \fIjob\fP, i.e., the file that is queued for transmission should contain one \s-1JOB\s0 card near the beginning and no others. A priority control card may legitimately precede the \s-1JOB\s0 card. The \s-1JOB\s0 card must conform to the local installation's standard. At \s-1BISP\s0, it has the following structure: .DS 1 0 //name job (acct[\fB,\fP\fB.\|.\|.\fP])\fB,\fPpgmrname[\fB,\fPkeywds=?] [usr=\fB.\|.\|.\fP] .DE .H 1 "USER SPECIFICATION" .P A ``usr'' specification is required on print or punch output that is to be delivered to a UNIX user. .DS 1 0 usr=(login,place,[level]) .DE where .I login is the \s-1UNIX\s0 login name of the user, .I level is the desired level of notification (see end of this section for an explanation), and .I place is as follows: .AL A .LI If .I place is the name of a directory (writable by others), then the output file is placed there as a unique .B prnt or .B pnch file. The mode of the file will be 454. .LI If .I place is the name of an existing, writable (by others), non-executable (by others) file, then the output file replaces it. The mode of the file will be 454. .LI If .I place is the name of a non-existent file in a writable (by others) directory, then the output file is placed there. The mode of the file will be 454. .LI If .I place is the name of an executable (by others) file, then the \s-1RJE\s0 output is set up as standard input to .I place, and .I place is executed. Five string arguments are passed to .I place. For example, if .I place is a shell procedure, the following arguments are passed as $1 \fB.\|.\|.\fP $5: .AL 1 "" 1 .LI Flag indicating whether file space is scarce in the file system where .I place resides. A .B 0 indicates that space is \fInot\fP scarce, while .B 1 indicates that it is. .LI Job name. .LI Programmer's name. .LI Job number. .LI Login name from the ``usr=\fB.\|.\|.\fP'' specification. .LE 1 A ``\fB:\fP'' is passed if a value is not present. The current directory for the execution of \fIplace\fP will be set to the directory containing \fIplace\fP. The environment (see .I environ\^ (7)) will contain values for .B \s-1LOGNAME\s0 and .B \s-1HOME\s0 based on the login name from the ``usr=\fB.\|.\|.\fP'' specification, and a value for .B \s-1TZ\s0 . Since the login name supplied on the ``usr=\fB.\|.\|.\fP'' specification cannot be believed for security purposes, the \s-1UID\s0 will be set to a reserved value. .LI In all other cases, the output will be thrown away. .LE .P The .I place value must not be a full pathname, unless it refers to an executable file (see D above). For cases A, B, and C above (and case D, if a full pathname is not supplied), the name of the user's login directory will be used to form a full pathname. .P The ``usr=\fB.\|.\|.\fP'' field may occur anywhere within the first 100 card images sent and within the first 200 output images received by the \s-1UNIX\s0 system. The only restriction is that it be contained completely on a single line or card image. Therefore, the ``usr=\fB.\|.\|.\fP'' field may be placed on a \s-1JOB\s0 card or comment card. It may also be passed as data. .P For redirection of output by the host, a ``usr=\fB.\|.\|.\fP'' card, if not already present, must be supplied by the user. This can be done by placing a job step that creates this card before your output steps. .P Messages generated by \s-1RJE\s0 or passed on from the host are assigned a level of importance ranging from 1 to 9. The levels currently in use are: .DS 1 0 3 transmittal assurance 5 job acknowledgement 6 output ready message .DE The optional .I level field of the ``usr=\fB.\|.\|.\fP'' specification must be a one or two-digit code of the form .I mw\^ . A message from the host with importance .I x (where .I x comes from the above list) is compared with each of the two decimal digits in .I level . If \fIx\fP\(>=\fIw\fP and if the user is logged in and is accepting messages, the message will be written to his or her terminal. Otherwise, if \fIx\fP\(>=\fIm\fP, the message will be mailed to the user. In all other cases, the message will be discarded. The default .I level is .B 54 . You should specify level .B 1 if you want to receive complete notification, and level .B 59 to divert the last three messages in the above list to your mailbox. .H 1 "MONITORING RJE" .P R\s-1JE\s0 is designed to be an autonomous facility that does not require manual supervision. R\s-1JE\s0 is initiated automatically by the \s-1UNIX\s0 reboot procedures and continues in execution until the system is shut down. Experience has shown \s-1RJE\s0 to be reasonably robust, although it is vulnerable to system crashes and reconfigurations. .P Users have a right to assume that when the \s-1UNIX\s0 system is up for production use, \s-1RJE\s0 will also be up. This implies more than an ability to execute the \fIsend\fP\^(1) command, which should be available at all times; it means that queued jobs should be submitted to the host for execution and their output returned to the \s-1UNIX\s0 system. If a user cannot obtain any throughput from \s-1RJE\s0, he or she should so advise the \s-1UNIX\s0 operators. .P The .IR rjestat (1) command, invoked with no arguments will report the status of all \s-1RJE\s0 links for which a given \s-1UNIX\s0 system is configured. It may sometimes also print a message of the day from \s-1RJE\s0. .DS 1 0 .ne 5 $ rjestat \s-1RJE\s+1 to \s-1B\s+1 operating normally. \s-1RJE\s+1 to \s-1A\s+1 down, reason: \s-1IBM\s+1 not responding. .DE .P A host machine may be reported to be not responding to \s-1RJE\s0 because it is down, or because of its operator's failure to initialize the associated line, or because of a communications hardware failure. .P .I Rjestat also has the ability to send operator commands to the host machine and retrieve the responses generated by the commands. Refer to the .IR rjestat (1) manual page for a complete description of this command. .br .ne 60 .in 0 .nf .ta 9n,17n,25n,33n,41n,49n,57n,65n,73n,81n .ll 75 .ss 18 Appendix\-Sample \s-1JES2\s+1 Output Listing .sp .5v $ cat rje/prnt0 .if t .ps 8 .if t .vs 10p .br 14\fB.\fP40\fB.\fP31 JOB 384 $HASP373 GENER STARTED - INIT 26 - CLASS X - SYS RRMA .br .nf 14\fB.\fP40\fB.\fP32 JOB 384 $HASP395 GENER ENDED -\|-\|-\|-\|-\|- JES2 JOB STATISTICS -\|-\|-\|-\|-\|-\| 1 AUG 77 JOB EXECUTION DATE 54 CARDS READ 76 SYSOUT PRINT RECORDS 0 SYSOUT PUNCH RECORDS 0\fB.\fP01 MINUTES EXECUTION TIME 1 //GENER JOB (9999\fB,\fPR740)\fB,\fPPGMRNAME\fB,\fPCLASS=X JOB 384 \(**\(**\(** USR=(MYLOGIN\fB,\fPMYPLACE) 2 //IEBGENER EXEC PGM=IEBGENER 3 //SYSPRINT DD DUMMY 4 //SYSIN DD DUMMY 5 //SYSUT2 DD SYSOUT=A 6 //SYSUT1 DD \(** // IEF236I ALLOC\fB.\fP FOR GENER IEBGENER IEF237I DMY ALLOCATED TO SYSPRINT IEF237I DMY ALLOCATED TO SYSIN IEF237I JES ALLOCATED TO SYSUT2 IEF237I JES ALLOCATED TO SYSUT1 IEF142I GENER IEBGENER - STEP WAS EXECUTED - COND CODE 0000 IEF285I JES2\fB.\fPJOB0384\fB.\fPSO0102 SYSOUT IEF285I JES2\fB.\fPJOB0384\fB.\fPSI0101 SYSIN IEF373I STEP /IEBGENER/ START 77242\fB.\fP1440 IEF374I STEP /IEBGENER/ STOP 77242\fB.\fP1440 CPU 0MIN 00\fB.\fP13SEC SRB 0MIN 00\fB.\fP01SEC VIRT 36K SYS 188K \(**\(**\(**\(**\(**\(**\(** SERVICE UNITS=0000174 SERVICE RATE=0000268 SERVICE UNITS/SECOND \(**\(**\(**\(**\(**\(**\(** PERFORMANCE GROUP=005 \(**\(**\(**\(**\(**\(**\(** EXCP COUNT BY UNIT ADDRESS IEF375I JOB /GENER / START 77242\fB.\fP1440 IEF376I JOB /GENER / STOP 77242\fB.\fP1440 CPU 0MIN 00\fB.\fP13SEC SRB 0MIN 00\fB.\fP01SEC \(**\(**\(**\(**\(**\(**\(** SERVICE UNITS=0000174 SERVICE RATE=0000268 SERVICE UNITS/SECOND \(**\(**\(**\(**\(**\(**\(** APPROXIMATE PROCESSING TIME= \fB.\fP01 MINUTES \(**\(**\(**\(**\(**\(**\(** EXCPS=000000000 \(**\(**\(**\(**\(**\(**\(** PROJECTED CHARGES= \fB.\fP01 .in +15n .sp .5v .if t .ps .if t .vs \fIfirst line of data\fP .sp -.5v \0\fB.\fP .if t .sp -.5v \0\fB.\fP .if t .sp -.5v \0\fB.\fP \fIlast line of data\fP .sp .5v .if t .ps 8 .if t .vs 10p .in 0 \(**OS/VS2 REL 3\fB.\fP7 JES2\(** END JOBNAME=GENER BIN=R740 JOB #=384 PGMRNAME \(**OS/VS2 REL 3\fB.\fP7 JES2\(** END JOBNAME=GENER BIN=R740 JOB #=384 PGMRNAME \(**OS/VS2 REL 3\fB.\fP7 JES2\(** END JOBNAME=GENER BIN=R740 JOB #=384 PGMRNAME .if t .ps .if t .vs $ rm \-f rje/prnt0 .ex