Technical Notes

Enabling and Using Logging in Verastream Integration Broker
Technical Note 10234
Last Reviewed 07-Nov-2005
Applies To
Verastream Integration Broker version 9.0 or higher
Summary

Log files are an important tool for troubleshooting problems with Verastream Integration Broker (VIB). You may use VIB logs for your own application development debugging or Attachmate Technical Support may request logs when you initiate a Service Request. This technical note explains how to capture complete logs. This information supplements the product documentation.

The information in this technical note is organized in to the following sections:

A. The MYDBG Environment Variable

Most VIB logging is configured using the MYDBG environment variable. The MYDBG variable consists of two elements, <log-file> and <log-options>. These elements are detailed below.

Syntax: <log-file><log-options>

Log-File

The <log-file> element consists of the log directory and the log file name (which may include directives).

Log Directory

The directory path syntax varies depending on your operating system. Directory substitution environmental variables, such as %SNPRODUCTROOTDIR%, can also be used.

If no path is specified, the current working directory (".") is used. The current directory varies depending on the module and how the module is being run, for example:

How the Module is Run	Current Directory
Command shell prompt, UNIX shell script, or Windows .bat file	The operating system shell's current directory.
Microsoft Windows Shortcut	The "Start in" directory specified in the shortcut's Properties.
Windows sntcpd daemon, running as a service	%WINDIR%\System32. For example, C:\WinNT\System32.
Verastream Component Protocol (VCP) server components started by the sntcpd daemon	The directory specified during registration. In version 9.6 or higher of the VCP Component Directory Explorer, the registered directory is listed as the 'Working directory.' In version 9.5.1 or earlier of the Component Directory, it is listed under 'Start in directory.'
Component Server Switch (CSX) started by the sntcpd daemon	The Verastream bin directory.

Log File Name and Optional Directives

If a file name is specified without directives, a log file name must be provided. Directives are optional; however, if no directives are specified the log file is overwritten each time the application is executed.

Directives are a type of variable substitution unique to MYDBG, they enable MYDBG to create a separate log file, with a unique file name, each time the application is executed.

The following directives are supported:

Directive	Definition
%a	For snpi and nova, the Verastream application name (usually same as base file name) For CSX (version 9.7 and higher), the VCP address including namespace (with slashes replaced with underscores) For sntcpd, this is blank
%d	Creation date in the format YYYYMMDD
%j	Creation date in the format MMDD
%m	Current millisecond (3 digits)
%p	Verastream process ID (up to 5 digits)
%s	Number of seconds since 1/1/1970 (10 digits)
%t	Creation time in the format HHMMSS
%u	Combination of %s and %m
%%	Forces a percent character in the file name

Multiple directives may be used. For readability, multiple directives are commonly separated by a set character, such as an underscore ("_") or a dot (".").

For example, if MYDBG is set to testsystem_%a_%d_%t.log, and the application "addcustomer" is run on March 15, 2004 at 9:03:51 A.M., the log file created will look similar to this: testsystem_addcustomer_20040315_090351.log.

Log-Options

The <log-options> element consists of log groups and control flag options.

Log Groups

The following chart lists groups of information that can be logged. Each group name must be proceeded by a separator character. Multiple groups can be specified.

Note: The separator character varies depending on your host environment. Further details regarding separator characters are provided in the Separator Character section. The separator "!" character is used for samples within this document.

For example, the string below enables logging for csx, distr, and socket.

Group	Definition
all	Logs all groups. When using this option, you can exclude specific groups by listing the group name preceded by the "-" character. For example, to log all groups except snmp use the value <log-file>!all!-snmp. Note: You cannot use the "-" switch to exclude the all group itself.
csx	Verastream Component Server Switch
distr	Network read/write activity
ident	Operating system, program file, version, license
memory	Internal memory use
message	Message tables (localized errors, etc.)
ole	Microsoft OLE and COM
opsys	Operating system (command lines and arguments, file operations, etc.)
param	Parameters (environmental variable values and sources)
report	Report objects
rml	RML database table
service	COMPONENT objects
snmp	Simple Network Management Protocol
socket	TCP/IP network socket activity
sql	SQL database
ssl	Secure Socket Layer encryption with OpenSSL libraries
surprise	Miscellaneous exceptions, warnings, etc.
vcp	VCP server components (if server component application logging is enabled, it is replicated in the client log)
warning	Warnings (not errors or exceptions)
window	Graphical user interface (Windows or X)

