# 7 Pipeline Manager iScript Functions

This chapter provides reference information for Oracle Communications Billing and Revenue Management (BRM) Pipeline Manager iScript functions.

For information on creating custom iScript and iRules modules, see "Creating iScripts and iRules" in BRM Developer's Guide.

## Arithmetic Functions

Table 7-1 contains the arithmetic functions.

Table 7-1 Arithmetic Functions

Function Description

decimalAbs

Derives an absolute value from a decimal value.

decimalToLong

Converts the integer portion of a decimal value to a Long value.

longAbs

Derives an absolute value from a Long value.

longToDecimal

Converts a Long value to a decimal value.

round

Rounds a decimal value to a specified number of decimal places.

sqrt

Calculates the square root of the input value.

trunc

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);
```

Parameter

source

The decimal value from which to derive the absolute value.

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);
```

Parameter

source

The decimal value to convert to a Long value.

Return Values

Returns the Long value of the integer portion of the decimal value.

Example

```Long p = decimalToLong( 3.1415 );
```

### longAbs

This function derives an absolute value from a Long value.

Syntax

```Long longAbs(Long source);
```

Parameter

source

The Long value from which to derive the absolute value.

Return Values

Returns the derived absolute value.

Example

```if ( x == longAbs( x ) )
{
logFormat( "x is a positive value" );
}
```

### longToDecimal

This function converts a Long value to a decimal value.

Syntax

```Decimal longToDecimal(Long value);
```

Parameter

value

The Long value to convert to a decimal value.

Return Values

Returns the converted decimal value.

Example

```Decimal bytesPerSecond = longToDecimal( bytes ) / \
longToDecimal( seconds );
```

### round

This function rounds a decimal value to a specified number of decimal places.

Syntax

```Decimal round(Decimal value [, Long places] [, String mode]);
```

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
```

### sqrt

This function calculates the square root of the input value.

Syntax

```Decimal sqrt(Decimal value);
```

Parameter

value

The value for which to calculate the square root.

Return Values

Returns the square root of the input value.

Example

```Decimal c = sqrt( a*a + b*b );
```

### trunc

This function truncates a decimal value to a specified number of decimal places.

Syntax

```Decimal trunc(Decimal value [, Long places]);
```

Parameters

value

The value to truncate.

places

The number of decimal places by which the value should be truncated (the default is 0).

Return Values

Returns the value truncated to the specified decimal place.

Example

```Decimal t = trunc( 3.1415, 3 ); // t now is 3.141
```

## ASN.1 Functions

Table 7-2 contains the ASN.1 functions.

Table 7-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.

asnTreeCreate

Creates a tree in memory to hold an ASN.1 file structure.

asnTreeDelete

Deletes the last created or used ASN.1 tree.

asnTreeDeleteNodeByIndex

Deletes a node from the ASN.1 tree.

asnTreeFlush

Flushes the content of the ASN.1 tree to the output.

asnTreeGetStoredNode

Gets the active (working) node from a list of created and store

asnTreePop

Backs up one level in the ASN.1 tree hierarchy.

asnTreePushTag

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.

asnTreeStoreNode

Stores an index to a constructed block node in the ASN.1 tree, when the block position in the tree is fixed.

This function adds an integer object to the current active node of the ASN.1 tree.

Syntax

```Bool asnTreeAddInteger(String blockName, Long value);
```

Parameters

blockName

The name of the block to add (exact type from the block description file).

value

The integer to insert as the value.

Return Values

Returns True if successful; otherwise, returns False.

Example

```...
...
```

This function adds a string object to the current active node of the ASN.1 tree.

Syntax

```Bool asnTreeAddString(String blockName, String value)
```

Parameters

blockName

The name of the block to add. This must exactly match the type from the block description file.

value

The string to insert as the value.

Return Values

Returns True if successful; otherwise, returns False.

Example

```...
...
```

### 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);
```

Parameter

nodeIdx

Node index in the ASN.1 tree as returned by asnTreeStoreNode().

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);
```

Parameter

nodeIdx

Node index in the ASN.1 tree as returned by asnTreeStoreNode().

Return Values

Returns True if successful; otherwise, returns False.

Example

```...
asnTreeGetStoredNode(networkInfoIdx);
//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

blockName

The name of the structured block to add (exact type from the block description file).

isIndefiniteLength

Flag to indicate that the generated block has to use indefinite lengths. The default is false, that is, it stores the exact size of the value field in the objects header.

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:
details
trailer
;
{
asnTreeCreate();
asnTreePushTag("TAP3.QoSRequestedList");
}
;
trailer:
TRAILER
{
asnTreePop(); //for asnTreePushTag("TAP3.QoSRequestedList");
asnTreeFlush();
asnTreeDelete();
}
;
details:
details
DETAIL
{
asnTreePushTag("TAP3.QoSRequested");
asnTreePop(); //for asnTreePushTag("TAP3.QoSRequested");
}
| /*EMPTY*/
;
}
```

## Database Connection Functions

Table 7-3 contains database connection functions.

Table 7-3 Database Connection Functions

Function Description

dbBeginTransaction

Starts a new transaction using the specified connection.

dbCloseConnection

Closes a connection to the Pipeline Manager database.

dbCloseResult

Closes a result handle after processing the result data.

dbCommitTransaction

Commits a transaction to a specific connection.

dbConnection

Establishes a connection to the Pipeline Manager database. The handle returned by this function should be used in future calls to the dbExecute function.

dbDataConnection

Connects the extension to a DBC_Database module.

dbError

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.

dbExecute

Executes an SQL statement against the Pipeline Manager database.

dbNextResult

Switches the cursor to the next result for the result handle you specify.

dbNextRow

Switches the cursor to the next row in the current result.

dbRollbackTransaction

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);
```

