Siebel Escript Standards

ING Service Center Claims

Siebel eScript standards

Final 1.0

Date: 09-01-2003

drs. M.A.T. Linssen MA

Document Identification

This document aims to set the standard in Siebel eScript programming. It is based on one man-year hands-on experience with eScript itself, as well as several man-years experience with various other programming languages, such as BASIC, COBOL, C, C++, VB, Qbasic, Clipper; platforms, such as mainframe (OS/390), midframe, (AS/400), Unix (HP-UX, Sun Solaris, AIX), PC (Windows 3.1 through XP, OS/2); scripting languages (Unix shell scripting, Javascript, Rexx, MS-DOS), and several man-years experience in system analysis, system design, system programming and system test.

Rejected remarks

Siebel eScript standardsPage 1

Table of Contents

1Introduction......

2General coding guidelines......

2.1Naming convention......

2.2Whitespace......

2.2.1Tabs and spaces......

2.2.2Whitespace......

Example 1: tabs and spaces......

2.3Comments......

2.3.1Introductory comment......

2.3.2Comment blocks......

2.3.3Line comments......

2.3.4Example 2: comment block and line comment......

2.4Declaration......

2.4.1Example 3: declaration......

2.5Initialisation and assignment......

2.5.1Initialisation......

2.5.2Assignment......

2.5.3String concatenation......

2.5.4Example 4: initialisation......

2.6Destruction......

2.6.1Example 5: destruction......

2.7Statements......

2.7.1Statement block......

2.7.2If statement......

2.7.3Example 6: if statement......

2.7.4FOR loop......

2.7.5DO - WHILE and WHILE loop......

2.7.6Example 6: for loop......

2.7.7Example 7: while loop......

2.7.8Switch and Case statements......

2.7.8.1Switch statement......

2.7.8.2Case statement......

2.7.9Example 8: Switch statement......

2.8Script redirection......

2.8.1Throw statement......

2.8.2Dummy do-while loop......

2.8.3Return......

2.8.4Example 10: return......

2.8.5Example 11: dummy do - while loop with inner loop......

2.9Function calling......

2.9.1Objects......

2.9.1.1Object properties......

2.9.2Variables......

2.9.3Control over properties......

2.9.4Example 12: object and properties......

2.10Error handling......

2.10.1Return......

2.10.2PreInvokeMethod......

2.10.3Output evaluation......

2.10.4Try - catch......

2.10.5Example 13: try-catch......

2.10.6Error logging......

2.10.7Useful generic functions......

2.11Business Services......

2.11.1Multiple business service forming a single logical transaction......

2.11.2Restoring arrays and other objects......

2.12Known Siebel product defects......

2.13Illegal statements and actions......

2.13.1GOTO statement......

2.13.2WITH statement......

2.13.3CONTINUE LABEL statement......

2.13.4Function recursion......

2.13.5Property sets......

2.13.6Returning objects......

2.13.7Arrays with counters of datatype string......

2.13.8Global variables......

2.13.9ForwardOnly on instantiated business components......

2.13.10Vanilla Siebel business services......

2.14Functions......

3General query guidelines......

3.1Business objects and business components......

3.1.1Hierarchical database......

3.2Comparison to SQL......

3.2.1SetViewMode......

3.2.2ActivateFields......

3.2.3ClearToQuery......

3.2.4SetSearchSpec......

3.2.5ExecuteQuery......

3.2.6Example 14: Siebel Query......

3.3Querying......

3.3.1Query Mode......

1 Introduction

This document outlines the guidelines and mandatory standards for ING Service Center Claims eScripting. It is not intended to be a step by step instruction manual on how to script, but lots of hints, tips & tricks and do's & dont's are given. All applies to Siebel 6.x.

It is intended to ensure that any eScripting performed is accurate, easy to read and maintainable. In fact, following these guidelines will result in perfectly clear and legible code. It is a very rigid document, which should be interpreted that way.

The general idea is that one standard will enable all programmers to look at regardless which functionality or technicality and that this code will look AS HIS OR HER OWN CODE. One can imagine the benefits of this.

There can be only one standard, and that standard will have to be used only: if there are any reasons to deviate from that standard, such will first have to be judged by all parties involved: if sensible, it should be judged again: if practical, it should be judged again: if not conflicting with any other standard in this document, it should be incorporated into it.

If not, it should be added to this document as a "rejected remark", preventing others from making the same remark.