Log Control Flags

The following chart lists extra details that can be logged. As with log groups, each control flag must be preceded by a separator character. Multiple groups and control flags can be specified. (See Separator Character for details.)

Flag	Definition
appl	Enables application logging (same as DBG STATUS). Verastream Script Language (VSL) code lines are logged. Not applicable for csx or sntcpd.
date	Available in version 9.6 or higher. Adds the date at the beginning of each log line. This is especially useful for applications that are always running (so multiple days are logged within a single file).
flush	Enables writing of the log buffer to disk after each line. This ensures all activity is captured when processes crash or are killed with DCL command STOP on OpenVMS. Note: This results in a significant performance degradation on OpenVMS. For OpenVMS, this flag is supported in version 9.6 patch 7 or later (and flushing is no longer enabled by default). Replaces functionality provided by VMSFLUSH environment variable in version 9.6 for OpenVMS. For other (non-OpenVMS) platforms, flush is enabled by default. In version 9.7 and higher, you can use "-flush" to disable flushing, but there is no known performance advantage.
incore	Enables internal logging for Process Integrator (PI) and Component Developer (CD) development tools (requires 'appl'). Supported in versions 9.0 patch 1 through 9.2. Use only under the direction of Attachmate Technical Support.
time	Adds a time stamp (in seconds) at the beginning of each log line.
mtime	Adds a time stamp (including milliseconds) at the beginning of each log line.
more	Adds verbose logging of network activity and CSX. Note this may create substantially larger log files.
sn2c	Enables internal logging for PI and CD development tools (requires 'appl'). Supported in version 9.5 or higher. Same as dbgtim entry point (-edbgtim). Use only under the direction of Attachmate Technical Support.
sync	Enables shared access on OpenVMS. Closes the log file after each entry so it can be viewed during engine execution. Note: This option can significantly degrade performance. Supported in version 9.6 patch 7 or higher for OpenVMS.

For example, a typical log option may look like this:

Separator Character

You must use a separator character before each group or control flag option. The separator character varies, depending on where you set MYDBG and which operating system you run.

In the sn.ini File

If you set MYDBG from the sn.ini file, use "!" for the separator character on all platforms. The sn.ini file is described in the sn.ini File section below.

Character	Supported Operating System
! (exclamation mark)	All (Windows, UNIX, OpenVMS, AS/400, OS/390)

In the Command Line or a Script

Because the operating system may already be using the "!" character as a special character, outside of the sni.ini file you may not be able to use "!" for a separator character. (For example, "!" is used to indicate comments in OpenVMS and substitution in UNIX.) Refer to the following table to determine which character to use.

Character	Supported Operating System
, (comma)	OpenVMS
: (colon)	UNIX, OS/390, AS/400
; (semicolon)	Windows

B. Where to Set MYDBG

Like all VIB environmental variables, MYDBG can be set from the command line, the sni.ini file, or the operating system shell.

sn.ini File

MYDBG environmental variables are most commonly set in the sn.ini initialization file. This file is used to store many parameter definitions and defaults, and can be modified with any text editor.

Typically, there is a single sn.ini file stored in the Verastream /bin directory. However, if an additional sn.ini file exists in the current working directory, that file takes precedence over the sn.ini in the /bin directory.

Environmental variables set in the [default] section of the sn.ini file apply to all executables. Variables set in other sections, for specific executables, take precedence over those set in the [default] section.

Within sn.ini, the semicolon character (";") can be used at the beginning of a line for comments.

The executable sections, in sn.ini and their typical use, are as follows:

