Quick Start


Diagnosing Initial Connection Failures

All TSM clients that use APPC issue standard CPI-C calls to communicate. A standard set of return codes apply to all clients and can be useful in diagnosing initial connection failures. The CPI-C return codes are prefixed by CM. For example, CM_PARAMETER_ERROR.

Determining CPI-C Return Codes

TSM does not write the base CPI-C return code to the TSM error log. To determine the CPI-C return code, you must run an an TSM trace. To run a trace, add the following statements to the client options file (dsm.opt):

+--------------------------------------------------------------------------------+
|traceflags comm                                                                 |
|tracefile  trace.out                                                            |
+--------------------------------------------------------------------------------+

An example of the trace file is shown in Figure 39.

Figure 39. Sample Trace File


Tracing is active to file 'trace.out',
--------------------------------------------------------------
--
06/20/1998 10:59:32  - Trace begun.
commcpic.c(3895): ConvInit set protocol stack to OS/2SAA rc: 0
commcpic.c(3929): ConvInit: Error initializing conversation to sym_dest_name SPIKE
commcpic.c(3231): CpicOpen: Error initializing conversation, rc: 24
commcpic.c(4172): CastCpicRc: Entry rc: CM_PROGRAM_PARAMETER_CHECK (24),
Note:Tivoli Storage Manager clients at V1 R2 L0.3 or later write the CPI-C return information directly to the dsmerror.log file, eliminating the need to run the COMM trace.

Analyzing CPI-C Return Codes

Here is a list of common CPI-C errors encountered when trying to configure APPC communications for TSM. A complete list of the CPI-C return codes is documented in Common Programming Interface Communications Specifications (SC31-6180)

CM_ALLOCATE_FAILURE_NO_RETRY

The conversation cannot be allocated on a session because of a condition that is not temporary. Likely causes are:

It is usually useful to get the sense information for these failures (see Obtaining Sense Information).

CM_ALLOCATE_FAILURE_RETRY

The conversation cannot be allocated on a session because of a condition that might be temporary. Likely causes are:

It is usually useful to get the sense information for these failures (see Obtaining Sense Information).

CM_TP_NOT_AVAILALBE_NO_RETRY

The remote system rejected the allocation request because the local program specified a remote program that the remote system recognizes but cannot start. Likely causes are:

CM_PARAMETER_ERROR

The local program issued a call specifying a parameter containing an invalid argument. Likely causes are:

CM_PROGRAM_PARAMETER_CHECK

The local program issued a call in which a programming error has been found in one or more parameters. Ensure that the following are correct:

Gathering Initial Documentation for Level-2 Support

If you need to contact the support center for help, collect the following information:


Table 5. Obtaining Client Configuration Definitions

Product Where to Look...
OS/2 Communications Manager 2 (CM/2) CM/2 writes configuration definitions to a file with the extension of .ndf. This file can be found in the -CMLIB subdirectory.
OS/2 Extended Services Extended Services writes configuration definitions to a file with the extension of .ndf. This file can be found in the -CMLIB-APPN subdirectory.
SNA/6000 SNA/6000 allows the user to export SMIT SNA/6000 configuration definitions to a .jfs file. To export the definitions:
  • Type SMIT SNA from a AIX command line
  • Select Configure SNA Profiles
  • Select Advanced Configuration
  • Select Export Configuration Profiles
  • Enter a filename for the export output
NetWare SAA NetWare SAA does not provide a mechanism to export SIUTIL definitions to a file. Screen captures from SIUTIL must be obtained. From the SIUTIL exec, view the side information file and capture the three main SIUTIL screens:
  • Local LU Configuration Data
  • Partner LU Configuration Data
  • Node Configuration Data

Also obtain the PU 2.1 service profile being used by the TSM side information record.

Obtaining Sense Information

Often it is useful to obtain the sense information to pinpoint an error. In some specific cases, such as CM_ALLOCATE_FAILURE_NO_RETRY, it is necessary. Each platform offers a unique trace facility to capture this information. The following sections discuss each platform in detail.

OS/2 CM/2

There are two ways to obtain sense information in an OS/2 environment.

Running CM/2 Trace Services

To run CM/2 Problem Determination Aids - Trace Services, double click on the Problem Determination Aids - Trace icon in the CM/2 folder. The Problem Determination Aids - Trace Services window appears.

To start the trace, follow these steps:

  1. Select APPC under the APIs column.

  2. Select the DLC which your computer is using. IBMTRNET is used in this example.

  3. Select all Events that begin with APPC_.

  4. Press the Start button.

To view the trace, follow these steps:

  1. Press the Stop all button to stop the trace.

  2. Press the Save button.

  3. Select a filename and press the OK button.

  4. Select Format trace file... from the File pull-down menu.

  5. Check the Output file format - Detail box. Let all other options assume their default values.

Issuing CMTRACE Commands

