Any errors which occur while using Remote IMS are displayed in a popup window. The popup contains the same information whether you are running the Remote IMS Test program or a DL/I application program. The popup contains a description of the error. In many cases it also suggests how to correct the problem. For many of the errors you are likely to encounter, this is all the information you need to resolve the problem.
To identify and correct some SNA communication errors, you may need to use tools supplied by your communications product vendor. The CPI-C interface only provides a general error code. The return code is shown on the popup but it may not be enough information to resolve the problem. This is particularly true when using a Generic communications product. For the built-in communication products, we can provide specific suggestions on the popup because of our experience with these products. We can only provide general suggestions for the Generic products.
The information displayed on the popup is all of the information supplied by the CPI-C interface to the Requester. There is not a great deal of information so careful installation and configuration of communications is your best approach for minimizing errors. Also, the corrective actions given are just guidelines. Many of them say "generally indicates" or "may be caused by" for good reason. In theory, the return codes provided should point to a specific error, however, in practice we have found them to be less than perfect, especially when the communications setup is not yet defined correctly.
If you suspect a communications problem but cannot determine the cause of a problem you may need to run an SNA trace. Your PC communications product probably provides a trace facility. If the PC SNA trace isn't adequate you can also run a VTAM trace with assistance from your mainframe systems' personnel. The key piece of information from the trace is the SNA "sense data". The sense data provides very specific error descriptions. See your respective communication product's manuals for tracing instructions and the meaning of sense codes. Some communication products also contain error logs. More detailed information, including the SNA sense data, may be included in these error logs without having to run a trace. For example, SNA Server's client on NT writes errors to the NT Event Viewer. You should look there first before running a trace.
The other tools which can be useful are the operator services. Vendors call their tools by various names such as management tools or administration tools. However they all provide the same basic functions. They enable you to view and control APPC Transaction Programs, LUs, links or connections, sessions and conversations. For additional information see the section Using Communication Product's Operator Services in the chapter Communication Details.
If APSB is listed as the "Function" in the popup, it indicates a failure of the APSB call that the Server issued in order to schedule the PSB. The APSB call is issued using the AIBTDLI call interface. The AIBTDLI return and reason codes are shown in the popup. A short description of most of the error codes is also shown. See your IMS/ESA manuals for a complete description.
Note: DPSB (deallocate PSB) call failures are reported in a similar manner but as they are likely to be the result of a Requester or Server programming error, they should not occur.
There are various reasons why the APSB call on IMS/ESA might fail, some of which are shown below. The corrective action for most of these should be straightforward. For example:
The table below lists the AIB return/reason codes for some APSB failures:
| Reason Code |
Description |
|---|---|
| X"0108"/X"0304" | PSB is not found |
| X"0108"/X"0308" | PSB authorization failure |
| X"0108"/X"0314" | PSB is already scheduled |
| X"0108"/X"0318" | PSB is stopped |
This section provides help with identifying and correcting communication errors when using the Generic communications support. The popup errors for the built-in products provide general and product-specific assistance in the text on the popup. This section also gives a more detailed explanation of various errors in case the suggestions on the popup are not adequate to resolve the problem.
The popup error message has the same general format. The information is also written to the IMS System Log file named imsmto.log. See the section IMS System Log in the chapter IMS Option Administration Information in your Administrator's Guide. Use the Function, CPI-C Call and RC values to find a possible match in the following section.
In the upper left corner of the popup there is an ID of RMTERR. Its format is:
<title>
Function: xxxxxxxx
Servername: xxxxxxxxxxxxxx
CPI-C Call: xxxxxx RC: xxxx/xxxxxxxxxxxxxxxxxxxxx
PSB: xxxxxxxx DBD: xxxxxxxx Server Type: xxxxxxxx
<hint line 1>
<hint line 2>
<hint line 3>
<hint line 4>
where:
| Parameter |
Description |
|---|---|
| <title> | A general description of the error. For example: Error processing DL/I call - communications error. |
| Function | The function being performed. For example, the database call being issued (GU, ISRT, etc.), Sched-PSB, ROLLBACK, etc. The function may be a symbolic identifier of a Requester function. The Function is used with the CPI-C Call and RC to help identify errors. |
| Servername | The ServerName setting in the rmtims.ini file. |
| CPI-C Call and RC | The CPI-C call which failed and its return code. After the return code is a short description of the return code. |
| PSB, DBD and Server Type | For reference only. They are the PSB
and DBD from the application using Remote IMS. Server Type is always
MVSIMSTM. There are other values for server type but these are for
internal use only. When running the MFRMTTST test program, this line is not shown. |
| <hint lines> | Suggestions for correcting this specific problem, if any. In some cases this area may just contain a more detailed explanation of the problem. |
| Error |
Description |
|---|---|
| CPI-C call: CMINIT RC: 0020 FUNCTION: any |
A return code of 20 with this call generally indicates that the communications product has not been started. It can also mean the communications product could not initialize properly. This could be caused by an incorrect installation of your communications product. For SNA Server on Windows 95 and NT clients it starts automatically so this error is not likely to occur. If it does, check that the SNA Server-name configured for the client matches the name on your SNA Server. |
| CPI-C call: CMINIT RC: 0024 FUNCTION: any |
This error generally indicates that there is no CPI-C Side File defined. There must be a CPI-C Side File which matches the name specified in the rmtims.ini file's CpicSideFile setting. See the section CPI-C Side File in the chapter Configuring PC Communications for more details. A less likely cause is that a parameter in the Side File is not valid. Usually the parameters are validated later with the CMALLC call but some parameters may be checked during the CMINIT call. For example, if the partner LU specifies an LU alias but the alias is not defined on that machine it may result in an error during CMINIT. For SNA Server clients it can also mean there is no outgoing APPC LU available on the SNA Server. See the section Microsoft SNA Server in the chapter Configuring PC Communications for an explanation of SNA Server's APPC LU support. |
| CPI-C call: CMALLC RC: any FUNCTION: any |
Errors on the CMALLC call result from
the local communications product trying to create an LU 6.2 session to
the partner system. An LU 6.2 session must be established prior to
creating a conversation between the Requester and the Server. See the
section LU
6.2 Session vs. Conversation in the Communication Details
chapter for an explanation of sessions and conversations. A failure to establish a session can often be a communications configuration error - possibly some kind of parameter mismatch between the local and partner systems. For example, the mode-name used in the local communication product is not defined on your mainframe system. CMALLC errors can also result from APPC/MVS or IMS/APPC not being started. Some suggestions are provided in the popup for these errors for all communication products. The suggestion depends on which specific error code was returned. If this is not enough to resolve the problem you need to review your communication product's error log or run a communications trace. |
| Note on CMINIT and CMALLC | CMINIT and CMALLC call failures are a strong indication that something is wrong in the communications definitions. These are the first two CPI-C calls made by the Requester. Once you get past these errors, almost all other errors appear with the CPI-C call of "CMRCV" (CPI-C Receive). The Requester uses "buffered send data" mode for performance reasons so even errors sending messages are reported on the subsequent receive that it issues. |
| CPI-C call: CMRCV RC: 0021 RC:0022 RC:0023 FUNCTION: XCHG-CFG |
These three error codes, when occurring during the "XCHG-CFG" function during conversation initialization, indicate that IMS/ESA (or possibly APPC/MVS) has rejected the APPC session or conversation for some reason. The most likely cause for these error values is that the trancode on IMS/ESA is stopped. Use the "/DIS TRAN name" IMS command to check its status and start it if needed. |
| CPI-C call: CMRCV RC: 0002 RC:0011 FUNCTION: XCHG-CFG |
These two error codes indicate "retry possible". These generally mean that the communications configuration is correct but some temporary condition prevents the session or conversation from being established, for example, a communications line is down. These return codes are just guidelines and are only indicating that a retry is possible. There may be situations where operator intervention is required before it can succeed. If a "retry" return code persists and you are uncertain of your communications definitions, you should review them carefully. Also review the communication product's error log or run a trace. |
| CPI-C call: CMRCV RC: all others FUNCTION: XCHG-CFG |
Any other return codes during XCHG-CFG than those just described mean the session or conversation could not be established for some other reason. These are the most likely errors when initially setting up your communications definitions. The description of the return code may help you to isolate the area of definitions with the problem. If not, carefully review your communications definitions. Also review the communication product's error log or run a trace. |
| CPI-C call: CMRCV RC: 0002 RC:0011 FUNCTION: all but XCHG-CFG |
When these "retry possible" errors occur after the conversation is established they mean that something has failed but that a conversation may be re-established if you retry. When these occur, the Requester cannot automatically retry the conversation since the failure would have caused backout processing on the Server. IMS Option needs to be notified of the error so it can backout all other managed resources. You could retry by restarting IMS Option and re-executing the failed application. |
| CPI-C call: any RC: 0020 FUNCTION: any |
A return code of 20 is a product specific
error. See the CMINIT error 20 for possible causes with that call. For
all other CPI-C calls you need to review your communication product's
error log. Check your vendor's documentation and knowledge bases for
assistance. For example, with SNA Server knowledge base, article
Q132720, provides suggestions. See the section SNA
Server in this chapter for more information. You can also try
running a trace. |
Communication failures between the Requester and Mainframe Manager typically surface on the client as a CCI Timeout popup error message. This can happen for several reasons such as:
Configuration errors in Mainframe Manager usually surface on the client as a popup error message "603 Invalid response from Mainframe Manager ALLOCERROR" followed by an RPL Code." The Requester interprets some RPL Codes and provides text descriptions. Others result in the just the 8 digit return/reason code. Probable causes for error message 603 are:
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.