Section	Definition
[sntcpd]	Verastream network daemon (Directory Server, Activation Server starting server components, runtime registration, replication with other daemons)
[snpi]	.pia files, Process Integrator, Repository Manager, etc.
[nova]	.fle files, VCP Component Directory Explorer, etc.
[csx]	Component Server Switch (version 9.5 and later) – see also section E. MYDBG Logging for CSX Switches
[sndi]	Data Integrator
[snds]	Data Server

Note: Multiple instances of the same section are treated as a single consecutive section.

After making changes to sn.ini, executable(s) affected by the update must be re-started before the changes take effect. For example, after modifying [sntcpd] MYDBG, the sntcpd daemon must be restarted.

In Windows, where programs are typically launched from icons, the icon properties or system file extension association specifies the executable that is run. The default installed file types are as follows:

Extension	File Type Description	Executable
.LGC	Verastream Logic	nova.exe
.FLE	Verastream Application	nova.exe
.PIA	Verastream Process Integrator Application	snpi.exe

Command Line Parameter

Environment variables can be set from the snpi or nova executable command line for a specific executable instance. When setting MYDBG from the command line, insert a + before MYDBG.

Syntax: <program name> +<variable>=<value>

Windows example: snpi myprogram +MYDBG=/temp/debug.log!all

OpenVMS example: nova mytest "+MYDBG=mytest.log,all,mtime"

Note: By default, the command line syntax above is used for registered VCP server components. For related information, see section D. MYDBG Logging and Registered Server Components.

Operating System Shell

Environment variables can be set in the operating system shell for specific users, or system wide. Note: The sntcpd daemon and server components can be configured to run under various user accounts.

Order of Precedence

If the MYDBG environmental variable is set in multiple locations, the following order of precedence is used.

1. Executable command line
2. sn.ini in current directory, executable-specific section
3. sn.ini in Verastream bin directory, executable-specific section
4. sn.ini in current directory, [default] section
5. sn.ini in Verastream bin directory, [default] section
6. Shell environment variables set in current session or scripts used to start Verastream
7. Shell environment variables set for a specific user
8. Shell environment variables set for all users or system-wide

Note: The value of MYDBG at the time of server component registration is unrelated to what is used when the server component runs. (For example, using +MYDBG on the -eregister command line will generate a log of the registration process only.) For information on configuring logging for runtime execution, see D. MYDBG Logging and Registered Server Components.

C. Determining Which MYDBG Logs to Configure or Gather

When troubleshooting a problem within a composite application, a single snpi or nova log file may be sufficient. More logs may be needed to troubleshoot an issue that involves calling CSX, Siebel, or a server component.

For example, consider troubleshooting a composite application that calls a VCP server component in a CSX pool on another system. In this instance, you may need to capture and collect a number of logs, such as the following:

• snpi or nova log of the client execution
• sntcpd log of the system where client application runs
• sntcpd log of the system where the server component is registered and runs
• snpi log of the server component registration
• csx log for this particular CSX switch
• snpi or nova log of the server component execution

D. MYDBG Logging and Registered Server Components

The Verastream Register/Unregister dialog box can be accessed in multiple ways, such as from the Run menu in Verastream Process Integrator.

By default, a +MYDBG parameter is generated when you register a server component using the Verastream Register/Unregister dialog box. The parameter is generated in the command line that is run to start the component.

To configure Verastream not to generate a +MYDBG parameter during registration, in the Register/Unregister dialog box, select "Logging detected by runtime environment variable MYDBG" (version 9.6 or higher) or "logging detected by (global) environment variable MYDBG" (version 9.5.1 or earlier).

If you enable specific "Logging specifications" (version 9.6 or higher) or "Logging options for this registration" (versions 9.5.1 or earlier) the log group options correspond to MYDBG logging options as follows:

Version 9.6 or higher	Version 9.5.1 or earlier	MYDBG Equivalent Option
Granularity/Complete	Complete logging	all
Granularity/VSL only	VSL logging only	appl
Replication/Replicate all logging to VCP client	Replicate to client	vcp
N/A	No replication	-vcp
Timestamps/Seconds	With timestamps (seconds)	time
Timestamps/Milli-seconds	With timestamps (milliseconds)	mtime

