UPoCs used within the TPS module interface

These UPoCs include:
UPoC Usage
Protocol Read This delivers a single inbound data protocol message to the engine from the protocol driver.
Protocol Start-Up This is the first UPoC that is applied to an inbound data message that is delivered from a protocol driver to the engine. This UPoC controls what happens when the first message is sent to or received from a connection.

Actions are:

  • Pass the message to the pre-TPS queue for further processing.
  • Stop the message.
  • Generate an outbound protocol message that is delivered immediately after the procedure returns.

This UPoC customizes the startup actions of a protocol driver without changing the driver code itself. It is not called again until the thread restarts.

Protocol Start-Up Switch This is used to control how protocol messages received from the protocol driver are routed. At thread start-up, a Tcl procedure, if defined, is given control of message flow. It is called once to set up its initial state. It is then called each time a new protocol message arrives from the connection. The procedure is given the message and it has the option to do whatever is required.

Each time the procedure is invoked, including the initial invocation, the return value from the procedure is a list of binary object handles wrapped inside two keyed lists.

  • The first list indicates binary objects that should be written to the connection.
  • The second list indicates binary objects that should be moved to the inbound pre-SMS queue. The second list gives the Tcl procedure the opportunity to pass along protocol messages that it receives that are uninteresting to it.

When the procedure is running, it has access to the inbound pre-SMS stack. It may remove messages from the queue using Tcl built-in functions. This functionality is provided so it can remove messages that have not yet entered inbound SMS processing.

When the procedure is finished controlling the start-up flow, it changes the protocol switch from within Tcl. When the procedure returns after it has thrown the switch, the procedure is not called again until the thread is restarted.

The protocol start-up switch is thrown using the engine-only Tcl command engpswthrow. This is required for normal processing. Otherwise, the thread stays in Startup mode.

Inbound Data TPS Processing An Inbound Data TPS modifies the inbound data messages and creates application-level acknowledgments. Data messages read from a connection are processed through this stream.

Messages received from the protocol thread and put into the Inbound pre-TPS queue are saved into Raima and SMAT, if SMAT is defined. At this point, the message is going to the engine, because this message can be recovered /resent from Raima and SMAT.

When an Inbound Data TPS is called, messages are placed in the inbound message queue. The input is recently-read data protocol messages. The output is pre-translation data messages. Resulting engine messages are sent to the translation thread for processing.

This UPoC is used to:

  • Coalesce messages
  • Divide messages
  • Convert from EBCDIC to ASCII
  • Create acknowledgment messages
Outbound Data TPS Processing This modifies the outbound message data.

This UPoC is used to:

  • Coalesce messages, to create a batch file
  • Divide messages, when remote connection power is limited
  • Convert ASCII to EBCDIC

When the Outbound Data TPS is called, it modifies the message immediately before it enters the queue to be written to the destination connection. The input is post-translation data messages, and the output is to-be-written outbound data protocol messages.

All post-translation data messages are processed through this stream. Resulting messages are placed in the outbound data queue.

If message forwarding is enabled, then data messages are run through this UPoC on the forwarded thread.

Route Detail Pre-Processor The XLT Route Detail Pre-Processor works on a copy of the original message, and processes the message before the route detail translation actions are run. Each route detail gets its own copy of the resulting message from the pre-processor.

This UPoC is used to:

  • Process an entire inbound message before it goes into translation.
  • Transliterate operations.
  • Modify all translated versions of a message
Route Detail Post-Processor This processes the message immediately after the detail transaction actions are complete.

This UPoC is used to:

  • Modify an entire outbound message.
  • Convert an entire message to uppercase.
Generate routes These affect message routes and translations, where the destination and translation used to process messages are under programmatic control.

Typically, use Generate routes to route a message that is based on its content. These commands are valid:

  • msgrouteget msgId retrieves the message’s route detail list, which is a list of keyed lists from the Network Configurator file.
  • msgrouteset msgId list replaces the message’s routing list.

If you do not use msgrouteset, then the route detail list retains its original value. These commands work only during Generate route processing.