Parameter

conHandle

The connection you want to use for the new transaction.

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);
```

Parameter

conHandle

The connection you want to close.

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);
```

Parameter

resHandle

The result handle you want to close.

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);
```

Parameter

conHandle

The connection you want to use for the transaction.

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);
```

Parameter

dbcModule

The registry name for the DBC_Database module.

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(Long conHandle, String sqlStatement);
```

Parameters

conHandle

The connection you want to use.

sqlStatement

The SQL statement to execute.

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);
```

Parameter

resHandle

The result handle you want to process.

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, ...);
```

Parameters

resHandle

The handle for the result you want to process.

A list of bound variables

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);
```

Parameter

conHandle

The connection whose transaction you want rolled back.

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 7-4 contains data normalizing functions.

Table 7-4 Data Normalizing Functions

Function Description

convertCli

Normalizes wireline and wireless command-line interfaces (CLIs).

Static class function: "EXT_ConvertCli::convert"

convertIPv4

Static class function: "EXT_ConvertIPv4::convert"

String convertIPv6

Static class function: "EXT_ConvertIPv6::convert"

convertIPv4onv6

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

Syntax

```String convertIPv4( String ip );
```

Parameter

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

Syntax

```String convertIPv6(String ip;
```

Parameter

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

Syntax

```String convertIPv4onv6(String ip);
```

Parameter

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 7-5 contains date functions.

Table 7-5 Date Functions

Function Description

dateDiff

Calculates the difference between two dates.

dateIsValid

Checks a date for validity; for example, after initialization from a string.

dateToStr

Converts a date value to a string.

strToDate

Converts a string into a date value.

sysdate

Retrieves the current system date.

This function manipulates date and time values.

Syntax

```Date dateAdd(Date source [, Long years [, Long months [, days [, Long hours [, Long mins [, Long secs]]]]]]);
```

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(Date date1, Date date2);
```

Parameters

date1

The first date used for calculating the difference. This is the minuend.

date2

The second date used for calculating the difference. This is the subtrahend.

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);
```

Parameter

date

The date to validate.

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");
```

### sysdate

This function retrieves the current system date.

Syntax

```Date sysdate();
```

Parameters

None.

Return Values

Returns the current system date.

Example

```Date now;
now = sysdate();
```

## EDR Container Functions

Table 7-6 contains EDR container functions.

Table 7-6 EDR Container Functions

Function Description

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.

edrArrayIndex

Accesses the array index values in EDR container.

edrClearErrors

Clears the list of errors that the pipeline modules add to the EDR container.

edrConnectToken

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.

edrConnectTokenEx

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.

edrCurrentTokenIndex

Provides the index of the token parsed from the stream. Valid only in input grammar.

edrDate

Retrieves and sets date values in the current EDR container. This function is usually used to retrieve date values.

edrDateEx

Retrieves and sets date values in the current EDR container. This function is usually used to retrieve date values.

edrDecimal

Retrieves and sets decimal values in the current EDR container. This function is used usually to retrieve decimal values.

edrDecimalEx

Retrieves and sets decimal values in the current EDR container. This function is used usually to retrieve decimal values.

edrDelete

Deletes the current EDR container, changing the current pointer to the EDR container directly in front of the deleted EDR.

edrDeleteDatablock

Deletes a data block from the current EDR container. The function is not supported for nested transactions.

edrDeleteField

Clears the contents of a field in an EDR container. The function is not supported for nested transactions.

edrDuplicate

Duplicates the current EDR container.

edrEmptyInput

Sets the state of a field to EDR_INPUT_EMPTY when the field is present in the CDR but contains no value.

edrFieldConnectInfo

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.

edrFieldTokenBytePos

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.

edrGetError

Retrieves the names of the attached error messages.

edrGetErrorParameters

Retrieves the parameters associated to a specified error.

edrGetErrorSeverity

Retrieves the severity for each of the associated errors.

edrGetStream

Gets the output stream for an EDR.

edrHasError

Retrieves the names of the attached error messages.

edrInputState

Retrieves the input state of an EDR field.

edrInternalState

Returns the internal state of an EDR field.

edrInternalStateEx

Returns the internal state of an EDR field.

edrIsValidDetail

Determines whether the current EDR container is a valid detail container.

edrLong

Retrieves and sets Long values in the current EDR container. This function is usually used to retrieve Long values.

edrLongEx

Retrieves and sets Long values in the current EDR container. This function is usually used to retrieve Long values.

edrMaxSeverity

Finds the maximum severity of the errors added to the current EDR container.

edrMissingInput

Sets the state of a field to EDR_INPUT_MISSING when the field is not present in the CDR.

edrNumDatablocks

Determines the number of data blocks of the specified type.

edrNumDatablocksEx

Determines the number of data blocks of the specified type.

edrNumErrors

Accesses the number of error messages attached to the current EDR container.

edrNumTokens

Accesses the number of tokens attached to the current EDR container.

Removes additional output streams from an EDR.

edrSetContentType

Sets the content type of the current EDR container.

edrSetCurrent

Sets the current EDR container.

edrSetIsValidDetail

Sets the EDR container's valid detail flag. The valid detail flag specifies whether the EDR container is to be discarded.

edrSetStream

Sets the output stream for an EDR.

edrString

Retrieves and sets string values in the current EDR container. This function is usually used to retrieve string values.

edrStringEx

Retrieves and sets string values in the current EDR container. This function is usually used to retrieve string values.

edrTokenString

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.

iRulesModeOn

Enables the iRules mode.

iRulesModeOff

Disables the iRules mode.

pipelineName

Retrieves the name of the pipeline in which the script is running.

stopPipeline

Stops the pipeline from which it is called.

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);
```

