|
|
|
|
SNAP-IX is a complex software product. You may therefore occasionally encounter problems when you are running SNAP-IX, either with SNAP-IX itself, or with other system components.
This manual describes some of the more common types of problems that you might encounter, provides guidance for investigating them, and describes how to gather further diagnostic information. The manual is structured in the following way:
This chapter introduces the types of diagnostic information that are available to you, and describes how to use each type.
Resolving Common Problems, describes the basic checks that you should always perform, and provides step-by-step guidance on how to investigate a specific problem further. Read this chapter if you have encountered a problem and need to know how to investigate it.
Using Logging and Tracing, describes how to use the SNAP-IX tracing and logging facilities to gather further diagnostics information. Read this chapter if you need guidance on how to gather a particular type of trace or how to gather specific kinds of logs.
This section describes the range of diagnostic information that is available to you to resolve SNAP-IX system problems, and how to use each type.
SNAP-IX diagnostic information can be categorized in the following way:
Notification
information is always available
to you; it cannot be turned on or off. This type of information indicates
that an error has occurred and should be investigated. It includes error messages,
error logs and alerts.
Diagnostic
information can be controlled, and
should be used to gather further information on specific problems. This type
of information includes exception logs, audit logs, and tracing data.
SNAP-IX also provides online help information that can be useful in preventing or resolving problems.
When SNAP-IX is running, you will generally use all these types of information, at different times, to resolve any problems that you may encounter.
For example, when an APPC application program is running, different SNAP-IX events such as starting or stopping a session may occur. Each event is made up of a number of smaller events. So a session event can include internal events such as connecting to an LU, starting the session, security checking, and link initialization. You can configure SNAP-IX to log each of these smaller normal events to a file called an audit log file, if you wish to record them all.
When a program fails, SNAP-IX provides several diagnostic resources, each of which gives you different types and levels of information about the events that have occurred. This information can be displayed on your screen or logged to a file called an error log file. Further event information for a particular area of SNAP-IX can also be generated and collected in a file when you activate traces for a specific feature of SNAP-IX.
This section describes all these types of information and how you might use them.
These messages are displayed by the system whenever a serious system problem is encountered.
Log messages contain information about program events. There are three different types of events about which information is logged: problem, exception, and audit. Each is captured to a log file that you can access to obtain the information needed to resolve a problem.
SNAP-IX also maintains a separate log file that records information about your usage of SNA resources on the local node. See Usage Logging for more information.
Tracing is a means of tracking the events occurring across a particular boundary of SNAP-IX while SNAP-IX is running. SNAP-IX offers a wide variety of tracing options that can be activated for diagnostic purposes.
Standard SNA alerts are generated and transmitted to the host. They can be viewed on the host with NetView.
The program error messages and log messages usually specify the nature of the problem, its cause, and the recommended action, which is often enough to help you resolve a problem. The amount of information available to you depends on the nature of the problem and on how you set up logging. For example:
Program error messages are automatically displayed; they cannot be disabled.
Event logs indicating problems are also automatically generated and cannot be disabled, though logging of exception event logs can be disabled. Audit event logs are not logged unless you choose to log them.
Tracing should only be activated when you suspect a problem. You can then trace activity in the area that you are experiencing a problem with. Additionally, you can control the amount and format of the tracing information collected for you.
In addition to diagnostic information, SNAP-IX also has extensive online help information for the following:
Motif administration program
Web administration program
Command-line administration program
3270 emulation program
5250 emulation program
RJE
SNAP-IX also includes
manual (man
) pages. You will find the online help information
useful both in preventing and resolving problems.
The rest of this chapter describes each kind of diagnostic information in more detail, and explains where to find SNAP-IX online help information.
For a list of the more common problems that are encountered by users and the steps to take to resolve them, see Resolving Common Problems. For information about how to use logging and tracing, see Using Logging and Tracing.
The most obvious indication of a problem is the display of a program error message. SNAP-IX generates program error messages automatically to report serious problems. Program error messages are reported to the screen or console. Each message describes the problem that the program encountered. You cannot disable these messages.
For example, if an administrator using the command-line administration program tried to start a node when there was no node configuration file on the server, a message would be displayed similar to the following:
$: snaadmin init_node init_node command failed: primary_rc = STATE_CHECK, secondary_rc = NODE_NOT_CONFIGURED
If an administrator using the Motif administration program tried to modify parameters in the Node Parameters window while the node was running, a pop-up message would be displayed similar to the following:
You cannot modify the node's parameters while it is not inactive.
Often a program error message is accompanied by log messages that provide additional information. For information about the error log file, see Types of Log Information.
When a program is executing, different events such as starting or ending a session occur. SNAP-IX records log messages for these and other events in log files to provide you with specific information about the internal activities of SNAP-IX. Other internal activities of SNAP-IX that are logged include port initialization, security checks, and network link station failures.
SNAP-IX logs messages for normal events (such as starting the session) and for abnormal events (such as unexpected session termination and resource shortage). For each event, the messages describe what happened, when, and where. You can disable some types of logging (see Determining Which Messages Are Logged) and control the amount of detail recorded in the logs (see Choosing the Format of Logs). One log file can contain more than one type of message.
SNAP-IX categorizes events by severity and groups them into one of three types.
An abnormal system event that degrades system performance in a way that is easily perceived by a user (for example, abnormal termination of a session).
SNAP-IX always logs these events. You cannot disable logging of these events.
Exception events fall into two categories:
Abnormal system events that degrade system performance but are not immediately perceived by a user (for example, a resource shortage).
Events that do not degrade system performance but may indicate the cause of later exceptions or problems. An example is receiving an unexpected message from the remote system.
By default, SNAP-IX logs exception events.
To control logging exception events using the Motif administration program, see Controlling Logging Using the Motif Administration Program.
You can also control logging of these events by using the snaadmin set_global_log_type command to establish global default settings for all servers, or the snaadmin set_log_type command to override the defaults for a particular server.
For more information about controlling logging using administration commands, refer to the SNAP-IX Administration Command Reference.
A normal system event (for example, starting a session). By default, SNAP-IX does not log these events.
To control logging audit events using the Motif administration program, see Controlling Logging Using the Motif Administration Program.
You can also control logging of these events by using the snaadmin set_global_log_type command or the snaadmin set_log_type command.
Some problem and exception messages, which may require corrective action, are displayed on the Solaris system console as well as being written to the log file. You can suppress these console messages by using the option when starting the SNAP-IX software (refer to the SNAP-IX Administration Guide for more information). Messages are then written only to the log file.
In general, you should review the error log file first to help resolve any problem you encounter when using SNAP-IX.
The log files contain a Message action field, which describes any recommended action as a result of the message. In some cases, no action is required. For example, an exception message may not indicate an error but may provide background information that helps to identify the cause of a later problem message.
Common recommended actions include the following:
Check the local SNAP-IX configuration and add, modify, or activate resources. For more information, refer to the SNAP-IX Administration Command Reference.
Check the Solaris computer's resources (such as memory, hard disk space, or adapter cards). For more information, refer to your Solaris operating system documentation.
Contact support personnel for the system with which SNAP-IX is communicating to resolve configuration mismatches. For more information, see Types of Support Personnel.
Contact the developer of an application that uses the SNAP-IX APIs if the application is making API calls that are not valid.
Report the error condition to your SNAP-IX supplier if the Cause type field indicates an internal error in the SNAP-IX software.
Checking for logging information on the local system and on the remote server.
If the logs contain less information than you expect, you may have succinct logging enabled (succinct and verbose are the two modes available). To recover the missing information, use the snahelp utility (see Using snahelp for Succinct Logging Messages). For information about enabling verbose logging, see Choosing the Format of Logs.
SNAP-IX provides trace facilities to enable you to capture and obtain information about the internal activities of SNAP-IX while it is running. This information can be helpful for diagnosing specific problems. For example, if you suspect a DLC (data link control) problem, you can activate line tracing for the specific DLC.
You can control the type and amount of trace data to be collected by using the administration programs. Depending upon the type of tracing you perform, your output is generated in either ASCII or binary format. Use a text editor to view ASCII files. For binary data, use the snatrcfmt utility to convert binary files to text files. For more information, see Formatting Internal Binary Trace Output into Text Files.
The following section briefly describes the types of tracing and provides examples of when to use tracing. For detailed information about tracing, see Tracing.
SNAP-IX provides the following types of tracing:
Use
line tracing to trace messages between the node and the remote system. You
can control the amount of tracing by specifying the resource type (DLC, port,
link station, or session). Line Tracing is also sometimes known as
DLC Tracing
.
Line tracing output is typically used by an SNA administrator to solve end-user problems, including the inability to bring up a session or session failure. The format is a standard SNA trace. For more information about line tracing, see Line Tracing.
The output produced by line tracing is binary. You can select specific entries from a line trace file by using the snafilter utility, and you can format binary trace output into text files by using the snatrcfmt utility. For more information about these utilities, see Using snafilter and snatrcfmt.
Use API tracing to locate communication problems that involve any of the following SNAP-IX APIs: Advanced Program-to-Program Communication (APPC), Common Programming Interface for Communications (CPI-C), Conventional LU Application Programming Interface (LUA), Logical Unit Type 0 Application Programming Interface (LU0), High Level Language Application Program Interface (HLLAPI), Node Operator Facility (NOF), Management Services (MS), and Common Service Verbs (CSVs). API tracing traces all the parameters supplied to the API library or driver by an application and all the parameters returned by the API library.
API trace data is written to text files. For more information, see API Tracing.
Use client-server tracing to trace messages flowing between the SNAP-IX server and a client, as well as between SNAP-IX servers in the same domain. Client-server tracing can be used, for example, to find out why a client is unable to connect to the server.
Client-server tracing is written to text files. For more information, see Client-Server Tracing.
Use TN server tracing to record messages flowing between the SNAP-IX TN server and its TN3270 clients. Typically, the System Administrator initiates this trace to resolve a TN3270-related problem.
The TN server trace data is written to text files. For more information, see TN Server Tracing.
Use 3270 emulation program tracing and RJE workstation tracing to show the data being transferred between the program and the host, and messages that are internal to SNAP-IX. You control this tracing by setting environment variables on the command line.
Trace data from the 3270 emulation program and RJE workstation program is written to text files. For more information, see 3270 Emulation Program Tracing and RJE Workstation Tracing.
Use internal tracing to trace messages that flow between internal components of the SNAP-IX node.
A large amount of trace output will usually be generated quickly. Once you have captured the information you need to solve your problem, stop tracing to prevent files from growing too large or from being overwritten. For more information about internal tracing, see Internal Tracing.
The output produced by internal tracing (which is typically used by support personnel) is binary. You can select specific entries from an internal trace file by using the snafilter utility, and you can format binary trace output into text files by using the snatrcfmt utility. For more information about these utilities, see Using snafilter and snatrcfmt.
If you encounter a problem, use the SNAP-IX trace facilities to obtain more information about the messages that are flowing across specific interfaces. For example:
If you have an application that uses the SNAP-IX APIs and the API return codes indicate a problem, use API tracing.
If you are unable to connect to a remote system successfully, or if SNAP-IX produces exception and problem logs when you try to do so, use line tracing or client-server tracing.
Do not run SNAP-IX tracing unless you have encountered a problem with your SNAP-IX system. The system runs more slowly when tracing is enabled.
For more information about using tracing, see Tracing.
Alerts are SNA messages that are generated automatically. They are sent to and processed by different programs on the external network and are used to identify problems or impending problems. There can be alerts from connectivity components, 3270 user alerts, or alerts provided by an application program using the Management Services API.
Alerts are sent to the first active host link encountered or to the link station you specified using the snaadmin define_default_pu command. If the link station is inactive, alerts are stored on disk and transmitted when the link station is reactivated.
NetView, which typically runs on the host, is the most commonly used program for viewing and processing alerts.
In addition to log and trace information, which describe SNAP-IX system activities that occur during a problem, SNAP-IX also includes standard online help information. You may find this information useful if you encounter problems while using a particular program or if you want more information about a certain topic or about using a command.
SNAP-IX provides the following online help information:
Motif administration program online help
Web administration program online help
Command-line administration program help
3270 emulation program online help
5250 emulation program online help
RJE console and customizer online help
Man pages
Usage strings
The SNAP-IX Motif administration program and Web administration program, which are used to configure and manage SNAP-IX, provide online help. You can access this online help in two ways; each provides a different form of help information:
From the main window you can access a broad range of help topics.
To display the online help menu, click Help in the top right-hand corner of the administration window.
Select Contents from the Help menu. The main online help dialog provides a list of topics.
From individual dialogs you can access help on that particular dialog.
To obtain more information about the dialog fields click on the Help button.
You can access administration command-line help for a command through the command-line administration program. The help provides information about the full syntax of snaadmin commands, including their parameters and default values. For example, type the following command to obtain a description of the help that is available:
snaadmin -h
SNAP-IX 3270 emulation program online help provides help for the following program elements:
This help describes the overall function of the program.
This help describes the overall function of the menu.
This help provides detailed information about the functions provided by the menu options.
This help explains the overall purpose of the dialog box and specifies the valid entries for each field.
SNAP-IX 5250 emulation program includes an online help system. You can access this online help in two ways; each provides a different form of help information:
From the main window you can access a broad range of help topics.
To display the 5250 emulation program online help click Help in the top right-hand corner of the 5250 emulation program window.
Select Contents from the Help menu. A main online help dialog provides a list of topics.
From individual dialogs you can access help on that particular dialog.
To obtain more information about the dialog fields click on the Help button.
The SNAP-IX RJE console provides help screens that do the following:
Describe how to navigate around the RJE console screen
Explain how to use the online help
When running the SNAP-IX RJE console, press the F1 key to access the main help screen.
The SNAP-IX RJE customizer provides help screens that do the following:
Describe how to navigate around the RJE customizer
Provide context-sensitive help
When running the SNAP-IX RJE customizer, press the F1 key to access the online help.
Man pages contain information about command usage. You should access them if you need a quick overview of a topic or information about how to use a particular command.
To get a man page from the command line, type man
pagename, where pagename
represents the name of the page you want to see (generally the name of a SNAP-IX
command). For example, to see the sna
man page, type
man sna.
In addition to displaying the requested information, man pages provide a list of related commands.
You can access usage strings for SNAP-IX programs by invoking the programs using the -h parameter to obtain a brief syntax statement. For example, type the following:
sna -h
|
|
|
 |
|