Net.Data Reference

String Functions

The following functions are the set of standard string functions that Net.Data supports:

DTW_ASSIGN
DTW_CONCAT
DTW_DELSTR
DTW_INSERT
DTW_LASTPOS
DTW_LENGTH
DTW_LOWERCASE
DTW_POS
DTW_REVERSE
DTW_STRIP
DTW_SUBSTR
DTW_TRANSLATE
DTW_UPPERCASE

MBCS support for OS/390, OS/2, Windows NT, and UNIX: You can specify multiple-byte character set (MBCS) support for word and string functions with the DTW_MBMODE configuration value. Specify this value in the Net.Data initialization file; the default is no support. You can override the value in the initialization file by setting the DTW_MBMODE variable in a Net.Data macro file. See the configuration variable section in Net.Data Administration and Programming Guide and DTW_MBMODE for more information.

MBCS support for OS/400: DBCS support is provided automatically and does not require this variable.

DTW_ASSIGN

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Assigns the value of an input variable to an output variable. You can also use this function to change a variable in a macro.

Format

@DTW_ASSIGN(stringOut, stringIn)

Values

Table 48. DTW_ASSIGN Parameters

Data Type Parameter Use Description
string stringOut OUT A variable that contains the literal string identical to stringIn.
string stringIn IN A variable or literal string.

Data Type	Parameter	Use	Description
string	`stringOut`	OUT	A variable that contains the literal string identical to `stringIn`.
string	`stringIn`	IN	A variable or literal string.

Examples

Example 1:

@DTW_ASSIGN(RC, "0")

Sets RC to "0".

Example 2:

@DTW_ASSIGN(string1, string2)

Sets string1 to the value of string2.

DTW_CONCAT

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Concatenates two strings.

Format

@DTW_CONCAT(stringIn1, stringIn2, stringOut)

@DTW_rCONCAT(stringIn1, stringIn2)

Values

Table 49. DTW_CONCAT Parameters

Data Type Parameter Use Description
string stringIn1 IN A variable or literal string.
string stringIn2 IN A variable or literal string.
string stringOut OUT A variable that contains the string 'stringIn1stringIn2', where string1 is concatenated with string2.

Data Type	Parameter	Use	Description
string	`stringIn1`	IN	A variable or literal string.
string	`stringIn2`	IN	A variable or literal string.
string	`stringOut`	OUT	A variable that contains the string `'stringIn1stringIn2'`, where `string1` is concatenated with `string2`.

Examples

Example 1:

@DTW_CONCAT("This", " is a test.", result)

Returns: result = "This is a test."

Example 2:

@DTW_CONCAT(string1, "1-2-3", result)

Input: string1 = "Testing "
Returns: result = "Testing 1-2-3"

Example 3:

@DTW_rCONCAT("This", " is a test.")

Returns: "This is a test."

DTW_DELSTR

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Deletes a substring of the specified string from the nth character for length characters.

Format

@DTW_DELSTR(stringIn, n, length, stringOut)

@DTW_DELSTR(stringIn, n, stringOut)

@DTW_rDELSTR(stringIn, n, length)

@DTW_rDELSTR(stringIn, n)

Values

Table 50. DTW_DELSTR Parameters

Data Type Parameter Use Description
string stringIn IN A variable or literal string.
integer n IN The position of the character at which the substring to delete begins. If n is greater than the length of stringIn, stringOut is set to the value of stringIn.
integer length IN The length of the substring to delete. The default is to delete all characters to the end of stringIn.
string stringOut OUT A variable that contains the modified form of stringIn.

Data Type	Parameter	Use	Description
string	`stringIn`	IN	A variable or literal string.
integer	`n`	IN	The position of the character at which the substring to delete begins. If `n` is greater than the length of `stringIn`, `stringOut` is set to the value of `stringIn`.
integer	`length`	IN	The length of the substring to delete. The default is to delete all characters to the end of `stringIn`.
string	`stringOut`	OUT	A variable that contains the modified form of `stringIn`.

Examples

Example 1:

@DTW_DELSTR("abcde", "3", "2", result)

Returns: result = "abe"

Example 2:

@DTW_rDELSTR("abcde", "4", "1")

Returns: "abce"

DTW_INSERT

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Inserts a string into another string starting after the nth character.

Format

@DTW_INSERT(stringIn1, stringIn2, n, length, pad, stringOut)

@DTW_INSERT(stringIn1, stringIn2, n, length, stringOut)

@DTW_INSERT(stringIn1, stringIn2, n, stringOut)

@DTW_INSERT(stringIn1, stringIn2, stringOut)

@DTW_rINSERT(stringIn1, stringIn2, n, length, pad)

@DTW_rINSERT(stringIn1, stringIn2, n, length)

@DTW_rINSERT(stringIn1, stringIn2, n)

@DTW_rINSERT(stringIn1, stringIn2)

Values

Table 51. DTW_INSERT Parameters

Data Type Parameter Use Description
string stringIn1 IN A variable or literal string to be inserted into stringIn2.
string stringIn2 IN A variable or literal string.
integer n IN The character position in stringIn2 after which stringIn1 is inserted. If n is greater than the length of stringIn2, it is padded with the padding character, pad, until it has enough characters. The default is to insert at the beginning of stringIn2.
integer length IN The number of characters of stringIn1 to insert. The string is padded with the padding character, pad, if this parameter is greater than the length of stringIn1. The default is the length of stringIn1.
integer pad IN The padding character, as described for n and length. The default pad character is a blank.
string stringOut OUT A variable that contains stringIn2 modified by inserting part or all of stringIn1.

Data Type	Parameter	Use	Description
string	`stringIn1`	IN	A variable or literal string to be inserted into `stringIn2`.
string	`stringIn2`	IN	A variable or literal string.
integer	`n`	IN	The character position in `stringIn2` after which `stringIn1` is inserted. If `n` is greater than the length of `stringIn2`, it is padded with the padding character, `pad`, until it has enough characters. The default is to insert at the beginning of `stringIn2`.
integer	`length`	IN	The number of characters of `stringIn1` to insert. The string is padded with the padding character, `pad`, if this parameter is greater than the length of `stringIn1`. The default is the length of `stringIn1`.
integer	`pad`	IN	The padding character, as described for `n` and `length`. The default pad character is a blank.
string	`stringOut`	OUT	A variable that contains `stringIn2` modified by inserting part or all of `stringIn1`.

Examples

Example 1:

@DTW_INSERT("123", "abc", result)

Returns: result = "123abc"

Example 2:

@DTW_INSERT("123", "abc", "5", result)

Returns: result = "abc 123"

Example 3:

@DTW_INSERT("123", "abc", "5", "6", result)

Returns: result = "abc 123 "

Example 4:

@DTW_INSERT("123", "abc", "5", "6", "/", result)

Returns: result = "abc//123///"

Example 5:

@DTW_rINSERT("123", "abc", "5", "6", "+")

Returns: "abc++123+++"

DTW_LASTPOS

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Returns the position of the last occurrence of a string in another string, starting from the nth character and working backwards (right to left).

Format

@DTW_LASTPOS(stringIn1, stringIn2, n, position)

@DTW_LASTPOS(stringIn1, stringIn2, position)

@DTW_rLASTPOS(stringIn1, stringIn2, n)

@DTW_rLASTPOS(stringIn1, stringIn2)

Values

Table 52. DTW_LASTPOS Parameters

Data Type Parameter Use Description
string stringIn1 IN A variable or literal string searched for in stringIn2.
string stringIn2 IN A variable or literal string.
integer n IN The character position in stringIn2 to begin searching for stringIn1. The default is to start searching at the last character and scan backwards (from right to left).
integer position OUT The position of the last occurrence of stringIn1 in stringIn2. If no occurrence is found, 0 is returned.

