Release 10.1A: OpenEdge Development:
ADM and SmartObjects

> ## {get} and {set} pseudo-syntax for object properties

> Progress supplies a `{get}` and `{set}` pseudo-syntax in the ADM that can be used to access property values. It is implemented using Progress include files named `get` and `set`, located in the `gui` and `tty` directories. This pseudo-syntax makes accessing property values as simple as possible, and it provides transparency to whether a property can be retrieved or set directly, or must be accessed through its `get` and `set` functions. (The normal `.i` extension is removed to make these references look as much like standard syntax as possible.)

> ##### Get include file logic

> The `get` include files use the following logic:

>     {get propname target-variable [ object-handle ] }.

> The `get` syntax first checks to see whether the preprocessor `xp` `propname` exists. If it does, the `get` syntax returns the value in the `TARGET-PROCEDURE`’s ADMProps temp-table into `target-variable`. If the optional `object-handle` is specified, the `get` syntax searches that procedure’s ADMProps temp-table instead of the `TARGET-PROCEDURE`.

> If there is no `xp` `propname` preprocessor constant, the `get` `propname` function is executed in the `TARGET-PROCEDURE` (or in the `object-handle`, if specified).

> This syntax is appropriate as an optimization for super procedures. In your application code, you should invoke the real functions.

> ##### Set include file logic

> The `set` include files operate similarly, as follows:

>     {set propname value [ object-handle ] }.

> If `xp` `propname` is defined, that entry in the `TARGET-PROCEDURE`’s or the `object-handle`’s ADMProps temp-table is set to `value`. If `xp` `propname` is not defined, the `set` `propname` function is executed and passed the `value` (in its native data type) as an input parameter. The function returns `TRUE` or `FALSE`, depending on whether the operation was successful.

> The following example illustrates interpreting the `{get}` logic:

>     {get DataColumns cColumns}.

> How this translates depends on whether DataColumns has an xp preprocessor defined for it. If it does, the statement translates into the actual 4GL code:

>     ASSIGN ghProp = WIDGET-HANDLE(ENTRY(1, TARGET-PROCEDURE:ADM-DATA, CHR(1)))
>          ghProp = ghProp:BUFFER-FIELD(’DataColumns’)
>           cColumns = ghProp:BUFFER-VALUE.

> This retrieves the handle of the ADMProps temp-table buffer for the `TARGET-PROCEDURE` (stored in the procedure’s `ADM-DATA` attribute) and then retrieves the field value using the dynamic `BUFFER-FIELD` attribute.

> If the preprocessor is not defined for DataColumns, the statement translates to the following:

>     cColumns = dynamic-function("getDataColumns":U IN TARGET-PROCEDURE).

> The `ghProp` variable is defined in `smart.i` for use by these include files. The buffer handle of the ADMProps property temp-table record is stored in the `ADM-DATA` procedure property of each SmartObject, so it can be located by these include files. These include files resolve during compilation to a single executable Progress statement, making them extremely fast.

> ##### Using the get and set include files in other Progress code

> You can use the `get` and `set` include files from any Progress code. When you use them either from a SmartObject of a given type or one of its super procedures, the syntax locates and uses the basic properties in the ADMProps property temp-table. If you use the syntax in other Progress application code (for example, in an object of a different type that does not share that property), it will not have a value for the preprocessor index and so will always use the `get` and `set` property functions.

> The `get` and `set` include files are not actual 4GL syntax and represent a fairly small optimization, so you should restrict their use to super procedures and use the standard `get` and `set` function invocations in other Progress application code. Further, any non-Progress code that uses the Open 4GL interfaces will be able to access the property only by invoking the appropriate `get` or `set` functions directly. For this reason, you should always define `get` `propname` and `set` `propname` functions for each basic property intended to be read and written from outside the object’s class. These property functions can simply access the ADMProps value directly.

> ##### Special properties

> In some cases, it is desirable to store a property value in the ADMProps temp-table, to allow direct access to it from its super procedure and elsewhere, but also to have an action of some type take place when the value is set. For example, the `QueryPosition` property holds information about the cursor position of a query (`FirstRecord`, `LastRecord`, and so on). Whenever its value is set, a message must be also `PUBLISH`ed so other objects can react. In cases of this type, you should not define an `xp` `propertyname` preprocessor constant, so the `get` and `set` functions that have the additional behavior will run instead of getting and setting the value directly in the ADMProps temp-table.

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