This document provides troubleshooting advice for various ApplinX topics:
See also Troubleshooting in document Upgrading, Migrating and Installing Fixes.
This section covers the following topics:
See Web Application Development for introduction and concepts, and Error Messages for troubleshooting help.
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.
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.
The JavaScript logger engine automatically logs JavaScript errors to a log text file on the server (logs/javascript_log.txt).
Note:
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.
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:
<engineConfig 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 />
Note:
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 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;
doSomthing(myBool);
if (!myBool){
GXLog.debug("myModule","Something went terribly wrong!!");
}
return myBool;
}
Ensure to set the config/gx_clientConfig.xml as detailed above.
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.
To define the messages that will be displayed in the framework
log:
Open config/gx_logConfig.xml.
Uncomment the following section:
<!--category additivity="false" name="<Category-Name>"> <level value="info"/> <appender-ref ref="FRAMEWORK_LOG"/> </category -->
<!-- logger additivity="false" name="<Category-Name>"> <level value="info"/> <appender-ref ref="FRAMEWORK_LOG"/> </logger -->
Change the level tag value to either: info, error, warning, or debug.
Change the <Category-Name> to a meaningful value. This will make it easier for you to find log entries at a later time.
Restart your web server, in order for the changes to take effect.
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):
GXLog.info("Category-Name","<Message>");
GXLog.error("Category-Name","<Message>");
GXLog.warning("Category-Name","<Message>");
GXLog.debug("Category-Name","<Message>");
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.
The necessary steps depend on whether you are using Natural under UNIX or another scenario.
To customize the session ID when running under Natural UNIX
Create new Java file under WEB-INF/contexts - we called it "aaa" in this example.
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() {
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();
}
Edit the hostLogin.jsp to use this new Java file, by pointing the gx_page to the new class <gx:page gx_context="contexts.aaa">.
Use the build script (make.sh) to recompile this class.
Restart Tomcat and try again.
To customize the ApplinX session ID in another (non-Natural/UNIX) scenario
Go to the ApplinX web application folder.
Edit the GXBasicContext.java file.
In the gx_initSessionConfig method, uncomment the following line:
gx_appConfig.getSessionConfig().setSessionId("<YOUR_SESSION_ID>");
Change <YOUR_SESSION_ID> to the required value.
Use the build script (make.sh etc) to recompile this class.
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:
Click on Click here for configuration details.
Open Windows Explorer and right-click on the config directory in your Web application (<YourWebApp>\config).
Select and then select the tab.
Click .
If you are working with a network/active directory, you need to change the location and select the server name/computer name.
Add the IIS process user, typically called ASPNET, to the list of object names that it is possible to select. Click to locate the defined user.
Click
Add Modify and Write permissions to the folder where the configuration is located. Click
Restart IIS.
In the Framework Configuration Editor, re-save your configuration.
See Configuring your Web Application for more information.
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.
| 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:
|
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 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.
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.
To trace the APX daemon
Go to the $NATDIR/$APXNODE directory.
Edit the apxsrvd.sh file.
Find EXECUTABLE=apxsrvd, and change it to EXECUTABLE=apxsrvd.tr
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.
Restart the daemon:
> apxsrvd.sh servicename stop > apxsrvd.sh servicename start
or
> apxsrvd.sh portnumber stop > apxsrvd.sh portnumber start
To trace the Natural Application with the APX library
Go to the $NATDIR/$APXNODE directory.
Edit the apx.sh file.
$NATDIR/$NATVERS/bin/natapx parm=$PARAMETERS etid=$$
>/dev/null 2>&1
Change natapx to natapx.tr
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.
See Web Procedures for more information.
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:
The XPath defined may not capture the correct element. Run the procedure from within the Designer and follow the output in the Console area.
Refine the XPath to make it more robust. Refer to What is an XPath?
Change the ApplinX Server log level to "trace" to help you understand where the problem may lie.
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.
<MainConfiguration>
...
<ServerConfiguration>
...
<webProcedureConfig>
<waitElementTimeout>30000</waitElementTimeout>
<navigationTimeout>90000</navigationTimeout>
<javascriptTimeout>30000</javascriptTimeout>
<cssEnabled>false</cssEnabled>
</webProcedureConfig>
</ServerConfiguration>
</MainConfiguration>
| 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: |
|
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. |
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.
| 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. |
| 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. |
| 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. |
| 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. |