ESQL short course

ESQL
• Extends the constructs of the SQL language to define the behavior of
nodes in a message flow
– Test, calculate, and manipulate fields in logical message
– Reference message header fields
– Change field properties
• Based upon standard SQL 3

Examples:
RETURN Body.Msg.Name = 'IBM';
SET OutputRoot.XML.Msg.Name = 'IBM';
SET OutputRoot.XML.Msg.Name=InputBody."First.Name";

OrderMsg sample message

<OrderMsg>
<OrderData Nr=”300524” Date=”2001-11-05”/>
<Customer Nr=”123456” FirstName=”Andrew” LastName=”Smith” />
<OrderItem Nr=”111” Price=”27.95” InStock=”100”>
<Quantity>2</Quantity></OrderItem>
<OrderItem Nr=”222” Price=”8765.12”>
<Quantity>2</Quantity></OrderItem>
<OrderItem Nr=”333” Price=”3.75” InStock=”456”>
<Quantity>10</Quantity>
<Discount>3</Discount></OrderItem></OrderMsg>
Some ESQL syntax
• ESQL keywords not case-sensitive
SET set SeT.....
• CorrelationNames and field references are case-sensitive
OutputRoot, InputBody.Msg.field .....
• ‘Character constants’ and literals enclosed with single quotation
marks (‘ ’)
• “Field references” enclosed with double quotation marks (“ ”) if:
– Special characters in name, such as a blank space
– Name is an ESQL reserved word
• Statement delimiter: semicolon (;)
• Comments
one line: -- (two dashes)
block: /*..comment here ..*/

ESQL data types: Numeric and string

• DECIMAL
precision 1 to 31, scale 0 to 30
SQL_C_CHAR

• FLOAT
1.23e-45 6.7890E2 (64bit)
SQL_C_DOUBLE

• INTEGER, INT
+123 -890 0x123ab 0X3B
64-bit 2-complement form
SQL_C_LONG

• BIT
b'10110'
• BLOB
x'3C493E'
8-bit bytes, 2 digits per byte
SQL_C_BINARY

• CHARACTER
'ABC '='ABC'
SQL_C_CHAR

DECLARE MyDec DECIMAL 12345678.1111112;

SET OutputRoot."BLOB"."BLOB"=x'3C493E';
ESQL data types: Date, time, boolean
• DATE
DATE '2001-10-03'
SQL_C_DATE

• TIME
TIME '23:09:01.123456'
SQL_C_TIME

• TIMESTAMP
TIMESTAMP '2001-10-03
23:09:01.123456'
SQL_C_TIMESTAMP
• GMTTIME, GMTTIMESTAMP
Greenwich Mean Time

• INTERVAL
either YEAR and MONTH
variable length
or DAY HOUR MINUTE SECOND
fixed length
INTERVAL '90' MINUTE
INTERVAL '1-06' YEAR TO MONTH

• BOOLEAN
TRUE, FALSE, UNKNOWN (NULL)
SQL_C_BIT

Declare V1 Interval (CURRENT_DATE - Date '2000-01-01') DAY;

Declare V2 Interval (CURRENT_TIME - Time '09:00:00') HOUR TO
SECOND;

Moving reference variables

• Move cursor
 PARENT
 PREVIOUSSIBLING
 NEXTSIBLING
 FIRSTCHILD
 LASTCHILD
DECLARE myRef REFERENCE TO InputBody.OrderMsg;
MOVE myRef FIRSTCHILD;
MOVE myRef NEXTSIBLING NAME 'OrderItem';
MOVE myRef LASTCHILD TYPE XMLNSC.Attribute;
MOVE myRef PREVIOUSSIBLING REPEAT TYPE;

 Check success of MOVE or DECLARE...REFERENCE

WHILE LASTMOVE(myRef) DO...
Field references in tree structures
• Paths are dot separated
[i] Index (Origin 1; <1 is LAST)
[ ] Array of (a list)
( ) Search for type (Name, XMLNSC.Attribute and so forth)
: Namespace followed by name
* Any element of any type, name, value (or namespace)
{ } Evaluate this expression (must yield CHAR string)

