Skip Headers
Oracle® Communications Billing and Revenue Management Developer's Guide
Release 7.5

E16702-10
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

20 Creating iScripts and iRules

This chapter describes how to use the Application Programming Interface (API) to create custom Oracle Communications Billing and Revenue Management (BRM) iScript and iRules modules to process event detail records (EDRs) in the pipeline.

For information about Pipeline Manager, see "About Pipeline Rating" in BRM Configuring Pipeline Rating and Discounting.

For information about the iScript functions, see "About iScript Functions".

About iScripts

iScript is a script language for analyzing and manipulating usage events. You can access any field within the usage structure and modify it. Using an iScript, you can implement and configure new guiding rules, mapping scenarios, discounting structures, interfaces to user-defined database objects and to reference data, and operating report files.

iScript is the Pipeline Manager script programming language that can be used to customize Pipeline Manager. It can be used for:

  • Mapping operations that are not covered by standard modules.

  • Adjusting values, such as normalizing phone numbers and IP addresses.

  • Evaluating additional statistical data.

  • Firing events.

  • Performing splitting operations.

  • Performing customer-specific pre- or post-rating or enrichment functionality.

You use iScripts to perform the same operation on every EDR. For example, if you have to enrich or normalize data in EDRs or if you have to evaluate EDRs before splitting them.

iScript makes it easier than C or C++ programming languages to implement custom functionality and business policies.

See "About Configuring iScripts" in BRM System Administrator's Guide.

About iRules

An iRule consists of rule items that contain a number of conditions and a script to execute when a condition is fulfilled. Only the script for the first valid rule item is executed during the rule evaluation.

You create the scripts to be executed by using pattern-matching evaluation (for example, wildcards and logical expressions) as well as normal comparison operators (for example, equal to, less than, and greater than).

You use iRules when a function should be executed only on certain EDRs or under certain conditions. The rule-based engine offers an optimized method for defining logical conditions and extensive string comparisons. Therefore, iRules offer a faster way of implementing rule-based conditions than writing an iScript, which can include many "if-else" constructs.

You group rules and rule items into rule sets. A rule set defines the set of rules to be used by a particular iRule module. You specify the rule set in the FCT_IRule module startup registry. See "About Configuring iRules" in BRM System Administrator's Guide.

Note:

You can refer to only one EDR extension block in an iRule. For example, you cannot use DETAIL.ASS_GSMW_EXT and DETAIL.ASS_SUSPENSE_EXT extension blocks in the same iRule. Use an iScript instead to compare or evaluate fields from multiple EDR extension blocks.

You can create rules and rule items by using a description file or in Pricing Center. To create rules in Pricing Center, see the Online Help.

Creating Rule Sets via Description Files

In addition to the database interface and the file interface, you can also use a description file to define a rule set. This is useful when you store the rule data in separate database tables or ASCII files. A rule set defined by a description file can only have one rule.

Descriptions for Data from an ASCII File

In the following example description file:

  • The rule name in is ClassTypeMap

  • The source data is stored in an ASCII file called /data/data.txt.

  • The variables, represented by ${N}, are replaced by values in the source data file.

    RULE: ClassTypeMap 
    SOURCE: File 
    FILE: /data/data.txt 
    INIT_SCRIPT: 
    String code = edrString( DETAIL.SERVICE_CODE ) + edrString( DETAIL.SERVICE_CLASS ); 
    CONDITION: 
    code =~ "${1}"; 
    edrString( DETAIL.CALL_CLASS ) =~ "${2}"; 
    edrString( DETAIL.CALL_TYPE ) =~ "${3}"; 
    RESULT: 
    edrString( DETAIL.CALL_TYPE ) = "${4}"; 
    edrString( DETAIL.CALL_CLASS ) = "${5}";
      
    

