Troubleshooting and reporting Communication
problems
| Date: |
10 September, 1998 |
| Product/Release: |
LANSA Open, LANSA For Windows Super Server |
| Abstract: |
A step by step guide to help determining the cause of a communications
problem and what information is required by LANSA Support when it comes to reporting such
a problem |
| Submitted By: |
LANSA Technical Support |
Detailed Description:
Refer to this guide every time a customer reports a communications problem.
Also distribute it to your customer base.
Step 0. Only valid when communications method used is either Enhanced APPC or
CPIC.
Before getting into verifying user profiles, finding job logs, etc., have a
quick look at the tables below depending on the communications method being used. Try to
find the return code and if found, verify the cause with your customer.
ENHANCED APPC return codes.
The following table covers the most common return codes issued with a communications
error code LCE0023 when using ENHANCED APPC communication method (i.e. Client/Access, PC
Support, Netsoft Router).
Table 1. ENHANCED APPC return codes.
| Hex value |
Description |
Cause |
| 1 |
Deallocation normal |
1. Partition doesn't exist or user not authorized for
partition. 2. File doesn't exist (at all or in a library in the library list) or
user not authorized for file.
3. Language used not defined in the partition. |
| 5 |
Resource failure retry |
PC has run out of memory. Confirm by opening a session with
no declarations. Reduce the number of applications loaded when the system starts. |
| 6 |
Resource failure no retry |
Likely to be caused by hardware failure. Check the
connections (cabling) between PC and AS/400. |
| 7 |
Unsuccessful |
The router has started the connection with one Host System
but the Host System name specified in either the LANSA.INI (HostSystem=) or LceUseSystem
points to a different one. |
| 8 |
APPC Busy |
Likely that two routers are active at the same time
(i.e. Netsoft and SNA Server). Use one at a time. |
| 1C |
Parameter check; bad partner name. |
1. The program is calling LceUseSystem with an incorrect
name. 2. LANSA.INI specifies an incorrect "Host System".
3. The router software is using a default system name which is incorrectly configured. |
| 14 |
Parameter check; invalid verb. |
An incorrect EHNAPPC.DLL may have been picked up. |
| 33 |
Allocation error; retry |
The Host system referenced in either LceHostSystem or in
LANSA.INI is "down" . |
| 35 |
Allocation error; transaction program name not recognized |
The LANSA Open invoke entry point program cannot be found: 1.
Check library list of job description has QGPL and LANSA program library.
2. Check that LCXP0010 is in QGPL. This program MUST exist in QGPL.
3. Check HostProgram= in LANSA.INI |
| 37 |
Security not valid |
1. Userid/password combination invalid (i.e. user profile has
not been defined in the AS/400 or incorrect password for userid). 2. Password in wrong
case, AS/400 requires uppercase passwords. |
| 46 |
Deallocation abend program |
1. LANSA program library not in user's job
description's initial library list. 2. When I/O module was compiled, settings
*IOMXSERVER, *IOMBLOCKBYKEY and *IOMBLOCKBYRRN were missing in DC@OSVEROP data area
(MCH0802 in joblog, see above). 3. Ensure a valid Superserver or Server
licence exists (with enough seats) if needed for the application being
used. |
| 48 |
Memory allocation error |
Insufficient DOS conventional memory to perform the task
being requested. PC Support loads TSR prior to starting Windows. When LANSA Open
calls
PC Support DLL running under Windows, PC Support needs additional conventional memory
(depending on function called) to communicate with TSR. Provide more DOS conventional
memory prior to running Windows. Closing other open Windows applications may also assist. |
| 49 |
Too many conversations |
The number of active communication sessions is greater than
the router can handle. Increase the appropriate parameter value in the router's
configuration or close any 5250 emulation sessions you may be running at the same time. |
| 63 |
Undefined |
1. The Host System name specified in either the LANSA.INI
(HostSystem=) or LceUseSystem is invalid. There is no Host defined with that name in the
routers configuration. 2. In 32 bit environments it can also be a result of typing the
Host System name in lowercase when using the L/Server configuration utility. Ensure the
Host System name was consistently typed using Uppercase characters everywhere it has been
entered.
3. If an application consistently fails after retrieving a certain amount of records
and CA/400 for Win95 is being run you may need a service pack. If running Netsoft
router v2.00, please upgrade to 2.11 or later. |
CPI-C return codes. Valid for LANSA Open, LANSA Client and LANSA for
Windows Super Server.
The following table covers the most common return codes issued with a communications
error code Lce0023 returned by LANSA Open when using CPI-C communication method (i.e. MS
SNA Server, Network Services for DOS, OS/2 Communication Manager). LANSA for Windows Super
Server returns the CPIC code and description (e.g. CM_PRODUCT_SPECIFIC_ERROR, error
code 20))
Note: LANSA Open always returns the error codes in hexadecimal format. The
documentation for CPI-C shows them in decimal format. Whenever receiving a Lce0023 using
CPI-C type of communications convert the hex code returned by L/Server into the
decimal format and then look in Table 2 (e.g.: LANSA Open returns Lce0023 return code
0x13. Look for 19 in Table 2)
Table 2. CPI-C return codes.
| Dec. value |
Return Code |
Cause |
| 6 |
SECURITY_NOT_VALID |
Userid/password combination invalid (i.e. user profile has
not been defined in the AS/400 or incorrect password for userid). No job could be started
on the Host, i.e. don't look for a joblog. |
| 17 |
DEALLOCATED_ABEND |
1.LANSA program library not in user's job
description's initial library list. 2. When I/O module was compiled, settings
*IOMXSERVER, *IOMBLOCKBYKEY and *IOMBLOCKBYRRN were missing in DC@OSVEROP data area
(MCH0802 in joblog, see above). 3. Ensure a valid Superserver or Server
licence exists (with enough seats) if needed for the application being
used. |
| 18 |
DEALLOCATED_NORMAL |
1. Partition doesn't exist or user not authorized for
partition. 2. File doesn't exist or user not authorized for file.
3. Language used not defined in the partition. |
| 19 |
PARAMETER_ERROR |
On the SNA Server, use SNA Server Admin. to add a LU6.2
partner relationship between the "Local LU" and "Partner LU" which has
a MODE of "BLANK". |
| 20 |
PRODUCT_SPECIFIC_ERROR |
Same as 19 (PARAMETER_ERROR) and also SNA Server not started. |
| 24 |
PROGRAM_ PARAMETER_CHECK |
Most likely the userid or password is more than 8 characters
long. SNA requires userid/passwords to be a maximum of 8 characters. |
| 26 |
RESOURCE_FAILURE_NO_RETRY |
Likely to be caused by hardware failure. Check the
connections (cabling) between PC and AS/400. |
| 27 |
RESOURCE_FAILURE_RETRY |
PC has run out of memory. Confirm by opening a session with
no declarations. Reduce the number of applications loaded when the system starts. |
Step 1. AS/400 HOST: verify the validity of your
user profile
LANSA Licence.
- Sign on as the AS/400 security officer. On the AS/400 command line
type <lansa program library>/lansa licence. Verify that the licence is still valid.
User Profile.
- Must be defined to the AS/400.
- Must be authorised to the LANSA partition being accessed.
Job Description.
- Use the command DSPUSRPRF to find out the job description (jobd) used
by your user profile.
- Use the command DSPJOBD to display the configuration of the job
description.
- The parameter INLLIBL (Initial library list) must have a library list
that includes the LANSA program library (usually DC@PGMLIB), QGPL and QTEMP specified.
- The parameter LOG (Message logging) must be at Level 4,
Severity 00 and Text *SECLVL (LOG 4 00 *SECLVL). This will ensure that a job log is
produced for all jobs started under user profiles using this job description.
Note: Depending on the LANSA product, the user profile can be
defined in different ways:
- LANSA for Windows Super Server. Check the value for the user=
parameter in the x_run command. If running from inside the LANSA for Windows development
environment (LANSA/PC), it will be the user currently being used (it will be
displayed in the
title bar).
- LANSA Open. It is passed using the LceUseUserId. Alternatively,
if using Enhanced APPC configure a default user id and password as part of the
host definition.
LANSA Client. It is the user id specified in the LANSA Client Administration utility for the Configured Host being accessed. Alternatively, if using
Enhanced APPC you may configure a default user id and password as part of the host
definition.
Test 1.
Sign on to an AS/400 terminal or 5250 emulator
using the same user profile as the one for the connection and on the AS/400 command line
type LANSA PARTITION(<partition name>) DEVELOPER(A). The LANSA for the
AS/400 main menu should
be displayed. Now, type DSPLIBL. QGPL and QTEMP should appear in the resulting library
list.
WHEN REPORTING TO LANSA SUPPORT: Clearly state that this test has
been successfully completed.
Step 2. AS/400 HOST: Make sure that the Listener and session jobs are running (only
valid when running TCP/IP).
The commands WRKACTJOB or WRKSBSJOB can be used <subsystem
name>. If either the Listener or session jobs are not active, the options are they have
not been started or they have failed to start. (re)-Submit the Listener and from either
WRKACTJOB or WRKSBSJOB <subsystem name> screens watch it start. If it starts and
then abends, refer to the next step in order to find the job log of the failed Listener
startup.
WHEN REPORTING TO LANSA SUPPORT: Clearly state
that both the Listener and session jobs have been checked and are running or attach the job log
of the failed jobs.
Step 3. AS/400 HOST: find the job log.
Provided Step 1 has been successfully verified, the next step is to locate and analyse
the job log. For each attempted remote connection an AS/400 job will be started on a
specific subsystem. When that job ends, a spool file named QPJOBLOG will be created in a
queue named QEZJOBLOG.
Test 2.
Run the application. Immediately after if
fails, use the command WRKOUTQ QEZJOBLOG, and press F18 to go to the bottom of the list.
When using TCP/IP, the session jobs are not started under the user profile who is actually
running the application but under the user profile who started the Listener job. In that
case, the same applies to the QPJOBLOG spool file.
Test 3.
If no job log appears to have been produced,
use the command WRKSBSJOB <subsystem name> or WRKACTJOB and scroll down
until the subsystem can be seen. Run the application and immediately press F5 to Refresh the list of
jobs for the subsystem. If absolutely sure that no new jobs are started in the
subsystem then the process is not getting as far as starting a task or session
on the
AS/400. Refer to the next step.
WHEN REPORTING TO LANSA SUPPORT: Whenever a
job log is found attach THE COMPLETE job log to your support request. Do not cut
and paste the parts considered relevant into an e-mail message. Only if the job log has
many pages (e.g. more than 10) should they be reduced to the ones considered
most important.If no job log was found, clearly state that in the support request.
Step 4. AS/400 HOST: Tracing options. (SKIP THIS STEP
UNLESS SPECIFICALLY REQUIRED BY LANSA SUPPORT)
Tracing at the communications level is only available when using
TCP/IP.
Test 4:
- Sign on to the AS/400
as the security officer.
- On the AS/400 command line, type <lansa program
library>/lansa configure.
- Select COMMS_EXTENSIONS
- Select COMMS_DEFINITIONS and write down the qualified name for
the location of the trace file (default QGPL/LCROUT.TRC).
- Select COMMS_FACILITY_TRACE. If required, press F6 subsequently
to add faclity modules CPIC MANAGER, IPC MODULES, LISTENER and TP STUB. For each of the
modules created, select option 2=Review/Change and turn tracing on Errors, CPIC Data,
External IPC Calls, Calls to CPIC, System Info and Internal IPC Calls.
- Select COMMS_LISTENER_RECS. If required, press F6 to add faclity
SOCKET. Select option 2=Review/Change and refer to previous point for tracing options to
turn on.
- Stop and re-start the Listener, make sure they start (refer to
previous step).
- Run your application. After it fails, locate the trace file and
examine it.
- When the tests have finished, turn the tracing options back
off, stop and restart the Listener. It is not necessary to delete the facility modules
created.
WHEN REPORTING TO LANSA SUPPORT: attach the
trace file to the LANSA Support request.
Step 5. PC: tracing options
Tracing at the communications level is only available when using
TCP/IP.
Test 5.
- Start the LANSA
Communication Administrator (LCA). Write down the Communications Route Table Path,
the file LROUTE.DAT should be attached to the support request.
- In the Advanced pull down menu, select Module Log and Trace.
- Select CPIC Manager, click on Edit and turn tracing initially on
Errors, Calls to CPIC and Internal IPC Calls. Write down the trace file path
- Repeat the previous step for the module IPC Modules.
- Make sure no previous trace file exists on the PC (see trace
file path). If there is one, delete it.
- Run your application. WHEN IT FAILS, EXIT OUT OF YOUR PC
APPLICATION.
- Locate the trace file and examine it starting
from the bottom. Make sure an Error has been
outputted to the trace file. If the error is
reported as a Native Error: 10nnnn, refer to a
sockets Web site for a description of the socket
error.
WHEN REPORTING TO LANSA SUPPORT: attach the
trace file and the route table file to the LANSA Support request.
|
