DEFINE DATA-SOURCE statement

Defines a data-source object that is created at compile time for use in an external procedure or within a single class or class hierarchy.

Syntax 

 

DEFINE [ PRIVATE | PROTECTED ] [ STATIC ] DATA-SOURCE data-source-name   FOR [ QUERY query-name ]       [ source-buffer-phrase [ , source-buffer-phrase ] ... ]

[ PRIVATE | PROTECTED ] [ STATIC ] DATA-SOURCE data-source-name FOR

Defines and identifies a data-source object 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 data-source as a data element of a method (including constructors, destructors, and property accessors) or a procedure.

Note:

The specified options are applicable only when defining a data member for a class in a class definition (.cls) file. Note also that you cannot shadow (override) the definition of a given data-source data member in a class hierarchy.

PRIVATE data-source data members can be accessed by the defining class. An instance can access a private data-source data member of another instance if both instances are of the same class. PROTECTED data-source data members can be accessed by the defining class and any of its derived classes. An instance can access the protected data-source data member of a second instance of a class that is at the same level or higher in the class hierarchy. The default access mode is PRIVATE.

A data-source 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 data-source 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 data-source 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 data-source data member that is scoped to a single instance of the class where it is defined. ABL creates one copy of the specified instance data-source for each such class instance that you create. You cannot directly reference an instance data-source data member from a STATIC class member definition defined within the same class or class hierarchy.

For more information on accessing data-sources of different access modes and scopes, see the reference entry for Class-based data member access.

Note:

Members of a class are grouped into six namespaces, including buffers/temp-tables, methods, variables/properties/events, ProDataSets, queries, and data-sources. Data-sources defined as members of a class share the same namespace. There can be only one class member in this namespace with a given name.

For more information on where and how to define data members in a class, see the CLASS statement reference entry.

DATA-SOURCE data-source-name FOR

Defines and identifies a data-source object for access only within the current procedure, method of a class (including constructors, destructors, and property accessors), or as a PRIVATE data member of a class.

[ QUERY query-name ]

Specifies a query that defines the buffers for the data-source object. Use this option to override the default query for the data-source object.

You can also use the QUERY attribute to override the default query, or the FILL-WHERE-STRING attribute to override the WHERE clause in the query.

If the data-source is a data member of a class, you must specify the name of a compatible query. Thus, if the data-source is a static data member, the query must also be a static data member; if the data-source is PROTECTED, the query must also be defined as PROTECTED or inherited from a super class; and if the data-source is PRIVATE, the query can be defined as either PRIVATE or PROTECTED.

source-buffer-phrase [ , source-buffer-phrase ] ...

Specifies one or more database or temp-table buffers for the data-source object using the following syntax:

 

buffer-name [ KEYS ( { field1 [ , fieldn ]... | ROWID } ) ]

buffer-name

The name of the database or temp-table buffer. If the data-source is a data member of a class, you must define and specify the name of a compatible buffer data member for the table. Thus, if the data-source is a static data member, the buffer must also be a static data member; if the data-source 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 data-source is a PRIVATE instance data member, you can also specify a default database table buffer; you cannot specify a default database buffer for a data-source data member defined with any other combination of access mode and scope.

Note:

ABL defines the default buffer for every database table that you access in a class as a PRIVATE instance buffer data member.

KEYS ( { field1 [ , fieldn ]... | ROWID } )

Specifies one or more database table fields that constitute a unique key that can be used by the AVM to find a record in the table given a record in the temp-table that uses it as a data source.

The ROWID keyword can occur exactly once in place of a field list to use the ROWID as the key.

Examples 

For examples of data-source definitions and usage, see OpenEdge Development: ProDataSets.

For examples of instance and static data-source data member definitions, see the descriptions of r-CustObj.cls, r-CustObjStatic.cls, and r-CustObjAbstract.cls in the CLASS statement reference entry.

Note 

A data-source can be compile-time defined (often referred to as a static data-source object), where the data-source is defined and created at compile time using this statement, or it can be run-time defined (often referred to as a dynamic data-source object), where the data-source is defined and created at run time using the CREATE DATA-SOURCE statement and data-source object handle operations. A compile-time defined data-source can also be defined as a static data member of a class. In this case, it is a static data-source object that is also a class static data member.

See also 

Class-based data member access, CREATE DATA-SOURCE statement, Data-source object handle, FILL( ) method, FILL-WHERE-STRING attribute, QUERY attribute