The following example source data file contains the values that replace the variables (represented by ${N}) in the definition file.

  • The source data file must contain at least the number of columns, separated by semicolons, as there are variables in the definition file.

  • The column position corresponds to the variable number. For example, ${2} in the description file is replaced with the value in column 2 of the source data file.

    CODE1;CC1*;CT*;NewCC1;NewCT 
    CODE2;CC2*;CT*;NewCC2;NewCT 
    CODE3;CC3*;CT*;NewCC3;NewCT 
    CODE4;CC4*;CT*;NewCC4;NewCT 
    CODE5;CC5*;CT*;NewCC5;NewCT 
    CODE6;CC6*;CT*;NewCC6;NewCT 
    CODE7;CC7*;CT*;NewCC7;NewCT 
    CODE8;CC8*;CT*;NewCC8;NewCT
    

Descriptions for Data from a Database Table

In the following example description file:

  • The rule name is CZT_MapRule.

  • The source data is retrieved from the IFW_CLASSTYPEZONE_MAP database table.

  • The data is ordered first by the ZONEMODEL column and then by the RANK column.

  • Each variable, represented by ${COLUMN_NAME}, is replaced by the value in that database table column.

    SOURCE: Database 
    RULE: CZT_MapRule 
    TABLE: IFW_CLASSTYPEZONE_MAP 
    ORDERBY: ZONEMODEL 
    ORDERBY: RANK 
    INIT_SCRIPT: 
    String code = edrString( DETAIL.SERVICE_CODE ) + edrString( DETAIL.SERVICE_CLASS ); 
    CONDITION: 
    code =~ "${CODE}" 
    edrString( DETAIL.CALL_TYPE ) =~ "${CALLTYPE}"; 
    edrString( DETAIL.CALL_CLASS ) =~ "${CALLCLASS}"; 
    edrString( DETAIL.SERVICE_CODE ) =~ "${SERVICECODE}"; 
    edrString( DETAIL.AOC_ZONE ) =~ "${ZONE_WS}"; 
    edrString( DETAIL.CHARGED_ZONE ) =~ "${ZONE_RT}"; 
    RESULT: 
    if ( length( "${NEW_CALLTYPE}" ) > 0 ) 
    { 
    edrString( DETAIL.CALL_TYPE ) = "${NEW_CALLTYPE}"; 
    } 
    if ( length( "${NEW_ZONE_RT}" ) > 0 ) 
    { 
    edrString( DETAIL.CHARGED_ZONE ) = "${NEW_ZONE_RT}"; 
    } 
    if ( length( "${NEW_ZONE_WS}" ) > 0 ) 
    { 
    edrString( DETAIL.AOC_ZONE ) = "${NEW_ZONE_WS}"; 
    }
    

Importing and Exporting Validation Rules

You use the Database Storage and Extraction Tool for Validation Rules to extract validation rules from the Pipeline Manager database and to import them in the Pipeline Manager database. Pipeline Manager uses these validation rules for the roaming incollect and outcollect processes.

This tool uses DBI and DBD drivers which are not part of the Pipeline Manager installation. You download these drivers from www.cpan.org and compile and install them separately.

The Database Storage and Extraction Tool for Validation Rules consists of the following scripts:

  • The db2irules.pl script extracts validation rules from the Pipeline Manager database.

  • The irules2db.pl script adds validation rules to the Pipeline Manager database.

About the Rule Set XML File

The Database Storage and Extraction Tool for Validation Rules extracts the validation rules from the database to a Rule Set XML file. When creating the XML file, it maps the Structured Query Language (SQL) tables from the database to the appropriate XML tag names. When you import rules and rule items in the database, the rank for each of these is determined by the order in which they appear in the Rule Set XML file. For example, the first rule row or rule item row found in the XML file is inserted into the database with a rank of 1, the second one is inserted with a rank of 2 and so forth.

Table 20-1 shows a possible mapping:

Table 20-1 Possible Mappings for Validation

Pipeline Manager Database Table Pipeline Manager Database Table Column XML Tag Parent XML Tag

N/A

N/A

<RULESET_ROW>

NONE

IFW_RULESET

RULESET

<RULESET_RULESET>

<RULESET_ROW>

IFW_RULELSETLIST