Parameter

output_stream_name

The name of the new output stream that you are adding.

Return Values

Returns true if the function is successful. Returns false for all other conditions.

Example

```addoutmod.isc
------
function onDetailEdr
{
{
}
{
}
} // 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
{
{
}
}
}
}
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
}
}
}
}
```

Important:

To ensure output file integrity, specify a unique combination of OutputPath, OutputPrefix, and OutputSuffix values for each output stream defined in the registry.

This function adds a new data block to the current EDR container.

Syntax

```Bool edrAddDatablock(EdrField block [, Long idx1 [, Long idx2 ...]]);
```

Parameters

block

The name of the EDR block you want to add.

idxN

Additional index values specifying the path through the EDR tree structure.

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" );
}
```

This function adds a new data block to the current EDR container.

Syntax

```Bool edrAddDatablockEx(String block, Long indicesArray, Long numIndices);
```

Parameters

block

The name of the EDR block you want to add.

indicesArray

Array of additional index values specifying the path through the EDR tree structure.

numIndices

Number of indices.

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" );
}
```

This function adds a new error to the current EDR container.

Syntax

```Bool edrAddError(String error, Long severity [, String paramX...]);
```

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" )
{
( DETAIL.SERVICE_CODE ) );
}
```

### edrArrayIndex

This function accesses array index values in EDR container.

Syntax

```Long edrArrayIndex(EdrField block [, Long idx1 [, Long idx2 ...]]);
```

Parameters

block

The array block of the EDR container whose index you want to access.

idxN

Additional index values specifying the path through the EDR tree structure.

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.

Important:

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(EdrField field [, Long idx1 [, Long idx2 ...]], const String tokenName);
```

Parameters

field

The name of the EDR field you want to access.

idxN

Additional index values specifying the path through the EDR tree structure.

tokenName

The name of the token field to access (stream record field).

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(String field, Long indicesArray, Long numIndices, String tokenName);
```

Parameters

field

The name of the EDR field you want to access.

indicesArray

Array of additional index values specifying the path through the EDR tree structure.

numIndices

Number of indices.

tokenName

The name of the token field to access (stream record field).

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");
```

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);
```

Parameter

output_stream_name

The name of the output stream you want to confirm exists in the EDR.

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(EdrField field [, Long idx1 [, Long idx2 ... ]]);
```

Parameters

field

The name of the EDR field you want to access.

idxN

Additional index values specifying the path through the EDR tree structure.

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(String field, Long indicesArray, Long numIndices);
```

Parameters

field

The name of the EDR field you want to access.

indicesArray

Array of additional index values specifying the path through the EDR tree structure.

numIndices

Number of indices

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(EdrField field [, Long idx1 [, Long idx2 ...]]);
```

Parameters

field

The name of the EDR field you want to access.

idxN

Additional index values specifying the path through the EDR tree structure.

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(String field, Long indicesArray, Long numIndices);
```

Parameters

field

The name of the EDR field you want to access.

indicesArray

Array of additional index values specifying the path through the EDR tree structure.

level

Number of indices.

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(EdrField block, Long idx1 [, Long idx2 ...]);
```

Parameters

block

The name of the data block you want to delete.

idxN

Additional index values specifying the path through the EDR tree structure.

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(EdrField field, Long idx1 [, Long idx2 ...]);
```

Parameters

field

The name of the EDR field you want to delete.

idxN

Additional index values specifying the path through the EDR tree structure.

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(EdrField field, Long idx1 [, Long idx2 ... ]);
```

Parameters

field

The name of the empty EDR field.

idxN

Additional index values specifying the path through the EDR tree structure.

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(EdrField field [, Long idx1 [, Long idx2 ...]]);
```

Parameters

field

The name of the EDR field you want to access.

idxN

Additional index values specifying the path through the EDR tree structure.

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(EdrField field [, Long idx1 [, Long idx2 ...]]);
```

Parameters

field

