#### 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:

- binary (base 2)
- octal (base 8)
- decimal (base 10)
- hexadecimal (base 16)

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:

- A "-" character is written for negative numbers
- A "-" character is written for negative numbers, a space character for positive numbers
- A "-" character is written for negative numbers, a "+" character for positive numbers

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

- `NUMBER: CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL - Character set [SYSTEM]`
  - `NONE - No character set defined`
  - `SYSTEM - SYSTEM (environment specific (on mainframe EBCDIC else ASCII))`
  - `ASCII - ASCII (mainly used in the for open system)`
  - `UCS1 - UCS-1 (for text formatting identical to ASCII < 64k)`
  - `UTF8 - UTF-8 (for text formatting identical to ASCII < 2M)`
  - `EBCDIC - EBCDIC (mainly used on IBM mainframe)`
  - `UCS2BE - UCS-2 Big Endian (multibyte character set < 64k)`
  - `UTF16BE - UTF-16 Big Endian (multibyte character set < 2M)`
  - `UCS2LE - UCS-2 Little Endian (multibyte character set < 64k)`
  - `UTF16LE - UTF-16 Little Endian (multibyte character set < 2M)`
  - `UCS4BE - UCS-4 Big Endian (multibyte character set < 64k)`
  - `UTF32BE - UTF-32 Big Endian (multibyte character set < 2M)`
  - `UCS4LE - UCS-4 Little Endian (multibyte character set < 64k)`
  - `UTF32LE - UTF-32 Little Endian (multibyte character set < 2M)`
  - `LOCAL - LOCAL (platform specific (on mainframe EBCDIC else ASCII))`
- `NUMBER: BASE=num/BIN/B02/OCT/B08/DEC/B10/HEX/B16 - Base / Radix [DECIMAL]`
  - `BIN - Binary base (2)`
  - `B02 - Base 2 (binary)`
  - `OCT - Octal base (8)`
  - `B08 - Base 8 (octal)`
  - `DEC - Decimal base (10)`
  - `B10 - Base 10 (decimal)`
  - `HEX - Hexadecimal base (16)`
  - `B16 - Base 16 (hexadecimal)`
- `NUMBER: CASE=UPPER/LOWER - Print letters in upper or lower case (for hexadecimal) [UPPER]`
  - `UPPER - Change character to upper case`
  - `LOWER - Change character to lower case`
- `NUMBER: SIGN=IFNEGATIVE/SPACEIFPOSITIVE/PLUSIFPOSITIVE - When/How to print the sign [IFNEGATIVE]`
  - `IFNEGATIVE - Minus for negative values only, no sign if positive`
  - `SPACEIFPOSITIVE - Minus for negative, space for positive values`
  - `PLUSIFPOSITIVE - Minus for negative, plus for positive values`
- `NUMBER: DIGITS=num - Fixed number of digits with preceding zeros`
- `NUMBER: FIXEDLENGTH=num - Pad string to this fixed length in bytes using PADCHAR [variable]`
- `NUMBER: PADDING=NONE/RIGHT/LEFT - Choose padding for variable or fixed-length strings [NONE if variable or LEFT if fixed-length]`
  - `NONE - No padding`
  - `RIGHT - Pad on the right`
  - `LEFT - Pad on the left`
- `STRING: PADCHAR='bin'/BINARY-ZERO/ASCII-BLANK/EBCDIC-BLANK/UTF08-BLANK/UTF16BE-BLANK/UTF16LE-BLANK/UTF32BE-BLANK/UTF32LE-BLANK - Byte array to pad string to a fixed or provided length [system]`
  - `BINARY-ZERO - Padding with 0x00`
  - `ASCII-BLANK - Padding with 0x20`
  - `EBCDIC-BLANK - Padding with 0x40`
  - `UTF08-BLANK - Padding with 0x20`
  - `UTF16BE-BLANK - Padding with 0x0020`
  - `UTF16LE-BLANK - Padding with 0x2000`
  - `UTF32BE-BLANK - Padding with 0x00000020`
  - `UTF32LE-BLANK - Padding with 0x20000000`
- `NUMBER: GROUPSEPARATOR/MARKER=num/NON/OFF/SYSTEM/PERIOD/COMMA/SPACE/APOSTROPHE - Thousand separator [NON]`
  - `NON - Decimal marker are not set`
  - `OFF - Decimal marker are not allowed`
  - `SYSTEM - Use locale dependent separator`
  - `PERIOD - Use period (.) as separator`
  - `COMMA - Use comma (,) as separator`
  - `SPACE - Use space ( ) as separator`
  - `APOSTROPHE - Use apostrophe (') as separator`
- `STRING: VALUE='str' - Default value (decimal) used, to produce an empty string [NONE]`
- `SWITCH: USEEID - Use empty indication, don't print default value if read integer was an empty string [FALSE]`
- `SWITCH: NULLTERM - Ensure null termination of string [FALSE]`