Progress
Results Administration
and Development Guide


API Basics

The Results API consists of a set of shared variables and a procedural interface. The following sections provide basic information about how to access the shared variables and procedures of the Results API in a feature or integration procedure.

Accessing Shared Variables

Results establishes and maintains a set of shared variables, called API shared variables, that you can access and set from a feature or integration procedure. API shared variables provide information about the current state of the Results application and the current query in Results. Table 3–2 provides summary information about the API shared variables available in Results.

Table 3–2: API Shared Variables
Shared Variable
Name
Data Type
Extent
Description
qbf–vers
CHARACTER
N/A
A version number for the current installation of Results.
qbf–module
CHARACTER
N/A
A character code representing the current Results view.
qbf–name
CHARACTER
N/A
The name of the current query in Results.
qbf–sortby
CHARACTER
N/A
A comma-separated list of field names to sort by. The fields are listed by precedence in the sort.
qbf–count
INTEGER
N/A
An integer representing the number of records returned by the current query.
qbf–governor
INTEGER
N/A
An integer representing the number of records to process in report, label, and export views. Zero (0) processes all records.
qbf–rc#
INTEGER
N/A
The number of fields (database, calculated, and arrays) in the current query.
qbf–rcn
CHARACTER
64
The name of each field in the current query and additional expression information.
qbf–rcc
CHARACTER
64
Information about each calculated field and stacked array in the current query.
qbf–rcg
CHARACTER
64
Information about aggregate fields in the query.
qbf–rcl
CHARACTER
64
Labels for each field in the current query.
qbf–rcf
CHARACTER
64
Formats for each field (database or calculated) in the current query.
qbf–rcp
CHARACTER
64
A comma-separated list of values for each field representing layout information for the field in a report, form, and label views.
qbf–rcw
INTEGER
64
The width in characters for each field in a report view of the current query.
qbf–rct
INTEGER
64
Data type identifiers for each field in the current query. The integer identifier corresponds to a list entry in the qbf–dtype shared variable.
qbf–dtype
CHARACTER
N/A
A comma-separated list of data types.

To access these API shared variables in a feature or integration procedure, you must define them in your procedure. Typically, you use the DEFINE SHARED VARIABLE statement to define a previously established shared variable for use in a procedure. However, Results provides the u-pvars.i include file to define the API shared variables for you. Use the following syntax to reference the u-pvars.i include file in the feature or integration procedure:

{aderes/u-pvars.i} 

Once you reference this include file at the top of your procedure, you can access any of the API shared variables. For more information about referencing include files see the Progress Language Reference. See the "Accessing and Editing the Current Query" section in this chapter for more information on how to use the API shared variables in a feature or integration procedure.

Using the Procedural Interface

Results provides an interface that allows you to manipulate Results queries and execute Results features from a feature or integration procedure. The procedure interface consists of six API procedures. All of the API procedures are located in the procedure library in the $DLC/gui directory. Table 3–3 provides summary information about the API procedures available for Results.

Table 3–3: API Procedures 
API Procedure
Description
aderes/sffire.p 
Executes a feature defined in Results from a feature or integration procedure.
aderes/vgrpti.p 
Retrieves report information. This procedure returns information about the format of a report.
aderes/vgtbll.p 
Retrieves the table list of the current query in Results.
aderes/vgtbli.p 
Retrieves table information. This procedure accesses the join and selection criteria associated with a specified table in the current query in Results.
aderes/vstbll.p 
Sets the table list for a new current query in Results.
aderes/vsrpti.p 
Sets page size for the current query.
aderes/vstbli.p 
Sets the table information associated with the current query.
aderes/vsexpi.p 
Sets the export format for the current query.
aderes/vslbli.p 
Sets the label format for the current query.

To use these API procedures in a feature procedure:

For more information, see the RUN Statement and DEFINE VARIABLE Statement in the Progress Language Reference.The following sections of this chapter describe how to use the different API procedures in a feature procedure.

Executing a Feature from a Feature Procedure

The API sffire.p procedure executes a feature from a feature procedure. With this capability, you can use features in Results as building blocks for other features. Use the following syntax to call the API sffire.p procedure from a feature procedure:

SYNTAX
RUN aderes/sffire.p 
( INPUT featureId , INPUT args, OUTPUT result ) . 

The following list describes the parameters associated with the API sffire.p procedure:

INPUT featureId

A string value representing the name of a feature as defined in Results. For information about Results features, see Appendix A, “Results Features.”

INPUT args

A string value representing one or more arguments passed to the specified feature. Specify multiple arguments as a comma-separated list. If the feature specified does not take arguments, pass the unknown value (?) for this parameter. For information about arguments for Results features, see "Results Features."

OUTPUT result

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

If you use the sffire.p API procedure in a feature procedure, you must define a variable for the result output parameter, as shown in the following example:

  DEFINE VARIABLE result AS LOGICAL NO-UNDO. 
                    . 
                    . 
                    . 
RUN aderes/sffire.p (INPUT "FileOpen", INPUT ?, OUTPUT result). 

In this example, FileOpen is a feature that does not take an argument list. If Results can execute the FileOpen feature, the OUTPUT parameter result returns a TRUE value.

Table 3–4 lists several Results features that you can use with the API sffire.p procedure. These features are important for developing other feature and integration procedures.

Table 3–4: Important Results Features 
API Feature
Argument
Description
AdminProgInitialize
None
Clears all information from the API shared variables.
AdminProgInstantiate
None
Initializes any unset API shared variables with valid default values.
AdminProgWrite4GL
proc-name,format
Generates 4GL code for the current query and view, placing the source in the file specified with the proc-name argument. The format argument must be the character g or r. The character g generates stand-alone code. The character r generates code dependent on the Results application.

For information about additional features in Results, see "Results Features."

Testing the Results Version Number

The API shared variable qbf–vers contains a string value representing the Results product version number. The product version number consists of two digits separated by a decimal point, and followed by a letter (for example, 9.1A). Check the version number to verify that the environment you used to develop your feature and integration procedures matches the version of Results at the end-user site.

If the versions do not match, API changes between Results versions could cause erratic behavior. Feature and integration procedures that access API shared variables and procedures might yield error messages. Table 3–5 lists some of the error messages that can result from a change to the Results API between versions.

Table 3–5: The Results API and Error Messages 
Error Message
Possible Problem
** "aderes/proc-name" 
was not found. (293) 
The API procedure referenced in a feature or integration procedure is no longer supported in the current version of Results.
** Unknown Field or 
Variable name - 
var-name. (201) 
The API shared variable referenced in a feature or integration procedure is no longer supported in the current version of Results.
Mismatched parameter 
types passed to 
procedure proc-name. 
(3230) 
The parameters required by an API procedure are different in the current version of Results.
Procedure proc-name sent 
sub-procedure proc-name 
mismatched parameters. 
The parameters required by an API procedure are different in the current version of Results.

These errors can prevent the feature or integration procedure from executing. To avoid this problem, rebuild your application. See "Administering Results," for more information about rebuilding an application.


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