NAME

send, gath − gather files and/or submit RJE jobs

SYNOPSIS

gath [−ih] file ...

send argument ...

DESCRIPTION

Gath

Gath concatenates the named files and writes them to the standard output.  Tabs are expanded into spaces according to the format specification for each file (see fspec(5)). The size limit and margin parameters of a format specification are also respected. Non-graphic characters other than tabs are identified by a diagnostic message and excised. The output of gath contains no tabs unless the −h flag is set, in which case the output is written with standard tabs (every eighth column). 

Any line of any of the files which begins with ~ is interpreted by gath as a control line.  A line beginning “~  ” (tilde,space) specifies a sequence of files to be included at that point.  A line beginning ~!  specifies a UNIX command; that command is executed, and its output replaces the ~!  line in the gath output. 

Setting the −i flag prevents control lines from being interpreted and causes them to be output literally. 

A file name of − at any point refers to standard input, and a control line consisting of ~.  is a logical EOF.  Keywords may be defined by specifying a replacement string which is to be substituted for each occurrence of the keyword.  Input may be collected directly from the terminal, with several alternatives for prompting.  In fact, all of the special arguments and flags recognized by the send command are also recognized and treated identically by gath. Several of them only make sense in the context of submitting an RJE job. 

Send

Send is a command-level interface to the RJE subsystems.  It allows the user to collect input from various sources in order to create a run stream consisting of card images, and submit this run stream for transmission to a host computer. 

Possible sources of input to send are: ordinary files, standard input, the terminal, and the output of a command or shell file.  Each source of input is treated as a virtual file, and no distinction is made based upon its origin.  Typical input is an ASCII text file of the sort that is created by the editor ed(1). An optional format specification appearing in the first line of a file (see fspec(5)) determines the settings according to which tabs are expanded into spaces. In addition, lines that begin with ~ are normally interpreted as commands controlling the execution of send. They may be used to set or reset flags, to define keyword substitutions, and to open new sources of input in the midst of the current source. Other text lines are translated one-for-one into card images of the run stream.

The run stream that results from this collection is treated as one job by the RJE subsystems.  Send prints the card count of the run stream, and the queuer that is invoked prints the name of the temporary file that holds the job while it is awaiting transmission.  The initial card of a job submitted to an IBM host must have a // in the first column.  The initial card of a job submitted to a UNIVAC host must begin with a “@RUN” or “`run”, etc.  Any cards preceding these will be excised.  If a host computer is not specified before the first card of the runstream is ready to be sent, send will select a reasonable default.  In the case of an IBM job, all cards beginning with /*$ will be excised from the runstream, because they are HASP command cards. 

The arguments that send accepts are described below.  An argument is interpreted according to the first pattern that it matches.  Preceding a character with \ causes it to loose any special meaning it might otherwise have when matching against an argument pattern. 

. Close the current source. 

− Open standard input as a new source. 

+ Open the terminal as a new source. 

:spec: Establish a default format specification for included sources,
e.g., :m6t−12:

:message Print message on the terminal. 

−:prompt Open standard input and, if it is a terminal, print prompt.

+:prompt Open the terminal and print prompt.

−flags Set the specified flags, which are described below. 

+flags Reset the specified flags. 

=flags Restore the specified flags to their state at the previous level. 

!command Execute the specified UNIX command via the one-line shell, with input redirected to /dev/null as a default.  Open the standard output of the command as a new source. 

$line Collect contiguous arguments of this form and write them as consecutive lines to a temporary file; then have the file executed by the shell.  Open the standard output of the shell as a new source. 

@directory The current directory for the send process is changed to directory. The original directory will be restored at the end of the current source.

~comment Ignore this argument. 

?:keyword Prompt for a definition of keyword from the terminal unless keyword has an existing definition. 

?keyword=xx Define the keyword as a two digit hexadecimal character code unless it already has a non null replacement. 

?keyword=string Define the keyword in terms of a replacement string unless it already has a non null replacement. 

=:keyword Prompt for a definition of keyword from the terminal. 

