Return to em3280.8 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/em3280.8, revision 1.1

1.1     ! root        1: '\" t
        !             2: .TH EM3280 8 DLBA 1.5
        !             3: \" @(#)em3280.8        1.5
        !             4: .SH NAME
        !             5: em3280 \- IBM 328X Printer Emulation
        !             6: .SH SYNOPSIS 
        !             7: .nf
        !             8: .I
        !             9:      /usr/bin/em3280
        !            10: .I
        !            11:      /usr/lib/bsc/bsclog
        !            12: .I
        !            13:      /usr/lib/bsc/bscmon
        !            14: .I
        !            15:      /usr/lib/bsc/bsctrace
        !            16: .fi
        !            17: 
        !            18: .SH DESCRIPTION 
        !            19: Em3280 is the communal name for the collection of programs and a file
        !            20: organization that allows a computer system to communicate emulating an IBM
        !            21: 328x printer. Together with a Bisync communications facility, 
        !            22: .I em3280
        !            23: can emulate an IBM 3284, 3286, 3287, or 3288 printer.
        !            24: The communications facility itself emulates the functions of the IBM 3271 
        !            25: communications control unit to which the 328x printer is usually attached.
        !            26: .P
        !            27: The Binary Synchronous protocol, commonly called BISYNC, is a byte-oriented,
        !            28: half-duplex protocol, although full-duplex communications facilities
        !            29: are sometimes used in order to reduce the time required to turn the
        !            30: transmission direction around. A set of control characters are used
        !            31: to provide framing and data transparency; data containing imbedded
        !            32: control characters may be transmitted in a "transparent" mode to
        !            33: avoid conflicts with the protocol control characters.
        !            34: (The IBM 328x printer does not use the "transparent" mode.)
        !            35: Communications may be point-to-point, in which case a contention
        !            36: method is used to control the line; communications may also be multi-point,
        !            37: in which case one node is designated the controlling node and polls
        !            38: and/or selects the other nodes in order to control communications. The
        !            39: IBM 328x printer is commonly used only in conjunction with multi-point
        !            40: BISYNC communications facilities.
        !            41: .P
        !            42: In the em3280 system, the administrator designates a collection of
        !            43: one or more hosts to which the computer connects emulating an
        !            44: IBM 328x printer. For each of these hosts, the administrator provides
        !            45: a set of parameters pertaining to that host connection and the specific
        !            46: printer parameters for emulation.
        !            47: .P
        !            48: Users may direct em3280 output to stdout, directly to a file or device
        !            49: (e.g. /dev/lp), or to a program (e.g. lpr).
        !            50: Four print formats are supported: fixed at 40, 64, or 80 characters per line,
        !            51: and variable-length, the data having newlines and other
        !            52: format effectors imbedded in it.
        !            53: .P
        !            54: An audit trail can optionally be kept which records all em3280
        !            55: activity. The audit trail logs host, user, and time for various messages
        !            56: about connection and disconnection,
        !            57: various statistics and all errors, temporary or permanent.
        !            58: Once started, the audit trail file grows indefinitely; the administrator
        !            59: is responsible for trimming it back when necessary.
        !            60: .P
        !            61: The following diagram shows the relationships between various files
        !            62: and programs used in the 328X emulation process.
        !            63: .TS
        !            64: box,center;
        !            65: c|c|c.
        !            66: DESIRED        USER    LINK
        !            67: FUNCTION       LEVEL   LEVEL
        !            68: _
        !            69: Emulate 328x   em3280  /dev/bsc*
        !            70: _      _       _
        !            71: Check status   bsclog  <dir>/AUDIT
        !            72: _
        !            73: Monitor        bscmon,                 /dev/bsctr*
        !            74: Activity       bsctrace
        !            75: .TE
        !            76: .P
        !            77: The 
        !            78: .I <dir> 
        !            79: designator refers to the host's spool directory.  This name is a combination of
        !            80: the directory prefix "/usr/spool/bscbatch/"
        !            81: followed by the <hostname> directory into which the AUDIT file
        !            82: pertaining to this host will be placed.
        !            83: .P
        !            84: At the beginning of a session (user invokes 
        !            85: .I em3280) 
        !            86: the utility will read the host parameter file to determine the communications
        !            87: line characteristics \- device to use, terminal identification, ...
        !            88: and the printer parameter file to determine printer characteristics \-
        !            89: output type (file or program), printer type (3284, 3286, ...),
        !            90: ....
        !            91: The communications line will be opened and the printer's characteristics
        !            92: noted. As files are received from the host, they will be formatted according
        !            93: to those characteristics and the output sent to either a user-specified
        !            94: destination (file, device, or program), or stdout if no destination was
        !            95: specified.
        !            96: .P
        !            97: When receive timeout is detected, the printer output device or file will be
        !            98: closed, then re-opened to flush whatever output has been spooled so far.
        !            99: .P
        !           100: The session is terminated when the daemon detects that the host has dropped
        !           101: the data set ready signal. At that point, connection with the host has been
        !           102: terminated.  The installation may provide an exit routine to be invoked at this
        !           103: time (immediately after termination of connection) to take care of
        !           104: any necessary cleanup.
        !           105: .P
        !           106: A trace facility can be invoked which records communications events
        !           107: and the time they occur,
        !           108: and optionally records actual data, transmitted and received. The
        !           109: trace information can be placed into a file for immediate or later
        !           110: analysis by another program.
        !           111: The general intent is to provide enough information for communications
        !           112: debugging that a data link analyzer is not necessary.
        !           113: .P
        !           114: The 
        !           115: .I bsctrace 
        !           116: program interprets trace information provided to 
        !           117: .I bscmon 
        !           118: by /dev/bsc*tr. A state diagram provided with the
        !           119: .I bscmon(8) 
        !           120: document shows the communication
        !           121: states and flow which makes up the BISYNC protocol; state transition
        !           122: information is provided to 
        !           123: .I bscmon, 
        !           124: which records
        !           125: it and optionally the transmitted and received data, in a file.
        !           126: .I Bsctrace 
        !           127: is used to display this data in a readable format.
        !           128: .SH ADMINISTRATION
        !           129: .SS Installation.
        !           130: The em3280 tape is used in the installation process for the em3280
        !           131: facility. To install em3280, do the following:
        !           132: .RS
        !           133: .IP 1.
        !           134: Make a directory to contain the installation files, e.g.,
        !           135: /tmp/em3280, then change to that directory. Use 
        !           136: .I tar xov0
        !           137: to copy the files from tape to the directory.
        !           138: The following files should be extracted:
        !           139: .TS
        !           140: center;
        !           141: c c c.
        !           142: em3280 em3280.x        empr.h
        !           143: 3280   3280inst        inst3280.c
        !           144: .TE
        !           145: .IP 2.
        !           146: Prepare installation exit subroutines, if necessary.
        !           147: File inst3280.c contains default
        !           148: subroutines for the installation exits, as described below. They
        !           149: may be modified or completely replaced, but must exist.
        !           150: .RS
        !           151: .P
        !           152: .I
        !           153: connect (host, dev)
        !           154: .br
        !           155: .I
        !           156: char *host, *dev;
        !           157: .P
        !           158: is called when 
        !           159: .I em3280 
        !           160: is ready to make a connection to
        !           161: .I host 
        !           162: via device
        !           163: .I devname. 
        !           164: The connection will be made only if 
        !           165: .I connect 
        !           166: returns a zero value; if a non-zero value is returned, a note will be placed
        !           167: in the AUDIT file (if one exists), and 
        !           168: .I em3280 
        !           169: will terminate.
        !           170: .P
        !           171: This routine may perform operator communication
        !           172: necessary for connection. The default (supplied) routine merely
        !           173: returns a zero value immediately.
        !           174: .P
        !           175: .I
        !           176: disconnect (host, devname)
        !           177: .br
        !           178: .I
        !           179: char *host, *devname;
        !           180: .P
        !           181: is called when 
        !           182: .I em3280 
        !           183: has just disconnected from the given host and device.
        !           184: This routine may perform any cleanup necessary
        !           185: at this time. The default (supplied) routine merely returns.
        !           186: .P
        !           187: .I
        !           188: audit (message)
        !           189: .br
        !           190: .I
        !           191: char *message;
        !           192: .P
        !           193: is a routine which may be called by any of the installation-supplied
        !           194: routines which need to place information into the AUDIT file. The
        !           195: single parameter will be written into the AUDIT file along with a
        !           196: time stamp and the current host's name.
        !           197: .RE
        !           198: .IP 3.
        !           199: Install all files. "3280inst" is a shell command file which will
        !           200: link the em3280 command object file with inst3280.c and
        !           201: install all commands and files into the appropriate directories.
        !           202: .RE
        !           203: .SS "Set Up Host Configurations."
        !           204: For each separate host, a file must be created in /usr/lib/bscbatch
        !           205: which supplies the control and administrative information used by
        !           206: em3280. The file may be created via the text editor.
        !           207: Sample configurations appear in file 3280, extracted in step 1 above.
        !           208: Any of the following parameters may be specified in the configuration
        !           209: file, one parameter per line. The default will be taken for any unspecified
        !           210: parameters.
        !           211: .TP
        !           212: CODE=ASCII|EBCDIC. 
        !           213: This specifies the transmission code
        !           214: to be used in the protocol, and what translation is to be performed
        !           215: on transmitted or received data. 
        !           216: Default: EBCDIC.
        !           217: .TP
        !           218: DEVICE=/dev/bsc*. 
        !           219: The device to be used for BISYNC operations must be specified here.
        !           220: Default: /dev/bsc.
        !           221: .TP
        !           222: DUPLEX=HALF|FULL. 
        !           223: Specify FULL for a full-duplex modem, HALF for a half-duplex modem.
        !           224: Default: HALF.
        !           225: .TP
        !           226: LINESPERPAGE=lines
        !           227: Specify the number of lines to be printed on a page.
        !           228: Default: 60.
        !           229: .TP
        !           230: MAIL=userid. 
        !           231: .I Em3280 
        !           232: will send mail to the system administrator (name given by 
        !           233: .I userid)
        !           234: for any significant problems requiring attention.
        !           235: These include incorrect parameters in this file,
        !           236: inability to connect to host, and host id check failures.
        !           237: Default: messages sent to /dev/console.
        !           238: .TP
        !           239: MPTADDR=aa.
        !           240: .I Aa
        !           241: is the address of the emulated printer if this is a multipoint network.
        !           242: If this is point-to-point, this parameter must not be specified.
        !           243: .I Aa
        !           244: consists of two alphabetic characters. The first is the polling address,
        !           245: the second the select address.
        !           246: Default: poll address=0x40, select address=0x60.
        !           247: .TP
        !           248: NBID=nn. 
        !           249: .I Nn 
        !           250: is the number of initial handshakes,
        !           251: or "line bids" which will be made when there is no host response.
        !           252: In a multipoint or other leased line arrangement, this value should
        !           253: be zero, which means retry forever.
        !           254: Maximum value for 
        !           255: .I nn: 
        !           256: 255.
        !           257: Default: 0 (no limit).
        !           258: .TP
        !           259: NNAK=nn. 
        !           260: .I Nn 
        !           261: specifies the number of NAK's (negative
        !           262: acknowledgement to text block due to CRC error) that the driver should
        !           263: give before terminating communications via sending EOT instead of
        !           264: NAK. This parameter prevents endless transmissions for cases where
        !           265: the text block was actually built incorrectly.
        !           266: Maximum value for 
        !           267: .I nn: 
        !           268: 255.
        !           269: Default: 16.
        !           270: .TP
        !           271: NRETRY=nn. 
        !           272: .I Nn 
        !           273: is the number of retries which will
        !           274: be made during transmission where a text block has been NAK'd (received
        !           275: with incorrect CRC, or check characters) or where a text block has
        !           276: had no response from the host (timeout).
        !           277: Maximum value for 
        !           278: .I nn: 
        !           279: 255.
        !           280: Default: 15.
        !           281: .TP
        !           282: NTTD=nn.
        !           283: .I Nn 
        !           284: is the number of TTD's (temporary
        !           285: text delays from host) that the driver should receive and NAK before
        !           286: terminating the receive operation via sending EOT. This parameter
        !           287: may be used to prevent prolonged delays from tying up a communications
        !           288: line. A value of zero will force the driver to always NAK a TTD.
        !           289: Maximum value for 
        !           290: .I nn: 
        !           291: 255.
        !           292: Default: 150.
        !           293: .TP
        !           294: NWACK=nn.
        !           295: .I Nn 
        !           296: is the maximum number of WACK's (wait
        !           297: acknowledgements) the driver will accept while attempting to transmit
        !           298: before terminating transmission via sending EOT. This parameter may
        !           299: be used to prevent prolonged delays while the host computer is unable
        !           300: to accept the next data block due to delays.
        !           301: A value of zero will force the driver to always accept a WACK.
        !           302: Maximum value for 
        !           303: .I nn: 
        !           304: 255.
        !           305: Default: 150.
        !           306: .TP
        !           307: OUTPUT=P|F,destination
        !           308: Specify whether output will be written to a file (F), or piped to a program (P),
        !           309: and the name  of the file or pipe.
        !           310: Default: P,lpr.
        !           311: .TP
        !           312: PTYPE=4|6|7|8|9
        !           313: Specify the type of IBM 328x printer being emulated; 4=3284, 6=3286, etc.
        !           314: Default: 4.
        !           315: .TP
        !           316: TIMEOUT=nnn
        !           317: If there are no files to be sent to the current host, and there is no
        !           318: activity from the host (no files being received from the host) for
        !           319: .I nnn
        !           320: seconds,
        !           321: .I bscd
        !           322: will disconnect.
        !           323: Default: 30.
        !           324: .TP
        !           325: TPRINT=YES|NO.
        !           326: Specifiy whether the IBM text print option, available only on 3288 printers, 
        !           327: will be used.
        !           328: Default: NO.
        !           329: .SS "Set Up Host SPOOL Area."
        !           330: For each host, make a directory /usr/spool/bscbatch/<hostname>.
        !           331: If an audit trail is to be kept on this host, create an empty file
        !           332: in that directory called AUDIT.
        !           333: .SS "Regular Maintenance."
        !           334: .P
        !           335: Some minimal maintenance of the host spool areas is required.
        !           336: The administrator's mailbox should be inspected and cleaned out regularly.
        !           337: The audit trail file (/usr/spool/bscbatch/<hostname>/AUDIT) should be truncated
        !           338: via the 
        !           339: .I bsclog 
        !           340: utility regularly.
        !           341: Most convenient is an entry in crontab \- once per day,
        !           342: .I
        !           343: bsclog -purge=3 
        !           344: could be run to discard all but
        !           345: AUDIT information for the last three days (see 
        !           346: .I bsclog(8)).
        !           347: .SH "SEE ALSO"
        !           348: .br
        !           349: em328x(1C) - 328x printer emulator
        !           350: .br
        !           351: bsclog(8) - batch audit trail utility
        !           352: .br
        !           353: bscmon(8) - bsc monitor/trace utilities
        !           354: .br
        !           355: .I
        !           356: Setting Up UNIX
        !           357: .br
        !           358: .I
        !           359: General Information - Binary Synchronous Communications,
        !           360: IBM document GA27-3004.
        !           361: .br
        !           362: .I
        !           363: 3270 Component Description,
        !           364: IBM document GA27-2749.
        !           365: .SH "SYSTEM REQUIREMENTS"
        !           366: .SS Modems.
        !           367: If two identical modems (same manufacturer, same options)
        !           368: are used at each end of the communications line, most any synchronous
        !           369: RS-232-C interface modem will function correctly. The following modems
        !           370: are definitely supported:
        !           371: .P
        !           372: .nf
        !           373:      Bell 201A3 (2000 bits per second)
        !           374:      Bell 201C  (2400 bits per second)
        !           375:      Bell 208B  (4800 bits per second)
        !           376:      Bell 209A  (9600 bits per second)
        !           377: .fi
        !           378: .SS Hardware.  
        !           379: This software is supported when used with the following:
        !           380: .P
        !           381: .nf
        !           382:      UNIX Version 7, System 3, or System 5 operating system
        !           383:      MODEM port jumpered for external clocking
        !           384:      MODEM port jumpered as Data Terminal Equipment
        !           385: .fi
        !           386: .SH DIAGNOSTICS
        !           387: .P
        !           388: em3280 <host>: can't open <confdir> configuration directory.
        !           389: .IP
        !           390: The configuration directory for this host couldn't be opened.
        !           391: Check the modes. Processing was aborted.
        !           392: .P
        !           393: em3280 <host>: <devname> cannot be opened for communications.
        !           394: .IP
        !           395: The communications device <devname> for the specified
        !           396: host could not be opened. Either the mode is set wrong, or some other
        !           397: process has the device open. Processing was aborted.
        !           398: .P
        !           399: em3280 <host>: unrecognized keyword, line <l> in <filename>.
        !           400: .IP
        !           401: While reading the host configuration file <filename>,
        !           402: an unrecognized keyword was found on line <l>. Probably a typographical
        !           403: error. Processing was aborted.
        !           404: .P
        !           405: em3280 <host>: invalid parameter for keyword <k> in <filename>.
        !           406: .IP
        !           407: While reading the host configuration file <filename>,
        !           408: keyword <k> was found to have an invalid parameter. Probably a typographical
        !           409: error, but it is also possible that the given parameter was out of
        !           410: range. Processing was aborted.
        !           411: .P
        !           412: em3280 <host>: device <devname> reports modem failure.
        !           413: .IP
        !           414: The named device reported a transmit timeout error. The usual reason
        !           415: for this is that the device did not get a transmit clock signal from
        !           416: the modem. This could be due to improper modem option specification,
        !           417: improper cable to the modem from the computer system, or to not having
        !           418: jumpered the MODEM port for external timing. Transmission is
        !           419: aborted for this host.

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