DIGITAL TP Desktop Connector
Getting Started


Previous Contents Index

10.3.1 Specifying an ACMS Gateway Adapter Error Log File

To diagnose problems with communications between the ACMS gateway adapter and the TP Desktop Connector Gateway for ACMS, specify a file on the client system in which the runtime system writes exception information. In the process in which the client runs, define the following environment variable with the full path and name of a file that holds the exception information:


STDL_ACMSDA_LOG 

If the environment variable is defined when the client starts, the runtime system creates the file. If a file of the same name exists, the software appends information to it. Examine the file with any editor that can read ASCII text.

These exceptions are described in the file acmsdi_client_messages.txt, located in a directory with a name in the following format:

install-directory\stdl\include

For example, if you installed the product in the C:\tpware directory, the client message file is located at:


C:\tpware\stdl\include\acmsdi_client_messages.txt 

10.3.2 Specifying a TCP/IP Port Number for Calls to ACMS Tasks

If the OpenVMS node running the gateway process defines a TCP/IP port number different from the default, the client process needs to know that port number.

To specify the gateway node's TCP/IP port number in the client process, define the following environment variable with the node-name of the node running the gateway process:

STDL_ACMSDA_PORT_node-name

For the value of the environment variable, supply the integer number of the port used on the gateway node.

10.3.3 Managing the TP Desktop Connector Gateway for ACMS

The TP Desktop Connector product provides connectivity to ACMS applications through the TP Desktop Connector Gateway for ACMS. The TP Desktop Connector for ACMS Installation Guide describes how to install the gateway and associated samples. The TP Desktop Connector for ACMS Gateway Management Guide contains additional information on gateway configuration, tuning, and troubleshooting.

However, the TP Desktop Connector for ACMS Gateway Management Guide contains some information specific to the client services interface that does not pertain to the adapter interface. The following features are not supported by the adapter interface:


Appendix A
TPware Error Logging

TPware software supports recording of runtime errors that cannot be returned to the client process. The software attempts to log these errors and any additional information required to help diagnose the problem indicated by the errors.

A.1 Error Logging Overview

If the TPware software encounters an error at runtime, it attempts to return the error to the client program. If the error cannot be returned to the client, or if additional information should be logged to help diagnose a primary error, TPware attempts to log the primary error and any additional information. The software uses one of the following types of error logging:

The stdlog utility is used to view records in a TPware error log file (see Section A.4).

You can use the STDL_SOURCE_TRACE environment variable to have information about the source of the error included in the log. If you set the environment variable to the value TRUE, the runtime system includes in the log the number of the source line and the name of the file containing the application source related to the error.

A.2 Use of the Platform Event Log Facility

TPware software writes error information to a platform event log facility if you do not log errors to a TPware error log file. The results depend on the availability of an event log facility:

A.3 Enabling and Disabling Error Logging to a File

Enable TPware error logging to a file by defining a system environment variable named stdl_log_file and supplying as a value the specification of the file to which the error information is to be written. If the system environment variable stdl_log_file is defined, error information is logged to the file.

A.3.1 Enabling Error Logging on Windows NT

On a Windows NT system, define a system environment variable as follows:

  1. From the desktop, double click My Computer.
  2. In the My Computer window, double click Control Panel.
  3. In the Control Panel window, double click the System icon.
  4. In the System Properties window, click the Environment tab.
  5. In the Environment window under the System Variables list, do the following:
    1. Click on an existing system environment variable.
    2. Click in the Variable text box and type stdl_log_file.
    3. Click in the Value text box and enter the full path and name for the error log file for that system. The value entered for stdl_log_file must be a valid path and file name. For example:


      d:\tpwaresamples\myerror.log 
      

    4. Click the Set button.
    5. Click the OK button.
  6. Reboot the system for the change to take effect.

TPware errors are subsequently logged to the file specified by the stdl_log_file environment variable. If the file does not exist, the software creates it. If the file exists, error logging information is appended to it.

A.3.2 Disabling Error Logging to a File

To disable error logging to the TPware error log file, delete the system environment variable named stdl_log_file. If the system environment variable stdl_log_file is not defined, the results depend on the operating system (see Section A.1).

A.4 Viewing Records in the TPware Error Log File

If error logging to a file is enabled on the client system (see Section A.3), use the TPware stdlog utility to view records in the TPware error log file.

A.4.1 Error Log Utility Syntax

In a Command Prompt window, run the stdlog utility.

Synopsis

Use the following syntax:

stdlog [ option-flag . . .]

You can use the stdlog utility in interactive mode or single command mode.

If you enter the stdlog command alone or without the -l flag, the utility enters interactive mode. If the environment variable stdl_log_file is defined, the software opens and displays the related file. If the environment variable is not defined, the utility runs and displays the following prompt:


