85 Pipeline Manager iScript Functions
This chapter provides reference information for Oracle Communications Billing and Revenue Management (BRM) Pipeline Manager iScript functions.
Arithmetic Functions
Table 85-1 contains the arithmetic functions.
Table 85-1 Arithmetic Functions
| Function | Description |
|---|---|
|
Derives an absolute value from a decimal value. |
|
|
Converts the integer portion of a decimal value to a Long value. |
|
|
Derives an absolute value from a Long value. |
|
|
Converts a Long value to a decimal value. |
|
|
Rounds a decimal value to a specified number of decimal places. |
|
|
Calculates the square root of the input value. |
|
|
Truncates a decimal value to a specified number of decimal places. |
decimalAbs
This function derives an absolute value from a decimal value.
Syntax
Decimal decimalAbs(Decimal source);Return Values
Returns the derived absolute value.
Example
if ( x == decimalAbs( x ) )
{
logFormat( "x is a positive value" );
}decimalToLong
This function converts the integer portion of a decimal value to a Long value.
Syntax
Long decimalToLong(Decimal source);Return Values
Returns the Long value of the integer portion of the decimal value.
Example
Long p = decimalToLong( 3.1415 );
round
This function rounds a decimal value to a specified number of decimal places.
Syntax
Decimal round(Decimalvalue[, Longplaces] [, Stringmode]);
Parameters
- value
-
The value to round.
- places
-
The number of decimal places to achieve when rounding, also known as the number of significant digits (the default is 0).
- mode
-
The rounding mode, or method of rounding. Possible values:
-
ROUND_PLAIN: (Default) If the digit following the last significant digit is 5 or greater, round up. If the digit following the last significant digit is less than 5, round down.
-
ROUND_UP: Always round up if the digit following the last significant digit is greater than 0.
-
ROUND_DOWN: Always round down. This is the same as truncating all digits following the last significant digit.
-
ROUND_BANKERS: This mode rounds in one of the following ways, depending on the value of the digit following the last significant digit:
-
If it is less than 5, truncate all digits following the last significant digit.
-
If it is greater than 5, round up.
-
If it is 5, round to the nearest even digit. For example, if the precision is 2, 10.155 and 10.165 both round to 10.16 because 6 is an even number.
-
Return Values
Returns the value rounded to the specified decimal place.
Example
Decimal r = round( 3.1415, 3 ); // r now is 3.142
ASN.1 Functions
Table 85-2 contains the ASN.1 functions.
Table 85-2 ASN.1 Functions
| Function | Description |
|---|---|
|
Adds an integer object to the current active node of the ASN tree. |
|
|
Adds a string object to the current active node of the ASN tree. |
|
|
Creates a tree in memory to hold an ASN.1 file structure. |
|
|
Deletes the last created or used ASN.1 tree. |
|
|
Deletes a node from the ASN.1 tree. |
|
|
Flushes the content of the ASN.1 tree to the output. |
|
|
Gets the active (working) node from a list of created and store |
|
|
Backs up one level in the ASN.1 tree hierarchy. |
|
|
Adds a new block to the current active node of the ASN.1 tree and sets this new block as an active node of the tree. |
|
|
Stores an index to a constructed block node in the ASN.1 tree, when the block position in the tree is fixed. |
asnTreeAddInteger
This function adds an integer object to the current active node of the ASN.1 tree.
Syntax
Bool asnTreeAddInteger(String blockName, Long value);
Parameters
Return Values
Returns True if successful; otherwise, returns False.
Example
...
asnTreeAddInteger("TAP3.DataVolume.DATA_VOLUME", 2512);
...asnTreeAddString
This function adds a string object to the current active node of the ASN.1 tree.
Syntax
Bool asnTreeAddString(String blockName, String value)
Parameters
Return Values
Returns True if successful; otherwise, returns False.
Example
...
asnTreeAddString("TAP3.CalledPlace.CALLED_PLACE", "Freephone");
...asnTreeCreate
This function creates a tree in memory to hold an ASN.1 file structure, where the Length field of the objects can be calculated in the end, just before writing on the output.
Parameters
None.
Return
True on success, otherwise, False
Only one tree can be in use at a time.
Example
...
if ( asnTreeCreate() == false )
{
logFormat( "asnTreeCreate() failed.");
}
...asnTreeDelete
This function deletes the last created or used ASN.1 tree.
Syntax
Bool asnTreeDelete();
Parameters
None.
Return Values
Returns True if successful; otherwise returns False.
Example
...
if ( asnTreeDelete() == false )
{
logFormat( "asnTreeDelete() failed.");
}
...asnTreeDeleteNodeByIndex
This function deletes a node from the ASN.1 tree, by recursively deleting all contained blocks and values.
Syntax
Bool asnTreeDeleteNodeByIndex(Long nodeIdx);
Return Values
Returns True if successful; otherwise, returns False.
Example
... //there is no need for this optional block (no data to store //in it), so delete it asnTreeDeleteNodeByIndex(networkInfoIdx); ...
asnTreeFlush
This function flushes the content of the ASN.1 tree to the output.
Syntax
Bool asnTreeFlush();
Parameters
None.
Return Values
Returns True if successful; otherwise, returns False.
Example
...
if ( asnTreeFlush() == false )
{
logFormat( "asnTreeFlush() failed.");
}
...asnTreeGetStoredNode
This function gets the active (working) node from a list of created and stored, but not filled, constructed blocks.
Syntax
Bool asnTreeGetStoredNode(Long nodeIdx);
Return Values
Returns True if successful; otherwise, returns False.
Example
... asnTreeGetStoredNode(networkInfoIdx); //use asnTreeAddString() and asnTreeAddInteger() to update //the TAP3.NetworkInfo block. ...
asnTreePop
This function backs up one level in the ASN.1 tree hierarchy. Every asnTreePushTag(xxxx) should have an associated asnTreePop(); it is like opening and closing brackets.
Syntax
Bool asnTreePop();
Parameters
None.
Return Values
Returns True if successful; otherwise, returns False.
Example
...
asnTreePushTag("TAP3.AuditControlInfo");
...
asnTreePop(); //asnTreePushTag("TAP3.AuditControlInfo");
...asnTreePushTag
This function adds a new block to the current active node of the ASN.1 tree and sets this new block as an active node of the tree. Use this function to create constructed ASN.1 objects, for example, SEQUENCE or CHOICE.
If the isIndefiniteLength parameter is set to true, the Length field of the ASN.1 object is set to 0x80 and 2 null bytes are appended to the Value field of the ASN.1 object.
Syntax
Bool asnTreePushTag(String blockName [, Bool isIndefiniteLength=false] );
Parameters
Return Values
Returns True if successful; otherwise, returns False.
Example
...
asnTreePushTag("TAP3.AuditControlInfo");
...asnTreeStoreNode
This function stores an index to a constructed block node in the ASN.1 tree, when for example, the data values that should be put in this block are unknown, but the block position in the tree is fixed.
Syntax
Long asnTreeStoreNode();
Parameters
None.
Return Values
Returns a node index that can be used with asnTreeGetStoredNode(nodeIdx) or asnTreeDeleteNodeByIndex(nodeIdx).
Example
...
asnTreePushTag("TAP3.NetworkInfo");
Long networkInfoIdx = asnTreeStoreNode();
//Nothing to do now, node will be updated after all //details are processed
asnTreePop(); //for asnTreePushTag("TAP3.NetworkInfo");
...
The following example iScript demonstrates how to create an output file in ASN.1 containing only a list of QoS requested objects (one per event data record (EDR)), with all field values set to 3.
This is the content of the OutGrammar.dsc file. There should be an associated file describing the block structure that is here used, for example, TAP3.QoSRequestedList.
// The initial iScript code
iScript
{
use EXT_AsnTree; // iScript extension to build a Tree of ASN.1 object
// used to fill the Length value of the ASN.1 bloc,
// before printing on output stream
}
// The definition of the grammar
Grammar
{
edr_stream:
header
details
trailer
;
header:
HEADER
{
asnTreeCreate();
asnTreePushTag("TAP3.QoSRequestedList");
}
;
trailer:
TRAILER
{
asnTreePop(); //for asnTreePushTag("TAP3.QoSRequestedList");
asnTreeFlush();
asnTreeDelete();
}
;
details:
details
DETAIL
{
asnTreePushTag("TAP3.QoSRequested");
asnTreeAddInteger("TAP3.QoSDelay.QOS_DELAY", 3);
asnTreeAddInteger("TAP3.QoSMeanThroughput.QOS_MEAN_THROUGHPUT", 3);
asnTreeAddInteger("TAP3.QoSPeakThroughput.QOS_PEAK_THROUGHPUT", 3);
asnTreeAddInteger("TAP3.QoSPrecedence.QOS_PRECEDENCE", 3);
asnTreeAddInteger("TAP3.QoSReliability.QOS_RELIABILITY", 3);
asnTreePop(); //for asnTreePushTag("TAP3.QoSRequested");
}
| /*EMPTY*/
;
} Database Connection Functions
Table 85-3 contains database connection functions.
Table 85-3 Database Connection Functions
| Function | Description |
|---|---|
|
Starts a new transaction using the specified connection. |
|
|
Closes a connection to the Pipeline Manager database. |
|
|
Closes a result handle after processing the result data. |
|
|
Commits a transaction to a specific connection. |
|
|
Establishes a connection to the Pipeline Manager database. The handle returned by this function should be used in future calls to the dbExecute function. |
|
|
Connects the extension to a DBC_Database module. |
|
|
Retrieves a description for the last error. This description is not reset after a valid call to one of the other database connection functions. Therefore, dbError should only be called directly after one of the other database connection functions fails. |
|
|
Executes an SQL statement against the Pipeline Manager database. |
|
|
Switches the cursor to the next result for the result handle you specify. |
|
|
Switches the cursor to the next row in the current result. |
|
|
Rolls the current transaction back for the specified connection. |
dbBeginTransaction
This function starts a new transaction using the specified connection.
Syntax
Bool dbBeginTransaction(Long conHandle);Return Values
Returns true if the transaction was successfully started. Returns false if the function fails.
Example
if ( dbBeginTransaction( conHandle ) == false )
{
logFormat( "ERROR: failed to begin a new transaction: " \
+ dbError() );
} dbCloseConnection
This function closes a connection to the Pipeline Manager database.
Syntax
Bool dbCloseConnection(Long conHandle);Return Values
Returns true if the connection was successfully closed. Returns false if the function fails.
Example
if ( dbCloseConnection( conHandle ) == false )
{
logFormat( "ERROR: failed to close a connection: " + \
dbError() );
}dbCloseResult
This function closes a result handle after processing the result data.
Syntax
Bool dbCloseResult(Long resHandle);Return Values
Returns true if the result handle was successfully closed. Returns false if the function fails.
Example
resHandle = dbExecute( "SELECT * FROM INT_SUBS_CLI" );
if ( resHandle == INVALID_RESULT )
{
logFormat( "ERROR: dbExecute() failed: " + dbError() );
}
...
// Process the result data
...
dbCloseResult( resHandle ); dbCommitTransaction
This function commits a transaction to a specific connection.
Syntax
Bool dbCommitTransaction(Long conHandle);Return Values
Returns true if the transaction was successfully committed to the connection. Returns false if the function fails.
Example
if ( dbCommitTransaction( conHandle ) == false )
{
logFormat( "ERROR: failed to commit the transaction: " + dbError() );
}dbConnection
This function establishes a connection to the Pipeline Manager database. The handle returned by this function should be used in future calls to the dbExecute function.
Note:
Before calling dbConnection, connect to DBC_Database module using dbDataConnection.
Syntax
Long dbConnection();
Parameters
None.
Return Values
Returns the handle for the new connection (the handle is a value greater than or equal to 0) if the function is successful. Returns INVALID_CONNECTION if the function fails.
Example
conHandle = dbConnection();
if ( conHandle == INVALID_CONNECTION )
{
logFormat( "ERROR: dbConnection() failed: " + dbError() );
}dbDataConnection
This function connects the extension to a DBC_Database module. This connection is valid for the whole extension; you cannot connect the extension to two different DBC_Database modules.
Note:
Before calling dbConnection, connect to DBC_Database module using dbDataConnection.
Syntax
Bool dbDataConnection(String dbcModule);Return Values
Returns true if the extension was successfully connected to the module. Returns false if the function fails.
Example
use IXT_Db;
if ( dbDataConnection( "integrate.DataPool.Login.Module" ) == \
true )
{
logFormat( "Connection to DBC module established" );
}
else
{
logFormat( "ERROR: failed to establish the connection \
to DBC module" );
}dbError
This function retrieves a description for the last error. This description is not reset after a valid call to one of the other database connection functions. Therefore, dbError should only be called directly after one of the other database connection functions fails.
Syntax
String dbError();
Parameters
None.
Return Values
Returns a description of the error.
Example
resHandle = dbExecute( conHandle, "SELECT * FROM INT_SUBS_CLI" );
if ( resHandle == INVALID_RESULT )
{
logFormat( "ERROR: dbExecute() failed: " + dbError() );
}dbExecute
This function executes an SQL statement against the Pipeline Manager database. The handle this function returns should be used to access the result of the SQL statement in the dbNextResult and dbNextRow calls that follow. After processing the result data, free the handle by calling dbCloseResult.
Syntax
Long dbExecute(LongconHandle, StringsqlStatement);
Return Values
Returns the result handle (the handle is a value greater than or equal to 0) if the function is successful. Returns INVALID_RESULT if the function fails.
Example
resHandle = dbExecute( conHandle, "SELECT * FROM INT_SUBS_CLI" );
if ( resHandle == INVALID_RESULT )
{
logFormat( "ERROR: dbExecute() failed: " + dbError() );
}dbNextResult
This function switches the cursor to the next result for the result handle you specify.
Note:
This function is specific to results, not rows. The return generated by dbExecute can consist of a list of results in table form, with each result containing one or more data rows. Using dbNextResult moves the cursor from result to result, not from data row to data row within a result.
Syntax
Long dbNextResult(Long resHandle);Return Values
Returns the next result in the result handle if the function is successful. Returns NO_MORE_RESULTS if the function reaches the last result. Returns a value less than 0 if the function fails.
Example
resHandle = dbExecute( conHandle, "SELECT * FROM INT_SUBS_CLI" );
// loop for all results
do
{
// process the rows of the current result
while ( (ret = dbNextResult( resHandle )) == NEXT_RESULT );
if ( ret != NO_MORE_RESULTS )
{
logFormat( "ERROR: dbNextResult() failed: " + dbError() );
}dbNextRow
This function switches the cursor to the next row in the current result.
Note:
This function is specific to rows, not results. The return generated by dbExecute can consist of a list of results in table form, with each result containing one or more data rows. Using dbNextRow moves the cursor from row to row within a result, not from result to result.
Syntax
Long dbNextRow(Long resHandle, ...);Return Values
Returns the next row in the result if the function is successful. Returns NO_MORE_ROWS if the function reaches the last row. Returns a value less than 0 if the function fails.
Example
resHandle = dbExecute( conHandle, "SELECT * FROM INT_SUBS_CLI" );
// loop for all rows
while ( (rowRet = dbNextRow( resHandle, cli, validFrom validTo )) > 0 )
{
...
}
if ( rowRet != NO_MORE_ROWS )
{
logFormat( "ERROR: dbNextRow() failed: " + dbError() );
} dbRollbackTransaction
This function rolls the current transaction back for the specified connection.
Syntax
Bool dbRollbackTransaction(Long conHandle);Return Values
Returns true if the rollback is successful. Returns false if the function fails.
Example
if ( dbRollbackTransaction( conHandle ) == false )
{
logFormat( "ERROR: failed to rollback current transaction: " \
+ dbError() );
}Data Normalizing Functions
Table 85-4 contains data normalizing functions.
Table 85-4 Data Normalizing Functions
| Function | Description |
|---|---|
|
Normalizes wireline and wireless command-line interfaces (CLIs). Static class function: "EXT_ConvertCli::convert" |
|
|
Normalizes IPv4 addresses. Static class function: "EXT_ConvertIPv4::convert" |
|
|
Normalizes IPv6 addresses. Static class function: "EXT_ConvertIPv6::convert" |
|
|
Normalizes IPv4 over IPv6 addresses. Static class function: "EXT_ConvertIPv4onv6::convert" |
convertCli
This function normalizes wireless and wireline CLIs into international format.
Syntax
String convertCli( String cli, String modInd, Long typeOfNumber, String natAccessCode, StringArray intAccessCode, StringArray countryCode, String intAccessCodeSign, String natDestinCode )
Parameters
- cli
-
CLI to normalize.
- modInd
-
Modification Indicator, for example, "00".
- typeOfNumber
-
Type Of Number, for example, 0.
- natAccessCode
-
National Access Code, for example, "0".
- intAccessCode
-
International Access Code, for example, "00".
- countryCode
-
Country Code, for example, "49".
- intAccessCodeSign
-
International Access Code Sign, for example, "+".
- natDestinCode
-
National Destination Code, for example, "172".
Return Values
Returns a CLI in international normalized format: <iac>< cc><ndc>extension.
Example
... use EXT_Converter; String normCli; String cli = "01721234567"; normCli = convertCli( cli, "00", 0, "0", "00", "49", "+", "172" ); // normCli now contains: 00491721234567 ...
convertIPv4
This function normalizes IPv4 addresses.
Syntax
String convertIPv4( String ip );
Return Values
Returns an IP address in normalized format.
Dots (.) are skipped. Tokens are left-padded to 3 digits with zeroes.
Example
.... use EXT_Converter; String normIp; String ip = "192.168.1.253"; normIp = convertIPv4( ip ); // normIp now contains: 192168001253 ...
String convertIPv6
This function normalizes IPv6 addresses.
Syntax
String convertIPv6(String ip;
Return Values
Returns an IP address in normalized format.
Dots (.) are skipped. Tokens are left-padded to 4 digits with zeroes.
Example
.... use EXT_Converter; String normIp; String ip = "0:0:0:AF:E:0:1:FE"; normIp = convertIPv6( ip ); // normIp now contains: 00000000000000AF000E0000000100FE ...
convertIPv4onv6
This function normalizes IPv4 over IPv6 addresses. The decimal IPv4 address is converted into hexadecimal representation.
Syntax
String convertIPv4onv6(String ip);
Return Values
Returns an IPv6 address in normalized format.
Dots (.) are skipped. Tokens are left-padded to 4 digits with zeroes.
Example
.... use EXT_Converter; String normIp; String ip = "0:0:0:0:0:0:192.168.10.1"; normIp = convertIPv4onv6( ip ); // normIp now contains: 000000000000000000000000C0A80A01 ...
Date Functions
Table 85-5 contains date functions.
Table 85-5 Date Functions
| Function | Description |
|---|---|
|
Adds date and time values. |
|
|
Calculates the difference between two dates. |
|
|
Checks a date for validity; for example, after initialization from a string. |
|
|
Converts a date value to a string. |
|
|
Converts a string into a date value. |
|
|
Retrieves the current system date. |
dateAdd
This function manipulates date and time values.
Syntax
Date dateAdd(Datesource[, Longyears[, Longmonths[,days[, Longhours[, Longmins[, Longsecs]]]]]]);
Parameters
- source
-
The source date for the addition.
- years
-
The number of years to add. This parameter can be positive or negative.
- months
-
The number of months to add. This parameter can be positive or negative.
- days
-
The number of days to add. This parameter can be positive or negative.
- hours
-
The number of hours to add. This parameter can be positive or negative.
- mins
-
The number of minutes to add. This parameter can be positive or negative.
- secs
-
The number of seconds to add. This parameter can be positive or negative.
Return Values
Returns the manipulated source date.
Note:
The variable source itself is not manipulated; only the result is returned.
Example
Date now = sysdate(); Date later = dateAdd( now, 1, 2, 0, 5 ); logStdout( "Date now is " + dateToStr(now) + "\n" ); logStdout( "In 1 year, 2 months and 5 hours it is " + dateToStr(later) + "\n" );
dateDiff
This function calculates the difference between two dates. The difference is returned in seconds.
Syntax
Long dateDiff(Datedate1, Datedate2);
Parameters
Return Values
Returns the difference between the first and second date, in seconds.
Example
if ( dateDiff( sysdate(), date ) < 0 )
{
logFormat( "the date is a future date" );
}dateIsValid
This function checks a date for validity; for example, after initialization from a string.
Syntax
Bool dateIsValid(Date date);Return Values
Returns true if the date is valid. Returns false if the date is not valid.
Example
Date timeStamp = strToDate( timeString );
if ( dateIsValid( timeStamp ) == false )
{
logFormat( timeString + " is no valid date string" );
}dateToStr
This function converts a date value to a string.
Syntax
String dateToStr(Date date);Parameters
- %a
-
The abbreviated week day name; for example, Sun for Sunday. This is from tm::tm_wday.
- %A
-
The full weekday name; for example, Sunday. This is from tm::tm_wday.
- %b
-
The abbreviated month name; for example, Feb for February.
- %B
-
The full month name; for example, February.
- %c
-
The date and time; for example, Feb 29 14:34:56 2004. This may use all members.
- %d
-
The day of the month; for example, 29.
- %H
-
The hour of the 24-hour day; for example, 14.
- %I
-
The hour of the 12-hour day; for example, 02.
- %j
-
The day of the year starting from 001; for example, 060. This is from tm::tm_yday.
- %m
-
The month of the year, from 01; for example, 02.
- %M
-
The minutes after the hour; for example, 34.
- %p
-
The AM/PM indicator, if any; for example, AM.
- %S
-
The seconds after the minute; for example, 56.
- %U
-
The week of the year, starting from 00; for example, 45. This is from tm::tm_yday and tm::tm_wday. The week is defined as starting on Sunday.
- %w
-
The day of the week, with 0 for Sunday; for example, 2 for Tuesday.
- %W
-
The week of the year, from 00; for example, 33. This is from tm::tm_yday and tm::tm_wday. In this case, the week is defined as starting on Monday.
- %x
-
The date; for example, Feb 29 2004. This uses tm::tm_yday in some locales.
- %X
-
The time; for example, 14:34:56.
- %y
-
The year of the century, from 00; for example, 04 for 2004. In most cases, you should avoid this parameter; to ensure correct handling of the past century, use %Y instead.
- %Y
-
The year including the century; for example, 1994.
- %Z
-
The time zone name; for example, PST or PDT. This is from tm::tm_isdst.
Return Values
Returns the date as a string using the format defined by the function parameters if the function is successful. Returns an empty string if the date is invalid.
Example
dateToString("%a %d. %B %Y")
will result in:
"Mon 24. June 2002"
strToDate
This function converts a string into a date value. The only supported string format is YYYYMMDDHHMMSS.
Syntax
Date strToDate(String dateStr);Parameters
- %%
-
The literal % character.
- %d
-
The day of the month; for example, 29. The range is 00-31.
- %H
-
The hour of the 24-hour day; for example, 14. The range is 00-23.
- %m
-
The month of the year, from 01; for example, 02. The range is 01-12.
- %M
-
The minutes after the hour; for example, 34. The range is 00-59.
- %S
-
The seconds after the minute; for example, 56. The range is 00-59.
- %y
-
The year of the century, from 00; for example, 04 for 2004. The range is 01-99. In most cases, you should avoid this parameter.
- %Y
-
The year including the century; for example, 1994.
Return Values
Returns a valid date if the input string is in the right format. Returns an invalid date if the format is not correct.
Example
edrDate(DETAIL.CHARGING_START_TIMESTAMP) = \
strToDate("24.12.2002", "%d. %m. %Y");EDR Container Functions
Table 85-6 contains EDR container functions.
Table 85-6 EDR Container Functions
| Function | Description |
|---|---|
|
Adds additional output streams to each EDR. |
|
|
Adds a new data block to the current EDR container. |
|
|
Adds a new data block to the current EDR container. |
|
|
Adds a new error to the current EDR container. |
|
|
Accesses the array index values in EDR container. |
|
|
Clears the list of errors that the pipeline modules add to the EDR container. |
|
|
Associates an EDR field with an input token and is identical to calling a block mapping with edrInputMap, except that it is accomplished using only one field. This function calls the edrMissingInput and edrEmptyInput state-setting functions, which indicate the reason for missing fields. |
|
|
Associates an EDR field with an input token and is identical to calling a block mapping with edrInputMap, except that it is accomplished using only one field. This function calls the edrMissingInput and edrEmptyInput state-setting functions, which indicate the reason for missing fields. |
|
|
Determines whether an EDR has an additional output stream with the name you pass in. |
|
|
Provides the index of the token parsed from the stream. Valid only in input grammar. |
|
|
Retrieves and sets date values in the current EDR container. This function is usually used to retrieve date values. |
|
|
Retrieves and sets date values in the current EDR container. This function is usually used to retrieve date values. |
|
|
Retrieves and sets decimal values in the current EDR container. This function is used usually to retrieve decimal values. |
|
|
Retrieves and sets decimal values in the current EDR container. This function is used usually to retrieve decimal values. |
|
|
Deletes the current EDR container, changing the current pointer to the EDR container directly in front of the deleted EDR. |
|
|
Deletes a data block from the current EDR container. The function is not supported for nested transactions. |
|
|
Clears the contents of a field in an EDR container. The function is not supported for nested transactions. |
|
|
Duplicates the current EDR container. |
|
|
Sets the state of a field to EDR_INPUT_EMPTY when the field is present in the CDR but contains no value. |
|
|
Retrieves the Info string associated with the token for the corresponding EDR field. By default, the Info string contains the description of the token type. The function works only when the EDR field is associated with a token through either the edrInputMap or edrConnectToken function. |
|
|
Calculates the position of the token associated with the corresponding EDR field. The function works only when the EDR field is associated with a token through either the edrInputMap or edrConnectToken function. |
|
|
Gets the name of an additional EDR output stream given an array index number. |
|
|
Retrieves the names of the attached error messages. |
|
|
Retrieves the parameters associated to a specified error. |
|
|
Retrieves the severity for each of the associated errors. |
|
|
Gets the output stream for an EDR. |
|
|
Retrieves the names of the attached error messages. |
|
|
Retrieves the input state of an EDR field. |
|
|
Returns the internal state of an EDR field. |
|
|
Returns the internal state of an EDR field. |
|
|
Determines whether the current EDR container is a valid detail container. |
|
|
Retrieves and sets Long values in the current EDR container. This function is usually used to retrieve Long values. |
|
|
Retrieves and sets Long values in the current EDR container. This function is usually used to retrieve Long values. |
|
|
Finds the maximum severity of the errors added to the current EDR container. |
|
|
Sets the state of a field to EDR_INPUT_MISSING when the field is not present in the CDR. |
|
|
Determines the number of data blocks of the specified type. |
|
|
Determines the number of data blocks of the specified type. |
|
|
Accesses the number of error messages attached to the current EDR container. |
|
|
Accesses the number of tokens attached to the current EDR container. |
|
|
Removes additional output streams from an EDR. |
|
|
Sets the content type of the current EDR container. |
|
|
Sets the current EDR container. |
|
|
Sets the EDR container's valid detail flag. The valid detail flag specifies whether the EDR container is to be discarded. |
|
|
Sets the output stream for an EDR. |
|
|
Retrieves and sets string values in the current EDR container. This function is usually used to retrieve string values. |
|
|
Retrieves and sets string values in the current EDR container. This function is usually used to retrieve string values. |
|
|
Used to retrieve the content of each token, as identified by their indexes. When the index is not available, as for a function call with no argument, this function returns the complete byte string attached to the EDR. The byte string corresponds to the original input string that generated the EDR. The function works only when the EDR field is associated with a token through either the edrInputMap or edrConnectToken function. |
|
|
Enables the iRules mode. |
|
|
Disables the iRules mode. |
|
|
Retrieves the name of the pipeline in which the script is running. |
|
|
Stops the pipeline from which it is called. |
edrAddAdditionalStream
This function adds additional output streams to each EDR.
Each Out_GenericStream pipeline module has a default output stream for EDRs. You use this function to add additional output streams to direct the output to additional locations.
Output stream characteristics (output path, record prefix, and record suffix) are set in the registry file.
If the stream name sent in with this function already exists, edrAddAdditionalStream returns true but does not create the stream again.
Syntax
Bool edrAddAdditionalStream(String output_stream_name);Return Values
Returns true if the function is successful. Returns false for all other conditions.
Example
This iScript example adds two additional output module streams:
addoutmod.isc
------
function onDetailEdr
{
if (edrAddAdditionalStream( "TElOut1" ) == true)
{
logStdout("Stream TelOut1 added ");
}
if (edrAddAdditionalStream( "TELOut2" ) == true)
{
logStdout("Stream TElOut2 added ");
}
} // end onDetailEdr + end iScript ----
This registry fragment shows the two example iScript files, addoutmod.isc and removeoutmod.isc, defined in the FunctionPool section. These iScripts add and remove output module streams. The new iScripts are shown in bold.
FunctionPool
{
Iscript
{
ModuleName = FCT_IScript
Module
{
Active = True
Source = FILE
Scripts
{
addoutmod
{
FileName = ./samples/simple/addoutmod.isc
}
}
}
}
Iscript2
{
ModuleName = FCT_IScript
Module
{
Active = True
Source = FILE
Scripts
{
removeoutmod
{
FileName = ./samples/simple/removeoutmod.isc
}
}
}
}
This output registry section defines the TELOut1 output section:
TELOut1
{
ModuleName = OUT_GenericStream
Module
{
Grammar = ./formatDesc/Formats/Solution42/SOL42_V430_OutGrammar.dsc
DeleteEmptyStream = TRUE
OutputStream
{
ModuleName = EXT_OutFileManager
Module
{
OutputPath = ./samples/simple/data/out2
OutputPrefix = Sol42_
OutputSuffix = .out
TempPrefix = tmp
TempDataPath = ./samples/simple/data/out2
TempDataPrefix = out.tmp.
TempDataSuffix = .data
Replace = TRUE
}
}
}
} Note:
To ensure output file integrity, specify a unique combination of OutputPath, OutputPrefix, and OutputSuffix values for each output stream defined in the registry.
edrAddDatablock
This function adds a new data block to the current EDR container.
Syntax
Bool edrAddDatablock(EdrFieldblock[, Longidx1[, Longidx2 ...]]);
Parameters
Return Values
Returns true if the function is successful. Returns false if the function fails.
Example
if ( edrAddDatablock( DETAIL.ASS_CBD ) == false )
{
logFormat( "ERROR: failed to add ASSOCIATED_CHARGE \
datablock" );
} edrAddDatablockEx
This function adds a new data block to the current EDR container.
Syntax
Bool edrAddDatablockEx(Stringblock, LongindicesArray, LongnumIndices);
Parameters
Return Values
Returns true if the function is successful. Returns false if the function fails.
Example
Long indicesArray [ ];
Long numberOfIndices;
String edrFieldName;
edrFieldName = "DETAIL.ASS_CBD";
numberOfIndices = 0;
if ( edrAddDatablockEx(edrFieldName, indicesArray, numberOfIndices) == false )
{
logFormat( "ERROR: failed to add ASSOCIATED_CHARGE \
datablock" );
} edrAddError
This function adds a new error to the current EDR container.
Syntax
Bool edrAddError(Stringerror, Longseverity[, StringparamX...]);
Parameters
- error
-
The name of the error you want to add to the EDR container.
- severity
-
The severity of the error:
-
0 = Debug
-
1 = Normal
-
2 = Warning
-
3 = Minor error
-
4 = Major error
-
5 = Critical error
Return Values
Returns true if the function is successful. Returns false if the function fails.
Example
if ( edrString( DETAIL.SERVICE_CODE ) != "Tel" and \
edrString( DETAIL.SERVICE_CODE ) != "Fax" )
{
edrAddError( "ERR_UNKNOWN_SERVICE_CODE", 3, edrString\
( DETAIL.SERVICE_CODE ) );
}edrArrayIndex
This function accesses array index values in EDR container.
Syntax
Long edrArrayIndex(EdrFieldblock[, Longidx1[, Longidx2...]]);
Parameters
Return Values
Returns the index of the EDR container.
Example
edrArrayIndex( DETAIL.ASS_TCF_AAA_DETAIL.PCM_OP_TCF_AAA_AUTHORIZE.INPUT.PIN_FLD_BALANCES, 0, 0, 0, 0) = 1; edrIndex = edrArrayIndex( DETAIL.ASS_TCF_AAA_DETAIL.PCM_OP_TCF_AAA_AUTHORIZE.OUTPUT.PIN_FLD_BALANCES, 0, 0, 0, 0);
edrClearErrors
This function clears the list of errors that the pipeline modules add to the EDR container.
Each pipeline module error has a name, severity level, and optional parameters that you can use for debugging or constructing an error message. The error list is a collection of all the errors that the pipeline modules have added to an EDR, the number of errors in the list, and the maximum severity of the errors. You can use the errors to reject an EDR or to instruct the pipeline module to process an EDR differently or to not process an EDR.
However, if an EDR does not have errors severe enough to be rejected or processed differently, you can use this function to remove the errors from the list. This function resets the error count to 0 and the maximum severity level to normal.
Note:
Before clearing the errors, analyze all the errors in the EDR to ensure they can be safely ignored.
Syntax
Void edrClearErrors();
Parameters
None.
Return Values
Returns nothing.
Example
function onInvalidDetailEdr
{
if(edrNumErrors() > 0)
{
logStdout(" Current Edr contains" + longToStr(edrNumErrors()) + "Errors");
edrClearErrors();
logStdout(" Current Edr contains" + longToStr(edrNumErrors()) + "Errors after clearErrors");
}
else
{
logStdout(" Current Edr contains no Errors");
}
}edrConnectToken
This function associates an EDR field with an input token and is identical to calling a block mapping with edrInputMap, except that it is accomplished using only one field.
This function calls the edrMissingInput and edrEmptyInput state-setting functions, which indicate the reason for missing fields.
Syntax
Bool edrConnectToken(EdrFieldfield[, Longidx1[, Longidx2 ...]], const StringtokenName);
Parameters
Return Values
Returns true if the EDR field is successfully associated with the input token. Returns false if the function fails.
Example
Bool success = edrConnectToken(DETAIL.RECORD_TYPE, "SOL42.DETAIL.RECORD_NUMBER");
edrConnectTokenEx
This function associates an EDR field with an input token and is identical to calling a block mapping with edrInputMap, except that it is accomplished using only one field.
This function calls the edrMissingInput and edrEmptyInput state-setting functions, which indicate the reason for missing fields.
Syntax
Bool edrConnectTokenEx(Stringfield, LongindicesArray, LongnumIndices, StringtokenName);
Parameters
Return Values
Returns true if the EDR field is successfully associated with the input token. Returns false if the function fails.
Example
Long indicesArray [ ]; Long numberOfIndices; String edrFieldName; edrFieldName = "DETAIL.RECORD_TYPE"; numberOfIndices = 0; Bool success = edrConnectTokenEx(edrFieldName, indicesArray, numberOfIndices, "SOL42.DETAIL.RECORD_NUMBER");
edrContainsAdditionalStream
This function determines whether an EDR has an additional output stream with the name you pass in. EDRs contain one default stream and any number of additional output streams.
Syntax
Bool edrContainsAdditionalStream(String output_stream_name);Return Values
Returns true if the stream exists. Returns false if it does not.
Example
if ( edrContainsAdditionalStream( "TELOut3" ) == false )
{
logStdout( "ERROR: EDR does not contain additonal stream: TELOut1\n" );
}edrCurrentTokenIndex
This function returns the index of the token parsed from the stream. It is valid only in input grammar.
Syntax
Long edrCurrentTokenIndex();
Parameters
None.
Return Values
Returns the token index if the token exists. Returns -1 if the function fails.
Example
Long index = edrCurrentTokenIndex(); logStdout(“Currently processing: “ + edrTokenString(index0 + “\n");
edrDate
This function retrieves and sets date values in the current EDR container. This function is usually used to retrieve date values. When setting date values, use the function as the left-hand value in an assignment statement.
Syntax
Date edrDate(EdrFieldfield[, Longidx1[, Longidx2... ]]);
Parameters
Return Values
Returns the date value of the EDR field if the function is successful. Returns INVALID_DATE if the data type for this EDR is not Date or if the path through the EDR tree structure is not valid.
Example
Date timeStamp; timeStamp = edrDate( DETAIL.CHARGING_START_TIMESTAMP ); \ edrDate( DETAIL.CHARGING_START_TIMESTAMP ) = sysdate();
edrDateEx
This function retrieves and sets date values in the current EDR container. This function is usually used to retrieve date values. When setting date values, use the function as the left-hand value in an assignment statement.
Syntax
Date edrDateEx(Stringfield, LongindicesArray, LongnumIndices);
Parameters
Return Values
Returns the date value of the EDR field if the function is successful. Returns INVALID_DATE if the data type for this EDR is not Date or if the path through the EDR tree structure is not valid.
Example
Long indicesArray [ ]; Long numberOfIndices; String edrFieldName; edrFieldName = "DETAIL.CHARGING_START_TIMESTAMP"; numberOfIndices = 0; Date timeStamp; timeStamp = edrDateEx( edrFieldName, indicesArray, numberOfIndices); \ edrDateEx( edrField, indicesArray, numberOfIndices) = sysdate();
edrDecimal
This function retrieves and sets decimal values in the current EDR container. This function is used usually to retrieve decimal values. When used to set decimal values, use the function as the left-hand value in an assignment statement.
Syntax
Decimal edrDecimal(EdrFieldfield[, Longidx1[, Longidx2...]]);
Parameters
Return Values
Returns the decimal value of the EDR field if the function is successful. Returns an invalid decimal value if the data type for this EDR is not decimal or if the path through the EDR tree structure is not valid (for example, an index number is wrong).
Example
Decimal oldAmount; oldAmount = edrDecimal( DETAIL.CHARGED_AMOUNT_VALUE ); \ edrDecimal( DETAIL.CHARGED_AMOUNT_VALUE ) = oldAmount + 1.0;
edrDecimalEx
This function retrieves and sets decimal values in the current EDR container. This function is used usually to retrieve decimal values. When used to set decimal values, use the function as the left-hand value in an assignment statement.
Syntax
Decimal edrDecimalEx(Stringfield, LongindicesArray, LongnumIndices);
Parameters
Return Values
Returns the decimal value of the EDR field if the function is successful. Returns an invalid decimal value if the data type for this EDR is not decimal or if the path through the EDR tree structure is not valid (for example, an index number is wrong).
Example
Long indicesArray [ ]; Long numberOfIndices; String edrFieldName; edrFieldName = "DETAIL.CHARGED_AMOUNT_VALUE"; numberOfIndices = 0; Decimal oldAmount; oldAmount = edrDecimalEx(edrFieldName, indicesArray, numberOfIndices); \ edrDecimalEx(edrFieldName, indicesArray, numberOfIndices) = oldAmount + 1.0;
edrDelete
This function deletes the current EDR container, changing the current pointer to the EDR container directly in front of the deleted EDR.
Syntax
Bool edrDelete();
Parameters
None.
Return Values
Returns true if the current EDR container is deleted successfully. Returns false if there was no current EDR container.
Example
if ( edrDelete() )
{
logStdout( "EDR container deleted" );
} edrDeleteDatablock
This function deletes a data block from the current EDR container. The function is not supported for nested transactions (for example, transactions contained within transactions).
Syntax
Bool edrDeleteDatablock(EdrFieldblock, Longidx1[, Longidx2...]);
Parameters
Return Values
Returns true if the data block is successfully deleted. Returns false if the operation fails.
Example
if edrDeleteDatablock( DETAIL.ASS_GSMW_EXT, 0 ) == false )
{
logStdout("Error: failed to delete datablock");
}edrDeleteField
This function clears the contents of a field in an EDR container. The function is not supported for nested transactions (for example, transactions contained within transactions).
Syntax
Bool edrDeleteField(EdrFieldfield, Longidx1[, Longidx2...]);
Parameters
Return Values
Returns true if the EDR field content is successfully deleted. Returns false if the operation fails.
Example
if edrDeleteField( DETAIL.ASS_GSMW_EXT.RECORD_NUMBER ) == false )
{
logStdout("ERROR: failed to delete field");
}edrDuplicate
This function duplicates the current EDR container. The returned index is used as a parameter for the edrSetCurrent function to access the newly created EDR container.
Syntax
Long edrDuplicate();
Parameters
None.
Return Values
Returns the index of the duplicate EDR container (the index is greater than or equal to 0) if the function is successful. Returns a value less than 0 if the function fails.
Example
Long index = edrDuplicate();
if ( index < 0 )
{
logFormat( "ERROR: duplication of edr failed" );
}
else
{
if ( edrSetCurrent( index ) == true )
{
// send new edr to duplicate output
edrSetStream( "DuplicateOutput" );
}
}edrEmptyInput
This function sets the state of a field to EDR_INPUT_EMPTY when the field is present in the CDR but contains no value.
Syntax
Bool edrEmptyInput(EdrFieldfield, Longidx1[, Longidx2... ]);
Parameters
Return Values
Returns true if the function is successful. Returns false if the function fails.
Example
Bool success = edrEmptyInput(DETAIL.BASIC_SERVICE);
edrFieldConnectInfo
This function retrieves the Info string associated with the token for the corresponding EDR field. By default, the Info string contains the description of the token type. This is the default for ASCII object types.
The function works only when the EDR field is associated with a token through either the edrInputMap or edrConnectToken function.
Syntax
String edrFieldConnectInfo(EdrFieldfield[, Longidx1[, Longidx2...]]);
Parameters
Return Values
Returns the Info string associated with the token for the EDR field if the function is successful. Returns an empty string if the path through the EDR tree structure is not valid.
Example
logStdout("This field is of type: "+ edrFieldConnectInfo\
( DETAIL.RECORD_TYPE ) +"\n" ); edrFieldTokenBytePos
This function calculates the position of the token associated with the corresponding EDR field. The calculation is in bytes starting from the beginning of the input file.
The function works only when the EDR field is associated with a token through either the edrInputMap or edrConnectToken function.
Syntax
Long edrFieldTokenBytePos(EdrFieldfield[, Longidx1[, Longidx2...]]);
Parameters
Return Values
Returns the position (in bytes) of the token associated with the EDR field if the function is successful. Returns -1 if the EDR field is not associated with a token.
Example
if ( edrString( DETAIL.RECORD_TYPE ) != "020" )
{
logStdout("Error, unexpected value at bytePosition= \
"+ longToStr(edrFieldTokenBytePos( DETAIL.RECORD_TYPE )) + \
"\n" );
}edrGetAdditionalStream
This function gets the name of an additional EDR output stream given an array index number.
Each EDR contains a default output stream and any number of additional output streams.
Syntax
String edrGetAdditionalStream(Long index_number);Return Values
Returns the name of the stream if the function is successful. Returns an empty string for all other conditions.
Example
String streamName = edrGetAdditionalStream( 5)
if ( streamName == "" )
{
logStdout( "ERROR: no additional stream set at index: 5\n" );
}edrGetError
This function retrieves the names of the attached error messages.
Syntax
String edrGetError(Long idx);Return Values
Returns the name of the attached error if the function is successful. Returns an empty string if the function fails.
Example
for ( i = 0; i < edrNumErrors(); i = i+1 )
{
logStdout( "ERROR " + longToStr(i) + ": " + \
edrGetError(i) + "\n" );
}edrGetErrorParameters
This function retrieves the parameters associated to a specified error.
Syntax
Long edrGetErrorParameters(Longidx, Arrayparams);
Parameters
Return Values
Returns the number of parameters in the array. Returns 0 if this function fails or if there are no parameters in the array.
Example
String paramList[];
Long paramCount;
Long Tap3MaxParamCount = 7;
long i;
for ( i = 0; i < edrNumErrors(); i = i+1 )
{
if (edrGetError(i) == "ERR_TAP3_RET")
{
// get parameter list
paramCount = edrGetErrorParameters(i, paramList);
// check if enough parameters
if (paramCount != Tap3MaxParamCount)
{
logStdout( "ERROR " + longToStr(i) + ": " + edrGetError(i) \
+ ", has missing parameters\n" );
}
}
}edrGetErrorSeverity
This function retrieves the severity for each of the associated errors.
Syntax
Long edrGetErrorSeverity(Long idx);Return Values
Returns 0 if the severity of the attached error is Normal. Returns 1 if the severity of the attached error is Warning. Returns 2 if the severity of the attached error is Minor. Returns 3 if the severity of the attached error is Major. Returns 4 if the severity of the attached error is Critical. Returns -1 if the function fails.
Example
for ( i = 0; i < edrNumErrors(); i = i+1 )
{
logStdout( "ERROR " + longToStr(i) + " Severity: " + \
longToStr(edrGetErrorSeverity(i)) + "\n" );
}edrGetStream
This function gets the output stream for an EDR.
Syntax
String edrGetStream();
Parameters
None.
Return Values
Returns the name of the actual string.
Example
String streamName = edrGetStream();
edrHasError
This function retrieves the names of the attached error messages.
Syntax
Bool edrHasError(String error);Return Values
Returns the name of the attached error if the function is successful. Returns an empty string if the function fails.
Example
for ( i = 0; i < edrNumErrors(); i = i+1 )
{
logStdout( "ERROR " + longToStr(i) + ": " + \
edrGetError(i) + "\n" );
}edrInputState
This function retrieves the input state of an EDR field.
Syntax
Long edrInputState(EdrFieldfield, Longidx1[, Longidx2...]);
Parameters
Return Values
Returns 1 if the EDR field contains a default value that was added due to missing input data in the CDR. Returns 2 if the EDR field contains a default value that was added due to empty input data in the CDR. Returns 3 if the EDR field is not populated or contains data that came from the CDR.
Example
Bool boolvar;
boolvar = edrEmptyInput(DETAIL.BASIC_SERVICE);
boolvar = edrMissingInput(DETAIL.QOS_USED);
switch(edrInputState(DETAIL.BASIC_SERVICE))
{
case EDR_INPUT_MISSING:
logStdout("DETAIL.BASIC_SERVICE: MISSING\n");
break;
case EDR_INPUT_EMPTY:
logStdout("DETAIL.BASIC_SERVICE: EMPTY\n");
break;
default: // "uninteresting" values
logStdout("DETAIL.BASIC_SERVICE: OTHER\n");
break;
}edrInternalState
This function returns the internal state of an EDR field.
Syntax
Long edrInternalState(EdrFieldfield, Longidx1[, Longidx2...]);
Parameters
Return Values
Returns 0 if cleared. Returns 1 if connected. Returns 2 if initialized. Returns 3 if set. Returns 4 if restored. Returns 5 if restored asset. Returns -1 if the function fails.
Example
Long state = edrInternalState(DETAIL.ASS_CBD.CP.CHARGE);
edrInternalStateEx
This function returns the internal state of an EDR field.
Syntax
Long edrInternalStateEx(Stringfield, LongindicesArray, LongnumIndices);
Parameters
Return Values
Returns 0 if cleared. Returns 1 if connected. Returns 2 if initialized. Returns 3 if set. Returns 4 if restored. Returns 5 if restored asset. Returns -1 if the function fails.
Example
Long indicesArray [ ]; Long numberOfIndices; String edrFieldName; edrFieldName = "DETAIL.ASS_CBD.CP.CHARGE"; indicesArray[0]=0; indicesArray[1]=0; numberOfIndices=2; Long state = edrInternalStateEx(edrFieldName, indicesArray, numberOfIndices);
edrIsValidDetail
This function determines whether the current EDR container is a valid detail container. This helps you avoid processing of EDR containers that will be discarded.
Syntax
Bool edrIsValidDetail();
Parameter
None.
Return Values
Returns true if the current EDR container is a valid detail container. Returns false if it is not a valid detail container.
Example
if ( edrIsValidDetail() == true )
{
// process the edr
} edrLong
This function retrieves and sets Long values in the current EDR container. This function is usually used to retrieve Long values. When setting Long values, use the function as left-hand value in an assignment statement.
Syntax
Long edrLong(EdrFieldfield[, Longidx1[, Longidx2...]]);
Parameters
Return Values
Returns the Long value of the EDR field if the function is successful. Returns 0 if the EDR has no Long field or if the path through the EDR tree structure is not valid.
Example
edrLong( DETAIL.CHARGED_TAX_RATE ) = 1600;
edrLongEx
This function retrieves and sets Long values in the current EDR container. This function is usually used to retrieve Long values. When setting Long values, use the function as left-hand value in an assignment statement.
Syntax
Long edrLongEx(Stringfield, LongindicesArray, LongnumIndices);
Parameters
Return Values
Returns the Long value of the EDR field if the function is successful. Returns 0 if the EDR has no Long field or if the path through the EDR tree structure is not valid.
Example
Long indicesArray [ ]; Long numberOfIndices; String edrFieldName; edrFieldName = "DETAIL.CHARGED_TAX_RATE"; numberOfIndices=0; edrLongEx(edrFieldName, indicesArray, numberOfIndices) = 1600;
edrMaxSeverity
This function finds the maximum severity of the errors added to the current EDR container.
Syntax
Long edrMaxSeverity();
Parameters
None.
Return Values
Returns the maximum severity of the errors of the EDR container if the function is successful. Returns 0 if there are no errors. Returns -1 if the function fails.
Example
if ( edrMaxSeverity() == 0 )
{
// The edr has no errors with severity > 0
}edrMissingInput
This function sets the state of a field to EDR_INPUT_MISSING when the field is not present in the CDR.
Syntax
Bool edrMissingInput(EdrFieldfield, Longidx1[, Longidx2...]);
Parameters
Return Values
Returns true if the function is successful. Returns false if the function fails.
Example
Bool success = edrMissingInput(DETAIL.QOS_USED);
edrNumDatablocks
This function determines the number of data blocks of the specified type.
Syntax
Long edrNumDatablocks(EdrFieldblock[, Longidx1[, Longidx2...]]);
Parameters
Return Values
Returns the number of data blocks (the number is greater than or equal to 0) if the function is successful. Returns a value less than 0 if the function fails.
Example
for ( i = 0; i < edrNumDatablocks( DETAIL.ASS_CBD ); i = i + 1 )
{
String recordType = edrString( DETAIL.ASS_CBD.RECORD_TYPE, i );
} edrNumDatablocksEx
This function determines the number of data blocks of the specified type.
Syntax
Long edrNumDatablocksEx(Stringblock, LongindicesArray, LongnumIndices);
Parameters
Return Values
Returns the number of data blocks (the number is greater than or equal to 0) if the function is successful. Returns a value less than 0 if the function fails.
Example
Long indicesArray [ ];
Long numberOfIndices;
String edrFieldName;
edrFieldName = "DETAIL.ASS_CBD";
numberOfIndices=0;
for ( i = 0; i < edrNumDatablocksEx(edrFieldName, indicesArray, numberOfIndices); i = i + 1 )
{
String recordType = edrString( DETAIL.ASS_CBD.RECORD_TYPE, i );
} edrNumErrors
This function accesses the number of error messages attached to the current EDR container.
Syntax
Long edrNumErrors();
Parameters
None.
Return Values
Returns the number of attached error messages (this number will be greater than or equal to 0) if the function is successful. Returns -1 if the function fails.
Example
for ( i = 0; i < edrNumErrors(); i = i+1 )
{
logStdout( "ERROR " + longToStr(i) + ": " + \
edrGetError(i) + "\n" );
} edrNumTokens
This function accesses the number of tokens attached to the current EDR container.
Syntax
Long edrNumTokens();
Parameters
None.
Return Values
Returns the number of attached tokens (this number will be greater than or equal to 0) if the function is successful. Returns -1 if the function fails.
Example
for ( i = 0; i < edrNumTokens(); i = i+1 )
{
logStdout( "Token " + longToStr(i) + ": " + \
edrGetToken(i) + "\n" );
} edrRemoveAdditionalStream
This function removes additional output streams from an EDR. Each EDR has a default output stream and any number of additional output streams.
Note:
This function will not remove the default output stream.
Syntax
Bool edrRemoveAdditionalStream(String output_stream_name);Return Values
Returns true if the function is successful or if the named stream does not exist. Returns false for all other conditions.
Example
This example shows how to use edrRemoveAdditionalStream to remove an output stream.
if ( edrRemoveAdditionalStream( "TELOut1" ) == false
{
logStdout( "ERROR: failed to remove additional stream: TELOut1\n" );
}Example 85-1 Example removeoutmod.isc file
This example removes output module streams:
removeoutmod.isc
---------------
function onDetailEdr
{
if (edrRemoveAdditionalStream( "TelOut1" ) == true)
{
logStdout("Stream TelOut1 removed ");
}
if (edrRemoveAdditionalStream( "TelOut2" ) == true)
{
logStdout("Stream TelOut2 removed ");
}
} // end onDetailEdr + end iScript edrSetContentType
This function sets the content type of the current EDR container.
Syntax
Bool edrSetContentType(Long content);Parameter
-
EDR_UNKNOW_CONT
-
EDR_HEADER
-
EDR_DETAIL
-
EDR_TRAILER
-
EDR_START
-
EDR_STOP
-
EDR_BEGIN
-
EDR_END
-
EDR_BEGIN_TRANSACTION
-
EDR_END_TRANSACTION
Return Values
Returns true if the content type is valid. Returns false if the container type is not valid.
Example
if ( edrSetContentType( EDR_TRAILER ) == false )
{
logFormat( "ERROR: edrSetContentType() failed" );
}edrSetCurrent
This function sets the current EDR container. All EDR container functions only access the current EDR container.
Syntax
Bool edrSetCurrent(Long index);Parameter
Return Values
Returns true if there is an EDR container with the specified index. Returns false if there is no EDR container with that index.
Example
Long index = edrDuplicate();
if ( index < 0 )
{
logFormat( "ERROR: duplication of edr failed" );
}
else
{
// Set the output stream for the old container
edrSetStream( "OrigOutput" );
// Set the output stream for the new container
if ( edrSetCurrent( index ) == true )
{
edrSetStream( "NewOutput" );
}
}edrSetIsValidDetail
This function sets the EDR container's valid detail flag. The valid detail flag specifies whether the EDR container is to be discarded.
Syntax
Void edrSetIsValidDetail(Bool flag);Return Values
Returns nothing.
Example
if ( ... )
{
// record shall be discarded
edrSetIsValidDetail( false );
}edrSetStream
This function sets the output stream for an EDR. Internally, Pipeline Manager uses stream numbers instead of stream names. For this reason, the name specified must be converted to a number. If you use a constant as the stream name, the conversion can be performed at compile time, resulting in quicker performance than using a stream name that is not a constant. The second advantage of using a constant is that the existence of the stream can be checked at compile time.
Caution:
Illegal stream names lead to compilation errors.
Syntax
Bool edrSetStream(String streamName);Return Values
Returns true if the output stream is successfully set. Returns false if the output stream does not exist.
Example
// This is the FAST method: The stream number can be evaluated \
at compile time.
// There is also a check if the stream exists at compile time.
if ( edrSetStream( "NationalOutput" ) == false )
{
logFormat( "ERROR: edrSetStream() failed" );
}
// This is the SLOW method and should be avoided.
String nationalOutput = "NationalOutput"
if ( edrSetStream( nationalOutput ) == false )
{
logFormat( "ERROR: no stream " + nationalOutput );
}edrString
This function retrieves and sets string values in the current EDR container. This function is usually used to retrieve string values. When setting string values, use this function as the left-hand value in an assignment statement.
Syntax
String edrString(EdrFieldfield[, Longidx1[, Longidx2 ...]]);
Parameters
Return Values
Returns the string value of the EDR field if the function is successful. Returns an empty string if the path through the EDR tree structure is not valid.
Example
if ( edrString( DETAIL.RECORD_TYPE) == "020" ) edrString(DETAIL.RECORD_TYPE) = "021";
edrStringEx
This function retrieves and sets string values in the current EDR container. This function is usually used to retrieve string values. When setting string values, use this function as the left-hand value in an assignment statement.
Syntax
String edrStringEx(Stringfield, LongindicesArray, LongnumIndices);
Parameters
Return Values
Returns the string value of the EDR field if the function is successful. Returns an empty string if the path through the EDR tree structure is not valid.
Example
Long indicesArray [ ]; Long numberOfIndices; String edrFieldName; edrFieldName = "DETAIL.RECORD_TYPE"; numberOfIndices=0; if ( edrStringEx(edrFieldName, indicesArray, numberOfIndices) == "020" ) edrStringEx(edrFieldName, indicesArray, numberOfIndices) = "021";
edrTokenString
This function retrieves the content of each token, as identified by their indexes. When the index is not available, as for a function call with no argument, this function returns the complete byte string attached to the EDR. The byte string corresponds to the original input string that generated the EDR.
The function works only when the EDR field is associated with a token through either the edrInputMap or edrConnectToken function.
Syntax
String edrTokenString([Long idx]);Parameter
Return Values
Returns the contents of the tokens if the function is successful. Returns an empty string if the index is invalid or there are no tokens associated with the EDR.
Example
logStdout( "The original (input) record corresponding to this \ EDR is \n" + edrTokenString() );
iRulesModeOn
This function enables the iRules mode. In the iRules mode, the init section does not consider the specified indices for an EDR field.
Syntax
iRulesModeOn();
Parameters
None.
Return Values
Returns nothing.
Example
INIT_SCRIPT:
function testPrint
{
iRulesModeOff();
logFormat("hyewons era hardc
-->"+edrString(DETAIL.CUST_A.PRODUCT.ERA.PA.KEY,0,0,0,1));
logFormat("hyewons era hardc
-->"+edrString(DETAIL.CUST_A.PRODUCT.ERA.PA.KEY,0,0,0,2));
iRulesModeOn();
}iRulesModeOff
This function disables the iRules mode. Disabling iRules mode ensures that the INIT takes the specified indices.
Syntax
iRulesModeOff();
Parameters
None.
Return Values
Returns nothing.
Example
INIT_SCRIPT:
function testPrint
{
iRulesModeOff();
logFormat("hyewons era hardc
-->"+edrString(DETAIL.CUST_A.PRODUCT.ERA.PA.KEY,0,0,0,1));
logFormat("hyewons era hardc
-->"+edrString(DETAIL.CUST_A.PRODUCT.ERA.PA.KEY,0,0,0,2));
iRulesModeOn();
}pipelineName
This function retrieves the name of the pipeline in which the script is running.
Syntax
String pipelineName();
Parameters
None.
Return Values
Returns the pipeline name.
Example
logPipeline("This script runs in pipeline " + pipelineName());stopPipeline
This function stops the pipeline from which it is called. After the pipeline is stopped, the operator must restart the pipeline using the ifw command.
Note:
This function does not work within the BEGIN function because the pipeline object instantiation is not completed when the BEGIN function is executed.
Note:
Use this function only when there is an unrecoverable error that requires operation intervention.
Syntax
Void stopPipeline();
Parameters
None.
Return Values
Returns nothing.
Example
if (unrecoverableError())
{
stopPipeline();
}File Manipulation Functions
Table 85-7 contains file manipulation functions.
Table 85-7 File Manipulation Functions
| Function | Description |
|---|---|
|
Closes a file that was opened earlier using the fileOpen function. |
|
|
Copies a file. |
|
|
Deletes a file. |
|
|
Checks to see whether the end of file has been reached. |
|
|
Flushes the contents of the file buffer to disk. |
|
|
Determines whether a file is currently open. |
|
|
Opens a file for reading or writing. If the file is already open, the old file will be closed and the new file will be opened. The open mode is equivalent to the fopen C function. |
|
|
Reads a line from the input file. The line is read until the function encounters an end-of-line or end-of-file character or until maxLen is reached. |
|
|
Renames a file. |
|
|
Sets the read/write pointer on a specific position (in bytes from the beginning of the file) in an opened file. |
|
|
Retrieves the position (measured in bytes from the start of the file) of the read/write pointer in an opened file. |
|
|
Writes a Long value, as a string and not in binary mode, to the output file. |
|
|
Writes a string to the output file. |
fileClose
This function closes a file that was opened earlier using the fileOpen function.
Syntax
Void fileClose(File file);Return Values
Returns nothing.
Example
File out;
if ( fileOpen( out, "test.txt", "w" ) == true )
{
fileWriteStr( out, "Hello World!" );
fileClose( out );
}fileCopy
This function copies a file.
Syntax
Bool fileCopy(Stringold, Stringnew);
Return Values
Returns true when a file has been copied. Returns false when it has not been copied.
Example
if ( fileCopy(tempName, realname ) == false )
{
logStdout( "Failed to copy" + tempName + " to " + realName );
}fileDelete
This function deletes a file.
Syntax
Void fileDelete(String file);Return Values
Returns true if the file was successfully deleted. Returns false if the function failed.
Example
if ( fileDelete( "test.txt" ) == false )
{
logFormat( "ERROR: failed to delete 'test.txt'" );
}fileEof
This function checks to see whether the end of file has been reached.
Syntax
Bool fileEof(File file);Return Values
Returns true if the end of the file was reached or if no file was open. Returns false if it does not reach the end of the file.
Example
while ( fileReadLine( in, line, 2048 ) == true )
{
...
}
if ( fileEof( in ) == false )
{
logFormat( "ERROR: read error()" );
}fileFlush
This function flushes the contents of the file buffer to disk.
Syntax
Bool fileFlush(File file);Return Values
Returns true if the file was successfully flushed. Returns false if the function failed.
Example
fileWriteStr( out, "Price is " + price );
if ( fileFlush( out ) == false )
{
logFormat( "ERROR: fileFlush() failed" );
}fileIsOpen
This function determines whether a file is currently open.
Syntax
Bool fileIsOpen(File file);Return Values
Returns true if the file is open. Returns false if the function failed.
Example
if ( fileIsOpen( in ) == false )
{
logFormat( "ERROR: file is not open" );
}fileOpen
This function opens a file for reading or writing. If the file is already open, the old file will be closed and the new file will be opened. The open mode is equivalent to the fopen C function.
Syntax
Bool fileOpen(Filefile, StringfileName, StringopenMode);
Parameters
- file
-
The file you want to open.
- fileName
-
The name of the file you want to open.
- openMode
-
The string specifying the open mode. Specify this parameter as you would for the fopen C function. The following description of open mode is from the Linux ManPage:
-
r: Open text file for reading. The stream is positioned at the beginning of the file.
-
r+: Open for reading and writing. The stream is positioned at the beginning of the file.
-
w: Truncate file to zero length or create text file for writing. The stream is positioned at the beginning of the file.
-
w+: Open for reading and writing. The file is created if it does not exist; otherwise it is truncated. The stream is positioned at the beginning of the file.
-
a: Open for writing. The file is created if it does not exist. The stream is positioned at the end of the file.
-
a+: Open for reading and writing. The file is created if it does not exist. The stream is positioned at the end of the file.
Return Values
Returns true if the file was opened successfully. Returns false if the function failed.
Example
File out;
if ( fileOpen( out, "test.txt", "w" ) == false )
{
logFormat( "ERROR: fileOpen() failed" );
}fileReadLine
This function reads a line from the input file. The line is read until the function encounters an end-of-line or end-of-file character or until maxLen is reached.
Syntax
Bool fileReadLine(Filefile, Stringline, LongmaxLen);
Parameters
Return Values
Returns true if the line is successfully read. Returns false if the function failed.
Example
File in;
String line;
if ( fileOpen( in, "test.txt", "r" ) == true )
{
fileReadLine( in, line, 100 );
}fileRename
This function renames a file. The new name can specify a different directory, but both the old and new file must be in the same file system.
Syntax
Bool fileRename(Stringold, Stringnew);
Return Values
Returns true if the file is successfully renamed. Returns false if the function failed.
Example
if ( fileRename( tempName, realName ) == false )
{
logStdout( "Failed to rename " + tempName + " to " + realName );
}fileSeek
This function sets the read/write pointer on a specific position (in bytes from the beginning of the file) in an opened file.
Syntax
Bool fileSeek(Filefile, Longoffset);
Parameters
Return Values
Returns true when setting the read/write pointer in an opened file is successful. Returns false when it has not been successful.
Example
long offset = fileTell( myfile );
if ( fileSeek(myfile, offset) == false )
{
logStdout( "could not set the file read/write pointer to " + longToStr(offset) );
}fileTell
This function retrieves the position (measured in bytes from the start of the file) of the read/write pointer in an opened file.
Syntax
Long fileTell(File file);Return Values
Returns the position of the read/write pointer when successful. Returns (-1) when an error occurs.
Example
long offset = fileTell( Myfile );
if ( offset != (-1) )
{
logStdout( "the read pointer is currently on position " + longToStr() + " to " + realName );
}fileWriteLong
This function writes a Long value to the output file. The Long value is written as a string and not in binary mode.
Syntax
Bool fileWriteLong(Filefile, Longvalue[, Longlen[, Boolleading[, Stringpad]]]);
Parameters
- file
-
The file you want to write the Long value to.
- value
-
The Long value to write.
- len
-
The length of the output.
- leading
-
Specifies whether to add leading or trailing characters: true adds leading characters, false adds trailing characters.
- pad
-
The padding character to use as the first character of the string.
Return Values
Returns true if the Long value is successfully written. Returns false if the function failed.
Example
File out;
if ( fileOpen( out, "test.txt", "w" ) == true )
{
fileWriteLong( out, 100, 14, true, "0" );
}fileWriteStr
This function writes a string to the output file. The string is not automatically terminated by an end-of-line character.
Syntax
Bool fileWriteStr(Filefile, Stringstring);
Parameters
- file
-
The file you want to write the string to.
- string
-
The string to write.
- len
-
The length of the output. This parameter is optional.
- leading
-
Specifies whether to add leading or trailing characters: true adds leading characters, false adds trailing characters.
- pad
-
The padding character to use as the first character of the string.
Return Values
Returns true if the string is successfully written. Returns false if the function failed.
Example
File out;
if ( fileOpen( out, "test.txt", "w" ) == true )
{
fileWriteStr( out, "Hello World!\n" );
}Flist Manipulation Functions
Table 85-8 contains flist manipulation functions.
Table 85-8 Flist Manipulation Functions
| Function | Description |
|---|---|
|
Returns the content of the current flist in string format. |
|
|
Replaces the current flist with an flist based on the input string. |
|
|
Counts the number of elements at the top level of the current flist. |
|
|
Replaces the current flist with an empty flist. |
|
|
Retrieves the date value from the current flist. |
|
|
Retrieves the decimal value from the current flist. |
|
|
Removes an array from the current flist. |
|
|
Deletes a field from the current flist. |
|
|
Retrieves the array element ID from the specified array field. |
|
|
Puts the field name from the flist into string1 and the error text into string2. |
|
|
Retrieves the long value from the current flist. |
|
|
Counts the number of elements in an array in the current flist. |
|
|
Resets the array to the previous value. |
|
|
Creates and sets the array element into which other functions set field values. |
|
|
Sets a date field in the current flist. |
|
|
Sets a decimal field in the current flist. |
|
|
Sets a long value within a PIN_FLDT_INT or PIN_FLDT_EMUN field in the current flist. |
|
|
Sets a POID field in the current flist. |
|
|
Sets a string field in the current flist. |
|
|
Retrieves the string value from the current flist. |
|
|
Calls the opcode specified in the parameter. |
fListToString
This function returns the content of the current flist in string format. The function calls PIN_FLIST_TO_STR.
Syntax
String fListToString();
Parameters
None.
Return Values
Returns the content of the current flist in string format. Returns an empty string on failure.
Example
logStdout(fListToString()); fListCreateNew();
fListFromString
This function removes the current flist and replaces it with an flist based on a string that you pass in as a parameter. The function calls PIN_STR_TO_FLIST.
Syntax
Bool fListFromString(const String flist_str);Return Values
Returns true on success and false on failure.
Example
String flistStr =
"0 PIN_FLD_ARRAY ARRAY [0] allocated 13, used 1" +
"1 PIN_FLD_STRING STR [0] \"testing\"" +
"1 PIN_FLD_DECIMAL DECIMAL [0] 0.000" +
"1 PIN_FLD_INT INT [0] 60";
if(!fListFromString(flistStr))
{
// flist could not be parsed
}fListCount
This function counts the number of elements at the top level of the current flist by calling PIN_FLIST_COUNT.
Syntax
Long fListCount();
Parameters
None.
Return Values
Returns the number of elements at the top level of the current flist. Returns -1 on failure.
Example
Long resultCounts = fListCount();
fListCreateNew
This function removes the current flist and replaces it with an empty flist.
Syntax
Bool fListCreateNew();
Parameters
None.
Return Values
Returns true on success and false on failure.
Example
fListCreateNew();
fListDate
This function retrieves the date value from a PIN_FLDT_TSTAMP field in the current flist. If the field is stored in substructs or arrays, you must specify the path. You must include element IDs for all arrays.
Syntax
Date fListDate([const Stringpath_field[, Longelem_id]] [,const Stringpath_field2[, Longelem_id] ... , ] const Stringfield);
Parameters
Return Values
Returns the date value from the specified PIN_FLDT_TSTAMP field. Returns INVALID_DATETIME on failure.
Example
fListDate("PIN_FLD_RESULTS",1,"PIN_FLD_CREATED_T");fListDecimal
This function retrieves the decimal value from a PIN_FLDT_DECIMAL field in the current flist. If the field is stored in substructs or arrays, you must specify the path. You must include element IDs for all arrays.
Syntax
Decimal fListDecimal([const Stringpath_field[, Longelem_id]] [,const Stringpath_field2[, Longelem_id] ... , ] const Stringfield);
Parameters
Return Values
Returns the decimal value from the specified PIN_FLDT_DECIMAL field. Returns INVALID_DECIMAL on failure.
Example
fListDecimal("PIN_FLD_OBJ_DESC", 0, "PIN_FLD_OBJ_ELEM", 6, "PIN_FLD_ORDER");fListDropElem
This function removes an array from the current flist by calling PIN_FLIST_ELEM_DROP.
Syntax
Bool fListDropElem(const Stringarray_field[,Long = 0elem_id]);
Return Values
Returns true on success and false on failure.
Example
fListDropElem("PIN_FLD_ARGS", 2);fListElemid
This function retrieves the array element ID from the specified array field using a 0-n index in the array.
Syntax
Decimal fListElemid([const String path_field [, Long elemid]] [,const String path_field2 [, Long elemid] ... , ] const String array_field, Long index);
Parameters
- path_field
-
A parent substruct or array field that is part of the path to the target array. The parameter is repeated in the case of nested arrays.
- elem_id
-
The element ID of a parent array or substruct.
- field
-
The name of the array from which the element ID is retrieved.
- index
-
The 0-n index of the exact array element, the ID of which to return.
Return Values
Returns the elem_id value of the array element specified by 0-n index. Returns INVALID_ARRAY on failure.
Example
fListElemid("PIN_FLD_OBJ_DESC", 0, "PIN_FLD_OBJ_ELEM", 0);fListGetErrorText
This function puts the field name from the flist into string1 and the error text into string2. You can use the error information for logging or other purposes.
Syntax
Void fListGetErrorText(Stringstring1, Stringstring2);
Parameters
Return Values
Returns nothing.
Example
// Opcode failed String s1; String s2; fListGetErrorText(s1, s2);
fListLong
This function retrieves the long value from a PIN_FLDT_INT or PIN_FLDT_ENUM field in the current flist. If the field is stored in substructs or arrays, you must specify the path. You must include element IDs for all arrays.
Syntax
Long fListLong([const Stringpath_field[, Longelem_id]] [,const Stringpath_field2[, Longelem_id] ... , ]const Stringfield) ;
Parameters
Return Values
Returns the long value from the specified PIN_FLDT_INT or PIN_FLDT_ENUM field. Returns 0 on error.
Example
fListLong("PIN_FLD_OBJ_DESC", 0, "PIN_FLD_OBJ_ELEM", 6, "PIN_FLD_LENGTH")fListNumElem
This function counts the number of elements in a PIN_FLD_ARRAY field by calling PIN_FLIST_ELEM_COUNT. If the array is stored in substructs or other arrays, you must specify the path. You must include element IDs for all arrays.
Syntax
Long fListNumElem([const Stringpath_field[, Longelem_id]] [,const Stringpath_field2[, Longelem_id] ... , ] const Stringarray_field, Longelem_id);
Parameters
Return Values
Returns the number of elements in the specified array. Returns -1 on failure.
Example
Long resultCounts = fListNumElem("PIN_FLD_OBJ_DESC", 0, "PIN_FLD_OBJ_ELEM", 6);fListPopElem
This function resets the array to the previous value.
Syntax
Void fListPopElem();
Parameters
None.
Return Values
Returns nothing.
Example
fListPopElem();
fListPushElem
This function creates and sets the array element into which other functions set field values. The function calls PIN_FLIST_ELEM_ADD.
Syntax
Bool fListPushElem(const Stringarray_field[,Long = 0element]);
Parameters
Return Values
Returns true on success and false on failure.
Example
fListPushElem("PIN_FLD_ARGS", 2);fListSetDate
This function sets a date field in the current flist.
Syntax
Bool fListSetDate(constStringfield, Datevalue);
Return Values
Returns true on success and false on failure.
Example
Date d = strToDate("20060402143600"); // Apr 2, 2006 2:36 pm
fListSetDate("PIN_FLD_EFFECTIVE_T", d);fListSetDecimal
This function sets a decimal field in the current flist.
Syntax
Bool fListSetDecimal(const Stringfield, Decimalvalue);
Return Values
Returns true on success and false on failure.
Example
fListSetDecimal("PIN_FLD_DECIMAL",edrDecimal(DETAIL.ASS_DATA.VALUE,1));fListSetLong
This function sets a long value in a PIN_FLDT_INT or PIN_FLDT_ENUM field in the current flist.
Syntax
Bool fListSetLong(const Stringfield, Longvalue);
Return Values
Returns true on success and false on failure.
Example
fListSetLong("PIN_FLD_INT",edrLong(DETAIL.ASS_DATA.QUANTITY, 1));fListSetPoid
This function sets a POID field in the current flist.
Syntax
Bool fListSetPoid(Stringfield, Stringpoid);
Return Values
Returns true on success and false on failure.
Example
Bool success = fListSetPoid( "PIN_FLD_POID", "0.0.0.1 /account 1099832 0" );
fListSetString
This function sets a string field in the current flist.
Syntax
Bool fListSetString(const Stringfield, Stringvalue);
Return Values
Returns true on success and false on failure.
Example
fListSetString("PIN_FLD_USAGE_TYPE", usageClass);fListString
This function retrieves the string value from a PIN_FLDT_STR or PIN_FLDT_POID field in the current flist. If the field is stored in substructs or arrays, you must specify the path. You must include element IDs for all arrays.
Syntax
String fListString([const Stringpath_field[, Longelem_id]] [,const Stringpath_field2[, Longelem_id] ... , ] const Stringfield);
Parameters
Return Values
Returns the string value from the specified PIN_FLDT_STR or PIN_FLDT_POID field. Returns NULL_STRING on failure.
Example
fListString("PIN_FLD_OBJ_DESC", 0, "PIN_FLD_OBJ_ELEM", 6, "PIN_FLD_DESCR")opcodeExecuteInternal
This function calls the opcode specified in the parameter. You can call any opcode.
You use this function in iScripts that run in a real-time pipeline. The function uses the Connection Manager (CM) context information in the EDR to call the opcode through the existing connection.
See "opcodeExecute" for information about calling opcodes in batch pipelines.
Before calling opcodeExecuteInternal, you compose the input flist by using the flist extension functions. The input flist is stored and used internally by the opcode call.
The output flist of the opcode call is also stored internally and replaces the input flist. It can be retrieved by using the flist extension functions again.
If there is an error in the opcode call, an error buffer will be set. The error text can be retrieved with the fListGetErrorTextfunction. The error text can then be logged.
Syntax
Bool opcodeExecuteInternal(Longopcode, Longflags);
Parameters
Return Values
Returns true on success and false on failure.
Example
Long PCM_OP_SEARCH = 7; ... if ( opcodeExecuteInternal(PCM_OP_SEARCH, 0) == false ) ....
Hash and Array Functions
Table 85-9 contains hash and array functions.
Table 85-9 Hash and Array Functions
| Function | Description |
|---|---|
|
Clears an array. |
|
|
Determines the size of an array. |
|
|
Clears a hash. |
|
|
Checks to determine whether a hash-array contains a specific value. |
|
|
Retrieves all keys used in an associative array. |
|
|
Removes an entry from an associative array. |
arraySize
This function determines the size of an array.
Syntax
Long arraySize(Array array);Return Values
Returns the size of the array.
Example
for ( i = 0; i < arraySize( array ); i = i + 1 )
{
logStdout( "array[" + longToStr(i) + "] = " + array[i] );
}hashContains
This function checks to determine whether a hash-array contains a specific value.
Syntax
Void hashContains(Hashhash, Stringkey);
Return Values
Returns true if the hash contains the value specified by key. Returns false if the hash does not contain this value.
Example
if ( hashContains( hash, "Hamburg" ) == true )
{
logStdout( "The hash contains a value for 'Hamburg'" );
}hashKeys
This function retrieves all keys used in an associative array.
Syntax
Long hashKeys(Hashhash, Arraykey);
Parameters
Return Values
Returns the number of elements in the hash.
Example
String keys[];
Long age{};
Long i;
age{"Mary"} = 23;
age{"John"} = 18;
Long entries = hashKeys( age, keys );
for ( i = 0; i < entries; i = i+1 )
{
logStdout( "Age of " + keys[i] + " is " + \
longToStr( age{keys[i]} ) + "\n" );
}hashRemove
This function removes an entry from an associative array.
Syntax
Bool hashRemove(Hashhash, Stringkey);
Return Values
Returns true if the element was removed successfully. Returns false if the function failed.
Example
if ( hashRemove( hash, "Hamburg" ) == true )
{
logStdout( "The entry 'Hamburg' was removed from the hash\n" );
}Mapping Functions
Table 85-10 contains mapping functions.
Table 85-10 Mapping Functions
| Function | Description |
|---|---|
|
Maps Long values to other Long values. |
|
|
Maps string values to other string values. |
longDecode
This function maps Long values to other Long values.
Syntax
Long longDecode(LongtoMap, Longdefault[[, const Longsrc1, const Longdest1] ...]);
Parameters
Return Values
Returns the matching destination value if the destination exists. Returns the value you specified in the default parameter if there is no destination.
Example
newRecordType = longDecode( oldRecordType, C_defaultRecordType, C_oldDetail, C_newDetail, C_oldHeader, C_newHeader, C_oldTrailer, C_newTrailer );
strDecode
This function maps string values to other string values.
Syntax
String strDecode(StringtoMap, Stringdefault[[, const Stringsrc1, const Stringdest1] ...]);
Parameters
Return Values
Returns the matching destination value if the destination exists. Returns the value you specified in the default parameter if there is no destination.
Example
newRecordType = strDecode( oldRecordType, C_defaultRecordType, C_oldDetail, C_newDetail, C_oldHeader, C_newHeader, C_oldTrailer, C_newTrailer );
Opcode Calling Functions
Table 85-11 contains opcode calling functions.
Table 85-11 Opcode Calling Functions
| Function | Description |
|---|---|
|
Calls the specified opcode. |
|
|
Obtains a connection from the specified connection pool. |
|
|
Calls PCM_OP, which performs the operation of the specified opcode and then returns the contents of the error buffer (ebuf) produced by the operation. |
opcodeExecute
This function calls the opcode specified in the parameter. You can call any opcode.
You use this function to call opcodes in batch pipelines. See "opcodeExecuteInternal" for information about calling opcodes from real-time pipelines.
Before calling opcodeExecute the first time in an iScript, you must call opcodeGetConnection to get the connection from the connection pool. If the CM restarts or if the existing connection is broken, an error results. To get a new connection, add more conditional checks for opcodeExecute and then call opcodeGetConnection.
For example:
.....
Bool connectionOpened;
Long PCM_OP_NUMBER = 200;
function onBeginEdr
{
connectionOpened = false;
}
function getCMConnection
{
if (connectionOpened == false)
{
{String connectionPool = "ifw.DataPool.CMConnectionPool.Module"; connectionOpened = opcodeGetConnection(connectionPool);
}
}
function Bool callOpcode
{
Long retryCount;
Bool success;
Long numberOfRetries = 10;
String fldName;
String errMsg;
getCMConnection();
success = opcodeExecute(PCM_OP_NUMBER, 0);
if (success == false)
{
fListGetErrorText (fldName, errMsg);
if (errMsg == "PIN_ERR_CONNECTION_LOST")
{
connectionOpened = false;
for (retryCount = 0; ((retryCount < numberOfRetries) and (connectionOpened == false)); retryCount = retryCount + 1)
{
connectionOpened = false
getCMConnection();
if(connectionOpened == true)
{
success = opcodeExecute(PCM_OP_NUMBER,0);
}
if ((connectionOpened == false) and (retryCount >= numberOfRetries))
{
logStdout("Error executing opcode PCM_OP_GET_PIN_VIRTUAL_TIME due to lost connection with CM\n");
}
if ((success == false)
{
logStdout("Error: "+ errMsg + "while executing opcode PCM_OP_GET_PIN_VIRTUAL_TIME\n");
}
return success;
function onDetailEdr()
{
Bool success = callOpcode()
}
.....
Before calling opcodeExecute, you compose the input flist by using the flist extension functions. The input flist is stored and used internally by the opcode call.
The output flist of the opcode call is also stored internally and replaces the input flist. It can be retrieved by using the flist extension functions again.
If there is an error in the opcode call, an error buffer will be set. The error text can be retrieved with the fListGetErrorText function. The error text can then be logged.
Syntax
Bool opcodeExecute(Longopcode, Longflags);
Parameters
Return Values
Returns true on success and false on failure.
Example
... Long PCM_OP_SEARCH = 7; Bool success = opcodeExecute(PCM_OP_SEARCH, 0) ...
opcodeGetConnection
This function obtains a connection to the CM from the specified connection pool in a batch pipeline. You must configure a connection pool in the pipeline before using this function. See DAT_ConnectionPool in the BRM documentation for information about configuring a connection pool.
In an iScript, you must call opcodeGetConnection before calling opcodeExecute the first time. You do not need to call opcodeGetConnection again for subsequent opcode calls in the same script. Adding more conditional checks ensures that opcodeGetConnection is not called every time a CDR is processed.
Note:
This function is required in iScripts used in batch pipelines only. It is not necessary in real-time pipelines.
For example:
........
Bool connectionOpened;
function onBeginEdr
{
connectionOpened = false;
}
function getCMConnection
{
if(connectionOpened == false)
{
String connectionPool = "ifw.DataPool.CMConnectionPool.Module";
connectionOpened = opcodeGetConnection(connectionPool);
}
if(connectionOpened == false)
{
logStdout("Unable to get connection to CM\n");
}
}
.........Syntax
Bool opcodeGetConnection(String connectionPool);Return Values
Returns true on success and false on failure.
Example
... String connectionPool = "ifw.DataPool.CMConnectionPool.Module"; Bool success = opcodeGetConnection(connectionPool); ...
pcmOpCatch
This function calls the PCM_OP opcode, which performs the operation of the specified opcode and then returns the contents of the error buffer (ebuf) produced by the operation. This enables the calling iScript to resolve any errors that occur during the operation without exiting the logic the iScript is performing.
Syntax
pcmOpCatch(opcode, flags, in_flistp, ebufp);
Parameters
- opcode
-
The name or number of the opcode whose operation PCM_OP is to perform.
Note:
Opcode numbers are listed in the pcm_ops.h file in the BRM_home/include directory, where BRM_home is the directory in which you installed the BRM components.
- flags
-
The flags supported by the opcode being called. See the opcode description for information on the flags it takes.
-
If the opcode takes no flags, enter 0.
-
To specify multiple flags, separate the flag names with a vertical bar ( | ).
-
Return Values
This function returns nothing.
Errors are passed back to the calling iScript through the specified error buffer.
Example
pcmOpCatch(7, SRCH_DISTINCT, search, PINERR);
Pipeline System Functions
Table 85-12 contains Pipeline system functions.
Table 85-12 Pipeline System Functions
| Function | Description |
|---|---|
|
Determines the name of the format the script is running in. |
|
|
Writes messages to the pipeline log |
|
|
Writes messages to the pipeline log. |
|
|
msgArg |
Deprecated. |
|
msgName |
Deprecated. |
|
msgNumArgs |
Deprecated. |
|
Returns the name of the registry node in which the script (iScript or input/output grammar) is running. |
|
|
Retrieves values from the registry. |
|
|
Sends a request to a registered object and waits for an answer (i.e., synchronous messaging). |
|
|
Sets the usable flag for the script. If the usable flag is set to false in the BEGIN function during Pipeline Manager startup, Pipeline Manager will not start to process CDRs. The false setting can be useful if the iScript initialization fails. |
|
|
Sends an event to the event handler. |
|
|
Stops the format; for example, after critical errors. |
formatName
This function determines the name of the format the script is running in.
Syntax
String formatName();
Parameters
None.
Return Values
Returns the format name.
Example
logFormat( "This script runs in format " + formatName() );
logPipeline
This function writes messages to the pipeline log.
Syntax
Void logPipeline(Stringmsg[, Longseverity]);
Parameters
-
0 = Debug
-
1 = Normal
-
2 = Warning
-
3 = Minor error
-
4 = Major error
-
5 = Critical error
The default is 0.
Return Values
Returns nothing.
Example
logPipeline( "ERROR: critical database error occurred", 4 );
registryNodeName
This function returns the name of the registry node in which the script (iScript or input/output grammar) is running.
Syntax
String registryNodeName();
Parameters
None.
Return Values
Returns the name of the registry node in which the script (iScript or input/output grammar) is running.
Example
logFormat( "This script is located at registry: " + registryNodeName () ); //this will return the following result, //This script is located at registry: ifw.Pipelines.ciber25.Functions.Thread1.FunctionPool.myIScript.Module.Scripts.retrieve
regString
This function retrieves values from the registry.
Syntax
String regString(String name);Return Values
Returns the specified registry entry if it exists. Returns an empty string if there is no registry entry with that name.
Example
if ( regString( "IntegRate.DataPool.Customer.Module.Source" ) ==\
"FILE" )
{
logFormat( "Customers are read from file" );
}reqSend
This function sends a request to a registered object and waits for an answer (i.e., synchronous messaging).
Syntax
Bool reqSend(StringreqDestination, StringreqName, ArrayinParams, ArrayoutParams);
Parameters
Request Names
- REQ_NEWSEQUENCENUMBER
-
(Sequencer) Returns the new sequence number.
- REQ_CC
-
(Pipeline) Returns the country code defined in the registry for this pipeline.
- REQ_MCC
-
(Pipeline) Returns the mobile country code defined in the registry for this pipeline.
- REQ_NAC
-
(Pipeline) Returns the national access code value defined in the registry for this pipeline.
- REQ_IAC
-
(Pipeline) Returns the international access code defined in the registry for this pipeline.
- REQ_IAC_SIGN
-
(Pipeline) Returns the international access code sign value defined in the registry for this pipeline.
- REQ_NDC
-
(Pipeline) Returns the national destination code value defined in the registry for this pipeline.
- REQ_REJECT_STREAM_NAME
-
(Pipeline) Returns the reject stream name defined in the registry for this pipeline.
- REQ_REJECT_STREAM
-
(Pipeline) Returns the reject stream number defined in the registry for this pipeline.
- REQ_EVENTHANDLER_NAME
-
(ifw) Returns the event handler name.
- REQ_ERROR_FILENAME
-
(Input) Returns the name and path of the error file.
- REQ_INPUT_FILENAME
-
(Input) Returns the name and path of the input file.
- REQ_INPUT_TEMP_FILENAME
-
(Input) Returns the name and path of the temporary input file.
- REQ_DONE_FILENAME
-
(Input) Returns the name and path of the done file.
- REQ_RETURN_FILENAME
-
(Input) Returns the name and path of the return file.
- REQ_OUTPUT_FILENAME
-
(Output) Returns the name and path of the output file.
- REQ_OUTPUT_TEMP_FILENAME
-
(Output) Returns the name and path of the temporary output file.
Return Values
Returns true if the request has been sent and an answer received successfully. Returns false if sending the request has failed.
Example
sendArray [0] = "abcdefg.so142" ;
if ( reqSend( reg_InputStream, "REQ_ERROR_FILENAME",sendArray, receiveArray)==true )
{
String errFileName = receiveArray[0]; // the fully qualified filename (including path)
}scriptUsable
This function sets the usable flag for the script. If the usable flag is set to false in the BEGIN function during Pipeline Manager startup, Pipeline Manager will not start to process CDRs. The false setting can be useful if the iScript initialization fails.
Note:
You can use this function only in the iScript modules and not in the input grammar.
Syntax
Void scriptUsable(Bool usable);Return Values
Returns nothing.
Example
function BEGIN
{
...
if ( fileOpen( inFile, "data.txt", "r" ) == false )
{
logFormat( "failed to open data file 'data.txt'" );
scriptUsable( false );
}
}sendEvent
This function sends an event to the event handler.
Syntax
Bool sendEvent(Stringevent[, Stringarg1[, Stringarg2...]]);
Parameters
Return Values
Returns true if the event was successfully sent. Returns false if the function failed.
Example
if ( sendEvent( EVT_FILE_PROCESSED, filename ) == false )
{
logFormat( "ERROR: sendEvent() failed" );
};Static Functions
This section describes static functions.
EXT_ConvertCli::convert
This function normalizes wireless and wireline CLIs into international format.
Syntax
const BAS_String EXT_ConvertCli::convert(const BAS_String& cli, const BAS_String& modInd, const long typeOfNumber, const BAS_String& natAccessCode, const BAS_String& intAccessCode, const BAS_String& countryCode, const BAS_String& intAccessCodeSign, const BAS_String& natDestinCode );
Parameters
- cli
-
CLI to normalize.
- modInd
-
Modification Indicator, for example, "00".
- typeOfNumber
-
Type Of Number, for example, 0.
- natAccessCode
-
National Access Code, for example, "0".
- intAccessCode
-
International Access Code, for example, "00".
- countryCode
-
Country Code, for example, "49".
- intAccessCodeSign
-
International Access Code Sign, for example, "+".
- natDestinCode
-
National Destination Code, for example, "172".
Return Values
Returns a CLI in international normalized format: <iac>< cc><ndc>extension.
Example
... #include "EXT_ConverterExt.hpp" #include "EXT_CliConverter.hpp" BAS_String normCli; BAS_String cli = "01721234567"; normCli = EXT_ConvertCli::convert( cli, "00", 0, "0", "00", "49", "+", "172" ); // normCli now contains: 00491721234567 ...
EXT_ConvertIPv4::convert
This function normalizes IPv4 addresses.
Syntax
const BAS_String EXT_ConvertIPv4::convert( const BAS_String& ip );
Return Values
Returns an IP address in normalized format.
Dots (.) are skipped. Tokens are left-padded to 3 digits with zeroes.
Example
.... #include "EXT_ConverterExt.hpp" #include "EXT_CliConverter.hpp" BAS_String normIp; BAS_String ip = "192.168.1.253"; normIp = EXT_ConvertIPv4::convert( ip ); // normIp now contains: 192168001253 ...
EXT_ConvertIPv6::convert
This function normalizes IPv6 addresses.
Syntax
const BAS_String EXT_ConvertIPv6::convert( const BAS_String& ip );
Return Values
Returns an IP address in normalized format.
Dots (.) are skipped. Tokens are left-padded to 4 digits with zeroes.
Example
.... #include "EXT_ConverterExt.hpp" #include "EXT_CliConverter.hpp" BAS_String normIp; BAS_String ip = "0:0:0:AF:E:0:1:FE"; normIp = EXT_ConvertIPv6::convert( ip ); // normIp now contains: 00000000000000AF000E0000000100FE ...
EXT_ConvertIPv4onv6::convert
This function normalizes IPv4 over IPv6 addresses. The decimal IPv4 address is converted into hexadecimal representation.
Syntax
const BAS_String EXT_ConvertIPv4onv6::convert( const BAS_String& ip );
Return Values
Returns an IPv6 address in normalized format.
Dots (.) are skipped. Tokens are left-padded to 4 digits with zeroes.
Example
.... #include "EXT_ConverterExt.hpp" #include "EXT_CliConverter.hpp" BAS_String normIp; BAS_String ip = "0:0:0:0:0:0:192.168.10.1"; normIp = EXT_ConvertIPv4onv6::convert( ip ); // normIp now contains: 000000000000000000000000C0A80A01 ...
Standard Functions
Table 85-13 contains standard functions.
Table 85-13 Standard Functions
| Function | Description |
|---|---|
|
Closes the connection to the Diameter client |
|
|
Gets the current system time in milliseconds. |
|
|
Gets the state of a Diameter client. |
|
|
Acquires the mutex specified by the handle (a number that identifies the mutex). When the mutex specified by the handle is already acquired by another thread, the function call is blocked unless the other thread releases the mutex by calling the mutexRelease function. |
|
|
Creates a mutex that can later be accessed by its handle. |
|
|
Used to destroy a mutex that is no longer needed. |
|
|
Releases a mutex that has been acquired. It unblocks a functional call by another thread that has been trying to acquire the mutex using the mutexAcquire function. |
|
|
Makes the process sleep. |
|
|
Starts the timer. |
|
|
Executes a command line in a file. |
|
|
Gets an environment variable. |
closeClientConnection
This function closes the connection to the Diameter client.
Syntax
Void closeClientConnection(Socket Num);
Return Values
Returns nothing.
Example
if( (commandCode == DIA_DP_REQUEST) and (commandFlag == 0) )
{
logPipeline("CommandCode: DIA_DP_REQUEST. Closing the connection.",0);
closeClientConnection(edrLong(DETAIL.ASS_PROTOCOL_INFO.ASS_DIAMETER_INFO.SOCKETID,0,0));
}
currentTimeInMillis
This function gets the current system time in milliseconds.
You can use this function in your custom iScript to record the time when a pipeline or a pipeline module starts processing an EDR and when it finishes processing the EDR. You can then calculate the difference between the start and end times to determine the latency of the EDR processing in a pipeline or module.
You can include the iScript at any point in a pipeline to determine the latency of an EDR processing between two points in a pipeline.
Syntax
Long currentTimeInMillis();
Parameters
None.
Return Values
Returns the current system time as a long value.
Example
This example gets the current system time and logs a message:
logStdout("The Time in milliseconds is = " + longToStr(currentTimeInMillis()) + "\n"); getClientState
This function gets the state of a Diameter client.
Syntax
Long getClientState(Socket Num);
Return Values
Returns one of the following state values:
-
0 = STATE_INITIAL
-
1 = STATE_OKAY
-
2 = STATE_DOWN
Example
state = getClientState(edrLong(DETAIL.ASS_PROTOCOL_INFO.ASS_DIAMETER_INFO.SOCKETID,0,0));
mutexAcquire
This function acquires the mutex specified by the handle (a number that identifies the mutex). When the mutex specified by the handle is already acquired by another thread, the function call is blocked unless the other thread releases the mutex by calling the mutexRelease function.
Syntax
Bool mutexAcquire(Long handle);Return Values
Returns true if a valid handle is used and the mutex is acquired. Returns false if an invalid handle is used and the mutex is not acquired.
Example
// enter the protected area mutexAcquire (handle) // protected area //leave the protected area mutexRelease(handle)
mutexCreate
This function creates a mutex that can later be accessed by its handle.
Syntax
Long mutexCreate();
Parameters
None.
Return Values
Returns a handle (>0) if the mutex was created successfully. Returns <0 if the mutex was not created successfully.
Example
long handle; function BEGIN
{
handle = mutexCreate ( )
if (handle < 0)
{
logStdout("Mutex creation failed\n");
}
}mutexDestroy
This function destroys a mutex that is no longer needed.
Syntax
Bool mutexDestroy(Long handle);Return Values
Returns true when destroying the mutex is successful. Returns false when destroying the mutex has not been successful.
Example
if ( mutexDestroy (handle) == false )
{
logStdout( "Illegal mutex handle\n");
}mutexRelease
This function releases a mutex that has been acquired. It unblocks a functional call by another thread that has been trying to acquire the mutex using the mutexAcquire function.
Syntax
Bool mutexRelease(Long handle);Return Values
Returns true when a valid handle was used and the mutex is released successfully. Returns false when the handle used is invalid and the mutex is not released.
Example
// enter the protected area mutexAcquire (handle) // protected area // leave the protected area mutexRelease(handle)
sysExecute
This function executes a command line in a file. When you call this function in an iScript, you must configure an EventHandler in the pipeline registry file. For example:
EventHandler
{
ModuleName = EVT
Module
{
Events
{
}
Buffer
{
Size = 1000
}
}
}
Syntax
Long sysExecute(StringcommandLine[StringreturnBuffer, LongtimeToWait]);
Parameters
- commandLine
-
The command line to execute. The value must be the path to an executable, followed by any arguments.
- returnBuffer
-
A string to collect the output produced on stdout by commandLine. The stdin and stderr for commandLine will be the terminal.
- timeToWait
-
The maximum time (in seconds) to wait for the response from the event handler. Command execution is terminated when timeToWait expires.
Return Values
Returns a Long value greater than 0 if the function is successful. Returns -1 if the specified path points to a file that is either not readable or not executable.
Example
// list the contents of the /data/input directory
String cmdline = "/usr/bin/ls -l /data/input";
String retbuf;
Long timeToWait = 10; // 10 seconds
Long retval = sysExecute( cmdline, retbuf, timeToWait );
if ( retval != -1 )
{
// code to process retbuf
logStdout( retbuf );
}sysGetEnv
This function specifies an environment variable you want returned.
Syntax
String sysGetEnv(String envVariable);Return Values
Returns the specified environment variable and its settings.
Example
logStdout("*******************-\n");
logStdout( "PATH=" + sysGetEnv( "PATH") +"\n");directory \n");String Functions
Table 85-14 contains string functions.
Table 85-14 String Functions
| Function | Description |
|---|---|
|
Converts a decimal value into a string. |
|
|
Converts a decimal value into a hexadecimal string. Use round(value) or trunc(value) to remove the decimal portion if you do not want it to be coded in hexadecimal. |
|
|
Converts a Long value into a hexadecimal string. |
|
|
Converts a Long value into a string. |
|
|
Converts the first character in the input string to its byte value. |
|
|
Maps string values to other string values. |
|
|
Checks to see if a string ends with a special suffix. |
|
|
Converts each pair of characters in a given hexadecimal string into the equivalent single-byte ASCII character in a new string. The returned string is half the size of the original. Only ASCII values from 0 through 255 can be handled by this function. Characters from multi-byte character sets will cause unexpected results. The function fails if memory cannot be allocated for the string to be returned. |
|
|
Converts a hexadecimal string to a decimal value. |
|
|
Converts a hexadecimal string into a Long value. |
|
|
Determines the length of a string. |
|
|
Compares a regular expression to a string, looking for a match. |
|
|
Pads a string to a specific length. The padding character and the justification can be selected. |
|
|
Replaces substrings in a string. |
|
|
Searches for a substring inside another string. |
|
|
Searches for a regular expression to a string. |
|
|
Splits a string according to a specific separator character and stores the resulting tokens in a string array. |
|
|
Checks to see if a string starts with a specified prefix. |
|
|
Removes special leading or trailing characters from a string. |
|
|
Converts each character in a given string into its two-character hexadecimal equivalent in a new string. The returned string is twice the size of the original. Only ASCII values from 0 through 255 can be handled by this function. Characters from multi-byte character sets cause unexpected results. The function fails if memory cannot be allocated for the string to be returned. |
|
|
Extracts a substring from a string. |
|
|
Converts a string into a date value. |
|
|
Converts string values to decimal values. |
|
|
Converts a string value to a Long value. |
|
|
Converts a string to lowercase characters. |
|
|
Converts a string to uppercase characters. |
decimalToStr
This function converts a decimal value into a string.
Syntax
String decimalToStr(Decimalvalue[, Longprecision]);
Parameters
Return Values
Returns the value as a string.
Example
logFormat( "Pi = " + decimalToStr(pi) ); logFormat( "Pi = " + decimalToStr(pi,2) );
decimalToStrHex
This function converts a decimal value into a hexadecimal string.
Note:
Use round(value) or trunc(value) to remove the decimal portion if you do not want it to be coded in hexadecimal. For example, use round(0) to omit the .000 if you want only integer values returned.
Syntax
String decimalToStrHex(Decimalvalue[, Stringseparator[, Longprecision]]);
Parameters
Return Values
Returns the decimal value as a hexadecimal string.
Example
logFormat( "X = " + decimalToStr(x) + "(" + decimalToStrHex(x) + \
" hexadecimal)" );longToHexStr
This function converts a Long value into a hexadecimal string.
Syntax
String longToHexStr(Long value);Return Values
Returns the value as a hexadecimal string.
Example
logFormat( "X = " + longToStr(x) + "(" + longToHexStr(x) + \
" hexadecimal)" );strByteValue
This function converts the first character in the input string to its byte value.
Syntax
Long strByteValue(String string);Return Values
Returns the byte value of the first character if the function is successful. Returns 0 if the string is empty.
Example
Long ascA = strByteValue( "A" ); logStdout( "ASCII(A) = " + longToStr( ascA ) + "\n" );
strDecode
This function maps string values to other string values.
Syntax
String strDecode(StringtoMap, Stringdefault[[, const Stringsrc1, const Stringdest1] ...]);
Parameters
Return Values
Returns the matching destination value if the destination exists. Returns the value you specified in the default parameter if there is no destination.
Example
newRecordType = strDecode( oldRecordType, C_defaultRecordType, C_oldDetail, C_newDetail, C_oldHeader, C_newHeader, C_oldTrailer, C_newTrailer );
strEndsWith
This function checks to see if a string ends with a special suffix.
Syntax
Bool strEndsWith(Stringstring, Stringsuffix);
Return Values
Returns true if the string ends with the specified suffix. Returns false if the string does not end with the suffix.
Example
if ( strEndsWith( filename, ".txt" ) )
{
logFormat( "file suffix is .txt" );
}strHexStrToStr
This function converts each pair of characters in a given hexadecimal string into the equivalent single-byte ASCII character in a new string. The returned string is half the size of the original. For example, if you pass the string 58595A373839 to strHexStrToStr, it returns the string XYZ789.
Only ASCII values from 0 through 255 can be handled by this function. Characters from multi-byte character sets will cause unexpected results. The function fails if memory cannot be allocated for the string to be returned.
Syntax
String strHexStrToStr(source);Parameter
-
It must have an even number of characters.
-
Only numeric characters and A through F are permitted.
-
It cannot be empty.
Return Values
Returns the string converted to ASCII if the function is successful.
If source has hexadecimal representations for embedded nulls, the returned string contains embedded nulls. The caller must interpret such strings correctly.
Example
String source = ""58595A373839"; String result = strHexStrToStr(source); logStdout(result);
strHexToDecimal
This function converts a hexadecimal string to a decimal value.
Syntax
Decimal strHexToDecimal(Stringstring[, Stringseparator[, Longprecision]]);
Parameters
Return Values
Returns a decimal value when the value entered for string is successfully converted to a decimal value. Returns 0.0 if string is not a valid hexadecimal decimal/Long value and is therefore not converted to a decimal value.
Example
logStdout ( "1FF hex is " + decimalToStr ( strHexToDecimal ( "1FF" ) ) + " decimal\n" );
strHexToLong
This function converts a hexadecimal string into a Long value.
Syntax
Long strHexToLong(String string);Return Values
Returns the hexadecimal string as a Long value.
Example
logStdout( "1FF hex is " + strHexToLong( "1FF" ) + " decimal\n" );
strLength
This function determines the length of a string.
Syntax
Long strLength(String string);Return Values
Returns the string length in characters if the function is successful.
Example
if ( strLength( edrString( DETAIL.RECORD_TYPE ) ) != 3 )
{
logFormat( "WARNING: illegal RECORD_TYPE" );
};strMatch
This function compares a regular expression to a string, looking for a match.
Syntax
String strMatch(Stringstring, StringregExp[, Longindex]);
Parameters
Return Values
Returns the matching part of the string if the function is successful. Returns 0 if the function does not find a match.
Example
if ( strMatch( filename, ".*\\.edr" ) != "" ) // IMPORTANT: the first \ is removed by the compiler!!!!
{
logFormat( filename + " is a *.edr file" );
}strPad
This function pads a string to a specific length. The padding character and the justification can be selected.
Note:
The original string you started with will be truncated. If the original string is greater in length than the string you set up to result from applying the String strPad function.
Syntax
String strPad(Stringstring, StringpadChar, Longlength, BoolisLeftJustified);
Parameters
- string
-
The string to pad (or truncate) to a specified length.
- padChar
-
The pad character to use (the first of the string is used if empty).
- length
-
The desired length of the returned string. If length is less than or equal to 0, an empty string is returned.
- isLeftJustified
-
If set to true, it specifies that the string be left justified. If set to false, it specifies that the string be right justified.
Return Values
Returns the padded or truncated string.
Example
String resString;
resString = strPad ("hello", " ", 2, true); // -> resString = "he";
resString = strPad ("hello", " ", 2, false); // -> resString = "he";
resString = strPad ("hello", " ", 10, true); // -> resString = "hello ";
resString = strPad ("hello", " ", 10, false); // -> resString = " hello";
resString = strPad ("hello", "0", 10, false); // -> resString = "00000hello";
resString = strPad ("hello", " ", -2, true); // -> resString = "";strReplace
This function replaces substrings in a string.
Syntax
String strReplace(StringtoReplace, Longpos, Longlen, Stringreplace);
Parameters
Return Values
Returns a string with the replacement string in the correct position. Returns an empty string if pos and len do not specify a valid substring.
Example
logFormat( strReplace( "Hello !", 5, 1, "World " ) );
strSearch
This function searches for a substring inside another string.
Syntax
Long strSearch(Stringstring, Stringsearch[, Longindex]);
Parameters
Return Values
Returns the starting index (this should be a value greater than or equal to 0) for the search within the string. Returns a value less than 0 if the function does not find the string.
Example
if ( strSearch( edrString( DETAIL.B_NUMBER ), "0049", 0 ) >= 0 )
{
logFormat( "B-Number contains '0049'" );
}strSearchRegExpr
This function searches for a regular expression to a string.
Syntax
Long strSearchRegExpr(Stringstring, const StringregExp[, Longindex]);
Parameters
Return Values
Returns the position index (this should be a value greater than or equal to 0) of the string if the function is successful. Returns a value less than 0 if the function does not find the string.
Example
if ( strSearchRegExpr( filename, ".*\\.doc", 0 ) >= 0 )
// IMPORTANT: the first \ is removed by the compiler
{
logFormat( filename + " is a *.doc file" );
}strSplit
This function splits a string according to a specific separator character and stores the resulting tokens in a string array.
Syntax
Long strSplit(Arrayres, Stringstring, Stringsep);
Parameters
Return Values
Returns the number of elements in the resulting array.
Example
String ListArray[];
String ListString;
ListArray="first,second,third"
Long nbElem = strSplit( ListArray, ListString, "," );
for (Long i=0 ; i<nbElem ; i=i+1)
{
logStdout( "Element " + ListArray[i] + "\n");
}strStartsWith
This function checks to see if a string starts with a specified prefix.
Syntax
Bool strStartsWith(Stringstring, Stringprefix);
Parameters
Return Values
Returns true if the string starts with the specified prefix. Returns false if the string does not start with the specified prefix.
Example
if ( strStartsWith( edrString( DETAIL.B_NUMBER ), "0049" ))
{
isNationalCall = true;
}strStrip
This function removes special leading or trailing characters from a string.
Syntax
Bool strStrip(Stringstring[, LongstripMode[, StringstripChar]]);
Parameters
- string
-
The string from which you want to remove leading or trailing characters.
- stripMode
-
The strip mode:
-
STRIP_LEADING
-
STRIP_TRAILING
-
STRIP_BOTH
The default is STRIP_LEADING.
Return Values
Returns the stripped string.
Example
String test = "--------Hello-------------";
if ( strStrip( test, STRIP_BOTH, "-" ) == "Hello" )
{
logStdout( "strStrip() works correct" );
}strStrToHexStr
This function converts each character in a given string into its two-character hexadecimal equivalent in a new string. The returned string is twice the size of the original. For example, if you pass the string XYZ789 to strStrToHexStr, it returns the string 58595A373839.
Only ASCII values from 0 through 255 can be handled by this function. Characters from multi-byte character sets cause unexpected results. The function fails if memory cannot be allocated for the string to be returned.
Syntax
String strStrToHexStr(source);Parameter
Return Values
Returns the string converted to hexadecimal if the function is successful.
Example
String source = "XYZ789"; String result = strStrToHexStr(source); logStdout(result);
strSubstr
This function extracts a substring from a string.
Syntax
String strSubstr(Stringstring, Longpos, Longlen);
Parameters
Return Values
Returns the specified string if the function is successful. Returns an empty string if pos and len do not specify a valid substring.
Example
if ( strLength( string ) > 6 )
{
string = strSubstr( string, 0, 6 );
}strToDate
This function converts a string into a date value. The only supported string format is YYYYMMDDHHMMSS.
Syntax
Date strToDate(String dateStr);Parameters
- %%
-
The literal % character.
- %d
-
The day of the month; for example, 29. The range is 00-31.
- %H
-
The hour of the 24-hour day; for example, 14. The range is 00-23.
- %m
-
The month of the year, from 01; for example, 02. The range is 01-12.
- %M
-
The minutes after the hour; for example, 34. The range is 00-59.
- %S
-
The seconds after the minute; for example, 56. The range is 00-59.
- %y
-
The year of the century, from 00; for example, 04 for 2004. The range is 01-99. In most cases, you should avoid this parameter.
- %Y
-
The year including the century; for example, 1994.
Return Values
Returns a valid date if the input string is in the right format. Returns an invalid date if the format is not correct.
Example
edrDate(DETAIL.CHARGING_START_TIMESTAMP) = \
strToDate("24.12.2002", "%d. %m. %Y");strToDecimal
This function converts string values to decimal values.
Syntax
Decimal strToDecimal(String string);Return Values
Returns the string converted to a decimal value if the function is successful. Returns 0 if the string is not a valid decimal value.
Example
x = x + strToDecimal( "13.32" );
strToLong
This function converts a numeric string value to a Long value. An alphanumeric string is returned as 0.
Syntax
Long strToLong(String string);Return Values
Returns the string converted to a Long value if the function is successful. Returns 0 if the string is not a valid Long value.
Example
if ( strToLong( edrString(DETAIL.RECORD_TYPE) ) == 20 )
{
// Basic detail record
}strToLower
This function converts a string to lowercase characters.
Syntax
String strToLower(String string);Return Values
Returns the string converted to lowercase characters if the function is successful.
Example
if ( strToLower( "HELLO" ) == "hello" )
{
...
}Transaction Management Functions
Table 85-15 contains transaction management functions.
Table 85-15 Transaction Management Functions
| Function | Description |
|---|---|
|
Sends a request to the Transaction Manager to cancel the current transaction. |
|
|
Sends a request to the Transaction Manager to roll back the current transaction. |
|
|
Allows the iScript module to request the reason for the rollback in the onRollback function. |
|
|
Returns the type of an item in the currently processed transaction. |
|
|
Returns the number of items processed in the currently processed transaction. |
|
|
Used to access the extension value of each item in the current transaction. |
|
|
Used to access the stream name of each item in the current transaction. |
|
|
Returns the transaction ID of the transaction currently being processed. |
edrDemandCancel
This function sends a request to the Transaction Manager to cancel the current transaction.
Syntax
Bool edrDemandCancel();
Parameters
None.
Return Values
Returns true if the function is successful. Returns false if the function fails.
Example
if ( edrDemandCancel() == false )
{
logStdout( "ERROR: failed to demand cancel" );
}edrDemandRollback
This function sends a request to the Transaction Manager to roll back the current transaction.
Syntax
Bool edrDemandRollback([rollbackReason]);Return Values
Returns true if the function is successful. Returns false if the function fails.
Example
Request for rollback success status:
if ( edrDemandRollback() == false )
{
logStdout( "ERROR: failed to demand rollback" );
}
Request for rollback with a reason:
edrDemandRollback("Invalid Input file")edrRollbackReason
This function allows the iScript module to request the reason for the rollback in the onRollback function.
Syntax
String edrRollbackReason();
Parameters
None.
Return Values
Returns a string indicating the reason for the rollback.
Example
function Bool onRollback
{
rollbackReason = edrRollbackReason();
logStdout( "rollback reason= " + rollbackReason + "\n");
return true;
}tamItemType
This function returns the type of an item in the currently processed transaction. These items are only accessible for the functions dealing with transactions like onCancel, onCommit, onRollback, and so forth.
Syntax
Long tamItemType(Long idx);Return Values
Returns the type of the specified item:
-
TAM_NORMAL
-
TAM_RECYCLE
-
TAM_RECYCLE_TEST
Returns a value of <0 if there is no current transaction in all other functions or the index is out of range.
Example
function onCancel
{
Long i;
for ( i=0; i<tamNumTransItems(); i=i+1 )
{
if ( tamItemType(i) == TAM_NORMAL )
{
...
}
}
} tamNumTransItems
This function returns the number of items processed in the currently processed transaction. The count includes only items accessible for the functions dealing with transactions like onCancel, onCommit, onRollback, and so forth.
Syntax
Long tamNumTransItems();
Parameters
None.
Return Values
Returns the number of items in the transaction currently being processed. Returns 0 if there is no current transaction in all other functions or there are no items in the current transaction.
Example
function onCancel
{
Long i;
for ( i=0; i<tamNumTransItems(); i=i+1 )
{
...
}
} tamStreamExtension
This function accesses the extension value of each item in the current transaction. The index should be between 0 and tamNumTransItems()–1. Usually, the extension value contains the sequence number of the currently processed stream.
Syntax
String tamStreamExtension(Long idx);Return Values
Returns the stream extension string if the function is successful. Returns an empty string if the function fails.
Example
function onCommit
{
Long i;
for ( i=0; i<tamNumTransItems(); i=i+1 )
{
logFormat( "commiting " + tamStreamName(i) + \
" with extension " + tamStreamExtension(i) );
}
} tamStreamName
This function accesses the stream name of each item in the current transaction. The index should be between 0 and tamNumTransItems( )–1.
Syntax
String tamStreamName(Long idx);Return Values
Returns the stream name if the function is successful. Returns an empty string if the function fails.
Example
function onCommit
{
Long i;
for ( i=0; i<tamNumTransItems(); i=i+1 )
{
logFormat( "committing " + tamStreamName(i) );
}
}tamTransId
This function returns the transaction ID of the transaction currently being processed. This function should only be used with functions dealing with transactions like onCancel, onCommit, onRollback, and so forth.
Syntax
Decimal tamTransId();
Parameters
None.
Return Values
Returns the current transaction ID. Returns 0.0 if there is no current transaction in the other functions.
Example
function onCancel
{
Decimal transId = tamTransId();
...
}