2 General coding guidelines

2.1 Naming convention

• Because Siebel eScript automatically converts variables from one type to another when needed, programmers normally do not have to worry about type conversions as they do in strongly typed languages, such as C. (quote from Siebel Bookshelf eScript.pdf)
• The Siebel type conversion is reflected in the naming conventions. As integers can easily be converted to floats, strings, and vice versa, there are only two types: objects and the rest.
  Objects have to be destroyed, the rest doesn't.
  Objects are prefixed by an o (for object), the rest is the rest, and prefixed by nothing:
  Business Objects, Business Components, Property Sets, Arrays, Date objects, Time objects, they are all objects: oINSClaimsBO, oINSClaimsBC, oPropSet, oField, oToday.
  Strings, Integers, Booleans - they're not: Address, Mileage, LegalPersonIndicator
• The main other rule is to use meaningful names: oInput, oOutput, oINSClaimsBC, RecordFound, RowId, Brand, HouseNumber, PostalCode, MaidenName, oToday, TempField, PolicyBranch, RelationNumber, etc.
• Extra identifiers should be added to variables, i.e. suffixing them instead of prefixing them: oINSClaimsBC, not oBCINSClaims, HouseNumber, HouseNumberAddition, HouseNumberAdditionNumericPart, ArraySeparator, and not NumberHouse, NumberAdditionHouse, NumericPartNumberAdditionHouse, SeparatorArray
• Of course, all variables, as well as everything else, are in English.
• Write words like you would write them, and try to capitalize each word within a word, even if they're abbreviations: oINSClaimsBO (copying vanilla name) instead of oInsClaimsBo, oPropSet instead of oPropset, oBusComp, oBusObject, and not oBuscomp, oBusobject, SendReceiveMessage instead of Sendreceivemessage, XMLRequest instead of Xmlrequest, oDateTimeStamp and not oDatetimestamp.

• Reserved words, apart from the Siebel eScript reserved words:
  Output is the value to be returned;
  oInput and oOutput are input and output property sets;
  MethodName is the method to be called;
  exception is reserved for the variable caught in a try-catch.
  

2.2 Whitespace

2.2.1 Tabs and spaces

• All lines start with a tab: in Siebel Tools, tab width should be set to three (via Tools - Options - Scripting).
• The only lines not starting with a tab are the function descriptor and the start- and end brace.
• No line ever starts with spaces: spaces are to be used only at the end of a line or sentence; tabs are be avoided at this point because of possible tab-width differences.
• Spacing and tabbing should be nice, in general: code should read like a book, or rather, like a poem: whitespace must be used to keep code legible, quiet, peaceful, and maybe even a little entertaining: programming and maintaining code is not only a difficult job, but a pretty tiresome one as well. Overview is easily lost if "the code looks like a mess".
• Every variable, identifier and condition should be separated by a space, if applicable (not with auto-increment/-decrement, assignment operators): it doesn't matter for the compiler but it does to the eye!

2.2.2 Whitespace

• Whereever possible, use plenty of whitespace. There will be moments of running into and out of the Siebel 16 KB limit for single functions, at which the best thing to do is to split the whole function in two parts, if possible. Double line feeds make your code breathe, and will only cost you 4 to 6 bytes in general.

2.2.3 Example 1: tabs and spaces

2.3 Comments

• There are several ways of indicating a comment:
  1)// at the beginning of a line will make that whole line a comment;
  2)// at some place in a line will make the rest of that line a comment;
  3)/* will start a comment and end it when */ is encountered: this is the only way to make multiple-line comments, also known as comment blocks.

2.3.1 Introductory comment

• Every function starts with a big comment block naming author, date and functionality. This block also names and describes input and output parameters. An additional block can be used for "special remarks", and every block ends with a revision history block.

2.3.2 Comment blocks

• Of the above possibilities, /* --- */ (option 3 ) is the preferred one for major comments. For minor comments, also known as line comments, // can be used for ends of if-statements, switch-statements, case-statements, do-, while- and for-loops, or any other useful comment.

• For consistency and lay-out, lines within a comment block will start with an extra space, followed by an asterisk.
• All comment blocks start with a tab, one tab only: don't indent comment blocks along with code indenting because you'll soon get out of (legible, visible) space.

2.3.3 Line comments

• Line comments indicating ends of if-statements, do-, while- and for-loops should start one space after the brace, and repeat the whole statement (unless legibility requires otherwise), to be ended by another space and the word "end". This insures consisitency throughout the whole script, although changes in the statement itself must be reflected in the comment!

