PWB1/usr/man/man1/send.1

.if t .ds ` ``\"
.if t .ds ' ''\"
.if n .ds ` ""\"
.if n .ds ' ""\"
.tr #
.th SEND I 5/31/77
.sh NAME
send \*- submit RJE job
.sh SYNOPSIS
.bd send
argument ...
.sh DESCRIPTION
.it Send
is a command-level interface to the RJE subsystems
.it hasp\^\c
(VIII)
and
.it uvac\^\c
(VIII).
It allows the user
to collect input from various sources
in order to create a run stream
consisting of card images.
.it Send
creates a temporary file, with a special format,
to contain the collected run stream,
and then queues the file for transmission
by invoking
.it haspqer
or
.it uvacqer,
as appropriate.
Further processing of the job is controlled by
the appropriate PWB/UNIX RJE subsystem and the host computer
to which the job is submitted.
.s3
Possible sources of input to
.it 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
.it ed\^\c
(I).
An optional format specification
appearing in the first line of a file
(see
.it fspec\^\c
(V)) 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
.it 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.
.s3
The run stream that results from this collection
is treated as one job by the RJE subsystems.
.it Send
provides a card count for the run stream,
and the queuer that is invoked
announces the position
that the job has been assigned
in the queue of jobs waiting to be transmitted.
The initial card of a job
submitted to an IBM system
must have a \*`/\*' in the first column.
The initial card of a job submitted to a UNIVAC system
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,
.it send
will select a reasonable default.
In the case of an IBM job, all cards
beginning \*`/*$\*' will be excised from the runstream,
because they are HASP command cards.
.s3
The arguments that
.it send
accepts are described below.
An argument is interpreted
according to
the first pattern that it matches.
Preceding a character with \*`\\\*'
causes it to lose any special meaning
it might otherwise have
when matching against an argument pattern.
.s3
.lp +23 21
\&\fB.\fP	Close the current source.
.s3
.lp +23 21
\-	Open standard input as a new source.
.s3
.lp +23 21
+	Open the terminal as a new source.
.s3
.lp +23 21
:\fIspec\fR\^:	Establish a default format
specification for included sources,
e.g.,
\%:m6t-12:.
.s3
.lp +23 21
:\fImessage\fR	Print message on the terminal.
.s3
.lp +23 21
\-:\fIprompt\fR	Open standard input
and, if it is a terminal,
print \fIprompt\fP.
.s3
.lp +23 21
+:\fIprompt\fR	Open the terminal
and print \fIprompt\fP.
.s3
.lp +23 21
\-\fIflags\fR	Set the specified flags,
which are described below.
.s3
.lp +23 21
+\fIflags\fR	Reset the specified flags.
.s3
.lp +23 21
=\fIflags\fR	Restore the specified flags to their state
at the previous level.
.s3
.lp +23 21
!\fIcommand\fR	Execute the specified PWB/UNIX \fIcommand\fP
via the one-line Shell,
with input redirected to \fI/dev/null\fP
as a default.
Open the standard output of the command
as a new source.
.s3
.lp +23 21
$\fIline\fR	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.
.s3
.lp +23 21
~\fIcomment\fR	Ignore this argument.
.s3
.lp +23 21
=:\fIkeyword\fR	Prompt for a definition
of \fIkeyword\fP from the terminal.
.s3
.lp +23 21
\fIkeyword\fR\^=^\fIxx\fR	Define \fIkeyword\fP
as a two-digit hexadecimal character code.
.s3
.lp +23 21
\fIkeyword\fR\^=\fIstring\fR	Define \fIkeyword\fP
in terms of a replacement string.
.s3
.lp +23 21
\fIhost\fR	Job is to be submitted to: \fBA\fR, \fBB\fR, \fB1110\fR.
The pseudonyms \fBA\fR and \fBB\fR are built into RJE to
represent any IBM host connection.
Their actual destinations are immaterial to RJE.
The pseudonym \fB1110\fR is built into RJE to represent
any UNIVAC host.
.s3
.lp +23 21
\fIfilename\fR	Open the specified file as a new source of input.
.i0
.s3
Arguments of the form \*`!\fIchdir directory\fR\*'
will be trapped so that the
.it send
process can execute the specified \fIchdir\fP itself.
The original directory will be restored at the end
of any source that contains  a \fIchdir\fP.
.s3
The flags recognized by
.it send
are described in terms of
the special processing
that occurs when they are set:
.s3
.lp +7 5
\fB\-l\fR	List card images on standard output.
EBCDIC characters are translated back to ASCII.
.s3
.lp +7 5
\fB\-q\fR	Do not output card images.
.s3
.lp +7 5
\fB\-f\fR	Do not fold lower case to upper.
.s3
.lp +7 5
\fB\-t\fR	Trace progress on diagnostic output,
by announcing the
opening of input sources.
.s3
.lp +7 5
\fB\-k\fR	Ignore the keywords
that are active at the previous level
and erase any keyword definitions
that have been made at the current level.
.s3
.lp +7 5
\fB\-r\fR	Process included sources in raw mode;
pack arbitrary 8-bit bytes
one per column (80 columns per card) until an end-of-file.
.s3
.lp +7 5
\fB\-i\fR	Do not interpret control lines
in included sources;
treat them as text.
.s3
.lp +7 5
\fB\-s\fR	Make keyword substitutions
before detecting and interpreting
control lines.
.s3
.lp +7 5
\fB\-y\fR	Suppress error diagnostics
and submit job anyway.
.s3
.lp +7 5
\fB\-g\fR	Gather mode, qualifying
.bd \-l
flag;
list text lines before
converting them to card images.
.s3
.lp +7 5
\fB\-h\fR	Write listing with standard tabs.
.s3
.lp +7 5
\fB\-p\fR	Prompt with \*`*\*' when taking input from the terminal.
.s3
.lp +7 5
\fB\-m\fR	When input returns to the terminal
from a lower level, repeat the prompt, if any.
.s3
.lp +7 5
\fB\-a\fR	Make
.bd \-k
flag propagate to included sources,
thereby protecting them from keyword substitutions.
.s3
.lp +7 5
\fB\-c\fR	List control lines on diagnostic output.
.s3
.lp +7 5
\fB\-d\fR	Extend the current set of keyword
definitions by adding those active at the end of
included sources.
.i0
.s3
Control lines are input lines
that begin with \*`~\*'.
In the default mode
.bd +ir,
they are interpreted as commands to
.it send.
Normally they are
detected immediately and
read literally.
The
.bd \-s
flag forces
keyword substitutions to be made
before control lines
are intercepted and interpreted.
Arguments appearing in control lines are handled
exactly like the command arguments to
.it send,
except that they are processed
at a nested level of input.
.s3
The two possible formats for a control line are:
\*`~argument\*' and \*`~##argument#\fB...\fP\*'.
In the first case,
where the \*`~\*' is not followed by a space,
the remainder of the line
is taken as a single argument to
.it 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.
.s3
The interpretation of the argument \*`\fB.\fP\*'
is chosen so that an input line
consisting of \*`~\fB.\fP\*'
is treated as a logical end-of-file.
The following example illustrates
some of the above conventions:
.s3
.lp +10 0
send## \-
.br
~##argument ...
.br
~\fB.\fP
.i0
.s3
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
.it send
command reads standard input
if no other input source is specified.
.it Send
may therefore be employed
as a filter with side-effects.
.s3
The execution of the
.it 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
.bd \-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
.it send
first begins execution,
all mode flags are reset,
and no keywords are defined.
.s3
The initial, reset state for all mode flags
is the \*`+\*' state.
In general, special processing
associated with a mode \fIx\fP
is invoked by flag \-\fIx\fP
and is revoked by flag +\fIx\fP.
Most mode settings have an immediate effect
on the processing of the current source.
Exceptions to this are the
.bd \-r
and
.bd \-i
flags,
which apply only to included source,
causing it to be processed
in an uninterpreted manner.
.s3
A keyword is an arbitrary 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.
.s3
All of the keywords definitions made
in the current source
may be deleted by
setting the
.bd \-k
flag.
It then becomes possible
to reuse them,
although this is not recommended.
Setting the
.bd \-k
flag also causes keyword definitions active
at the previous source level to be ignored.
Setting the
.bd +k
flag causes keywords at the previous level to be ignored
but does not delete the definitions
made at the current level.
The
.bd =k
argument reactivates the definitions of the previous level.
.s3
A keyword may not be redefined,
except redundantly,
if it is active at some level of source input
and its replacement is not null.
Prompts for keywords
that have already been defined at some higher level
will simply cause the definitions
to be copied down to the current level;
new definitions
will not be solicited.
Only in the case where a keyword is defined by a null replacement, \fIA=\fP,
is a redefinition allowed, \fIA=a\fP.
Prompts for the keyword, \fI=:A\fP,
will be satisfied by either definition.
.s3
Keyword substitution is
an elementary macro facility
that is easily explained
and that appears useful enough
to warrant its inclusion in the
.it send
command.
More complex replacements are
the function of a general macro processor(\c
.it m4\^\c
(I), 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.
.s3
.it 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
.it send,
before invoking the queuer,
to prompt for positive affirmation
that the suspect run stream
should be submitted.
.s3
.tr ||
The
.it hasp
subsystem, which supports IBM RJE,
operates in EBCDIC code.
The
.it send
command is therefore required to
translate ASCII characters into
their
EBCDIC equivalents.
The standard conversion is based on
the character set described in
\*`Appendix H\*' of
.it "IBM System/370 Principles of Operation"
(IBM SRL GA22-7000).
Each ASCII character in the octal range 040-176
possesses an EBCDIC graphic equivalent
into which it is mapped,
with four exceptions:#
.if t broken vertical bar into \*`\(or\*',
.if t \*`^\*' into \*`\(no\*',
.if t \*`[\*' into \*`\(ct\*',
.if t \*`]\*' into broken vertical bar.
.if n broken vertical bar into EBCDIC \*`|\*',
.if n \*`^\*' into EBCDIC not,
.if n \*`[\*' into EBCDIC cents,
.if n \*`]\*' into EBCDIC broken vertical bar.
In listings requested from
.it send
and in printed output returned by
.it hasp,
the reverse translation
is made
from EBCDIC to ASCII,
with the qualification that
EBCDIC codes
that do not have ASCII equivalents
are translated into \*`^\*'.
The
.it uvac
subsystem, on the other hand,
operates in ASCII code,
and any translations between
ASCII and field-data
are made,
in accordance with the UNIVAC standard,
by the host computer.
.s3
Additional control over the translation process
is afforded by
the
.bd \-f
flag
and hexadecimal character codes.
As a default,
.it send
folds
lower-case letters into upper case.
For UNIVAC RJE it does more:
the entire ASCII range 140-176
is folded into 100-136,
so that \*`\^\`\^\*', for example,
becomes \*`@\*'.
In either case, setting the
.bd \-f
flag
inhibits any folding.
Non-standard character codes are obtained as
a special case of keyword substitution.
.s3
When invoked under the name
.it gath,
the
.it send
command establishes initial flag settings
.bd \-lgq
and suppresses announcement of a zero card count.
While in
.bd \-gq
mode,
long lines that are detected
elicit a diagnostic
but are not truncated.
Also, in this mode,
it is potentially useful
to convey non-graphics
to standard output.
To prevent
.it gath
from deleting non-printing characters,
each may be declared as a single character keyword
whose replacement is itself.
To retain backspaces, for example,
supply the argument \*`BS=BS\*',
where BS denotes the ASCII character
whose octal code is 010.
.s3
The UNIVAC 1110 capability is only supported at the BTL Piscataway location.
.sh FILES
.lp +20 20
/bin/sh	Shell
.lp +20 20
/tmp/sh*	Shell temporary
.lp +20 20
/usr/rje/sys	PWB/UNIX system name, e.g., \*`A\*'
.lp +20 20
/usr/rje/lines	RJE configuration table
.s3
.i0
And, where
.it xxxx
is either
.it hasp
or
.it uvac:
.s3
.lp +20 20
/usr/xxxx/pool/stm*	temporary
.lp +20 20
/usr/xxxx/xmit???	queued output
.lp +20 20
/usr/xxxx/xxxxqer	queueing program
.lp +20 20
/usr/xxxx/xxxxlock	null file for lockout
.lp +20 20
/usr/xxxx/xxxxstat	queue status record
.i0
.sh "SEE ALSO"
help(I), m4(I), sh(I), ascii(V), ebcdic(V), fspec(V), hasp(VIII)
.br
.it "Guide to IBM Remote Job Entry for PWB/UNIX Users"
by A. L. Sabsevitz.
.sh DIAGNOSTICS
\*`non-graphic deleted\*',
\*`undefined tab deleted\*',
\*`long line detected\*',
\*`long line truncated\*',
\*`illegal card excised\*'
\- followed by the resulting card image.
.br
\*`Errors detected\*' 
\- type \*`y\*' to submit anyway.
.s3
Use
.it help\^\c
(I) for explanations of error messages.
.sh BUGS
Standard input is read in blocks, and unused bytes are
returned via
.it seek\^\c
(II).
If standard input is a pipe, multiple arguments
of the form \*`\-\*' and \*`\-:\fIprompt\fR\^\*'
should not be used,
nor should the logical end-of-file \*`~\fB.\fP\*'.
.tr ##