DML functions: Strings and binaries

String Functions

The following String Functions enable you to search for Strings within other Strings, to modify a String, or replace a String with another one. (The position of the first character in the String is always 1.)

length
getStringLeft / getStringRight
getSubString
countString
index
padStringLeft / padStringRight
replaceString / replaceStringAll
toLower / toUpper
trimString / trimStringLeft / trimStringRight

length

length	Comment
Description	length.0 returns length. If the string is empty, blanksBlanks can include white space, carriage return and tab stops. returns the number of characters in a string including
Syntax	length(string_expression)
Return	Integer
Parameter	string_expression Enter an expression that returns a String.
Examples	length("Today") returns the value 5. length("Today is the fourteenth of July.") returns the value 32.

getStringLeft

getStringLeft	Comment
Description	getStringLeft returns a subset of characters in a string, starting from the left.
Syntax	getStringLeft(string_expression, number_of_characters)
Return	String
Parameters	string_expression Enter an expression that returns a String.
Parameters	number_of_characters Enter an Integer expression that represents the number of characters in string_expression that getStringLeft copies. If number_of_characters is: Greater than the length of string_expression, getStringLeft returns the complete string. Equal to zero, getStringLeft returns " ". Less than zero, getStringLeft returns null.
Examples	getStringLeft("Today",4) returns "Toda"- the first 4 characters in the string. getStringLeft("Today", 7) returns "Today" - the complete string, since it is shorter than number_of_characters. getStringLeft("Today", O) returns " ". getStringLeft("Today", -5) returns null.

getStringRight

getStringRight	Comment
Description	getStringRight returns a subset of characters in a string, starting from the right.
Syntax	getStringRight(string_expression, number of characters_in_string)
Return	String
Parameters	string_expression Enter an expression that returns a String.
Parameters	number_of_characters Enter an Integer expression that represents the number of characters in string_expression that getStringRight copies. If number_of_characters is: Greater than the length of string_expression, getStringRight returns the complete string. Equal to zero, getStringRight returns " ". Less than zero, getStringRight returns null.
Examples	getStringRight("Today",3) returns "day" - the last 3 characters in the string. getStringRight("Today",8) returns "Today" - the complete string, since number_of_characters is greater than the length of string_expression. getStringRight("Today",0) returns " ". getStringRight("Today",-2) returns null.

getSubString

getSubString	Comment
Description	getSubString returns a subset of characters in a string, starting from the position in the string that you specify.
Syntax	getSubString(string_expression, position_in_string,number_of_characters)
Return	String
Parameters	string_expression Enter an expression that returns a String.
	position_in_string Specify the position in string_expression where getSubString begins to return characters. This value is an Integer. The first character in the String is in position 1. If position_in_string is: less than one, getSubString returns null greater than the length of the string, getSubString returns null
	number_of_characters Specify the number of characters in string_expression that getSubString returns. This value is an Integer. If number_of_characters is: Greater than the number of characters available after position_in_string, getSubString returns all available characters. Less than zero, getSubString returns null.
Examples	getSubString("Today",2,3) returns "oda" - the 3 characters starting from position 2. getSubString("Today",0,3) returns null - the position in the string is less than one. getSubString("Today",6,3) returns null - the position in the string is greater than the length of the string. getSubString("Today",3,6) returns "day" - all the available characters starting from position 3. getSubString("Today",3,-2) returns null.

index

index	Comment
Description	index returns the starting position of the first occurrence of a substring.
Syntax	index(string_expression, substring[, position_in_string])
Returns	Integer NOTE: If the substring is not found, index returns 0.
Parameters	string_expression String expression to be parsed.
	substring Substring to be searched for within string_expression.
	position_in_string (Integer) Starting position in string_expression from which index begins search for substring. If you do not specify a position, index starts at position one. If position_in_string is: Less than or equal to zero, index returns null. Greater than the length of string, index returns null.
