SNA LU6.2

The SNA LU6.2 communication point enables Rhapsody to exchange messages with hardware compatible with IBM's Systems Network Architecture (SNA). It is only made available for platforms for which IBM's CPIC native libraries are available, in other words Microsoft® Windows®, Linux, and AIX.

To use the communication point, you must connect Rhapsody to an IBM Communications Server by installing the IBM Communications Server on the Rhapsody server, or through IBM Communications Server Remote Client software installed on the Rhapsody server.

The communication point must be configured to use IBM's CPIC libraries in order to connect to an IBM Communications Server, specifically the CPIC Java library, and the CPIC native libraries. These libraries are distributed with an IBM Communications Server installation.

Supported Operational Modes: Input, Output.

Environment Variables

The SNA LU6.2 communication point uses environment variables to locate the Java executable to run on.

Setting the following environment variables is recommended. These variables cannot be set while Rhapsody is running. For the values to be visible to Rhapsody, they must be set from the command line from which you launch the Rhapsody.

Setting the following environment variables are optional. They do not normally need to be set, and only examined, for example, if the communication point has failed to start.

Configuration Properties

LU6.2 Conversations

In LU6.2 communication protocol, data is transmitted between the two end-points over a 'conversation'. Typically, a conversation only remains in an allocated (connected) state while there is data to be sent. When there is no data to be sent, the conversation is de-allocated (closed). The following sections outline the communication point's behavior in relation to the LU6.2 conversation (applicable to both the Vanilla LU6.2 and Siemens modes):

• Receiving Mode

• Sending Mode

• Conversation Details

Receiving Mode

• When started, the communication point initializes the conversation, sets the Transaction Program Name configuration property and enters a listening state waiting for the remote side to allocate the conversation (in other words, to initiate a connection). When the communication point is stopped, a conversation cannot be established with the communication point.
• If the conversation is deallocated, the communication point automatically re-initializes the conversation, sets the Transaction Program Name, and again enters a listening state waiting for the remote side to allocate the conversation.

Sending Mode

• When started, the communication point sets the Symbolic Destination Name configuration property, and initializes and allocates the conversation. The IBM Communication Server uses the CPIC side information to identify the remote program to connect with.
• When the communication point is in sending mode and has performed no operations (in other words, there is no data to be sent), the conversation is automatically de-allocated. As new messages are queued to be sent, the communication point re-allocates the conversation.

Conversation Details

• The communication point expects the conversation type to be Mapped (not Basic).
• The synchronization level can be either Confirm or None (refer to the Sync Level configuration property). In Siemens mode, the synchronization level is always None.
• When in Siemens mode, the communication point sends and receives the Siemens commands over the conversation in half-duplex mode. This means that only one side of the conversation can act as the sender at any given time, and the sender alternates between the two end-points with every message sent.

Siemens Mode

Siemens mode enables Rhapsody to act as an interface partner for sending and receiving messages to an OAS Communication Subsystem (OAS Comm Sub) using SNA communications. In order to use this mode, appropriate values must first be determined for the Maximum Sequence Number Disagreement, Sequence Number Length, Region Code, Hospital Code and System ID for the OAS Comm Sub.

Siemens Commands

The communication point handles Siemens commands (ACK, NAK, STRT (start), SHUTDOWN) as follows:

• If Rhapsody sends 3STRT commands to the OAS Comm Sub and receives two consecutive NAK messages in response, the communication point stops running and retries negotiations based on the configured connection retries (see Connection Retries). If unsuccessful, it stops in error.
• The communication point only supports Siemens data messages with the last block of data indicator set to 'L' (to indicate the last block of data). Multi-block messages (with last block of data indicator set to 'N') are not supported.
• When receiving data messages, the sequence number of each message is tracked. Rhapsody expects each message received to increment the sequence number by 1. If a message is received with a sequence number that is too high (for example a sequence number of 4 is received immediately after a sequence number of 1), Rhapsody assumes data loss has occurred and sends a NAK to the remote party with the last successfully received sequence number. The message that is received out-of-order is discarded with the expectation the remote party will re-send the lost messages in order including the discarded message.
• Similarly, when sending data messages, the communication point includes a sequence number. The value is incremented by 1 for each message that is sent. If a NAK is received in response to a data message, the communication point would attempt automatically to re-send the lost messages from the sequence number the NAK indicates. However, if the sequence number difference between the last message sent and the NAK received is greater than the maximum allowed difference configured, then the communication point would stop in error.
• If Rhapsody receives a SHUTDOWN request from the OAS Comm Sub, it responds with appropriate acknowledgment. The communication point, however, remains in a running state, with the LU6.2 connection maintained, so that it can listen for incoming STRT requests, or initiate its own STRT requests if needing to send messages to the OAS Comm Sub. One exception is when the SHUTDOWN request is due to the sequence number disagreement being too great, in which case the communication point stops in error.
• As per the Siemens specification, the communication point attempts to negotiate sequence numbers with the OAS Comm Sub when it is started, and if required it resends messages where there is sequence number disagreement, up to the configured maximum sequence number disagreement. If during negotiation the sequence numbers are found to be out of disagreement by more than the configured maximum sequence number disagreement, the communication point retries negotiations based on the configured connection retries (refer to Connection Retries), and then stops in error. At this stage, manual intervention would be required to restart the communication point. Refer to Correcting Message Sequence Numbers for details. It is recommended that disaster recovery plans are designed and implemented for power failure scenarios.

Correcting Message Sequence Numbers

The following instructions describe how to correct the message sequence numbers used within Rhapsody when the SNA LU6.2 communication point is in Siemens mode and send all unsent messages to the OAS Comm Sub:

• If maintaining absolute message order is not required:
  

  1. The messages that need to be resent can be found using the Management Console by searching for output messages sent by that communication point:

     1. Calculate the difference between the sequence number Rhapsody has locally and the sequence number the remote system has (as reported in the error log message when the communication point stopped in error). Use this difference to determine the messages that need to be resent.

     2. Enqueue the oldest (lowest sequence number) message first, then the second oldest, and so on. These messages can be re-enqueued for sending by selecting the Resend button.

  2. The communication point cannot be started yet as there is still a sequence number disagreement. There is a sequence number stored at either end of the connection, so either the sequence number used in the remote Siemens system can be updated, or the sequence numbers in the Rhapsody communication point can be updated. Updating the sequence numbers in Rhapsody involves editing a file in the Rhapsody datastore:
     

     1. Navigate to the location where the datastore is located, and then navigate to the commpoints/sna folder. As the files within this folder are keyed to individual SNA LU6.2 communication points, it is important to select the correct file.

     2. By viewing the communication point in question in the Management Console, the communication point ID can be found in the URL of that page, where it is the number at the end of the URL. In the folder, there is a .record file that has the communication point ID in its name.
        

     3. This file can be opened and edited in any text editor. The value for last.sent.sequence.number can be adjusted to the agreed value.

        When editing the sequence number file, care should be taken, firstly that the correct file is being edited, and secondly that no extraneous text is added to the file. Care should also be taken not to edit or delete any other files in the data store.

        
        

  3. Start the SNA LU6.2 communication point. If a Hold Queue filter has been used, ensure the SNA LU6.2 communication point successfully restarts communications and resends the messages that were re-enqueued before releasing the messages that are on the hold queue.
     