RULESET

<RULESET_RULESET>

<RULESET_ROW>

IFW_RULESET

NAME

<RULESET_NAME>

<RULESET_ROW>

IFW_RULESET

DESCRIPTION

<RULESET_DESCRIPTION>

<RULESET_ROW>

N/A

N/A

<RULE_ROW>

<RULESET_ROW>

IFW_RULESETLIST

RULE

<RULE_RULE>

<RULE_ROW>

IFW_RULE

RULE

<RULE_RULE>

<RULE_ROW>

IFW_RULEITEM

RULE

<RULE_RULE>

<RULE_ROW>

IFW_RULE

NAME

<RULE_NAME>

<RULE_ROW>

IFW_RULESETLIST

NAME

<RULE_NAME>

<RULE_ROW>

IFW_RULE

INIT_SCRIPT

<RULE_INIT_SCRIPT>

<RULE_ROW>

N/A

N/A

<RULEITEM_ROW>

<RULE_ROW>

IFW_RULEITEM

NAME

<RULEITEM_NAME>

<RULEITEM_ROW>

IFW_RULEITEM

CONDITION

<RULEITEM_CONDITION>

<RULEITEM_ROW>

IFW_RULEITEM

RESULT

<RULEITEM_RESULT>

<RULEITEM_ROW>


About the db2irules.pl Script

You use the db2irules.pl script to extract rule sets from the Pipeline Manager database to the Rule Set XML file. You can extract any number of rule sets at the same time. If you extract multiple rule sets, each rule set is written to a separate Rule Set XML file.

When db2irules.pl extracts rows from the database, the text of each database row is checked for the following XML reserved characters:

  • Left angle bracket (<)

  • Right angle bracket (>)

  • Ampersand (&)

The XML parser uses these characters to find the start tags, end tags, and any references. It replaces them with the following HTML and XML flags:

  • &lt;

  • &gt;

  • &amp;

These flags make the file XML compliant, so that any XML parser can parse this file successfully.

For more information, see "db2irules.pl" in BRM Configuring Pipeline Rating and Discounting.

About the irules2db.pl Script

Use the irules2db.pl script to insert a rule set from Validation Rules XML file into the Pipeline Manager database. You can insert only one rule set at a time. To load multiple rule sets into the database, run this script separately for each rule.

When irules2db.pl imports rows to the database, each rule and rule set row of the XML file is checked for the following HTML and XML flags:

  • &lt;

  • &gt;

  • &amp;

The XML parser uses these characters to find the start tags, end tags, and any references. It replaces the m with the following XML-reserved characters:

  • Left angle bracket (<)

  • Right angle bracket (>)

  • Ampersand (&)

If you specify an invalid file name for the rule set, the irules2db.pl script displays an error and terminates. If the file exists and can be opened, the script opens a transaction to the database and starts inserting the rule sets. If any of the rule sets specified already exists in the database, the irules2db.pl script reports an error, rolls back the transaction, and terminates. The error message contains information on which row in the XML file caused the error.

For more information, see "irules2db.pl" in BRM Configuring Pipeline Rating and Discounting.

Updating a Rule Set

You can update rule sets that already exist in the database in two ways:

  • Extract, update, and import a rule set

  • Replace a rule set with an updated version

Extract, update, and import a rule set

To update a rule set that already exists in the database, export, update, and reimport the XML file:

  1. Export the rule set to a Rule Set XML file by using the db2irules.pl script. For more information, see "About the db2irules.pl Script".

    Example:

    db2irules.pl [-u] dbi:Oracle:orcl scott tiger /home/data/CIBER_val
      
    
  2. Delete the rule set from the database by using the db2irules.pl script. Specify the name of the rule set and set the -d parameter.

    Example:

    db2irules.pl [-d] dbi:Oracle:orcl scott tiger /home/data/CIBER_val
      
    

    The script deletes all rules of a rule set recursively.

    Note:

    If you use Pricing Center, you first have to delete each rule set separately and then can delete the rule set.

    For more information, see "db2irules.pl" in BRM Configuring Pipeline Rating and Discounting.

  3. Update the rule set in the XML file. For more information, see "About the Rule Set XML File".

  4. Import the rule set to the database by using the irules2db.pl script. For more information, see "About the irules2db.pl Script".

    Example:

    irules2db.pl dbi:Oracle:orcl scott tiger /home/data/CIBER_val_2002_07_01_17-15-39.xml 
      
    

