What's New for v2.2?

In Brief

Extensive exception handling and IFS-based trace and error logging have been added to critical components of the toolkit. The formerly manual procedure used to initialize and synchronize the toolkit's local copies of the customer's macro message template definitions has been transformed into a low-touch, automated procedure which will continue to maintain synchronization without user intervention. Use of the now-deprecated ESS dequeue web service has been replaced with the new ESS high volume dequeue web service which is capable of substantially increased transaction throughputs.

The following sections describe specific areas where the product was enhanced.

Automated Macro Template Definition Synchronization

The current manual procedure which is used to synchronize the toolkit's local macro template definitions via a save file (SAVF) created via a Omnitracs hub utility has been replaced with a web service based low-touch mechanism. This new synchronization can work in fully automated and in on-demand modes.

Fully Automated Mode

The fully automated macro template synchronization mechanism is built into the toolkit's return message processor and works as follows...

Registration - Customers will subscribe to the ESS Macro Template Change Notification transaction (T.2.09.0) via portal web page
Change Detection - The toolkit's return message processor (IIRTNPROC) will "listen" for T.2.09.0 transactions, which are generated as a result of customer-initiated macro template additions and changes
Template Requests - The toolkit's return message processor will call a web service to retrieve the new or modified macro's template definitions from the portal
Definition Updates - The toolkit's return message processor will store the macro's returned template definition information in its local database, overwriting any previous definitions for the given macro

On Demand Mode

A low-Touch on-demand macro template synchronization mechanism is available via a new utility IIMACRFSH, which can be directly called from a command line or submitted to batch. The utility works as follows...

Initialization & Re-synchronization - All the toolkit's local macro template definitions may be initialized as part of the toolkit's post installation initialization (or anytime for that matter) by calling the new IIMACRFSH utility. The utility will call a web service to retrieve the list of all the customer's macros currently defined on the portal and then another web service to retrieve the macro template definition details for each one before storing them locally in the toolkit's database.
Ad Hoc - If desired, the utility may also be used at any time to synchronize the template for a single specific macro, although this is not expected to be a common use case.

The calling interface for the utility is as follows:

IIMACRFSH parameter Interface:

Parameter	Direction	Type	Length	Precision	Description
Macro Direction	Input	Character	1	n/a	"F" = Forward, 'R" = Return, "A" = All (forward and return)
Macro Number	Input	Character	2	n/a	Macro number "1" to "63" or "0" if macro direction "A" (All) specified
Completion Status String	Output	Character	200	n/a	Blank if successful or error string if failure encountered

Enhanced Exception Handling and Enhanced Trace and Error Logging

Exception Monitoring and Handling

Extensive exception condition monitoring and handling logic has been added to both the forward and return message processors, along with other key toolkit modules, ensuring a high degree of fault tolerance and the ability to automatically recover from most unexpected errors and continue running without interruption (ie. MSGWs). Certain failures encountered when attempting to call web services while the portal is offline or unreachable will now be detected and handled before the message processor returns to its normal processing/retry loop.

IFS-Based Exception Logging

IFS based logging, similar to that currently generated by the toolkit web service wrappers will be supported by the forward and return message processors along with other key modules, however the logging will be exception-based only. This logging will supplement the existing warning messages issued to users when the forward and return message processes detect error conditions which might be solved through user interventions such as PIT configuration file changes.

All IFS-based logging (both exception and trace) is enabled or disabled by specifying or clearing the IFS path string field (DFIFSPATH) in the toolkit configuration file (IICONFIGP).

IFS-Based File Name Conventions

IFS file names written to the path specified in the toolkit configuration file will take the general form: FILENAME_NN.EXTENSION
...where FILENAME indicates the toolkit module or process generating the file, and NN is an automatically incrementing and wrapping value which allows multiple historical versions of the exception or trace logging file to exist.

(info) The IFS log files should be sorted by creation timestamp rather than name for an accurate representation of the sequence in which they were created.

Support for High Volume ESS Transaction Dequeue Web Service

The toolkit return message processor will now make use of the latest ESS High Volume Dequeue web service rather than the deprecated ESS Dequeue web service. The new web service is capable of substantially higher transaction throughputs and is more efficient than the deprecated dequeue web service it's replacing. All enhancements are internal to the toolkit and require no special configuration or actions.

(info) Individual ESS XML transactions are limited to approximately 32K characters in length. The toolkit's transaction table (IITRAN) will only store 32K characters worth of parsed data or raw (non-parsed) XML for each dequeued ESS transaction.