This topic includes the following:
- Setting options for the xfServerPlus log
- XFPL_LOG
- XFPL_LOGFILE
- XFPL_SINGLELOGFILE
- XFPL_SESS_INFO
- XFPL_FUNC_INFO
- XFPL_DEBUG
- Protocol versions
- Error messages in the xfServerPlus log
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.
|
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.
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.)
|
|
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. |
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
Points to the name and location of the log file. The log must be on the machine that xfServerPlus is running on. On Windows and Unix, place it in a location that does not have a period ( . ) in the directory name. (A period in the directory path may cause the file to be placed in an unexpected location or to not be created at all.) 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
|
|
(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. |
(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
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 |
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 clients. |
|
ALL |
Server protocol version |
Protocol version of xfServerPlus. See the table in Protocol versions 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 encryption is the only type available as of Synergy/DE 11. |
|
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. |
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
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 |
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 |
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 |
|
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
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 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 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 versions
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.
|
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 11.1 12.1, 12.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.
|
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 |
|
2024 |
Unable to access method catalog file |
|
3001 |
Integer length in Synergy Method Catalog invalid |
|
3002 |
Incoming data too big for the desired variable |
