Troubleshooting

Learn how to identify and resolve common issues in ApplinX, including framework errors, connection pool problems, and configuration challenges.

For more information, see Upgrading, migrating and installing fixes and Log files in ApplinX.

ApplinX Framework

Monitor performance, debug JavaScript errors, investigate code, and customize session handling in ApplinX Framework applications. For more information, see the following:

Performance monitoring

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

This feature monitors the processing of an instant or generated page, from pressing a host key until the result page is fully loaded. Monitoring covers browser performance, web server performance, and ApplinX server and host performance.

Monitoring includes:
Total request
The total wait time from pressing an action key to receiving the HTML result of the target screen.
Total server side
The total time the web server takes to process the user request, including ApplinX server processing and the host response times.
SendKeys
The send key response time.
Client load
The time required to load the HTML page.
ApplinX actions
Important ApplinX actions such as attaching to the ApplinX Server, creating the instant page (Generate Instant), updating controls from the host screen, updating tables (when applicable), and detaching from the ApplinX Server.
JavaScript logger engine

The JavaScript logger engine is used primarily to log JavaScript errors (primarily) and to debug specific modules of the JavaScript engine. The engine logs JavaScript errors that occur for users of the web application. These errors are logged in the framework JavaScript log together with the following user information: session ID, IP address, and 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).

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

Debugging JavaScript modules

