HP-UX TN3270 Administration Guide 11iv1 and 11iv2 Manufacturing Part Number: J6381-90002 United States © Copyright 2005 © Hewlett-Packard Company, 2005. 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.
Contents 1. Understanding TN3270 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is TN3270? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TN3270 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TN3270 Features Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of TN3270 Tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Tracing of the TN3270 Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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.
Table 1 Typographic Conventions Special Element Sample of Typography Document title HP-UX SNAplus2 3270 & TN3270 HLLAPI Programmers Guide File or path name com.cfg Directory name /opt/sna/ Program or application tncfgtcp Command or HP-UX utility vi Option or flag TRON Parameter tn3270_support Name of a TN3270 configuration record host record Constant IBM-DYNAMIC Return value System limit Variable representing a supplied value devicename Environment variable PATH User input file1.
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
1 Chapter 1 Understanding TN3270 11
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? A single file that contains a record of any errors that TN3270 detects. The name of this file is specified in the configuration file. 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.
Understanding TN3270 What Is TN3270? The TN3270E features are supported only if the directly connected host, or the communications product that provides the TN Server function, also supports the TN3270E features. When the connection is established, the host or communications product negotiates with the TN3270 product to determine the level of support. You can configure the level of support that you desire for the TN3270 product by specifying a value for the tn3270_support field in the host record.
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? 18 Chapter 1
2 Chapter 2 Installing TN3270 19
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. Use the HP-UX tool swinstall to load the TN3270 product (load J6381AA).
Installing TN3270 Loading the Product Files 22 Chapter 2
3 Chapter 3 Configuring TN3270 23
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 te
Configuring TN3270 Overview of the Configuration Process If the tncfgtcp program detects an error, such as an invalid file name or 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.
Configuring TN3270 Overview of the Configuration Process It is possible to write a new configuration directly to the running configuration file /etc/opt/tn3270/com.cfg by using the file /etc/opt/tn3270/com.txt as input. However, any active copies of the TN3270 emulation program continue to run with the previous configuration and are not affected by the change.
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 contai
Configuring TN3270 Understanding the Configuration Text File Records The configuration file contains one user record for each 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 record 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 • Which field type is expected for the field name. • 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 The semi-colon (;) character indicates a comment string. If you include this character at any point on a 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 override 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 Following are two examples of host records: Example 3-2 [host] name domain model override lu_name tn3270_support protocols Example 3-3 [host] name domain model override port tn3270_support Example of a host Record Using a Symbolic Domain Name = hostrec1 = remote.host.
Configuring TN3270 Understanding the Configuration Text File Records Table 3-2 Summary of Parameters (Continued) Field_name Type Range Req/Opt Default view_rtm flag - Optional - change_domain flag - Optional - Specify values for name and any desired optional fields as described in the following list: 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.
Configuring TN3270 Understanding the Configuration Text File Records Specify the name of the default TN3270 style file for this user. Use 1–8 of any printable, case-sensitive characters. This style file is used if the TN3270 user does not specify a style file when starting the TN3270 emulation program. If no file name is specified, the TN3270 emulation program uses its own default settings.
Configuring TN3270 Understanding the Configuration Text File Records Include this field with no value to give the TN3270 user permission to specify an alternative domain and port for a particular session. For more information about host domains and ports, refer to the TN3270 Users Guide.
Configuring TN3270 Understanding the Configuration Text File Records Table 3-3 Summary of diagnostics Parameters (Continued) Field_name Type Range Req/Opt Default rtm_bdy_1 number 5–1000 Optional 5 rtm_bdy_2 number 5–1000 Optional 10 rtm_bdy_3 number 5–1000 Optional 20 rtm_bdy_4 number 5–1000 Optional 50 Specify values for any desired optional fields as described in the following list: error_file Use 5–49 characters to indicate the full path and file name of the error log file, wh
Configuring TN3270 Understanding the Configuration Text File Records Include this field with no value to enable exception messages, or do not include this field to disable exception messages. Exception messages record abnormal events that do not necessarily indicate problems. Problem messages are always enabled. For more information about the three types of log messages, see Chapter 4, “Using TN3270 Log Messages.
1 Chapter 1 Using TN3270 Log Messages 41
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 events to the file sna.aud in the /var/opt/tn3270 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.
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 1-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 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. Resource Resource shortage (for example, insufficient memory on the HP-UX computer).
Using TN3270 Log Messages Format of Log Messages A normal event, reported for information only. System name The name of the computer where the condition that 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.
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.
1 Chapter 1 Using TN3270 Tracing Facilities 51
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 Figure 1-1 54 Relationship between TN3270 Components and Tracing Boundaries Chapter 1
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 Traces the messages sent over TCP/IP to the host in 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.
Using TN3270 Tracing Facilities Trace File Formats Table 1-1 Abbreviations Used in Trace Message Headers (Continued) 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 Appendix A Required and Recommended Functions in the terminfo Database 63
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 Alternate character mode: acsc, enacs, smacs, rmacs Used to draw the menus and dialog boxes. If the 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 use the Up and Down arrow keys or accelerator keys to select buttons from radio groups. PageUp: kpp or ka3 and PageDown: knp or kc3 Used to move quickly within a listbox. The Up and Down arrow keys can be used instead, but are slower. Either of the termcap names can be used. Home: ka1 or khome and End: kc1 Used to move quickly to the first or last entry in a listbox.
Required and Recommended Functions in the terminfo Database Defining Functions in terminfo box. (On some terminal types, such as the Wyse 60, Backspace is interpreted as a Left arrow key.) Color support: colors, pairs, setb, setf The TN3270 menu interface can be run without color support, but it will use color if your terminal supports it. This applies particularly when communicating with host TN3270 programs that support color.
Required and Recommended Functions in the terminfo Database Defining Functions in terminfo in both the Required and Recommended lists. However, you can remap a 3270 key to a different keystroke if your HP-UX terminal does not have the same key. Refer to the HP-UX TN3270 Users Guide for more information. Include in the terminfo database any additional keys on the terminal's keyboard if you want to use them in the TN3270 program to represent 3270 keys.
Required and Recommended Functions in the terminfo Database Defining Functions in terminfo 70 Appendix A
A 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.
A Appendix A Migrating from Earlier Versions of TN3270 73
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 Before using an existing Release 4 configuration file with Release 6, you need to modify it to take account of this change. TN3270 provides a 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 and to add the new audit and exception fields, if appropriate. The settings of audit and exception are based on the value of audit_level, as follows: Table A-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, 13 administration tasks, 12 administrator responsibilities, 17 API (application program interface), 14 audit log file, 15, 46 automating TN3270 emulation start-up, 14 B binary configuration file, creating, 25 C character-based TN 3270 emulation program, 13 configuration, 12, 14, 17, 24, 25 configuration file converting to Release 5 format, 78 migration utility, 78 overview, 14 configuration file records, 28 configuration file, overview, 25 configuration information, 26 co
Index R related publications, 8 response times, host, 13 running configuration file changing, 27 description, 26 S sample configuration text file, 25 semaphores, 74 shared memory, 74 SNACTL environment variable, 59 SNAMSG environment variable, 57 SNATRC environment variable, 57, 58 style file, 14 swinstall command, 21 swverify command, 21 T TCP/IP, 13 TCP/IP host, 32 TN3270 loading, 21 TN3270 emulation program configuration options, 13 different versions, 13 features, 13 tracing, 57 TN3270 message tracing,
