Return to bscm.4 CVS log

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

Annotation of cci/usr/src/usr.bin/bsc/doc/bscm.4, revision 1.1

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.