The JavaScript logger engine is used by ApplinX developers to debug specific modules of the JavaScript engine (The JavaScript engine core, emulation, modal windows, type ahead, and 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: 

<engineConfig
logLevel="3" <- 3-activate debug mode (0-Error , 1-Warnings , 2-Message , 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 and debug (when active) messages when the browser is refreshed, when the system is disconnected, when the Write to server log button is clicked in the log console (if the log console is displayed), and when the log console size reaches 5 KB to avoid reducing the speed of the browser.

For example:

When myFunc executes, the Boolean variable myBool is evaluated. If the value received is false, a message is logged in the debug log stating that a problem has occurred.

function myFunc(){
      var myBool = false;
      doSomething(myBool);
      if (!myBool){
       GXLog.debug("myModule","Something went terribly wrong!!");
      }
      return myBool;
}
Ensure to set the config/gx_clientConfig.xml as detailed earlier. For more information, see the following API:
  • GXLog.debug(moduleName, message)
  • GXLog.warning(moduleName, message)
  • GXLog.error(moduleName, message)

Investigating the web application code

You can 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.

To define the messages that is displayed in the framework log:
  1. Open config/gx_logConfig.xml file.
  2. Uncomment the following section:
    JSP
    <!--Logger name="<Category-Name>" level="info" additivity="false"> <AppenderRef ref="FRAMEWORK_LOG"/> </Logger-->
    .NET
    <Logger name="<Category-Name>" level="info" additivity="false"> <AppenderRef ref="FRAMEWORK_LOG"/> </Logger>
  3. Change the level tag value to one of the following: info, error, warning, or debug.
  4. Change the <Category-Name> to a meaningful value to make it easier to find log entries at a later time.
  5. Restart the web server for the changes to take effect.
  6. To write to the log file from anywhere in the code, ensure that the call resembles one of the following example, depending on the log level:
    • GXLog.info("Category-Name","<Message>");
    • GXLog.error("Category-Name","<Message>");
    • GXLog.warning("Category-Name","<Message>");
    • GXLog.debug("Category-Name","<Message>");

Redirecting back to hostLogin page

When using the hostLogin.jsp or hostLogin.aspx files and disconnect a 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 must be loaded outside the ApplinX Framework frameset.

Customizing the session ID

The required steps depend on whether you are using Natural for Linux® and Cloud or a different scenario.

To customize the session ID when running under natural for Linux and Cloud:
  1. Create new Java™ file under WEB-INF/contexts, for example, HostLogin.
  2. Implement the Java class as follows:
    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() {
        super.gx_onLoad();
    }

    public void doLogin() {
        super.doLogin();
    }

    @Override
    public void gx_initSessionConfig() {
        GXWebAppConfig gx_appConfig = getGXAppConfig();
        gx_appConfig.getSessionConfig().setSessionId(
            getTagsAccesor().getTagContent("GXUser")
        );
        gx_appConfig.getSessionConfig().setDescription("desc1");
        super.gx_initSessionConfig();
    }
}
  3. Edit hostLogin.jsp to use the new Java file by pointing the gx_page to the new class:
    <gx:page gx_context="contexts.aaa">
  4. Use the build script (make.sh) to recompile the class.
  5. Restart Tomcat and try again.

To customize the ApplinX session ID in another (non-natural/Linux) scenario:

  1. Go to the ApplinX web application folder.
  2. Edit the GXBasicContext.java file.
  3. In the gx_initSessionConfig method, uncomment the following line:
    gx_appConfig.getSessionConfig().setSessionId("<YOUR_SESSION_ID>");
  4. Change <YOUR_SESSION_ID> to the required value.
  5. Use the build script (make.sh) to recompile the class.

.NET configuration

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

  1. Click Click here for configuration details.
  2. Open Windows Explorer and right-click the config directory in the web application (<YourWebApp>\config).
  3. Select Sharing and Security, and then click Security tab.
  4. Click Add.
  5. If you are working with a network or active directory, you must change the location and select the server name or computer name.
  6. Add the IIS process user (typically called ASPNET) to the list of selectable object names. Click Check Names to locate the defined user.
  7. Click OK.
  8. Add Modify and Write permissions to the folder that contains the configuration files. Click OK.
  9. Restart IIS.
  10. Re-save your configuration in the Framework Configuration Editor.

For more information, see Configuring your web application.

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 matches the screen image; however another screen might be more suitable or identical to the screen image. Check the name of the screen which is on the screen image and verify that it matches the current screen. The name shown in the screen image indicates how the server identified the screen image based on all current screen definitions.

For more information, see Application map.

Troubleshooting connection pool issues

Table 1. Connection pools
Symptoms 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:
  • The connection is alive.
  • 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.
Note: When you record trace files to capture the symptoms as mentioned earlier, use the following variables in the trace file name: connection ID (%c), session ID (%u), and creation time of file (%t). For more information, see Recording Trace Files and Connection Pools.

Natural for Linux and Cloud APX component

To troubleshoot issues related to APX component functionality, enable tracing to monitor component activity. The APX daemon and the Natural application that uses the APX library can be traced independently. To determine which component activity to trace, use the following guidelines. If the issue appears to be related to connectivity between the ApplinX Server and the APX daemon, including authentication-related problems, enable tracing for the daemon component. For all other issues, enable tracing for the Natural application.

Note: Trace files should not be used on a regular basis in a production environment.
To trace the APX daemon:
  1. Go to the $NATDIR/$APXNODE directory.
  2. Edit the apxsrvd.sh file.
  3. Locate EXECUTABLE=apxsrvd and change it to EXECUTABLE=apxsrvd.tr.
  4. Define the following environment variables. The following example how to define them in sh or bash:
    > PT_TRACELEV=i6000 > SAGTMP=$HOME/tmp > export PT_TRACELEV > export SAGTMP
    The trace files are created in the $SAGTMP directory. In the previous example, this is $HOME/tmp.
  5. Restart the daemon by using one of the following methods:
    • By service name:
      > apxsrvd.sh servicename stop > apxsrvd.sh servicename start
    • By port number:
      > apxsrvd.sh portnumber stop > apxsrvd.sh portnumber start
To trace the natural application with the APX library:
  1. Go to the $NATDIR/$APXNODE directory.
  2. Edit the apx.sh file.
  3. Locate the following line:
    $NATDIR/$NATVERS/bin/natapx parm=$PARAMETERS etid=$$ >/dev/null 2>&1
  4. Change natapx to natapx.tr.
  5. Uncomment the TRACE section(by removing the # character from the beginning of the rows.

    The trace files are created in the $SAGTMP directory. By default, it is $HOME/tmp. The changes take effect the next time the application connects to the daemon.

For more information, see Installing APX Component for Natural Linux Protocol.

Error messages

Table 2. 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:
  • Missing or insufficient permissions
  • The host is offline.
  • Password expired (Natural for Linux and Cloud).
 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. Review the server launch config files (startup.bat or 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 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 it 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 infinite 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 ApplinX Designer
  • in the printer applet in the ApplinX Designer

For more information on how the response codes are organized, see Single Sign-on under AS/400.

Success response codes

Table 3. 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

Table 4. 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

Table 5. 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

Table 6. 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 unit 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.