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".
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.
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.
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.
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
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}";
}
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.
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> |
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:
<
>
&
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.
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:
<
>
&
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.
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:
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
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.
Update the rule set in the XML file. For more information, see "About the Rule Set XML File".
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.
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.iScript supports constants described in this section.
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" |
Table 20-4 lists the 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. |
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 |
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. |
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 |
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. |
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 |
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. |
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
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
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.
// ...
}
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.
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
{
}
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.
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;
}
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;."
You use the iScript functions to perform the following operations:
Perform arithmetic operations. See "Arithmetic Functions" in BRM Developer's Reference.
Manipulate ASN.1 objects. See "ASN.1 Functions" in BRM Developer's Reference.
Connect to the database and perform database operations. See "Database Connection Functions" in BRM Developer's Reference.
Normalize data. See "Data Normalizing Functions" in BRM Developer's Reference.
Manipulate date and time values. See "Date Functions" in BRM Developer's Reference.
Access and manipulate EDR containers. See "EDR Container Functions" in BRM Developer's Reference.
Read and write files and their contents. See "File Manipulation Functions" in BRM Developer's Reference.
Manipulate flists. See "Flist Manipulation Functions" in BRM Developer's Reference.
Manipulate hashes and arrays. See "Hash and Array Functions" in BRM Developer's Reference.
Perform mapping between old and new values. See "Mapping Functions" in BRM Developer's Reference.
Call opcodes. See "Opcode Calling Functions" BRM Developer's Reference.
Communicate with the pipeline system. See "Pipeline System Functions" in BRM Developer's Reference.
Perform static operations. See "Static Functions" in BRM Developer's Reference.
Create and manipulate mutex and start and stop processes. See "Standard Functions" in BRM Developer's Reference.
Work with strings. See "String Functions" in BRM Developer's Reference.
Access the Transaction Manager. See "Transaction Management Functions" in BRM Developer's Reference.
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. */
}
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. |
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. |
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. |
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. |
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.
The following iScript extensions include additional iScript functions:
Use EXT_Converter to convert and normalize phone numbers and IP addresses. See "Data Normalizing Functions" in BRM Developer's Reference.
Use EXT_AsnTree to output ASN.1 data. See "ASN.1 Tree Functions" in BRM Developer's Reference.
Use EXT_FList to retrieve and set data in flists. See "Flist Manipulation Functions" in BRM Developer's Reference.
Use EXT_Opcode to call opcodes. See "Opcode Calling Functions" in BRM Developer's Reference.
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.