• If maintaining absolute message order is required:

  The utmost care should be taken when resending messages manually using the Management Console in order to ensure that the messages are maintained in the correct order. Rhapsody cannot automatically detect out-of-order errors.

  1. Stop new messages flowing into the output queue of the communication point, so that messages from the archive can be resent before the new messages. Temporarily place a Hold Filter on the route in front of the communication point.

  2. If messages are already on the queue, delete them, taking careful note of which messages were deleted (information like the message identifier and timestamp will be helpful), as later these messages will need to be found again in the management console and queued up again.      

  3. The messages that need to be resent can be found using the Management Console by searching for output messages sent by that communication point:

     1. Calculate the difference between the sequence number Rhapsody has locally and the sequence number the remote system has (as reported in the error log message when the communication point stopped in error). Use this difference to determine the messages that need to be resent.

     2. Enqueue the oldest (lowest sequence number) message first, then the second oldest, and so on. These messages can be re-enqueued for sending by selecting the Resend button.

  4. When the archived messages have been re-enqueued, if any messages were deleted in step 1, locate those messages using the Management Console and re-enqueue them:

     1. Search for messages processed on the route that the SNA LU6.2 communication point is on.

     2. From this search, the individual messages that were deleted can then be viewed (they will have a message event indicating that they were deleted)

     3. The Redirect Copy button can be used to direct them back to SNA LU6.2 communication point.  

  5. The communication point cannot be started yet as there is still a sequence number disagreement. There is a sequence number stored at either end of the connection, so either the sequence number used in the remote Siemens system can be updated, or the sequence numbers in the Rhapsody communication point can be updated. Updating the sequence numbers in Rhapsody involves editing a file in the Rhapsody datastore:
     

     1. Navigate to the location where the datastore is located, and then navigate to the commpoints/sna folder. As the files within this folder are keyed to individual SNA LU6.2 communication points, it is important to select the correct file.

     2. By viewing the communication point in question in the Management Console, the communication point ID can be found in the URL of that page, where it is the number at the end of the URL. In the folder, there is a .record file that has the communication point ID in its name.
        

     3. This file can be opened and edited in any text editor. The value for last.sent.sequence.number can be adjusted to the agreed value.

        When editing the sequence number file, care should be taken, firstly that the correct file is being edited, and secondly that no extraneous text is added to the file. Care should also be taken not to edit or delete any other files in the data store.

        
        

  6. Start the SNA LU6.2 communication point. If a Hold filter has been used, ensure the SNA LU6.2 communication point successfully restarts communications and resends the messages that were re-enqueued before releasing the messages that are on the hold queue. 

Advanced Debugging

Enabling Full Debug Logging

Logging messages in Rhapsody are set with a 'level' that marks their importance. The levels, ranging from lowest to highest, are TRACE, DEBUG, INFO, WARN, and FATAL. Because the SNA LU6.2 communication point runs in a separate process from the Rhapsody, the logging is managed slightly differently. Logging messages at INFO level and higher is visible as per normal, but if full debug output is required, the Rhapsody's JVM logging.properties file must be edited to render visible all debug logging messages:

1. Locate the JVM logging.properties file in the JVM's lib directory:
   
   • If the JVM being used is the one supplied with Rhapsody, it is located in <Rhapsody Home>/rhapsody/jvm/lib/logging.properties.
     If the JAVA_HOME environment variable is set correctly, the JVM is located in $JAVA_HOME/lib/logging.properties (in a Unix environment) or %JAVA_HOME%/lib/logging.properties (in a Windows® environment). 
2. Change the default global logging level the logging.propertiesfile to FINE:
   1. Search for the property .level= INFO.
   2. Replace the line with .level= FINE.

Using Development Debugging Options

The Enable Debugging and Debugging Address configuration properties are for developmental use, and should not be enabled in a production environment. These options allow a developer to directly monitor and control the communication point process while it is running in a development environment. When Enable Debugging is enabled, and Debugging Address is set, the developer running Rhapsody will be able to connect to the running SNA LU6.2 communication point using Eclipse (or similar IDE) on the port number defined. The developer can then make use of break-points to halt execution and step through the code.

The Enable Assertions configuration property, when enabled, causes the SNA Java process to terminate if any of the defined Java assertion checks fail at runtime. This setting is also recommended for developmental use only (not for production), as the error reported in the case of an assertion failure may not be clear to the end user.