This section provides information on how to diagnose and solve problems. For the latest information on known problems and their solutions go to LANSA web site.

In general, you should follow the same diagnostic process as you would for any IBM i application.

Check the job log of the problem job.	The problem job could be an interactive job running a command, a batch job started by a command, or a batch job started by another batch job. Use the Display Job Log (DSPJOBLOG) command.
Check the job log of the parent job.	The parent job could be an interactive job running a command, or a batch job starting another batch job. Use the Display Job Log (DSPJOBLOG) command.
Check the job log of the child job.	The child job could be a batch job started by a command, or a batch job started by another batch job. Use the Display Job Log (DSPJOBLOG) command.
Check the system operator's message queue	Check QSYSOPR for relevant messages. Use the Display Messages (DSPMSG) command.
Check the history log	Check QHST for relevant messages. Use the Display Log (DSPLOG) command.

Specific information for troubleshooting the various parts of aXes Server can be found in the following sections:

• Browser Problem Analysis
• Configuration File Problem Analysis
• aXes Terminal Server Problem Analysis
• aXes Application Server Problem Analysis
• Document Access Problem Analysis

Browser Problem Analysis

Browser problems usually manifest as an incorrect terminal display. Either data is missing from the terminal display or an error occurs.

Firstly, ensure that the browser is a supported version. Depending on your version of aXes please refer to the relevant section of the supported software on the https://www.axeslive.com website.

Some common problems and suggestions for resolving them follow:

Logon Script not found

This means the axlogin.mjs file was not served by the host.

Check that the file exists.

If you are using the aXes Application Server then check that AXES has authority to the full file path.

Check that a firewall or proxy is not blocking the request. This includes personal firewalls such as ZoneAlarm.

This problem is frequently caused by HTTP/1.0 proxy servers and is known to occur with the Avirt Gateway and WebMarshal proxy servers. In this case you should change your browser settings to select the “Use HTTP 1.1 through proxy connections” setting. This option is found under the Tools->Options panel on the Advanced tab in the HTTP 1.1 settings section.

Sometimes this problem is caused by an error in the caching support provided by Internet Explorer. Try requesting the page directly by using the URL http://system:port/axests/axlogin.mjs where ‘system’ and ‘port’ are appropriate values for your environment.

You may also need to clear the cache by getting Internet Explorer to delete temporary files, close all browser windows, and start the aXes Terminal Server session again.

Previously seen screens redisplayed

This problem usually indicates a caching error in Internet Explorer. Ensure your browser settings allow Internet Explorer to automatically determine whether it should check for newer versions of cached pages. This option is found under the Tools->Internet Options panel on the General tab in the settings for the Temporary Internet files section.

Open terminal failed

This error can be caused by a number of things:

• The virtual device you requested is disabled.
• The QAUTOVRT system value is set such that virtual devices cannot be created.
• The IP address of the client is specified on the IPMask= directive in the aXes-TS configuration file.
• The entry in the User section of the aXes-TS configuration file is incorrect.
• The tslogonexit.lua script has rejected the logon request.
  
  • A problem occurred running the AXRTVVTDEV program:
  • Check that the program exists in the product library
  • Check that it is a system state program

If you are using the aXes Application Server then check that AXES has authority to the program.

If the message is due to a failure when opening a virtual terminal then the API message will also be displayed.

Internal system error occurred in program QTVSINIT

This error indicates a virtual device problem. Examine the job log of the AXES5250 job. It will provide more information about the cause of the problem. Follow any recovery steps described in the job log messages. Errors of this type are not usually aXes problems. They usually indicate an operating system problem of some sort such as device in use, device not available, device varied off, etc. Follow the normal recovery steps you would perform for device error recovery. These include varying off and on the device, deleting the device, checking authority to the device, etc. The recovery steps described under “Open terminal failed” may also prove helpful for this problem.

Unexpected internal system error occurred in program QTVWRTVT

