String-handling built-in functions

The string-handling built-in functions simplify the processing of bit, character, graphic, and widechar strings.

The string arguments can be represented by an arithmetic expression that will be converted to string either according to data conversion rules or according to the rules given in the function description.

Table 1. String-handling built-in functions

Function	Description
BIT	Converts a value to bit.
BOOL	Performs Boolean operation on 2 bit strings.
CENTERLEFT	Returns a string with a value centered (to the left) in it.
CENTERRIGHT	Returns a string with a value centered (to the right) in it.
CENTRELEFT	Synonym for CENTERLEFT.
CENTRERIGHT	Synonym for CENTERRIGHT.
CHARACTER	Converts a value to a character string.
CHARGRAPHIC	Converts a GRAPHIC string to a mixed character string.
COLLAPSE	Returns a string that reduces all multiple occurrences of a character to one with the character's leading and trailing instances trimmed.
COPY	Returns a string consisting of n copies of a string.
EDIT	Returns a string consisting of a value converted to a given picture specification.
GRAPHIC	Converts a value to graphic.
HIGH	Returns a character string consisting of n copies of the highest character in the collating sequence.
INDEX	Finds the location of one string within another.
INDEXR	Finds the location of one string within another when the search starts from the right.
LEFT	Returns a string with a value left-justified in it.
LENGTH	Returns the current length of a string.
LOW	Returns a character string consisting of n copies of the lowest character in the collating sequence.
LOWERCASE	Returns a character string with all the characters from A to Z converted to their corresponding lowercase character.
MAXLENGTH	Returns the maximum length of a string.
MPSTR	Truncates a string at a logical boundary and returns a mixed character string.
PICSPEC	Returns a string consisting of a value assumed to have a given picture specification.
REGEX	Searches a string for a match with a regular expression.
REPEAT	Returns a string consisting of n+1 copies of a string.
REPLACE	Returns a string with one or more occurrences of a substring replaced by another substring.
REPLACEBY2	Returns a string with some characters "translated" to a pair of characters.
REVERSE	Returns a reversed image of a string.
RIGHT	Returns a string with a value right-justified in it.
SCRUBOUT	Returns a string with all the characters from a second string removed.
SEARCH	Searches for the first occurrence of any one of the elements of a string within another string.
SEARCHR	Searches for the first occurrence of any one of the elements of a string within another string but the search starts from the right.
SQUEEZE	Returns a string that reduces all multiple occurrences of a character to one.
SUBSTR	Assigns a substring of a string.
TALLY	Returns the number of times one string occurs in another.
TRANSLATE	Translates a string based on two translation strings.
TRIM	Trims specified characters from the left and right sides of a string.
ULENGTH	Returns the number of UTF characters in a CHAR or WIDECHAR string.
ULENGTH8	Returns the length of a CHAR string needed if the UTF characters in a CHAR or WIDECHAR string were converted to UTF-8.
ULENGTH16	Returns the length of a WIDECHAR string needed if the UTF characters in a CHAR or WIDECHAR string were converted to UTF-16.
UPOS	Returns the position of the nth UTF character in a CHAR or WIDECHAR string.
UPPERCASE	Returns a character string with all the characters from a to z converted to their corresponding uppercase character.
USUBSTR	Returns a substring of a UTF string.
USUPPLEMENTARY	Returns the index of the first UTF surrogate pair in a CHAR or WIDECHAR string.
UTF8	Returns a CHAR value that is the UTF-8 equivalent of x.
UTF8STG	Returns the number of bytes that must be present if the input character is the start of a valid UTF-8 character.
UTF8TOCHAR	Returns a CHAR value holding x converted from UTF-8.
UTF8TOWCHAR	Returns a WCHAR value holding x converted from UTF-8 to UTF-16.
UVALID	Indicates if a CHAR or WIDECHAR string contains valid UTF data.
UWIDTH	Returns the width of the nth UTF character in a CHAR or WIDECHAR string.
VERIFY	Searches for first nonoccurrence of any one of the elements of a string within another string.
VERIFYR	Searches for first nonoccurrence of any one of the elements of a string within another string but the search starts from the right.
WHIGH	Returns a widechar string consisting of n copies of the highest widechar ('ffff'wx).
WIDECHAR	Converts a value to a widechar string.
WLOW	Returns a widechar string consisting of n copies of the lowest widechar ('0000'wx).