Replace a rule set with an updated version

To replace an existing rule set with an updated version that you didn't extract from the database, you can import the rule set and create a backup of the old rule set by using the -f parameter.

Example:

irules2db.pl -f dbi:Oracle:orcl scott tiger /home/data/CIBER_val /home/data/backup
  

The -f parameter causes the db2irules extraction script to be invoked and extract the original file from the database before loading the new file. A backup file of the original rule set is stored in the specified backup location.

For more information, see "irules2db.pl" in BRM Configuring Pipeline Rating and Discounting.

Supported iScript Data Types

iScript supports the following data types in Table 20-2:

Table 20-2 Supported iScript Data Types

Data Type Description

Bool

For Boolean values TRUE and FALSE.

String

For 8-bit character strings of an unlimited length.

Long

For signed integer values in the interval from - 9223372036854775808 (2^63) to 9223372036854775807 (2^63-1).

Date

For date/time values in the interval from the 1901/01/01 00:00:00 to the 2037/02/05 00:00:00.

Decimal

For floating pointer to numbers with a precision of 26 digits.

File

As a handle for files.


Note:

Based on the data types listed above, you can also use hash and arrays.

Supported iScript Constants

iScript supports constants described in this section.

Constants for Normalizing National Access Codes

Table 20-3 lists the iScript constants used to normalize national access codes.

Table 20-3 National Access Code Normalizing iScript Constants

Constant Type Value Description

NORM_NAC

String

"0"

"National access code"

NORM_IAC

String

"00"

"International access code array"

NORM_IAC_STRING

String

"00"

"International access code string"

NORM_CC

String

NA

Country code array

NORM_CC_STRING

String

"49"

"Country code string"

NORM_MCC

String

"262"

"Mobile country code"

NORM_IAC_SIGN

String

"+"

"International country code sign"

NORM_NDC

String

"172"

"Network destination code"


Date Constants

Table 20-4 lists the Date constants.

Table 20-4 Date Constants

Constant Type Value Description

MAX_DATE

Date

05.02.2037 23:59:59

Maximum value for the date. The date is stored as the number of seconds since 00:00:00.

The MAX_DATE value is the last date that can be represented with a four-byte unsigned long, which is February 5, 2037. The internal representation is adjusted to the time zone of the system.

MIN_DATE

Date

01.01.1901 00:00:00

Minimum value for the date. The date is stored as the number of seconds since 00:00:00.

The MIN_DATE value is January 1, 1901. The internal representation is adjusted to the time zone of the system.


Database Connection Constants

Table 20-5 describes the database connection constants.

Table 20-5 Database Connection Constants

Constant Type Value Description

INVALID_CONNECTION

Long

-1

Invalid database connection handle

INVALID_RESULT

Long

-1

Invalid result handle

NO_MORE_RESULTS

Long

0

No more results

NO_MORE_ROWS

Long

0

No more rows

NEXT_ROW

Long

1

Next row to be retrieved from the database table

NEXT_RESULT

Long

1

Next result from db query


Decimal Constants

Table 20-6 lists the decimal constants.

Table 20-6 Decimal Constants

Constant Type Value Description

INVALID_DECIMAL

Decimal

Decimal::initInvalidDecimal();

Invalid Decimal value


Decimal Rounding Constants

Table 20-7 lists the decimal rounding constants.

Table 20-7 Decimal Rounding Constants

Constant Type Value Description

ROUND_PLAIN

Long

0

If the digit to the right of the specified decimal place is equal to or greater than 5, add one to the digit at the specified decimal place, then truncate any digits to the right. Otherwise, truncate all digits to the right of the specified decimal place.