The name of the EDR field you want to access.

idxN

Additional index values specifying the path through the EDR tree structure.

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" );
}
```

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);
```

Parameter

index_number

The array index of the output stream that you need the name of.

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);
```

Parameter

idx

The index of the error to be retrieved.

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(Long idx, Array params);
```

Parameters

idx

The index of the error that you want to retrieve, where 0 <= idx < edrNumErrors.

params

The string array where the parameters can be stored. This is a return parameter.

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);
```

Parameter

idx

The index of the error whose severity is being retrieved.

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);
```

Parameter

error

The name of the error to be retrieved.

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(EdrField field, Long idx1 [, Long idx2...]);
```

Parameters

field

The name of the EDR field for which to return the input state.

idxN

Additional index values specifying the path through the EDR tree structure.

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(EdrField field, Long idx1 [, Long idx2...]);
```

Parameters

field

The name of the EDR field for which to return the internal state.

idxN

Additional index values specifying the path through the EDR tree structure.

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(String field, Long indicesArray, Long numIndices);
```

Parameters

field

The name of the EDR field you want to access.

indicesArray

Array of additional index values specifying the path through the EDR tree structure.

numIndices

Number of indices.

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(EdrField field [, Long idx1 [, Long idx2 ...]]);
```

Parameters

field

The name of the EDR field you want to access.

idxN

Additional index values specifying the path through the EDR tree structure.

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(String field, Long indicesArray, Long numIndices);
```

Parameters

field

The name of the EDR field you want to access.

indicesArray

Array of additional index values specifying the path through the EDR tree structure.

numIndices

Number of indices.

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(EdrField field, Long idx1 [, Long idx2...]);
```

Parameters

field

The name of the missing EDR field.

idxN

Additional index values specifying the path through the EDR tree structure.

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(EdrField block [, Long idx1 [, Long idx2 ...]]);
```

Parameters

block

The name of the data block you want to access.

idxN

Additional index values specifying the path through the EDR tree structure.

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(String block, Long indicesArray, Long numIndices);
```

Parameters

block

The name of the data block you want to access.

indicesArray

Array of additional index values specifying the path through the EDR tree structure.

numIndices

Number of indices.

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" );
}
```

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);
```

Parameter

output_stream_name

The name of the output stream that you are removing from the EDR.

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

content

The content type to be assigned to the EDR container:

• EDR_UNKNOW_CONT

• 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

index

The index of the EDR container you want to set. This is the return value from edrDuplicate.

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);
```

Parameter

flag

The valid detail flag for the EDR container.

Return Values

Returns nothing.

Example

```if ( ... )
{
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);
```

Parameter

streamName

The name of the output stream for the EDR container.

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(EdrField field [, Long idx1 [, Long idx2 ...]]);
```

Parameters

field

The name of the EDR field you want to access.

indicesArray

Array of additional index values specifying the path through the EDR tree structure.

numIndices

Number of indices.

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(String field, Long indicesArray, Long numIndices);
```

Parameters

field

The name of the EDR field you want to access.

indicesArray

Array of additional index values specifying the path through the EDR tree structure.

numIndices

Number of indices.

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

idx

The index of the token whose index you want to retrieve, where 0 <= idx < edrNumTokens.

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.

Important:

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 7-7 contains file manipulation functions.

Table 7-7 File Manipulation Functions

Function Description

fileClose

Closes a file that was opened earlier using the fileOpen function.

fileCopy

Copies a file.

fileDelete

Deletes a file.

fileEof

Checks to see whether the end of file has been reached.

fileFlush

Flushes the contents of the file buffer to disk.

fileIsOpen

Determines whether a file is currently open.

fileOpen

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.

fileRename

Renames a file.

fileSeek

Sets the read/write pointer on a specific position (in bytes from the beginning of the file) in an opened file.

fileTell

Retrieves the position (measured in bytes from the start of the file) of the read/write pointer in an opened file.

fileWriteLong

Writes a Long value, as a string and not in binary mode, to the output file.

fileWriteStr

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);
```

Parameter

file

The file you want to close.

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(String old, String new);
```

Parameters

old

The file name of the file to be copied.

new

The file name of the copy.

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);
```

Parameter

file

The name of the file you want to delete.

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);
```

Parameter

file

The file you want to check.

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 )
{
}
```

### fileFlush

This function flushes the contents of the file buffer to disk.

Syntax

```Bool fileFlush(File file);
```

Parameter

file

The file you want to flush.

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);
```

Parameter

file

The name of file you want to check.

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(File file, String fileName, String openMode);
```

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" );
}
```

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(File file, String line, Long maxLen);
```

Parameters

file

The name of file you want to read.

line

The string that specifies the line to be read. This must be a left-hand value.

maxLen

The maximum length for the line.

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 )
{
}
```

### 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(String old, String new);
```

Parameters

old

The old file name.

new

The new file name.

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(File file, Long offset);
```

Parameters

file

The file in which you want to set a read/write pointer.

offset

The position where you want to set the read/write pointer.

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);
```

Parameter

file