2.3.4 Example 2: comment block and line comment

2.4 Declaration

• Variables should be declared at the start of a function, after the first comment block. They should be declared alphabetically, because that's how the debugger will show them. Not binary alphabetic, but "just alphabetic": the debugger is case-insensitive!
  The first variables to show in the debugger are the ones passed as parameters to the function: as they'll all be objects anyway, don't worry about the alphabetic order of them: their values are of no use in the debugger. These arguments will be shown in reverse order: the last one first, then the second to last, etcetera.
  A comment block should precede the variables declaration, stating: Variables declaration
• Declaring variables at the uppermost level avoids scope problems, destruction problems, and optimization problems: one single declaration block at the uppermost level enables one single initialisation block, and one single destruction block.
• One line per variable! It is forbidden to declare more than one variable in a single line.
• If a variable is used only once, and if it's to be expected that that will remain the case, it is unnecessary and forbidden to use a variable, unless the alternative (a concatenation or computation of other variables) is too complex.
  On the other hand, if you use a value more than once, it should be made a constant: declare it as a variable.

2.4.1 Example 3: declaration

2.5 Initialisation and assignment

2.5.1 Initialisation

• Variables should be initialised after the start of a function, after the variables declaration block. They should be initialised logically, which means in the most logical order. If not every initialisation has to be in a logical order, group those that do.
• A comment block should precede the variables initialisation, stating: Variables initialisation
• Appropriate line spacing should be used between the logical blocks.
• It is unnecessary and thus forbidden to set variables to null. Treating variables set to null as an object (e.g. by checking length) will convert them to an object!
• Booleans are to be explicitly set to true or false. If a variable is undefined and compared as a boolean, Siebel will return false: in all other cases, Siebel will return true!
• Preferred logical order: Function name, Output, arrays, objects, property sets and services, business objects and business components, counters, booleans, simple variables.
• Appropriate spacing should be used between variables, operators, expressions, etcetera.

• Tabbing the equal sign is nice-looking but senseless, because it is dependent on the length of the longest variables in an initialisation block: therefor it is highly likely that the tab stops of most initialisation blocks are unequal. Moreover, changing the length of a variable will have to result in adjusting the tabs of all assignments!
  It's also conflicting with the general rule of legibility and tab-independency, as well as the major rule that tabs should only be preceded by tabs. That's why it is frowned upon, and forbidden.

2.5.2 Assignment

• Conditional operators are forbidden! An if statement must be used to assign variables a value that is dependent on a condition.

2.5.3 String concatenation

• Whereever a string concatenation is used, every string concatenator should end a line. Appropriate indenting must be used on the next lines: tabs should align these next lines as close as possible to the first word following the equal sign, and space must be used to exactly line them up.

2.5.4 Example 4: initialisation

2.6 Destruction

• To destroy an object in Siebel eScript, set it to null, or set the variable containing it to another value. The best practice is to destroy objects in the order opposite to the order of creation. (quote from Siebel Bookshelf ObjInt.pdf)

• Siebel eScript knows implicit object allocation, and explicit object deallocation: objects are always allocated to memory (and passed by reference), and have to be deallocated in order to free that same memory.
• Although many Siebel Vanilla functions do leak themselves, it is proven that "reverse memory deallocation", i.e. deallocation objects in the reverse order you assigned / initialised them, does help to reduce memory usage. The only possible way to achieve total memory deallocation is to close the Siebel application (sic!).
• Destruction must occurr just before the return.
• A comment block should precede the variables initialisation, stating:
  Return: clean up data associated with objects to deallocate them from memory
• Only objects may be destroyed, it is useless and confusing to set normal variables (non-composite datatypes) to null.
• Appropriate line spacing should be used: try to distinguish logical blocks when deallocating.

2.6.1 Example 5: destruction

2.7 Statements

• Apart from the previously mentioned layout rules and guidelines, there's a general layout rule: make code legible!

2.7.1 Statement block

• A statement block is a group of statements enclosed in braces, {}, which indicate that the enclosed individual statements are a group and are to be treated as one statement. Appropriate use of white space should be used to break up blocks of code. (quote from Siebel Bookshelf eScript.pdf)
• Statement blocks can appear in try-catch statements, if-statements, switch-statements, case-statements, for-loops, do-loops, and while-loops. The braces belong to the block, and therefor must be indented along with it.