This error indicates a virtual device problem. Examine the job log of the AXES5250 job. It will provide more information about the cause of the problem. Follow any recovery steps described in the job log messages. Errors of this type are not usually aXes problems. They usually indicate an application problem of some sort such as incorrectly using pop-up windows.

If the job log of the AXES5250 job shows message CPF87D4 “Data sent exceeded the corresponding I/O request” then the problem is most likely caused by the way the application handles pop-up windows. When a window is displayed by an application, the default behaviour is for the operating system to issue a request to save the current screen. When aXes Terminal Server receives this request it returns a representation of the current screen to the operating system. The operating system rejects responses that exceed 16KB. In some cases the representation of the screen used by aXes Terminal Server will exceed 16KB. Panels that contain lots of data and fields, such as very full 27*132 panels, can cause this limit to be exceeded. It can also be caused by the application displaying many windows on top of each other.

The reason the aXes Terminal Server screen representation may exceed 16KB is because aXes Terminal Server saves the complete creation data for the current screen where 5250 emulators just save the visible data. aXes Terminal Server needs to save everything to support future enhancements. Thus the more data in each panel, and the more windows on the screen, the more likely that a Save Screen request will cause the 16KB limit to be exceeded.
In most cases the default Save Screen request is not necessary because the application does not allow the operating system to restore the saved screen. Most applications cause the screen to be redrawn by reissuing the various WRITE commands for the record formats that make up the current screen once the window has been closed.

To correct the problem the application should exercise better control over whether a Save Screen request is issued by the operating system. For window record formats the Save Screen request can be controlled by specifying the USRRSTDSP keyword on the WINDOW record. For other record formats ensure the display file has RSTDSP(*NO) specified.

Because the root cause of the problem is directly related to the amount of data present in the screen being saved the problem can be avoided by making screens less cluttered with information. Perhaps the screen would be better designed as two or more panels with less useful information on the subsequent panels.

Logon fails

This message can appear when signing on to aXes Terminal Server using a skin that shows the spooled output tab (such as /ts/skins/ts.html). In this case it usually means the aXes Spool File Server is not licensed for this system therefore the automatic logon to aXes Spool File Server has failed. In this case use a skin that does not include spooled output such as /ts/skins/ts_basic.html

400 Bad Request

This error can be caused by a number of things:

• A problem occurred with the virtual device. See Open terminal failed above.
  A time-out occurred between aXes Application Server and aXes Terminal Server. Check that both servers are active and that the value for TSInactiveLimit directive in the TS configuration file is less than the value specified for –idle-timeout on the FastCGIServer directive in the W3 configuration file.

URL http://system:port/axests/0 displayed but no terminal frame visible

This means the POST of data to the server failed so no POSTed data is available.

Check that POST is not disabled in the server configuration file.

Check that you have the correct level of browser and MSXML support.

Check that a firewall or proxy is not blocking the request. This includes personal firewalls such as ZoneAlarm.

Check that the URL is not being redirected.

Error loading transaction

The following was returned in place of an XML document:

400 Bad Request

Because this is an HTTP error message you should follow the normal web server diagnosis for HTTP errors.

This message indicates the host could not satisfy the client request. It is usually caused by a time-out between the aXes Application server and the aXes Terminal Server due to the aXes Terminal Server taking too long to respond to the client request.

The time-out can be caused by excessive network traffic, by network configuration issues, or by the host system simply being too busy to respond in a timely manner.  In some cases it can be caused by inappropriate workload such as long running queries being invoked from the client session. To recover just close the XML error window and issue the request again.

If the problem persists you will need to determine the cause of the delay. You can increase the amount of time aXes will wait for responses. Try increasing the wait time specified for the –idle-timeout switch on the FastCGIServer directive in the W3 configuration file. Depending on the cause of the error you may also need to increase the value for the TSInactiveLimit directive.

Error loading transaction

The following was returned in place of an XML document:

Server Error!

The red box may contain web server diagnostic information such as:

• The server encountered an internal error and was unable to
• Complete your request. Either the server is overloaded or
• There was an error in a CGI script.

