Progress
Results Administration
and Development Guide


Accessing and Editing the Current Query

The following sections provide information about how to use the API shared variables and procedures to access and edit information associated with the current query in Results.

Determining the Current View

Use the qbf–module shared variable in your feature and integration procedures to determine and set the current view for the current query in Results. The qbf–module character variable holds one of the characters listed in Table 3–6.

Table 3–6: View Character Codes
Value
Current View
?
No current query or view
b
Browse view
f
Form view
r
Report view
l
Label view
e
Data Export view

When the qbf–module variable contains the unknown value (?), there is no current query or view in the Results application window.

When you set the qbf–module variable in a feature procedure, make sure the output parameter controlling the redisplay of Results is set to TRUE. Consider the following feature procedure:

  DEFINE INPUT PARAMETER args AS CHARACTER NO-UNDO 
  DEFINE OUTPUT PARAMETER winState AS LOGICAL NO-UNDO INITIAL FALSE. 
{aderes/u-pvars.i} 
qbf-module = ?. 
winState = TRUE. 

The last line of this feature procedure sets the winState output parameter to TRUE. This causes the Results window to redraw and display the changed module state when the feature procedure finishes executing.

Determining the Name of the Current Query

The shared variable qbf-name contains the name of the current query in Results. If you set the qbf-name variable in a feature procedure to a query that does not exist in the current query directory, Results creates a new temporary query definition. To save the new query definition permanently in the current query directory, execute the FileSave feature from a feature procedure or choose Query Save while the query is active in Results.

Accessing the Tables and Selection Criteria of the Current Query

Results provides API procedures that retrieve information about the tables in the current query.

The vgtbll.p API procedure retrieves a list of the tables referenced in the current query. Use the following syntax to call the vgtbll.p API procedure from a feature procedure:

RUN aderes/vgtbll.p (OUTPUT tableList). 

The OUTPUT tableList parameter is a string value containing a comma-separated list of table or alias names referenced in the currently active query.

The vgtbli.p API procedure retrieves information about the join and selection criteria for a specified table referenced in the current query. Use the following syntax to call the vgtbli.p API procedure from a feature procedure:

RUN aderes/vgtbli.p (INPUT tableName, OUTPUT refTable, OUTPUT joinTable, 
OUTPUT joinInfo, OUTPUT whereInfo, OUTPUT whereAsk, OUTPUT includeCode, 
OUTPUT result). 

The following list describes the parameters of the vgtbli.p API procedure:

INPUT tableName

A string value representing the name of a table or alias used in the current query.

OUTPUT refTable

If tableName is an alias, this parameter is a string value representing the name of the table associated with the alias. If tableName is an actual table name, this parameter returns the unknown value (?).

OUTPUT joinTable

A string value representing the name of a table to which the table specified with the first input parameter (tableName) is joined.

OUTPUT joinInfo

A string value containing the Progress 4GL statement relating the specified table with another table available in the currently active query.

OUTPUT whereInfo

A string value representing a selection expression in the WHERE clause of the query. This string value does not contain the keyword WHERE and contains only the selection criteria defined explicitly for the query. If this output parameter yields an empty string, there is no WHERE criteria for the corresponding table.

OUTPUT whereAsk

A string value representing the information used to prompt for a WHERE clause value at run time. This is the syntax for the string:

/*dataType,dbField,operator:promptString*/ TRUE 

The database field, the data type of the database field, the operator of the criteria expression, and the prompt string are listed.

OUTPUT includeCode

A string value containing Progress 4GL statements to execute immediately after each record access from the specified table in the current query.

OUTPUT result

A logical value that indicates whether the API procedure executed successfully.

Determining the Query Sort Order

Use the qbf–sortby variable to retrieve and set the sorting information for the current query. The qbf–sortby variable contains BY clauses but does not contain the keyword BY. The list in the qbf–sortby variable has the following form:

SYNTAX
db-name.tbl-name.fld-name [ DESC ] 
[ , db-name.tbl-name.fld-name [ DESC ] ] ... 

