STR

Convert Numeric to String Value

This string function converts a numeric value into a formatted string.

Syntax

STR (numeric-value[:format-mask][,ERR=line-ref|,ERC=error-code])

STR (numeric-value,NTP=numeric-type,SIZ=number-bytes
[,ERR=line-ref|,ERC=error-code])

numeric-value: is any number.
format-mask: is a string value that serves as the mask to be used in forming the result of this function.
numeric-type: is the data type accepted as valid input to a numeric data element.
number-bytes: is byte storage size.
line-ref: is the program line number or label to branch to if an error is produced by this function.
error-code: is a programmer-defined error code. Valid values are positive or negative whole numbers.

Remarks

If a mask is specified that is too small for the numeric value, and the ERR=line-ref option is included, an ERR=43 results. In other cases, the mask is ignored.

The SIZ= parameter enables you to specify the number of bytes in which the number will be stored.

The SIZ= parameter enables you to specify precision, which causes rounding to occur prior to converting a numeric value to a string. Valid values are .01 through .15, which specify precision of 0 through 14.

A change was made in release 8.8.3 to align the decimal point when NTP= is 0, 1, or 2. If the number of decimal places in the result is less than the precision value, the result will be shifted left and trailing zeros added. This change also affects numeric types 0, 1, and 2, and date type 8 in a FORMAT. PRM SHORTDEC disables the change.

Valid numeric types are as follows:

NTP	Description and Maximum Storage Size
0	Fixed point positive/negative numbers: 16
1	Fixed point positive numbers: 16
2	Fixed point negative numbers: 16
3	Binary positive/negative numbers: 8
4	Binary positive numbers: 8
5	Binary negative numbers: 8
6	Packed decimal numbers: 6
7	Informix decimal numbers: 8
8	IEEE single precision floating point: 4 (only)
9	IEEE double precision floating point: 8 (only)
10	BCD signed: 8
11	BCD unsigned: 8
12	BCD no sign byte: 7
13	ASCII sign stored in the high four bits of last byte: 14
14	ASCII sign leading separate: 15
15	ASCII sign trailing separate: 15

Numeric types 3, 4, 5, 6, 10, 11, 12, 13, 14 and 15 are decimal implied. The decimal is not stored, but calculated for input and output based on the Dictionary-IV format definition.

Data files storing numeric values using types 8 and 9 may not be portable from one environment to another. The storage of a number on one environment may be physically backward for another. You may use PRM IEEESWAP in order to reverse the natural ordering of the bytes. This is helpful when WRITEing files with IEEE numbers on one machine, and READing the file on another machine that has the reverse byte ordering. This parameter may be deactivated.

Please refer to the section on Converting Numeric Data to String Data in the chapter on Data Representation in Volume I for a complete discussion of the masking characters and operation of the STR function.

Examples

PRINT STR(-12345.67:"-###,###,##0.")

produces “ -12,346” (rounding occurs).

PRINT STR(-1*8005551212:"(000)B000-0000")

produces “(800) 555-1212”.

PRINT STR(91234567890:"FSNB0NB000000B0000")

produces “FSN 9N 123456 7890”.

PRINT HTA(STR (12345, NTP=6, SIZ=3))

produces 02182E.

PRINT HTA(STR (12345, NTP=10, SIZ=3))

produces 12345C.

PRINT STR(12345, NTP=15, SIZ=6)

produces 12345+.

PRINT STR(9.123, NTP=1, SIZ=8.05)

If PRM SHORTDEC is used produces 9.123 otherwise produces 9.1230.

STR

Syntax

Remarks

Examples

See also