Return to batch.8 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / usr.bin / bsc / doc

Power 6/32 Unix version 1.21

'\" t
.TH BATCH 8 1.9 DLBA
\" @(#)batch.8	1.9
.SH NAME
batch \- Binary Synchronous Batch Terminal Emulation
.SH SYNOPSIS
.br
.I /etc/bscd
.br
.I /usr/bin/bscbatch
.br
.I /usr/bin/bscpr
.br
.I /usr/lib/bsc/bsclog
.br
.I /usr/lib/bsc/bsclean
.br
.I /usr/lib/bsc/bscmon
.br
.I /usr/lib/bsc/bsctrace
.br
.SH DESCRIPTION 
.P
BATCH is the communal name for the collection of programs and a file
organization that allows a computer system to communicate emulating an IBM
binary synchronous batch terminal, such as the 2780 and 3780 batch
transmission terminals.
.P
The Binary Synchronous protocol, commonly called BISYNC, is a byte-oriented,
half-duplex protocol, although full-duplex communications facilities
are sometimes used in order to reduce the time required to turn the
transmission direction around. A set of control characters are used
to provide framing and data transparency; data containing imbedded
control characters may be transmitted in a "transparent" mode to
avoid conflicts with the protocol control characters.
Communications may be point-to-point, in which case a contention
method is used to control the line; communications may also be multi-point,
in which case one node is designated the controlling node and polls
and/or selects the other nodes in order to control communications.
.P
In the BATCH system, the administrator designates a collection of
one or more hosts to which the computer connects emulating an
IBM batch terminal. For each of these hosts, the administrator provides
a set of parameters pertaining to that host connection and the specific
terminal parameters for emulation.
.P
A user may submit files to be sent to a particular host by means
of the 
.I bscbatch
command.
Parameters to this command allow for the specification of
host, mail to be sent regarding transmission, and file to be sent.
The user may force the file to be sent in transparent mode, but normally
the file will be scanned at time of transmission to see if it contains
any control characters which force the file to be sent in transparent
mode. Normally the file will be sent as it appears at time of transmission;
the user may force a copy to be made of the file at time of submission
instead, so that the original file may be removed or be changed without
affecting the data to be transmitted.
.P
There is no easy way for the BATCH programs to know what to name
or where to put file received from the host computer. However, a
particular installation may be able to examine the received data
files and determine the appropriate owner and file name. For this
purpose, an installation-written subroutine may be linked with one
of the BATCH programs; this subroutine will be called to identify
and provide an appropriate name for received files. A standard subroutine
is provided which will result in all files being placed in a common
spool directory.
.P
An audit trail can optionally be kept which records all BATCH
activity. The audit trail logs host, user, and time for various messages
about connection and disconnection, sending and receiving files,
various statistics and all errors, temporary or permanent.
Once started, the audit trail file grows indefinitely; the administrator
is responsible for trimming it back when necessary.
.P
The BATCH facility can run completely unattended if the communications
interface is via a leased (dedicated) line, or if all communications
are to operate in automatic answer mode, i.e., the computer system answers
calls from the remote host. If communications are via dial-up (switched)
connections, either an operator is required to do the dialing, or
there must be an automatic calling unit connected with the synchronous
modem.
.P
The BATCH utilities do not provide for automatic calling units. However,
an installation-written routine can be invoked immediately before
host connection and just following host termination
to provide for such things as operator instructions
or automatic dialing.
.P
The following diagram shows the programs and file organization used
at various levels.
.P
.TS
box,center;
c|c|c|c|c.
DESIRED	USER	FILE	FRAME	LINK
FUNCTION	LEVEL	LEVEL	LEVEL	LEVEL
_
Send file	bscbatch	<dir>/C*
		[<dir>/D*]
_	_	_
Receive file	bscpr,	<dir>/PR*	bscd	/dev/bsc*
	bscbatch -q	<dir>/PU*	(daemon)
