EndMapper (v2) ESQL API

EndMapper (v2) provides a set of helper functions that can be used to accelerate the implementation effort for construction of mapping document:
Table 1. EndMapper (v2) ESQL API
API function Description 
CREATE PROCEDURE InitDocMapping(IN rOutputRoot REFERENCE, 
                                INOUT rDoc REFERENCE)
 Creates the XMLNSC child of output root and initializes the XML attributes (version and encoding). 
CREATE PROCEDURE InitTxnMapping(IN rOutputRoot REFERENCE, 
                                INOUT rTxn REFERENCE, 
                                IN cObjType CHAR);
 Creates an 'em:txn' element on output root of type <cObjType>. Moves <rTxn> to point to this element. 
CREATE PROCEDURE InitChunkMapping(IN rOutputRoot REFERENCE, 
                                  INOUT rChunk REFERENCE);
 Creates an 'em:chunk' element on output root of type <cObjType>. Moves <rChunk> to point to this element. 
CREATE PROCEDURE InitBatTxnMapping(IN rOutputRoot REFERENCE,
                                   INOUT rTxn REFERENCE, 
                                   IN cObjType CHAR);
 Batch version of InitTxnMapping function. 
CREATE PROCEDURE InitTxnIsf(IN rTxn REFERENCE, 
                            INOUT rIsf REFERENCE, 
                            IN ns CHAR, 
                            IN ns_prefix CHAR, 
                            INOUT rCols REFERENCE);
 Create an ISFMessage element in an 'ISF_DATA' column definition under <rTxn>. Move <rCols> and <rIsf> to point to the cols and ISFMessage elements respectively. 
CREATE PROCEDURE InitAbortMapping(IN rOutputRoot REFERENCE, 
                                  INOUT rAbort REFERENCE, 
                                  IN cObjType CHAR);
 Create an 'em:abort' element under an XMLNSC child of output root of type <cObjType>. 
CREATE PROCEDURE NewStrCol(IN rCols REFERENCE, 
                           IN cColName CHAR, 
                           IN cColValue CHAR);
 Create a 'str' column element under <rCols> using the values from <cColName> and <cColValue>. 
CREATE PROCEDURE NewIntCol(IN rCols REFERENCE, 
                           IN cColName CHAR, 
                           IN nColValue INTEGER);
 Create a 'int' column element under <rCols> using the values from <cColName> and <cColValue>. 
CREATE PROCEDURE NewDecimalCol(IN rCols REFERENCE, 
                               IN cColName CHAR, 
                               IN dColValue DECIMAL);
 Create a 'dec' column element under <rCols> using the values from <cColName> and <cColValue>. 
CREATE PROCEDURE NewBooleanCol(IN rCols REFERENCE, 
                               IN cColName CHAR, 
                               IN bColValue BOOLEAN);
 Create a 'boolean' column element under <rCols> using the values from <cColName> and <cColValue>. 
CREATE PROCEDURE NewDateCol(IN rCols REFERENCE, 
                            IN cColName CHAR, 
                            IN dtColValue DATE);
 Create a 'date' column element under <rCols> using the values from <cColName> and <cColValue>. 
CREATE PROCEDURE NewTimeCol(IN rCols REFERENCE, 
                            IN cColName CHAR, 
                            IN tColValue TIME);
 Create a 'time' column element under <rCols> using the values from <cColName> and <cColValue>. 
CREATE PROCEDURE NewDateTimeCol(IN rCols REFERENCE, 
                                IN cColName CHAR, 
                                IN tsColValue TIMESTAMP);
 Create a 'datetime' column element under <rCols> using the values from <cColName> and <cColValue>. 
CREATE PROCEDURE NewXmlCol(IN rCols REFERENCE, 
                           IN cColName CHAR, 
                           IN rColValue REFERENCE);
 Create a 'xml' column element under <rCols> using the values from <cColName> and <cColValue>. 
CREATE PROCEDURE NewBinaryCol(IN rCols REFERENCE, 
                              IN cColName CHAR, 
                              IN rColValue REFERENCE);
 Create a 'hex' column element under <rCols> using the values from <cColName> and <cColValue>. 
CREATE PROCEDURE StartBatch(IN rObject REFERENCE, 
                            INOUT rCols REFERENCE, 
                            IN cObjType CHAR);
 Create a 'batStart' element under <rObject> with type of <cObjType>. 
CREATE PROCEDURE EndBatch(IN rObject REFERENCE, 
                          INOUT rBatchEnd REFERENCE, 
                          INOUT rCols REFERENCE, 
                          IN cObjType CHAR);
 Create a 'batEnd' element under <rObject> with type of <cObjType>. 
CREATE PROCEDURE ObjValueString(INOUT rCols REFERENCE, 
                                IN cCategory CHAR, 
                                IN cKey CHAR, 
                                IN ref REFERENCE);
 Create a 'objVal' element as a sibling of <rCols> using the other parameter values.
Note: Please review usage notes at the end of the table
 
CREATE PROCEDURE ObjValueHex(INOUT rCols REFERENCE, 
                             IN cCategory CHAR, 
                             IN cKey CHAR, 
                             IN ref REFERENCE);
 Create a 'objVal' element as a sibling of <rCols> using the other parameter values. The reference <ref> must be a reference to a BLOB value.