The file to check.

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(File file, Long value [, Long len [, Bool leading [, String pad]]]);
```

Parameters

file

The file you want to write the Long value to.

value

The Long value to write.

len

The length of the output.

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(File file, String string);
```

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.

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 7-8 contains flist manipulation functions.

Table 7-8 Flist Manipulation Functions

Function Description

fListToString

Returns the content of the current flist in string format.

fListFromString

Replaces the current flist with an flist based on the input string.

fListCount

Counts the number of elements at the top level of the current flist.

fListCreateNew

Replaces the current flist with an empty flist.

fListDate

Retrieves the date value from the current flist.

fListDecimal

Retrieves the decimal value from the current flist.

fListDropElem

Removes an array from the current flist.

fListDropFld

Deletes a field from the current flist.

fListElemid

Retrieves the array element ID from the specified array field.

fListGetErrorText

Puts the field name from the flist into string1 and the error text into string2.

fListLong

Retrieves the long value from the current flist.

fListNumElem

Counts the number of elements in an array in the current flist.

fListPopElem

Resets the array to the previous value.

fListPushElem

Creates and sets the array element into which other functions set field values.

fListSetDate

Sets a date field in the current flist.

fListSetDecimal

Sets a decimal field in the current flist.

fListSetLong

Sets a long value within a PIN_FLDT_INT or PIN_FLDT_EMUN field in the current flist.

fListSetPoid

Sets a POID field in the current flist.

fListSetString

Sets a string field in the current flist.

fListString

Retrieves the string value from the current flist.

opcodeExecuteInternal

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);
```

Parameter

flist_str

The contents of the flist to be created, in string format.

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 String path_field [, Long elem_id]] [,const String path_field2 [, Long elem_id] ... , ] const String field);
```

Parameters

path_field

A substruct or array field that is part of the path to the target field. The parameter is repeated in the case of nested fields.

elem_id

The element ID of an array.

field

The name of the field from which the date is retrieved.

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 String path_field [, Long elem_id]] [,const String path_field2 [, Long elem_id] ... , ] const String field);
```

Parameters

path_field

A substruct or array field that is part of the path to the target field. The parameter is repeated in the case of nested fields.

elem_id

The element ID of an array.

field

The name of the field from which the decimal value is retrieved.

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 String array_field [,Long = 0 elem_id]);
```

Parameters

array_field

The name of the array.

elem_id

The array's element ID. The default is 0.

Return Values

Returns true on success and false on failure.

Example

```fListDropElem("PIN_FLD_ARGS", 2);
```

### fListDropFld

This function deletes a field from the current flist by calling PIN_FLIST_FLD_DROP.

Syntax

```Bool fListDropFld(const String field)
```

Parameter

field

The name of the field to be deleted.

Return Values

Returns true on success and false on failure.

Example

```fListDropFld("PIN_FLD_LABEL");
```

### 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(String string1, String string2);
```

Parameters

string1

String field into which the field name is placed.

string2

String field into which the error text is placed.

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 String path_field [, Long elem_id]] [,const String path_field2 [, Long elem_id] ... , ]const String field) ;
```

Parameters

path_field

A substruct or array field that is part of the path to the target field. The parameter is repeated in the case of nested fields.

elem_id

The element ID of an array.

field

The name of the field from which the long value is retrieved.

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 String path_field [, Long elem_id]] [,const String path_field2 [, Long elem_id] ... , ] const String array_field, Long elem_id);
```

Parameters

path_field

A substruct or array field that is part of the path to the target array. The parameter is repeated in the case of nested fields.

elem_id

The element ID of an array.

array_field

The name of the array.

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 String array_field [,Long = 0 element]);
```

Parameters

array_field

The name of the array to set.

element

The array's element ID. The default is 0.

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(const String field, Date value);
```

Parameters

field

The name of the date field to set.

value

The value to set for the field.

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 String field, Decimal value);
```

Parameters

field

The name of the decimal field to set.

value

The value to set for the field.

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 String field, Long value);
```

Parameters

field

The name of the long field to set.

value

The value to set for the field.

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(String field, String poid);
```

Parameters

field

The name of the POID field to set.

poid

The POID string to be set in the field.

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 String field, String value);
```

Parameters

field

The name of the string field to set.

value

The value to set for the field.

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 String path_field [, Long elem_id]] [,const String path_field2 [, Long elem_id] ... , ] const String field);
```

Parameters

path_field

A substruct or array field that is part of the path to the target field. The parameter is repeated in the case of nested fields.

elem_id

The element ID of an array.

field