_	_	_
Check status	bsclog	<dir>/AUDIT
_
Monitor	bscmon,			/dev/bsctr*
Activity	bsctrace
.TE
.P
The designator 
.I <lib> 
refers to directory name "/usr/lib/bscbatch";
in this directory are parameter files for each
possible host connection (<hostname>).
.P
The 
.I <dir> 
designator refers to the host's spool directory.
This name is a combination of
the directory prefix "/usr/spool/bscbatch/"
followed by the <hostname> directory into which all active files
pertaining to this host are placed.
.P
The 
.I bscbatch 
program is used to add files to the
transmit queue; one C* file is created for each new file to be sent.
The D* file is created if it is necessary to make a copy of the file.
Received files will be assigned a base file name of PR* or PU*, depending
on whether they were directed to the PRinter or PUnch. An installation
may choose to place the received files elsewhere; see the description
of the user exit facility in the installation procedures to follow.
.P
The 
.I bscd 
daemon is normally started via an entry in 
.I /usr/lib/crontab, 
which allows the daemon to
search for work as often as the system administrator desires.
(Telephone line costs may dictate running the daemon during hours
of lower charges, or there may be a regular overnight transmission.)
.P
The daemon searches for work
by examining each host's spool directory for a C* file. If there
is such a file, it will attempt to connect to that host.
An installation-provided exit routine can be invoked by 
.I bscd 
at this moment to allow
use of an auto-dialer or any necessary operator communication to
make the connection.
Once the connection is made, files received are handled as above,
and the C* files provide the names of files to be sent.
An empty C* file ("Connect", for example) may be used to force
.I bscd 
to make a connection even if there are no
files to be sent. (One may want to place an entry in /usr/lib/crontab
which will create such a file for certain hosts.)
An audit file, as discussed above, if it exists, will have appended
to it the audit information.
.P
After an installation-specified period of inactivity with respect
to a host, the daemon will terminate the connection to that host.
The installation may provide an exit routine to be invoked at this
time (immediately after termination of connection) to take care of
any necessary cleanup.
.P
The daemon may also be terminated by sending the terminate signal, 
.I 
kill -15,
.R
to the daemon's process. The daemon will make an appropriate entry in 
the audit file (if one exists), remove the lock files, and call the 
cleanup installation exit.
.P
A trace facility can be invoked which records communications events
and the time they occur,
and optionally records actual data, transmitted and received. The
trace information can be placed into a file for immediate or later
analysis by another program.
The general intent is to provide enough information for communications
debugging that a data link analyzer is not necessary.
.P
The 
.I bsctrace
program interprets trace information provided to 
.I bscmon 
by /dev/bsc*tr. A state diagram provided with the
.I bscmon(8) 
document shows the communication
states and flow which makes up the BISYNC protocol; state transition
information is provided to 
.I bscmon, 
which records
it and optionally the transmitted and received data, in a file.
.I Bsctrace 
is used to display this data in a readable format.
.P
.SH ADMINISTRATION
.SS Installation.
.P
The BSC BATCH tape is used in the installation process for the Batch
facility. To install the BATCH facility, do the following:
.RS
.IP 1.
Make a directory to contain the installation files, e.g.,
/usr/sys/src/bsc, then change to that directory. Use 
.I "tar xov0"
to copy the files from tape to the directory.
The following files should be extracted:
.TS
center;
l l l l.
2780	3780	
bscbatch	bscbinst	bscd	bscd.x	
bscinst	bscio.h	bsclean	bsclog	
bscmon	bscpr	bsctr.h	bsctrace	
install.c	libbsc.a	trace.text	maninst
.TE
.IP 2.
Prepare installation exit subroutines, if necessary.
File install.c contains four default
subroutines for the installation exits, as described below. They
may be modified or completely replaced, but must exist.
.IP
.I "connect (host, dev)"
.br
.I "char *host, *dev;"
.br
is called when
.I bscd 
is ready to make a connection to
.I host 
via device
.I devname. 
The connection will be made only if 
.I connect 
returns a zero value; if a non-zero value is returned, a note will be placed
in the AUDIT file (if one exists), and the daemon will skip processing
for this host.
.IP
This routine may perform auto-dialing or operator communication
necessary for connection. The default (supplied) routine merely
returns a zero value immediately.
.IP
.I "disconnect (host, devname)"
.br
.I "char *host, *devname;"
.br
is called when 
.I bscd
has just disconnected from
the given host and device. This routine may perform any cleanup necessary
at this time. The default (supplied) routine merely returns.
.IP
.I "notefile (uname, sfile, mailflag)"
.br
.I "char *uname, *sfile;"
.br
.I "int mailflag;"
.br
is called when file 
.I filename  
has been sent successfully to 
.I host 
on behalf of 
.I username. 
This routine is responsible for sending mail if requested, and for
making any notes necessary for association of files received to files
sent, such as noting a file submit number.
The default (supplied) version of
this routine merely sends mail to the user, if it was requested.
.IP
.I "char *asgnfile (host, file)"
.br
.I "char *host, *file;"
.br
is called to change the name assigned to a received file
.I (fname) 
to a more meaningful name, if possible. It may be possible, for example, to
associate the received file with a particular user by examining the
file and any data noted by the 
.I notefile 
routine.
The value returned is the new name assigned (if not reassigned, return
the current name). 
.I Fname 
is a file in the current directory.
.IP
Suggested procedure: link 
.I fname 
to  ./<username>/
.I fname; 
unlink 
.I fname; 
optionally send mail to <username>.
.IP
The default (supplied) routine merely returns the file name given
to it.
.IP
.I "audit (message)"
.br
.I "char *message"
.br
is a routine which may be called by any of the installation-supplied
routines which need to place information into the AUDIT file. The
single parameter will be written into the AUDIT file along with a
time stamp and the current host's name.
.IP 3.
Install all files. "Bscbinst" is a shell command file which will
link the bscd command object file with install.c and
install all batch commands and files into the appropriate directories.
Shell command file "bscinst" will install the remaining commands,
files, and system library.
Shell command file "maninst" will install the programmer manual files
in /usr/man.
.IP 4.
Modify system generation files, generate system.
.RS
.IP -
Make entry in /usr/sys/cf/dfile for bsc and bsct
.IP -
Add dependencies on libbsc to makefile
.IP -
Use "config" to build "low.s" and "conf.c"
.IP -
Generate system
.RE
.RE
.SS "Set up host configurations."
.P
For each separate host, a file must be created in /usr/lib/bscbatch
which supplies the control and administrative information used by
the BATCH utilities. The file may be created via the text editor.
Sample configurations for emulating a 2780 and a 3780 terminal
(respectively) appear in files 2780 and 3780, extracted in step 1 above.
Any of the following parameters may be specified in the configuration
file, one parameter per line. The default will be taken for any unspecified
parameters.
.TP
BLKSIZE=nnn.
.I Nnn 
must be at least 32 and no more than 512.
This parameter indicates the maximum number of characters which may
be placed into each transmission block, and the space to be reserved
for each receive block.
Default: 512.
.TP
CODE=ASCII\||\|EBCDIC. 
This specifies the transmission code
to be used in the protocol, and what translation is to be performed
on transmitted or received data. 
Default: EBCDIC.
.TP
COMPRESS=YES\||\|NO. 
YES should be specified if 3780-style space compression and expansion
should be performed on non-transparent data. Compression is never
performed on transparent data. 
Default: YES.
.TP
DEVICE=/dev/bsc*. 
The device to be used for BISYNC operations must be specified here.
Note this device must be the one corresponding to the 
.I bsc.o
driver installed in step 5 above.
Default: /dev/bsc.
.TP
DUPLEX=HALF\||\|FULL. 
Specify FULL for a full-duplex modem, HALF for a half-duplex modem.
Default: HALF.
.TP
IDCHECK=hostid. 
In the BISYNC protocol, allowances are made for erroneous connections
in a switched network. The two nodes are allowed to exchange identification
in the form of a short sequence of characters added to the initial
handshake. If it is desired that the host's identification be checked,
and that communications not be allowed to occur unless the identification
matches that given here, specify this parameter. The host identification
may consist of up to twenty alphanumeric characters.
Default: 
Do not check host identification.
.TP
MAIL=userid.
.I Bscd 
will send mail to the system administrator (name given by 
.I userid)
for any significant problems requiring attention. These include incorrect
parameters in this file, truncated receive files, minimum space limit
problems, inability to connect to host, and host id check failures.
Default: 
Messages sent to /dev/console.
.TP
MAXFSIZE=nnnnnn.
.I Nnnnnn 
is the maximum number
of bytes a received file can have without forced truncation; a value
of zero indicates no maximum. This is an administrative parameter
to prohibit extremely long files from taking up so much disk space
that the operating system is no longer able to function properly.
Maximum value for 
.I nnnnnn:
1000000000.  Default: 0 (No maximum).
.TP
MINSPACE=devname,nnnnnn.
.I Nnnnnn 
is the minimum number of blocks which device 
.I devname 
must have for
.I bscd
to accept data from a host, or for
.I "bscbatch -c"
to allow copying of a file for transmission.
.I bscbatch 
will give a warning to a user trying
to send a file if at least 150% of the minimum space required is
not available at that time.
.I bscd 
will make an audit trail entry and send mail
to the administrator (optionally, see MAIL above) when the minimum
space is not available.  Maximum value for 
.I nnnnnn:
1000000000.  Default: No minimum space requirement.
.TP
MPTADDR=aa.
.I Aa
is the address of the emulated terminal if this is a multipoint network.
If this is point-to-point, this parameter must not be specified.
.I Aa
consists of two printable characters, the first being the poll address,
the second the select address.
Default: 
Point-to-point mode.
.TP
NBID=nn.
.I Nn 
is the number of initial handshakes,
or "line bids" which will be made when there is no host response.
In a multipoint or other leased line arrangement, this value should
be zero, which means retry forever.
Maximum value for 
.I nn:
127. Minimum value\/Default: 0 (no limit).
.TP
NNAK=nn.
.I Nn 
specifies the number of NAK's (negative
acknowledgement to text block due to CRC error) that the driver should
give before terminating communications via sending EOT instead of
NAK. This parameter prevents endless transmissions for cases where
the text block was actually built incorrectly.
Maximum value for 
.I nn:
127. Minimum value: 0. Default: 16.
.TP
NRETRY=nn.
.I Nn 
is the number of retries which will
be made during transmission where a text block has been NAK'd (received
with incorrect CRC, or check characters) or where a text block has
had no response from the host (timeout).
Maximum value for 
.I nn:
127.  Minimum value: 0. Default: 15.
.TP
NTTD=nn.
.I Nn 
is the number of TTD's (temporary
text delays from host) that the driver should receive and NAK before
terminating the receive operation via sending EOT. This parameter
may be used to prevent prolonged delays from tying up a communications
line. A value of zero will force the driver to always NAK a TTD.
Maximum value for 
.I nn:
127.  Minimum value: 0. Default: 150.
.TP
NWACK=nn.
.I Nn 
is the maximum number of WACK's (wait
acknowledgements) the driver will accept while attempting to transmit
before terminating transmission via sending EOT. This parameter may
be used to prevent prolonged delays while the host computer is unable
to accept the next data block due to delays.
A value of zero will force the driver to always accept a WACK.
Maximum value for 
.I nn:
127.  Minimum value: 0. Default: 150.
.TP
RECBLK=nn.
.I Nn 
is the maximum number of records
which can be placed into one block for non-transparent transmission.
For transparent transmission, only one record will be placed in a
block.
Maximum value for 
.I nn:
32767. Default: 507 or BLKSIZE-5, whichever is less.
.TP
RECSEP=EM\||\|IRS.
Records will be separated within a block by either an IRS (typical
for 3780 terminal) or EM (typical for 2780 terminal).
Default: IRS.
.TP
RECSIZE=nnn.
.I Nnn 
gives the maximum number of characters
per record. 
.I Bscd 
will complain if it has to truncate any records due to length restrictions.
Default: 507 or BLKSIZE-5, whichever is less.
.TP
RVIMODE=IGNORE\||\|ABORT. 
When an RVI (reverse interrupt) is received during transmission,
.I bscd 
can ignore the interrupt and continue transmitting,
or it can abort the transmission.
Default: ABORT.
.TP
SIGNON=filename. 
Upon establishing communications with a host, 
.I bscd
can send a standard file (containing, for example, a "signon" record).
.I Bscd's 
current directory at time of establishing
initial communications will be the host's SPOOL directory.
If for any reason there is an error in sending this file (for example,
contention), the error will be logged and the remaining (if any) files
sent normally.
Communications for this host will not be aborted due to any error
having to do with the signon file.
Default: No signon file.
.TP
SIGNOFF=filename. 
When ready to terminate communications with the host, 
.I bscd
can send a standard file (containing, for example, a "signoff"
record).
If for any reason there is an error in sending this file (for example,
loss of DSR due to other host having disconnected the line), the error
will be logged and communications for this host terminated.
Default: No signoff file.
.TP
STATION=PRIMARY\||\|SECONDARY. 
In point-to-point mode, it is possible that there will be
contention for control of the communications line (if both host and
this computer wish to transmit at the same time). To eliminate bid
collisions, one end of the line is designated a primary station,
the other a secondary. The primary station bids once per second;
the secondary bids once every three seconds.
This parameter is not used in a multipoint mode.
Default: PRIMARY.
.TP
TERMID=ident. 
If this parameter is specified, 
.I ident 
will be
provided to the host as this (emulated batch) terminal's identification
(see 
.I IDCHECK, 
above). 
.I Ident 
may be a string of up to twenty alphanumeric characters.
Default: No identification.
.TP
TIMEOUT=nnnn.
If there are no files to be sent to the current host, and there is
no activity from the host (no files being received from the host)
for 
.I nnnn 
seconds, 
.I bscd 
will disconnect.
.I nnnn
must be greater than 0 and not more than 3000.
Default: 60.
.TP
TRANSPARENT=YES\||\|NO.
If it is not
permissable to send transparent files, this parameter should be set to 
.I NO. 
Default: YES.
.TP
UNITSEP = YES\||\|NO.
In 2780 mode, a "unit separator" (US) marks the end of a block, following EM.
If transmission is to be in 2780 mode, this parameter
should be set to  
.I YES. 
Default: NO.
.SS "Set up Host Spool Area."
.P
For each host, make a directory /usr/spool/bscbatch/<hostname>.
If an audit trail is to be kept on this host, create an empty file
in that directory called AUDIT.
.SS "Make /usr/lib/crontab entries."
.P
Make an entry in crontab which starts the daemon at the desired time(s).
For example,
.br
     0 * * * * /etc/bscd
