siebel escript standards - 21gradi | il blog personale di · web viewnaming convention because...

ING Service Center Claims

Siebel eScript standards

Final 1.0

Date: 09-01-2003

drs. M.A.T. Linssen MA

Document IdentificationAuthor drs. M.A.T. Linssen MA

Document Name Siebel eScript standards

Version Final 1.0

Issue Date 09-01-2003

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

Author Date Suggestion and comment

Siebel eScript standards

Table of Contents1 INTRODUCTION.................................................................................................................................. 5

2 GENERAL CODING GUIDELINES....................................................................................................6

2.1 NAMING CONVENTION....................................................................................................................... 62.2 WHITESPACE..................................................................................................................................... 7

2.2.1 Tabs and spaces........................................................................................................................ 72.2.2 Whitespace............................................................................................................................... 7Example 1: tabs and spaces..................................................................................................................... 7

2.3 COMMENTS....................................................................................................................................... 82.3.1 Introductory comment...............................................................................................................82.3.2 Comment blocks........................................................................................................................ 82.3.3 Line comments.......................................................................................................................... 82.3.4 Example 2: comment block and line comment...........................................................................8

2.4 DECLARATION................................................................................................................................... 92.4.1 Example 3: declaration............................................................................................................. 9

2.5 INITIALISATION AND ASSIGNMENT....................................................................................................102.5.1 Initialisation........................................................................................................................... 102.5.2 Assignment.............................................................................................................................. 102.5.3 String concatenation............................................................................................................... 102.5.4 Example 4: initialisation......................................................................................................... 10

2.6 DESTRUCTION................................................................................................................................. 112.6.1 Example 5: destruction........................................................................................................... 11

2.7 STATEMENTS................................................................................................................................... 122.7.1 Statement block....................................................................................................................... 122.7.2 If statement............................................................................................................................. 122.7.3 Example 6: if statement........................................................................................................... 122.7.4 FOR loop................................................................................................................................ 132.7.5 DO - WHILE and WHILE loop................................................................................................132.7.6 Example 6: for loop................................................................................................................ 132.7.7 Example 7: while loop............................................................................................................. 132.7.8 Switch and Case statements.....................................................................................................14

2.7.8.1 Switch statement................................................................................................................................142.7.8.2 Case statement...................................................................................................................................14

2.7.9 Example 8: Switch statement...................................................................................................142.8 SCRIPT REDIRECTION....................................................................................................................... 15

2.8.1 Throw statement...................................................................................................................... 152.8.2 Dummy do-while loop............................................................................................................. 152.8.3 Return..................................................................................................................................... 152.8.4 Example 10: return................................................................................................................. 152.8.5 Example 11: dummy do - while loop with inner loop...............................................................16

2.9 FUNCTION CALLING......................................................................................................................... 172.9.1 Objects.................................................................................................................................... 17

2.9.1.1 Object properties................................................................................................................................172.9.2 Variables................................................................................................................................ 172.9.3 Control over properties........................................................................................................... 172.9.4 Example 12: object and properties..........................................................................................18

2.10 ERROR HANDLING........................................................................................................................... 192.10.1 Return..................................................................................................................................... 192.10.2 PreInvokeMethod.................................................................................................................... 192.10.3 Output evaluation................................................................................................................... 192.10.4 Try - catch.............................................................................................................................. 192.10.5 Example 13: try-catch............................................................................................................. 202.10.6 Error logging.......................................................................................................................... 202.10.7 Useful generic functions.......................................................................................................... 20

Project Name – Siebel eScript standards

2.11 BUSINESS SERVICES......................................................................................................................... 222.11.1 Multiple business service forming a single logical transaction................................................222.11.2 Restoring arrays and other objects..........................................................................................22

2.12 KNOWN SIEBEL PRODUCT DEFECTS..................................................................................................232.13 ILLEGAL STATEMENTS AND ACTIONS................................................................................................24

