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.
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 theu-pvars.i
include file in the feature or integration procedure:
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.
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 APIsffire.p
procedure from a feature procedure:
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:
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.
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.
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 |