Because Generate routes affects messages dynamically, there are these considerations:

  • In any route detail list, only the first Generate is guaranteed to run. Route details after the Generate are available to the route’s procedure, but they might not be run.
  • If the route detail list is empty or it cannot be internalized, then the original source message is moved to the error database. For example, if there is bad format or typographical errors in the keyed lists.
  • Generate procedures can SEND and KILL messages, but all CONTINUE messages must have route detail lists attached to them.
Raw routes These turn a single source message into any resulting messages without applying a translation to the message.

A Raw route detail is a list of Tcl procedures that are:

  • Run in sequence
  • Called with the same keyed-list interface
  • Called with the same expected keyed-list output

Upon entry to each procedure, the source message’s msgXlateDests metadata field contains the list of destination connections to which the message is sent. Before the first procedure is called, the source message’s metadata is set to the default list of destinations that are configured for the route detail.

Each procedure can modify the list of destination connections. If no modifications are made, then the default list is used.

Modifications to the list can be made by direct manipulation or by calling a programmatic interface.

  • The first keyed list (messages that should be given to the remaining procedures, if any) is tagged with a key of CONTINUE.
  • The second keyed list is tagged with a key of SEND. The keyed list contains messages that should be sent to a connection independent from the processing of messages in the other keyed list.
  • Each message that is listed in the SEND keyed list is immediately placed into the Protocol queue without further processing.

When the translation is complete, all messages in the Partial queue are moved to the correct post-translation queue. This includes messages that are placed there by SEND operations. This movement takes place in a FIFO message priority order. During the movement, SEND-generated messages are not treated specially.

Reply Generation Reply generation is called only if the engine is expecting an inbound protocol reply message, but does not receive one. This UPoC exists because replies must be received within a configurable time-out period.

The input msgid is a COPY of the outbound data message that generated no reply. It is meant to be used as a reference for generating the inbound reply.

If the input msgid is returned with PROTO disposition, then the message is placed directly on the OB Processing queue. This message is not recoverable. To resend a recoverable message, use the OBMSGID.

The OBMSGID is the handle for the saved outbound data message that generated no reply.

Typically, use Reply Generation to:

  • Resend the outbound data message.
  • Receive message handles, zero or more, that are used as inbound reply protocol messages.

A source protocol thread waits on a reply for a defined amount of time. If no time-out is configured, then it waits indefinitely.

Pre-Write TPS

Use this for a final chance to edit a particular message before protocol write.

The Pre-Write TPS is used in sequence number synchronization and time-based logic.

The Pre-Write TPS is configured on the Network Configurator.

The only dispositions that are permitted are CONTINUE and KILL.

If a protocol write fails, then it can be re-queued to the outbound post-TPS queue for several retries before the write is considered to have failed. SENDFAIL controls additional retries if TRYAGAIN is set.

These retries cause the message to flow from the outbound post-TPS queue to the protocol specific write again, therefore going back through the pre-write UPoC. A message flag, MSG_FLAG_DONE_PREWRITE, is set when the message has successfully passed through a pre-write UPoC.

Replies Reply Message processing uses the reply TPS queue, and the reply message destination determines the message format. The inbound reply message destination is determined by the outbound message source.

There are two types of reply message TPS:

  • Inbound Reply TPS

    This processes all reply protocol messages read from a connection. The resulting engine messages are sent to the translation thread.

    Input is recently-read reply protocol messages.

    Output is pre-translation reply messages.

  • Outbound Reply TPS

    This processes all post-translation reply messages. The resulting protocol messages are placed in the outbound reply queue.

    Input is post-translation reply messages.

    Output is to-be-written outbound reply protocol messages.

    If message forwarding is enabled, then reply messages are sent through on the forwarded thread.

Send OK TPS This UPoC is called only if the outbound protocol message is successfully sent.

Typically, use the Send OK TPS to update application databases or to update other operations that are associated with the successful delivery of the message.

This UPoC receives a copy of the outbound message as an argument.

Send Fail Failed Data Message Send is a TPS called only if the outbound protocol message is not successfully sent.

Typically, the failed data message send:

  • Receives a copy of the outbound message as an argument.
  • Produces special message metadata that describes how the message failed.