If you think this is a server error, please contact the webmaster.

Error 500

Apache/2.0.47 (Linux/SuSE)

In this example the error message came from an Apache web server running on SuSE Linux therefore investigation of the problem should start with Apache. This problem may be a time-out similar to that described above under 400 Bad Request or it could be something specific to Apache.

Error loading transaction

The following was returned in place of an XML document:

The XML page cannot be displayed

This message indicates the client did not receive an XML document from the host. The red box may contain additional information about the problem.

This error does not necessarily indicate a problem with aXes Terminal Server. This sort of error can happen for many reasons. It may indicate a network problem, a firewall problem, a proxy server problem, or a time-out. It is simply part of using

a browser and web server. To recover just close the XML error window and issue the request again.

Ensure the network path between the browser and application server is correctly configured.

If the problem persists you will need to determine the cause. See other “Error loading Transaction” topics in this section for additional possibilities.

Error Loading Transaction

Cannot view XML input using XSLT style sheet

This message indicates that the MSXML parser is either not available or at the wrong level.  The red box may contain additional information about the problem. Ensure that MSXML3 or Service Pack 1 is installed for IE6.0

If you do not have MSXML3 you can get download it from http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=c0f86022-2d4c-4162-8fb8-66bfc12f32b0.

Be aware that many applications ship MSXML3. Accidentally uninstalling any one of those applications on a Windows system could potentially deregister the MSXML3 program files (msxml3.dll and msxml3r.dll). The visible effect of doing this

is that MSXML3 appears to no longer be installed or available but its program files still remain in the Windows system folder.

If you experience problems attempting to use MSXML 3.0 SP4 after removing an application that might have been using it then you can fix this by repeating the registration of msxml3.dll on your system.

To register MSXML 3.0

1. From the Start menu, click Run.

2. Enter the following command:

regsvr32 %windir%\system32\msxml3.dll

3. Click  OK.

If the registration is successful, you should see a message box displaying a message similar to the following:

DllRegisterServer in C:\WINDOWS\system32\msxml3.dll succeeded.

This problem is also frequently caused by HTTP/1.0 proxy servers and is known to occur with the Avirt Gateway and WebMarshal proxy servers. In this case you should change your browser settings to select the “Use HTTP 1.1 through proxy connections” setting. This option is found under the Tools->Internet Options panel on the Advanced tab in the HTTP 1.1 settings section.

This problem may also be caused by checking the "Do not save encrypted pages to disk" setting. This option is found under the Tools->Internet Options panel on the Advanced tab in the Security section.

Raw XML is displayed in the browser

If a panel much like the following is displayed when loading the terminal it usually indicates that the MSXML parser is either not available or at the wrong level. This can be caused by not having MSXML installed, by installing another product that disables MSXML, or by uninstalling a product that removes the MSXML registry entries.

The cause of this problem and the recovery process is the same as for the previous error.

The XML page cannot be displayed

Cannot view XML input using XSL style sheet

Please correct the error and then click the Refresh button, or try again later

Error while parsing “https://system:port/ts/skins/my_login.xml”.

No data is available for the requested resource

This message, or similar, indicates the client did not receive an XML document from the host or the XML document cannot be parsed.

Follow the instructions for the “Error loading transaction” topics with similar titles in this section for recovery.

Message “CPF1296 – Signon information required.” displayed

This message is usually caused by a customized sign-on display where the row and column order has changed the relative positions of the fields. The aXes terminal has a temporary restriction which requires that the IBM supplied input-

capable fields must be specified with row and column values such that the fields are present in the following order.

• USERID
• PASSWRD
• PROGRAM
• MENU
• CURLIB

You may change the row and column positions for these fields but USERID must always be prior to PASSWRD, and PASSWRD must always be prior to PROGRAM, and so on, even when some fields (such as PROGRAM, MENU, or CURLIB) are non-display fields.

Do not confuse row and column position with buffer position.

IBM requires that you must not change the buffer position when altering the sign-on screen but you can change the row and column positions of the fields.

