AssignData

Purpose

Use AssignData to define a constant, assign a different value to a variable, perform a mathematical operation, or manipulate strings of characters. AssignData assigns the result of the requested operation to a variable.


A screen capture of the Action AssignData window

Description

AssignData can be used for incrementing a counter during loop processing (followed by an EvaluateData to check the value of the counter), when a variable must have a specific value before an action is performed, or when the value of one variable should be assigned to a different variable.

Parameters

The parameters for AssignData identify an operation, the operands on which the operation is performed, and the variable to which the result is assigned. Operations that are performed on two values can be performed when the values are contained in variables, defined as constants, or a combination.

The parameters for AssignData are as follows:

Operator.
Identifies what operation to perform. Depending on the operation, you may have to define values for both Operand 1 and Operand 2, or only Operand 1. The results of the operation are assigned to the variable identified by the value of Result. The possible values for Operator are categorized below under the headings of :
  • Generic
  • Numeric
  • String
  • Tag
Generic
Assign.
Assigns the value you define for Operand 1 to the variable you identify as the Result parameter.
Numeric
Add.
Adds the values defined for Operand 1 and Operand 2. The sum is assigned to the variable you identify as the Result parameter.
Subtract.
Subtracts the value defined for Operand 2 from the value defined for Operand 1. The difference is assigned to the variable you identify as the Result parameter.
Multiply.
Multiplies the values defined for Operand 1 and Operand 2. The product is assigned to the variable you identify as the Result parameter.
Divide.
Divides the value defined for Operand 1 by the value defined for Operand 2. The result is assigned to the variable you identify as the Result parameter. If Operand 2 is zero the result is Overflow. See also the system variable System : MPN : Maximum decimal places (RW) (SV131) .
Modulus.
Divides the value defined for Operand 1 by the value defined for Operand 2. Both Operand 1 and Operand 2 must be integers, or else the result is Data Mismatch. The remainder is assigned to the variable you identify as the Result parameter.

For example, if Operand 1 is 10 and Operand 2 is 3, the Modulus operation calculates 10 divided by 3 = 3 remainder 1. Result is assigned a value of 1.

If Operand 2 is zero the result is Overflow.

Absolute Value.
Assigns the absolute value of the number found in Operand 1 to the variable identified as the Result parameter.

For example, if Operand 1 is a variable with a value of -5 at this state, Absolute Value assigns a value of 5 to the variable identified as Result.

Truncate.
Truncates the value defined for Operand 1 at the digit specified by Operand 2. The truncated value is assigned to the variable you identify as the Result parameter. Operand 2 must be an integer, or else the result is Data Mismatch.

Truncate operates on numbers. If Operand 2 is positive, AssignData truncates the number at that digit place to the right of the decimal place. If Operand 2 is negative, AssignData rounds the number down at that digit place to the left of the decimal place.

For example, if Operand 1 is 345.678 and Operand 2 is 1, Result is assigned the value 345.6. If Operand 2 is -1, Result is assigned the value 340. If Operand 2 is 0, Result is assigned the value 345.

Round.
Rounds the value defined for Operand 1 at the digit specified by Operand 2. The rounded value is assigned to the variable you identify as the Result parameter. Operand 2 must be an integer, or else the result is Data Mismatch.

Round operates on numbers. If Operand 2 is positive, AssignData rounds the number at that digit place to the right of the decimal place. If Operand 2 is negative, AssignData rounds the number at that digit place to the left of the decimal place. AssignData rounds numbers ending in 5 to the next higher value.

For example, if Operand 1 is 135.789 and Operand 2 is 1, Result is assigned the value 135.8. If Operand 2 is -1, Result is assigned the value 140. If Operand 2 is 0, Result is assigned the value 136.

String
Concatenate.
Appends the value of Operand 2 to the value of Operand 1 and assigns the new value to the variable you identify as the result parameter.

Concatenate is a string operation. If Operand 1 is a constant number, it treats the number as a string, not a mathematical value.

Left.
Starts at the left-hand character in the value of Operand 1 and counts over the number of characters defined by the value of Operand 2. The resulting string is assigned to Result.

For example, if Operand 1 is "caller" and Operand 2 is 4, the value assigned to Result is "call."

Left is a string operation. If Operand 1 is a number, it treats the number as a string, not a numeric value.

Right.
Starts at the right-hand character in the value of Operand 1 and counts over the number of characters defined by the value of Operand 2. The resulting string is assigned to Result.

For example, if Operand 1 is "telephone" and Operand 2 is 5, the value assigned to Result is "phone."

Right is a string operation. If Operand 1 is a number, it treats the number as a string, not a numeric value.

Index.
Selects a character in Operand 1 and assigns it to the variable identified as the Result parameter. The characters in Operand 1 are numbered from left to right, starting at 1. The character is selected by the number in Operand 2. If the number in Operand 2 points beyond either end of Operand 1, then the result will be an empty string.

