DML functions: Strings and binaries

String functions

Binary functions

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

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.

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.

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.

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.

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

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

[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

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)

Related Links