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. 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:

• Password expiration checking
• Cyclic redundancy checking
• Exchange steps
• Data compression
• SHOW_DESKTOP_USERS utility program
• Nonblocking calls
• Forced nonblocking calls
• Client task cancel calls
• Non-WIN32 client platforms
• Non-TCP/IP transports
• The Kanji code conversion library (JCNVWIN)

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:

• Error logging to a platform event log facility
  By default, TPware software writes error information to a central event log facility specific to the platform (see Section A.2).
• Error logging to a file
  If you define stdl_log_file as a system environment variable, TPware software writes error information to the TPware error log file defined by the environment variable (see Section A.3).

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:

• If the client process runs on a platform that can log errors to a central event log facility, TPware software writes the error record to the event log facility.
  On Windows NT platforms, TPware software uses the Windows NT Application Event Log as the event log facility.
• If the client process runs on a platform that has no event log facility, TPware software writes the error record to a TPware error log file.
  On Windows 95/98 platforms, TPware software uses the file with a name in the following format:

  drive:\TPware\logs\default_error.log

  
  The specification drive is the letter of the disk drive and TPware is the default directory on that drive in which the TPware software is installed. The \logs subdirectory is created when you install the software.
  View the records in this file with the stdlog utility (see Section A.4).

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 full path of the error log file
• The date and time of the day on which the stdlog utility created the report
• Selection criteria used
  • On the Before: line, the date and time of day on a -b flag.
  • On the Since: line, the date and time of day on a -s flag.

The record for each error shows:

• On the USER: line, the name of the user running the client program when the error occurred.
• On the TIME: line, the day, date, time of day, and year when the record was posted.
• On the PID: line, the process identification of the program posting the error record.
• On the TYPE line, the Fault error type. Only faults are logged.
• On the SEVERITY: line, the text error for all errors, primary and secondary.
• On the line under the SEVERITY: line, the text describing the error, with any symbolic error code.

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