Return to em3280.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 EM3280 8 DLBA 1.5
\" @(#)em3280.8	1.5
.SH NAME
em3280 \- IBM 328X Printer Emulation
.SH SYNOPSIS 
.nf
.I
     /usr/bin/em3280
.I
     /usr/lib/bsc/bsclog
.I
     /usr/lib/bsc/bscmon
.I
     /usr/lib/bsc/bsctrace
.fi

.SH DESCRIPTION 
Em3280 is the communal name for the collection of programs and a file
organization that allows a computer system to communicate emulating an IBM
328x printer. Together with a Bisync communications facility, 
.I em3280
can emulate an IBM 3284, 3286, 3287, or 3288 printer.
The communications facility itself emulates the functions of the IBM 3271 
communications control unit to which the 328x printer is usually attached.
.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.
(The IBM 328x printer does not use the "transparent" mode.)
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. The
IBM 328x printer is commonly used only in conjunction with multi-point
BISYNC communications facilities.
.P
In the em3280 system, the administrator designates a collection of
one or more hosts to which the computer connects emulating an
IBM 328x printer. For each of these hosts, the administrator provides
a set of parameters pertaining to that host connection and the specific
printer parameters for emulation.
.P
Users may direct em3280 output to stdout, directly to a file or device
(e.g. /dev/lp), or to a program (e.g. lpr).
Four print formats are supported: fixed at 40, 64, or 80 characters per line,
and variable-length, the data having newlines and other
format effectors imbedded in it.
.P
An audit trail can optionally be kept which records all em3280
activity. The audit trail logs host, user, and time for various messages
about connection and disconnection,
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 following diagram shows the relationships between various files
and programs used in the 328X emulation process.
.TS
box,center;
c|c|c.
DESIRED	USER	LINK
FUNCTION	LEVEL	LEVEL
_
Emulate 328x	em3280	/dev/bsc*
_	_	_
Check status	bsclog	<dir>/AUDIT
_
Monitor	bscmon,			/dev/bsctr*
Activity	bsctrace
.TE
.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 the AUDIT file
pertaining to this host will be placed.
.P
At the beginning of a session (user invokes 
.I em3280) 
the utility will read the host parameter file to determine the communications
line characteristics \- device to use, terminal identification, ...
and the printer parameter file to determine printer characteristics \-
output type (file or program), printer type (3284, 3286, ...),
....
The communications line will be opened and the printer's characteristics
noted. As files are received from the host, they will be formatted according
to those characteristics and the output sent to either a user-specified
destination (file, device, or program), or stdout if no destination was
specified.
.P
When receive timeout is detected, the printer output device or file will be
closed, then re-opened to flush whatever output has been spooled so far.
.P
The session is terminated when the daemon detects that the host has dropped
the data set ready signal. At that point, connection with the host has been
terminated.  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
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.
.SH ADMINISTRATION
.SS Installation.
The em3280 tape is used in the installation process for the em3280
facility. To install em3280, do the following:
.RS
.IP 1.
Make a directory to contain the installation files, e.g.,
/tmp/em3280, 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;
c c c.
em3280	em3280.x	empr.h
3280	3280inst	inst3280.c
.TE
.IP 2.
Prepare installation exit subroutines, if necessary.
File inst3280.c contains default
subroutines for the installation exits, as described below. They
may be modified or completely replaced, but must exist.
.RS
.P
.I
connect (host, dev)
.br
.I
char *host, *dev;
.P
is called when 
.I em3280 
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 
.I em3280 
will terminate.
.P
This routine may perform operator communication
necessary for connection. The default (supplied) routine merely
returns a zero value immediately.
.P
.I
disconnect (host, devname)
.br
.I
char *host, *devname;
.P
is called when 
.I em3280 
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.
.P
.I
audit (message)
.br
.I
char *message;
.P
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.
.RE
.IP 3.
Install all files. "3280inst" is a shell command file which will
link the em3280 command object file with inst3280.c and
install all commands and files into the appropriate directories.
.RE
.SS "Set Up Host Configurations."
For each separate host, a file must be created in /usr/lib/bscbatch
which supplies the control and administrative information used by
em3280. The file may be created via the text editor.
Sample configurations appear in file 3280, 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
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
DEVICE=/dev/bsc*. 
The device to be used for BISYNC operations must be specified here.
Default: /dev/bsc.
.TP
DUPLEX=HALF|FULL. 
Specify FULL for a full-duplex modem, HALF for a half-duplex modem.
Default: HALF.
.TP
LINESPERPAGE=lines
Specify the number of lines to be printed on a page.
Default: 60.
.TP
MAIL=userid. 
.I Em3280 
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,
inability to connect to host, and host id check failures.
Default: messages sent to /dev/console.
.TP
MPTADDR=aa.
.I Aa
is the address of the emulated printer if this is a multipoint network.
If this is point-to-point, this parameter must not be specified.
.I Aa
consists of two alphabetic characters. The first is the polling address,
the second the select address.
Default: poll address=0x40, select address=0x60.
.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: 
255.
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: 
255.
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: 
255.
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: 
255.
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: 
255.
Default: 150.
.TP
OUTPUT=P|F,destination
Specify whether output will be written to a file (F), or piped to a program (P),
and the name  of the file or pipe.
Default: P,lpr.
.TP
PTYPE=4|6|7|8|9
Specify the type of IBM 328x printer being emulated; 4=3284, 6=3286, etc.
Default: 4.
.TP
TIMEOUT=nnn
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 nnn
seconds,
.I bscd
will disconnect.
Default: 30.
.TP
TPRINT=YES|NO.
Specifiy whether the IBM text print option, available only on 3288 printers, 
will be used.
Default: NO.
.SS "Set Up Host SPOOL Area."
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 "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 \- 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)).
.SH "SEE ALSO"
.br
em328x(1C) - 328x printer emulator
.br
bsclog(8) - batch audit trail utility
.br
bscmon(8) - bsc monitor/trace utilities
.br
.I
Setting Up UNIX
.br
.I
General Information - Binary Synchronous Communications,
IBM document GA27-3004.
.br
.I
3270 Component Description,
IBM document GA27-2749.
.SH "SYSTEM REQUIREMENTS"
.SS Modems.
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:
.P
.nf
     Bell 201A3 (2000 bits per second)
     Bell 201C  (2400 bits per second)
     Bell 208B  (4800 bits per second)
     Bell 209A  (9600 bits per second)
.fi
.SS Hardware.  
This software is supported when used with the following:
.P
.nf
     UNIX Version 7, System 3, or System 5 operating system
     MODEM port jumpered for external clocking
     MODEM port jumpered as Data Terminal Equipment
.fi
.SH DIAGNOSTICS
.P
em3280 <host>: can't open <confdir> configuration directory.
.IP
The configuration directory for this host couldn't be opened.
Check the modes. Processing was aborted.
.P
em3280 <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 was aborted.
.P
em3280 <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 was aborted.
.P
em3280 <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 was aborted.
.P
em3280 <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.