The name of the field from which the string value is retrieved.

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(Long opcode, Long flags);
```

Parameters

opcode

The opcode number of the opcode to be executed.

flags

The opcode flag value. Flag values differ from opcode to opcode. Some opcodes do not expect a flag value. Use 0 for opcodes that do not expect a flag value.

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 7-9 contains hash and array functions.

Table 7-9 Hash and Array Functions

Function Description

arrayClear

Clears an array.

arraySize

Determines the size of an array.

hashClear

Clears a hash.

hashContains

Checks to determine whether a hash-array contains a specific value.

hashKeys

Retrieves all keys used in an associative array.

hashRemove

Removes an entry from an associative array.

### arrayClear

This function clears an array.

Syntax

```Void arrayClear(Array array);
```

Parameter

array

The array you want to clear.

Return Values

Returns nothing.

Example

```if ( arraySize( array ) > 0 )
{
// Cleanup the array
arrayClear( array );
}
```

### arraySize

This function determines the size of an array.

Syntax

```Long arraySize(Array array);
```

Parameter

array

The array whose size you want to determine.

Return Values

Returns the size of the array.

Example

```for ( i = 0; i < arraySize( array ); i = i + 1 )
{
logStdout( "array[" + longToStr(i) + "] = " + array[i] );
}
```

### hashClear

This function clears a hash.

Syntax

```Void hashClear(Hash hash);
```

Parameter

hash

The hash you want to clear.

Return Values

Returns nothing.

Example

```// Cleanup the hash
hashClear( hash );
```

### hashContains

This function checks to determine whether a hash-array contains a specific value.

Syntax

```Void hashContains(Hash hash, String key);
```

Parameters

hash

The hash you want to search.

key

The value you want to search for.

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(Hash hash, Array key);
```

Parameters

hash

The hash you want to search, looking for the key.

key

The string array as a return buffer for the keys.

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(Hash hash, String key);
```

Parameters

hash

The hash from which you want to remove the entry.

key

The entry to remove.

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 7-10 contains mapping functions.

Table 7-10 Mapping Functions

Function Description

longDecode

Maps Long values to other Long values.

strDecode

Maps string values to other string values.

### longDecode

This function maps Long values to other Long values.

Syntax

```Long longDecode(Long toMap, Long default [[, const Long src1, const Long dest1] ...]);
```

Parameters

toMap

The Long value to map.

default

The default return value if no valid mapping entry exists.

src1

The source value of the first mapping entry; this value must be a constant.

dest1

The destination value of the first mapping entry; this value must be a constant.

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_oldTrailer, C_newTrailer );
```

### strDecode

This function maps string values to other string values.

Syntax

```String strDecode(String toMap, String default [[, const String src1, const String dest1] ...]);
```

Parameters

toMap

The string value to map.

default

The default return value if no valid mapping entry exists.

src1

The source value of the first mapping entry; this value must be a constant.

dest1

The destination value of the first mapping entry; this value must be a constant.

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_oldTrailer, C_newTrailer );
```

## Opcode Calling Functions

Table 7-11 contains opcode calling functions.

Table 7-11 Opcode Calling Functions

Function Description

opcodeExecute

Calls the specified opcode.

opcodeGetConnection

Obtains a connection from the specified connection pool.

pcmOpCatch

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(Long opcode, Long flags);
```

Parameters

opcode

The opcode number of the opcode to be executed.

flags

The opcode flag value. Flag values differ from opcode to opcode. Some opcodes do not expect a flag value. Use 0 for opcodes that do not expect a flag value.

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);
```

Parameter

connectionPool

The full registry name of the connection pool used for the pipeline.

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. See "Base Opcodes" for possible opcodes.

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 ( | ).

in_flistp

A pointer to the input flist of the opcode being called. See the individual opcode flist reference pages for the input flist specifications.

ebufp

A pointer to the error buffer that stores any errors that occur during the operation.

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 7-12 contains Pipeline system functions.

Table 7-12 Pipeline System Functions

Function Description

formatName

Determines the name of the format the script is running in.

logFormat

Writes messages to the pipeline log

logPipeline

Writes messages to the pipeline log.

msgArg

Deprecated.

msgName

Deprecated.

msgNumArgs

Deprecated.

registryNodeName

Returns the name of the registry node in which the script (iScript or input/output grammar) is running.

regString

Retrieves values from the registry.

reqSend

Sends a request to a registered object and waits for an answer (i.e., synchronous messaging).

scriptUsable

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.

sendEvent

Sends an event to the event handler.

stopFormat

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() );
```

### logFormat

This function writes messages to the pipeline log.

Important:

This function is obsolete and should be replaced by the logPipeline function.

Syntax

```Void logFormat(String msg);
```

Parameter

msg

The message to write to the pipeline log.

Return Values

Returns nothing.

Example

```logFormat( "Hello World!" );
```

### logPipeline

This function writes messages to the pipeline log.

Syntax

```Void logPipeline(String msg [, Long severity]);
```

Parameters

msg

The message to write to the pipeline log.

severity

The severity of the message:

• 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:
```

### regString

This function retrieves values from the registry.

Syntax

```String regString(String name);
```

Parameter

name

The name of the registry entry.

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(String reqDestination, String reqName, Array inParams, Array outParams);
```

Parameters

reqDestination

The registry name of the request's destination.

reqName

The name of the request.

inParams

A string array containing the input parameter expected by the destination to be able to process the request.

outParams

A string array to contain the reply to the request.

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.

Important:

You can use this function only in the iScript modules and not in the input grammar.

Syntax

```Void scriptUsable(Bool usable);
```

Parameter

usable

The flag indicating whether the script is 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(String event [, String arg1 [, String arg2 ...]]);
```

Parameters

event

The name of the event to send.

argX

A comma-delimited number of argument strings used as parameters for the event.

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" );
};
```

