Topics

  1. Overview
  2. Handle Generators
    1. Transient handles
    2. Persistent handles
    3. Explicit handles
    4. Named handles
    5. Anonymous handles
  3. Developing custom handle generators

Overview

Object handles are usually generated by the repository during an exoSet(), exoInvoke() or exoCreate() function call. The generated handle is returned to the user for future reference.

exoInvoke() will return a handle under the following conditions:
  • A "key" is provided to the functions call
  • Always during object creation, regardless of whether a key is provided or not. When no key is provided an anonymous handle will be generated.

The repository contains a number of handle generators or algorithms for generating object handles. Users provides the object repository with a key, which is used to select the appropriate generator. Not only does the selected handle generator affect the format of the handle but it can also affect the life cycle of an object.

Custom Excel functions to virtual methods will add a key parameter to the method signature of the function to allow users to store the result of the function in the object repository. See Function Binding for more information.

Handle generators

The various handle types have interact differently with Excel's dependency tree algorithm. For more information, see Excel Dependency Tree.


Transient (? prefix)
Users can generate transient handles by providing any key with a question mark (?) as its first character. Objects with transient handles will be removed from the repository after their first retrieval. Transient handles will be suffixed with a unique hexadecimal number to ensure they are unique.
Example 1
    Key: ?
    Handle: ?:1000F

Example 2
    Key: ?abc
    Handle: ?:1000G


Persistent (! prefix)
Persistent handles will be generated when the user supplies a key that starts with an exclamation mark (!). The fixed handle generator will always generate the same handle for a given key.
Example
    Key: !myHandle
    Handle: !:myHandle


Explicit (# prefix)
The purpose of explicit handles is to allow the user a means to circumvent handle generation for those cases when they need to provide the handle explicitly. When the user supplies a key that starts with an asterisk (#) that key will be used as the corresponding object handle.
Example
    Key: #myHandle
    Handle: #myHandle


Named (no prefix)
When a handle is provided that does not confirm to any of the above definitions, the default handle generator is used. The default handle generator also generate handles that start with a dollar sign ($) and are suffixed with a hexadecimal number but also contain the provided key.
Example
    Key: myKey
    Handle: $:myKey:1000A


Anonymous (no prefix)
Anonymous handles are prefixed with an underscore postfixed with a numeric value that will be incremented every time the handle is accessed.
Example
    Key: null
    Handle: _:1000A

Developing custom handle generators

Developer documentation required.

Last edited Apr 29, 2013 at 11:17 PM by Tjaart, version 13

Comments

No comments yet.