Examples	index("Today","day") returns the value 3. The substring day first occurs at position 3 in the string Today index("Today","day",-1) returns null - position_in_string is less than zero. index("Today","day",6) returns null - position_in_string is greater than the length of the string.

countString

countString	Comment
Description	countString counts the number of times that a substring occurs within a string. If countString cannot find the substring, it returns zero.
Syntax	countString (string_expression, substring)
Return	Integer
Parameters	string_expression Enter a String expression.
Parameters	substring Enter the substring that countString counts.
Examples	countString("Today is the first day of the rest of your life","day") returns the value 2. The substring "day" occurs twice. countString("Today is the first day of the rest of your life","work") returns the value 0. The substring "work" does not appear in string_expression.

toUpper

toUpper	Comment
Description	toUpper converts all letters in string_expression to upper case.
Syntax	toUpper (string_expression)
Return	String
Parameter	string_expression Enter an expression that returns a String.
Examples	toUpper("Today") returns the String "TODAY". The following Function converts all letters to upper case in the strings designated by FirstName and LastName. Subject = toUpper(\CustomerTransaction\Customer\FirstName) & " " & toUpper(\CustomerTransaction\Customer\LastName)

toLower

toLower	Comment
Description	toLower converts all letters in string_expression to lower case.
Syntax	toLower(string_expression)
Return	String
Parameter	string_expression Enter an expression that returns a String.
Examples	toLower("TODAY") returns the String. Subject = toLower(\CustomerTransaction\Customer\FirstName) & " " & toLower(\CustomerTransaction\Customer\LastName)

replaceString

replaceString	Comment
Description	replaceString replaces the first occurrence of a substring with the string that you specify.
Syntax	replaceString(string_expression,substring,replace_string[,position_in_string])
Return	String If one of the parameters has the value null or absent, the function returns null.
Parameters	string_expression Enter an expression that returns a String.
	substring Enter the substring that replaceString replaces.
	replace_string Enter the string that replaceString substitutes for substring.
	position_in_string Specify the position in string_expression where replaceString begins to search for substring. If you do not specify a position, replaceString uses position 1. If position in string is: Less than zero, >replaceString returnsnull Greater than the length of string, replaceString returns null
Example	In the following example, replaceString substitutes the replace_string parameter ("wages") for the substring parameter ("tax"). replaceString("Increase tax by ten per cent", "tax", "wages") returns the String "Increase wages by ten per cent".

replaceStringAll

replaceStringAll	Comment
Description	replaceStringAll uses a string to replace every occurrence of a string within a string. If replaceStringAll does not find the string within a string, it returns the unmodified string.
Syntax	replaceStringAll(string_expression, findstring, replaceString)
Return	A modified String.
Parameters	string_expression Enter an expression that returns a String.
	findstring Specify the String within string_expression that you want to replace.
	replacestring Enter the String that replaceStringAll substitutes for findstring.
Examples	In the following example, replaceStringAll replaces every occurrence of the findstring parameter "be" with the replacestring parameter "work". replaceStringAll("To be or not to be, that is the question", "be", "work") returns the String "To work or not to work, that is the question" replaceStringAll("To be or not to be, that is the question", "have", "work") returns the unmodified String "To be or not to be, that is the question", since no occurrence of the findstring parameter "have" was found.

trimString

trimString	Comment
Description	trimString deletes a leading and trailing character chain that you specify. If you do not specify a character chain, trimString deletes leading and trailing spaces.
Syntax	trimString(string_expression[, character_string])
Return	String: the trimmed String.
Parameters	string_expression Enter an expression that returns a String.
Parameters	[character_string] Enter a character string.
Example	trimString("ABABABABTodayABABAB","AB") returns the String "Today"

trimStringLeft

trimStringLeft	Comment
Description	trimStringLeft deletes a leading character chain that you specify. If you do not specify a character chain, trimStringLeft deletes leading spaces.
Syntax	trimStringLeft(string_expression[, character_string])
Return	String: the trimmed String
Parameters	string_expression Enter an expression that returns a String.
Parameters	[character chain] Enter a character string.
Example	trimStringLeft(ABABABABToday,"AB") returns the String "Today"