Examples:
DECLARE i INTEGER CARDINALITY(InputRoot.*[]);
SET rowCust.{'Customer-'||C} = InputBody.Customer[<2];
SET OutputRoot.MRM.addr:addressDetails.addr:postcode = 'ZZ01
4WW';
SET OutputRoot.XMLNSC.A.(XMLNSC.Attribute)B = 3;

ESQL operators
• Arithmetic
+ -
numeric, datetime, intervals
* /
numeric, intervals
unary (negation) -
numeric, intervals
concatenate ||
strings
Order of precedence

• Logical
AND, OR, NOT
Boolean

• Comparison
< > <= >= <> =
BETWEEN
3 BETWEEN 1 AND 10
IN
'A' IN (1,'ABC',123.4,'A')
LIKE
multiple characters: %
'ABC' LIKE 'A%' true
single character: _
'ABC' LIKE 'A_' false
IS, IS NOT
test for NULLs
NULL, UNKNOWN, TRUE, FALSE
myVar IS NOT NULL
Deleting and reordering fields
• Delete a field or structure
– Delete and free memory; useful for large messages
DELETE FIELD OutputRoot.XMLNSC.OrderMsg.Customer;
DECLARE myRef REFERENCE TO
OutputRoot.XMLNSC.OrderMsg.OrderItem[1];
DELETE NEXTSIBLING OF myRef;
– Set to NULL
SET OutputRoot.XMLNSC.OrderMsg.OrderItem[2]=NULL;
– Detach (cut and paste)
DETACH myRef;

• Reorder: paste detached structure to new position in message tree

ATTACH myRef TO OutputRoot.XMLNSC.OrderMsg
AS FIRSTCHILD;

CREATE
• Create new fields (tags) or attributes
– At any point in message
– A scalar field
SET OutputRoot=InputRoot;
CREATE FIELD OutputRoot.XMLNSC.OrderMsg.Customer.AnAttr
TYPE XMLNSC.Attribute VALUE 'C';
DECLARE myRef REFERENCE TO OutputRoot.XMLNSC;
CREATE PREVIOUSSIBLING OF myREF DOMAIN 'MQRFH2';
– Or a structure (per dupli cation)
DECLARE myRef REFERENCE TO OutputRoot.XMLNSC.OrderMsg;
CREATE FIRSTCHILD OF myRef
FROM InputBody.OrderMsg.OrderItem[3];

NULL value
• NULL is distinct state
– Not 0 or ' '
– SQL_NULL_DATA
– All ESQL datatypes (except REFERENCE)
• If value is
– Unknown
– Undefined
– Uninitialized
• General rule: If any operand is NULL then value is NULL
• Use NULL to delete field or structure
Example:
SET OutputRoot.XMLNSC.Msg.Field=NULL;
SET OutputRoot.XMLNSC.Msg.F2= InputBody.Msg.Unknown;
CAST: Transform into other data type
• CAST can convert character string into BLOB or BIT and vice versa,
if CCSID and ENCODING specified

• ESQL generally does not do automatic casting

– Runtime error if SET MyChar=MyInteger;
– Some implicit CASTs for comparison and arithmetic operators
– Recommendation: If in doubt, CAST

• CAST can use format patterns as in EXCEL and ICU

DECLARE B BLOB X'48656c6c6f';
DECLARE S CHAR CAST(B AS CHAR); Output: 'X''48656c6c6f'''
SET S = CAST(B AS CHAR CCSID 850); Output: 'Hello'
SET S = CAST(CURRENT_DATE AS CHAR FORMAT 'dd-MM-yy')
Output: '24-10-05'

Some functions for date and time

DECLARE D DATE CURRENT_DATE;
DECLARE T TIME CURRENT_TIME;
DECLARE TS TIMESTAMP CURRENT_TIMESTAMP;
DECLARE GT GMTTIME CURRENT_GMTTIME;
DECLARE IV INTERVAL LOCAL_TIMEZONE;
DECLARE I INTEGER;
SET I = EXTRACT(HOUR FROM CURRENT_TIME);

Some string functions