2.13.1 GOTO statement..................................................................................................................... 242.13.2 WITH statement...................................................................................................................... 242.13.3 CONTINUE LABEL statement.................................................................................................242.13.4 Function recursion.................................................................................................................. 242.13.5 Property sets........................................................................................................................... 242.13.6 Returning objects.................................................................................................................... 242.13.7 Arrays with counters of datatype string...................................................................................242.13.8 Global variables..................................................................................................................... 252.13.9 ForwardOnly on instantiated business components.................................................................252.13.10 Vanilla Siebel business services...........................................................................................25

2.14 FUNCTIONS...................................................................................................................................... 26

3 GENERAL QUERY GUIDELINES....................................................................................................28

3.1 BUSINESS OBJECTS AND BUSINESS COMPONENTS...............................................................................283.1.1 Hierarchical database............................................................................................................. 28

3.2 COMPARISON TO SQL...................................................................................................................... 283.2.1 SetViewMode.......................................................................................................................... 283.2.2 ActivateFields......................................................................................................................... 283.2.3 ClearToQuery......................................................................................................................... 283.2.4 SetSearchSpec......................................................................................................................... 283.2.5 ExecuteQuery......................................................................................................................... 293.2.6 Example 14: Siebel Query.......................................................................................................29

3.3 QUERYING....................................................................................................................................... 293.3.1 Query Mode............................................................................................................................ 29


1 IntroductionThis 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


function Service_PreInvokeMethod(MethodName, oInput, oOutput){

/* ******************************************************************************** * Generic function for interface definitions * ******************************************************************************** * Author: drs. M.A.T. Linssen MA, CGEY NL * * Date-written: 01-07-2002 * ******************************************************************************** * This function generically defines an interface through 7 arrays * ******************************************************************************** * Input: * * MethodName Method to be called with this business service * * oInput Input property set * * oOutput Output property set * * * * Output: * * oOutput Output property set containing joined arrays * ******************************************************************************** */

var Output;

Output = ContinueOperation;

return (Output);}

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


/* * Main: tell user the truth */

if (true){TheApplication().MsgBox("It's true!");} // if (true) end

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


/* * Variables declaration */

var i;var j;var oINSClaimsBC;var oINSClaimsBO;var oInput;var oInterfaceService;var oOutput;var Output;var Organization;var PolicyBranch;var RecordFound;var Role;

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


/* * Variables initialisation */

oInput = TheApplication().NewPropertySet();oOutput = TheApplication().NewPropertySet();

oInterfaceService = TheApplication().GetService("SCC Interface");

Welcome = "Hello " + UserName + ", how are you?";

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


/* * Return: clean up data associated with objects to deallocate them from memory */

oINSClaimsBO = null;oINSClaimsBC = null;

oInterfaceService = null;oOutput = null;oInput = null;

return (Output);}

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


if ((Attribute[i] == "Attribute name=Category type=str"&& Role.toUpperCase() == "VERZEKERINGNEMER")|| (Attribute[i] == "Entity "&& (Role.toUpperCase() == "BESTUURDER"|| Role.toUpperCase() == "GETUIGE"|| Role.toUpperCase() == "TEGENPARTIJ"|| Role.toUpperCase() == "VERZEKERDE")))

{Data[d][0] = i;if (!Skip[i])

{Data[d][1] = oBusComp.GetFieldValue(Field[i]));}

else{Data[d][1] = "";}

}

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


for (i = 0, d = 0; i < Data.length; d++){i = Data[d][0];oSCCPropertySet[Child[i]] = TheApplication().NewPropertySet();

if (Attribute[i] == ""){oSCCPropertySet[Child[i]].SetType(Field[i]);}

...

...} // for (i = 0, d = 0; i < Data.length; d++) end

while (RecordFound){Interface.ClaimId = oINSClaimsBC.GetFieldValue("Id");

SCCLogErrors(Interface);

oInput.SetProperty("Id", Interface.ClaimId);oInterfaceService.InvokeMethod("SCCHandleInterfaceRequest", oInput, oOutput);...} // while (RecordFound) end

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


/* * Variable execution: switch Interface to determine which one has been called */