ROUND_UP

Long

1

If the digits the right of the specified decimal place are non-zero, add one to the digit at the specified decimal place and truncate any digits to the right.

ROUND_DOWN

Long

2

Truncate all digits to the right of the specified decimal place.

ROUND_BANKERS

Long

3

If incrementing the digit at the specified decimal place results in an even number, increment it and truncate the digits to its right. Otherwise, truncate the digits to the right of the specified decimal place.


EDR Container Content Constants

Table 20-8 lists the EDR container content constants.

Table 20-8 EDR Container Constants

Constant Type Value Description

EDR_UNKNOWN_CONT

Long

1

Unknown EDR content type

EDR_HEADER

Long

2

EDR header record

EDR_DETAIL

Long

3

EDR detail record

EDR_TRAILER

Long

4

EDR trailer record

EDR_START

Long

5

Service container that tells pipeline starts

EDR_STOP

Long

6

Service container that tells pipeline shutting down

EDR_BEGIN

Long

7

Service container that tells EDR processing begins

EDR_END

Long

8

Ser vice container that tells EDR processing ends

EDR_BEGIN_TRANSACTION

Long

9

Service container that tells transaction begins

EDR_END_TRANSACTION

Long

10

Service container that tells transaction ends


EDR Container Characters Deletion Constants

Table 20-9 lists the EDR container content deletion constants.

Table 20-9 EDR Container Content Deletion Constants

Constant Type Value Description

STRIP_LEADING

Long

True

Roguewave constant used to delete the special leading characters in an EDR string, for example, white spaces at the beginning of the EDR container.

STRIP_TRAILING

Long

True

Roguewave constant used to delete the special trailing characters in an EDR string, for example, white spaces at the end of the EDR container.

STRIP_BOTH

Long

True

Roguewave constant used to delete both the special leading and trailing characters in an EDR string, for example, white spaces at the beginning of the EDR container.


EDR Input State Constants

Table 20-10 lists the EDR input state constants.

Table 20-10 EDR Input State Constants

Constant Type Value Description

EDR_INPUT_MISSING

Long

0

Not supplied in input data

EDR_INPUT_EMPTY

Long

1

Supplied with no value

EDR_INPUT_OTHER

Long

2

Other "uninteresting" input state


EDR Internal State Constants

Table 20-11 lists the EDR internal state constants.

Table 20-11 EDR Internal State Constants

Constant Type Value Description

STATE_CLEARED

Long

0

EDR value is cleared

STATE_CONNECTED

long

1

EDR value is connected with a field from an input record

STATE_INITIALZED

long

2

EDR value is initialized

STATE_SET

long

3

EDR value is set

STATE_RESTORED

long

4

EDR value is restored

STATE_RESTOREDASSET

long

5

EDR value is restored as set

CONTAINER_HEADER

Long

2

Header record descriptor in container

CONTAINER_DETAIL

Long

3

Detail record descriptor in container

CONTAINER_TRAILER

Long

4

Trailer record descriptor in container

CONTAINER_UNKNOWN

Long

1

Unknown record type in container


POID Constants

Table 20-12 lists the Portal object ID (POID) constants.

Table 20-12 POID Constants

Constant Type Value Description

NULL_PPOID

POID

BAS::Identifier(0, "", 0);

Null POID pointer

INVALID_PPOID

POID

BAS::Identifier

Invalid POID pointer


TAM Transaction Constants

Table 20-13 lists the TAM transaction constants.

Table 20-13 TAM Transaction Constants

Constant Type Value Description

TAM_NORMAL

Long

0

Normal transaction

TAM_RECYCLE

Long

1

Recycle transaction

TAM_RECYCLE_TEST

Long

2

Recycle transaction for testing

TAM_UNKNOWN

Long

-1

Unknown transaction type


Supported Regular Expressions

iScript supports the regular expressions listed in Table 20-14:

Table 20-14 Regular Expressions Supported by iScript

Expression Description

.

