Return to bsc.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/bsc.4, revision 1.1

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