Note: Please review usage notes at the end of the table
 
CREATE PROCEDURE ObjValueXml(INOUT rCols REFERENCE, 
                             IN cCategory CHAR, 
                             IN cKey CHAR, 
                             IN ref REFERENCE);
 Create a 'objVal' element as a sibling of <rCols> using the other parameter values. The reference <ref> must be a reference to an XMLNSC tree.
Note: Please review usage notes at the end of the table
 
CREATE PROCEDURE Counter(INOUT rCols REFERENCE, 
                         IN cName CHAR, 
                         IN cType CHAR, 
                         IN nCount INTEGER, 
                         IN dAmount DECIMAL);
 Create a 'counter' element as a sibling of <rCols> using the other parameter values.
Note: Please review usage notes at the end of the table
 
CREATE PROCEDURE Error(INOUT rCols REFERENCE, 
                       IN cType CHAR, 
                       IN cScheme CHAR, 
                       IN cCode CHAR, 
                       IN cCompType CHAR, 
                       IN cCompName CHAR, 
                       IN cDesc CHAR, 
                       IN cSev CHAR);
 Create an 'error' element as a sibling of <rCols> using the other parameter values.
Note: Please review usage notes at the end of the table
 
CREATE PROCEDURE NewErrorStuct(IN rInRef REFERENCE, 
                               IN rError REFERENCE);
 Create an 'error' element under <rInRef> and copy error structure from <rError>. 
CREATE PROCEDURE Transmission(IN rObject REFERENCE, 
                              INOUT rCols REFERENCE, 
                              IN cObjType CHAR);
 Create a 'pt' element under <rObject> with type of <cObjType>.

Usage Notes

A number of procedures accept an rCols reference that is defined as INOUT:
  • ObjValueString
  • ObjValueHex
  • ObjValueXml
  • Counter
  • Error
These functions all move the rCols reference to point to the new element such that you can recall the function to add a second, third, fourth etc element. The intended usage of these is that you first complete the creation of all the object col elements under rCols before you proceed to create the secondary items. The application code must also be mindful of the correct element order as per the XSD:
  1. Cols
  2. ObjValue
  3. Counter
  4. Error
A correct usage example is shown below:

CALL PhysicalTransmissionFlow.InitTxnIsf(rTxn, rIsf, isfNS, 'isf', rCols);

CALL MapTransactionISF(rIsf);

CALL PhysicalTransmissionFlow.NewStrCol(rCols, 'CID', rISFPaymInstr.Identification);
CALL PhysicalTransmissionFlow.NewStrCol(rCols, 'UID', rInPmtInf.*:PmtInfId);

CALL PhysicalTransmissionFlow.ObjValueString(rCols, 'cat', 'key1', rIsf.StringData);
CALL PhysicalTransmissionFlow.ObjValueString(rCols, 'cat', 'key2', rIsf.StringData);

CALL PhysicalTransmissionFlow.Counter(rCols, 'name1', 'type', nCount, dAmount);
CALL PhysicalTransmissionFlow.Counter(rCols, 'name2', 'type', nCount, dAmount);

CALL PhysicalTransmissionFlow.Error(rCols, 'cType', 'cScheme', 'cCode', 'cCompType', 'cCompName','cDesc', 'cSev');
CALL PhysicalTransmissionFlow.Error(rCols, 'cType', 'cScheme', 'cCode', 'cCompType', 'cCompName','cDesc', 'cSev');
It is recommended that application code follows this pattern as far as possible.
If the application code wishes to execute these calls in a different order it must be done carefully such that the move of the INOUT reference does not cause breakage. A typical scenario might be the application wishing to create error records during or just after ISF mapping. The below example shows error records created before the column values. This is facilitated by declaring a new reference rErrors and passing that into the Error() function call so as not to move the original reference.

CALL PhysicalTransmissionFlow.InitTxnIsf(rTxn, rIsf, isfNS, 'isf', rCols);

CALL MapTransactionISF(rIsf);

DECLARE rErrors REFERENCE TO rCols; -- create a second reference so as not to move the original rCols
CALL PhysicalTransmissionFlow.Error(rErrors, 'cType', 'cScheme', 'cCode', 'cCompType', 'cCompName','cDesc', 'cSev');
CALL PhysicalTransmissionFlow.Error(rErrors, 'cType', 'cScheme', 'cCode', 'cCompType', 'cCompName','cDesc', 'cSev');

CALL PhysicalTransmissionFlow.NewStrCol(rCols, 'CID', rISFPaymInstr.Identification);
CALL PhysicalTransmissionFlow.NewStrCol(rCols, 'UID', rInPmtInf.*:PmtInfId);

CALL PhysicalTransmissionFlow.ObjValueString(rCols, 'cat', 'key1', rIsf.StringData);
CALL PhysicalTransmissionFlow.ObjValueString(rCols, 'cat', 'key2', rIsf.StringData);

CALL PhysicalTransmissionFlow.Counter(rCols, 'name1', 'type', nCount, dAmount);
CALL PhysicalTransmissionFlow.Counter(rCols, 'name2', 'type', nCount, dAmount);

It is important to note that these helper functions are not the only way to create the document structure. If the application code is structured in a manner that causes these functions to produce an invalid document, it is possible to use basic ESQL statements to supplement or alter the document structure.