Matches any single character except the newline character \n.

\

Introduces metacharacters, and as part of the escape sequences. For example, \n, a newline character, and \*, is a literal asterisk. You can use it with three digits representing a number between 0 and 255 (ASCII code) to get the corresponding character. For example, \065 is matched to the character A.

[ ]

A character class which matches any character within the brackets. If the first character is a circumflex (^), it changes the meaning to match any character except the ones within the brackets. A dash inside indicates a character range. For example [0-9] means the same thing as [0123456789].

{ }

Indicates how many times to match the previous pattern when the pattern has one or two numbers, e.g. A{1,3} matches one to three occurrences of the letter A.

*

Matches zero or more copies of the preceding expression.

+

Matches one or more copies of the preceding expression. For example. [0-9]+ matches 1, 111, or 123456 but not an empty string.

?

Matches zero or one copy of the preceding expression. For example. -?[0-9]+ matches a signed number including an optional leading minus.

|

Matches either the preceding expression or the following expression.

( )

Groups a series of expressions into a new expression. Useful when building up complex patterns with *, +, and |.

!

Negates the complete expression. It must be the first character in the expression.


iScript Variable Declarations

The syntax of the variable declaration is similar to the C/C++ syntax:

Type Name [=Value];
  

As an option, you can declare variables to be constants:

const Type Name = Value;
  

For example:

Long x;
String serviceCode = "Tel";
const Decimal pi = 3.1415927

iScript Arrays and Hashes

All data types except File can be used in arrays or hashes:

Long a[ ]; // A normal array declaration
String dist [ ] [ ]; // A 2-dimensional string array
String ndc { } [ ]; // An associative array
String cli { } [ ]; // An associative array or arrays
  

You do not have to specify the dimension of the arrays and hashes. The data structures are resized automatically and are initialized by default values. For numerical values, this is 0; for strings, it is an empty string and dates become invalid.

You can access arrays and associative arrays in the following way:

a [3] = 4711;
ndc { "040" } = Hamburg;
cli { "Max Mueller" } [0] = "0171123456789";
cli { "Max Mueller" } [0] = "0177471111245";

Important:

If you use arrays and hashes in functions, clear them at the start of the functions, as in this example:

function myFunction

{

    String str[];

    arrayClear(str);

     // ...

}

Arrays and hashes aren't initialized at the start of functions. They behave like static variables. If they are not cleared in a function, they retain values from the last time the function was executed

iScript Function Declarations

A function declaration has the following syntax:

function [returnType] identifier [( parameter [,parameter...])]
  

where returnType is optional. If you do not specify any return type, the default is VOID. A function can have an unlimited number of arguments. You can use the basic types as return and parameter types.

For example:

function Long square (Long x)
{
  return x.*;
}

Important:

Avoid nesting functions. Nested functions can create unexpected results, as in this example:

function myFunction

{

    Long i = 5;

    // ...

    myFunction();

        // Here the variable i is assigned the value set in the nested function.

    // ...

}

iScript Control Structures

The syntax of the control structures is similar to the C++ syntax, but because there are no implicit type casts, the following expression is not valid in iScript:

if ( i ) ...
  

You must use explicit type casts:

if ( i != 0 )...
  

There are AND and OR operators for Boolean expressions. Empty statements in FOR loops are not valid in iScript and there is no increment operator.

For example:

for ( ; i<100; i++ )
  

in C++ has to be replaced with

for ( i ; i<100; i=i+1)
  

in iScript.

iScript Function Blocks

A function block that is followed by a control structure must be enclosed in curly braces { }. This is also true if only one statement is in the function block.

For example:

if ( (edrString ( DETAIL.RECORD_TYPE) = = "H"))
 {
  logStdout ("Header detected\n");
 }
else
 {
  
 }

Using iScript Switch Statements

iScript provides switch statements for String values, Long values, and regular expressions. The syntax of the switch statement is similar to the C syntax. Follow these rules when including switch statements:

  • Specify only one statement per case label.

  • Use a statement block and enclose several statements between curly braces ({ }).

  • Terminate every case label by a break statement. Otherwise the statement of the following case label is also executed.

  • For regular expressions, use the regExprSwitchCase statement instead of switch.