To use CMTRACE commands to create a trace file, do the following:

  1. From an OS/2 command prompt, run the APPNT.CMD command file shown in Figure 40. This starts CMTRACE.

    Figure 40. APPNT.CMD Command File


    @ECHO OFF
    REM ** Start traces after resetting the trace buffer
    REM ** Trace APPC and services verbs, Token ring Data and
    REM ** APPC events 1 2 3 4 5 and 12
    REM **      event  1 = internal DLC interface
    REM **      event  2 = APPC verbs
    REM **      event  3 = internal APPC flows
    REM **      event  4 = APPC send and receive
    REM **      event  5 = XID flows
    REM **      event 12 = Utility verbs such as error log entries
    REM ** storage 3 uses up to three 64K segments for traces
    REM ** For other options in tracing enter "CMTRACE ?"
    ECHO ON
    CMTRACE START -reset -api appc services -data ibmtrnet -event 1 2 3 4 5 12
    -storage 3
    

  2. Run the TSM command or operation you want to trace.

  3. From an OS/2 command prompt, run the APPNF.CMD command file shown in Figure 41. This stops CMTRACE and formats the trace file.

    Figure 41. APPNF.CMD Command File


    @ECHO OFF
    REM ** Stop traces (trace data remains in storage)
    REM ** Copy TRACE from storage to disk file in the current directory
    REM ** File name is specified as a parameter and the extension is
    REM **    .TRC for the full trace,
    REM **    .DET for the detailed trace and
    REM **    .SUM for the trace summary
    REM ** For other options in trace formatting enter FMTTRACE ?
    REM ** If you want tracing to continue with the same type, then remove
    REM ** the CMTRACE STOP line.
    ECHO ON
    CMTRACE STOP
    CMTRACE copy %1.trc
    FMTTRACE -DS %1
    

Reading the Trace File

If you used Trace Services, a detailed trace file was created with the same prefix that was chosen when the file was saved, but with an extension of .det. If you used CMTRACE at the command line, the trace file that you specified was created.

In the trace file, look for the CM_ALLOCATE_FAILURE_NO_RETRY message. Paging up from this error code reveals the sense data. For example, Sense data = 0xFFFE0113.

NetWare for SAA

The PBTRACE program is NetWare's equivalent to the CM/2 trace facility. It can be used to determine the Primary and Secondary APPC return codes for NetWare for SAA clients.

Running PBTRACE

To run PBTRACE, follow these steps:

  1. Make sure COMMEXEC is loaded by issuing the LOAD COMMEXEC command from the NetWare console.
    Note:All of the commands shown in this section should be issued from the NetWare console.

  2. Issue the LOAD PB_NWSAA command.

  3. Issue the CSLOAD APPCPRO to load the 2.1 service profile.

  4. Issue the LOAD PBTRACE command.

    Answer yes ("Y") to the two prompts that follow.

  5. Issue the LOAD CPIC_SAA SYS:\SYSTEM\NWSAA\CPIC\MVSTIVSM.CPI command to load the side information file.

  6. Issue the LOAD SYS:\TIVSM\DSMC command.

Note:To stop the trace, reissue the LOAD PBTRACE command, but answer no ("N") to the two prompts that follow.

Reading the Trace File

After completing the previous steps, the trace information is written to a file called SYS:\SYSTEM\OUTPUT.PC.

The service profile log found in the SYS:SYSTEM directory should also be obtained along with the trace. For some errors the SUBTYPE field will contain the sense code from the error.

Contact Novell or IBM support to help read the trace information.

SNA Server/6000

Sense information can be found in the SNA Server/6000 failure logs. For more information about SNA Server/6000 trace facilities, see AIX SNA Server/6000: Diagnosis Guide and Messages

Obtaining Failure Log Information

To obtain failure log information, follow these steps:

  1. Direct the SNA Server/6000 failure log to a file by issuing the following command:
    +--------------------------------------------------------------------------------+
    |sna -setlogs -f /var/sna/tivsm                                                  |
    +--------------------------------------------------------------------------------+

    This directs failure messages to /var/sna/tivsm.1.

  2. Recreate the failure.

  3. Close the current set of logs with the command:
    +--------------------------------------------------------------------------------+
    |sna -setlogs -t                                                                 |
    +--------------------------------------------------------------------------------+

    This closes the file /var/sna/tivsm.1 and directs failure messages to /var/sna/tivsm.2

  4. Format the failure log by issuing the following command:
    +--------------------------------------------------------------------------------+
    |trcrpt -d 27B /var/sna/tivsm.1 > /var/sna/tivsm.out                             |
    +--------------------------------------------------------------------------------+

    This formats the data and writes it to a file called /var/sna/tivsm.out.

Note:To issue commands you must be running as root or as part of group system.

Reading the Formatted Failure Log

Use "vi" or any other system editor to view the log information. Look for the string Sense Code:.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]