ObjectStore Inspector User Guide

Chapter 7 User-Defined Methods

Introduction

User-defined methods allow you to work directly with objects in an ObjectStore database from within Inspector. Specifically, user-defined methods allow you to perform the following operations by invoking the method from within Inspector:

Create ObjectStore objects
Read ObjectStore objects
Update ObjectStore objects
Delete ObjectStore objects

In addition you can use a user-defined method to retrieve sets of ObjectStore objects.

This chapter describes how to work with user-defined methods in Inspector.

In this chapter

This chapter covers the following topics:

User-defined Methods Overview

This section describes the process of using user-defined methods in Inspector.

Defining User-Defined Methods

This section describes the purpose of the user-defined methods supported in Inspector and how to define them.

Purpose

The purpose of the user-defined methods you can invoke through Inspector is defined in the following table.


Method	Purpose
Create	To create a persistent ObjectStore object
Read	To return computed values from a persistent ObjectStore object
Update	To modify a persistent ObjectStore object
Delete	To delete a persistent ObjectStore object
Extent	To retrieve a set of persistent ObjectStore objects

Required Signature

Each user-defined method supported by Inspector has a required signature that must be exposed in order for it to be registered. This section describes those signatures.

Create

static PersistentClass* PersistentClass::methodName(
            os_database* aDB,
            const os_Dictionary<char*, void*>& args
      )

static PersistentClass* PersistentClass::methodName(
            os_segment* aSeg,
            const os_Dictionary<char*, void*>& args
      )

You use the aDB and aSeg arguments to specify information about the persistent storage location to be used.

The args argument can be used to specify arguments to the invoked method. The dictionary key is a mnemonic name for the argument; the dictionary value can be any of the following C++ types:

int* (pointer to a 32-bit integer)
double*
char*
os_collection*
void*

If one of the registered arguments of a create method is of type os_collection*, Inspector builds a transient os_collection and lets you specify any number of persistent objects to populate it. If type void* is one of the method's registered arguments, Inspector allows you to specify one persistent object to define the argument.

The create method cannot delete any key or value specified in the dictionary, and it should return the pointer to the newly created instance if no error conditions are detected (NULL otherwise).

Inspector opens the database in write mode and starts an update transaction before calling the method.

Read

returnType PersistentClass::methodName(void)

where returnType can be any of the following C++ types:

signed/unsigned int
signed/unsigned long
signed/unsigned short
signed/unsigned char
float
double
long double
char *
PersistentClass*
os_Collection<PersistentClass*>*
Any os_collection subclass

After you have registered a read method, Inspector is able to include it in the class instance format and to output the returned values as it would do with any class data member of the same type as the method's return type. Inspector opens the database in MVCC mode and starts a read-only ObjectStore transaction before calling any read method.

If the return value is a pointer to an object, the object itself is deleted by Inspector if the object is transiently allocated.

Update

int PersistentClass::methodName(
            const os_Dictionary<char*, void*>&args
      )

The args argument can be used to specify arguments to the invoked method. The dictionary key is a mnemonic name for the argument; the dictionary value can be any of the following C++ types:

int* (pointer to a 32-bit integer)
double*
char*
os_collection*
void*

If one of the registered arguments of an update method is of type os_collection*, Inspector builds a transient os_collection and lets you specify any number of persistent objects to populate it. If type void* is one of the method's registered arguments, Inspector allows you to specify one persistent object to define the argument.

The update method cannot delete any key or value specified in the dictionary, and it should return a nonzero value if no error conditions are detected (0 otherwise).

Inspector opens the database in write mode and starts an update transaction before calling the method.

Delete

static int PersistentClass::methodName(
            void* anObject
)

The anObject argument is used to specify the pointer to the persistent object that is to be deleted. Inspector assumes that anObject is actually a pointer to an instance of PersistentClass.

The delete method should return a nonzero value if no error conditions were detected (0 otherwise).

Inspector opens the database in write mode and starts an update ObjectStore transaction before calling the method.

Extent

static int PersistentClass::methodName(
            os_database *aDB, os_collection& aCollection
)

The aDB argument is the currently Inspected database. The aCollection is a collection created by Inspector which the user needs to populate.

The extent method should return a nonzero value if no error conditions were detected (0 otherwise).

Inspector opens the database in MVCC mode and starts a read-only ObjectStore transaction before calling the method.

Registering User-Defined Methods

Once you have defined a user-defined method, you need to register it before it can be invoked by Inspector. Registering a method is the process of adding information about the method to Inspector's metaknowledge about the current ObjectStore database.

This section describes how to register and unregister different user-defined method types.

The Register User-Defined Methods Window

You use the Register User-Defined Methods window to register all types of user-defined methods.

The window contains five pages, one for each method type. The main list box displays all the user-defined methods in the DLL schemas associated with the current database that satisfy the signature rules for the type of method you are registering.

Tip: A check mark to the left of the method indicates that the method is already registered.

How to open the window

To open the Register User-Defined Methods window:

Select an instance.
Select Instance | User-Defined Methods | Register from the menu bar.

Alternative: Select User-Defined Methods | Register from the Instance shortcut menu.
The Register User-Defined Methods window appears.

How to Register User-Defined Methods

The basic procedure for registering a user-defined method is the same, regardless of the type. Note that update and create user-defined methods also allow you to define arguments. The procedure for defining arguments is described separately.

To register a user-defined method:

Open the Register User-Defined Methods window.
Click the tab that corresponds to the type of method you want to register.
Select the methods you want to register.

Alternative: You can double-click a single method to register it.
Are you registering either update or create user-defined methods?

If yes, see How to Add Arguments to Update and Create Methods.
If no, go to step 5.
Click the Register button.
To register another type of user-defined method, go to step 2. Otherwise, click OK to close the Register User-Defined Methods window.

How to Add Arguments to Update and Create Methods

When you register update and create user-defined methods, you also need to add the expected arguments and their types to Inspector's metaknowledge. For example, consider the following user-defined create method:

CPerson* CPerson::createPerson(
            os_database * aDB,
            const os_Dictionary<char *, void *> & args)
{
      CPerson* newPerson=new (aDB, get_os_typespec()) CPerson;
      newPerson->set_m_name ((char*)args.pick("name"));
      newPerson->set_m_city ((char*)args.pick("city"));
      int* age=(int*)args.pick("age");
      if(age!=NULL)
            newPerson->m_age=*age;
      return newPerson;
}