Examples for Switch Statements

Switch statements (Long)

switch ( edrLong ( DETAIL.RECORD_LENGTH ) )
{
 case 104:
  logStdout ( "Header record!" );
  break;
 case 685:
  {
      detail = detail + 1;
      logStdout ( "Detail record" );
  }
  break;
 default:
  logStdout ( "unknown record type" );
}
  

Switch statements (String)

switch ( edrString ( DETAIL.ERROR_TEXT) )
{
  case "ERR_DATETIME":
    logStdout ("invalid date/time" );
    break;
  case "ERR_NOIMSI":
    logStdout ("IMSI not specified");
  case "":
    logStdout ("no error detected");
    break;
...
}
  

Switch statements for regular expressions

regExprSwitch ( edrString ( DETAIL.A_NUMBER ) )
{
  case "0049171.*":
    logStdout ( "D1-call\n" );
    break;
  case "0049172.*":
    logStdout ( "D2-call\n" );
    break;
}

Including Other iScript Source Files in Your iScript

You can use the include statement in your iScript to include other iScript source files.

Use the following syntax and specify each include statement in a separate line:

include "iScriptFile.isc";
  

Before an iScript is compiled, a preprocessor evaluates and processes the include statements. If the included iScript file has an absolute path, the preprocessor tries to include the file with the absolute path. Otherwise, the preprocessor uses a semicolon-separated list of include directories specified in the ISCRIPT_INCLUDE environment variable.

If the ISCRIPT_INCLUDE environment variable is not set, the preprocessor uses only the current directory as the input directory. If the environment variable is set, it does not contain the current working directory by default. You must explicitly add the current working directory to the list by using a dot (.) as the path. For example:

bash and sh:

export ISCRIPT_INCLUDE="/home/integRate/iscript include;/usr/iscript;."
  

csh and tsch:

setenv ISCRIPT_INCLUDE "/home/integRate/iscript_include;/usr/iscript;."

About iScript Functions

You use the iScript functions to perform the following operations:

About Special iScript Functions

Pipeline Manager includes a basic iScript interpreter and an extended interpreter that calls special iScript functions on external events, such as onHeaderEdr or onDetaiEdr. These special functions are function hooks that you can use to implement any actions you want to perform at specific situations, such as when a transaction is rolled back, during EDR processing.

For example, to perform custom actions when a transaction rolls back, you can include the following function block in an iScript:

Function onRollback
{
  logStdout("onRollback() \n");
  /* Define rollback-related actions here. */
}

Pipeline-Related Function Hooks

Use the functions listed in Table 20-15 to perform the actions you want at various stages of the pipeline process:

Table 20-15 Pipeline-Related Functions

Function Description

BEGIN

Called when Pipeline Manager starts and after the iScript is compiled.

END

Called when Pipeline Manager is shut down.

onMessageReceived

Deprecated.

onStartEdr

Called when a pipeline starts. It is called once in the life of a pipeline process.

onStopEdr

Called when a pipeline stops. It is called once in the life of a pipeline process.


EDR Processing-Related Function Hooks

Use the functions listed in Table 20-16 to perform the actions you want during various stages of EDR processing:

Table 20-16 EDR-Processing Related Functions

Function Description

onBeginEdr

Called when a BEGIN EDR container for each file opened in a transaction passes through a module.

onBeginTransaction

Called when a BEGIN_TRANSACTION EDR container passes through a module.

onDetailEdr

Called when a DETAIL EDR container passes through a module.

onEndEdr

Called when an END EDR container for each file opened in a transaction passes through a module.

onEndTransaction

Called when an END_TRANSACTION EDR container passes through a module.

onHeaderEdr

Called when a HEADER EDR container passes through a module.

onInvalidDetailEdr

Called when an EDR with invalid detail record is received by a module.

onTrailerEdr