DECLARE I INTEGER;
SET I = POSITION('or' IN 'Hello World'); Output: 8
SET I = LENGTH('Hello World'); Output: 11
DECLARE S CHARACTER;
SET S = SUBSTRING('Hello World' FROM 8 FOR 2); Output: 'or'
SET S = OVERLAY('Hello World'
PLACING 'My' FROM 1 FOR 5); Output: 'My World'
SET S = REPLACE ('Hello','l','xx'); Output: 'Hexxxxo'
SET S = REPLICATE ('Hello',3); Output: 'HelloHelloHello'
SET S = TRANSLATE ('Hello World','eo','a'); Output: 'Hall Wrld'
SET S = TRIM(LEADING '!' FROM '!Hello!'); Output: 'Hello!'
SET S = TRIM(BOTH ' ' FROM ' Hello '); Output: 'Hello'
SET S = UPPER('Hello'); Output: 'HELLO'
SET S = LOWER('Hello'); Output: 'hello'
SET S = 'Hello' || 'World'; Output: 'HelloWorld'
Some numeric functions
CEIL(3.673); Result: Round up to next integer, returns 4.0
FLOOR(3.673); Result: Round down to previous integer, returns 3.0
ROUND(3.673, 1); Result: Round with given precision, returns 3.7
TRUNCATE(3.673, 1); Result: Truncate to given precision, returns 3.6
ABS(-3.673); Result: Absolute value, returns 3.673
MOD(3,7); Result: Modulus (remainder), returns 1
SQRT(4); Result: Square root, returns 2E+1
DECLARE I INTEGER;
SET I = BITAND(7,12); Result: Bitwise AND for integers, returns 4
Other functions: BITNOT, BITOR, BITXOR
Many more mathematical functions for trigonometry, and so forth

Some list functions

•EXISTS Are there any elements in a list (TRUE or FALSE)
•SINGULAR Is there exactly one element in a list? (TRUE or FALSE)
•CARDINALITY How many elements is a list (INTEGER count)
•THE Returns the first element of a list

>--EXISTS--(--ListExpression--)-->>
>--SINGULAR--(--ListExpression--)-->>
>--CARDINALITY--(--ListExpression--)-->>
>--THE--(--ListExpression--)-->>

where ListExpression is any expression which returns a list

•Any SELECT expression,

•LIST constructor
•Field reference having the array indicator [ ]

IF statement
IF InputBody.Message.Department = 'Sales‘
THEN
SET OutputRoot.XMLNSC.Msg.Type = 'S';
SET OutputRoot.XMLNSC.Msg.DeptNo = '4711';
ELSE
SET OutputRoot.XMLNSC.Msg.Type = 'X';
SET OutputRoot.XMLNSC.Msg.DeptNo = '9999';
END IF;
CASE function
• Like ?: Expression in C, but more powerful
• Simple form: 1:n test
SET OutputRoot.XMLNSC.Msg.Type = CASE InputBody.Msg.Department
WHEN 'Sales' THEN 'S'
WHEN 'Distribution' THEN 'D'
ELSE 'X'
END;

• Searched form: n:n test

SET OutputRoot.XMLNSC.Msg.CustomerType = CASE
WHEN InputBody.Msg.Custno = '007' THEN 'TopSecret'
WHEN InputBody.Msg.OrderValue > 100000 THEN 'HighValue'
ELSE 'Normal'
END;

• Specialized: NULLIF
SET OutputRoot.XMLNSC.Msg.CustNo =
NULLIF(InputBody.Msg.Custno,'007')

CASE statement
• Like SWITCH statement in C, but more powerful
• Evaluates and executes multiple statements
• Simple form: 1:n test

CASE InputBody.Msg.Department
WHEN 'Sales' THEN SET OutputRoot.XMLNSC.Msg.Type = 'S';
WHEN 'Distribution' THEN CALL handleDistribution();
ELSE
CALL handleUnknown();
RETURN;
END CASE;

• Searched form: n:n test

CASE
WHEN InputBody.Msg.Custno = '007' THEN
SET OutputRoot.XMLNSC.Msg.CustomerType='TopSecret';
WHEN InputBody.Msg.OrderValue > 100000
THEN CALL handleHighValue();
END CASE;

WHILE
Use a WHILE loop to repeat a sequence of statements, for example:

DECLARE I INTEGER 1;
WHILE I <= 10 DO
SET OutputRoot.XMLNSC.Msg.MYARRAY[I] = I;
SET I = I + 1;
END WHILE;
Procedures
• Subroutines with IN, OUT, and INOUT parameters and optional RETURNS value
– Can be used recursively
– Language can be ESQL, Java or database (stored procedure)