keyword=xx Define keyword as a two-digit hexadecimal character code. 

keyword=string Define keyword in terms of a replacement string. 

host The host machine that the job should be submitted to.  It can be any name that corresponds to one in the first column of the RJE configuration file (/usr/rje/lines). 

file-name Open the specified file as a new source of input. 

When commands are executed via $ or !  the shell environment (see environ(7)) will contain the values of all send keywords that begin with $ and have the syntax of a shell variable. 

The flags recognized by send are described in terms of the special processing that occurs when they are set:

−l List card images on standard output.  EBCDIC characters are translated back to ASCII. 

−q Do not output card images. 

−f Do not fold lower case to upper. 

−t Trace progress on diagnostic output, by announcing the opening of input sources. 

−k Ignore the keywords that are active at the previous level and erase any keyword definitions that have been made at the current level. 

−r Process included sources in raw mode; pack arbitrary 8-bit bytes one per column (80 columns per card) until an EOF. 

−i Do not interpret control lines in included sources; treat them as text. 

−s Make keyword substitutions before detecting and interpreting control lines. 

−y Suppress error diagnostics and submit job anyway. 

−g Gather mode, qualifying −l flag; list text lines before converting them to card images. 

−h Write listing with standard tabs. 

−p Prompt with ∗ when taking input from the terminal. 

−m When input returns to the terminal from a lower level, repeat the prompt, if any. 

−a Make −k flag propagate to included sources, thereby protecting them from keyword substitutions. 

−c List control lines on diagnostic output. 

−d Extend the current set of keyword definitions by adding those active at the end of included sources. 

−x This flag guarantees that the job will be transmitted in the order of submission (relative to other jobs sent with this flag). 

Control lines are input lines that begin with ~.  In the default mode +ir, they are interpreted as commands to send. Normally they are detected immediately and read literally. The −s flag forces keyword substitutions to be made before control lines are intercepted and interpreted.  This can lead to unexpected results if a control line uses a keyword which is defined within an immediately preceding ~$ sequence.  Arguments appearing in control lines are handled exactly like the command arguments to send, except that they are processed at a nested level of input.

The two possible formats for a control line are: “~argument” and “~  argument ...”.  In the first case, where the ~ is not followed by a space, the remainder of the line is taken as a single argument to send. In the second case, the line is parsed to obtain a sequence of arguments delimited by spaces. In this case the quotes ′ and " may be employed to pass embedded spaces. 

The interpretation of the argument . is chosen so that an input line consisting of ~. is treated as a logical EOF.  The following example illustrates some of the above conventions:

send   −
~  argument ...
~.

This sequence of three lines is equivalent to the command synopsis at the beginning of this description.  In fact, the − is not even required.  By convention, the send command reads standard input if no other input source is specified.  Send may therefore be employed as a filter with side-effects. 

The execution of the send command is controlled at each instant by a current environment, which includes the format specification for the input source, a default format specification for included sources, the settings of the mode flags, and the active set of keyword definitions.  This environment can be altered dynamically.  When a control line opens a new source of input, the current environment is pushed onto a stack, to be restored when input resumes from the old source.  The initial format specification for the new source is taken from the first line of the file.  If none is provided, the established default is used or, in its absence, standard tabs.  The initial mode settings and active keywords are copied from the old environment.  Changes made while processing the new source will not affect the environment of the old source, with one exception: if −d mode is set in the old environment, the old keyword context will be augmented by those definitions that are active at the end of the new source. 

When send first begins execution, all mode flags are reset, and the values of the shell environment variables become the initial values for keywords of the same name with a $ prefixed. 

The initial reset state for all mode flags is the + state.  In general, special processing associated with a mode N is invoked by flag −N and is revoked by flag +N. Most mode settings have an immediate effect on the processing of the current source.  Exceptions to this are the −r and −i flags, which apply only to included source, causing it to be processed in an uninterpreted manner. 

