System Functions
STR( ) Convert Numeric to String
   
Formats
1. Convert Numeric String to ASCII: STR(num[:mask$][,err_val$][,ERR=stmtref])
2. Convert ASCII String to Mask: STR(string$:mask$[,err_val$][,ERR=stmtref])

Where:

err_val$ Error value to return should the conversion fail. String expression. If you omit err_val$ and the conversion fails, ProvideX either reports Error #43: Format mask invalid or returns the value unformatted, depending on your setting for 'FI'.
mask$ Format mask to be used in the conversion process. Max string size 8kb. For a list of valid mask characters, refer to Data Format Masks .
num Numeric value to convert to a character string.
string$ String expression to be processed.
stmtref Program line number or statement label to which to transfer control.
   
Returns String, converted and validated.
   
Description The STR( ) function converts and validates strings. Add a format mask to specify the size and format of the resultant character string.

When a format mask is included, STR( ) returns a string value converted from numeric using the default decimal point and thousands separator set by 'DP' and 'TH'. If the format mask is omitted, 'DP' and 'TH' settings are ignored.

   
See Also 'FI' System Parameter,
'DP'= System Parameter,
'TH'= System Parameter,
Data Format Masks .
   
Format 1 Convert Numeric String to ASCII

STR(num[:mask$][,err_val$][,ERR=stmtref])

Use this format to convert a numeric value to an ASCII character string; e.g.,

Function String value returned
A$=STR(5*6) yields A$="30"
A$=STR(5*6:"000") yields A$="030"
A$=STR(.01:"0.00") yields A$="0.01"
A$=STR(99:"0.00","****") yields A$="****"
   
Format 2 Convert ASCII String to Mask

STR(string$:mask$[,err_val$][,ERR=stmtref])

Use this format to convert and validate a string value based on the format mask (which dictates the size and content of the results) e.g.,

 

Function String value returned
A$=STR("1234567":"000-0000") yields A$="123-4567"
A$=STR("AB":"00","**") yields A$="**"
   
Examples The following will print **OverFlow** if the value is too large for the mask:

x=1234567890.12
PRINT STR(x:"####,##0.00-","**OverFlow**") ! Yields **OverFlow**

If value is too large with pennies, we’ll try it without the pennies, or else print **OverFlow**:

x=1234567890.12
PRINT STR(x:"####,##0.00-",str(x:"####,###,##0","**OverFlow**")) ! Yields 1234,567,890