This document provides troubleshooting advice for various ApplinX topics:

See also Troubleshooting in document Upgrading, Migrating and Installing Fixes.

ApplinX Framework

This section covers the following topics:

See Web Application Development for introduction and concepts, and Error Messages for troubleshooting help.

Performance Monitoring

Performance monitoring provides the ability to trace the performance of all sessions/single sessions, and save them to a CSV (Excel) file.

This feature monitors the process of an instant/generated page, from pressing a host key until the result page is fully loaded. The monitoring includes browser performance, Web server performance and ApplinX server/host performance.

The monitoring includes:

  • The entire wait time the user waits between pressing an action key, until receiving the HTML result of the target screen - Total Request.

  • The entire time that the Web server processed the user request (including ApplinX server & the host response times) - Total Server Side.

  • The send key response time - SendKeys.

  • The HTML page loading time - Client Load.

  • Important ApplinX actions such as attaching to ApplinX server, creating the instant page (Generate Instant), updating controls from the host screen, updating tables (when tables exist), detaching from ApplinX server.

JavaScript Logger Engine

The JavaScript logger engine is used to log JavaScript errors (primarily) as well as to debug specific modules of the JavaScript engine. The engine logs JavaScript errors which occur to users of the Web application. These errors are logged to the framework JavaScript log, with the following user information: Session ID, IP, browser details.

Each line in the log displays a timestamp, module name, log level, and the message.

Logging JavaScript Errors

The JavaScript logger engine automatically logs JavaScript errors to a log text file on the server (logs/javascript_log.txt).

Applications created in ApplinX versions prior to 5.2.4 this file should be replaced/edited (if changes were made) with the config/gx_logConfig.xml file from the new application/config directory of the relevant framework type jsp/c#/vb.

Debugging JavaScript Modules

The JavaScript Logger Engine can be used by ApplinX developers to debug specific modules of the JavaScript engine (The JavaScript engine core, Emulation, modal windows, type ahead, Natural data transfer), by displaying the information in the log console (or writing to the server log when the log console is not shown).

To configure the JavaScript log console, configure parameters in the config/gx_clientConfig.xml file as follows:

logLevel="3" <- 3-activate debug mode (0-Error , 1-Warnings , 2-Massage , 3-Debug)
debugModules=:z_engine.js,z_emulator.js,z_window.js,z_typeAhead,z_ndt.js" <- which modules to debug
showLogConsole="true" <- show/hide the log console

The log text file also logs any error/debug (when active) messages when the browser is refreshed, when the system is disconnected, when clicking on the Write to server log button in the log console (if the log console is displayed) and when the log console's size reaches 5k (to avoid reducing the speed of the browser).


Whenever myFunc is executed the Boolean variable "myBool" is evaluated. If the value received is "false", a message is logged in the debug log stating that there is a problem.