For example, if Operand 1 is 4085551212 and Operand 2 is 3, the value assigned to Result is 8.

Index is a string operation. If Operand 1 is a number, it treats the number as a string, not a numeric value.

Search String.
Searches for the string in Operand 2 within the string in Operand 1 (a longer string). If Operand 2 is found, the Result parameter is assigned the position of the start of Operand 2 in Operand 1. If Operand 2 is not found, the result is 0.

For example, if Operand 1 is 5551212 and Operand 2 is 51, the value assigned to Result is 3.

Search String is a string operation. If either operand is a number, it treats the number as a string, not a numeric value.

Length.
Counts the number of characters in Operand 1 and assigns the result to the variable identified as the Result parameter.

Length is a string operation. If Operand 1 is a number, it treats the number as a string, not a numeric value.

To Uppercase.
Capitalizes all the letters in the string defined for Operand 1 and assigns the capitalized string to the variable identified as the Result parameter.
To Lowercase.
Makes sure none of the letters in the string defined for Operand 1 are capitalized and assigns the lowercase string to the variable identified as the Result parameter.
Tag
Remove Tag
Searches the string in Operand 1 for the tag label in Operand 2. If the tag label is found, the Result parameter contains the string in Operand 1 minus the tag string designated by the tag label. To update the tag string in Operand 1, specify the Result variable to be the same as Operand 1.
RemoveAttribute
Searches the string in Operand 1 for the tag.attribute pair identified in Operand 2. If the attribute is found, the Result parameter contains the string in Operand 1 minus the attribute substring. To update the tag string in Operand 1, specify the Result variable to be the same as Operand 1.
GetTag
Searches for the tag label in Operand 2 within the string in Operand 1. If the tag is found, the whole tag string is appended to the string within the variable identified as the Result parameter
GetAttributeValue
Searches for the tag.attribute pair identified in Operand 2 within the string in Operand 1. If the attribute is found, its value is assigned to the variable identified as the Result parameter.
GetTagValue
Searches for the tag label in Operand 2 within the tag string in Operand 1. If the tag label is found, the tag value is assigned to the variable identified as the Result parameter
PutTag
Uses the tag label in Operand 1 and the tag value in Operand 2 to build a tag string and append it to the variable identified as the Result parameter. PutTag first checks for any duplicates of the tag label and fails if any are found.
PutAttribute
Uses the tag label element of the tag.attribute pair in Operand 1 to identify a tag substring in the Result parameter, and the attribute element to check this substring for any duplicates of the attribute. If it does not find a tag substring that matches the tag label, or if the attribute already exists in the substring, AssignData returns a Failed result. Otherwise PutAttribute builds an attribute from the attribute element of the tag.attribute pair in Operand 1 and the value provided in Operand 2, and inserts this into the identified tag substring.
ChangeTagValue
Searches the string variable identified as the Result parameter for the tag label in Operand 1. If the tag is found its value is replaced with the value in Operand 2, otherwise ChangeTagValue fails and leaves the tag unchanged.
Note:
  1. A tag string is a string of data that is built (using syntactic rules) to map tags with their values and attribute sets. Each tag has only one value and one attribute set. The tag, its value and attribute set together represent a tag substring.
  2. An attribute set is a set of attribute label name strings and their associated values. An attribute set is represented using an attribute substring.
  3. An attribute substring is built (using syntactic rules) to map attribute label names with their associated values. Each attribute has only one value.
Operand 1.
A constant or a variable.
Operand 2.
A constant or a variable.
Result.
Identifies the variable to which the results of the operation are assigned.

Possible results

AssignData can have one of the following results:

Succeeded
The operation was completed successfully. The variable identified as the Result parameter contains a new value.
Overflow
The variable identified as the Result parameter was too small to hold the result of the operation, or an attempt was made to divide by zero (divide or modulus).
Data Mismatch
The operation you selected for the Operator parameter found data in a form different to that expected (such as an attempt to add the number ‘123’ to the character string ‘ABC’). In the case of the tag manipulation operators, a Data Mismatch result would mean that one of the fields is syntactically incorrect.
Failed
A system error may have occurred or one of the variables was invalid for the operation. In the case of the tag manipulation operators, a Failed result is returned if a tag or attribute label is not found when expected, or if they already exist when an attempt is made to add them. In all these cases, Blueworx Voice Response does not assign a value to the variable identified as the Result parameter. Errors may be logged to the system monitor GUI, or to the errorlog file or DTstatus.out file under the path identified by the $OAM_LOG_PATH environment variable.

ASCII syntax

