HP-UX TN3270 Administration Guide Edition 2 Customer Order Number: J2656-90037 HP 9000 Networking Manufacturing Part Number: J2656-90037 E06/01 United States © Copyright 2001 © Hewlett-Packard Company, 2001. All rights reserved.
Legal Notices The information in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material. Warranty.
©copyright 1980, 1984, 1986 Novell, Inc. ©copyright 1986-1992 Sun Microsystems, Inc. ©copyright 1985-86, 1988 Massachusetts Institute of Technology. ©copyright 1989-93 The Open Software Foundation, Inc. ©copyright 1986 Digital Equipment Corporation. ©copyright 1990 Motorola, Inc.
Contents 1. Understanding TN3270 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is TN3270? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TN3270 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TN3270 Features Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Controlling Tracing of the TN3270 Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Tracing of HLLAPI Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling the Amount of Trace Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resetting Trace Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trace File Formats . . . . . . . . . . . . . . . . . . . . . .
Preface The HP-UX TN3270 Administrators Guide describes how to install, configure, and manage TN3270.
Intended Audience This book is intended for administrators responsible for installing, configuring, using, and maintaining TN3270 on a computer that uses the HP-UX operating system.
About This Book This section explains how informatoin is organized and presented in this book. Organization of This Book This book is organized as follows: Chapter 1, “Understanding TN3270.” Provides conceptual information to help you understand how to configure and manage TN3270 and lists the administration tasks you need to perform Chapter 2, “Installing TN3270.
Typographic Conventions Table 1, “Typographic Conventions,” shows the typographic styles used in this document. Table 1 Typographic Conventions Special Element Sample of Typography Document title HP-UX SNAplus2 3270 & TN3270 HLLAPI Programmers Guide File or path name com.
Table 1 Typographic Conventions Special Element Sample of Typography Keyboard keys Up 11
TN3270 Manual Set The TN3270 product provides the following documentation: HP-UX TN3270 Administrators Guide Explains how to install, configure, and manage TN3270. It describes the requirements for installing the TN3270 software, how to set up configuration information for using 3270 emulation, and how to use the product's diagnostics tools to resolve problems. HP-UX TN3270 Users Guide Explains how to use 3270 emulation, including the following tasks: • Start and stop 3270 emulation. • Transfer files.
Related Publications For additional information about IBM 3270 Information Display System Products, refer to the following publications: • IBM 3270 Information Display System: — 3274 Control Unit Description and Programmer's Guide, GA23-0061 — Color and Programmed Symbols, GA33-3056 — 3274 Control Unit Display Station: Operator's Guide , GA23-0023 — 3174 Control Unit Functional Description, GA23-0218 • The following Internet Requests for Comments (RFCs): — 854: Telnet Protocol Specification — 855: Telnet Op
1 Understanding TN3270 Chapter 1 15
Understanding TN3270 Overview Overview This chapter provides an overview of the TN3270 product and describes the responsibilities of the TN3270 administrator. The administrator is responsible for installing, configuring, and managing the TN3270 software.
Understanding TN3270 What Is TN3270? What Is TN3270? TN3270 is a software product that enables HP-UX computer terminals to connect over a TCP/IP network and emulate 3270 terminals connected to a host computer. Two versions of the TN3270 program, with different user interfaces, are available: a character-based version that runs on standard text terminals and a Motif graphical user interface.
Understanding TN3270 What Is TN3270? a TN3270 user. Using this API enables you to automate frequently used TN3270 emulation tasks, such as host application startup. For more information about the functions provided by HLLAPI, refer to the HP-UX SNAplus2 3270 & TN3270 HLLAPI Programmers Guide. TN3270 style files The TN3270 program enables you to customize TN3270 emulation parameters such as color mappings, HP-UX terminal keys used to represent host 3270 keys, and HLLAPI session IDs for TN3270 sessions.
Understanding TN3270 What Is TN3270? Audit log file A single file that contains a record of all significant system events. The name of this file, and the level of detail recorded in it, are specified in the configuration file. Trace files One or more optional trace files record the data transferred between the TN3270 program and the host, or between a HLLAPI application and the TN3270 program. You can use these files to help you debug specific problems.
Understanding TN3270 What Is TN3270? Sessions dialog box. For more information about these dialog boxes, refer to the TN3270 Users Guide. TN3270 does not provide support for the following functions that are described in the various RFCs that are supported: • The device type IBM-DYNAMIC. The device type that corresponds to the configured display model is used instead. • Keep-alive messages, although it does respond to them.
Understanding TN3270 What Are the TN3270 Administrator Responsibilities? What Are the TN3270 Administrator Responsibilities? As the TN3270 administrator, you have the following responsibilities: 1. Installing the TN3270 software. For more information about the hardware and software requirements for TN3270 and about installing the software, see Chapter 2, “Installing TN3270.” For additional information about installing TN3270, see Appendix A, “Required and Recommended Functions in the terminfo Database.
Understanding TN3270 What Are the TN3270 Administrator Responsibilities? 22 Chapter 1
2 Installing TN3270 Chapter 2 23
Installing TN3270 Overview Overview This chapter desribes the installation procedure used to install the TN3270 software.
Installing TN3270 Loading the Product Files Loading the Product Files After determining that you have the hardware, software and host requirements for the TN3270 product, you will need to load the TN3270 product file, as follows: Step 1. Ensure that you have a CD-ROM drive attached to your system to read the product file. This drive should be configured on your system with an entry in the /dev directory. Step 2.
Installing TN3270 Loading the Product Files 26 Chapter 2
3 Configuring TN3270 Chapter 3 27
Configuring TN3270 Overview Overview This chapter describes how to configure TN3270 and the information you need.
Configuring TN3270 Overview of the Configuration Process Overview of the Configuration Process TN3270 uses a single configuration file to hold the following details of your TN3270 configuration: • The host computers you can access • The TN3270 emulation functions available to individual TN3270 users • The files used to record TN3270 diagnostics information You create this single binary configuration file by first defining a configuration text file and then using the tncfgtcp program to convert the text fil
Configuring TN3270 Overview of the Configuration Process a syntax error in the text file, it writes a message to standard error and does not create a binary configuration file. For syntax errors, the program continues to parse the text file and writes a separate message for each error it finds. Correct the errors and run tncfgtcp again. If no errors are found, TN3270 creates the binary configuration file in the same directory as the text file.
Configuring TN3270 Overview of the Configuration Process TN3270 emulation program continue to run with the previous configuration and are not affected by the change. For example, if you change the parameters that control whether audit or exception messages (or both) are recorded, any active TN3270 emulation programs continue to use the previous settings. Users must stop and restart the TN3270 emulation program for the new settings to take effect.
Configuring TN3270 Understanding the Configuration Text File Records Understanding the Configuration Text File Records The configuration text file contains the following types of configuration records: host record Specifies the following information about a host that can be accessed using TN3270: • Either the host's symbolic domain name or Internet Protocol (IP) 32–bit dotted-decimal address • TCP/IP port used to access the host • 3270 screen model that the host supports The configuration file contains at
Configuring TN3270 Understanding the Configuration Text File Records HP-UX user who has permission to use TN3270 emulation. Instead of configuring each user explicitly, you can set up a default user record to be used by any HP-UX user.
Configuring TN3270 Understanding the Configuration Text File Records A name that identifies the individual record. The value assigned must not match the name of any other record of the same type. The following characters are valid: A–Z, 0–9, @, #, and $. (The characters a–z are also accepted but are converted to uppercase.) The value chosen is for the System Administrator's use only; it has no relevance outside of the TN3270 system. Choose a name that identifies the resource.
Configuring TN3270 Understanding the Configuration Text File Records • Range of allowed values. The value shown in the table depends on the field type: — For record, text, and file fields, range indicates the minimum and maximum number of characters allowed in a string. — For number fields, range indicates the minimum and maximum numeric values for the field. — For flag and choice fields, range is not used. • Whether the field is required or optional.
Configuring TN3270 Understanding the Configuration Text File Records line, any text following it (to the end of the line) is treated as a comment and ignored. Format of a host Record The host record provides information about a session with a TCP/IP host.Table 3-1, “Summary of host Parameters,” summarizes the parameters in a host record.
Configuring TN3270 Understanding the Configuration Text File Records Specify either the symbolic domain name or the 32-bit dotted-decimal Internet Protocol (IP) address of the TN3270 host. Use 1–100 of any printable, case-sensitive characters. For examples, see “Example of a host Record Using a Symbolic Domain Name” and “Example of a host Record Using a 32-Bit Dotted-Decimal IP Address”.
Configuring TN3270 Understanding the Configuration Text File Records Include this field with no value if a TN3270 user can override the screen model (can change the TN3270 session customization to use a different model). port Specify the TCP/IP port number that the host uses for TN3270 data. tn3270_support Specify the level of TN3270 support desired. Possible values are: TN3270 Only basic TN3270 protocols are supported.
Configuring TN3270 Understanding the Configuration Text File Records domain model override lu_name tn3270_support protocols Example 3-3 [host] name domain model override port tn3270_support = remote.host.addr = 4 ; ; ; ; = TNLU1 = TN3270E model 4: 43 x 80 user can override screen model use LU specified use enhanced TN3270E Example of a host Record Using a 32-Bit Dotted-Decimal IP Address = hostrec2 = 123.123.123.
Configuring TN3270 Understanding the Configuration Text File Records name Specify the name of the TN3270 user. Use 1–20 of any printable, case-sensitive characters. This value must match the HP-UX login ID of a user on the TN3270 computer. You can also set up a default TN3270 user record, using the name (in uppercase letters and surrounded by angle brackets, as shown). The record allows any HP-UX user to use TN3270 emulation.
Configuring TN3270 Understanding the Configuration Text File Records permission to modify the default style by including the modify_style field, TN3270 first searches for a file of the same name in the user's home directory. If you are setting up a standard style for all your users, store the file in /etc/opt/tn3270 and do not give users write access to this file.
Configuring TN3270 Understanding the Configuration Text File Records view_rtm change_domain records ; users can view RTM data ; users can override domain and port field in host Format of diagnostics Record The diagnostics record specifies the files used for audit and error logging and specifies the default logging level. The configuration text file must contain only one diagnostics record. Table 3-3, “Summary of diagnostics Parameters,” summarizes the parameters in a diagnostics record.
Configuring TN3270 Understanding the Configuration Text File Records the same file, use the file extension .log and specify the same value for this field and for the audit_file field. audit_file Use 5–49 characters to indicate the full path and file name of the audit log file, which is used to record audit messages. The file extension must be either .log or .aud. If you want to send both error and audit messages to the same file, use the file extension .
Configuring TN3270 Understanding the Configuration Text File Records and 4, and above boundary 4. Specify the boundaries as decimal numbers, from 5–1000, representing tenths of seconds. A value of 10 represents 1 second. The boundaries must not overlap. Boundary 4 must be greater than boundary 3, boundary 3 must be greater than boundary 2, and boundary 2 must be greater than boundary 1.
4 Using TN3270 Log Messages Chapter 4 45
Using TN3270 Log Messages Overview Overview This chapter provides information about how to control the logging and format of TN3270 log messages and explains what types of actions you can take based on information in the messages.
Using TN3270 Log Messages Overview of TN3270 Logging Overview of TN3270 Logging TN3270 logs messages for the following event categories: Problem event An abnormal event that degrades the system in a way that is easily perceived by a user. An example is abnormal termination of a session. TN3270 always logs these events. You cannot choose to disable logging of these events. By default, TN3270 logs these events to the file sna.err in the /var/opt/tn3270 subdirectory.
Using TN3270 Log Messages Overview of TN3270 Logging subdirectory. You can specify a different file name in the diagnostics configuration file record. If you prefer, you can specify that TN3270 log all messages to the same file by specifying the name of that file with the extension .log in both the exception and audit fields of the diagnostics configuration file record. For more information about the diagnostics configuration file record, see Chapter 3, “Configuring TN3270.
Using TN3270 Log Messages Backing Up and Resetting a Log File Backing Up and Resetting a Log File TN3270 provides a backup mechanism to prevent log files from becoming too large and consuming disk resources. When a log file reaches 1 megabyte, TN3270 copies its current contents to a backup file and then clears the log file. If error and audit information is logged in one file, a maximum of 2 megabytes of log information is stored.
Using TN3270 Log Messages Format of Log Messages Format of Log Messages This section explains the information given in the log file for each message. The following example shows a typical log message with notes on the information shown on each line: Example 4-1 Log Message Sample 12:17:28 GMT 11 Nov 1996 - Timestamp 3270 Message 0-26, Subcode: 0 Log category: PROBLEM Cause Type: Config System: tnbox Process ID: 12345 (tn3270) There are no sessions configured for 3270 user abc.
Using TN3270 Log Messages Format of Log Messages Log category The event category of the log message. Possible values are Problem, Exception, or Audit events. Cause type A summary of the cause of the message. Possible values are: Internal Internal error in the TN3270 software. Report errors of this type to your TN3270 support personnel. System limit An internal limiting value in the TN3270 software. External A cause external to TN3270.
Using TN3270 Log Messages Format of Log Messages caused the message was detected. Process ID and name The HP-UX process ID and executable name of the process that logged the message. Message text Text describing the condition being logged. This field may include a number of variable parameters relating to this particular occurrence of the message. For example, a message reporting failure to start a TN3270 session may include the TN3270 user name and the session number.
Using TN3270 Log Messages Recommended Actions for Log Messages Recommended Actions for Log Messages The Message action field for a logged message describes the recommended action. In some cases, no action is required. For example, an exception message may not indicate an error, but it may provide background information that helps to identify the cause of a later problem message. Common recommended actions include the following: • Check the TN3270 configuration, and add or modify resources.
Using TN3270 Log Messages Recommended Actions for Log Messages Sending Log and Trace Files to Support Personnel If the recommended action for a message includes sending the log files and trace files to support services, provide the error and audit log files created when the error occurred. If tracing was enabled, provide the trace files as well. If you were running TN3270 with audit logging or exception logging (or both) disabled, attempt to reproduce the problem with all categories of logging enabled.
5 Using TN3270 Tracing Facilities Chapter 5 55
Using TN3270 Tracing Facilities Overview Overview This chapter explains how to use TN3270 trace facilities to collect diagnostics data and how to produce trace output.
Using TN3270 Tracing Facilities Overview of TN3270 Tracing Overview of TN3270 Tracing TN3270 supports the following types of tracing: HLLAPI tracing Traces all the parameters that the HLLAPI application supplies to the HLLAPI library and all the parameters that the HLLAPI library returns to the application. For more information, see “Controlling Tracing of HLLAPI Applications”.
Using TN3270 Tracing Facilities Overview of TN3270 Tracing Boundaries 58 Chapter 5
Using TN3270 Tracing Facilities Controlling Tracing Controlling Tracing This section describes how you can start and stop tracing, how you specify the names of trace files, and how you can control the size of trace files. Controlling Tracing of the TN3270 Program The SNAMSG environment variable controls tracing the TN3270 program. The syntax for SNAMSG is: file1 [ : file2 ] Specify the following parameters in the SNAMSG environment variable: file1 Name of the trace file.
Using TN3270 Tracing Facilities Controlling Tracing Specifying Trace Files for a HLLAPI Application The SNATRC environment variable specifies one or two files to hold trace data and indicates whether to activate tracing when the application starts. The syntax for the SNATRC environment variable is: file1 [ : [ file2 ] [ : ] ] Specify the following parameters in the SNATRC environment variable: file1 Name of the trace file. file2 Optionally included name of a second trace file.
Using TN3270 Tracing Facilities Controlling Tracing The following examples illustrate the SNATRACESIZE environment variable: file1.trc:file2.trc Trace to file1 and file2. Tracing is inactive when the HLLAPI application is started. filea.trc:: Trace to one file (filea.trc). Tracing starts when the HLLAPI application is started.
Using TN3270 Tracing Facilities Controlling Tracing To use SNACTL, set it to any non-blank string. To cancel it, set SNACTL to a blank character. Controlling the Amount of Trace Data The following environment variables control the amount of data stored in trace files: SNATRUNC Specifies the maximum length in bytes of each entry in a trace file.
Using TN3270 Tracing Facilities Controlling Tracing Resetting Trace Files The SNATRCRESET environment variable controls whether a trace file is reset when an application first writes to it. Normally, the file is reset and its contents discarded when an application writes its first trace message to the file.
Using TN3270 Tracing Facilities Trace File Formats Trace File Formats This section provides examples and information about how to interpret the trace output for the different trace types. Common File Information The trace data for a single message can occupy more than one line in the trace file. Each individual message is preceded by a horizontal line indicating the time at which the trace entry was made.
Using TN3270 Tracing Facilities Trace File Formats the format in which they flow over the network. These messages are useful for investigating network problems. FMI data Traces data transferred between TN3270 and the host in the format in which they are represented inside TN3270. These messages can be useful for investigating local problems and problems with remote systems. The start of each trace entry shows the type of message being traced and a decoded version of some of the header information.
Using TN3270 Tracing Facilities Trace File Formats Table 5-1 Abbreviations Used in Trace Message Headers SC Session control TH Transmission header File Information for HLLAPI Tracing The following parameters for each HLLAPI function are traced when the function is issued and again when it returns. func_number This parameter is shown in parentheses after the name of the function. data_length and ps_position/return code These parameters are always shown following func_number.
A Required and Recommended Functions in the terminfo Database Appendix A 67
Required and Recommended Functions in the terminfo Database Overview Overview This chapter describes how to define the required or recommended functions in the terminfo database.
Required and Recommended Functions in the terminfo Database Defining Functions in terminfo Defining Functions in terminfo To allow HP-UX terminals to use the screen interface of the TN3270 program, define the following required or recommended functions in the terminfo database. To alter the terminfo database, use the tic and infocmp programs provided with your HP-UX operating system.
Required and Recommended Functions in the terminfo Database Defining Functions in terminfo HP-UX terminal does not support drawing menus and dialog boxes, it can still use the menu interface, but the menus and dialog boxes will be drawn with characters such as - and + instead of solid lines. The TN3270 program with the international option uses the ISO 8859 character set instead of the PC character set.
Required and Recommended Functions in the terminfo Database Defining Functions in terminfo Used for moving backwards through the sequence of items in a dialog box. If Backtab is not available, the keystroke Ctrl+B can be used instead. (These keystrokes are equivalent only in the menu interface.) In TN3270 emulation, the default key mapping for the 3270 BACKTAB key is Backtab; remap this to Ctrl+B or any other suitable keystroke if you do not have the Backtab key.
Required and Recommended Functions in the terminfo Database Defining Functions in terminfo this may mean that the last line of the screen is shared between the TN3270 display and the status line. The TN3270 program's default keyboard mapping (the mapping between keystrokes on the HP-UX terminal and the 3270 keys they represent) assumes that the HP-UX terminal's keyboard has all the keys included in both the Required and Recommended lists.
B Using Shared Memory and Semaphores This appendix describes how to define the amount of shared memory and semaphores required by TN3270 on the HP-UX computer.
Using Shared Memory and Semaphores Tuning System Parameters Tuning System Parameters Normally, the default values for these parameters are suitable for typical TN3270 configurations. In some cases, it may be necessary to tune some of these parameters. Tuning should only be done once TN3270 has been successfully installed and started using the defaults. The parameters should be set to large enough values to accommodate both the TN3270 requirements and the requirements of any other programs on the system.
C Migrating from Earlier Versions of TN3270 Appendix C 75
Migrating from Earlier Versions of TN3270 Overview Overview This appendix explains how to migrate from an earlier version of TN3270 to the current version.
Migrating from Earlier Versions of TN3270 Summary of Migrating from TN3270 Release 4 to TN3270 Release 6 Summary of Migrating from TN3270 Release 4 to TN3270 Release 6 The following summary helps you determine the migration steps that you need to take. Depending on the TN3270 functions that you use, you may not need to perform all of the steps. To migrate from TN3270 Release 4 to TN3270 Release 6, perform the following steps: Step 1.
Migrating from Earlier Versions of TN3270 Summary of Migrating from TN3270 Release 4 to TN3270 Release 6 migration program to make the necessary modifications to the configuration file. For more information about the configuration file format, see Chapter 3, “Configuring TN3270.
Migrating from Earlier Versions of TN3270 Summary of Migrating from TN3270 Release 4 to TN3270 Release 6 as follows: Table C-1 audit_level(Release 4) Release 6 field (omitted) exception 10 exception 8 audit, exception 6 audit, exception For more information about the audit and exception fields, see Chapter 4, “Using TN3270 Log Messages.
Migrating from Earlier Versions of TN3270 Summary of Migrating from TN3270 Release 4 to TN3270 Release 6 Trace File Format The format of trace files has changed slightly. In addition to the hexadecimal listing, message data is now interpreted both as EBCDIC and as ASCII in two separate columns rather than being interpreted character-by-character as either ASCII or EBCDIC.
Index A access to TN3270 functions, 17 administration tasks, 16 administrator responsibilities, 21 API (application program interface), 18 audit log file, 19, 48 automating TN3270 emulation start-up, 18 B binary configuration file, creating, 29 C character-based TN 3270 emulation program, 17 configuration, 16, 18, 21, 28, 29 configuration file converting to Release 5 format, 78 migration utility, 78 overview, 18 configuration file records, 32 configuration file, overview, 29 configuration information, 30 co
Index S sample configuration text file, 29 semaphores, 74 shared memory, 74 SNACTL environment variable, 61 SNAMSG environment variable, 59 SNATRC environment variable, 59, 60 style file, 18 swinstall command, 25 swverify command, 25 T TCP/IP, 17 TCP/IP host, 36 TN3270 loading, 25 TN3270 emulation program configuration options, 17 different versions, 17 features, 17 tracing, 59 TN3270 message tracing, 65 TN3270 sessions, 17 TN3270 style files, 21 TN3270 user, 39 tncfgtcp program command syntax, 29 use, 18,
