#### STR

#### Synopsis

    HELP:   String representation of an floating point number
    TYPE:   OBJECT
    SYNTAX: STR(CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL,SIGN=IFNEGATIVE/SPACEIFPOSITIVE/PLUSIFPOSITIVE,INTDIGITS=num,SEPARATOR=SYSTEM/PERIOD/COMMA/APOSTROPHE,FRACDIGITS=num,ROUNDING[=AWAYFROMZERO/NEAREST/TOWARDZERO/ERROR],FIXEDLENGTH=num,PADDING=NONE/RIGHT/LEFT,PADCHAR='bin'/BINARY-ZERO/ASCII-BLANK/EBCDIC-BLANK/UTF08-BLANK/UTF16BE-BLANK/UTF16LE-BLANK/UTF32BE-BLANK/UTF32LE-BLANK,VALUE='str',NULLTERM,USEEID)

#### Description

Writes a string representation of a real number, taking an FL5-internal neutral real number representation (produced by a reading counterpart) as input. The resulting string is in decimal format.

By default, the string is written with the minimum number of characters possible to represent the number's value. If the INTDIGITS parameter is set to a non-zero value, the string will always contain exactly the specified number of digits in the integral portion of the number string, even if the integer part could be represented with fewer digits. The integer portion is padded with leading zeros as necessary. If the number to convert requires more integral digits to be representable as string, an error occurs.

Accordingly, the FRACDIGITS parameter sets the length of the fractional portion to a fixed value. It is padded with zeros on the right as necessary. If there are more than FRACDIGITS fractional digits in the number to be converted, the remaining digits are cut off.

With SEPARATOR, the character separating intral and fractional part can be set to either period or comma. The default depends on the system's locale (e.g. environment variable LC_NUMERIC on Linux).

With the SIGN parameter, it is possible to specify if and how a sign character for positive and negative numbers is printed, when converting a real number 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 number 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 real numbers 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 a real number. This is always in local charset, decimal base and period is the decimal separator. If the the default value is encountered in the data, an empty string is written.

Additionally, you can activate the parameter USEEID (use empty indication). If a float value in the read data is an empty string, it is written out with the default value. With USEEID, an empty string is written instead of default value. If a default write value is also set, empty string is only written, if the float value is equal to default write value and the read float 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: SIGN=IFNEGATIVE/SPACEIFPOSITIVE/PLUSIFPOSITIVE - Define handling of leading sign [IFNEGATIVE]`
  - `IFNEGATIVE - Sign only if a negative value`
  - `SPACEIFPOSITIVE - Use space if a positive value`
  - `PLUSIFPOSITIVE - Use plus if a positive value`
- `NUMBER: INTDIGITS=num - Number of integral digits (before comma)`
- `NUMBER: SEPARATOR=SYSTEM/PERIOD/COMMA/APOSTROPHE - Floating point separator [SYSTEM]`
  - `SYSTEM - Use locale dependent separator`
  - `PERIOD - Use period (.) as separator`
  - `COMMA - Use comma (,) as separator`
  - `APOSTROPHE - Use apostrophe (') as separator`
- `NUMBER: FRACDIGITS=num - Number of fractional digits (after comma) [all digits]`
- `NUMBER: ROUNDING=AWAYFROMZERO/NEAREST/TOWARDZERO/ERROR - Rounding method if fractional digits don't fit [TOWARDZERO]`
  - `AWAYFROMZERO - Round fractional part away from zero (0.1 => 1; -0.1 => -1)`
  - `NEAREST - Round fractional part toward nearest integer (0.1=>0; 0.5=>1; -0.5=>-1)`
  - `TOWARDZERO - Round fractional part toward zero (=cut off) (0.9 => 0; -0.9 => 0)`
  - `ERROR - Return an error instead of rounding a too long number`
- `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 - Character 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`
- `STRING: VALUE='str' - Default value (period) used, to produce an empty string [NONE]`
- `SWITCH: NULLTERM - Ensure null termination of string [FALSE]`
- `SWITCH: USEEID - Use empty indication, don't print default value if read float was an empty string [FALSE]`