Using server‑side logging

By default, xfServerPlus always logs errors to the application event log (Windows), syslog (UNIX), or operator console (OpenVMS). On Windows, the dbs.exe runtime also logs traceback information from fatal errors to the application event log on the server machine.

Note

On UNIX, syslog may not be running by default. See your system administrator to ensure the daemon is running.

On OpenVMS, set REPLY/ENABLE=NETWORK to send messages to the operator console.

You can log additional information with the xfServerPlus log, which is a record of remote access requests, data passed and returned, and errors. It can be used for troubleshooting and as a record of who has logged into your system. The log resides on the machine that xfServerPlus is running on. By default, xfServerPlus logging is turned off.

On Windows and UNIX, the default is to create a separate xfServerPlus log file for each session; you can specify a single log file if desired. We recommend that when you have error‑only logging enabled in a production environment, you use a single log file. See Setting options for the xfServerPlus log below for details on this and other options.

On OpenVMS, the xfServerPlus log produces a single log file for each instance of xfServerPlus. There is no option for multiple log files. You can use servstat option 11, Cycle xfServerPlus log file, to close and then open a new version of the log file. This enables you to examine the log file without shutting down rsynd. (See servstat program for details.)

When xfServerPlus logging is turned on, you can use the XFPL_LOG routine to make application‑defined entries in the xfServerPlus log from either the server or the client application. See XFPL_LOG for more information.

Setting options for the xfServerPlus log

All logging options are set in the xfpl.ini file (see Using the xfpl.ini file). The logging options enable you to turn logging on and off, specify a name and location for the log file, indicate whether you want single or multiple log files, and control what data is logged.

For best results, we recommend that you put the XFPL_LOG setting first in the xfpl.ini file, followed by the other logging settings and then by the non‑logging settings, such as XFPL_LOGICAL. This enables xfServerPlus to create the log file before processing the other settings. Any errors that xfServerPlus encounters while reading the xfpl.ini file will then be recorded in the xfServerPlus log file. Even after encountering an error in the xfpl.ini file, xfServerPlus will continue processing the file so that all errors can be logged before terminating the remote connection. (These errors will also be output to the application event log on Windows, syslog on UNIX, or operator console on OpenVMS.)

Note

If you are using a single log file and have session or function logging enabled, the file will become quite large and should be cleared out periodically. You can either delete the entire file or open the file in a text editor and selectively delete material that is no longer needed.

If you are using multiple log files (Windows and UNIX only), the files themselves will not become very large, but large numbers of them will accumulate on your server and may need periodically to be deleted.

XFPL_LOG

Turns logging on and off. Additional settings control the type of information that is logged. If logging is turned on and no level is specified, error‑only logging will take place.

Values: ON, OFF

Default value: OFF

Example: XFPL_LOG=ON

XFPL_LOGFILE

Points to the name and location of the log file. The log must be on the machine that xfServerPlus is running on. If logging is turned on and you do not specify a file name and location, the defaults are used. If you are generating multiple log files (XFPL_SINGLELOGFILE is set to OFF; see below), a date/time stamp will be appended to the end of the log filename.

Default value: DBLDIR:xfpl.log

Example: XFPL_LOGFILE=c:\TempFiles\my_log.log

Note

(Windows) If no information is recorded in the log file, or if a log file is not created at all, verify that the account used to run xfServerPlus sessions has write permission for the directory in which the log is located. xfServerPlus installs in c:\Program Files\Synergex\SynergyDE. If the account used to run xfServerPlus sessions was created with user level privileges, it will not be able to write to a log file in that location because (by default) accounts in the user group cannot write to the Program Files directory or its subdirectories. Rather than change the privileges on the default directory, we recommend that you move the log file to another location.

XFPL_SINGLELOGFILE

(Windows and UNIX only) Determines whether information is logged to a single file or multiple files. By default, information from each session is logged to a separate log file named with the log filename plus a date and time stamp to differentiate the files. If you would prefer that all sessions write to a single log file, set XFPL_SINGLELOGFILE to ON. You can identify which log entries are associated with which session by the session ID.

We recommend that for error‑only logging, you use a single log file. For other logging levels, in which more information is logged, separate log files may be easier to read.

Multi‑file logging may offer improved performance because only one process is writing to the file, and so it can remain open. With single‑file logging, the file must be opened and closed because different processes are writing to it, which can slow performance.

Values: ON, OFF

Default value: OFF

Example: XFPL_SINGLELOGFILE=ON

