ESQL code conventions in WebSphere Message Broker PART 1

1. Introduction

The aesthetics and consistency of source code determines if a program is easy to understand and maintain, which is critical to software development because 80% of its lifetime cost lies in its maintenance and enhancement by many different developers over time. Coding conventions not only help improve code readability, they also discourage the use of wasteful and error-prone programming practices. Coding guidelines can also encourage the development of secure software that has better performance. Finally, should source code need to be shipped as a product, coding conventions can help ensure a quality in presentation.

This article describes coding standards for Extended Structured Query Language (ESQL), emphasizing the use of ESQL in the development of IBM® WebSphere® Message Broker message flow applications. Topics include file naming and organization, file layout, comments, line wrapping, alignment, white space, naming conventions, frequently used statements, and useful programming practices.

2. File naming and organization

The following guidelines should be used when constructing the ESQL files that implement a WebSphere Message Broker application:

• ESQL source files should always have names that end with the extension .esql. For example: NotificationTimeout.esql.
• ESQL filenames should consist of mixed-case alphabetic characters, with the first letter of each word and all acronyms in uppercase. For example: IBMExample.esql.

In general, ESQL files longer than 2000 lines are cumbersome to deal with and should be avoided, by ensuring that a single ESQL file implements the message flows that relate to each other, and by abstracting reusable code into separate ESQL files.

ESQL files can be grouped in broker schemas, which are a hierarchical way of organizing ESQL files. They also serve to create local name spaces so that procedures and functions can be reused, and yet be distinguished by the schema they are in. In short, broker schemas are organizational units of related code that address a specific business or logical problem. Therefore, related ESQL files should be placed in their own schema.

Figure 1. ESQL file organization and layout

3. File layout

The content of each ESQL file should conform to the following standards:

• The file must start with a descriptive header comment, as described in Section 5 below.
• The header comment should be followed by a broker schema declaration and the PATH clauses that specify a list of additional schemas to be searched when matching function and procedure calls to their implementations. Do not use the default broker schema.

  1 2 3

  BROKER SCHEMA com.ibm.convention.sample PATH com.ibm.convention.common; PATH com.ibm.convention.detail;

The remainder of the file should be divided into three sections:

1. Broker schema level variables and constants
   They are not globally reusable and can only be used within the same broker schema.
   EXTERNAL variables are also known as user-defined properties. They are implicitly constant. When you use the NAMESPACE and NAME clauses, their values are implicitly constant and of type CHARACTER.

   1 2 3 4

   DECLARE DAY1 EXTERNAL CHARACTER 'monday'; DECLARE XMLSCHEMA_INSTANCE NAMESPACE 'http://www.w3.org/2001/XMLSchema-instance'; DECLARE HIGH_PRIORITY CONSTANT INTEGER 7; DECLARE processIdCounter SHARED INTEGER 0;

2. Broker schema level procedures and functions
   They are globally reusable and can be called by other functions or procedures in ESQL files within any schema defined in the same or another project.

   1 2 3 4 5 6 7 8 9 10 11 12 13

   CREATE PROCEDURE getProcessId(OUT processId CHARACTER) BEGIN     BEGIN ATOMIC                SET processId = CAST(CURRENT_TIMESTAMP AS CHARACTER FORMAT 'ddHHmmss')                         || CAST(processIdCounter as CHAR);         SET processIdCounter = processIdCounter + 1;     END; END; CREATE FUNCTION encodeInBASE64(IN data BLOB) RETURNS CHARACTER LANGUAGE JAVA EXTERNAL NAME "com.ibm.broker.util.base64.encode";

3. Modules
   A module defines a specific behavior for a message flow node. It must begin with the CREATE node_type MODULE statement and end with an END MODULE statement. The node_type must be either COMPUTE, DATABASE, or FILTER. A module must contain the function Main(), which is the entry point for the module. The constants, variables, functions, and procedures declared within the module can be used only within the module.

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   CREATE FILTER MODULE FilterData     CREATE FUNCTION Main() RETURNS BOOLEAN     BEGIN         DECLARE messageType REFERENCE TO Root.XMLNSC.Msg.Type;         IF messageType = 'P' THEN             RETURN TRUE;         ELSE             IF messageType = 'D' THEN                 RETURN FALSE;             ELSE                 RETURN UNKNOWN;             END IF;         END IF;        END; END MODULE;

4. Naming conventions for

In general, the names assigned to various ESQL constructs should be mnemonic and descriptive, using whole words and avoiding confusing acronyms and abbreviations. Of course, you need to balance descriptiveness with brevity, because overly long names are hard to handle and make code harder to understand. The following table provides naming conventions for ESQL broker schemas, modules, keywords, correlation names, procedures, functions, variables, and constants.

Entity	Naming rules
Schema	A schema name reflects the file system name leading the location of files in this schema. Each level in a schema name is mapped to a directory name. To be supported by any file system, schema names should consist of lower case alphanumeric characters. The names should be prefixed with the reverse of the company URL.	com.ibm.convention. sample
Module	A module name should consist of more than one alphanumeric character, start with an upper case letter, and have mixed case, with the first letter of each internal word and all letters of acronyms in uppercase. It must match any label assigned to a compute, database, or filter node in a message flow that uses the module. If more than one such node in a message flow uses the same module, add additional characters to the node labels in order to differentiate between them.	ConstructInvoice1 ConstructInvoice2 IsReconnect RetrieveIBMData
ESQL keyword	ESQL keywords should be uppercase, although they are not case sensitive.	SET CREATE PROCEDURE TRUE
Field reference or correlation name	A field reference or correlation name should start with an uppercase letter and have mixed case, with the first letter of each internal word and all letters of acronyms in uppercase.	Environment.Variables. Invoice. CustomerNumber
Variable	A variable name should start with a lowercase letter and have mixed case, with the first letter of each internal word and all letters of acronyms in uppercase. Since a variable name should start with a lowercase letter, it should not start with an acronym. Trivial variable names such as i or x can be assigned to temporary variables of limited scope and importance at your discretion.	i invoiceItem currentHL7Section controlReference
Procedure or function	A procedure or function name should consist of more than one alphanumeric character, start with a lowercase letter, and have mixed case, with the first letter of each internal word and all letters of acronyms in uppercase. The first word of the name should be a verb.	setEnvironment computeIBMValue
Constant	A constant name should start with a letter, use all uppercase letters, and use the underscore ( _ ) to separate words.	MIN_VOLUME MAX_RETRIES

Downloadable resources

• PDF of this content