Data Type	Parameter	Use	Description
string	`stringIn1`	IN	A variable or literal string searched for in `stringIn2`.
string	`stringIn2`	IN	A variable or literal string.
integer	`n`	IN	The character position in `stringIn2` to begin searching for `stringIn1`. The default is to start searching at the last character and scan backwards (from right to left).
integer	`position`	OUT	The position of the last occurrence of `stringIn1` in `stringIn2`. If no occurrence is found, 0 is returned.

Examples

Example 1:

@DTW_LASTPOS(" ", "abc def ghi", result)

Returns: result = "8"

Example 2:

@DTW_LASTPOS(" ", "abc def ghi", "10", result)

Returns: result = "8"

Example 3:

@DTW_rLASTPOS(" ", "abc def ghi", "7")

Returns: "4"

DTW_LENGTH

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Returns the length of a string.

Format

@DTW_LENGTH(stringIn, length)

@DTW_rLENGTH(stringIn)

Values

Table 53. DTW_LENGTH Parameters

Data Type Parameter Use Description
string stringIn IN A variable or literal string.
integer length OUT A symbol containing the number of characters in stringIn.

Data Type	Parameter	Use	Description
string	`stringIn`	IN	A variable or literal string.
integer	`length`	OUT	A symbol containing the number of characters in `stringIn`.

Examples

Example 1:

@DTW_LENGTH("abcdefgh", result)

Returns: result = "8"

Example 2:

@DTW_rLENGTH("")

Returns: "0"

DTW_LOWERCASE

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Returns a string in all lowercase.

Format

@DTW_LOWERCASE(stringIn, stringOut)

@DTW_rLOWERCASE(stringIn)

@DTW_mLOWERCASE(stringMult1, stringMult2, ..., stringMultn)

Values

Table 54. DTW_LOWERCASE Parameters

Data Type Parameter Use Description
string stringIn IN A variable or literal string with characters of any case.
string stringOut OUT A variable that contains stringIn with all characters in lowercase.
string stringMult INOUT

On input: A variable that contains a string.
On output: A variable that contains the input string converted to lowercase.

Data Type	Parameter	Use	Description
string	`stringIn`	IN	A variable or literal string with characters of any case.
string	`stringOut`	OUT	A variable that contains `stringIn` with all characters in lowercase.
string	`stringMult`	INOUT	On input: A variable that contains a string. On output: A variable that contains the input string converted to lowercase.

Examples

Example 1:

@DTW_LOWERCASE("This", stringOut)

Returns: stringOut = "this"

Example 2:

@DTW_rLOWERCASE(string1)

Input: string1 = "Hello"
Returns: "hello"

Example 3:

@DTW_mLOWERCASE(string1, string2, string3)

Input: string1 = "THIS", string2 = "IS", string3 = "LOWERCASE"
Returns: string1 = "this", string2 = "is", string3 = "lowercase"

DTW_POS

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Returns the position of the first occurrence of a string in another string, using a forward search pattern.

Format

@DTW_POS(stringIn1, stringIn2, n, nOut)

@DTW_POS(stringIn1, stringIn2, nOut)

@DTW_rPOS(stringIn1, stringIn2, n)

@DTW_rPOS(stringIn1, stringIn2)

Values

Table 55. DTW_POS Parameters

Data Type Parameter Use Description
string stringIn1 IN A variable or literal string to search for.
string stringIn2 IN A variable or literal string to search.
integer n IN The character position in stringIn2 to begin searching. The default value is to start searching at the first character of stringIn2.
integer nOut OUT A variable that contains the position of the first occurrence of stringIn1 in stringIn2. If no occurrence is found, 0 is returned.

Data Type	Parameter	Use	Description
string	`stringIn1`	IN	A variable or literal string to search for.
string	`stringIn2`	IN	A variable or literal string to search.
integer	`n`	IN	The character position in `stringIn2` to begin searching. The default value is to start searching at the first character of `stringIn2`.
integer	`nOut`	OUT	A variable that contains the position of the first occurrence of `stringIn1` in `stringIn2`. If no occurrence is found, 0 is returned.

Examples

Example 1:

@DTW_POS("day", "Saturday", result)

Returns: result = "6"

