Return to bscm.4 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

\"	@(#)bscm.4	1.5
.TH BSCM 4 1.5 DLBA
.SH NAME 
bscm \- BISYNC Cluster Controller Driver
.SH DESCRIPTION 
.P
This section describes the general nature of the BISYNC Cluster Controller
driver.
.P
A prerequisite to fully understanding this section of the manual is a general
background in binary synchronous communications, which may be had by reading
the IBM General Information on Binary Synchronous Communications document,
mentioned in `SEE ALSO', to follow.
.P
The
.I bscm
driver controls one or more Bisync multipoint communications lines
with respect to one or more logical stations per Bisync line using
this driver.
The communications line is attached to a host computer which polls
the cluster controller (driver) to see if any of the controller's
stations have any data to send, and selects specific statons when
there is data for them.
.P
The cluster controller can control up to 32 logical stations, numbered
0 to 31.
The
.I bscm
driver distinguishes between these logical stations at time of open;
each logical station has a separate minor device number.
The lower five bits of the minor device number are used for the logical
station number, and the upper three bits indicate the modem port number.
If, at the time of an open request to a modem port, there are no other
logical stations with this modem port open, the requestor will be
forced to wait until the modem port indicates DATA SET READY (DSR).
When the open is requested, the driver will signal DTR (data terminal ready)
to the modem.
This indicates the `data terminal' (the computer system)
end is ready to communicate whenever the modem is ready.
.P
A connection has been made when the modem signals DSR (data set ready)
to the modem port.
On modems used with leased lines, DSR is usually asserted as long
as power is available to the modem.
.P
The connection has been broken when the modem drops the DSR signal to the
modem port.
This only occurs when someone at either end breaks the connection
(usually due to a power failure).
The 
.I bscm
driver will automatically disconnect upon close
by dropping the DTR signal to the modem.
.P
Reads and writes to this device correspond to reading and writing complete
data blocks via the binary synchronous (BISYNC) protocol.
In BISYNC, a series of one or more data blocks is transmitted to the other
end of the line; the last of the series of blocks is specially marked to
show that it is the last one.
This series of blocks is commonly called a transmission file.
While transmission of the series of blocks is proceeding,
the receiving host cannot transmit data blocks, and thus data transmission
is one way at a time.
Write calls to the driver, therefore, may be rejected
if the driver is presently receiving data; receive calls will be rejected
if the driver is still transmitting a data file (this can happen if the
driver was not informed that the last write operation was the last of a
series, for example).
.P
The 
.I bscm
driver is controlled by open, close, read, and
write, as usual, and by parameters passed to it via the
.I ioctl
call.
These parameters control the line discipline, transmission
codes, and limit counts; the current status of the driver can be queried
by the same call (one may obtain error counts and number of blocks sent,
etc.)
The 
.I ioctl(2) 
calls use the structure and constants which are defined in 
.I <bscio.h>:
.P
.nf
.ta .4i 3i
struct bscio {
	unsigned short b_blks;	/* max data blocks/ #sent/rcvd */
	unsigned short b_flags;	/* see description */
	char b_termid[20];	/* our station id */
	char b_hostid[20];	/* host's id */
	unsigned char b_nbid;	/* bid limit/count */
	unsigned char b_nnak;	/* nak limit/count */
	unsigned char b_nretry;	/* retry limit/count */
	unsigned char b_nttd;	/* xmt delay limit/count */
	unsigned char b_nwack;	/* rcv delay limit/count */
	unsigned char b_nor;	/* rd timeout/# overruns */
	};
.fi
.P
The primary 
.I ioctl(2) 
calls have the form:
.P
.nf
.ta .8i
	ioctl (fildes, command, arg)
	struct bscio *arg;
.fi
.P
The commands are:
.P
.nf
.ta .8i 1.6i
	BSCGET	Get the current values associated with
		the variables indicated in the structure.

	BSCSET	Set the bsc driver parameters to the
		values contained in the structure.
.fi
.P
BSCSET is only allowed when there is only one device presently open
on the Bisync line, as the call can change the overall line characteristics.
.P
The first field (b_blks) is used to set the driver's maximum
transmission data block size.
This value cannot exceed 512.
Common block sizes are 510 for the IBM 3780 terminal,
398 for the IBM 2780 terminal, and 254 for the IBM 3270 terminals
(this figure refers only to the data portion of the block; the documentation
for these devices refers to a block size which includes transmission
control characters STX and ETX/ETB).
On a GET operation, the number of blocks
read and written since the open
is placed in this word.
.P
The second field, b_flags, may be used to set several mode indicators,
as follows:
.P
.nf
.ta .8i 2i 2.8i
	BSCASCII	0000001	Transmission code is ASCII
	BSCIUS	0000004	Unit separators in use
	BSCRVIABT	0000010	Abort on RVI sequence
.fi
.P
A GET operation results in the b_flags field being set to the type of the
last error:
.P
.nf
.ta .8i 2i 2.8i
	BSCPROTO	1	Protocol error by remote host
	BSCRVI	2	RVI Abort
	BSCNBID	3	NBID limit exceeded
	BSCNNAK	4	NNAK limit exceeded
	BSCNRETR	5	NRETRY limit exceeded
	BSCNTTD	6	NTTD limit exceeded
	BSCNWACK	7	NWACK limit exceeded
	BSCNDSR	8	No DSR indication from modem
	BSCTXTO	9	Transmit timeout
	BSCRXTO	10	Receive idle timeout
	BSCDSC	11	Disconnect message (DLE-EOT) sent
	BSCRABT	12	Remote end aborted our sending
	BSCEEOF	13	Remote end aborted their sending
	BSCTXP	15	Block received in transparent mode
			(not an error)
	BSCBSOH	16	Block began with SOH
			(not an error)
	BSCONTND	17	Contention error (during write)