switch (Interface.Interface){case 'SCC Interface Claim':

{Interface.Function = "SCC Interface Claim";Interface.BusObjName = "INS Claims";Interface.BusCompName = "INS Claims";Interface.Request = true;break;}

default:{Output = "De interface\n" +

Interface.Interface +"\nis niet gedefinieerd in " +Interface.CurrentFunction +TheApplication().GetSharedGlobal("SCCSupport");

Output = TheApplication().GetSharedGlobal("SCCError") + Output;break;}

} // switch (Interface.Interface) end

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


oINSClaimsBO = null;oINSClaimsBC = null;oService = null;oOutput = null;oInput = null;

return (Output);}

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


do{...while (RecordFound)

{...if (oINSClaimsBC.GetFieldValue("Id") == null) // just kidding!

{StopProgram = true;break;}

...RecordFound = oINSClaimsBC.NextRecord();} // while (RecordFound) end

if (StopProgram){break;}

for (i = 0; i < Record.length; i++){...} // for (i = 0; i < Record.length; i++) end

} while (false) // dummy do ... while loop end

2.9 Function calling

Arguments can be passed to functions, and they always pass one back via the return value. For maintainability, it is very wise to limit the arguments passed to objects only and assign properties to these objects, which can be picked up in other functions. There are a lot of pro's (advantages) and a few con's (disadvantages) to this.

2.9.1 Objects

Objects are passed by reference. Instead of copying values and passing them to functions, only a memory address is passed where the object resides. This significantly speeds up execution and reduces memory usage!

Changes to objects at any place apply to the object itself, unless a copy is explicitly made. This is a great pro, and might be the greatest con as well.

2.9.1.1 Object properties

There is one single rule that eases the pain of handling objects: as long as object properties aren't objects themself, there's absolutely no need to touch object properties other than reading them and adding them. In fact, it's wise not to destroy any object properties at all unless the end of the function is reached where the object was created.

It might be inevitable to assign objects to objects, since it is best to pass one object only to functions: in fact, in the ideal situation, all functions only take one argument which is an object, but this might be to much arithmetic even for the advanced programmer.

Objects can become quite large, with all the properties added to them. Remember that this can never be a con, since these properties normally would have existed anyway as normal variables, at least once or twice!Collecting all variables of a module in one objects is a great advantage, as the object can be used for logging purposes in case of erros. At this point the greatest disadvantage is formed by Siebel which doesn't allow table colums to exceed 16 KB!

Variables that will eventually have to be added to function calls, because of functional and or technical demands, can simply be added to the object at some place and retrieved from the object at another place: there is no need to adjust the function call or the function arguments.

The debugger won't show object properties, neither from "real" objects nor from arrays. This has got nothing to do with pro's or con's of objects, this just points to a very sloppy and barely usable debugger in Siebel. If you want to see all properties of an object at any point, just use the generic dump function in combination with the log function or write function!

2.9.2 Variables

Since all values can be retrieved through the input parameters passed to functions, the value returned can be used for errorhandling. Of course errorhandling can be done via objects as well, but analyzing the return of a function is classical and practical. Objects and their properties will be used in errorhandling anyway, and in system programming is it inevitable that error(s) will turn up as object properties at some point in time.

2.9.3 Control over properties

When there are multiple functions and / or multiple business services involved in a single functional or logical transaction, it might become hard to control object property assignment and usage: the same goes for normal variables, which are not object properties. For clarification of object properties in use, export a business service or business component script to file and use DOS (FIND /I "Object.") or any other tool to retrieve the object properties. To find out object


properties in use at a certain point during script execution, use the generic log (to database or file) and / or dump function made for ING Service Center Claims.

Of course, a clear and up-to-date detailed technical design tells you where to find everything, but the code is leading when it comes to usage of objects / variables.

2.9.4 Example 12: object and properties


