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

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

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