![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to bscm.4 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / usr.bin / bsc / doc|
Return to bscm.4 CVS log | Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / usr.bin / bsc / doc |
1.1 root 1: \" @(#)bscm.4 1.5
2: .TH BSCM 4 1.5 DLBA
3: .SH NAME
4: bscm \- BISYNC Cluster Controller Driver
5: .SH DESCRIPTION
6: .P
7: This section describes the general nature of the BISYNC Cluster Controller
8: driver.
9: .P
10: A prerequisite to fully understanding this section of the manual is a general
11: background in binary synchronous communications, which may be had by reading
12: the IBM General Information on Binary Synchronous Communications document,
13: mentioned in `SEE ALSO', to follow.
14: .P
15: The
16: .I bscm
17: driver controls one or more Bisync multipoint communications lines
18: with respect to one or more logical stations per Bisync line using
19: this driver.
20: The communications line is attached to a host computer which polls
21: the cluster controller (driver) to see if any of the controller's
22: stations have any data to send, and selects specific statons when
23: there is data for them.
24: .P
25: The cluster controller can control up to 32 logical stations, numbered
26: 0 to 31.
27: The
28: .I bscm
29: driver distinguishes between these logical stations at time of open;
30: each logical station has a separate minor device number.
31: The lower five bits of the minor device number are used for the logical
32: station number, and the upper three bits indicate the modem port number.
33: If, at the time of an open request to a modem port, there are no other
34: logical stations with this modem port open, the requestor will be
35: forced to wait until the modem port indicates DATA SET READY (DSR).
36: When the open is requested, the driver will signal DTR (data terminal ready)
37: to the modem.
38: This indicates the `data terminal' (the computer system)
39: end is ready to communicate whenever the modem is ready.
40: .P
41: A connection has been made when the modem signals DSR (data set ready)
42: to the modem port.
43: On modems used with leased lines, DSR is usually asserted as long
44: as power is available to the modem.
45: .P
46: The connection has been broken when the modem drops the DSR signal to the
47: modem port.
48: This only occurs when someone at either end breaks the connection
49: (usually due to a power failure).
50: The
51: .I bscm
52: driver will automatically disconnect upon close
53: by dropping the DTR signal to the modem.
54: .P
55: Reads and writes to this device correspond to reading and writing complete
56: data blocks via the binary synchronous (BISYNC) protocol.
57: In BISYNC, a series of one or more data blocks is transmitted to the other
58: end of the line; the last of the series of blocks is specially marked to
59: show that it is the last one.
60: This series of blocks is commonly called a transmission file.
61: While transmission of the series of blocks is proceeding,
62: the receiving host cannot transmit data blocks, and thus data transmission
63: is one way at a time.
64: Write calls to the driver, therefore, may be rejected
65: if the driver is presently receiving data; receive calls will be rejected
66: if the driver is still transmitting a data file (this can happen if the
67: driver was not informed that the last write operation was the last of a
68: series, for example).
69: .P
70: The
71: .I bscm
72: driver is controlled by open, close, read, and
73: write, as usual, and by parameters passed to it via the
74: .I ioctl
75: call.
76: These parameters control the line discipline, transmission
77: codes, and limit counts; the current status of the driver can be queried
78: by the same call (one may obtain error counts and number of blocks sent,
79: etc.)
80: The
81: .I ioctl(2)
82: calls use the structure and constants which are defined in
83: .I <bscio.h>:
84: .P
85: .nf
86: .ta .4i 3i
87: struct bscio {
88: unsigned short b_blks; /* max data blocks/ #sent/rcvd */
89: unsigned short b_flags; /* see description */
90: char b_termid[20]; /* our station id */
91: char b_hostid[20]; /* host's id */
92: unsigned char b_nbid; /* bid limit/count */
93: unsigned char b_nnak; /* nak limit/count */
94: unsigned char b_nretry; /* retry limit/count */
95: unsigned char b_nttd; /* xmt delay limit/count */
96: unsigned char b_nwack; /* rcv delay limit/count */
97: unsigned char b_nor; /* rd timeout/# overruns */
98: };
99: .fi
100: .P
101: The primary
102: .I ioctl(2)
103: calls have the form:
104: .P
105: .nf
106: .ta .8i
107: ioctl (fildes, command, arg)
108: struct bscio *arg;
109: .fi
110: .P
111: The commands are:
112: .P
113: .nf
114: .ta .8i 1.6i
115: BSCGET Get the current values associated with
116: the variables indicated in the structure.
117:
118: BSCSET Set the bsc driver parameters to the
119: values contained in the structure.
120: .fi
121: .P
122: BSCSET is only allowed when there is only one device presently open
123: on the Bisync line, as the call can change the overall line characteristics.
124: .P
125: The first field (b_blks) is used to set the driver's maximum
126: transmission data block size.
127: This value cannot exceed 512.
128: Common block sizes are 510 for the IBM 3780 terminal,
129: 398 for the IBM 2780 terminal, and 254 for the IBM 3270 terminals
130: (this figure refers only to the data portion of the block; the documentation
131: for these devices refers to a block size which includes transmission
132: control characters STX and ETX/ETB).
133: On a GET operation, the number of blocks
134: read and written since the open
135: is placed in this word.
136: .P
137: The second field, b_flags, may be used to set several mode indicators,
138: as follows:
139: .P
140: .nf
141: .ta .8i 2i 2.8i
142: BSCASCII 0000001 Transmission code is ASCII
143: BSCIUS 0000004 Unit separators in use
144: BSCRVIABT 0000010 Abort on RVI sequence
145: .fi
146: .P
147: A GET operation results in the b_flags field being set to the type of the
148: last error:
149: .P
150: .nf
151: .ta .8i 2i 2.8i
152: BSCPROTO 1 Protocol error by remote host
153: BSCRVI 2 RVI Abort
154: BSCNBID 3 NBID limit exceeded
155: BSCNNAK 4 NNAK limit exceeded
156: BSCNRETR 5 NRETRY limit exceeded
157: BSCNTTD 6 NTTD limit exceeded
158: BSCNWACK 7 NWACK limit exceeded
159: BSCNDSR 8 No DSR indication from modem
160: BSCTXTO 9 Transmit timeout
161: BSCRXTO 10 Receive idle timeout
162: BSCDSC 11 Disconnect message (DLE-EOT) sent
163: BSCRABT 12 Remote end aborted our sending
164: BSCEEOF 13 Remote end aborted their sending
165: BSCTXP 15 Block received in transparent mode
166: (not an error)
167: BSCBSOH 16 Block began with SOH
168: (not an error)
169: BSCONTND 17 Contention error (during write)
170: .fi
171: .P
172: The third field, b_termid, is used to indicate the poll and select
173: addresses for this modem port.
174: The first byte of b_termid is the Poll address, the second is the
175: Select address.
176: Both characters must be translated to EBCDIC if that is the transmission
177: code in use.
178: .P
179: The fourth field, b_hostid, is reserved for future use in SET operations.
180: On a GET, this field will contain any
181: header information (given following an SOH and beginning a message block,
182: or preceding an ENQ, such as the poll or select address).
183: .P
184: The next several fields are used to set various protocol limits.
185: The b_nbid field is reserved for future use.
186: The number of negative acknowledgements the driver will give can be
187: set via the b_nnak field, number of response
188: timeouts and transmission errors which will be retried via the b_nretry
189: field, number of temporary transmit delays which will be accepted via the
190: b_nttd field, and number of received wait acknowledgements which will be
191: accepted via the b_nwack field.
192: For GET operations, these fields are set
193: to the counter values for these fields which have accumulated for the current
194: file transmission.
195: .P
196: The last field can be used to set a timeout value for read operations.
197: When set to a number of seconds between 1 and 127, it indicates the maximum
198: amount of time a read operation will suspend a process waiting to be
199: selected.
200: For GET operations, it indicates the number of receiver overruns which
201: have occurred during the current file transmission.
202: .P
203: The secondary calls to
204: .I ioctl(2)
205: have this form:
206: .P
207: .nf
208: .ta .8i
209: ioctl (fildes, command, arg)
210: int *arg, command;
211: .fi
212: .P
213: Note that `arg' is not used with most of the commands using this form.
214: The commands are:
215: .P
216: .nf
217: .ta .8i 2i
218: BSCTRNSP Turn on transparent mode
219: BSCNTRNS Turn off transparent mode
220: BSCSOH Force SOH block prefix
221: BSCNSOH Return to STX block prefix
222: BSCLAST Next block sent will be last
223: (Send with ETX rather than ETB)
224: BSCID Return station address (in ASCII or
225: EBCDIC, depending on b_flags)
226: BSCNDLY Set `no delay' mode for read requests
227: .fi
228: .P
229: Any eight-bit data can be sent in
230: .I transparent
231: mode; data blocks in this mode will be preceded by
232: DLE STX and followed by DLE ETB or DLE ETX.
233: If a DLE character occurs
234: within the data, it must be preceded by another DLE character; other
235: protocol control characters will be ignored within the data block.
236: .P
237: If BSCIUS is set, it indicates Unit Separator characters may appear in
238: the data block.
239: Under Bisync conventions, Unit Separators are followed by a CRC (EBCDIC)
240: or LRC (ASCII).
241: The driver will generate the CRC or LRC as appropriate if the BSCIUS flag
242: is set and a Unit Separator is found, however, the data block must provide
243: the extra space in which to place the CRC (2 bytes) or LRC (1 byte).
244: .P
245: Data blocks not sent in
246: .I transparent
247: mode must not contain protocol control characters STX, ETX,
248: ETB, IUS, ENQ, or DLE.
249: .P
250: A data block is sent as is (no code translation), preceded
251: by a [DLE] STX and followed by [DLE] ETB or [DLE] ETX (the LAST block
252: has the ETX terminator, all others an ETB).
253: If a heading needs to
254: be sent on a block, the BSCSOH command forces the next block to be
255: preceded by SOH instead of STX; in this case, the data block given
256: to the driver should consist of the heading, followed by STX, followed
257: by the data.
258: .P
259: Under multi-point protocols, each station attached to a cluster has a
260: separate station address; the address is the same for polling and selecting.
261: The BSCID command returns in the location indicated by `arg' the station
262: address for the station corresponding to the file descriptor; this is given
263: in EBCDIC or ASCII in accordance with the line transmission code.
264: .P
265: The driver appends block check characters to each data block as appropriate
266: for the protocol code.
267: ASCII gets a one byte LRC code, and all data
268: bytes are sent with odd parity; EBCDIC gets
269: a two byte binary polynomial (CRC).
270: All protocol messages will begin
271: with SYN characters to establish synchronization; all messages
272: will be terminated with one or more padding characters consisting of all one
273: bits.
274: .P
275: Normally,
276: .I read
277: requests are blocked until data has been received to satisfy the read
278: request.
279: If BSCNDLY has been set since the
280: .I open,
281: read requests will not be blocked; errno will be set to
282: .SM EAGAIN
283: to indicate this.
284: .I Write
285: requests are not affected by BSCNDLY; writes are blocked
286: until the transmit buffer is available, or if BSCLAST was set before this
287: .I write
288: call, until the last block has been sent and acknowledged.
289: .P
290: When a station address is selected for which the corresponding minor
291: device is not open, data sent to that station will be accepted by the
292: driver but discarded.
293: It is therefore important to have processes attached to station addresses
294: for which this matters when the system is first initialized.
295: For information on how to do this, see
296: .I /etc/rc
297: or
298: .I inittab(8).
299: .P
300: The monitoring and tracing utilities
301: .I bscmon
302: and
303: .I bsctrace
304: can be used to monitor a line, but these do not discriminate as to
305: the station address which is currently active.
306: In order to determine this, the data trace option must be used;
307: however, this generates a lot of trace data, and thus
308: .I bscmon
309: should record data to a file.
310: .SH SEE ALSO
311: .P
312: .nf
313: .ta 1.5i
314: bscd(8) IBM 2780/3780 Terminal Emulation
315: bscmon(8) Monitoring and Tracing Utilities
316: em3270(8) IBM 3270 Terminal Emulation
317: .I
318: General Information \- Binary Synchronous Communications,
319: IBM document GA27-3004.
320: .fi
321: .SH FILES
322: .nf
323: /dev/bsc*
324: .fi
325: .SH ERROR CODES
326: .TP
327: EAGAIN
328: BSCNDLY mode has been selected, and there is no data available to
329: satisfy the
330: .I read
331: request.
332: .TP
333: EIO
334: If an error occurs during a read or write operation,
335: .I errno
336: will be set to EIO.
337: An
338: .I ioctl
339: operation should be performed to determine the actual error
340: being reported (see above, BSCGET).
341: .TP
342: EINVAL
343: During a write operation, this indicates either: invalid length
344: (must be greater than zero and must not exceed b_blks), or
345: 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.