A keyword is an arbitrary 8-bit ASCII string for which a replacement has been defined.  The replacement may be another string, or (for IBM RJE only) the hexadecimal code for a single 8-bit byte.  At any instant, a given set of keyword definitions is active.  Input text lines are scanned, in one pass from left to right, and longest matches are attempted between substrings of the line and the active set of keywords.  Characters that do not match are output, subject to folding and the standard translation.  Keywords are replaced by the specified hexadecimal code or replacement string, which is then output character by character.  The expansion of tabs and length checking, according to the format specification of an input source, are delayed until substitutions have been made in a line. 

All of the keywords definitions made in the current source may be deleted by setting the −k flag.  It then becomes possible to reuse them.  Setting the −k flag also causes keyword definitions active at the previous source level to be ignored.  Setting the +k flag causes keywords at the previous level to be ignored but does not delete the definitions made at the current level.  The =k argument reactivates the definitions of the previous level. 

When keywords are redefined, the previous definition at the same level of source input is lost, however the definition at the previous level is only hidden, to be reactivated upon return to that level unless a −d flag causes the current definition to be retained. 

Conditional prompts for keywords, ?:A,/p which have already been defined at some higher level to be null or have a replacement will simply cause the definitions to be copied down to the current level; new definitions will not be solicited. 

Keyword substitution is an elementary macro facility that is easily explained and that appears useful enough to warrant its inclusion in the send command.  More complex replacements are the function of a general macro processor ( m4 (1), perhaps).  To reduce the overhead of string comparison, it is recommended that keywords be chosen so that their initial characters are unusual.  For example, let them all be upper case. 

Send performs two types of error checking on input text lines.  Firstly, only ASCII graphics and tabs are permitted in input text.  Secondly, the length of a text line, after substitutions have been made, may not exceed 80 bytes for IBM, or 132 bytes for UNIVAC.  The length of each line may be additionally constrained by a size parameter in the format specification for an input source.  Diagnostic output provides the location of each erroneous line, by line number and input source, a description of the error, and the card image that results.  Other routine errors that are announced are the inability to open or write files, and abnormal exits from the shell.  Normally, the occurrence of any error causes send, before invoking the queuer, to prompt for positive affirmation that the suspect run stream should be submitted.

For IBM hosts, send is required to translate 8-bit ASCII characters into their EBCDIC equivalents.  The conversion for 8-bit ASCII characters in the octal range 040-176 is based on the character set described in “Appendix H” of IBM System/370 Principles of Operation (IBM SRL GA22-7000).  Each 8-bit ASCII character in the range 040-377 possesses an EBCDIC equivalent into which it is mapped, with five exceptions: ~ into ¬, 0345 into ~, 0325 into ¢, 0313 into │, 0177 (DEL) is illegal.  In listings requested from send and in printed output returned by the subsystem, the reverse translation is made with the qualification that EBCDIC characters that do not have valid 8-bit ASCII equivalents are translated into ^.  UNIVAC hosts, on the other hand, operate in ASCII code, and any translations between ASCII and field-data are made, in accordance with the UNIVAC standard, by the host computer. 

Additional control over the translation process is afforded by the −f flag and hexadecimal character codes.  As a default, send folds lower-case letters into upper case.  For UNIVAC RJE it does more: the entire ASCII range 0140-0176 is folded into 0100-0136, so that `, for example, becomes @.  In either case, setting the −f flag inhibits any folding.  Non-standard character codes are obtained as a special case of keyword substitution. 

SEE ALSO

m4(1), orjestat(1C), rjestat(1C), sh(1), fspec(5), ascii(7), hasp(8), rje(8), uvac(8). 
Guide to IBM Remote Job Entry for PWB/UNIX Users by A. L. Sabsevitz and E. J. Finger. 
UNIX Remote Job Entry User’s Guide by K. A. Kelleman. 

BUGS

Standard input is read in blocks, and unused bytes are returned via lseek (2).  If standard input is a pipe, multiple arguments of the form − and −:prompt should not be used, nor should the logical EOF (~.). 

May 16, 1980