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.
Table 7-1 contains the arithmetic functions.
Table 7-1 Arithmetic Functions
Function | Description |
---|---|
Derives an absolute value from a decimal value. |
|
Converts the integer portion of a decimal value to a Long value. |
|
Derives an absolute value from a Long value. |
|
Converts a Long value to a decimal value. |
|
Rounds a decimal value to a specified number of decimal places. |
|
Calculates the square root of the input value. |
|
Truncates a decimal value to a specified number of decimal places. |
This function rounds a decimal value to a specified number of decimal places.
The value to round.
The number of decimal places to achieve when rounding, also known as the number of significant digits (the default is 0).
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.
Table 7-2 contains the ASN.1 functions.
Function | Description |
---|---|
Adds an integer object to the current active node of the ASN tree. |
|
Adds a string object to the current active node of the ASN tree. |
|
Creates a tree in memory to hold an ASN.1 file structure. |
|
Deletes the last created or used ASN.1 tree. |
|
Deletes a node from the ASN.1 tree. |
|
Flushes the content of the ASN.1 tree to the output. |
|
Gets the active (working) node from a list of created and store |
|
Backs up one level in the ASN.1 tree hierarchy. |
|
Adds a new block to the current active node of the ASN.1 tree and sets this new block as an active node of the tree. |
|
Stores an index to a constructed block node in the ASN.1 tree, when the block position in the tree is fixed. |
This function adds an integer object to the current active node of the ASN.1 tree.
The name of the block to add (exact type from the block description file).
The integer to insert as the value.
This function adds a string object to the current active node of the ASN.1 tree.
The name of the block to add. This must exactly match the type from the block description file.
The string to insert as the value.
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.
This function deletes a node from the ASN.1 tree, by recursively deleting all contained blocks and values.
This function gets the active (working) node from a list of created and stored, but not filled, constructed blocks.
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.
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.
The name of the structured block to add (exact type from the block description file).
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.
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.
Returns a node index that can be used with asnTreeGetStoredNode(nodeIdx) or asnTreeDeleteNodeByIndex(nodeIdx).
... asnTreePushTag("TAP3.NetworkInfo"); Long networkInfoIdx = asnTreeStoreNode(); //Nothing to do now, node will be updated after all //details are processed asnTreePop(); //for asnTreePushTag("TAP3.NetworkInfo"); ...
The following example iScript demonstrates how to create an output file in ASN.1 containing only a list of QoS requested objects (one per event data record (EDR)), with all field values set to 3.
This is the content of the OutGrammar.dsc file. There should be an associated file describing the block structure that is here used, for example, TAP3.QoSRequestedList.
// The initial iScript code iScript { use EXT_AsnTree; // iScript extension to build a Tree of ASN.1 object // used to fill the Length value of the ASN.1 bloc, // before printing on output stream } // The definition of the grammar Grammar { edr_stream: header details trailer ; header: HEADER { asnTreeCreate(); asnTreePushTag("TAP3.QoSRequestedList"); } ; trailer: TRAILER { asnTreePop(); //for asnTreePushTag("TAP3.QoSRequestedList"); asnTreeFlush(); asnTreeDelete(); } ; details: details DETAIL { asnTreePushTag("TAP3.QoSRequested"); asnTreeAddInteger("TAP3.QoSDelay.QOS_DELAY", 3); asnTreeAddInteger("TAP3.QoSMeanThroughput.QOS_MEAN_THROUGHPUT", 3); asnTreeAddInteger("TAP3.QoSPeakThroughput.QOS_PEAK_THROUGHPUT", 3); asnTreeAddInteger("TAP3.QoSPrecedence.QOS_PRECEDENCE", 3); asnTreeAddInteger("TAP3.QoSReliability.QOS_RELIABILITY", 3); asnTreePop(); //for asnTreePushTag("TAP3.QoSRequested"); } | /*EMPTY*/ ; }
Table 7-3 contains database connection functions.
Table 7-3 Database Connection Functions
Function | Description |
---|---|
Starts a new transaction using the specified connection. |
|
Closes a connection to the Pipeline Manager database. |
|
Closes a result handle after processing the result data. |
|
Commits a transaction to a specific connection. |
|
Establishes a connection to the Pipeline Manager database. The handle returned by this function should be used in future calls to the dbExecute function. |
|
Connects the extension to a DBC_Database module. |
|
Retrieves a description for the last error. This description is not reset after a valid call to one of the other database connection functions. Therefore, dbError should only be called directly after one of the other database connection functions fails. |
|
Executes an SQL statement against the Pipeline Manager database. |
|
Switches the cursor to the next result for the result handle you specify. |
|
Switches the cursor to the next row in the current result. |
|
Rolls the current transaction back for the specified connection. |
This function starts a new transaction using the specified connection.
Returns true if the transaction was successfully started. Returns false if the function fails.
This function closes a connection to the Pipeline Manager database.
Returns true if the connection was successfully closed. Returns false if the function fails.
This function closes a result handle after processing the result data.
Returns true if the result handle was successfully closed. Returns false if the function fails.
This function commits a transaction to a specific connection.
Returns true if the transaction was successfully committed to the connection. Returns false if the function fails.
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.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.
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.Returns true if the extension was successfully connected to the module. Returns false if the function fails.
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.
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.
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.
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.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.
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.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.
Table 7-4 contains data normalizing functions.
Table 7-4 Data Normalizing Functions
Function | Description |
---|---|
Normalizes wireline and wireless command-line interfaces (CLIs). Static class function: "EXT_ConvertCli::convert" |
|
Normalizes IPv4 addresses. Static class function: "EXT_ConvertIPv4::convert" |
|
Normalizes IPv6 addresses. Static class function: "EXT_ConvertIPv6::convert" |
|
Normalizes IPv4 over IPv6 addresses. Static class function: "EXT_ConvertIPv4onv6::convert" |
This function normalizes wireless and wireline CLIs into international format.
String convertCli( String cli, String modInd, Long typeOfNumber, String natAccessCode, StringArray intAccessCode, StringArray countryCode, String intAccessCodeSign, String natDestinCode )
CLI to normalize.
Modification Indicator, for example, "00".
Type Of Number, for example, 0.
National Access Code, for example, "0".
International Access Code, for example, "00".
Country Code, for example, "49".
International Access Code Sign, for example, "+".
National Destination Code, for example, "172".
This function normalizes IPv4 addresses.
Returns an IP address in normalized format.
Dots (.) are skipped. Tokens are left-padded to 3 digits with zeroes.
This function normalizes IPv6 addresses.
Returns an IP address in normalized format.
Dots (.) are skipped. Tokens are left-padded to 4 digits with zeroes.
Table 7-5 contains date functions.
Function | Description |
---|---|
Adds date and time values. |
|
Calculates the difference between two dates. |
|
Checks a date for validity; for example, after initialization from a string. |
|
Converts a date value to a string. |
|
Converts a string into a date value. |
|
Retrieves the current system date. |
This function manipulates date and time values.
Date dateAdd(Date source [, Long years [, Long months [, days [, Long hours [, Long mins [, Long secs]]]]]]);
The source date for the addition.
The number of years to add. This parameter can be positive or negative.
The number of months to add. This parameter can be positive or negative.
The number of days to add. This parameter can be positive or negative.
The number of hours to add. This parameter can be positive or negative.
The number of minutes to add. This parameter can be positive or negative.
The number of seconds to add. This parameter can be positive or negative.
Returns the manipulated source date.
Note:
The variable source itself is not manipulated; only the result is returned.This function calculates the difference between two dates. The difference is returned in seconds.
The first date used for calculating the difference. This is the minuend.
The second date used for calculating the difference. This is the subtrahend.
This function checks a date for validity; for example, after initialization from a string.
This function converts a date value to a string.
The abbreviated week day name; for example, Sun for Sunday. This is from tm::tm_wday.
The full weekday name; for example, Sunday. This is from tm::tm_wday.
The abbreviated month name; for example, Feb for February.
The full month name; for example, February.
The date and time; for example, Feb 29 14:34:56 2004. This may use all members.
The day of the month; for example, 29.
The hour of the 24-hour day; for example, 14.
The hour of the 12-hour day; for example, 02.
The day of the year starting from 001; for example, 060. This is from tm::tm_yday.
The month of the year, from 01; for example, 02.
The minutes after the hour; for example, 34.
The AM/PM indicator, if any; for example, AM.
The seconds after the minute; for example, 56.
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.
The day of the week, with 0 for Sunday; for example, 2 for Tuesday.
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.
The date; for example, Feb 29 2004. This uses tm::tm_yday in some locales.
The time; for example, 14:34:56.
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.
The year including the century; for example, 1994.
The time zone name; for example, PST or PDT. This is from tm::tm_isdst.
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.
This function converts a string into a date value. The only supported string format is YYYYMMDDHHMMSS.
The literal % character.
The day of the month; for example, 29. The range is 00-31.
The hour of the 24-hour day; for example, 14. The range is 00-23.
The month of the year, from 01; for example, 02. The range is 01-12.
The minutes after the hour; for example, 34. The range is 00-59.
The seconds after the minute; for example, 56. The range is 00-59.
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.
The year including the century; for example, 1994.
Returns a valid date if the input string is in the right format. Returns an invalid date if the format is not correct.
Table 7-6 contains EDR container functions.
Table 7-6 EDR Container Functions
Function | Description |
---|---|
Adds additional output streams to each EDR. |
|
Adds a new data block to the current EDR container. |
|
Adds a new data block to the current EDR container. |
|
Adds a new error to the current EDR container. |
|
Accesses the array index values in EDR container. |
|
Clears the list of errors that the pipeline modules add to the EDR container. |
|
Associates an EDR field with an input token and is identical to calling a block mapping with edrInputMap, except that it is accomplished using only one field. This function calls the edrMissingInput and edrEmptyInput state-setting functions, which indicate the reason for missing fields. |
|
Associates an EDR field with an input token and is identical to calling a block mapping with edrInputMap, except that it is accomplished using only one field. This function calls the edrMissingInput and edrEmptyInput state-setting functions, which indicate the reason for missing fields. |
|
Determines whether an EDR has an additional output stream with the name you pass in. |
|
Provides the index of the token parsed from the stream. Valid only in input grammar. |
|
Retrieves and sets date values in the current EDR container. This function is usually used to retrieve date values. |
|
Retrieves and sets date values in the current EDR container. This function is usually used to retrieve date values. |
|
Retrieves and sets decimal values in the current EDR container. This function is used usually to retrieve decimal values. |
|
Retrieves and sets decimal values in the current EDR container. This function is used usually to retrieve decimal values. |
|
Deletes the current EDR container, changing the current pointer to the EDR container directly in front of the deleted EDR. |
|
Deletes a data block from the current EDR container. The function is not supported for nested transactions. |
|
Clears the contents of a field in an EDR container. The function is not supported for nested transactions. |
|
Duplicates the current EDR container. |
|
Sets the state of a field to EDR_INPUT_EMPTY when the field is present in the CDR but contains no value. |
|
Retrieves the Info string associated with the token for the corresponding EDR field. By default, the Info string contains the description of the token type. The function works only when the EDR field is associated with a token through either the edrInputMap or edrConnectToken function. |
|
Calculates the position of the token associated with the corresponding EDR field. The function works only when the EDR field is associated with a token through either the edrInputMap or edrConnectToken function. |
|
Gets the name of an additional EDR output stream given an array index number. |
|
Retrieves the names of the attached error messages. |
|
Retrieves the parameters associated to a specified error. |
|
Retrieves the severity for each of the associated errors. |
|
Gets the output stream for an EDR. |
|
Retrieves the names of the attached error messages. |
|
Retrieves the input state of an EDR field. |
|
Returns the internal state of an EDR field. |
|
Returns the internal state of an EDR field. |
|
Determines whether the current EDR container is a valid detail container. |
|
Retrieves and sets Long values in the current EDR container. This function is usually used to retrieve Long values. |
|
Retrieves and sets Long values in the current EDR container. This function is usually used to retrieve Long values. |
|
Finds the maximum severity of the errors added to the current EDR container. |
|
Sets the state of a field to EDR_INPUT_MISSING when the field is not present in the CDR. |
|
Determines the number of data blocks of the specified type. |
|
Determines the number of data blocks of the specified type. |
|
Accesses the number of error messages attached to the current EDR container. |
|
Accesses the number of tokens attached to the current EDR container. |
|
Removes additional output streams from an EDR. |
|
Sets the content type of the current EDR container. |
|
Sets the current EDR container. |
|
Sets the EDR container's valid detail flag. The valid detail flag specifies whether the EDR container is to be discarded. |
|
Sets the output stream for an EDR. |
|
Retrieves and sets string values in the current EDR container. This function is usually used to retrieve string values. |
|
Retrieves and sets string values in the current EDR container. This function is usually used to retrieve string values. |
|
Used to retrieve the content of each token, as identified by their indexes. When the index is not available, as for a function call with no argument, this function returns the complete byte string attached to the EDR. The byte string corresponds to the original input string that generated the EDR. The function works only when the EDR field is associated with a token through either the edrInputMap or edrConnectToken function. |
|
Enables the iRules mode. |
|
Disables the iRules mode. |
|
Retrieves the name of the pipeline in which the script is running. |
|
Stops the pipeline from which it is called. |
This function adds additional output streams to each EDR.
Each Out_GenericStream pipeline module has a default output stream for EDRs. You use this function to add additional output streams to direct the output to additional locations.
Output stream characteristics (output path, record prefix, and record suffix) are set in the registry file.
If the stream name sent in with this function already exists, edrAddAdditionalStream returns true but does not create the stream again.
This iScript example adds two additional output module streams:
addoutmod.isc ------ function onDetailEdr { if (edrAddAdditionalStream( "TElOut1" ) == true) { logStdout("Stream TelOut1 added "); } if (edrAddAdditionalStream( "TELOut2" ) == true) { logStdout("Stream TElOut2 added "); } } // end onDetailEdr + end iScript ----
This registry fragment shows the two example iScript files, addoutmod.isc and removeoutmod.isc, defined in the FunctionPool section. These iScripts add and remove output module streams. The new iScripts are shown in bold.
FunctionPool { Iscript { ModuleName = FCT_IScript Module { Active = True Source = FILE Scripts { addoutmod { FileName = ./samples/simple/addoutmod.isc } } } } Iscript2 { ModuleName = FCT_IScript Module { Active = True Source = FILE Scripts { removeoutmod { FileName = ./samples/simple/removeoutmod.isc } } } }
This output registry section defines the TELOut1 output section:
TELOut1 { ModuleName = OUT_GenericStream Module { Grammar = ./formatDesc/Formats/Solution42/SOL42_V430_OutGrammar.dsc DeleteEmptyStream = TRUE OutputStream { ModuleName = EXT_OutFileManager Module { OutputPath = ./samples/simple/data/out2 OutputPrefix = Sol42_ OutputSuffix = .out TempPrefix = tmp TempDataPath = ./samples/simple/data/out2 TempDataPrefix = out.tmp. TempDataSuffix = .data Replace = TRUE } } } }
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.
The name of the EDR block you want to add.
Additional index values specifying the path through the EDR tree structure.
This function adds a new data block to the current EDR container.
The name of the EDR block you want to add.
Array of additional index values specifying the path through the EDR tree structure.
Number of indices.
This function adds a new error to the current EDR container.
The name of the error you want to add to the EDR container.
The severity of the error:
0 = Debug
1 = Normal
2 = Warning
3 = Minor error
4 = Major error
5 = Critical error
This function accesses array index values in EDR container.
The array block of the EDR container whose index you want to access.
Additional index values specifying the path through the EDR tree structure.
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.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"); } }
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.
Bool edrConnectToken(EdrField field [, Long idx1 [, Long idx2 ...]], const String tokenName);
The name of the EDR field you want to access.
Additional index values specifying the path through the EDR tree structure.
The name of the token field to access (stream record field).
Returns true if the EDR field is successfully associated with the input token. Returns false if the function fails.
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.
The name of the EDR field you want to access.
Array of additional index values specifying the path through the EDR tree structure.
Number of indices.
The name of the token field to access (stream record field).
Returns true if the EDR field is successfully associated with the input token. Returns false if the function fails.
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.
This function returns the index of the token parsed from the stream. It is valid only in input grammar.
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.
The name of the EDR field you want to access.
Additional index values specifying the path through the EDR tree structure.
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.
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.
The name of the EDR field you want to access.
Array of additional index values specifying the path through the EDR tree structure.
Number of indices
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.
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.
The name of the EDR field you want to access.
Additional index values specifying the path through the EDR tree structure.
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).
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.
The name of the EDR field you want to access.
Array of additional index values specifying the path through the EDR tree structure.
Number of indices.
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).
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;
This function deletes the current EDR container, changing the current pointer to the EDR container directly in front of the deleted EDR.
Returns true if the current EDR container is deleted successfully. Returns false if there was no current EDR container.
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).
The name of the data block you want to delete.
Additional index values specifying the path through the EDR tree structure.
Returns true if the data block is successfully deleted. Returns false if the operation fails.
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).
The name of the EDR field you want to delete.
Additional index values specifying the path through the EDR tree structure.
Returns true if the EDR field content is successfully deleted. Returns false if the operation fails.
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.
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.
This function sets the state of a field to EDR_INPUT_EMPTY when the field is present in the CDR but contains no value.
The name of the empty EDR field.
Additional index values specifying the path through the EDR tree structure.
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.
The name of the EDR field you want to access.
Additional index values specifying the path through the EDR tree structure.
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.
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.
The name of the EDR field you want to access.
Additional index values specifying the path through the EDR tree structure.
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.
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.
Returns the name of the stream if the function is successful. Returns an empty string for all other conditions.
This function retrieves the names of the attached error messages.
Returns the name of the attached error if the function is successful. Returns an empty string if the function fails.
This function retrieves the parameters associated to a specified error.
The index of the error that you want to retrieve, where 0 <= idx < edrNumErrors.
The string array where the parameters can be stored. This is a return parameter.
Returns the number of parameters in the array. Returns 0 if this function fails or if there are no parameters in the array.
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" ); } } }
This function retrieves the severity for each of the associated errors.
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.
This function retrieves the names of the attached error messages.
Returns the name of the attached error if the function is successful. Returns an empty string if the function fails.
This function retrieves the input state of an EDR field.
The name of the EDR field for which to return the input state.
Additional index values specifying the path through the EDR tree structure.
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.
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; }
This function returns the internal state of an EDR field.
The name of the EDR field for which to return the internal state.
Additional index values specifying the path through the EDR tree structure.
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.
This function returns the internal state of an EDR field.
The name of the EDR field you want to access.
Array of additional index values specifying the path through the EDR tree structure.
Number of indices.
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.
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.
Returns true if the current EDR container is a valid detail container. Returns false if it is not a valid detail container.
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.
The name of the EDR field you want to access.
Additional index values specifying the path through the EDR tree structure.
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.
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.
The name of the EDR field you want to access.
Array of additional index values specifying the path through the EDR tree structure.
Number of indices.
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.
This function finds the maximum severity of the errors added to the current EDR container.
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.
This function sets the state of a field to EDR_INPUT_MISSING when the field is not present in the CDR.
The name of the missing EDR field.
Additional index values specifying the path through the EDR tree structure.
This function determines the number of data blocks of the specified type.
The name of the data block you want to access.
Additional index values specifying the path through the EDR tree structure.
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.
This function determines the number of data blocks of the specified type.
The name of the data block you want to access.
Array of additional index values specifying the path through the EDR tree structure.
Number of indices.
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.
This function accesses the number of error messages attached to the current EDR container.
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.
This function accesses the number of tokens attached to the current EDR container.
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.
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.Returns true if the function is successful or if the named stream does not exist. Returns false for all other conditions.
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
This function sets the content type of the current EDR container.
The content type to be assigned to the EDR container:
EDR_UNKNOW_CONT
EDR_HEADER
EDR_DETAIL
EDR_TRAILER
EDR_START
EDR_STOP
EDR_BEGIN
EDR_END
EDR_BEGIN_TRANSACTION
EDR_END_TRANSACTION
Returns true if the content type is valid. Returns false if the container type is not valid.
This function sets the current EDR container. All EDR container functions only access the current EDR container.
The index of the EDR container you want to set. This is the return value from edrDuplicate.
Returns true if there is an EDR container with the specified index. Returns false if there is no EDR container with that index.
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" ); } }
This function sets the EDR container's valid detail flag. The valid detail flag specifies whether the EDR container is to be discarded.
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.Returns true if the output stream is successfully set. Returns false if the output stream does not exist.
// 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 ); }
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.
The name of the EDR field you want to access.
Array of additional index values specifying the path through the EDR tree structure.
Number of indices.
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.
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.
The name of the EDR field you want to access.
Array of additional index values specifying the path through the EDR tree structure.
Number of indices.
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.
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.
The index of the token whose index you want to retrieve, where 0 <= idx < edrNumTokens.
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.
This function enables the iRules mode. In the iRules mode, the init section does not consider the specified indices for an EDR field.
This function disables the iRules mode. Disabling iRules mode ensures that the INIT takes the specified indices.
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.Table 7-7 contains file manipulation functions.
Table 7-7 File Manipulation Functions
Function | Description |
---|---|
Closes a file that was opened earlier using the fileOpen function. |
|
Copies a file. |
|
Deletes a file. |
|
Checks to see whether the end of file has been reached. |
|
Flushes the contents of the file buffer to disk. |
|
Determines whether a file is currently open. |
|
Opens a file for reading or writing. If the file is already open, the old file will be closed and the new file will be opened. The open mode is equivalent to the fopen C function. |
|
Reads a line from the input file. The line is read until the function encounters an end-of-line or end-of-file character or until maxLen is reached. |
|
Renames a file. |
|
Sets the read/write pointer on a specific position (in bytes from the beginning of the file) in an opened file. |
|
Retrieves the position (measured in bytes from the start of the file) of the read/write pointer in an opened file. |
|
Writes a Long value, as a string and not in binary mode, to the output file. |
|
Writes a string to the output file. |
This function deletes a file.
Returns true if the file was successfully deleted. Returns false if the function failed.
This function checks to see whether the end of file has been reached.
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.
This function flushes the contents of the file buffer to disk.
Returns true if the file was successfully flushed. Returns false if the function failed.
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.
The file you want to open.
The name of the file you want to open.
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.
Returns true if the file was opened successfully. Returns false if the function 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.
The name of file you want to read.
The string that specifies the line to be read. This must be a left-hand value.
The maximum length for the line.
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.
Returns true if the file is successfully renamed. Returns false if the function failed.
This function sets the read/write pointer on a specific position (in bytes from the beginning of the file) in an opened file.
The file in which you want to set a read/write pointer.
The position where you want to set the read/write pointer.
Returns true when setting the read/write pointer in an opened file is successful. Returns false when it has not been successful.
This function retrieves the position (measured in bytes from the start of the file) of the read/write pointer in an opened file.
Returns the position of the read/write pointer when successful. Returns (-1) when an error occurs.
This function writes a Long value to the output file. The Long value is written as a string and not in binary mode.
The file you want to write the Long value to.
The Long value to write.
The length of the output.
Specifies whether to add leading or trailing characters: true adds leading characters, false adds trailing characters.
The padding character to use as the first character of the string.
Returns true if the Long value is successfully written. Returns false if the function failed.
This function writes a string to the output file. The string is not automatically terminated by an end-of-line character.
The file you want to write the string to.
The string to write.
The length of the output. This parameter is optional.
Specifies whether to add leading or trailing characters: true adds leading characters, false adds trailing characters.
The padding character to use as the first character of the string.
Returns true if the string is successfully written. Returns false if the function failed.
Table 7-8 contains flist manipulation functions.
Table 7-8 Flist Manipulation Functions
Function | Description |
---|---|
Returns the content of the current flist in string format. |
|
Replaces the current flist with an flist based on the input string. |
|
Counts the number of elements at the top level of the current flist. |
|
Replaces the current flist with an empty flist. |
|
Retrieves the date value from the current flist. |
|
Retrieves the decimal value from the current flist. |
|
Removes an array from the current flist. |
|
Deletes a field from the current flist. |
|
Retrieves the array element ID from the specified array field. |
|
Puts the field name from the flist into string1 and the error text into string2. |
|
Retrieves the long value from the current flist. |
|
Counts the number of elements in an array in the current flist. |
|
Resets the array to the previous value. |
|
Creates and sets the array element into which other functions set field values. |
|
Sets a date field in the current flist. |
|
Sets a decimal field in the current flist. |
|
Sets a long value within a PIN_FLDT_INT or PIN_FLDT_EMUN field in the current flist. |
|
Sets a POID field in the current flist. |
|
Sets a string field in the current flist. |
|
Retrieves the string value from the current flist. |
|
Calls the opcode specified in the parameter. |
This function returns the content of the current flist in string format. The function calls "PIN_FLIST_TO_STR".
Returns the content of the current flist in string format. Returns an empty string on failure.
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.
This function counts the number of elements at the top level of the current flist by calling PIN_FLIST_COUNT.
Returns the number of elements at the top level of the current flist. Returns -1 on failure.
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.
Date fListDate([const String path_field [, Long elem_id]] [,const String path_field2 [, Long elem_id] ... , ] const String 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.
The element ID of an array.
The name of the field from which the date is retrieved.
Returns the date value from the specified PIN_FLDT_TSTAMP field. Returns INVALID_DATETIME on failure.
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.
Decimal fListDecimal([const String path_field [, Long elem_id]] [,const String path_field2 [, Long elem_id] ... , ] const String 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.
The element ID of an array.
The name of the field from which the decimal value is retrieved.
Returns the decimal value from the specified PIN_FLDT_DECIMAL field. Returns INVALID_DECIMAL on failure.
This function retrieves the array element ID from the specified array field using a 0-n index in the array.
Decimal fListElemid([const String path_field [, Long elemid]] [,const String path_field2 [, Long elemid] ... , ] const String array_field, Long index);
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.
The element ID of a parent array or substruct.
The name of the array from which the element ID is retrieved.
The 0-n index of the exact array element, the ID of which to return.
Returns the elem_id value of the array element specified by 0-n index. Returns INVALID_ARRAY on failure.
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.
String field into which the field name is placed.
String field into which the error text is placed.
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.
Long fListLong([const String path_field [, Long elem_id]] [,const String path_field2 [, Long elem_id] ... , ]const String 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.
The element ID of an array.
The name of the field from which the long value is retrieved.
Returns the long value from the specified PIN_FLDT_INT or PIN_FLDT_ENUM field. Returns 0 on error.
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.
Long fListNumElem([const String path_field [, Long elem_id]] [,const String path_field2 [, Long elem_id] ... , ] const String array_field, Long elem_id);
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.
The element ID of an array.
The name of the array.
This function creates and sets the array element into which other functions set field values. The function calls PIN_FLIST_ELEM_ADD.
The name of the array to set.
The array's element ID. The default is 0.
This function sets a long value in a PIN_FLDT_INT or PIN_FLDT_ENUM field in the current flist.
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.
String fListString([const String path_field [, Long elem_id]] [,const String path_field2 [, Long elem_id] ... , ] const String 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.
The element ID of an array.
The name of the field from which the string value is retrieved.
Returns the string value from the specified PIN_FLDT_STR or PIN_FLDT_POID field. Returns NULL_STRING on failure.
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.
The opcode number of the opcode to be executed.
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.
Table 7-9 contains hash and array functions.
Table 7-9 Hash and Array Functions
Function | Description |
---|---|
Clears an array. |
|
Determines the size of an array. |
|
Clears a hash. |
|
Checks to determine whether a hash-array contains a specific value. |
|
Retrieves all keys used in an associative array. |
|
Removes an entry from an associative array. |
This function checks to determine whether a hash-array contains a specific value.
Returns true if the hash contains the value specified by key. Returns false if the hash does not contain this value.
This function retrieves all keys used in an associative array.
The hash you want to search, looking for the key.
The string array as a return buffer for the keys.
Table 7-10 contains mapping functions.
Function | Description |
---|---|
Maps Long values to other Long values. |
|
Maps string values to other string values. |
This function maps Long values to other Long values.
The Long value to map.
The default return value if no valid mapping entry exists.
The source value of the first mapping entry; this value must be a constant.
The destination value of the first mapping entry; this value must be a constant.
Returns the matching destination value if the destination exists. Returns the value you specified in the default parameter if there is no destination.
This function maps string values to other string values.
String strDecode(String toMap, String default [[, const String src1, const String dest1] ...]);
The string value to map.
The default return value if no valid mapping entry exists.
The source value of the first mapping entry; this value must be a constant.
The destination value of the first mapping entry; this value must be a constant.
Returns the matching destination value if the destination exists. Returns the value you specified in the default parameter if there is no destination.
Table 7-11 contains opcode calling functions.
Table 7-11 Opcode Calling Functions
Function | Description |
---|---|
Calls the specified opcode. |
|
Obtains a connection from the specified connection pool. |
|
Calls PCM_OP, which performs the operation of the specified opcode and then returns the contents of the error buffer (ebuf) produced by the operation. |
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.
The opcode number of the opcode to be executed.
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.
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"); } } .........
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.
For more information about the PCM_OP opcode, see "PCM_OP".
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.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 ( | ).
A pointer to the input flist of the opcode being called. See the individual opcode flist reference pages for the input flist specifications.
A pointer to the error buffer that stores any errors that occur during the operation.
This function returns nothing.
Errors are passed back to the calling iScript through the specified error buffer.
Table 7-12 contains Pipeline system functions.
Table 7-12 Pipeline System Functions
Function | Description |
---|---|
Determines the name of the format the script is running in. |
|
Writes messages to the pipeline log |
|
Writes messages to the pipeline log. |
|
msgArg |
Deprecated. |
msgName |
Deprecated. |
msgNumArgs |
Deprecated. |
Returns the name of the registry node in which the script (iScript or input/output grammar) is running. |
|
Retrieves values from the registry. |
|
Sends a request to a registered object and waits for an answer (i.e., synchronous messaging). |
|
Sets the usable flag for the script. If the usable flag is set to false in the BEGIN function during Pipeline Manager startup, Pipeline Manager will not start to process CDRs. The false setting can be useful if the iScript initialization fails. |
|
Sends an event to the event handler. |
|
Stops the format; for example, after critical errors. |
This function writes messages to the pipeline log.
Important:
This function is obsolete and should be replaced by the logPipeline function.This function writes messages to the pipeline log.
The message to write to the pipeline log.
The severity of the message:
0 = Debug
1 = Normal
2 = Warning
3 = Minor error
4 = Major error
5 = Critical error
The default is 0.
This function returns the name of the registry node in which the script (iScript or input/output grammar) is running.
Returns the name of the registry node in which the script (iScript or input/output grammar) is running.
This function retrieves values from the registry.
Returns the specified registry entry if it exists. Returns an empty string if there is no registry entry with that name.
This function sends a request to a registered object and waits for an answer (i.e., synchronous messaging).
The registry name of the request's destination.
The name of the request.
A string array containing the input parameter expected by the destination to be able to process the request.
A string array to contain the reply to the request.
(Sequencer) Returns the new sequence number.
(Pipeline) Returns the country code defined in the registry for this pipeline.
(Pipeline) Returns the mobile country code defined in the registry for this pipeline.
(Pipeline) Returns the national access code value defined in the registry for this pipeline.
(Pipeline) Returns the international access code defined in the registry for this pipeline.
(Pipeline) Returns the international access code sign value defined in the registry for this pipeline.
(Pipeline) Returns the national destination code value defined in the registry for this pipeline.
(Pipeline) Returns the reject stream name defined in the registry for this pipeline.
(Pipeline) Returns the reject stream number defined in the registry for this pipeline.
(ifw) Returns the event handler name.
(Input) Returns the name and path of the error file.
(Input) Returns the name and path of the input file.
(Input) Returns the name and path of the temporary input file.
(Input) Returns the name and path of the done file.
(Input) Returns the name and path of the return file.
(Output) Returns the name and path of the output file.
(Output) Returns the name and path of the temporary output file.
Returns true if the request has been sent and an answer received successfully. Returns false if sending the request has failed.
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.This section describes static functions.
This function normalizes wireless and wireline CLIs into international format.
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 );
CLI to normalize.
Modification Indicator, for example, "00".
Type Of Number, for example, 0.
National Access Code, for example, "0".
International Access Code, for example, "00".
Country Code, for example, "49".
International Access Code Sign, for example, "+".
National Destination Code, for example, "172".
This function normalizes IPv4 addresses.
Returns an IP address in normalized format.
Dots (.) are skipped. Tokens are left-padded to 3 digits with zeroes.
This function normalizes IPv6 addresses.
Returns an IP address in normalized format.
Dots (.) are skipped. Tokens are left-padded to 4 digits with zeroes.
Table 7-13 contains standard functions.
Function | Description |
---|---|
Closes the connection to the Diameter client |
|
Gets the current system time in milliseconds. |
|
Gets the state of a Diameter client. |
|
Acquires the mutex specified by the handle (a number that identifies the mutex). When the mutex specified by the handle is already acquired by another thread, the function call is blocked unless the other thread releases the mutex by calling the mutexRelease function. |
|
Creates a mutex that can later be accessed by its handle. |
|
Used to destroy a mutex that is no longer needed. |
|
Releases a mutex that has been acquired. It unblocks a functional call by another thread that has been trying to acquire the mutex using the mutexAcquire function. |
|
Makes the process sleep. |
|
Starts the timer. |
|
Executes a command line in a file. |
|
Gets an environment variable. |
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.
This function gets the state of a Diameter client.
Returns one of the following state values:
0 = STATE_INITIAL
1 = STATE_OKAY
2 = STATE_DOWN
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.
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.
This function creates a mutex that can later be accessed by its handle.
Returns a handle (>0) if the mutex was created successfully. Returns <0 if the mutex was not created successfully.
This function destroys a mutex that is no longer needed.
Returns true when destroying the mutex is successful. Returns false when destroying the mutex has not been successful.
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.
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.
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.
The command line to execute. The value must be the path to an executable, followed by any arguments.
A string to collect the output produced on stdout by commandLine. The stdin and stderr for commandLine will be the terminal.
The maximum time (in seconds) to wait for the response from the event handler. Command execution is terminated when timeToWait expires.
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.
Table 7-14 contains string functions.
Function | Description |
---|---|
Converts a decimal value into a string. |
|
Converts a decimal value into a hexadecimal string. Use round(value) or trunc(value) to remove the decimal portion if you do not want it to be coded in hexadecimal. |
|
Converts a Long value into a hexadecimal string. |
|
Converts a Long value into a string. |
|
Converts the first character in the input string to its byte value. |
|
Maps string values to other string values. |
|
Checks to see if a string ends with a special suffix. |
|
Converts each pair of characters in a given hexadecimal string into the equivalent single-byte ASCII character in a new string. The returned string is half the size of the original. Only ASCII values from 0 through 255 can be handled by this function. Characters from multi-byte character sets will cause unexpected results. The function fails if memory cannot be allocated for the string to be returned. |
|
Converts a hexadecimal string to a decimal value. |
|
Converts a hexadecimal string into a Long value. |
|
Determines the length of a string. |
|
Compares a regular expression to a string, looking for a match. |
|
Pads a string to a specific length. The padding character and the justification can be selected. |
|
Replaces substrings in a string. |
|
Searches for a substring inside another string. |
|
Searches for a regular expression to a string. |
|
Splits a string according to a specific separator character and stores the resulting tokens in a string array. |
|
Checks to see if a string starts with a specified prefix. |
|
Removes special leading or trailing characters from a string. |
|
Converts each character in a given string into its two-character hexadecimal equivalent in a new string. The returned string is twice the size of the original. Only ASCII values from 0 through 255 can be handled by this function. Characters from multi-byte character sets cause unexpected results. The function fails if memory cannot be allocated for the string to be returned. |
|
Extracts a substring from a string. |
|
Converts a string into a date value. |
|
Converts string values to decimal values. |
|
Converts a string value to a Long value. |
|
Converts a string to lowercase characters. |
|
Converts a string to uppercase characters. |
This function converts a decimal value into a string.
The value to convert into a string.
The number of digits after the decimal point.
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.The decimal value to convert into a hexadecimal string. Code this in readable ASCII.
The character you want to use as a decimal separator (the default is .).
The precision of the decimal value to use when generating the hexadecimal string (the default is 0).
This function converts the first character in the input string to its byte value.
Returns the byte value of the first character if the function is successful. Returns 0 if the string is empty.
This function maps string values to other string values.
String strDecode(String toMap, String default [[, const String src1, const String dest1] ...]);
The string value to map.
The default return value if no valid mapping entry exists.
The source value of the first mapping entry; this value must be a constant.
The destination value of the first mapping entry; this value must be a constant.
Returns the matching destination value if the destination exists. Returns the value you specified in the default parameter if there is no destination.
This function checks to see if a string ends with a special suffix.
Returns true if the string ends with the specified suffix. Returns false if the string does not end with the suffix.
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.
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.
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.
This function converts a hexadecimal string to a decimal value.
The hexadecimal string (coded in readable ASCII) to convert into a decimal value.
The character you want to use as decimal separator (the default is .).
The precision of the decimal value to be generated (the default is 0).
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.
This function compares a regular expression to a string, looking for a match.
The string that you want to search for the regular expression.
The regular expression to match against the string.
The starting index for the search; the beginning of the string has an index of 0 (the default is 0).
Returns the matching part of the string if the function is successful. Returns 0 if the function does not find a match.
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.The string to pad (or truncate) to a specified length.
The pad character to use (the first of the string is used if empty).
The desired length of the returned string. If length is less than or equal to 0, an empty string is returned.
If set to true, it specifies that the string be left justified. If set to false, it specifies that the string be right justified.
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 = "";
This function replaces substrings in a string.
The string in which you want the substring replaced.
Important:
The input string in toReplace is not changed.The start position of the substring to replace. Positions start with 0.
The length of the substring to replace.
The replacement string.
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.
This function searches for a substring inside another string.
The string that you want to search.
The string that you want to search for.
The starting index for the search; the beginning of the string has an index of 0 (the default is 0).
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.
This function searches for a regular expression to a string.
The string that you want to search.
The regular expression to look for in the string.
Important:
The strSearchRegExpr function does not support braces ({ }); for example, A{1,3}.The starting index for the search; the beginning of the string has an index of 0 (the default is 0).
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.
This function splits a string according to a specific separator character and stores the resulting tokens in a string array.
The resulting array to fill.
The input string to split.
The separator to use for splitting. If the separator you specify is longer than one character, the function uses only the first character.
This function checks to see if a string starts with a specified prefix.
The string in which to check for the specified prefix.
The specified prefix being checked for in the string.
Returns true if the string starts with the specified prefix. Returns false if the string does not start with the specified prefix.
This function removes special leading or trailing characters from a string.
The string from which you want to remove leading or trailing characters.
The strip mode:
STRIP_LEADING
STRIP_TRAILING
STRIP_BOTH
The default is STRIP_LEADING.
The character to be removed, which is the first or last character of the string (the default is the space character).
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.
The ASCII string to convert to hexadecimal. It cannot be empty. Embedded nulls are permitted and handled correctly.
This function extracts a substring from a string.
The string from which you want to extract the substring.
The start position of the substring to extract. Positions start with 0.
The length of the substring to extract.
Returns the specified string if the function is successful. Returns an empty string if pos and len do not specify a valid substring.
This function converts a string into a date value. The only supported string format is YYYYMMDDHHMMSS.
The literal % character.
The day of the month; for example, 29. The range is 00-31.
The hour of the 24-hour day; for example, 14. The range is 00-23.
The month of the year, from 01; for example, 02. The range is 01-12.
The minutes after the hour; for example, 34. The range is 00-59.
The seconds after the minute; for example, 56. The range is 00-59.
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.
The year including the century; for example, 1994.
Returns a valid date if the input string is in the right format. Returns an invalid date if the format is not correct.
This function converts string values to decimal 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.
This function converts a numeric string value to a Long value. An alphanumeric string is returned as 0.
Returns the string converted to a Long value if the function is successful. Returns 0 if the string is not a valid Long value.
Table 7-15 contains transaction management functions.
Table 7-15 Transaction Management Functions
Function | Description |
---|---|
Sends a request to the Transaction Manager to cancel the current transaction. |
|
Sends a request to the Transaction Manager to roll back the current transaction. |
|
Allows the iScript module to request the reason for the rollback in the onRollback function. |
|
Returns the type of an item in the currently processed transaction. |
|
Returns the number of items processed in the currently processed transaction. |
|
Used to access the extension value of each item in the current transaction. |
|
Used to access the stream name of each item in the current transaction. |
|
Returns the transaction ID of the transaction currently being processed. |
This function sends a request to the Transaction Manager to cancel the current transaction.
This function sends a request to the Transaction Manager to roll back the current transaction.
This function allows the iScript module to request the reason for the rollback in the onRollback function.
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.
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.
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.
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.
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.
Returns the stream extension string if the function is successful. Returns an empty string if the function fails.
This function accesses the stream name of each item in the current transaction. The index should be between 0 and tamNumTransItems( )–1.
Returns the stream name if the function is successful. Returns an empty string if the function fails.
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.
Returns the current transaction ID. Returns 0.0 if there is no current transaction in the other functions.