Called when a trailer container passes through a module.


Input Grammar-Related Function Hooks

Use the function hooks listed in Table 20-17 in the input grammar to execute the actions you want when the input module parses a stream:

Table 20-17 Input Grammar-Related Functions

Function Description

onParseEnd

Called when the input module finishes parsing a stream.

onParseError

Called when the input module encounters an error while parsing a stream.

onParseStart

Called when the input module starts processing a stream.

streamIsEmpty

Called when an empty stream is encountered.


Transaction-Manager Related Function Hooks

Use these functions listed in Table 20-18 to perform the actions you want during a transaction.

For more information on transaction management and the communication between pipeline modules and the transaction manager, see "About Pipeline Manager Transactions" in BRM System Administrator's Guide.

Table 20-18 Transaction Manager Related Functions

Function Description

onCancel

Called when a transaction needs to be cancelled.

onCommit

Called when the transaction manager notifies that a transaction is committed.

onPrepareCommit

Called when the transaction manager sends a request to prepare to commit a transaction.

onRollback

Called when a transaction needs to be rolled back.


About iScript Flist Extension Functions

You use the iScript flist extension functions to manipulate data in flists. For example, you can use the functions to retrieve information from an flist so that you can add it to the EDR container. You can also use the functions to add data taken from an EDR to an flist.

There are functions for creating flists, retrieving data from fields, setting field values, setting and unsetting the current array, deleting fields and arrays, and retrieving error text.

Here is a simple example of moving data from an EDR to an flist. Suppose you have the following EDR data block:

DETAIL.ASS_DATA
   String NAME
   Decimal VALUE
   Long QUANTITY
  

You can convert that EDR block to an flist in this format:

0 PIN_FLD_ARRAY   ARRAY 
1   PIN_FLD_STRING   STRING
1   PIN_FLD_DECIMAL   DECIMAL
1   PIN_FLD_INT   INT
  

The following is an example of iScript code to convert the EDR block to an flist:

fListPushElem( "PIN_FLD_ARRAY", 0 );
fListSetString( "PIN_FLD_STRING", edrString( DETAIL.ASS_DATA.NAME, 1 ) );
fListSetDecimal( "PIN_FLD_DECIMAL",edrDecimal( DETAIL.ASS_DATA.VALUE, 1 ) );
fListSetLong( "PIN_FLD_INT", edrLong( DETAIL.ASS_DATA.QUANTITY, 1 ) );
fListPopElem();
  

See "Flist Manipulation Functions" in BRM Developer's Reference for a list of the flist extension functions and information about their syntax.

iScript External Modules

The following iScript extensions include additional iScript functions:

Improving Pipeline Performance in Custom iScripts and iRules

This section provides some guidelines to reduce pipeline startup time and memory usage in your custom iScripts and iRules.

When the pipeline framework loads an iRule, a finite state machine (FSM) is built in memory. The number of objects the FSM creates in memory affects the pipeline startup and memory usage. FSMs create decision trees in memory at startup-time which affect pipeline startup, but decision trees help the pipeline work efficiently at run-time.

To reduce pipeline startup time and memory usage, follow these guidelines while creating iRules:

  • Split the database entries because the number of rows in the loaded table affects memory usage and startup time of Rules.

  • When writing rules, review the condition and reduce the number of compare patterns.

  • Keep the regular expressions as simple as possible.

  • If you have complex rules, place them at the beginning of an iRule.

  • To improve processing performance, split big iRules if you have CPUs to allocate for new threads.

To improve pipeline processing performance, follow these guidelines when creating iScripts:

  • If you can use an iRule instead of an iScript, use an iRule.

  • Keep iScripts simple.

  • Whenever possible, use standard modules instead of creating custom modules.

  • Avoid database read access from the iScript when processing EDRs. Instead, load data during startup into hashes, and use that data when processing EDRs.

  • Avoid functions that duplicate EDRs. They are performance intensive.

  • Avoid writing to a database within an iScript. If you do, make sure you handle transactions properly.