STR

Synopsis

HELP:   String representation of an integer
TYPE:   OBJECT
SYNTAX: STR(CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL,BASE=num/BIN/B02/OCT/B08/DEC/B10/HEX/B16,CASE=UPPER/LOWER,SIGN=IFNEGATIVE/SPACEIFPOSITIVE/PLUSIFPOSITIVE,DIGITS=num,FIXEDLENGTH=num,PADDING=NONE/RIGHT/LEFT,PADCHAR='bin'/BINARY-ZERO/ASCII-BLANK/EBCDIC-BLANK/UTF08-BLANK/UTF16BE-BLANK/UTF16LE-BLANK/UTF32BE-BLANK/UTF32LE-BLANK,GROUPSEPARATOR/MARKER=num/NON/OFF/SYSTEM/PERIOD/COMMA/SPACE/APOSTROPHE,VALUE='str',USEEID,NULLTERM)

Description

Writes a string representation of an integer number, taking an FL5-internal neutral integer representation (produced by a reading counterpart) as input.

The parameter BASE determines the base/radix of the output string. The following numeral systems are supported by the integer converter:

The default base is decimal. Decimal numbers may be positive or negative. For all other bases, only positive numbers are supported. Converting a negative integer number to binary, octal or hexadecimal string results in an error. When BASE is set to hexadecimal, the parameter CASE can be used to control whether upper (A-F) or lower case (a-f) characters are written.

By default, the string is written with the minimum number of characters possible to represent the integer's value in the given base. If the DIGITS parameter is set to a non-zero value, the string will always contain exactly the specified number of digits in the specified base, even if the integer could be represented with fewer digits. The number is padded with leading zeros as necessary. If the number to convert requires more digits to be representable as string, an error occurs. This consequently results in a limitation of the range of valid integer values, which depends on the specified base. Please note, that a potential sign character is not included in the digits count. So if DIGITS=5, then the number -123 gets converted to the string "-00123".

With the SIGN parameter, it is possible to specify if and how a sign character for positive and negative integers is printed, when converting an integer to a decimal string. The following options are available:

If the output string must have a specific length (e.g. to store it in a fixed-length data field), the FIXEDLENGTH field can be set to the desired number of bytes (not characters!). If the integer string is too short, the string is padded with whitespace characters on the left, by default.

The PADDING parameter determines on which side the string is padded. It can be padded at the start or end of the string.

With PADCHAR, the padding character can be changed. The default padding character is the space character in the specified CHRSET. If you specify a custom padding character, the value must be a byte sequence of the padding character in the specified target CHRSET. So, for example, if CHRSET=UTF16BE and the integer string is supposed to be padded with "." characters, PADCHAR must be set to the two bytes sequence of the period character in big endian UTF16. Specified in hex notation, this would be x"002E" (note the x before the quotation marks, which is the marker for hexadecimal notation of a sequence of byte values).

The CHRSET parameter determines the character set of the written string. If no character set is specified, the system's default character set is used. All character sets supported by the character conversion module can be used, including multi-byte charsets.

When using the byte interface (fcbconv()) to convert integers to strings, you have to make sure that the output buffer you provide is of sufficient size to hold the output string. If the buffer is too short, the return code is FLMRTC_LEN and the output buffer size is set to the minimum number of bytes required, allowing you to provide a larger buffer and retry the conversion.

You can also activate null termination of the string by activating the NULLTERM switch. The output length returned by the byte interface does not include the null termination character.

The parameter VALUE specifies the default value of an integer. It is always in local character set and decimal base. If the integer value is equal to the default value, an empty string will be written.

Additionally, you can activate the parameter USEEID (use empty indication). If read integer was an empty string which has now default float value, with USEEID will also write an empty string, instead of default value. If also write default value is set, empty string will only written, is integer value is equal to write default value and read integer was an empty string.

Arguments