After a server component is registered, you can examine the +MYDBG value in VCP Component Directory Explorer (version 9.6 or later) or Component Directory (version 9.5.1 or earlier), or in the pardir/snregtab.dat file.

E. MYDBG Logging for CSX Switches

The MYDBG value in the [csx] section of the sn.ini file applies to all CSX switch processes. In version 9.8, MYDBG can be set on a switch-specific basis from the CSX Configuration tool. If you do not specify a MYDBG value for an individual switch, the MYDBG value in the sn.ini file is used.

F. The NPCMD Environment Variable

In some troubleshooting situations, you may need to use the NPCMD environment variable along with the MYDBG variable to generate additional detailed debugging information. This undocumented variable is not typically used.

Warning: Enabling the NPCMD settings generates substantial additional logging detail, which can result in extremely large log files. This setting should only be used temporarily, and under the direction of Attachmate Technical Support.

When using the NPCMD environment variable, note the following:

• The MYDBG environment variable must be set to generate a log file, as described in prior sections.
• To enable network data logging, set NPCMD=debug in the appropriate sn.ini section or on the snpi command line. (See sn.ini File for details.)
• To enable detailed daemon logging of sent/received messages and replication, set NPCMD=repl in sn.ini [sntcpd] section.
• To enable logging of network data, messages, and replication, set NPCMD=repl!debug in sni.ini [sntcpd] section.

G. The NVNOCONFIRM Environment Variable

The NVNOCONFIRM environment variable is used to redirect pop-up dialog messages to a file. NVNOCONFIRM is useful for unattended processes, where user interaction is not expected (to avoid execution halting due to alert pop-up dialogs).

Messages that appear in the NVNOCONFIRM-specified file are the same as "alert" lines that appear in a MYDBG-specified log file.

With version 9.7 and earlier, set NVNOCONFIRM to the (optional directory and) file name.

With version 9.8, NVNOCONFIRM accepts MYDBG syntax (file name directives; date, time, and mtime control flag options; and separator characters) as described in section A. The MYDBG Environment Variable. For example:

Note: Be aware of the Order of Precedence. If you set NVNOCONFIRM in the sn.ini file, it is also applied when you run the development tools or other interactive applications (error messages do not appear on screen). Before running interactive tools, unset NVNOCONFIRM (or set it to a blank value, such adding +NVNOCONFIRM= to the shortcut executable command line used to run the development tool).

H. Verastream for Siebel: VCP Gateway Logging

The Verastream Siebel VCP Gateway handles requests from Siebel (Integration Objects [IOs] and Virtual Business Components [VBCs]) to VIB (CSX and VCP server components generated in PI Siebel IO/VBC wizards). Logging for VCP Gateway captures message transactions with thread ID numbers, errors, and settings.

To enable VCP Gateway logging, add or edit a MYDBG line in the vssblgw.ini configuration file on your Siebel system in the Siebel bin directory in UNIX, or the same directory as vssblgw.dll in Windows. The MYDBG syntax is the same as indicated in the MYDBG sections of this technical note; however, different file name directives and logging options are supported. These directives and options are listed below.

File Name Directives

Directive	Definition
%p	Process number (version 9.6 and higher)
%d	Date YYYYMMDD (version 9.6 and higher)
%t	Time (version 9.6 and higher)

Log Options

Flag	Definition
all	Enables !buf and !date
buf	Enables detailed logging, including raw data dump
date	Adds the date at the beginning of each log line (version 9.6 and higher)
dbg	Enables additional debug logging, including writing vssblgw.ini settings at the beginning of the log
mon	Enables logging of monitor thread which checks for timed out requests (default 5 second interval).

For example: MYDBG = c:\\log\\sbldll_%d_%t.log!buf

Note: Make sure the specified log directory already exists and has write permission. Otherwise, if logging cannot start, all Siebel requests will fail.

After editing the vssblgw.ini file, restart the Siebel system to unload the Gateway .dll or .so file. The changed configuration takes effect when the Gateway .dll or .so file is reloaded for the next VBC or IO request.

I. VSL Logging-Related Functions

Verastream Scripting Language (VSL) supports several useful functions related to logging.

BASE.DEBUG