The fields are positioned in the list based on sort precedence, with the primary sort field listed first. The letters DESC specified after a field name in the list indicate that the sort order for the field is descending. If the field is an array field, the field name is followed by a number in square brackets (for example, [#], where # is the array element selected for ordering).

Determining the Fields in the Current Query

Results places information about the fields of the current query into several different API shared variables. Many of the API shared variables that store information about the fields of the current query are arrays. In each of these field information arrays, there is one element per field in the current query. Results places information about each field into the field information arrays based on the order in which the fields are added to the current query. You can use a single index value to access information about a particular query field across these arrays. For example, an index value of 3 used with each field information array yields information about the third field added to the current query.

These are the shared variables and arrays that contain information about the fields of the current query:

Determining the Report Format of the Current Query

The vgrpti.p API procedure retrieves report format information associated with the current query. Use the following syntax to call the vgrpti.p API procedure from a feature procedure:

RUN aderes/vgrpti.p (OUTPUT leftOrigin, OUTPUT topOrigin,  
OUTPUT columnSpace, OUTPUT lineSpace, OUTPUT pageLines,  
OUTPUT headSpace, OUTPUT footSpace, OUTPUT pageEject,  
OUTPUT sumReport). 

The following list describes the parameters of the vgrpti.p API procedure:

OUTPUT leftOrigin

An integer representing left margin setting, in characters, from the output origin (page or display window).

OUTPUT topOrigin

An integer representing top margin setting, in characters, from the output origin (page or display window).

OUTPUT columnSpace

An integer representing the number of character units between fields on the report.

OUTPUT lineSpace

An integer representing the number of empty lines between text lines on the report.

OUTPUT pageLines

An integer representing the maximum number of lines allowed on a printed page of the report.

OUTPUT headSpace

An integer representing the number of lines between the report body and the report header.

OUTPUT footSpace

An integer representing the number of lines between the report body and the report footer.

OUTPUT pageEject

A string value containing the name of the report field used for page ejects.

OUTPUT sumReport

A logical value that specifies whether the report is a summary report.

The report view does not have to be active in Results in order to run the vgrpti.p API procedure.

Setting Table Information for the Current Query

The vstbli.p API procedure sets table information associated with the current query. Use the following syntax to call the vstbli.p API procedure from a feature procedure:

RUN aderes/vstbli.p (INPUT tableName, INPUT joinTable, INPUT joinInfo,  INPUT 
whereInfo, INPUT whereAsk, INPUT includedCode, OUTPUT result). 

The following list describes the parameters of the vstbli.p API procedure:

INPUT tableName

A string value representing the name of a table or alias used in the current query. The table name must be fully qualified (for example, db.table.name).

INPUT joinTable

A string value representing the name of the table to which tableName is joined, if any.

INPUT joinInfo

A string value containing the Progress 4GL code defining the join relationship between joinTable and tableName.

INPUT whereInfo

A string value representing a selection expression in the WHERE clause of the query. This string value does not contain the keyword WHERE and contains only the selection criteria defined explicitly for the query.

INPUT whereAsk

A string value representing the information used to prompt for a WHERE clause value at run time. This is the syntax for the string value:

/*dataType,Field,operator:promptString*/ TRUE 

The field, the data type of the field, the operator of the criteria expression, and prompt string are listed.

INPUT includedCode

A string value containing Progress 4GL statements to execute immediately after each record access from the specified table in the current query.

OUTPUT result

A logical value that indicates whether the API procedure executed successfully.

Setting the List of Tables for the Current Query

The vstbll.p API procedure sets the list of tables associated with the current query. Use the following syntax to call the vstbll.p API procedure from a feature procedure:

RUN aderes/vstbll.p (INPUT tableList, OUTPUT result). 

The following list describes the parameters of the vstbll.p API procedure:

INPUT tableList

A string value containing a list of tables to be used in the current query. The table names must be fully qualified (for example, db.table.name).

OUTPUT result

A logical value that indicates whether the API procedure executed successfully.

Setting the Export Format for the Current Query

The vsexpi.p API procedure sets the export format for the current query. Use the following syntax to call the vsexpi.p API procedure from a feature procedure:

RUN aderes/vsexpi.p (INPUT newFormat, OUTPUT result, OUTPUT oldFormat). 

The following list describes the parameters of the vsexpi.p API procedure:

INPUT newFormat

A string value representing the name of the export format to make active for the current query. If the format name is not found in the list of existing formats, it is not set.

OUTPUT result

A logical value that indicates whether the API procedure executed successfully.

OUTPUT oldFormat

A string value representing the name of the old (prior to calling this API) export format. This information can be used to restore the export format to its original state at the end of the feature procedure.

Setting the Report Format for the Current Query

The vsrpti.p API procedure sets the report (page) format for the current query. Use the following syntax to call the vsrpti.p API procedure from a feature procedure:

RUN aderes/vsrpti.p (INPUT newFormat, OUTPUT result, OUTPUT oldFormat). 

The following list describes the parameters of the vsrpti.p API procedure:

INPUT newFormat

A string value representing the name of the page format to make active for the current query. If the format name is not found in the list of existing formats, it is not set.

OUTPUT result

A logical value that signals whether or not the API procedure executed successfully.

OUTPUT oldFormat

A string value representing the name of the old (prior to calling this API) page format. This information can be used to restore the page format to its original state at the end of the feature procedure.

Setting the Label Format for the Current Query

The vslbli.p API procedure sets the label format for the current query. Use the following syntax to call the vslbli.p API procedure from a feature procedure:

RUN aderes/vslbli.p (INPUT newFormat, OUTPUT result, OUTPUT oldFormat). 

The following list describes the parameters of the vslbli.p API procedure:

INPUT newFormat

A string value representing the name of the label format to make active for the current query. If the format name is not found in the list of existing formats, it is not set.

OUTPUT result

A logical value that indicates whether the API procedure executed successfully.

OUTPUT oldFormat

A string value representing the name of the old (prior to calling this API) label format. This information can be used to restore the label format to its original state at the end of the feature procedure.


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