.br
will cause the daemon to be started every hour, on the hour.
(See 
.I cron(8)). 
.SS "Regular Maintenance."
.P
Some minimal maintenance of the host spool areas is required.
The administrator's mailbox should be inspected and cleaned out regularly.
The audit trail file (/usr/spool/bscbatch/<hostname>/AUDIT) should be truncated
via the 
.I bsclog 
utility regularly. Most convenient
is an entry in crontab, again -- once per day,
.I "bsclog -purge=3 "
could be run to discard all but
AUDIT information for the last three days (see 
.I bsclog(8)).
PR* and PU*
files should probably be removed when they are over a certain number
of days old; the 
.I bsclean 
utility may be used to do this in a fashion akin to that of 
.I bsclog.
.SH "SEE ALSO"
.P
bscbatch(1C), bscpr(1C), bsclog(8), bsclean(8), bscmon(8).
.br
.I "Setting Up UNIX"
.br
.I "General Information - Binary Synchronous Communications,"
IBM document GA27-3004.
.br
.I "Component Description: IBM 2780 Data Transmission Terminal,"
IBM document GA27-3005.
.br
.I "Component Information for the IBM 3780 Data Communication Terminal,"
IBM document GA27-3063.
.SH "SYSTEM REQUIREMENTS"
.SS Modems.
.P
If two identical modems (same manufacturer, same options)
are used at each end of the communications line, most any synchronous
RS-232-C interface modem will function correctly. The following modems
are definitely supported:
.br
     Bell 201A3 (2000 bits per second)
     Bell 201C  (2400 bits per second)
     Bell 208B  (4800 bits per second)
     Bell 209A  (9600 bits per second)