The function "DEBUG BASE <expr>" is supported in version 9.7 and higher. It enables you to write a string to the current log file, regardless of whether application debug logging is enabled. Otherwise it is the same as LOG BASE. This is helpful for applications where full debug logging generates too much activity in the log file.

BASE.LOG

The function "LOG BASE <expr>" enables you to write a string to the current log file. Output is written to the log file only when application debug logging is enabled. This is useful for writing field values and calculation results to the log file for debugging purposes. (Alternately, to write associated fields to a log file, the argument can be a table, component stream, or component structure.)

STATUS.DBG

The function "DBG STATUS" enables application debug logging. This is equivalent to specifying the "appl" log group option in MYDBG.

Note: To ensure a complete log file (including execution of statements prior to DBG STATUS and any built-in statements prior to your START function), please do not use DBG STATUS when creating logs for Attachmate Technical Support. Please configure "appl" in MYDBG instead.

STATUS.NODBG

The function "NODBG STATUS" disables application debug logging.

STATUS.NEWDBGFILE

The function "NEWDBGFILE STATUS <string>" enables you to set a new MYDBG value. The current log file (if any) is closed and subsequent logging output is written to the new file. In version 9.6 and earlier, NEWDBGFILE also implicitly enables application debug logging (appl). Note: Because startup header information is missing from the new log file, please do not use NEWDBGFILE when creating logs for Attachmate Technical Support.

In version 9.7 and higher (with log group 'all' or 'ident' enabled), the end of the existing log reports the new file name including resolved directives ('Logging will continue with file ...'), and the new log file indicates the previous file name ('Continuation of log file ...').

Info() Function

The info() function can be applied to the STATUS object to retrieve debugging information. Common uses are as follows:

Function	Returns
info('STATUS','DEBUG')	The status of application debug logging, 'ON' or 'OFF'
info('STATUS','DBGFILE')	The name of the logging file (if any)
info('STATUS','PID')	The process ID number (same as the %p log file name directive) in version 9.7 and higher
info('STATUS','RUNID')	The application name (same as the %a log file name directive)
info('STATUS','EXCEPTION')	An exception name (for use in CATCH blocks)
info('STATUS','EXCEPTIONNAME')	Returns original exception name. This may be different than info('STATUS','EXCEPTION') for an exception that is thrown in a called server component (if the server named exception is not declared in the component body definition)
info('STATUS','EXCEPTIONSTRING')	An exception description (for use in CATCH blocks)
info('STATUS','ERROR_FIELD')	The error string field from invocation of the ERROR_FIELD STATUS function

J. Tips for VCP Server Component Logging

Typically, application debug logging is configured on a global basis through "appl" in the MYDBG variable in the sn.ini file. If you wish to configure logging this separately for a particular VCP server component, you can re-register it with a new +MYDBG value. (See section D. MYDBG Logging and Registered Server Components.) Either of these methods ensures that all statements are logged, including complete log header and built-in statements that may execute prior to your START function.

Enabling logging within the application (through use of DBG STATUS or NEWDBGFILE STATUS) is discouraged, since the log lacks information that may be useful for Attachmate Technical Support.

Although not recommended, if your situation requires component-specific logging configuration without re-registration, the following code sample demonstrates how to enable logging through component-specific flags in the sn.ini file:

This code allows you to enable debug logging in the server component by simply setting the following in the sn.ini file [default] section:

Note that the calling client must also use the "vcp" log option in order to capture the server component application debugging in the client log.

K. Configuring Line Wrap in Log Files

To limit the length of (and to wrap) long log file lines, set the DELEN environment variable (for example, DELEN=78 in sn.ini file). This can be useful when viewing log files with certain OpenVMS native text editors such as EDT or TPU, but is generally not necessary with vi or other common text editors and viewers.

By default, DELEN is set to 78 in version 9.6 and earlier on OpenVMS. For all other platforms, and in version 9.7 and higher on OpenVMS, DELEN is set to 0 by default, which disables line wrap.

Related Technical Notes

10206	Verastream Scripting Language Environment Variables
10999	Verastream Integration Broker Technical Notes