XFPL_SESS_INFO

Determines the level of session logging. Session logging records information about the connection, such as when the session was started and stopped and whether compression was enabled.

Values: NONE, CRITICAL, ALL

Default value: NONE

Example: XFPL_SESS_INFO=CRITICAL

The following table shows the information that is logged when XFPL_SESS_INFO is set to CRITICAL or ALL. 

XFPL_SESS_INFO

Value

Information logged

Description

CRITICAL or ALL

Session ID

ID that indicates the transactions related to the activities of a single end user from log‑on to log‑off.

CRITICAL or ALL

xfServerPlusRemoteSession started

Date and time session started (log‑on).

CRITICAL or ALL

xfNetLink IP address

IP address of the xfNetLink machine that called xfServerPlus.

CRITICAL or ALL

Domain

Domain name or IP address of the xfNetLink machine.

CRITICAL or ALL

xfServerPlusRemoteSession connected to

The type of client xfServerPlus is connected to: Synergy, Java, or .NET.

CRITICAL or ALL

Errors

Error packet that is sent to xfNetLink from xfServerPlus if an error is detected. Also shows the line number at which the error occurred.

CRITICAL or ALL

xfServerPlusRemoteSession stopped

Date and time session terminated (log‑off).

ALL

xfNetLink port

Port on which xfNetLink is listening. Displays only for pre‑8.3 client.

ALL

Server protocol version

Protocol version of xfServerPlus. See the table in Protocol version for the correspondence between the protocol version and software version.

ALL

Compression

Indicates whether xfServerPlus compression is on or off.

ALL

Average compression

If compression is on, displays the average percentage of compression for data sent and received during this session.

ALL

Encryption

If encryption is enabled, displays the type of encryption: master or slave.

ALL

Cipher

If encryption is enabled, displays the level of encryption: high, medium, low.

ALL

xfServerPlusRemoteSession session time‑out

If SET_XFPL_TIMEOUT is called, this shows the value that the time‑out is set to. If xfServerPlus times out, that fact will be recorded in the log.

Note

Because many users may access your application at the same time, if you are using a single log file, entries regarding a single session will likely be interspersed with entries from other sessions. The session ID at the beginning of each line enables you to identify entries by session.

The example below shows the type of information that is recorded when XFPL_SESS_INFO is set to CRITICAL. “000007F4” is the session ID.

000007F4: xfServerPlusRemoteSession 10.3.1 started: 13‑JUL‑2014 16:35:49
000007F4: xfNetLink ip address = 111.22.33.44, 6F16212C
000007F4: Domain: webtest Domain or IP
000007F4: xfServerPlusRemoteSession connected to .Net client
000007F4: ***** Error #2012 at line 652 *****
000007F4: 2012: Routine not found in ELB.
000007F4: 2012: Error occurred during lookup of external routine.
000007F4: 2012: Routine name: function_fred
000007F4: 2012: ELB name: DBLDIR:xfpl_tst
000007F4: ***** End of Error *****
000007F4: xfServerPlusRemoteSession 10.3.1 stopped: 13‑JUL‑2014 16:35:53

The example below shows the type of information that is recorded when XFPL_SESS_INFO is set to ALL.

00000308: xfServerPlusRemoteSession 10.3.1 started: 13‑JUL‑2014 16:29:56
00000308: xfNetLink ip address = 111.22.33.44, 6F16212C
00000308: Server Protocol Version: 6
00000308: Domain: webtest Domain or IP
00000308: Compression = on
00000308: xfServerPlusRemoteSession connected to .Net client
00000308: xfServerPlusRemoteSession timeout set to 2 minutes and 7 seconds
00000308: Average Compression
00000308:   sends   : 11.18%
00000308:   receives: 0.00%
00000308: xfServerPlusRemoteSession 10.3.1 stopped: 13‑JUL‑2014 16:29:57 

XFPL_FUNC_INFO

Determines the level of function and subroutine logging. Function logging records information about the Synergy routines that are called from the client.

Values: NONE, CRITICAL, ALL

Default value: NONE

Example: XFPL_FUNC_INFO=ALL

The following table shows the information that is logged when XFPL_FUNC_INFO is set to CRITICAL or ALL.     

XFPL_FUNC_INFO

Value

Information logged

Description

CRITICAL or ALL

Session ID

Indicates the transactions related to the activities of a single end user from log‑on to log‑off. See the note under XFPL_SESS_INFO above.