CREATE PROCEDURE navigate (IN root REFERENCE, INOUT answer

CHARACTER)
LANGUAGE ESQL
BEGIN
SET answer = answer||’Reached Field...Name:’||FIELDNAME(root);
DECLARE cursor REFERENCE TO root;
MOVE cursor FIRSTCHILD;
IF LASTMOVE(cursor) THEN
SET answer = answer || ’Field has children... drilling down ’;
ELSE
SET answer = answer || ’Listing siblings... ’;
END IF;
WHILE LASTMOVE(cursor) DO
CALL navigate(cursor, answer);
MOVE cursor NEXTSIBLING;
END WHILE;
SET answer = answer || ’Finished siblings... Popping up ’;
END;

Inserting, updating, and deleting fields

• SET modifies field or structure if it exists
• SET appends field or structure (and the entire path) if it does not
exist
• SET...=NULL deletes field or structure
• Order of ESQL statements determines field order
Example:
CALL CopyMessageHeaders();
SET OutputRoot.XMLNSC.Msg.A.B.C = 1;
SET OutputRoot.XMLNSC.Msg.E = 2;
SET OutputRoot.XMLNSC.Msg.D = 3;
SET OutputRoot.XMLNSC.Msg.E.B.C = 4;
SET OutputRoot.XMLNSC.Msg.A.B.C = 5;
SET OutputRoot.XMLNSC.Msg.E.B = NULL;
Powerful ESQL syntax
PRODUCTS table:
PRODNO DESCR

333 Grapes

222 Oranges

111 Apples

ESQL:
SET OutputRoot.XMLNSC.OrderMsg.OrderItem[]=
(SELECT I.Nr, D.DESCR AS Description
FROM InputBody.OrderMsg.OrderItem[] as I,
Database.PRODUCTS as D
WHERE I.Nr = D.PRODNO);

Input Message:
<OrderMsg>
<OrderItem>
<Nr>111</Nr>
<Price>27.95</Price>
<Quantity>2</Quantity>
</OrderItem>
<OrderItem Discount="3">
<Nr>333</Nr>
<Price>100.75</Price>
<Quantity>1</Quantity>
</OrderItem>
</OrderMsg>

Output Message:
<OrderMsg>
<OrderItem>
<Nr>111</Nr>
<Description>Apples</Description>
</OrderItem>
<OrderItem>
<Nr>333</Nr>
<Description>Grapes</Description>
</OrderItem>
</OrderMsg>
Typical node ESQL
• Compute, Filter, and Database nodes are associated with one and
only one ESQL module
– Must be module for the type of node
CREATE FILTER MODULE <MyFilterModule>.......
– Modules can be reused by other nodes

• Each module contains a function called Main which is the entry point
at which the processing of the node starts
• RETURN value controls message propagation to output terminals
– Filter node
return TRUE; return FALSE; return UNKNOWN;
Propagates to respective terminal
RETURN;
Propagates to FAILURE terminal

– Compute and Database node

RETURN; and RETURN TRUE; Propagates to OUT terminal
RETURN FALSE or UNKNOWN Message is not propagated

Some ESQL syntax

• ESQL keywords not case-sensitive
SET set SeT.....
• CorrelationNames and field references are case-sensitive
OutputRoot, InputBody.Msg.field .....
• “Character constants” and literals enclosed with apostrophes
• “Field references” enclosed with quotation marks if:
– Special characters in name, such as blank
– Name is an ESQL reserved word
• Statement delimiter: ; (semicolon)
• Comments
one line: -- (two dashes)
block: /*..comment here ..*/

Variables
• Scalar and fixed data type
• Tree structures (ROW and REFERENCE)
>-DECLARE-+----Name-----+--+----------+-DataType-+--
+---------------+-->>
+--<<--,--<<--+ +-CONSTANT-+ |+-InitialValueExpr-+
+--NAMESPACE----------+
+--NAME---------------+
DECLARE var, I INTEGER 1;
DECLARE addr NAMESPACE ‘http://www.ibm.com/address’;
DECLARE course CONSTANT CHAR ‘WM663’;
Variable scope, lifetime, and sharing
• Scope: Where the variable appears
Examples: node, flow, execution group, broker