When using an ASCII editor, code this action with these parameters in the following order:

  1. result variable
  2. operator:
    • "ADD" or
    • "SUBTRACT" or
    • "MULTIPLY" or
    • "DIVIDE" or
    • "MODULUS" or
    • "ABSOLUTE_VALUE" or
    • "TRUNCATE, ROUND" or
    • "CONCATENATE" or
    • "LEFT" or
    • "RIGHT" or
    • "INDEX" or
    • "SEARCH_STRING" or
    • "LENGTH" or
    • "TO_UPPERCASE" or
    • "TO_LOWERCASE" or
    • "PUT_TAG" or
    • "PUT_ATTRIBUTE" or
    • "CHANGE_TAG_VALUE" or
    • "GET_TAG" or
    • "GET_TAG_VALUE" or
    • "GET_ATTRIBUTE_VALUE" or
    • "REMOVE_TAG" or
    • "REMOVE_ATTRIBUTE"
  3. operand 1 (variable or constant)
  4. operand 2 (variable or constant), if needed

For example:

label: "Check Edges"
	AssignData(loc1_n, "ASSIGN", 5)
	  edge EDGE_ASSIGN_OK:			  assign_ok
	  edge EDGE_ASSIGN_OVERFLOW:		  assign_overflow
	  edge EDGE_ASSIGN_MISMATCH:		  assign_mismatch
	  edge EDGE_ASSIGN_NOT_OK: 		 assign_not_ok
	;
	AssignData(loc2_n, "ADD", loc1_n, 4);
	AssignData(loc3_s, "SUBTRACT", 10, loc2_n);
	AssignData(loc4_s, "MULTIPLY", loc3_s, loc2_n);
	AssignData(in1_n, "DIVIDE", loc4_s, 2);
	AssignData(in2_n, "MODULUS", in1_n, 13);
	AssignData(in3_s, "ABSOLUTE_VALUE", in2_n);
	AssignData(in4_s, "TRUNCATE", 12, 678);
	AssignData(loc1_n, "ROUND", in4_s, SV142);
	AssignData(loc4_s, "CONCATENATE", in4_s, in3_s);
	AssignData(loc4_s, "LEFT", in3_s, 4);
	AssignData(loc4_s, "RIGHT", loc3_s, 5);
	AssignData(loc4_s, "INDEX", loc4_s, 5);
	AssignData(loc4_s, "SEARCH_STRING", loc3_s, "hello");
	AssignData(loc1_n, "LENGTH", loc3_s);
	AssignData(loc4_s, "TO_UPPERCASE", loc3_s);
	AssignData(loc4_s, "TO_LOWERCASE", loc4_s);

The parameters and edges are described above under "Parameters" and "Possible results". For more information, see Testing a state table using the debugger.

The use of the AssignData action to write to the System : Call : Info out system variable (SV541) and read from the System : Call Info : Info in system variable (SV542) is further clarified in the examples below (which assume that SV541 (outgoing tag to signalling process) is initially blank). The outcome of each call to AssignData is also described: 
AssignData(SV541, "PUT_TAG", "ORIGIN", "1234");
SV541 has one tag: tag label ORIGIN with associated value 1234.
AssignData(SV541, "PUT_TAG", "RDIRN", "5678");
SV541 now contains 2 tags: ORIGIN (value 1234) and REDIRN (value 5678).
AssignData(SV541, "PUT_ATTRIBUTE", "RDIRN.CALL_REF", "90");
The tag identified by tag label RDIRN in SV541 now also has an associated
attribute CALL_REF which itself has an associated value of 90.
AssignData(SV541, "PUT_ATTRIBUTE", "RDIRN.PRESENT", "1");	
Now REDIRN is associated to a second attribute PRESENT which has value 1.
AssignData(SV541,"CHANGE_TAG_VALUE", "REDIRN", "6789");
Tag identified by label REDIRN in SV541 has its value changed to 6789.
Now, using an initially empty local string: loc_s:
AssignData(loc_s, "REMOVE_TAG", SV541, "ORIGIN");
loc_s only contains tag RDIRN with its associated elements.
AssignData(SV541, "REMOVE_ATTRIBUTE", SV541, "RDIRN.CALL_REF");
SV541 still contains its original 2 tags, but the tag RDIRN now only has one
associated attribute left: PRESENT (value 1).
Now assume SV542 (incoming tag string from signalling process) contains 3 tags:
The first has label: CLGN, with value 1234 and attribute SCREEN with value 1.
The second has label: CALL_TYPE with value 1.
The third has label: FAC with value A7.
Consider the effects of the following steps, where local string variables
loc1_s and loc2_s are initially blank:
AssignData(loc1_s, "GET_TAG", SV542, "FAC");
loc1_s has one tag: its label name is FAC and value is A7. SV542 is unchanged.
AssignData(loc1_s, "GET_TAG", SV542, "CLGN");
loc1_s now has 2 tags: FAC (value A7) and CLGN  with associated value 1234
and attribute SCREEN which has value 1.
AssignData(loc2_s, "GET_TAG_VALUE", SV542, "CLGN");
loc2_s contains the string: "1234".
AssignData(loc2_s, "GET_ATTRIBUTE_VALUE", SV542, "CLNG.SCREEN");
loc2_s is overwritten with the string: "1".
Parent topic: Alphabetical list of state table actions