function myFunc(){
      var myBool = false;
      if (!myBool){
       GXLog.debug("myModule","Something went terribly wrong!!");
      return myBool;

Ensure to set the config/gx_clientConfig.xml as detailed above.

Refer to the API:

Investigating the Web Application's Code

It is possible to use the ApplinX framework log to analyze and debug the code in the Web application. This is implemented by making changes in the config/gx_logConfig.xml file.

Start of instruction setTo define the messages that will be displayed in the framework log:

  1. Open config/gx_logConfig.xml.

  2. Uncomment the following section:


    <!--category additivity="false" name="<Category-Name>">
    	<level value="info"/>
    	<appender-ref ref="FRAMEWORK_LOG"/>


    <!-- logger additivity="false" name="<Category-Name>">
    	<level value="info"/>
    	<appender-ref ref="FRAMEWORK_LOG"/>
  3. Change the level tag value to either: info, error, warning, or debug.

  4. Change the <Category-Name> to a meaningful value. This will make it easier for you to find log entries at a later time.

  5. Restart your web server, in order for the changes to take effect.

  6. To write to the log file from anywhere in your code, make sure that the call looks similar to the following (depending on the log level):"Category-Name","<Message>");

Redirecting back to hostLogin Page

When using the hostLogin.jsp/hostLogin.aspx files and disconnecting the user, use the following JavaScript syntax to redirect back to the hostLogin page in the ApplinX Framework application:

window.parent.location="<landing page url>"

The hostLogin page needs to be loaded outside of the ApplinX Framework frameset.

Customizing the Session ID

The necessary steps depend on whether you are using Natural under UNIX or another scenario.

Start of instruction setTo customize the session ID when running under Natural UNIX

  1. Create new Java file under WEB-INF/contexts - we called it "aaa" in this example.

  2. Implement the Java class in this manner:

    package contexts; 
    import com.sabratec.applinx.j2ee.framework.web.GXHostLoginContext; 
    import com.sabratec.applinx.framework.*; 
    public class aaa extends GXHostLoginContext { 
    private static final long serialVersionUID = 1L; 
    public void gx_onLoad() { 
    public void doLogin() { 
    public void gx_initSessionConfig() { 
           GXWebAppConfig gx_appConfig = getGXAppConfig(); 
  3. Edit the hostLogin.jsp to use this new Java file, by pointing the gx_page to the new class <gx:page gx_context="">.

  4. Use the build script ( to recompile this class.

  5. Restart Tomcat and try again.

Start of instruction setTo customize the ApplinX session ID in another (non-Natural/UNIX) scenario

  1. Go to the ApplinX web application folder.

  2. Edit the file.

  3. In the gx_initSessionConfig method, uncomment the following line:

  4. Change <YOUR_SESSION_ID> to the required value.

  5. Use the build script ( etc) to recompile this class.

.NET Configuration

In .NET, when attempting to save the changes made in the Configuration Editor, you may receive an error message: Access denied. In order to resolve this problem, follow these instructions:

  1. Click on Click here for configuration details.

  2. Open Windows Explorer and right-click on the config directory in your Web application (<YourWebApp>\config).

  3. Select Sharing and Security... and then select the Security tab.

  4. Click Add....

  5. If you are working with a network/active directory, you need to change the location and select the server name/computer name.

  6. Add the IIS process user, typically called ASPNET, to the list of object names that it is possible to select. Click Check Names to locate the defined user.

  7. Click OK.

  8. Add Modify and Write permissions to the folder where the configuration is located. Click OK.

  9. Restart IIS.

  10. In the Framework Configuration Editor, re-save your configuration.

See Configuring your Web Application for more information.

Application Map

An individual screen thumbnail within the Application Map can indicate problems or incompatibility between the defined identifiers and the screen image attached to the screen. Such problems are indicated by a red frame around the specific screen.

Possible problems:

  • Incompatibility between the defined identifiers and the screen image attached to the screen. This can happen as a result of creating a screen and then manually changing an identifier.

  • The screen suits the screen image, but there is a screen which is more suitable or identical to the screen image. Look at the name of the screen which is on the screen image and check that it suits the current screen. Note that the name which is on the screen image indicates how the server identified this screen image given all current screen definitions.

See Application Map for more information.

Connection Pools

Symptom Explanation Possible Reasons How to Check
All my connections are broken Host sessions become broken if they cannot get to Ready state. Ready means that:
  1. The connection is alive.

  2. If an "initial screen" is defined by the pool, the session must get there.

Host is unavailable. Try to connect to the host without the pool.
Initialization path needs to be modified. Create a connection outside the pool, run the initialization path and verify it gets to the "initial screen".
Connections disconnect after use but I want to reuse them The pool may be configured to allow reusing a host connection that was used by a previous user. This would require returning the connection to the initial screen, either by implementing a robust navigation logic inside the invoked procedure or in the recycle path. The Disconnect after usage option is checked. Observe the state of the Disconnect after usage checkbox in pool tab of the connection pool.
The logic of the user activity or the recycle path causes a disconnection from the host. Capture a trace file for the user activity and recycle path. Observe that the host session is not terminated during the invocation of user activity or the recycle path.
When a connection is returned to the pool and it is not in the "initial screen", and there is no recycle path that successfully navigates to the initial screen. Capture a trace file for the user activity and recycle path. Observe that at the end of the user activity and the recycle path invocation, the connection is in the initial screen.
Connections remain Active after use Upon finishing the user activity on a pool connection, the state of the connection would change according to the pool configuration and the state of the user session. The state of the connection would remain active if the session used by the pool has not ended. A flow procedure creates an emulation session on a pool connection, but the "end session" node is not called on that session. Verify the existence of an "end session" node in the flow procedure that creates the emulation session. Verify that the "end session" node is reached by capturing a trace file or by logging the invocation of the flow procedure.
Connections remain Terminating after use A pool may be terminating a connection based on the pool's configuration, connection count and the status of the session. When doing so, the connection status would become "Terminating" and the termination path would run on the connection. After the termination path is completed, the connection is removed from the pool. An exception in the termination path is causing the host connection to either get stuck or to terminate before completing the path. Capture a trace file that includes the invocation of the termination path and observe that the path has completed successfully. Search for exceptions in the server logs that occurred during the invocation of the termination path.
A used connection is disconnecting while being used   The host is disconnecting the pool connection based on the user activity or due to the host state. Capture a trace file for the user activity, observe the last packet transmissions between the server and the host. Look in the server log for an error indicating a socket close around this timestamp. Also ask the host administrator to inspect the host's log for disconnections.
Another host connection is using the same host credentials/device name and hijacking the session. When capturing trace files, you would notice a trace file created at the time when a previous trace file is closed. Both traces will include send sections containing the same credentials or device name.

When recording trace files to capture the symptoms mentioned above, we recommend using the following variables in the trace file name: connection ID (%c), session ID (%u), creation time of file (%t). See Recording Trace Files for more information.

See Connection Pools for more information.

Natural for UNIX APX Component

To troubleshoot problems in the APX component's functionality it is possible to define tracing its activity. The daemon and the Natural application with the APX lib can be traced separately. In order to determine which of the two components' activity should be traced follow these guidelines: when the problem seems to be to do with connecting the ApplinX server to the APX daemon (including authentication problems), trace the daemon component. For any other problems trace the Natural application. Note that it is not recommended to use the trace file in the production environment on a regular basis.

Start of instruction setTo trace the APX daemon

  1. Go to the $NATDIR/$APXNODE directory.

  2. Edit the file.

    Find EXECUTABLE=apxsrvd, and change it to

  3. Define the following environment variables (the following is an example of how these should be defined in sh/bash):

    > PT_TRACELEV=i6000
    > SAGTMP=$HOME/tmp
    > export PT_TRACELEV
    > export SAGTMP

    The trace files are created in the $SAGTMP directory. In the example above this is $HOME/tmp.

  4. Restart the daemon:

    > servicename stop
    > servicename start


    > portnumber stop
    > portnumber start

Start of instruction setTo trace the Natural Application with the APX library

  1. Go to the $NATDIR/$APXNODE directory.

  2. Edit the file.

    $NATDIR/$NATVERS/bin/natapx parm=$PARAMETERS etid=$$ >/dev/null 2>&1

    Change natapx to

    Uncomment (by removing the # from the beginning of the rows) the TRACE section.

The trace files are created in the $SAGTMP directory.

By default it is $HOME/tmp. It will take effect when next connecting to the daemon.

See Installing APX Component for Natural UNIX Protocol for more information.

Web Procedures

See Web Procedures for more information.

What to do when the Web Procedure Fails to Run

The Web Procedure can fail to run for a number of reasons such as an element cannot be found on the page or unexpected behavior when running JavaScripts. Some of these issues can be solved by adjusting parameters in the <ApplinX installation>/config/gxconfig.xml file. Following is a list of possible problems with a recommendation as to what to do and when relevant, which parameter to configure. Below is a snipet of the code as it appears within the gxconfig.xml file.

Timeout error: When running the Web Procedure, sometimes an error message is displayed indicating that a timeout occurred, and that the procedure failed and did not run successfully. This can be for a number of reasons:

  • A specific element used in the procedure was not found on the page. In this case, you should try the following:

    1. The XPath defined may not capture the correct element. Run the procedure from within the Designer and follow the output in the Console area.

    2. Refine the XPath to make it more robust. Refer to What is an XPath?

    3. Change the ApplinX Server log level to "trace" to help you understand where the problem may lie.

    4. If you know that this element is on the page, you should try to change the waitElementTimeout parameter and see if after extending this time the element is found.

  • Required resources are not loaded on the page within a certain amount of time. You can confirm that this is your problem by setting the ApplinX log level to "trace" and see that the actions/web element content retrieval is performed on the previous page. Change the navigationTimeout parameter to try and solve this.

Unexpected behavior when running JavaScript methods: If in a scenario which relies on the execution of a JavaScript method, the results are not as expected. Changing the javascriptTimeout may solve this.

CSS related problem: When there is a scenario that relies on the evaluation of CSS rules, and the results are not as expected, setting the cssEnabled parameter to enabled may solve this.


Error Messages

RC Error Message Explanation Possible Reasons What should I do?
5005 ERROR SOCKET Error communicating with ApplinX server May occur as a result of incompatible client and server version. Check the Applinx server version (see server log) and the client version (see client log) and make sure they are of the same version and build number.
If the host decides to close the connection with the ApplinX server, the session in the server will be disconnected and the client will receive a 5005 error, indicating that the ApplinX session is no longer active. Host failure or network issue that made it offline. Probably more details in the host logs. Catch this error in the client web application and act accordingly. Look into the host logs for more details.
5002 ERROR CANNOT CONNECT TO HOST When opening a Web application page we get the following error:
  1. Missing or insufficient permissions

  2. The host is offline.

  3. Password expired (Natural under UNIX).

Check user credentials.
n/a Error evaluating the expression In earlier versions, NULL and empty string were almost the same. From version 9.8 they are not, and you should actively use options like isNull() or put in a default value to avoid these errors. Usually these errors appear after migrating procedures, see the error message in the log for more details. Look for "If" block with the empty string or look for inputs without the default value. The error log message should help you figure out where this is coming from.
n/a The repository is not available Usually happens due to a Java heap space problem. The JVM's XMX parameter memory allocation is low. Look into the server's launch config files (startup.bat / GXApplinXService.ini) and increase the -xmx value of the JVM.
n/a General Javascript errors The Framework's JavaScript engine encountered an error. Could be caused by a host key not responding, or screen that wasn't refreshed after entering a value to an input field. Open the browser's developer tools and use them to debug the scenario until you pinpoint the root cause.
5051 Procedure Exception: Cannot run path procedure proc_name, error getting host connection, error code Service fails to run on the local server. The error code should be "ERROR_SERVICE_NOT_ACTIVE". Connection pool isn't active. Check connection pool configuration. If it is set to "when first accessed", change it to "manual".
5080 ERROR_CREATING_TABLE:Screen mismatch The developer wants to redirect the user to the main menu screen (or some other screen). The default behavior of the ApplinX Framework when it encounters an ApplinX session error is to redirect the user to the error.JSP page. This page will specify the error code and describe the error. For example: If for some reason the ApplinX session has been disconnected, pressing a PF key in the web application will result in an error. Customize ApplinX Framework Session Error Handling.
n/a Replayer configuration doesn't match the current host configuration. When running a trace file from the designer there should be a match between the Replayer to the current host configuration. Replayer configuration doesn't match the current host configuration. For example, the Replayer Expected Model is 5 and the Host configuration Model is 2. Open the Host configuration and change the host configuration according to the trace file.
n/a Error in Procedure. Repeat limit reached in step step_no. 500 repetitions. Repeat limit has been reached. To prevent creating infitinte loops by mistake, the default repeat limit value is set to 500. Enter a higher value for repeat limit, or specify zero, which means a record can be used an unlimited number of times.

Start-up Response Record

Under AS/400, a start-up response is provided by the host. This response code indicates whether an automatic sign-on attempt was successful or not. The response code is displayed:

  • in the web application

  • in the Error Log tab in the Software AG Designer

  • in the printer applet in the Software AG Designer

The response codes are organized as follows:

See also Single Sign-on under AS/400 under General Application Customization in the Web Application Development documentation.

Success Response Codes

Code Description
I901 Virtual device has less functionality than source device.
I902 Session successfully started.
I906 Automatic sign-on requested, but not allowed. Session still allowed; a sign-on screen will be coming.

Error Response Codes

Code Description
2702 Device description not found.
2703 Controller description not found.
2777 Damaged device Description
8901 Device not varied on.
8902 Device not available.
8903 Device not valid for session.
8906 Session initiation failed.
8907 Session failure.
8910 Controller not valid for session.
8916 No matching device found.
8917 Not authorized to object.
8918 Job canceled.
8920 Object partially damaged.
8921 Communications error.
8922 Negative response received.
8923 Start-up record built incorrectly.
8925 Creation of device failed.
8928 Change of device failed.
8929 Vary on or vary off failed.
8930 Message queue does not exist.
8934 Start-up for S/36 WSF received.
8935 Session rejected.
8936 Security failure on session attempt.
8937 Automatic sign-on rejected.
8940 Automatic configuration failed or not allowed.
I904 Source system at incompatible release.

Error Response Codes for non-Kerberos Service Token

Code Description
0001 System error.
0002 Userid unknown.
0003 Userid disabled.
0004 Invalid password/passphrase/token.
0005 Password/passphrase/token is expired.
0006 Pre-V2R2 password.
0008 Next invalid password/passphrase/token will revoke userid.

Error Response Codes for Kerberos Service Token

Code Description
0001 User profile is disabled.
0002 Kerberos principal maps to a system user profile.
0003 Enterprise Identity Map (EIM) configuration error.
0004 EIM does not map Kerberos principal to user profile.
0005 EIM maps Kerberos principal to multiple user profiles.
0006 EIM maps Kerberos principal to user profile not found on system.
1000 None of the requested mechanisms are supported by the local system.
2000 The input name is not formatted properly or is not valid.
6000 The received input token contains an incorrect signature.
7000 No credentials available or credentials valid for context init only.
9000 Consistency checks performed on the input token failed.
A000 Consistency checks on the cred structure failed.
B000 Credentials are no longer valid.
D000 The runtime failed for reasons that are not defined at the GSS level.