CRITICAL or ALL

Packet received at

Date and time that xfServerPlus received the packet.

CRITICAL or ALL

Method ID

Method ID that was called.

CRITICAL or ALL

Function

Name of the Synergy routine that was called.

CRITICAL or ALL

ELB

ELB or shared image in which the called routine is located.

CRITICAL or ALL

Packet returned at

Date and time the packet was returned by xfServerPlus.

ALL

Encryption enabled

If slave encryption is enabled, this indicates that the method is encrypted.

ALL

Parameter [n]

Data type, parameter size, and actual data passed for each parameter. [n] is the parameter sequence number; the data is enclosed in square brackets. If encryption is enabled, the log displays a string of 10 asterisks instead of the packet contents.

The following abbreviations are used for data type:

AL = alpha
AT = autotime
BI = binary (handle)
DEC = decimal
ENUM = enumeration
HA = memory handle
IMPDEC = implied‑decimal
INT = integer
SS = System.String
STR = structure

ALL

Function called at

Date and time the routine was called.

ALL

Function return value

The value returned by the function. If encryption is enabled, the log displays a string of 10 asterisks instead of the packet contents.

ALL

Returning parameter [n]

Data type, parameter size, and returned data for parameters flagged as having return data in the SMC. (These are “out” or “in/out” parameters). [n] is the parameter sequence number; the data is enclosed in square brackets. If encryption is enabled, the log displays a string of 10 asterisks instead of the packet contents. See above for data type abbreviations.

The example below shows the type of information that is recorded when XFPL_FUNC_INFO is set to CRITICAL. The final “packet received” message is the shutdown message received by xfServerPlus from the client.

00000418: Packet received at 13‑JUL‑2014 16:25:57
00000418: Method id: xfpl_tst1
00000418: Function: function_one
00000418: ELB: DBLDIR:xfpl_tst
00000418: Packet returned at 13‑JUL‑2014 16:25:57:990000
00000418: Packet received at 13‑JUL‑2014 16:25:58:991000

The example below shows the type of information that is recorded when XFPL_FUNC_INFO is set to ALL.

000003E0: Packet received at 13‑JUL‑2014 16:16:50:146000
000003E0: Method id: xfpl_tst6
000003E0: Function: function_ten
000003E0: ELB: DBLDIR:xfpl_tst
000003E0: **** Incoming Parameters ****
000003E0: Parameter[1] = Type: (AL), Size: (5)
000003E0: Data [abcde]
000003E0: Parameter[2] = Type: (AL), Size: (5)
000003E0: Data [54321]
000003E0: **** End of Incoming Parameters ****
000003E0: Function called at 13‑JUL‑2014 16:16:50:167000
000003E0: **** Outgoing Parameters ****
000003E0: Function Return Value: 123456789
000003E0: Returning Parameter[2] = Type: (AL), Size: (5)
000003E0: Data [back]
000003E0: **** End of Outgoing Parameters ****
000003E0: Packet returned at 13‑JUL‑2014 16:16:50:209000
000003E0: Packet received at 13‑JUL‑2014 16:16:51:229000 

XFPL_DEBUG

Turns debug logging on and off. Debug logging records information that may be useful in troubleshooting xfServerPlus and xfNetLink errors.

Values: ON, OFF

Default: OFF

Example: XFPL_DEBUG=ON

The following table shows the information that is recorded when XFPL_DEBUG is set to ON.

XFPL_DEBUG

Information logged

Description

Ini

Initialization. Shows what XFPL_SMCPATH is set to; if not set, the default is used (DBLDIR) and this line does not display.

Information that is recorded when XFPL_SESS_INFO is set to ALL

Session information; see XFPL_SESS_INFO .

Information that is recorded when XFPL_FUNC_INFO is set to ALL

Function information; see XFPL_FUNC_INFO .

Command line

Command line used to start xfServerPlus.

Packet

Text of every packet received by xfServerPlus or returned to xfNetLink. For outgoing packets, the initial character in the packet indicates the type of xfNetLink client:

D = Synergy client
J = Java client
N = .NET client

Returned packets are indicated by an ‘R’.

If encryption is enabled, the log displays a string of 10 asterisks instead of the packet contents.

Not returning parameter [n]

Data type and parameter size of parameters that were sent but are not being returned. (These are “in” parameters.) [n] is the parameter sequence number. The following abbreviations are used for data type:

AL = alpha
AT = autotime
BI = binary (handle)
DEC = decimal
ENUM = enumeration
HA = memory handle
IMPDEC = implied‑decimal
INT = integer
SS = System.String
STR = structure

The log also includes parameter and returning parameter information, recorded as part of the function information.

The example below shows the type of information that is recorded when XFPL_DEBUG is turned on.

00000D00: ini: XFPL_SMCPATH translates to {C:\work}
00000D00: xfServerPlusRemoteSession 10.3.1 started: 13‑JUL‑2014 12:40:13
00000D00: Command line = {C:\Program Files\Synergex\SynergyDE\
dbl\bin\dbs.exe ‑r DBLDIR:xfpl 6F16212C 0}
00000D00: xfNetLink ip address = 111.22.33.44, 6F16212C
00000D00: Packet = {        }
00000D00: Server Protocol Version: 6
00000D00: Packet = {     13‑JUL‑2014      12:40:13;00     }
00000D00: Packet = {J0000webtest Domain or IP;Challenge Response;     }
00000D00: Domain: webtest Domain or IP
00000D00: Compression = off
00000D00: xfServerPlusRemoteSession connected to .Net client
00000D00: Packet = {Nxfpl_tst6;2;AL5#abcde;AL5#54321;}
00000D00: Packet received at 13‑JUL‑2014 12:40:14:411000
00000D00: Method id: xfpl_tst6
00000D00: Function: function_ten
00000D00: ELB: DBLDIR:xfpl_tst
00000D00: **** Incoming Parameters ****
00000D00: Parameter[1] = Type: (AL), Size: (5)
00000D00: Data [abcde]
00000D00: Parameter[2] = Type: (AL), Size: (5)
00000D00: Data [54321]
00000D00: **** End of Incoming Parameters ****
00000D00: Function function_ten called at 13‑JUL‑2014 12:40:14:502000
00000D00: Function function_ten returned at 13‑JUL‑2014 12:40:14:531000
00000D00: **** Outgoing Parameters ****
00000D00: Function Return Value: 123456789
00000D00: Not returning Parameter[1] = Type: (AL), Size: (5)
00000D00: Returning Parameter[2] = Type: (AL), Size: (5)
00000D00: Data [back]
00000D00: **** End of Outgoing Parameters ****
00000D00: Packet returned at 13‑JUL‑2014 12:40:14:573000
00000D00: Packet = {Rxfpl_tst6;002;000DE9#123456789;002AL4#back;}
00000D00: Packet = {S;0;;}
00000D00: Packet received at 13‑JUL‑2014 12:40:14:640000
00000D00: xfServerPlusRemoteSession 10.3.1 stopped: 13‑JUL‑2014 12:40:14 

Protocol version

The protocol version for xfServerPlus is recorded in the xfServerPlus log and may occasionally appear in an error message. The table below shows the correspondence between protocol version and software version.

Protocol version

xfServerPlus version

2

6.3, 7.1

3

7.3

4

7.5

5

8.1, 8.3, 9.1

6

9.3, 9.5, 10.1, 10.3

Error messages in the xfServerPlus log

The table below lists the error numbers and the message text that appear in the xfServerPlus log. Errors recorded in the event log (Windows), syslog (UNIX), or operator console (OpenVMS) use these same error numbers, but the message text may be slightly different.

Errors in the 2000 series are logged and cause routine execution to stop, although xfServerPlus continues running. Errors in the 3000 series are logged but routine execution continues. The error message text shown in the table may be accompanied by additional detail information.

You may also see regular Synergy DBL errors with additional detail information.  

xfServerPlus Error Messages

Error number

Error message

2001

Incorrect message type

2002

Method ID too long

2003

Invalid number of parameters

2004

Parse error

2005

Invalid Synergy Type sent

2006

A required parameter was not passed

2007

Invalid data type specified in Method Catalog

2008

Error occurred in mapping array element

2009

Couldn’t open file output channel

2010

Invalid operation type in file_read

2011

Method ID not found

2012

Routine routine_name not found in ELB ELB_name

2013

Unable to open method catalog file

2014

Unable to open method parameter file

2015

ELB not found

2016

Global not found: global_name

2017

File not found: filename

2018

Internal routine not found

2019

Secure communications required

2020

Old ELB file format detected—relink

2021

Bad ELB detected

2022

ELB file built with opposite ‘endian’

2023

ELB file built with opposite bit size

3001

Integer length in Synergy Method Catalog invalid

3002

Incoming data too big for the desired variable