### stopFormat

This function stops the format; for example, after critical errors.

Syntax

```Void stopFormat();
```

Parameters

None.

Return Values

Returns nothing.

Example

```if ( fileWriteString( out, data ) == false )
{
logFormat( "ERROR: fileWriteString() failed" );
stopFormat();
};
```

## 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

Syntax

```const BAS_String EXT_ConvertIPv4::convert( const BAS_String& ip );
```

Parameter

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

Syntax

```const BAS_String EXT_ConvertIPv6::convert( const BAS_String& ip );
```

Parameter

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

Syntax

```const BAS_String EXT_ConvertIPv4onv6::convert( const BAS_String& ip );
```

Parameter

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 7-13 contains standard functions.

Table 7-13 Standard Functions

Function Description

closeClientConnection

Closes the connection to the Diameter client

currentTimeInMillis

Gets the current system time in milliseconds.

getClientState

Gets the state of a Diameter client.

mutexAcquire

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.

mutexCreate

Creates a mutex that can later be accessed by its handle.

mutexDestroy

Used to destroy a mutex that is no longer needed.

mutexRelease

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.

sleep

Makes the process sleep.

startTimer

Starts the timer.

sysExecute

Executes a command line in a file.

sysGetEnv

Gets an environment variable.

### closeClientConnection

This function closes the connection to the Diameter client.

Syntax

Void closeClientConnection(Socket Num);

Parameter

Num

Socket Id of the Diameter client.

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);

Parameter

Num

Socket Id of the Diameter client.

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);
```

Parameter

handle

The handle of the mutex to acquire.

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);
```

Parameter

handle

The handle of the mutex to be destroyed.

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);
```

Parameter

handle

The handle of the mutex you want to release.

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)
```

### sleep

This function makes the process sleep.

Syntax

```Void sleep(Long seconds);
```

Parameter

seconds

The number of seconds you want the process to sleep.

Return Values

Returns nothing.

Example

```sleep (10)
```

### startTimer

This function starts the timer.

Syntax

Void startTimer(Socket Num);

Parameter

Num

Socket Id of the Diameter client.

Return Values

Returns nothing.

Example

startTimer(edrLong(DETAIL.ASS_PROTOCOL_INFO.ASS_DIAMETER_INFO.SOCKETID,0,0));

### 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
}
}
}

```

See "Event Handler" in BRM Configuring Pipeline Rating and Discounting.

Syntax

```Long sysExecute(String commandLine [String returnBuffer, Long timeToWait]);
```

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);
```

Parameter

envVariable

The name of the environment variable you want returned.

Return Values

Returns the specified environment variable and its settings.

Example

```logStdout("*******************-\n");
logStdout( "PATH=" + sysGetEnv( "PATH") +"\n");directory \n");
```

## String Functions

Table 7-14 contains string functions.

Table 7-14 String Functions

Function Description

decimalToStr

Converts a decimal value into a string.

decimalToStrHex

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.

longToHexStr

Converts a Long value into a hexadecimal string.

longToStr

Converts a Long value into a string.

strByteValue

Converts the first character in the input string to its byte value.

strDecode

Maps string values to other string values.

strEndsWith

Checks to see if a string ends with a special suffix.

strHexStrToStr

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.

strHexToDecimal

Converts a hexadecimal string to a decimal value.

strHexToLong

Converts a hexadecimal string into a Long value.

strLength

Determines the length of a string.

strMatch

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.

strReplace

Replaces substrings in a string.

strSearch

Searches for a substring inside another string.

strSearchRegExpr

Searches for a regular expression to a string.

strSplit

Splits a string according to a specific separator character and stores the resulting tokens in a string array.

strStartsWith

Checks to see if a string starts with a specified prefix.

strStrip

Removes special leading or trailing characters from a string.

strStrToHexStr

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.

strSubstr

Extracts a substring from a string.

strToDate

Converts a string into a date value.

strToDecimal

Converts string values to decimal values.

strToLong

Converts a string value to a Long value.

strToLower

Converts a string to lowercase characters.

strToUpper

Converts a string to uppercase characters.

### decimalToStr

This function converts a decimal value into a string.

Syntax

```String decimalToStr(Decimal value [, Long precision]);
```

Parameters

value

The value to convert into a string.

precision