Enter the log file name:  

At the file name prompt, enter the name of the file in the current directory and press Enter. If the file is not in the current directory, enter the full path. The utility displays the specified file and redisplays the prompt. At the prompt, press Ctrl + C to stop the utility and return control to the Command Prompt window.

If you specify the stdlog command and option flags, you can issue the entire command in one line. The utility executes the single command and returns control to the Command Prompt window.

Option Flag Default Values

All default options are applied to extracting information from the log file. The names and default values of the option flags are shown in Table A-1.

Table A-1 stdlog Option Flags and Default Values
Option Flag Default
-b [ date-time] Displays records with all times before the current date and time of day.
-l log-file-name Displays records in the file specified by the definition of the stdl_log_file environment variable. Otherwise, prompts for the name of the log file to access.
-s [ date-time] Displays records with all times since the earliest date and time of day.

Option Flags

-b [ yyyy-mm-dd [ -hh:mm [ :ss [.ttt ]]]]

Displays error records that have been logged before the specified absolute date and time of day, expressed in Coordinated Universal Time (UTC) format where:
  yyyy Year from 0000 to 9999
  mm Month of the year from 01 to 12
  dd Day of the month from 01 to 31
  hh Hour of the day from 00 to 23
  mm Minutes from 00 to 59
  ss Seconds from 00 to 59
  ttt Thousandths of seconds from 000 to 999

If you omit the flag, the software displays all records before the current date and time of day.

If you specify -b, but omit the date and time of day, the software displays the records before 00:00:00 on the current date.

If you specify -b and a date, but omit the time, the software displays the records before 00:00:00 on the specified date.

-l log-file-name

Displays the specified log file log-file-name from the current working directory. If the file is not in the current working directory, specify the full path of the file to display.

If you omit the flag and the stdl_log_file environment variable is not defined, the utility prompts for a file name.

-s [ yyyy-mm-dd [-hh:mm [:ss [.ttt ]]]]

Displays error records that have been logged since the specified absolute date and time of day, expressed in UTC format where:
  yyyy Year from 0000 to 9999
  mm Month of the year from 01 to 12
  dd Day of the month from 01 to 31
  hh Hour of the day from 00 to 23
  mm Minutes from 00 to 59
  ss Seconds from 00 to 59
  ttt Thousandths of seconds from 000 to 999

If you omit the flag, the software displays all error records since the earliest date and time of day.

If you specify -s, but omit the date and time of day, the software displays error records since 00:00:00 on the current date.

If you specify -s and the date, but omit the time of day, the software displays error records since 00:00:00 on the specified date.

A.4.2 Sample Commands and Output

Example A-1 shows the commands to invoke the stdlog utility to view all the records in a specified log file.

Example A-1 Invoking the stdlog Utility

C:\> stdlog -l c:\tpwarelogdir\myerror.log  
   .
   .
   .
C:\> 

The stdlog command displays the contents of the error log file named myerror.log in the specified path.

Example A-2 shows a command to select error records from a file located in the current working directory using a time interval specified by -s and -b flags.

Example A-2 Specifying a Time Interval with the stdlog Utility

C:\tpwarelogdir> stdlog -l my.log -s 1998-09-09 -b 1998-09-10  
   .
   .
   .
C:\tpwarelogdir> 

The file my.log in the current directory is opened. The command displays error records written during the 24-hour period since 00:00:00 on September 9, 1998 and before 00:00:00 on September 10, 1998.

A sample of the stdlog output is shown in Example A-3.

Example A-3 stdlog Utility Sample Output

************************************************************************ 
STDL Log Report 
d:\tpwaresamples\myerror.log 
1998-09-21-09:43:09.810 
************************************************************************ 
SELECTION CRITERIA: 
Before: 
Since: 
Format: SYSTEM 
Type: 
************************************************************************ 
************************************************************************ 
USER: SYSTEM 
TIME: 1998-09-20-15:43:09.543 
POSTED BY: Client Process 
PID: 483 
TYPE: Fault 
SEVERITY: error 
%STDL-E-SRTLCALLGRPBAD, Group init error 
************************************************************************ 

The display consists of heading lines and one record for each TPware error enclosed by lines of asterisk (*) characters. The heading lines contain:

The record for each error shows:

The format for the date and time of day is:

yyyy-mm-dd-hh:mm:ss.ttt

  yyyy Year from 0000 to 9999
  mm Month of the year from 01 to 12
  dd Day of the month from 01 to 31
  hh Hour of the day from 00 to 23
  mm Minutes from 00 to 59
  ss Seconds from 00 to 59
  ttt Thousandths of seconds from 000 to 999


Previous Next Contents Index