UPoC protocol

The UPoC driver uses Tcl Procedure Streams to run Tcl commands and pass messages into the engine. As messages are delivered to the driver, they go through an outbound TPS for delivery to the database.

This driver runs a TCL script on a user-specified interval, usually to read messages into the interface. Alternately, the user can configure it to run a TCL script when a message write is attempted.

You can use an API to write code fragments in Java for UPoCs. Although there are many UPoCs, there are only three interface styles between the engine and the user code:

  • TPS:

    Controls/extends message movement through the engine.

  • TrxID:

    Determines a transaction code, or routing identifier, for a given message.

  • XLT:

    Transforms certain fields within a message as part of a transformation specification.

In the Java API, each of these styles is represented as a class which can be extended by the interface developer.

Options pane

This table show the parameters for the Options pane:

Parameter Description
Read TPS Click Edit to open the TPS Editor. Then, click Add to select the inbound procedures. (IB disabled if 0 procs).

The driver’s inbound (read) TPS generates inbound messages and passes them into the engine (READTPS).

This option is disabled if Use advanced scheduling is selected.

Messages returned with CONTINUE disposition are treated as inbound messages.

When generating a message in Start mode in Read TPS, inbound messages are placed in the IB Pre/Post queue twice. This leads to an error in translation. To prevent this, do not generate messages in Start mode in Read TPS.

Read Interval Specify the inbound interval. This is the READINTERVAL. The IB is disabled if there are no procs. This option is disabled if Use advanced scheduling is selected.
Use advanced scheduling Select this to schedule recurring events, such as recycling log or SMAT files. Then, click Setup to open the Scheduling dialog box.
Write TPS Click Edit to open the TPS Editor. Then, click Add to select the outbound procedures. The driver’s outbound (write) TPS is required to write the message, using WRITETPS.

This is run when an outbound message is available for protocol delivery.

In the UPoC Write TPS, only use CONTINUE (success) or ERROR (failure).

A CONTINUE disposition goes to SEND OK.

When you use the CONTINUE disposition your messages out should increment and if you have a procedure applied, the Send OK TPS is run.

When you use ERROR, the message is sent to the Send Fail TPS. If there is no code in Send Fail TPS or it returns a CONTINUE, then the message is re-queued at the top of the queue for re-delivery. If a retry is not necessary, then use ERROR inside the Send Fail procedure.

Use the Send OK/Fail procs to control the post delivery aspects of your UPoC protocol.

Note:  For your Send Fail procedure to run, the Retries setting on the Outbound tab must be greater than 0. 3 or 10 is typical, depending on the interfaces requirements.

Start-Up Procedures pane

Click Edit to open the TPS Editor. Use this to select the procedures and Java class to run when the thread starts. This is a TPS (Tcl Procedure Stream). Use it to trade messages with the remote end.

Inbound messages

If a non-zero inbound scan-time value is provided, then the driver runs its inbound (read) TPS according to other threads’ actions. It is run no less than N seconds between invocations. Unlike most TPS instances, there is no input for this.

Because there is no input, the UPoC driver introduces another time-based mode. Similar to start-up, procedures may or may not receive a MSGID in their arguments. This mode is distinctive from start-up mode so that procedures can take other actions.

No matter how the TPS is called, it produces zero or more messages under these dispositions:

  • CONTINUE:

    Passes into engine and places on inbound pre-TPS queue

  • ERROR:

    Transitions to error database

  • KILL:

    Destroys the message

  • OVER:

    Illegal; warns and destroys the message

  • PROTO:

    Places on outbound post-TPS queue

  • SEND:

    Places on inbound post-TPS queue

Outbound messages

The outbound operation of this driver pushes messages through the TPS.

The dispositions that are procured by the TPS are:

  • CONTINUE:

    Destroys

  • ERROR:

    Transitions to error database

  • KILL:

    Destroys the message

  • OVER:

    Illegal; warns and destroys the message

  • PROTO:

    Places on outbound post-TPS queue

  • SEND:

    Places on inbound post-TPS queue