trimStringRight

trimStringRight	Comment
Description	trimStringRight deletes a trailing character chain that you specify. If you do not specify a character chain, trimStringRight deletes trailing spaces.
Syntax	trimStringRight(string_expression[, character_string])
Return	String: the trimmed String
Parameters	string_expression Enter an expression that returns a String.
Parameters	[character_string] Enter the string of characters that you want to delete.
Example	trimStringRight("TodayABABABAB", "AB") returns the String "Today"

padStringLeft

padStringLeft	Comment
Description	padStringLeft enlarges the length of a string to the returned_string_length that you specify, by adding a leading character string that you specify. If you do not specify a character string, padStringLeft adds spaces.
Syntax	padStringLeft(string_expression, returned_string_length[, character_string])
Return	String: the padded String
Parameters	string_expression Enter an expression that returns a String.
	returned_string_length Enter an Integer that indicates the length of the modified string. If returned_string_length is less than the length of string_expression, padStringLeft returns null.
	[character_string] Enter a string of characters. If the number of characters in character_string is greater than returned_string_length, the character chain is truncated.
Examples	padStringLeft("Today", 10, ">") returns the String ">>>>>Today". padStringLeft("Today", 10, "ABC") returns the String "ABCABToday".

padStringRight

padStringRight	Comment
Description	padStringRight enlarges the length of a string to the returned_string_length that you specify by adding a trailing character string that you specify. If you do not specify a character string, padStringRight adds spaces.
Syntax	padStringRight(string_expression, returned_string_length, [character_string])
Return Type	String: the padded string
Parameters	string_expression Enter an expression that returns a String.
	returned_string_length Enter an Integer that indicates the length of the modified string. If returned_string_length is less than the length of string_expression, padStringRight returns null.
	[character_string]: a String. If the number of characters in character_string is greater than returned_string_length, the character string is truncated.
Examples	padStringRight("Today", 10, ">") returns the String "Today>>>>>". padStringRight("Today", 10, "ABC") returns the String "TodayABCAB".

Binary Functions

To manipulate data of the class V (Very Large Objects), you must first extract it to the data class String.

Extract extracts from a Very Large Object the number of octets that you specify and returns a String.
byteSize returns the number of octets in a Very Large Object.

extract

Comment

Description

extract extracts from a Very Large Object the number of octets that you specify, starting from the position that you specify, and returns String data with the specified encoding.

Syntax

extract(very_large_object, position_in_very_large_object, number_of_octets, [encoding])

Return

String in specified encoding

Parameters

very_large_object
Specify a Very Large Object value.

position_in_very_large_object
Specify the position in the Very Large Object where extract starts to extract characters. position_in_very_large_object must not be greater than the length of very_large_object.

number_of_octets
Specify the number of characters in very_large_object that extract extracts.

encoding

Specify the encoding of the String. The encoding types delivered with Map Engine include:

"big5" = BIG5
"ebcdic" = EBCDIC
"eucjp" = EUC-JP
"ibmknj" = IBM kanji
"is8859" = iso8859
"jis" = JIS
"sjis" = Shift-JIS
"ucs2" = UCS-4
"utf16" = UTF-16
"utf32" = UTF-32
"utf8" = UTF-8

If the encoding doesn't exist in Mapping Services, an error occurs at runtime.

Note

The function doesn't check whether the string is compatible with the specified encoding. Thus, an error may occur when the String value is first used.

Example

extract(BEInVNode,10 000,500, "utf8") returns a String with encoding UTF-8 that consists of the 500 characters starting from position 10 000 in the Business Document node BEInVNode.

byteSize

byteSize	Comment
Description	byteSize returns the length in octets of very_large_object.
Syntax	byteSize(very_large_object)
Return	Integer
Parameters	very_large_object Specify a Very Large Object value.
Example	byteSize(BEInVNode)

Product

Content Type

Environment

Mapping Services 3.3.1 DML Users Guide