DEFINE { [ [ NEW ] SHARED ] | [ PRIVATE | PROTECTED ] [ STATIC ] }
QUERY query
FOR buffer-name [ field-list ] [ , buffer-name [ field-list ] ] ...
[ CACHE n ]
[ SCROLLING ]
[ RCODE-INFORMATION ]
|
[ PRIVATE
| PROTECTED
] [ STATIC
] QUERY
query
Defines and identifies a query as a data member of a class, and optionally specifies an access mode (PRIVATE or PROTECTED) and scope (instance or STATIC) for that data member. You cannot specify these options when defining a query as a data element of a method (including constructors, destructors, and property accessors) or a procedure. For a data member query, each
buffer-name must be the name of a compatible data member buffer (see the FOR option).
PRIVATE query data members can be accessed only by the defining class. PROTECTED query data members can be accessed by the defining class and any of its derived classes. The default access mode is PRIVATE. When you reference a query from another data member definition (such as a data-source) defined in the same class or class hierarchy, the access mode of the query cannot be more restrictive than the access mode of the referencing data member.
A query defined with the STATIC option is a static data member of the class type for which it is defined and is scoped to the ABL session where it is referenced. ABL creates one copy of the specified class static query on first reference to the class type, and ABL creates only one such copy for any number of instances of the class that you create. You can directly reference an accessible static query data member from any other static or instance class member defined in the same class or class hierarchy.
Without the STATIC option, ABL creates an instance query data member that is scoped to a single instance of the class where it is defined. ABL creates one copy of the specified instance query for each such class instance that you create. You cannot directly reference an instance query data member from a STATIC class member definition defined within the same class or class hierarchy.
FOR buffer-name [ field-list ] [ ,
buffer-name [ field-list ] ] ...
Specifies the buffers to be used by the query, where buffer-name is a table or alternate buffer name. For a shared query, each
buffer-name must be a shared buffer. If the query is a data member of a class, you must specify the name of a compatible buffer. Thus, if the query is a static data member, the buffer must also be a static data member; if the query is PROTECTED, the buffer must also be defined as PROTECTED or inherited from a super class; and if the data-source is PRIVATE, the buffer can be defined as either PRIVATE or PROTECTED. If the query is a PRIVATE instance data member, you can also specify a default database table buffer; you cannot specify a default database buffer for a query data member defined with any other combination of access mode and scope.
Once the query has been defined, you cannot change the buffers that it references, even if the query is closed and re-opened. For example, a buffer, buff1, is created for the Customer table in a DEFINE QUERY or OPEN QUERY for the query, qry1. The query is run and closed. You cannot now DEFINE or OPEN qry1 with buff1 for the item table. You can reuse buffers with CREATE QUERY, but you must re-run QUERY-PREPARE.
The field-list is an optional list of fields to include or exclude when you open the query. This is the syntax for
field-list:
|
Note:
|
Field lists should be used with caution because they can cause unexpected run-time errors. It is possible, for example, that you may have eliminated a field that is required by a new or revised subroutine or trigger. The result can be a run-time error that may be difficult to debug. You can use the -rereadfields startup option if you have unexpected run-time errors resulting from field lists. When an error occurs, the -rereadfields startup option causes the AVM to ignore the field list and to fetch the entire record. Also note that he AVM ignores the FIELDS option for temp-tables.
|
This statement defines a query to retrieve only the name and balance fields from the Customer table:
|
|
Retrieves complete records when you open the query with EXCLUSIVE-LOCK or update any row (such as with a browse). This ensures proper operation of updates and the local before-image (BI) file. For information on the local BI file, see OpenEdge Data Management: Database Administration.
|
Specifies that you can jump to a location within the list of records that satisfy the query by using the REPOSITION statement. If you do not use this option, you can use only the FIRST, NEXT, LAST, and PREV options of the GET statement to navigate within the list. Queries are faster if you do not use this option, but you must specify it to use the REPOSITION statement. For non-OpenEdge databases, if you do not specify SCROLLING, you can only move forward through the list of records using the FIRST and NEXT options of the GET statement.
|
|
A query can be compile-time defined (often referred to as a static query object), where the query is defined and created at compile time using this statement, or it can be run-time defined (often referred to as a dynamic query object), where the query is defined and created at run time using the CREATE QUERY statement and query object handle operations. A compile-time defined query can also be defined as a static data member of a class. In this case, it is a static query object that is also a class static data member.
|
|
|
Specifying a field list (field-list) for buffer-name can increase the performance of remote (network) queries substantially over specifying buffer-name alone.
|
You can use the -rereadfields startup option if you have unexpected run-time errors resulting from field lists. When an error occurs, the
-rereadfields startup option causes the AVM to ignore the field list and to fetch the entire record.
|
|
If you reference an unfetched database field in a query at run time, the AVM raises the ERROR condition. ABL does not perform a compile-time check to ensure that the field is fetched because the compiler cannot reliably determine how a particular record will be read (that is, whether it is retrieved using a FIND statement, retrieved with or without a field list, including additional fields to satisfy join conditions, etc.).
|
|
|
You can specify the Field List Disable (-fldisable) startup parameter to cancel field list retrieval and force the AVM to retrieve complete records. This is a run-time client session parameter that is especially useful for deployed applications whose database triggers are later redefined to reference unfetched fields (raising the ERROR condition). Using -fldisable provides a workaround that allows the application to run (although more slowly) until the application can be fixed.
|
|
|
A ProDataSet data-relation defined with REPOSITION or SELECTION is overridden if a query is defined for a child relation data-source. Normally, if REPOSITION is not specified, the child query selects the children of the parent. But coding a query for the child data-source overrides whether or not a SELECTION or REPOSITION relation mode was defined.
|
Class-based data member access,
CLOSE QUERY statement,
CREATE QUERY statement,
CURRENT-RESULT-ROW function,
DEFINE BROWSE statement,
DEFINE DATASET statement,
GET statement,
NUM-RESULTS function,
OPEN QUERY statement,
REPOSITION statement,
RUN statement