Example 2:

@DTW_POS("a", "Saturday", "3", result)

Returns: result = "7"

Example 3:

@DTW_rPOS(" ", "abc def ghi", "5")

Returns: "8"

DTW_REVERSE

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Reverses the input string.

Format

@DTW_REVERSE(stringIn, stringOut)

@DTW_rREVERSE(stringIn)

Values

Table 56. DTW_REVERSE Parameters

Data Type Parameter Use Description
string stringIn IN A variable or literal string to reverse.
string stringOut OUT A variable that contains the reversed form of stringIn.

Data Type	Parameter	Use	Description
string	`stringIn`	IN	A variable or literal string to reverse.
string	`stringOut`	OUT	A variable that contains the reversed form of `stringIn`.

Examples

Example 1:

@DTW_REVERSE("This is it.", result)

Returns: result = ".ti si sihT"

Example 2:

@DTW_rREVERSE(string1)

Input: string1 = "reversed"
Returns: "desrever"

DTW_STRIP

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Removes leading blanks, trailing blanks, or both from the input string.

Format

@DTW_STRIP(stringIn, option, stringOut)

@DTW_STRIP(stringIn, stringOut)

@DTW_rSTRIP(stringIn, option)

@DTW_rSTRIP(stringIn)

Values

Table 57. DTW_STRIP Parameters

Data Type Parameter Use Description
string stringIn IN A variable or literal string.
string option IN Specifies which blanks to remove from stringIn. The default is B.

B or b - remove both leading and trailing blanks
L or l - remove leading blanks only
T or t - remove trailing blanks only

string stringOut OUT A variable that contains stringIn with blanks removed as specified by option.

Data Type	Parameter	Use	Description
string	`stringIn`	IN	A variable or literal string.
string	`option`	IN	Specifies which blanks to remove from `stringIn`. The default is B. B or b - remove both leading and trailing blanks L or l - remove leading blanks only T or t - remove trailing blanks only
string	`stringOut`	OUT	A variable that contains `stringIn` with blanks removed as specified by option.

Examples

Example 1:

@DTW_STRIP("  day ", result)

Returns: result = "day"

Example 2:

@DTW_STRIP("  day ", "T", result)

Returns: result = " day"

Example 3:

@DTW_rSTRIP("  a day  ", "L")

Returns: "a day "

DTW_SUBSTR

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Returns a substring of the input string, with optional pad characters.

Format

@DTW_SUBSTR(stringIn, n, length, pad, stringOut)

@DTW_SUBSTR(stringIn, n, length, stringOut)

@DTW_SUBSTR(stringIn, n, stringOut)

@DTW_rSUBSTR(stringIn, n, length, pad)

@DTW_rSUBSTR(stringIn, n, length)

@DTW_rSUBSTR(stringIn, n)

Values

Table 58. DTW_SUBSTR Parameters

Data Type Parameter Use Description
string stringIn IN A variable or literal string to be searched.
integer n IN The first character position of the substring. The default is to start at the beginning of stringIn
integer length IN The number of characters of the substring. The default is the rest of the string.
string pad IN The padding character used if n is greater than the length of stringIn or if length is longer than stringIn. The default is a blank.
string stringOut OUT A variable that contains a substring of stringIn.

Data Type	Parameter	Use	Description
string	`stringIn`	IN	A variable or literal string to be searched.
integer	`n`	IN	The first character position of the substring. The default is to start at the beginning of `stringIn`
integer	`length`	IN	The number of characters of the substring. The default is the rest of the string.
string	`pad`	IN	The padding character used if `n` is greater than the length of `stringIn` or if `length` is longer than `stringIn`. The default is a blank.
string	`stringOut`	OUT	A variable that contains a substring of `stringIn`.

Examples

Example 1:

@DTW_SUBSTR("abc", "2", result)

Returns: result = "bc"

Example 2:

@DTW_SUBSTR("abc", "2", "4", result)

Returns: result = "bc "

Example 3:

@DTW_SUBSTR("abc", "2", "4", ".", result )

