Scribd Logo
Upload

Welcome to Scribd!

  • 11 views

    ESQL Coding and Naming Standards

    Uploaded by

    marina14350

    Copyright:

    © All Rights Reserved
    Download as PDF or read online from Scribd
    Flag for inappropriate content

    You might also like

    ESQL Coding and Naming Standards

    Uploaded by

    marina14350
    11 views11 pages

    Copyright

    © © All Rights Reserved

    Available Formats

    PDF or read online from Scribd

    Did you find this document useful?

    Is this content inappropriate?

    Report this Document

    Copyright:

    © All Rights Reserved
    Download as PDF or read online from Scribd
    Flag for inappropriate content
    Download as pdf
    11 views11 pages

    ESQL Coding and Naming Standards

    Uploaded by

    marina14350

    Copyright:

    © All Rights Reserved
    Download as PDF or read online from Scribd
    Flag for inappropriate content
    Download as pdf
    of 11
    ESQL code conventions in WebSphere Message Broker ‘Summary: ‘These coding conventions for Extended Structured Query Language (ESQL) wil help you develop ESQL ccode that is easy to understand and maintain, Ths ance is for developers using ESQL to implement message flow applications for deployment on WebSphere Message Broker. |. Introduction ‘The aesthetics and consistoney of source code determines if programis easy to understand and maintain, which is critical to software development because 80% ofits litime cost bes in ts maintenance and enhancement by many diferent developers overtime, Coding conventions not only help improve code readabilty, they ako discourage the wse of wastefl and ertor-prone programming practices, Coding guidelines can abo encourage the development of secure software that has better performance, Finally, shoul! source code need to be shipped as a product, coding convertions can help ensure a quality in presentation. ‘This arle deseres coding standards for Extemled Structured Query Language (ESQL), emphasing te use of SQL. inthe development of BM® WebSphere® Message Broker message flow applications. Topics inca fle raming ad organization, fle hyout, comment, line wrapping, alignment, white space, naming conversions, Fequendy used stalemenis, and wef programming practices. 2. File naming and organization ‘The following guidelines should be used when constructing the ESQL. fies that implement a WebSphere Message Broker application: ‘+ ESQL soure fies shoud aways have names that end with the extension esql. For example: NoticatioiTimeout esa ‘+ ESQL flemames should consist of mixed-case alphabeti characters, with the fist eter ofeach word and all acronyms in uppercase. For example: IBMExampl. esq ‘In general, ESQL files longer than 2000 lines are cumbersome to deal with and should be avoided, by ensuring that a single ESQL le implements the message flows that relate to each other, and by abstracting reusable code into separate ESQL fies. ESQ fils can be grouped in broker schemas, which are a hierarchical way of organizing ESQL ies. They also serve create local rame spaces so that procedures and finctions can be reused, and yet be distingished by the scherm they are in. In shor, broker schemas are organizational ui of related code that address a specific business or logical problem. Therefore, related ESQL fies should be placed in their own scheme sgt crvetn seem at ans 938 Soterenss Staoments 3. Fle hyout ‘The content of each ESQL fle should conform to the folbwing standards: 4 The fle must start with «descriptive header comment, as desorbed in Section S below. ‘The header comment should be folowed by a broker schema declaration andthe PATH clauses that specif a lit ‘of adional schemas to be searched when machin finction and procedure cals to their implementations, Do not use the definit broker schema, [BROKER SCHEMA comin. convention. sample ‘The rerminder ofthe fle should be divided ino ee sections: 1. Broker schema level variables and constants “They are not gobully reusable and can only be used win the same broker schema, [EXTERNAL variables are abo known as wser-detned properties They ae impicily constant. When you we the NAMESPACE and NAME clases, des vals are imply constant are of type CHARACTER. DECLARE DAYL EXTERNAL CHARACTER ‘mondays DECLARE AULSCHEMA INSTANCE KAMEGPRCE. *hctps//wuw.w3.org/2001/XMLSenena~inatance's 2. Broker schema level procedures and functions ‘They are globally reusable and can be called by otberfinetions or procedures in ESOL fles win any schema, defined inthe same or another project. (CREATE PROCEDURE getProceasT4(OUT processId CHARACTER) BEGIN Arne SET processid = CAST (CURRENT TIMESTAMP AS CHARACTER FORMAT 'ddiinnss') I casT(procecetdcounter as CHAR) SEP proceserdcounter ~ processZdCounter +17 qf creed nese Heme Dat eons 9389 (CREATE FUNCTION encodeTNBASE64(IN data 5205) Modules ‘A module defies a specie behavior fora message fw node. It must begin withthe CREATE node_ype ‘MODULE statement and end with an END MODULE statement. The rode type mst be ether COMPUTE, DATABASE, or FILTER. A module mast contain the fintion Main), which the entry point for the module ‘The constants, variables, finctions, and procedures declared within the module canbe used only within the module. CREATE FONCTION Main() AETORNS BOOLEAN DECLARE messagetype REFERENCE 70 Root mHINSC.¥9g."yEF 4. Naming conventions In genera the names assigned to various FSQL comsrucs shoul be memonic and descriptive, using whole words and avoiding confsing acronyms and abbreviations. Ofcourse, you need to balance descriptiveness with brevity, because ‘overly long namss are hard to handle and make code hardr to understand. The follwing table proves naming ‘comentions for ESQL broker schemas, modules, keywords, correlation names, procedures, finctions, variables, and constrs. Entity Naming rules Examples Schema ‘A schema name reflects the fle sytem name leading the Icaton of fein hs schema. ach kvelina schemn name mapped toa directory name. To be supported by any com.bm.conveetion. fe system, schema names shoul consist of ower case alphanumeric characters. The sample ‘ams shouldbe prefixed wits the reverse ofthe company URL. ‘A module name should consist of more than one alpharurerc character, tart with an ‘uppercase eter, and have mixed cas, withthe fist ktter ofeach iteral word end allConstructiwoice] Module R= ofacronymns in uppercase, It mast ach ny kbel assed to a compute, Comsrctvoie2 database, or fiter node ina message fw tat uses the module. fmore than one such IsReconnect node ina message fw uses the same module, add addtional characters to the node RetreveIBMData labels in order to dfférenate between them, SET ESQL CREATE Keyword SQL Keywords should be uppercase, although they are not case sense SRC EDURE TRUE Feld refirence A fell reference or corelation tame shoul start with an upperease ter and ave Environment Variables. ‘mixed case, withthe fist eter ofeach itera word and ull ers ofaeronyrs in Invoive. coretionippercase. CustomerNumber qf creed nese Heme Dat eons 9389 comeionmpercase, CustomenNumber ‘A variable name shoul start with lowercase ter and have mixed case, withthe fist [eter ofeach intemal word and alters of acronyms in uppercase. Since a variable \Varible_name sbouid start wit a lowercase lt, it should not start with an acronym. Trivial ‘arable names such as or x canbe assigned to temporary variables of mited scope and inportance at your discretion. A procedure or faneton name should consist of more than one alphanumeric character, rocedurestart wit lowercase eter, and have mixed case, with the fist keer ofeach intemal” stEnvironment or finetonword and al tes of acronyms in uppercase. The fist word ofthe name should be a computeIBMVahe inwoiecliem curentHLTSection controRReference ven. Contant *Otstant name should strt witha eter, use alluppercase ters, and we the MIN_VOLUME underscore (_)1o separate words. MAX_RETRIES 5. Comments ‘The discussion below classifies ESQL comment into one of two classes: Header comments, sed to summarize and demarcate a secon ofan FSQL fle Implementation comments, used to chr tbe meaning ofa piece of SQL logic. 5.1, Header comments Su ik header ‘An ESQIL fie should alvays begin witha fe-header comment that provides the name ofthe fl, a brie synopss ofthe purpose ofthe fe, the copyright, and author formation. The exzmple below dhstrates one poste format for such 2 beader, but any sutable aternative that clearly conveys the same information s acceptable. The header is 80 characters in kgth. The description text should consést of complete sentenes, wrapped as needed without using lyphenation. List cach aubor ona separate Ine. File nana: Workfsle.eaql Purpose: Sample ESQL file with proper prologue. "Ankor Upachyaya pate 21 Maren 2008 authore: Rachel shen + copyright 18M canada uta. 2008, ALL rights reserved. ‘Module header [Every module defikon must be preceded by a module eader comment. A module header contains descriptive text that consists of complete sentences, wrapped as needed without using hyphenaton: - + Module description goes here u qf creed nese Heme Dat eons 9389 5.1.3. Procedure header Bvery procedure defntion mst be preceded by a procedure header comment. A procedure header contains descriptive ‘ext that cons of compte sentences, wrapped as needed without using hyphenaton. This header should alo ame and describe each ofthe parameters handled by the procedure, classifi them as type IN, OUT, or INOUT. The parameter descriptions need not consist of compte sentences ~ brie, descriptive phases shoud suf. However, they should be preceded by a hyphen and propery aligned with one another: C + Procedure description goes here. + nv: REFERENCE paraneteri ~ Description goes here. ” 5.1.5. Funtion header Function headers are essently the same as procedure headers nr + runction description goes here. + nv: REFERENCE paraneteri ~ Description goes here. + niour: INTEGER paranetez? ~ Description goes here. ‘RETURNS: SOOLEAE 46° Description goes here. 7 ‘5.2. Implementation comments ‘Add comments to ESQL source code to crf program logic and convey information that & not immediately obvious ‘fom inspecting the code. Do not add too many comments ~ they can become redundant, complicate code maintenance, and get out of date as the sofware evoles. In general, too many comments indicate poorly writen code, because well ‘writen code tends to be se explanatory. Implementation comments can be writen in singl-Ine, block, or aig fom, as deserbed below. 52.1. Singl-ne comments A single-lne commen is a short comment that explins and alls with the code tht flows it I shouldbe preceded by singe blank ine ad inemedately flowed by the code that it describes: qf creed nese Heme Dat ene 930-4 5.2.2. Block comments Block comments are used to provide descriptions of ESQL. fs, modules, procedures, and fintions, Use Block comment atthe beginning of each fie and before each moduie, procedure, and fincton. You can abo use them anywhere inan ESQL. fic. Block comments inside a fincton or procedure shoul be indented at the same eve asthe code they deserbe. Precede a block comment by a single blank tne and irmedistely flow it by the code it describes "Because shorter coments wih expressive eode are always preferable to lengthy block comment, block comments shouldbe rarely used within a procedure or fincton, Example ofa block commen: + within @ procedure or function. y 2F condition THEN ere =x ty 32.3. Tralng comments ‘Tralng comments are brief remarks on the sure ne asthe code they refer to. Inden these comments to clearly separate them fom the relevant code. [several vaing comments rete to the same segmere of code, align the commen with ‘one another, Trang comments are wal brief phrases and need not be complete sentences 2F condition THEX Serre xt ys => trailing coment 1 SET 2 = (ey; comment 2, aligned with comment 1 6. Style mideines 6.1, Line wrapping and alignment Lines of SQL source code shoul be wrapped and algned according to the bwing guidelines: Every statement shou be placed on a separate tn. * Lines ionger than 80 characters shout be avoided as they exceed the def with of many terminals and development to's. + The uit of indentation used to align ESQL source code shoud be four characters which s the defi seting in the ‘WebSphere Message Broker Toolkit, The specie constuction ofthis indentation using spaces or tabs eto the discretion ofthe programmer. Line engl should be ited by breaking lng expressions according to the owing rus: Lines should be as ong as possible, witout exceeding 80 characters; ‘Break afr a comma; ‘Break befbre an operator; Break at the highest vel possible in the expression: ‘Align a new ine withthe begining ofthe expression a he same lvelon the preceding lin. Shou tis alignment equie deep indentations tht produce awkward code, an indentation of eight spaces may be wsed instead. ‘The folbwing ESQL code samples state the above rules. qf creed nese Heme Dat eons 9389 1X Longexpzesston? CHAR, Our longtapression? NIMGER, INOUT longexproscion CHAR) CALL procedurel (nyLongVariablel, nyLongVariable2, nyLongVariabie3, ‘mylongvariabied) ‘ser returnvalue = function! (argument, argument2, szgunent3, Fonction? argument, argument, azgunent6}) Ser finalderslt = (( / varéablel) + (varisble2 ~ varsabie3)) yt variables)? ‘The ESQL sample below ustates «case where an indentation of eight spaces shouldbe used instead ofthe usual alert to avoid deeper indentations that would resul in confxing code. CREATE PROCEDURE showaveryLongProcedureNiane IN azgusent1, uF azgunene3) Fully, the ESQL samples below isirats line wrapping and alignment practices. The fis is preferable because the Ine ‘break i serted atthe highest level possible ‘SET longwanel = Longtane2 * (Lonatane3 + longMano4 - longvanes) 74 longnaneé; > PREFER, SEP longuanel ~ Longhane2 * (LenglaneS + tongvaned “ionawanes) +4 * ongnaneér = avoro 6.2. White space ‘White space should be used to inprove code readily. Insert two blank tines between sections ofa ESQL fle; Insert one blink Ene between fictions and procedures; Insert one blank ine between the variable declarations fa finctonprocedure and is fst statement; Insert one blank ine before a block or singe-ine comment, ‘A blank space should flow each comma in ay FSQlL statement that makes we of commas ouside ofa string tera, * Allbisry operators shouldbe separated ftom ther operands by spaces, Seta teeb) / (et as 7. Statemens Each line should contain at most one statement Here are some samp statements 7.1, DECLARE Put declarations right flr the broker schemas ora the beginning of meds, finctons, and procedures. One

    You might also like