Troubleshooting and reporting Communication problems
| Date: | Archived |
|---|---|
| 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 |
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.