Xbasic

SQL::Row::FormatData Function

Syntax

Formatted_Data as C = FormatData(ColumnIndex as N | ColumnName as C | Definition as SQL::DataTypeInfo [, FormatName as C][, UserContext as P])

Formatted_Data as C = <SQL::Row>.FormatData( ColumnIndex as N | ColumnName as C | <Definition> as SQL::DataTypeInfo [, DisplayFormat as C [, UserContext as P ]] )

Arguments

Formatted_Data

A string representation of a data value in a result set row.

SQL::Row

A SQL::Row object created with a DIM statement.

ColumnIndex

The number of the column in the selected table.

FormatName

The name of the field in the selected table.

Definition

Optional. A SQL::DataTypeInfo object created with a DIM statement.

DisplayFormat

Optional.

UserContext

Optional. The user context is passed into the evaluation of the expression when data is formatted.

Description

Format the data for the column name, index or definition specified.

Discussion

The SQL::Row.FormatData() method returns a string representation of a data value in a result set row depending on the contents of the two properties (see below). The FormatData() method works as follows.

1. If the caller requests a format, FormatData()looks to see if the format is defined. If so, it evaluates the right-hand-side expression and returns the result.
2. If the caller does not request a format, and a default (unnamed format) exists, FormatData()evaluates the default expression and returns the result.
3. If the type of the data is numeric and a DisplayFormat is defined, FormatData()uses that format when calling the str() function.
4. If no condition above is satisfied, FormatData()converts the value to the default string format and returns the result.
Property
Description
.NamedFormatExpressions

This property is a CR-LF delimited list of Xbasic expressions. One of those expressions can be unnamed, subsequent expressions should be prefixed with ?<name>=?. The Xbasic expression part of each line is executed in the context of a generated function that has three arguments:

Argument
Description
.CurrentRow

SQL::Row

.ColumnDefinition

SQL::DataTypeInfo

.Context

This value is provided by the caller and typically will be a dot variable with additional contextual information required by the expression.

.DisplayFormat

Used to specify a numeric format (where appropriate) using the values you would pass to the Xbasic str() function.

.ExternalFileNameExpression

If this string is defined when FormatData()is called:

1. FormatData()evaluates this expression to get the name of the file to create.
2. FormatData()stores the data in the file named by the expression. If the data is binary, the function stores it in binary form. The function stores all other values in string form.

See Also