DML functions: Strings and binaries

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

length(string_expression)

Integer

string_expression
Enter an expression that returns a String.

getStringLeft returns a subset of characters in a string, starting from the left.

getStringLeft(string_expression, number_of_characters)

String

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.

getStringRight returns a subset of characters in a string, starting from the right.

getStringRight(string_expression, number of characters_in_string)

String

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.

getSubString returns a subset of characters in a string, starting from the position in the string that you specify.

getSubString(string_expression, position_in_string,number_of_characters)

String

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.

index returns the starting position of the first occurrence of a substring.

index(string_expression, substring[, position_in_string])

Integer

NOTE: If the substring is not found, index returns 0.

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.

countString counts the number of times that a substring occurs within a string. If countString cannot find the substring, it returns zero.

countString (string_expression, substring)

Integer

string_expression
Enter a String expression.

substring
Enter the substring that countString counts.

toUpper converts all letters in string_expression to upper case.

toUpper (string_expression)

String

string_expression
Enter an expression that returns a String.

toLower converts all letters in string_expression to lower case.

toLower(string_expression)

String

string_expression
Enter an expression that returns a String.

replaceString replaces the first occurrence of a substring with the string that you specify.

replaceString(string_expression,substring,replace_string[,position_in_string])

String

If one of the parameters has the value null or absent, the function returns null.

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

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.

replaceStringAll(string_expression, findstring, replaceString)

A modified String.

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.

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.

trimString(string_expression[, character_string])

String: the trimmed String.

string_expression
Enter an expression that returns a String.

[character_string]
Enter a character string.

trimStringLeft deletes a leading character chain that you specify. If you do not specify a character chain, trimStringLeft deletes leading spaces.

trimStringLeft(string_expression[, character_string])

String: the trimmed String

string_expression
Enter an expression that returns a String.

[character chain]
Enter a character string.

trimStringRight deletes a trailing character chain that you specify. If you do not specify a character chain, trimStringRight deletes trailing spaces.

trimStringRight(string_expression[, character_string])

String: the trimmed String

string_expression
Enter an expression that returns a String.

[character_string]
Enter the string of characters that you want to delete.

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.

padStringLeft(string_expression, returned_string_length[, character_string])

String: the padded String

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.

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.

padStringRight(string_expression, returned_string_length, [character_string])

String: the padded string

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.

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.

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

String in specified encoding

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.

byteSize returns the length in octets of very_large_object.

byteSize(very_large_object)

Integer

very_large_object
Specify a Very Large Object value.