2.7.2 If statement

• The if statement must be outlined as follows: one space after the word if, round brackets for the condition and braces for the statement block. No spaces should be used after a begin round bracket, (, and before an end-round bracket, ).
• Logical operators (AND, &, and OR, ||) must start at a new line. Appropriate use of space must be used to line up the various lines comprising the if statement. Use of brackets should be limited, there's no need to use braces for every part of a condition, unless it is absolutely necessary. Don't forget that AND operators take precedence over OR operators.
• Whenever booleans are to be evaluated in an if statement, they must not be compared to true or false, but to the boolean itself: the logical NOT operator, !, must be used to compare it to false

2.7.3 Example 6: if statement

2.7.4 FOR loop

• The for loop is a conditional loop with initialisation, condition and increment. It must be outlined as follows: one space after the word for, round brackets for the statement and braces for the statement block. No spaces should be used after the begin round bracket, (, and before the end-round bracket, ).
• Appropriate spacing should be used: the same rules apply that must be followed for if-statements.

2.7.5 DO - WHILE and WHILE loop

• The do - while loop and while loop are conditional loops, both with a condition. The condition can contain logical operators. It must be outlined as follows: one space after the word do (or while), round brackets for the statement and braces for the statement block. No spaces should be used after the begin round bracket, (, and before the end-round bracket, ).
• Logical operators must start at a new line.
• Appropriate spacing should be used: the same rules apply that must be followed for if-statements.

2.7.6 Example 6: for loop

2.7.7 Example 7: while loop

2.7.8 Switch and Case statements

2.7.8.1 Switch statement

• A switch statement is a conditional statement, which is in fact an if - else if statement where one variable can be compared to several conditions. It must be outlined as follows: one space after the word switch, round brackets for the statement and braces for the statement block. No spaces should be used after the begin round bracket, (, and before the end-round bracket, ).
• A switch consists of at least one case and one default (at the end of the switch statement). All cases and the default end with a colon, :, directly after the last character.

2.7.8.2 Case statement

• Every case must end with a break! The break belongs to the statement block and must be indented accordingly. If there is no break, execution will continue with the next statement block, disregarding the corresponding case!
• A case statement must be outlined as follows: one space after the word case, single or double quotes for the value, a colon directly following the value, and braces for the statement block.

2.7.9 Example 8: Switch statement

2.8 Script redirection

• eScript doesn't offer functions within functions: every function itself is a single entity that is executed in sequential order, must be entered in a separate Designer window, and is stored in a separate column in the database. This is in itself not a problem, but there sometimes is a strong need for halting script execution.

2.8.1 Throw statement

• This can be achieved by the throw() statement, which generates an exception, and will cause the script to redirect itself to the surrounding catch. Throwing is rarely used since it is unlikely that the same error will occur at different places in a program, that is, if you're a good programmer.
  However, not all script halting is caused by an error. eScript offers the break statement to break out of a loop (for-loop, while-loop, do-while loop), and this is very usefull. The throw statement should be avoided, since an exception points to a program technical failure rather than a logical or functional mismatch.

2.8.2 Dummy do-while loop

• Therefor each function must have a do-while loop, with condition false, to enable breaking out of a script at any moment. This loop must start directly after the try clause, and end directly before the catch clause. It must be outlined as follows: a linefeed after the word do, round brackets for the statement block and braces for the condition. No spaces should be used after the begin round bracket, (, and before the end-round bracket, ) of the condition.
• A dummy loop poses problems when there's an inner loop used within: to break out of both loops, a variable must be set. The preferred variable is StopProgram, a boolean which is set to true in the innermost loop directly before the break: after the innermost loop, the boolean must be checked: if true, a break must be issued to break out of the outermost loop (the dummy loop) as well. This mechanism works with countless loops!

2.8.3 Return

• It is technically possible to have as many returns as possible in a script. A return will directly end a script, leaving all objects and variables as they are, unless there is a try-catch-finally construction, where the finally will be executed first, but you'll notice that a little further in this document it is explained why finally clauses are useless and thus forbidden.
• Multiple returns are forbidden: every function must contain at minimum one and at maximum one return. As there is always something to return, this poses no problems at all. It must be outlined as follows: one space after the word return, and round brackets for the return value, which must always be Output. No spaces should be used after the begin round bracket, (, and before the end-round bracket, ).

2.8.4 Example 10: return