# System Functions

STR( ) | Convert Numeric to String

## Formats

1. Convert Numeric String to ASCII: | STR(num[:mask$][,err_val$] [ DEFAULT ] [,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, PxPlus either reports Error #43: Format mask invalid or returns the value unformatted, depending on your setting for the 'FI' system parameter.
mask$ | Format mask to be used in the conversion process. Maximum string size 8KB. For a list of valid mask characters, see 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.
DEFAULT | Optional keyword that, when specified, forces the function to use the system defaults for the decimal point (.), currency symbol ($) and thousand separator (,) as opposed to the characters defined by the 'DP', 'CU' and 'TH' system parameters.

(The DEFAULT keyword was added in PxPlus 2014.)

## 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' Ignore Format Mask Error
'DP'= Decimal Point Symbol
'CU'= Currency Symbol
'TH'= Thousands Separator
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.

Example:

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).

Example:

Function | String Value Returned
A$=str("1234567":"000-0000") | Yields A$="123-4567"
A$=str("AB":"00","**") | Yields A$="**"

## Example

The following example will print **OverFlow** if the value is too large for the mask:

> x=1234567890.12
> print str(x:"####,##0.00-","**OverFlow**") ! Yields **OverFlow**

If the value is too large with pennies, 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