Release 10.1A: OpenEdge Development:
Progress Dynamics Advanced Development

> ## How objects are instantiated using prepareInstance

> This section outlines the steps necessary to bring a container window or other container object into being at run time using the cached Repository information. If you want to understand more about exactly how containers are created, you can study the relevant code in the ADM2 support procedure `src/adm2/container.p`, as well as the dynamic window procedure `ry/uib/rydyncontw.w`.

> When an object is launched, whether it is by `launchContainer`, `constructObject`, or just from the editor, a Repository Manager function called `prepareInstance` is called from the main block of the base ADM property include file `smrtprop.i.` This is just about the earliest that anything can run in the ADM world, and the call must be as early as possible so that the `ADMProps` temp-table, where all of each object’s attributes are held, is built as soon as possible.

> The `prepareInstance` function attempts to determine the logical name of the object being launched, since this is what is used to retrieve the objects from the Repository. It does this by calling a function called `getCurrentLogicalName` in the procedure that launched the object being run. This function is defined in the Session Manager (which contains `launchContainer`, the primary starting point for objects run from the menu), the dynamic container procedure `rydyncontw`.w, the dynamic viewer `rydynviewv.w`, and the dynamic TreeView `rydyntreew.w`.

> The value returned by `getCurrentLogicalName` can be in one of two forms (errors and blanks excepted):

> - The actual value of the object’s logical name, equivalent to the Repository field `ryc_smartobject.object_filename`.

> - A value in the form of `InstanceId=<value>`.

> If there is a single valid object name, rather than the form `InstanceId=*`, the relevant data is retrieved from either the cache or the Repository, using `cacheObjectOnClient`. Once this data is returned, the ADMProps temp-table is constructed based on the object's attribute buffer.

> The `InstanceID` ADM attribute is set at this point. Each object that is run will have a unique `InstanceID`.

> The reason for the two different forms of the return value of `getCurrentLogicalName` is that when you are instantiating a master object (which would be the container of other objects), the function returns the actual logical object name that you want to retrieve. When you want to retrieve object instances within a container, the function returns the `InstanceId=` form. This is because there might be many records with the contained instance’s logical object name. If a toolbar is placed on many windows, for example, there will be one record for the master and one for each object instance. By contrast, there can only be one record with a particular instance ID (`tRecordIdentifier`).

> Consider a window called `window1`. It contains an SDO called `fullo1` and a browser called `browser1`. If you launch `window1` from a menu, `launchContainer` sets the `CurrentLogicalName` value to `window1` before running the dynamic container object (the procedure `rydyncontw.w`). When `rydyncontw.w` runs, it picks up the logical object name and passes that into the function `cacheObjectOnClient`, which then retrieves into the cache the five sets of object records that make up the window:

> - `window1` itself (the master object).

> - `fullo1` (the master and instance of `fullo1` on `window1`).

> - `browser1` (the master and instance of `fullo1` on `window1`).

> Two standard ADM2 support procedures in the container class have been extended for Progress Dynamics to create dynamic containers from cached Repository data as opposed to simply running static procedure objects, as would be the case with a standard Version 9 ADM2 application. These are `createobjects` and `constructObject`.

> As `window1` in created, the ADM container startup code runs `createobjects`. This procedure has the responsibility of creating the objects that are to appear on `window1`. `createobjects` retrieves the `InstanceID` property of `window1` and then makes sure that the correct `cache_Object` record is available, by calling `getCacheObjectBuffer` and passing in the `InstanceID`. This `InstanceID` is used to build a query to loop through all of the contained instances (... `WHERE tContainerRecordIdentifier = dInstanceID`).

> The framework then runs `constructObject` to construct `browser1` and `fullo1`. The code must make sure that the correct set of attributes is used for the instance of each object on `window1`, so it sets the `CurrentLogicalName` to `Instanceid`= since this is already available.

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