• Lifetime: Variable duration

Examples: code block, module, thread

• Sharing: Thread visibility

– Flow or execution group stopping ends SHARED variable lifetime
– ATOMIC blocks can serialize access to SHARED variables
Example:

DECLARE s_counter SHARED INT 1;

……
BEGIN ATOMIC
SET s_counter = s_counter+1;
END;

Special ESQL data types for tree structures

• ROW: named tree with dynamic data type for leaf nodes
– Copies or subsets of other ROWs > Like Root
– SELECT results
– Built using ROW() function
DECLARE rowCust ROW InputRoot.XMLNSC.OrderMsg.Customer;
SET rowCust.Address = ROW('Hursley' AS Town, 'UK' AS
Country);
– REFERENCE: tree cursor
Warning: reference to non-existing field points to Root, so check success of
declaration with FIELDNAME or LASTMOVE
DECLARE refCust REFERENCE TO InputBody.OrderMsg.Customer;
IF LASTMOVE(refCust) THEN……
IF FIELDNAME(refCust) <> ‘Customer’ THEN... .
– SET refCust not allowed

Sample Compute node ESQL for MRM

CREATE COMPUTE MODULE Output_in_3_formats_with_missing_elements
CREATE FUNCTION Main() RETURNS BOOLEAN
BEGIN
CALL CopyMessageHeaders();
SET OutputRoot.Properties.MessageSet='My_Set';
SET OutputRoot.Properties.MessageType='AddressesMsg';
-- omit HomeAddress fields
SET OutputRoot.MRM.WorkAddress.Line[1]='Mail Point 135';
SET OutputRoot.MRM.WorkAddress.Line[2]='Hursley Park';
SET OutputRoot.MRM.WorkAddress.Country='UK';
SET OutputRoot.MRM.WorkAddress.Zip='SO21 2JN';
 SET OutputRoot.Properties.MessageFormat='Binary1';
PROPAGATE DELETE NONE;

SET OutputRoot.Properties.MessageFormat='XML1';
PROPAGATE DELETE NONE;

SET OutputRoot.Properties.MessageFormat='Text1';
RETURN TRUE;
END;

1. ESQL to fill AddressesMsg and output same content in three

physical formats.

2. PROPAGATE DELETE NONE propagates the message but does not

delete the output buffer.

3. RETURN TRUE statement is identical to PROPAGATE statement

ESQL Database
Insertion:
INSERT INTO Database.DSN2.Schema2.PRICEDATA
(PRODUCT_NAME, ITEM_PRICE, STATUS)
VALUES (Body.Message.ProductID,
Body.Message.UnitPrice,'OPEN');

PASSTHRU example
• PASSTHRU function to issue complex SELECTS
Example:
SET OutputRoot.XMLNSC.Msg.Results[]= PASSTHRU(
'SELECT WORKDEPT, MAX(SALARY) AS MaxSalary
FROM schema1.EMPLOYEE
GROUP BY WORKDEPT
HAVING MAX(SALARY) > ?'
TO Database.SAMPLE
VALUES(InputBody.Msg.Salary));

•PASSTHRU statement to issue administrative commands to

Database

•Use parameter markers for performance

THE (SELECT …)
• SELECT returns a list
SET OutputRoot.XML.Msg.Name[]=
(SELECT E.LASTNAME
from Database.EMPLOYEE as E);
Msg 
Name  LASTNAME  Haas
Name LASTNAME  Thompson

• THE (SELECT …) returns the first element of a list

SET OutputRoot.XML.Msg.Name =
THE(SELECT E.LASTNAME
from Database.EMPLOYEE as E);

Msg Name  LASTNAME  Haas

SELECT (ITEM …)
• SELECT (ITEM..) gets value only
– Without the ITEM keyword, the database table column name or XML tag will
be used as message tag
– Can be overridden by AS keyword in SELECT statement

SET
OutputRoot.XML.Msg.Name[]=
(SELECT E.LASTNAME from
Database.EMPLOYEE as E);

Msg
Name LASTNAME Haas
 Name LASTNAME Thompson

SET
OutputRoot.XML.Msg.Name[]=
(SELECT ITEM E.LASTNAME from
Database.EMPLOYEE as E);

Msg
Name Haas
 Name Thompson