The number of digits after the decimal point.

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(Decimal value [, String separator [, Long precision]]);
```

Parameters

value

The decimal value to convert into a hexadecimal string. Code this in readable ASCII.

separator

The character you want to use as a decimal separator (the default is .).

precision

The precision of the decimal value to use when generating the hexadecimal string (the default is 0).

Return Values

Returns the decimal value as a hexadecimal string.

Example

```logFormat( "X = " + decimalToStr(x) + "(" + decimalToStrHex(x) + \
```

### longToHexStr

This function converts a Long value into a hexadecimal string.

Syntax

```String longToHexStr(Long value);
```

Parameter

value

The Long value to convert into a hexadecimal string.

Return Values

Returns the value as a hexadecimal string.

Example

```logFormat( "X = " + longToStr(x) + "(" + longToHexStr(x) + \
```

### longToStr

This function converts a Long value into a string.

Syntax

```String longToStr(Long value);
```

Parameter

value

The Long value to convert into a string.

Return Values

Returns the value as a string.

Example

```logFormat( "X = " + longToStr(x) );
```

### strByteValue

This function converts the first character in the input string to its byte value.

Syntax

```Long strByteValue(String string);
```

Parameter

string

The string whose first character you want to convert.

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(String toMap, String default [[, const String src1, const String dest1] ...]);
```

Parameters

toMap

The string value to map.

default

The default return value if no valid mapping entry exists.

src1

The source value of the first mapping entry; this value must be a constant.

dest1

The destination value of the first mapping entry; this value must be a constant.

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_oldTrailer, C_newTrailer );
```

### strEndsWith

This function checks to see if a string ends with a special suffix.

Syntax

```Bool strEndsWith(String string, String suffix);
```

Parameters

string

The string to check the suffix for.

suffix

The suffix to check.

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

source

The hexadecimal string to convert to ASCII:

• 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(String string [, String separator [, Long precision]]);
```

Parameters

string

The hexadecimal string (coded in readable ASCII) to convert into a decimal value.

separator

The character you want to use as decimal separator (the default is .).

precision

The precision of the decimal value to be generated (the default is 0).

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);
```

Parameter

string

The hexadecimal string to convert into a Long value.

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);
```

Parameter

string

The string whose length you want to determine.

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(String string, String regExp [, Long index]);
```

Parameters

string

The string that you want to search for the regular expression.

regExp

The regular expression to match against the string.

index

The starting index for the search; the beginning of the string has an index of 0 (the default is 0).

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" );
}
```

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(String string, String padChar, Long length, Bool isLeftJustified);
```

Parameters

string

The string to pad (or truncate) to a specified length.

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(String toReplace, Long pos, Long len, String replace);
```

Parameters

toReplace

The string in which you want the substring replaced.

Important:

The input string in toReplace is not changed.
pos

The start position of the substring to replace. Positions start with 0.

len

The length of the substring to replace.

replace

The replacement string.

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(String string, String search [, Long index]);
```

Parameters

string

The string that you want to search.

search

The string that you want to search for.

index

The starting index for the search; the beginning of the string has an index of 0 (the default is 0).

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(String string, const String regExp [, Long index]);
```

Parameters

string

The string that you want to search.

regExp

The regular expression to look for in the string.

Important:

The strSearchRegExpr function does not support braces ({ }); for example, A{1,3}.
index

The starting index for the search; the beginning of the string has an index of 0 (the default is 0).

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(Array res, String string, String sep);
```

Parameters

res

The resulting array to fill.

string

The input string to split.

sep

The separator to use for splitting. If the separator you specify is longer than one character, the function uses only the first character.

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(String string, String prefix);
```

Parameters

string

The string in which to check for the specified prefix.

prefix

The specified prefix being checked for in the string.

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(String string [, Long stripMode [, String stripChar]]);
```

Parameters

string

The string from which you want to remove leading or trailing characters.

stripMode

The strip mode:

• STRIP_TRAILING

• STRIP_BOTH

stripChar

The character to be removed, which is the first or last character of the string (the default is the space character).

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

source

The ASCII string to convert to hexadecimal. It cannot be empty. Embedded nulls are permitted and handled correctly.

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(String string, Long pos, Long len);
```

Parameters

string

The string from which you want to extract the substring.

pos

The start position of the substring to extract. Positions start with 0.

len

The length of the substring to extract.

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);
```

Parameter

string

The string to convert to a decimal value.

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);
```

Parameter

string

The string to convert to a Long value.

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);
```

Parameter

string

The string to convert to lowercase characters.

Return Values

Returns the string converted to lowercase characters if the function is successful.

Example

```if ( strToLower( "HELLO" ) == "hello" )
{
...
}
```

### strToUpper

This function converts a string to uppercase characters.

Syntax

```String strToUpper(String string);
```

Parameter

string

The string to convert to uppercase characters.

Return Values

Returns the string converted to uppercase characters if the function is successful.

Example

```if ( strToUpper( "Hello" ) == "HELLO" )
{
...
}
```

## Transaction Management Functions

Table 7-15 contains transaction management functions.

Table 7-15 Transaction Management Functions

Function Description

edrDemandCancel

Sends a request to the Transaction Manager to cancel the current transaction.

edrDemandRollback

Sends a request to the Transaction Manager to roll back the current transaction.

edrRollbackReason

Allows the iScript module to request the reason for the rollback in the onRollback function.

tamItemType

Returns the type of an item in the currently processed transaction.

tamNumTransItems

Returns the number of items processed in the currently processed transaction.

tamStreamExtension

Used to access the extension value of each item in the current transaction.

tamStreamName

Used to access the stream name of each item in the current transaction.

tamTransId

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]);
```

Parameter

rollbackReason

The reason for the rollback.

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);
```

Parameter

idx

The index of the transaction item you want to access.

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);
```

Parameter

idx

The index of the transaction item you want to access.

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);
```

Parameter

idx

The index of the transaction item you want to access.

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();
...
}
```