.br
.SS Hardware.  
.P
This software is supported when used with the following:
.br
     UNIX Release 3 operating system
     MODEM port jumpered for external clocking
     MODEM port jumpered as Data Terminal Equipment
.br
.SH "DIAGNOSTICS"
.P
bscd <host>: can't open <confdir> configuration directory.
.IP
The configuration directory for this host couldn't be opened.
Check the modes. Processing for this host was aborted.
.P
bscd <host>: <devname> cannot be opened for communications.
.IP
The communications device <devname> for the specified
host could not be opened. Either the mode is set wrong, or some other
process has the device open. Processing for this host was aborted.
.P
bscd <host>: unrecognized keyword, line <l> in <filename>.
.IP
While reading the host configuration file <filename>,
an unrecognized keyword was found on line <l>. Probably a typographical
error. Processing for this host was aborted.
.P
bscd <host>: invalid parameter for keyword <k> in <filename>.
.IP
While reading the host configuration file <filename>,
keyword <k> was found to have an invalid parameter. Probably a typographical
error, but it is also possible that the given parameter was out of
range. Processing for this host was aborted.
.P
bscd <host>: file system <devname> has less than minimum
blocks available. Processing aborted.
.IP
The amount of free space on <devname> is below the specified
minimum amount. 
.I Bscd 
refuses to receive any files
from this host while this condition lasts. Processing for this host
was aborted.
Check the MINSPACE parameter
in the host configuration file and the amount of free space on the
file system.
.P
bscd <host>: Transmission of <file> aborted: Attempt to send transparent
to non-transparent host.
.IP
While sending file <file> to this host, configured for normal data
only, transparent characters were encountered. Check <file> for
control characters or typographical errors. Transmission of <file>
was aborted.
.P
bscd <host>: directory <dirname> not readable.
.IP
The spool directory for <host> can not be read.
Check the directory's mode. Processing for this host was aborted.
.P
bscd <host>: file <filename> can't be created.
.IP
While attempting to create <filename> to hold a file being
received, an error was encountered. Check the modes on the directory
and/or file. The receive operation will be aborted.
.P
bscd <host>: file <filename> can't be removed.
.IP
The C* and D* files are normally removed from the host's spool
directory once the file has been sent.
In this case, an error was encountered while trying to unlink the
named file. The file will be left there, which will mean the file
will be sent every time 
.I bscd 
connects to this host, usually highly undesirable. 
.I Bscd 
will abort processing with this host immediately. 
.I Bscd 
will attempt to prevent itself from being started again by leaving a lockfile
in /usr/spool/bscbatch locked after termination; unless this file
is removed by the system administrator, no further batch communication
will occur.
.P
bscd <host>: device <devname> reports modem failure.
.IP
The named device reported a transmit timeout error. The usual reason
for this is that the device did not get a transmit clock signal from
the modem. This could be due to improper modem option specification,
improper cable to the modem from the computer system, or to not having
jumpered the MODEM port for external timing. Transmission is
aborted for this host.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.