Returns: result = "bc.."

Example 4:

@DTW_rSUBSTR("abc", "2", "6", ".")

Returns: "bc...."

DTW_TRANSLATE

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Translates characters in the input string using input and output translation tables, tableI and tableO. If tableI, tableO, and the default character are not in the parameter list, the stringIn parameter is translated to uppercase. If tableI and tableO are in the list, each character in the input string is searched for in tableI and translated to the corresponding character in tableO. If a character in tableI has no corresponding character in tableO, the default character is used instead.

Format

@DTW_TRANSLATE(stringIn, tableO, tableI, default, stringOut)

@DTW_TRANSLATE(stringIn, tableO, tableI, stringOut)

@DTW_TRANSLATE(stringIn, tableO, stringOut)

@DTW_TRANSLATE(stringIn, stringOut)

@DTW_rTRANSLATE(stringIn, tableO, tableI, default)

@DTW_rTRANSLATE(stringIn, tableO, tableI)

@DTW_rTRANSLATE(stringIn, tableO)

@DTW_rTRANSLATE(stringIn)

Values

Table 59. DTW_TRANSLATE Parameters

Data Type Parameter Use Description
string stringIn IN A variable or literal string.
string tableO IN A variable or literal string used as a translation table. Use null ("") to specify tableI or default; otherwise this parameter is optional.
string tableI IN A variable or literal string searched for in stringIn. Use null ("") to specify default; otherwise this parameter is optional.
string default IN The default character to use. The default is a blank.
string stringOut OUT A variable that contains the translated result of stringIn.

Data Type	Parameter	Use	Description
string	`stringIn`	IN	A variable or literal string.
string	`tableO`	IN	A variable or literal string used as a translation table. Use null ("") to specify `tableI` or `default`; otherwise this parameter is optional.
string	`tableI`	IN	A variable or literal string searched for in `stringIn`. Use null ("") to specify `default`; otherwise this parameter is optional.
string	`default`	IN	The default character to use. The default is a blank.
string	`stringOut`	OUT	A variable that contains the translated result of `stringIn`.

Examples

Example 1:

@DTW_TRANSLATE("abbc", result)

Returns: result = "ABBC"

Example 2:

@DTW_TRANSLATE("abbc", "R", "bc", result)

Returns: result = "aRR "

Example 3:

@DTW_rTRANSLATE("abcdef", "12", "abcd", ".")

Returns:"12..ef"

Example 4:

@DTW_rTRANSLATE("abbc", "", "", "")

Returns: "abbc"

DTW_UPPERCASE

AIX HP-UX OS/2 OS/390 OS/400 SCO SUN Win NT
X X X X X X X X

Purpose

Returns a string in uppercase.

Format

@DTW_UPPERCASE(stringIn, stringOut)

@DTW_rUPPERCASE(stringIn)

@DTW_mUPPERCASE(stringMult1, stringMult2, ..., stringMultn)

Values

Table 60. DTW_UPPERCASE Parameters

Data Type Parameter Use Description
string stringIn IN A variable or literal string with characters of any case.
string stringOut OUT A variable that contains stringIn with all characters in uppercase.
string stringMult INOUT

On input: A variable that contains a string.
On output: A variable that contains the input string converted to uppercase.

Data Type	Parameter	Use	Description
string	`stringIn`	IN	A variable or literal string with characters of any case.
string	`stringOut`	OUT	A variable that contains `stringIn` with all characters in uppercase.
string	`stringMult`	INOUT	On input: A variable that contains a string. On output: A variable that contains the input string converted to uppercase.

Examples

Example 1:

@DTW_UPPERCASE("Test", result)

Returns: result = "TEST"

Example 2:

@DTW_rUPPERCASE(string1)

Input: string1 = "Web pages"
Returns: "WEB PAGES"

Example 3:

@DTW_mUPPERCASE(string1, string2, string3)

Input: string1 = "This", string2 = "is", string3 = "uppercase"
Returns: string1 = "THIS", string2 = "IS", string3 = "UPPERCASE"

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]