.fi
.P
The third field, b_termid, is used to indicate the poll and select
addresses for this modem port.
The first byte of b_termid is the Poll address, the second is the
Select address.
Both characters must be translated to EBCDIC if that is the transmission
code in use.
.P
The fourth field, b_hostid, is reserved for future use in SET operations.
On a GET, this field will contain any
header information (given following an SOH and beginning a message block,
or preceding an ENQ, such as the poll or select address).
.P
The next several fields are used to set various protocol limits.
The b_nbid field is reserved for future use.
The number of negative acknowledgements the driver will give can be
set via the b_nnak field, number of response
timeouts and transmission errors which will be retried via the b_nretry
field, number of temporary transmit delays which will be accepted via the
b_nttd field, and number of received wait acknowledgements which will be
accepted via the b_nwack field.
For GET operations, these fields are set
to the counter values for these fields which have accumulated for the current
file transmission.
.P
The last field can be used to set a timeout value for read operations.
When set to a number of seconds between 1 and 127, it indicates the maximum
amount of time a read operation will suspend a process waiting to be
selected.
For GET operations, it indicates the number of receiver overruns which
have occurred during the current file transmission.
.P
The secondary calls to 
.I ioctl(2) 
have this form:
.P
.nf
.ta .8i
	ioctl (fildes, command, arg)
	int *arg, command;
.fi
.P
Note that `arg' is not used with most of the commands using this form.
The commands are:
.P
.nf
.ta .8i 2i
	BSCTRNSP	Turn on transparent mode
	BSCNTRNS	Turn off transparent mode
	BSCSOH	Force SOH block prefix
	BSCNSOH	Return to STX block prefix
	BSCLAST	Next block sent will be last
		(Send with ETX rather than ETB)
	BSCID	Return station address (in ASCII or
		EBCDIC, depending on b_flags)
	BSCNDLY	Set `no delay' mode for read requests
.fi
.P
Any eight-bit data can be sent in 
.I transparent
mode; data blocks in this mode will be preceded by
DLE STX and followed by DLE ETB or DLE ETX.
If a DLE character occurs
within the data, it must be preceded by another DLE character; other
protocol control characters will be ignored within the data block.
.P
If BSCIUS is set, it indicates Unit Separator characters may appear in
the data block.
Under Bisync conventions, Unit Separators are followed by a CRC (EBCDIC)
or LRC (ASCII).
The driver will generate the CRC or LRC as appropriate if the BSCIUS flag
is set and a Unit Separator is found, however, the data block must provide
the extra space in which to place the CRC (2 bytes) or LRC (1 byte).
.P
Data blocks not sent in 
.I transparent 
mode must not contain protocol control characters STX, ETX,
ETB, IUS, ENQ, or DLE.
.P
A data block is sent as is (no code translation), preceded
by a [DLE] STX and followed by [DLE] ETB or [DLE] ETX (the LAST block
has the ETX terminator, all others an ETB).
If a heading needs to
be sent on a block, the BSCSOH command forces the next block to be
preceded by SOH instead of STX; in this case, the data block given
to the driver should consist of the heading, followed by STX, followed
by the data.
.P
Under multi-point protocols, each station attached to a cluster has a
separate station address; the address is the same for polling and selecting.
The BSCID command returns in the location indicated by `arg' the station
address for the station corresponding to the file descriptor; this is given
in EBCDIC or ASCII in accordance with the line transmission code.
.P
The driver appends block check characters to each data block as appropriate
for the protocol code.
ASCII gets a one byte LRC code, and all data
bytes are sent with odd parity; EBCDIC gets
a two byte binary polynomial (CRC).
All protocol messages will begin
with SYN characters to establish synchronization; all messages
will be terminated with one or more padding characters consisting of all one
bits.
.P
Normally,
.I read
requests are blocked until data has been received to satisfy the read
request.
If BSCNDLY has been set since the
.I open,
read requests will not be blocked; errno will be set to
.SM EAGAIN
to indicate this.
.I Write
requests are not affected by BSCNDLY; writes are blocked
until the transmit buffer is available, or if BSCLAST was set before this
.I write
call, until the last block has been sent and acknowledged.
.P
When a station address is selected for which the corresponding minor
device is not open, data sent to that station will be accepted by the
driver but discarded.
It is therefore important to have processes attached to station addresses
for which this matters when the system is first initialized.
For information on how to do this, see
.I /etc/rc
or
.I inittab(8).
.P
The monitoring and tracing utilities
.I bscmon
and
.I bsctrace
can be used to monitor a line, but these do not discriminate as to
the station address which is currently active.
In order to determine this, the data trace option must be used;
however, this generates a lot of trace data, and thus
.I bscmon
should record data to a file.
.SH SEE ALSO
.P
.nf
.ta 1.5i
bscd(8)	IBM 2780/3780 Terminal Emulation
bscmon(8)	Monitoring and Tracing Utilities
em3270(8)	IBM 3270 Terminal Emulation
.I
General Information \- Binary Synchronous Communications,
IBM document GA27-3004.
.fi
.SH FILES
.nf
/dev/bsc*
.fi
.SH ERROR CODES
.TP
EAGAIN
BSCNDLY mode has been selected, and there is no data available to
satisfy the
.I read
request.
.TP
EIO
If an error occurs during a read or write operation,
.I errno
will be set to EIO.
An
.I ioctl
operation should be performed to determine the actual error
being reported (see above, BSCGET).
.TP
EINVAL
During a write operation, this indicates either: invalid length
(must be greater than zero and must not exceed b_blks), or
wrong mode (driver is presently in read mode).

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