This document is designed to assist the system administrator to verify that Con-nect SNADS has been installed properly.
Although the following procedures are not the only means of verification and problem analysis, the intent here is to provide the administrator with some guide lines that will insure that the system is operational.
This document covers the following topics:
The asynchronous server programs are the Con-nect SNADS implementation of DS_ROUTER_DIRECTOR, DS_SEND and DS_RECEIVE. Although any of the three programs may not run for a common reason, the procedures for installation, verification and problem analysis vary from program to program. See the Con-nect Administration documentation, section Con-nect SNADS, sub-section Implementation of Con-nect SNADS for a brief description of these programs.
Before testing DS_ROUTER_DIRECTOR and/or DS_SEND, set all Con-nect SNADS queues to manual operation as described in Installation Steps for Com-plete, Installation Steps for Batch Mode , or Installation Steps for CICS. For example, set the Reset Status for inbound and all outbound queues to I (inactive) and change the status to output by marking the "Reset Status" field in the "Queue Info" screen (do not use the timer driven scheduling (T) unless you are certain that the system is completely operational). Verify that the input status is active.
Using the Con-nect Send function, send a message to a SNADS addressee. The status message "Waiting for Distribution" appears in your Outbasket along with the list of addressees. The actual message sent appears as an item in the Con-nect SNADS inbound queue. You can begin testing at this point.
Note:
If testing must be interrupted, re-establish the inactive status for
inbound and outbound queues.
Initialize the inbound queue (using the DS_ROUTER_DIRECTOR program) from the "Queue Maintenance" screen. Observe the number of items in the queue and the changes in the output status associated with this queue by occasionally pressing ENTER.
If the system is running properly, the following sequence of events occur:
The output status of the queue changes from I (inactive) to "scheduled" (indicated by a blank). When the status changes to "scheduled", the end-user task issues a CICS START command which invokes the DS_ROUTER_DIRECTOR program but does not activate it.
The output status of the queue changes from " " (scheduled) to A (active). This status change is made by the DS_ROUTER_DIRECTOR program when executed.
The number of items in the queue is decremented to 0. If the items in the queue are addressed to multiple addressees, the queue items appear as members of the outbound queues. The items do not appear in the outbound queues if the only specified SNADS addressee is a local Con-nect user or if the specified addressee DSUN could not be matched to a SNADS routing entry.
The output status of the queue changes back to I when the DS_ROUTER_DIRECTOR completes its execution.
A sequence of events which does not follow the above indicates a problem with the installation of Con-nect SNADS, usually resulting in one of two events:
The queue output status changes to H (held) which indicates that Con-nect SNADS detected a fatal error (e.g. a program check during execution). If this occurs, check the Con-nect SNADS log records for further information.
If the problem is a Natural error condition, it appears in the log records as a message that originates from the X-FE program. This message contains the Natural error number, line number and the name of the affected Natural program which runs in conjunction with Con-nect SNADS.
The queue output status changes from I (inactive) to " " (scheduled) but the system is "hung". A hung system indicates that an error occurred before the DS_ROUTER_DIRECTOR program was initialized properly. See Problem Analysis When the DS_ROUTER_DIRECTOR is "hung" in the Scheduled Status for further information.
Note:
Always reset the queue output status to I (inactive) before
continuing the test procedures.
If the output status queue changed from I (inactive) to " " (scheduled) but the system is "hung" in the Scheduled status, find the CICS transaction code which is assigned to the Con-nect SNADS CSSEND program. That transaction code in this section will be referred to as the parameter tran.
Execute the DS_ROUTER_DIRECTOR program by using the CICS CECI utility and issue the following command:
CECI START TR(tran) FR(_ _ _ _ _ _ _ _)
Make sure that eight underscores are entered in the FR parameter and press ENTER.
The three most common results when using the CECI utility are:
The installation problem is obvious.
The program seems to be working properly. If so, examine the PCT entry by which you defined the parameter "tran". Con-nect SNADS does not internally use "tran" but rather the external transaction ID, X'21F0F0F1'. Verify that 21F0F0F1 is specified as an external transaction ID in that PCT entry and that it does not appear as an external transaction ID in other PCT entries.
The DS_ROUTER_DIRECTOR is still hung in the Scheduled status. Using the CICS terminal ID (taken from the EIB display in CECI) assign your terminal to the transaction in question (terminal ID in this section is referred to as the parameter "term") and issue the following command:
CECI START TR(tran) TE(term) FR(_ _ _ _ _ _ _ _)
One of the following occurs:
The installation problem is obvious.
The program seems to work but screen I/Os are displayed (for example, a Natural Security mailbox). Asynchronous Natural tasks should never attempt screen I/Os. When screen I/Os are requested in such a task, the Natural CICS driver forces that task to abend with NT06 and a message is directed to the operator console. If this happens, change the system set up so that screen I/Os cannot occur and restart the test from the beginning.
The program seems to work and screen I/Os are not apparent except for the Natural code NAT9995. Check for device type dependencies. Make sure NATTTY was added in the Natural nucleus. If that is not the problem, verify that the Natural Security logon procedure or user exit which is based on terminal IDs or types are correct (when asynchronous Natural tasks are running under CICS the value of "*DEVICE" is set to ASYNC).
The DS_ROUTER_DIRECTOR program is still hung. Use the CICS CEDF utility as a debugging aid. To use the CICS utility, start the DS_ROUTER_DIRECTOR program by issuing the following command:
CECI START TR(tran) TE(term) FR(_ _ _ _ _ _ _ _) I(30)
Before the program begins, the CICS Interval Control pauses thirty seconds, and then executes the transaction. During the pause issue the following command:
CEDF
If the DS_ROUTER_DIRECTOR program runs successfully, the number of items in the queue is decremented to 0. If the items in the queue are addressed to multiple addressees the queue items appear as members of the outbound queues. The items do not appear in the outbound queues if the only specified SNADS addressee is a local Con-nect user or if the specified addressee DSUN could not be matched to a SNADS routing entry.
Testing techniques for DS_SEND are similar to the testing procedures for the DS_ROUTER_DIRECTOR program. However, before you begin there are several important steps that you must observe.
Verify that the APPC connection is operational and is properly defined to Con-nect SNADS. If the connection is operational, the CICS CEMT utility indicates that the connection is in the acquired state and the log mode is defined to CICS. The "Available Session Count" must be greater than 0 and SNASVCMG must not be used as a log mode.
The logical link to the CICS connection and log mode definitions must be set up in the appropriate outbound queue definition. Be aware that the Connection ID in the "Queue Info" screen must not be specified as an LU name, but as the four-character CICS name assigned to that connection. The log mode must be specified exactly as it is defined to the network or left blank (if you do not care which one is used).
When issuing the CICS START command, specify the Con-nect SNADS queue ID in the FR parameter (which must be eight characters long, using trailing blanks if necessary).
If "queue-id" is the Con-nect SNADS queue ID, the CECI commands should be issued in the order below:
CECI START TR(tran) FR(queue-id)
CECI START TR(tran) TE (term) FR(queue-id)
CECI START TR(tran) TE (term) FR(queue-id) I(30)
If you are using the CICS CEDF utility as a diagnostic aid, you can trap the CICS LU6.2 commands They are useful in pointing out the installation problem(s). If you do trap the commands, keep in mind that they all begin with EXEC CICS GDS (at least for the unmapped conversation as it is used for SNADS).
An additional reason why the output status changes to H (held) when testing DS_SEND is that the neighboring SNADS node is rejecting Con-nect messages. If that is the case, they could be syntactically or semantically incorrect. An indication of this problem are log records which originate from the X-FOX-N8 program. In this case, see Neighboring Node Does Not Accept Messages.
Begin by setting the Con-nect SNADS inbound queue to manual operation (i.e. to status I for inactive). If a SNADS message from Con-nect is successfully transmitted to another node in the network, a SNADS status message appears.
As an alternative test, log on to one of the other SNADS nodes in the network and send a message to an addressee residing at the local Con-nect node. If this message appears in your inbound queue within a reasonable amount of time (about five or ten minutes), proceed with Checking For Inconsistent SNADS Definitions.
If messages sent from another SNADS node (within the SNADS environment) do not appear in your inbound queue, perform the following steps:
Verify that the connections to the neighboring nodes are operational and are in the acquired state.
If they are, verify that the usage count of the Con-nect SNADS CSRECV program is incremented (an indication that a neighboring SNADS node is attempting to invoke the DS_RECEIVE program (CSRECV) to transmit messages to Con-nect). If the parameter "csrecv" is the PPT name of your local CSRECV program, you can observe the usage count when using the CICS CEMT utility and issuing the command:
CEMT I PROG(csrecv)
If the usage count is not incremented, check that X'21F0F0F2' is specified as an external transaction ID in the PCT entry which is associated with CSRECV. If it is, check that a duplicate 21F0F0F2 does not appear as an external transaction ID in other PCT entries. If you have verified all of this, then the problem is with the other SNADS nodes. Verify that the APPC connections are properly set up and that the routing tables are set up correctly. The remote system requires definitions not only of local but also of remote users in order to communicate with them. Check the set up of the remote systems.
If CSRECV is invoked but the items do not appear in the inbound queue, look at the Con-nect SNADS log records. The log records display information relating to Natural error conditions (program names beginning with X-FE) or they indicate that the DS_RECEIVE program has become active (log records which display program names beginning with X-FIX).
If CSRECV is invoked but fails before becoming operational and you are unable to figure out why, use CEDF for further testing.
When testing with CEDF, it is helpful to know that each possible APPC session is associated to its own TCT terminal entry (CICS generates the TCT entries automatically). Typically, the name of a TCT entry begins with a minus sign (-) e.g. "-99F".
If you know the TCT entry name of the APPC session you are using to transmit a SNADS message to Con-nect, trapping the respective CSRECV execution is possible when issuing the following command:
CEDF -99F (or corresponding ID)
If you do not know the TCT entry name and you are using single session connections (usually not the case), let "lu-name" be the LU name of the neighboring node by issuing the command:
CEMT I NET(lu-name)
The result is the display of one TCT terminal entry. Use the ID from this entry.
If you are using parallel session connections, issue the command:
CEMT I NET(lu-name)
The result is a list of TCT entries. Try each of the TCT entries until you "catch" the conversation with CEDF.
If CSRECV abends after the initialization phase, check the log records resulting from programs beginning with X-FIX. The terminal ID (called "conversation ID" here) is listed in these log records.
When a SNADS message from a remote sender is received on the local Con-nect SNADS inbound queue, insure that the SNADS definitions match on both sides.
To verify the definitions, check the queue item display and look at the originator's SNADS node and user ID. If there is a status message, the user ID may be blank. In this case, try with a real message (i.e. DSUN and DUN). Verify that the names are the same you assumed when setting up the local system.
Additionally, look at the addressees queue item display. Verify that the names match with your prior assumptions. If you are not clear about this, use the Con-nect Send function and send a message to a SNADS addressee or a SNADS node. The window which appears shows your and the addressee's SNADS node and user IDs. If necessary, change the definitions for consistent naming.
If the naming is consistent, start the DS_ROUTER_DIRECTOR program and verify that the message appears in the appropriate Con-nect Inbasket or, if it is a status report, check the Con-nect Outbasket. If the message cannot be found, consult the Con-nect SNADS control information and verify that the DS_ROUTER_DIRECTOR program marked the appropriate Con-nect system as accessible.
Furthermore, verify that the database ID and file number of the Con-nect system file which the DS_ROUTER_DIRECTOR program entered during its last execution are correct. Basically, there are two reasons for problems in this area.
The name of the Con-nect system entered in the Con-nect SNADS control information does not match the name which is specified in the Initialize Node File function. For further information, see the Con-nect Administration documentation, section Con-nect System Maintenance .
The contents of the Con-nect spool file are not consistent. For further information, see Inconsistency in the Con-nect Spool File.
Note:
If the Con-nect timezones are not set up properly, incoming
messages may remain "invisible" for some time after delivery in the Con-nect
Inbasket.
If upon execution of DS_SEND, the output status of the respective outbound queue changes to H (held), check for one of two problems:
There may be a communication problem; check the connection status to the neighboring system.
The neighboring system may find the message is syntactically or semantically incorrect. An indication of this situation are log records that originate from a program with the name X-FOX-N8.
If the SNADS messages from a Con-nect node are incorrect, the problem is one of the following:
The Origin Node DSUN and/or the Origin Name DUN are not built according to SNADS conventions. In particular, the only component of DSUN and DUN that can be blank is the group entry of the DSUN (RGN). Check the Origin Node DSUN and the Origin Name DUN by looking at the "Data Interchange Unit" screen. If the DSUN is wrong, then the SNADS control information is defined incorrectly. If the first part of the SNADS user ID (DUN, the first-group-component of it is called DGN) is blank, then the contents of the Con-nect spool file are probably inconsistent.
The definitions that are set up for Con-nect in the neighboring system are incorrect.
For each Con-nect system file that is to be serviced by one Con-nect spool file, there is one so called "Home Node Record" stored in the spool file. That record is used for all external mailing methods of Con-nect, not just Con-nect SNADS. The Home Node Record is a logical link between the spool file and the system files. The Home Node Record contains two major pieces of information, both of which are defined as descriptors: the name of the respective Con-nect system (up to eight characters in length), and the database ID and file number of the system file.
Con-nect SNADS uses the Home Node Record for two purposes:
During execution of the Send function, Con-nect SNADS determines the database ID and file number of the Con-nect system file. The database ID and file number are then used to retrieve the name of the respective system from the Home Node Record. This name is used as the default DGN when building the SNADS DUN of the message originator. The name is also used as a key to locate the appropriate SNADS control information entry when building the SNADS DSUN of the message originator.
The Home Node Record is also used when an incoming SNADS message is directed to the local Con-nect system. Con-nect SNADS determines the name of the local system using the SNADS recipient DSUN and the information kept in the Con-nect SNADS control information. Then for a physical transfer of the message to that system, Con-nect SNADS consults the Home Node Record to retrieve the appropriate database ID and file number.
A Home Node Record is created when executing the Initialize Node File function in the Con-nect ADMIN program. For further information, see the Con-nect Administration documentation, section Con-nect System Maintenance .
Inconsistencies may occur within the Con-nect Home Node Record. Below are some of the most common inconsistencies.
As in the Con-nect system described in scenario number one (outgoing SNADS messages) of the previous section, The Home Node Record in the Con-nect Spool File, there are two common problems:
The Home Node Record is missing altogether. This occurs when the Initialize Node File function is not executed.
The Home Node Record is obscured by other database records that have the same "number" key value. Normally all "noise" records have a name descriptor which is similar to the real Home Node Record. (They are in effect partial copies of the Home Node Record.) This "normal" case, however, persists only if the Initialize Node File functions are executed for each serviced system file immediately after you create your Con-nect spool file and before any other Administration Functions. What usually happens in this case is that Con-nect SNADS builds syntactically invalid SNADS DSUNs (node IDs) and DUNs (user IDs) Con-nect message originators. Check the SNADS DSUN and DUN which Con-nect assigns to you when issuing the Send function with a SNADS address (it is displayed in the window which prompts for the completion of the addressee information). Check the outgoing messages in the Con-nect SNADS queues. A neighboring system usually rejects such messages. Be sure that you have set up the SNADS control information properly, invalid DSUNs may have been specified.
As in the Con-nect system described in scenario number two (incoming SNADS messages) of the previous section, The Home Node Record in the Con-nect Spool File, there are five common inconsistencies.
The Home Node Record is missing altogether. This occurs when the Initialize Node File function is not executed.
The name descriptor of the Home Node Record is corrupt. In this case, the system behaves as if the Home Node Record is missing.
The Home Node Record exists, but the database ID and file number specified are incorrect. Verify that the database ID and file number of your Con-nect system file was changed after executing the Initialize Node File function.
The Home Node Record is not unique. For example, more than one Home Node Record exists with the same name descriptor. The same name may have been used while executing the Initialize Node File function from different Con-nect systems, referencing the same spool file. Or, an attempt was made to fix the inconsistency resulting from changing the database ID and file number of the Con-nect system file by implementing another Initialize Node File function.
If any of the above inconsistencies occur, the incoming SNADS messages and their status will not transfer to the appropriate Con-nect system. Check the Con-nect SNADS control information. The DS_ROUTER_DIRECTOR program records the database ID and file number of each defined local Con-nect system as they are found in the respective Home Node Records at the beginning of each run.
If you find that the contents of your spool file are inconsistent, try to solve the problem by executing the Initialize Node File function.
If the problem persists, the only recommended solution is to scratch the spool file and create a new one (execute the Initialize Node File function immediately after creating the spool file). Not only Con-nect SNADS, but all other external mailing methods will have trouble with your old, corrupted spool file. Keep in mind that you have to re-enter all Con-nect SNADS system definitions (not the SNADS nodes and addressees) as they are defined in the Con-nect spool file.