aXes Terminal Server requires that the row and column positions you use do not alter the relative positions of these fields.

Other errors

If the previous information does not help you solve your problem you can obtain additional diagnostic information about the terminal session from the Help->Diagnostics menu in the terminal session menu bar.

Configuration File Problem Analysis

Configuration file entries that are incorrect will cause a message to be sent to the job log of the server job indicating the problem. Read the second-level help for the message and correct the directive in error. Stop and restart the server.

aXes Terminal Server Problem Analysis

If the aXes Terminal Server was started using the STRAXESTS command, or by an aXes Application Server instance, or automatically when the AXES subsystem was started, the server jobs run under the AXES user profile. You can find these jobs by using the WRKUSRJOB USER(AXES) command.

If the aXes Terminal Server will not start the most likely cause is that the required TCP/IP port is in use by another process. Determine the port number and host identifier (IP address or host name) from the appropriate configuration file. Each server must use a unique combination of host and port. Use the NETSTAT OPTION(*CNN) command to check if the port is in use.

Always check the job log of the server job for error messages—even if an error message is displayed at the client there may be more detailed information in the server job log.

If the information in the job log is not sufficient to determine the cause of the problem then tracing can be activated to get low-level detail about the server process.

Tracing is activated by adding the Trace=1 directive to the aXes-TS configuration file and then starting the server. The diagnostic trace is written to the <log-path>/.aXesTStrc.txt file. The log-path can be controlled by specifying the LogPath= directive. For example:

LogPath=/logs/mylogs

The trace data detail can be controlled by specifying the TraceLevel= directive. This directive takes a list of options. For example:

To log Informational messages, specify: TraceLevel=Info

To log Warning messages, specify: TraceLevel=Warn

To log Error messages, specify: TraceLevel=Error

To log all messages, specify: TraceLevel=Info Warn Error

The TraceLevel= directive also causes the messages to be sent to the job log.

Message CPF1151 when starting the server

This means a library exists in both the system portion of the library list and the user portion of the library list. It is usually caused by specifying QTEMP in the QSYSLIBL system value. A work-around is to remove QTEMP from the AXES job description. Use the Change Job Description (CHGJOBD) command to do this.

aXes Application Server Problem Analysis

If the aXes Application server was started using the STRAXESW3 command the server jobs run under the AXES user profile. You can find these jobs by using the WRKUSRJOB USER(AXES) command.

If the aXes Application Server will not start the most likely cause is that the required TCP/IP port is in use by another process. Determine the port number and host identifier (IP address or host name) from the appropriate configuration file. Each server must use a unique combination of port and host. Use the NETSTAT OPTION(*CNN) command to check if the port is in use.

If the information in the job log is not sufficient to determine the cause of the problem then tracing can be activated to get low-level detail about the server process.

Tracing is activated by adding the Trace=1 directive to the aXesW3 configuration file and then starting the server. The diagnostic trace is written to the <log-path>/.aXesW3trc.txt file. The log-path can be controlled by specifying the LogPath= directive. For example:

LogPath=/logs/mylogs

The trace data detail can be controlled by specifying the TraceLevel= directive. This directive takes a list of options. For example:

To log Informational messages, specify: TraceLevel=Info

To log Warning messages, specify: TraceLevel=Warn

To log Error messages, specify: TraceLevel=Error

To log all messages, specify: TraceLevel=Info Warn Error

The TraceLevel= directive also causes the messages to be sent to the job log.

Message CPF1151 when starting the server

This means a library exists in both the system portion of the library list and the user portion of the library list. It is usually caused by specifying QTEMP in the QSYSLIBL system value. A work-around is to remove QTEMP from the AXS job

description. Use the Change Job Description (CHGJOBD) command to do this.

Document Access Problem Analysis

When using the aXes Application Server:

Verify that *PUBLIC has read (*R) authority and does not have execute (*X) authority to the data files being served.

Verify that *PUBLIC has execute (*X) authority and does not have read (*R) authority to scripts being run.