Release 10.1A: OpenEdge Development:
Progress Dynamics Advanced Development

> ## Functions that return field values and attributes

> The `Query` class that supports SDOs provides a large number of functions that you can use to retrieve data values and the properties of those fields.

> ##### column<attribute> functions

> There is a whole set of functions that return individual 4GL attributes from fields in a data object (one for which the `QueryObject` property is `TRUE`, basically SDOs or SBOs).

> These functions are located in an adjunct SDO super procedure called `dataextcols.p`. Both the `query` class and the `data` class have enough supporting functions that the code to support them causes compilation problems in older versions of the Progress 4GL. So the `get` and `set` functions for properties are in separate super procedures called `queryext.p` and `dataext.p,` respectively. In addition, the `dataextcols.p` procedure supports all these special column attribute functions. These are all run along with the standard super procedures `query.p` and `data.p` and made part of the super procedure stack.

> These functions return values in the appropriate data type for the attribute. All the functions have names of column plus the attribute name. The prefix, column, is not entirely appropriate here, because these return field values from the current row in the SDO buffer, not browse column values.

> They take a single input parameter, which is the name of the field. This can be:

> - A simple SDO field name.

> - A field name qualified by `RowObject`.

> - A field name qualified by the database table it is derived from.

> Column attribute functions include:

> - `columnColumnLabel` — Returns the `Column-Label` of the field. Note the word column does appear twice in the function name.

> - `columnDataType` — Returns the data type of the underlying database field represented by this column.

> - `columnDBColumn` — Returns the name of the column in the database, in case it has been renamed in the SDO.

> - `columnDBName` — Returns the name of the database that the field is derived from.

> - `columnHandle` — Returns the handle of the field in the `RowObject` buffer.

> - `columnHelp` — Returns the value of the field’s Help text.

> - `columnInitial` — Returns the field’s initial value.

> - `columnLabel` — Returns the field’s label.

> - `columnModified` — Returns a `LOGICAL` flag indicating whether the field has been modified since it was read into the `RowObject` table.

> - `columnPrivateData` — Returns the Progress `Private-Data` attribute of a specified column.

> - `columnTable` — Returns the name of the database table the column is derived from. It is qualified according to how the SDO is defined.

> - `columnWidth` — Returns the width in characters.

> There are also equivalent `assignColumn``<attribute>` functions for most of these, which take the field name and the attribute value as input parameters.

> There are also a few more specialized column functions that are useful.

> ##### columnQuerySelection

> This `CHARACTER` function, supported for data objects, takes a column name as input and returns a `CHR(1)-`delimited string with all operators and values that have been added to the query for this field using the `assignQuerySelection` method (described later in this chapter). For example, if the query contains `custnum` `>` `5` and`custnum` `<` `9`, this function returns `>|5|<|9` (where `CHR(1)` is shown as |). Use this function to do analysis on the current query or to display information to the user.

> ##### columnValue

> This `CHARACTER` function, supported for data objects, takes the name of the field as input and returns its value, in character form, but without any formatting characters added. This is equivalent to applying the `STRING` function to the `BUFFER-VALUE` of the field.

> ##### columnStringValue

> This `CHARACTER` function, supported for data objects, takes the name of the field as input and returns its `STRING-VALUE`, which is the fully formatted value as it would appear on the screen (so it is the buffer equivalent to the `SCREEN-VALUE` of a displayed field or browse column).

> ##### colValues

> This `CHARACTER` function, supported for data objects, takes as input a comma-separated list of field names in an SDO and returns a `CHR(1)`-delimited list of the formatted values (`STRING-VALUE`s, in effect) for those columns for the current row, preceded by a string called the `RowIdent` that holds the database `RowID` of the record the columns are derived from. If the SDO involves a join, then this first `RowIdent` entry in the list is itself a comma-separated list of the `RowID` values for the records in the join. This is the standard function used internally by viewers in particular to retrieve the values to display as the `SCREEN-VALUE`s of the fields in the viewer.

> Note that because the `RowIdent` is always the first entry in the `CHR(1)`-delimited list, your code must always look for the value for a column that was in the nth position in the input list, in the `n+1`th position in the return value.

> This function can be useful for retrieving multiple values at a time, but the `columnValue` and `columnStringValue` functions were designed for application use as a more convenient way to retrieve individual values at a time.

> ##### colStringValues

> This `CHARACTER` function provides an alternative to `colValues` as a way to retrieve multiple values in a single call, and with flexible formatting. It does not return the `RowIdent` of the database records as `colValues` does. The function takes three `INPUT` parameters:

> - `pcColumnList` — This is a comma-delimited list of `RowObject` column names to return values for.

> - `pcFormatOption` — This parameter allows you to specify the format of returned values. It can be:

> - `Blank` or ? — No formatting is done; unformatted buffer values are returned.
> - `Formatted` — Returned values are formatted according to the `columnFormat` with right-justified numeric values.
> - `TrimNumeric` — Returned values are formatted according to the `columnFormat` with left-justified numeric values.
> - `pcDelimiter` — This optional parameter specifies a delimiter between values; the default delimiter is `CHR(1)`.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095