try{do

{


Fraud = new Object();

Fraud.Function = "SCC Fraud Check";Fraud.CurrentFunction = "CheckFraud";

Fraud.RowId = oInput.GetProperty("Id");Fraud.ClaimId = oInput.GetProperty("ClaimId");Fraud.FraudText = oInput.GetProperty("Fraud Text");

Fraud.Error = "";Fraud.FraudStatus = "";

Fraud.GeenBestuurder = false;Fraud.QuickRoute = false;Fraud.Reassign = false;Fraud.SpeciaalOnderzoek = false;Fraud.SpecialeSchade = false;Fraud.VABevoegdFlag = false;

...

/* * Check claim data */

if (!CheckClaimData(Fraud)){break;}

2.10Error handling

Error handling must occur within each and every function, throughout all business services, business component scripts, etcetera. Error handling must start in the PreInvoke Method and continue in each underlying function: the return of the main function must be passed to the output property set, and unsupported methods must be left to Siebel by issueing a ContinueOperation.

Each business service must contain a primary function which supplies the main functionality: all other functions must be called from within. This function must create - and destroy - the object which is used to pass along to the other functions, collect various variables and serve as log base in case of an error.

2.10.1 Return

Functions return values: in all cases, this value will be the variable Output. If an error occurred, this variable will contain an error message which will be concatenated with the global variable SCCSupport, which is a sentence redirecting the user to the company's support desk.To drive the types of output it must then be preceded by another global variable, of which there are three: SCCError, SCCWarning and SCCInfo. These will determine the message box title and icon.

2.10.2 PreInvokeMethod

By default, each PreInvoke Method must assign ContinueOperation (in fact, the value 1) to the variable Output, which is to be returned. Failure to invoke the method with an appropriate method name will result in a vanilla Siebel error, which may only occur during development.

A switch must evaluate the various MethodNames passed, and assign CancelOperation (mostly) or ContinueOperation before the break in each underlying case.

Each business service must return the property SCCOutput in the property set oOutput: this string must be equal to the global variable SCCOutput, otherwise the business service has failed execution and further execution must end. The property SCCOutput is set to the value returned by the main function.

Business services executed on the server, called by invoking a server request that executes a workflow, must also return this value: all workflows executing business services must have at least one output argument, with the same name, that passes on this output argument to the calling function, which has to evaluate it.

2.10.3 Output evaluation

There is a generic function called SCCAnalizeoutput for analyzing outputs. It takes two arguments, viz. Result (the output argument from a previously called function or business service), and an object, which may be left out. If the object contains a boolean called DisableNotification, set to false, the user will get the output on screen if it is not equal to the global variable SCCOutput. The same effect will be achieved if this function is called with only the first argument.

2.10.4 Try - catch

Each function must have a try-catch construction: the try statement is used to process exceptions that occur during script execution. The catch clause is used to handle the exception.

It is technically possible to have the catch statement be followed by a finally statement, but since this clause offers arbitrary script redirection as well as multiple returns, it is forbidden.Furthermore, all possibilities offered by the finally clause can be achieved by placing code on


exactly the same place, without the clause itself: sequential script execution will always continue after the catch!

The try-catch statement must be outlined as follows: a linefeed after the words try and catch and braces for the code block. Appropriate indenting must be used. For the catch, the variable caught should always be exception, which must be enclosed in round brackets, with a space between catch and exception. No spaces should be used after the begin round bracket, (, and before the end-round bracket, ).

The try statement must start after the declaration block and before the initialisation block: that is the first point where errors can ocur.

In the catch, the output Output must be set to the most likely error message. Dependent on the place of execution (client or server) this error will be (directly) shown to the user, but eventually, at the end of the whole transaction, it will have to be shown to the user, and written to the database error log, as well as to a file in the temporary Windows directory of the client's machine.If the execution resides on the server as a whole (e.g. a batch process) it must only be written to the error log.

The catch must always be accompanied by a comment block explaining the possible error(s) leading to the exception. All significant function variables must be stored to the object in the catch.

2.10.5 Example 13: try-catch

2.10.6 Error logging

All errors must be logged. Error logging must be as extensive as possible. The object must be fully read and written to file and / or database.

There is one generic function that logs errors to file, which is especifically built for all interfacing and includes the 8 arrays that make up an interface - as well as the object itself - and writes these to file.


try{...}

catch (exception){

/* * I really don't know what could go wrong here, but who knows? * Anyway, set Output to SCCError */

Interface.d = d;Interface.Exception = exception;Interface.i = i;Interface.ii = ii;Interface.j = j;

Output = "Er is een onbekende fout opgetreden in functie " +Interface.CurrentFunction +TheApplication().GetSharedGlobal("SCCSupport");

Output = TheApplication().GetSharedGlobal("SCCError") + Output;}

2.10.7 Useful generic functions

Filename and directory are retrieved dynamically via the generic function SCCGetEnvironmentVariables, which among others determines the name of the temporary directory of the operating system, the Siebel working directory, the computer name and dump switches.

Other useful settings are retrieved dynamically via the generic function SCCGetUserSetings, which among others determines the user name, the position id, the login id and the organization.

There is also a generic function that logs errors to the database, where the 16KB prevents these arrays from being written to the database (an average log file is 40 - 60 KB), and only the object itself is extracted: it is called SCCLogErrors, and located on the Application.

Finally, there is a generic function that logs errors to file, where the object itself and 8 arrays are extracted: it is called SCCDumpErrors, and located on the Application. It has been built especially for all interfaces created via the business services starting with SCC Interface, but can be easily modified to a single object-writing function.


2.11Business Services

Business services are modules, which contain functions. Each business service must contain a main function which is called from the PreInvoke Method. Whereas all functions return the variable Output, which is analysed, this main function must return the variable Output as well, having the value ContinueOperation or CancelOperation.

The main function called in a business service returns a variable Output which must be set to the property SCCOutput, which is a property of the output property set of the business service.

2.11.1 Multiple business service forming a single logical transaction

Cross-business services programming is quite extreme: business services can only be called with property sets, which only support the datatype string. The only solution is to build a generic function (which has already been built for ING Service Center Claims, viz. SCCGetPropertySet and SCCSetPropertySet) that variably and dynamically converts objects to property sets and vice versa. When converting from property sets to objects, all datatypes have to be restored: booleans have to be set to false or true, integers have to be made integer again, "defined" and "undefined" have to be restores to its special state, and (multi-dimensional) arrays have to be restored as well.

2.11.2 Restoring arrays and other objects

Joining an array is child's play, but splitting a string into an array poses problems: when splitting, the array created exists of references to offsets in the string. If the array itself is passed to the function that splits it from a string, which is inevitable of course, the reference is not to the original array, but to the string. Leaving the function destroys all variables, including the reference, resulting in the original aray being untouched. The only way to fix this is to force the reference to the array by prefixing it with an ampersand in the arguments of the function that splits it from a string: this will achieve the desired result.

Instantiated business objects and components technically can be restored as well, but shouldn't be passed in the first place, only for logging purposes. Furthermore it is very dangerous and thus forbidden to restore business objects and components, since it is unclear what their scope is!


2.12Known Siebel product defects

Siebel product defects are a product in itself: eScript has quite a few of them. Following is a complete list of Service Requests dealing with eScript and affecting eScript: if there is a workaround for these functions, there must be made one, which has to be offered to all developers. If there isn't, use the function with extreme caution and test it extensively!

SR: 38-826383251CR: 12-EESUPCSiebel doesn't support global functions. Functions can be placed on the application level, but the Application is not parsed when execution is on the server.The only workaround possible which offers the same functionality is to include all functions in an include file and include that file in the Application_Start event. Be aware that this js-file has to be located on all development machines with tools installed!The support of global functions in eScript has been rejected by Siebel in the same SR.

SR: parseInt(), isNaN(), ToNumber() and isFinite() are fully defective: they will parse as integers linefeeds, carriage returns, spaces, horizontal as well as vertical tabs, and non-breaking spaces. ToNumber() will return Infinity and -Infinity for the + and - sign. Siebel states this is according to ECMA standards. ParseInt() will also return numbers for the decimal ASCII range 58-64: colon, semi-colon, equals-sign, etcetera...There are lots of workarounds possible: the best is to write a function that uses the ASCII code to determine whether something is a number or not. Use justavariable.charCodeAt(), which returns a number between 0 and 65535 indicating the Unicode value, according to the Bookshelf: it will return 0 through 255 for the ASCII set.

SR: 38-867062561CR: 12-EC9VXOReferencing a multi-dimensional array (e.g. Data[i][0]) will create the index for that element, regardless of existence. Suppose there's only one entry, Data[0][0], and Data[6][0] is referenced: the array length will now be 7!This very dangerous product defect can create endless loops, eventually causing Siebel to crash when running out of memory.

SR: 38-921460451CR: 12-F95SULReferencing a single-dimensional array via the function defined() will create the index for that element, regardless of existence. Suppose there's only one entry, Data[0], and Data[6] is referenced - if (defined(Data[6])): the array length will now be 7!This very dangerous product defect can create endless loops, eventually causing Siebel to crash when running out of memory.


2.13 Illegal statements and actions

It is technically possible but absolutely forbidden to use the following statements in Siebel eScript, besides the ones mentioned above:

2.13.1 GOTO statement

The goto statement enables jumping back and forth through functions. It makes script absolutely illegible, and is the gravest error one can make: it is proof of programming incapability. Even jumping forth to one specific label, e.g. End:, is forbidden because the same goal can be achieved by breaking out of a (dummy) loop.

2.13.2 WITH statement

The with statement assigns a default object to a statement block, so you need to use the object name with its properties and methods. (quote from Siebel Bookshelf eScript.pdf)

The with statement is very usefull in VB and Siebel VB, but is absolutely useless and quite dangerous in Siebel eScript, since only methods can be used in the statement block that are supported by the object itself. In VB, a period must precede these methods, but in eScript it may not. It is therefor impossible to mix object methods with other assignments, because these assignments will be treated as object methods, rendering this feature highly unpractical.

2.13.3 CONTINUE LABEL statement

The continue statement is simular to the break statement: it ends the current iteration of a loop and begins the next. Any conditional expressions are reevaluated before the loop reiterates.

The continue statement in itself is not prohibited, on the contrary, it is very useful. It may not, however, be used to jump to a label. Labels in general are prohibited, even for documentation purposes: a comment block will do.

2.13.4 Function recursion

A recursive function is a function that calls itself or that calls another function that calls the first function. Recursion is permitted in Siebel eScript. Each call to a function is independent of any other call to that function. Be aware that recursion has limits. If a function calls itself too many times, a script will run out of memory and abort. (quote from Siebel Bookshelf eScript.pdf)

'Nough said...

2.13.5 Property sets

It is forbidden to use property sets for any other purpose than input and output parameters to business services. Property sets are passed by reference, but can only contain strings and are therefor very limited in use. Property sets have the same con's as objects but much less pro's!

2.13.6 Returning objects

It is forbidden to return objects, since it is impossible to deallocate these objects: the scope of their reference doesn't exist anymore, thus causing a memory leak.

2.13.7 Arrays with counters of datatype string

It is forbidden to reference Array index elements with strings instead of numbers, since manipulation of this reference (Array[i + 1] will result in string concatenation instead of addition: 10 + 1 will become 101 instead of 11.


2.13.8 Global variables

The only way to set and get a global variable throughout the application (i.e. across business services, business components, etcetera) is through use of TheApplication().SetSharedGlobal() and TheApplication().GetSharedGlobal(). The commands TheApplication().SetProfileAttr() and TheApplication().GetProfileAttr() do the same, but they add no additional functionality to it: they are forbidden.TheApplication().SetUserProperty() and TheApplication().GetUserProperty() set global variables throughout business components: these variables are existing along with the instance of the business component and are accessible via COM as well. They might be used for this goal and this goal only: if a global variable will do, that must be used.

It is forbidden to set a global variable and not declare it in the application in the event Application_Start: it should be clear to all which global variables are already in use. Remember that global variables can only be used with datatype string: if a more flexible datatype is desired, an object must be declared - which must be destroyed in the event Application_Close.

2.13.9 ForwardOnly on instantiated business components

It is forbidden to retrieve already instantiated business components (this.) and use the cursor mode ForwardOnly on them: it is impossible to tell what the user action will be on these business components, possibly resulting in a crash of the application.

2.13.10 Vanilla Siebel business services

Vanilla Siebel business services can be useful, and can be useless: they also can be defective. The business services “EAI XML Write to File" and “EAI XML Read from File” must not be used: SCCWriteFile and SCCReadFile must be used: they give full control over directory- and file-accessibility, and could offer possibilities to overcome the large string-bug in SIebel, which will cause problems if strings are larger than 50KB.Both functions are placed on the Application level, take one object as input and return “the usual” output.


2.14Functions

Knowing all this, it is very easy to build a function:

It starts with a statement block, describing the function;

Then comes the declarations block, naming all the variables;

Next is the try clause, which starts the errorhandling;

The dummy do while enables script redirection;

The initialisation block follows, initializing variables as much as possible, without overinitializing them;

Execution begins, and ends, avoiding all prohibited and defective statements;

The dummy do while ends;

The try ends, and the catch starts, where the exception and as much as variables as possible are set as properties to the input object;

Object deallocation takes place through variables destruction;

The function returns the output Output.

Life can be simple!

On the following page there's an example of a skeleton function, to be used for creating new functions in Siebel.


3 General query guidelines

3.1 Business objects and business components

3.1.1 Hierarchical database

Siebel turns each database into a hierarchical database: to follow and use the links between business components, the following has to be done in the exact order:

First of all the business object has to be instantiated;

Next, the primary business component has to be instantiated with the correct viewmode;

Then, for each underlying business component, the business components have to be instantiated as they are linked in the business object: if the business object is three levels deep and the last level has to be reached, this can only be achieved by instantiating the first, the second and the third level, in that same order.

If you don’t “walk through the business object” in this way, you will get into trouble!

3.2 Comparison to SQL

Siebel interacts with the database via its query-statements: this means that they can be literally translated to (parts of) SQL-statements, which results in a logical order:

3.2.1 SetViewMode

When instantiating the primary business component, set the desired view mode: don’t forget this or you’ll create mysterious problems for yourself and your fellow developers: the view mode gives user-restricted access to tables and views. If the current viewmode must be stored, use GetViewMode.

The general view mode used is AllView: this will give you visibility across all organisations. In special cases, the view mode OrganizationView can be used, but there has to be a very good reason to do this!

3.2.2 ActivateFields

Activating fields means adding them to the SQL-select clause. Fields that are ForceActive on the business component or have their Link Specification set to TRUE, Siebel system fields such as Created, Updated, Id and Siebel fields that are visible at the moment (becuas they’re on the active applet) don’t need to be activated.

3.2.3 ClearToQuery

ClearToQuery is used to clear the current searchspec and sortspec on the business component. If the current Searchspec or Searchexpression must be stored, use GetSearchSpec or GetSearchExpr. Clearing a query means emptying the current SQL where-clause.

3.2.4 SetSearchSpec

SetSearchSpec is used to set (a part of) the where-clause of the SQL-query


3.2.5 ExecuteQuery

ExecuteQuery offers the SQL-statement to the database and returns a recordset

3.2.6 Example 14: Siebel Query

3.3 Querying

3.3.1 Query Mode

If possible, use ForwardOnly, since this will significantly speed up execution. ForwardOnly is possible if you don't travel back (e.g. by using FirstRecord(), PreviousRecord(), FirstSelected()) through the recordset without requerying the business component. Siebel will hold the entire recordset in memory, occupying a considerable amount of memory and maintaining a large rollback segment, causing a high drain on performance.

Don’t (this has been mentioned earlier) use ForwardOnly on already active business components! If the bookshelf is right (which it isn’t), ForwardOnly should not be used at all because the only way to instantiate a business component is to reuse an exisitng one or recreate one if it doesn’t already exists; of course, there’s no telling which situation is at hand since there’s only one command to instantiate a business component.


/* * Main: get fraud specific fields, check consistency */

oINSClaimsBC.SetViewMode(AllView);

oINSClaimsBC.ActivateField("Loss Date");oINSClaimsBC.ActivateField("SCC Beschadigde Zaak Type");oINSClaimsBC.ActivateField("SCC Branche Code");oINSClaimsBC.ActivateField("SCC Direct Behandelen Flag");

oINSClaimsBC.ClearToQuery();

oINSClaimsBC.SetSearchSpec("Id", Fraud.ClaimId);

oINSClaimsBC.ExecuteQuery();

RecordFound = oINSClaimsBC.FirstRecord();

if (RecordFound){...}

siebel escript standards - 21gradi | il blog personale di · web viewnaming convention because...

Documents