Main Table of Contents

Table of Contents

class PtAllSet

PtAllSet: class summary

PtAllSet::PtAllSet()

PtAllSet::~PtAllSet()

PtAllSet::Append()

PtAllSet::Assign()

PtAllSet::BeginCriticalSection()

PtAllSet::Clear()

PtAllSet::Delete()

PtAllSet::EndCriticalSection()

PtAllSet::FindKey()

PtAllSet::GetClassId()

PtAllSet::GetCurrentPos()

PtAllSet::GetDescId()

PtAllSet::GetNum()

PtAllSet::Insert()

PtAllSet::IsAssigned()

PtAllSet::Lock()

PtAllSet::Make()

PtAllSet::Put()

PtAllSet::Query()

PtAllSet::Search()

PtAllSet::Seek()

PtAllSet::SetFilter()

PtAllSet::SetReadAhead()

PtAllSet::SortBy()

PtAllSet::SortByIndex()

PtAllSet::Unget()

PtAllSet::Unlock()

PtAllSet::UnsetFilter()

PtAllSet::UnsetWatch ()

PtAllSet::Watch()

class PtAllSet

When you open a database you need some way of accessing the objects it contains. An AllSet contains all objects of a given class. PTXX declares an AllSet for each persistent class it encounters. You can step through an AllSet sequentially or perform value-based and identity-based queries on it. For instance, if you have Jets in your database you can use the JetAllSet to find the first jet, or you can perform queries on the JetAllSet to find jets with particular characteristics.

This chapter documents the functions for PtAllSet. When PTXX finds a persistent class declaration, it creates a new class to manage the AllSets for that persistent class. The new AllSet class that PTXX generates is derived from PtAllSet. These generated functions are usually the ones you will use.

For instance, JetAllSet is derived from PtAllSet, but it uses only Jet pointers and Jet ondemands, not PtObject pointers or PtOndemand. For instance, PtAllSet has this function:

virtual int PtAllSet::Unget(PtObject* pObj, PtLockSpec* plk = 0,PtWatchSpec* pwatch = 0);

For the Jet class, PTXX generates the following function, substituting a Jet pointer for the PtObject pointer:

virtual int JetSet::Unget(Jet* pObj, PtLockSpec* plk = 0,PtWatchSpec* pwatch = 0);

Please read the chapter "Sets" for general guidelines on declaring and programming with sets. Set declaration syntax is explained in the chapter "The PTXX Precompiler."

PtAllSets are derived from PtObjectSet, and most of the methods you will use are documented more completely under PtObjectSet. Looking for the Get() function? It is a PtObjectSet function, and is documented there.

PtAllSet: class summary

Member functions:

* Dummy function, always returns an error.

PtAllSet::PtAllSet()

Declaration:

Description:

Constructor for PtAllSet. If you do not pass the PtBase* parameter then you must use Assign() to assign the AllSet to a database before you use it.

Parameters

PtAllSet::~PtAllSet()

Declaration:

Description:

Destructor.

PtAllSet::Append()

Declaration:

Description:

Dummy function. Always returns ERR_PT_ILLEGAL_USE. You can not add elements to an AllSet using Append. Instead, use the object's Store() method.

PtAllSet::Assign()

Declaration:

Description:

Assigns the AllSet to a given database. This function assumes that the PtBase pointer is valid, and does not return an error. If this pointer is invalid, this will cause problems when the AllSet tries to access the database.

Parameters

PtAllSet::BeginCriticalSection()

Declaration:

Description:

Enters a critical section local to this object. If the critical section is already in use by a different thread, the function blocks until the other thread calls EndCriticalSection().

This function can be used to serialize access if you are using the same PtAllSet object in different threads simultaneously and you need to call more than one function sequentially. You do not need to call this function if you are using different PtAllSet objects in every thread.

PtAllSet::Clear()

Declaration:

Description:

Dummy function. Always returns ERR_PT_ILLEGAL_USE. You can not clear an AllSet. You must delete elements individually.

PtAllSet::Delete()

Declaration:

Description:

Dummy function. Always returns ERR_PT_ILLEGAL_USE. To delete an object from an AllSet, use the object's Delete() method.

PtAllSet::EndCriticalSection()

Declaration:

Description:

Leaves a critical section local to this AllSet object. After that other threads are able to enter the critical section again.

PtAllSet::FindKey()

Declaration:

Description:

Sets the current position to the first entry at or above the specified key. FindKey() allows you to position quickly to a particular value in a sorted AllSet. It is like positioning using Find(), but instead of positioning to an object with a particular object identity, it positions to an object with a particular indexed value. For instance, if you have an AllSet which is sorted by Name, you could use FindKey() to position to the first entry starting with the name "Marissa". FindKey() is very useful for implementing incremental searches.

Parameters:

Returns:

Discussion:

To use FindKey(), you must first use PtAllSet:: SortByIndex() or PtAllSet:: SortBy() to set a sort order for the AllSet, and the data for your key must have the same type as the index used to sort the AllSet. If the index is a compound index, the data for the key must match the first field in the index, and positioning will be based on the first field.

If the item is found, FindKey() positions to the item. If it is not found, FindKey() returns ERR_PT_KEY_NOT_FOUND and positions just previous to the next greater value. To position to the next greater value, do a Seek() or a Get() with the seek parameters 1 and PtCURRENT. Suppose you have a class called Person which has an index on Person:: Name:

persistent class Person

{

PtString Name;

useindex NameIX;

};

indexdef NameIX : Person

{

Name;

};

In your program, you can take a PersonAllSet, sort it by the name index, and position to the first person whose name is greater than or equal to Marissa:

PersonAllSet allPersons(pObjBase);

int err = allPersons.SortByIndex("NameIX");

check(err);

PtString searchKey = "Marissa";

err = allPersons.FindKey(PtSTRING_T, &searchKey, 1);

check(err);

// The current position is now at the first entry greater than // or equal to Marissa

Limitations:

Wildcards are not supported.

Comparision is limited to the significance of the index being used index. Compound indexes always return ERR_PT_KEY_NOT_FOUND, because they cannot be fully qualified in the argument.

The later two limitations do not apply to PtAllSet::Search().

PtAllSet::GetClassId()

Declaration:

Description:

Returns the PtClassId for the set type itself. For instance, if this set is a PersonAllSet then it would return the PtClassId for PersonAllSet.

PtAllSet::GetCurrentPos()

Declaration:

Description:

Dummy function. Always returns ERR_PT_ILLEGAL_USE. GetCurrentPos() works for PtObjectSets, but not for PtAllSets. Since you often change the position within an AllSet without doing a Seek(), AllSets can not easily return an absolute position - you can use filters to position based on values, or you can access AllSets using indexes in various sort orders, and these indexes are updated every time you do a Store() or Delete(). Therefore, we can not easily put absolute position numbers in our index entries.

PtAllSet::GetDescId()

Declaration:

Description:

Returns the PtClassId for the class contained in the set. For instance, if this set was declared like this:

lset <Person*> PersonSet;

Then it would return the PtClassId for Person. Since sets are polymorphic, the set may contain any object which belongs to a class derived from Person, e.g. Firemen, Programmers, and Morticians.

PtAllSet::GetNum()

Declaration:

Description:

Returns the number of objects in the AllSet.

If you are in a transaction, this will include objects added using a Store() during the transaction and exclude objects deleted with Delete() during the transaction.

PtAllSet:: GetNum() does not work for a filtered set. There is no way to determine the number of matching items without reading through the set.

Returns

PtAllSet::Insert()

Declaration:

Description:

Dummy function. Always returns ERR_PT_ILLEGAL_USE. The only way to add elements to an AllSet is to use the object's Store() method.

PtAllSet::IsAssigned()

Declaration:

Description:

Returns a non-zero value if the PtAllSet has been assigned to a database.

PtAllSet::Lock()

Declaration:

Description:

Locks all the objects in the AllSet. This is the same as PtObjectSet:: Lock(), but the depth mode in the PtLockSpec must always be PtFLAT. Any other depth mode results in an error return without locking any objects. Although locks for objects stack, locks for AllSets do not stack. You may set more than one lock for an AllSet, but no two locks may have the same lock mode and depth.

Locking is an all-or-nothing affair. If POET can not lock all the objects in the set, the whole Lock() will fail without locking anything.

Returns

PtAllSet::Make()

Declaration:

Description:

Creates an object of class PtAllSet which contains all objects of the given class class. If no class with the given name was registered inside the POET dictionary, the function returns a null-pointer.

PtAllSet::Put()

Declaration:

Description:

Dummy function. Always returns an error. You can not replace an element in an AllSet directly.

PtAllSet::Query()

Declaration:

Description:

This function does the same thing as PtObjectSet:: Query(), and is documented in the PtObjectSet class.

PtAllSet::Search()

Declaration:

Description:

Retrieves one object from the AllSet. The search criteria is passed as an argument. You can specify one criteriona for each part of a component index.

Parameters:

Returns:

Limitations:

Wildcards are not supported.

PtAllSet::Seek()

Declaration:

Description:

Sets the current position of the AllSet. When reading objects from the AllSet, it is usually best not to call Seek() explicitly; instead, call Get() with the seek parameters.

Parameters:

Returns

PtAllSet::SetFilter()

Declaration:

Description:

Installs the query specification as a filter. When you retrieve an item from a filtered AllSet, you only see the items which satisfy the query conditions that you specified in the filter. In other words, the AllSet acts as though it were the result set for the query, but instead of performing the query all at once, POET finds each item as you read it from the filtered set. The PtQuery may not contain a SortBy clause. Except for this, you can use any query specification, including nested query specifications. Filters do not nest. An AllSet may only have one filter at a given time. Queries on filtered sets currently ignore the filter entirely and act as though the filter had never been set.

If you have used SortByIndex() to set an order, you can decide if the filter should maintain this sort order. Set the parameter UseCurrentIndex to PtTRUE if you want to keep the sort order. Note, however, that this sort order may force POET to use a sub-optimal search strategy. In general, use this only when you are searching based on the same member or members that you want to sort by.

PtAllSet:: GetNum() does not work for a filtered set. There is no way to determine the number of matching items without reading through the set.

PtAllSet::SetReadAhead()

Declaration:

Description:

Specifies the size of a read-ahead cache which POET will use when reading items for a particular set. It is particularly useful for writing browsers. Note: locks and watches are applied when the object is read using Get(), not when it is read into the cache, so you should be very careful if you use this for applications where you need concurrency control or distributed objects.

PtAllSet::SortBy()

Declaration:

Description:

Choose an indexed data member to determine the sort order of the AllSet. This function is less useful than SortByIndex(), which is the function you probably want to be using for new development.

By default, AllSets are sorted in ascending order using the surrogate, which is equivalent to sorting the objects by the order in which they were first assigned to the database. You can use any index to set a different order. For instance, if you want to access objects sorted by name and your object has a member called LastName then you can set the sort order like this:

// Sort by Person.LastName

PersonAllSet.SortBy("LastName", PtASCENDING);

You can reverse this sort order by using PtDESCENDING:

// Sort by Person.LastName, descending order

PersonAllSet.SortBy("LastName", PtDESCENDING);

The second form of the function does not specify a member name - the surrogate index is implied:

// sort by surrogate, descending order

PeopleAllSet.SortBy(PtDESCENDING);

If the sort order is PtASCENDING, SortBy() seeks to the beginning of the set. If the sort order is PtDESCENDING, SortBy() seeks to the end of the set.

Parameters:

Returns:

PtAllSet::SortByIndex()

Declaration:

Description:

Chooses an index to determine the sort order of the AllSet. SortByIndex() does not actually sort the AllSet, it merely uses the sort order defined by the index. By default, AllSets use the surrogate index, which is equivalent to sorting the objects by the order in which they were first assigned to the database. You can use any index to set a different order. If the sort order is PtASCENDING, SortByIndex() also seeks to the beginning of the set. If the sort order is PtDESCENDING, SortByIndex() seeks to the end of the set.

Parameters:

Returns:

Examples:

If the Person class has an index called TelephoneBookOrderIX then you can set this as the sort order like this:

PersonAllSet AllPersons(pObjBase);

int err = AllPersons.SortByIndex("TelephoneBookOrderIX");

check(err);

PtAllSet::Unget()

Declaration:

Description:

Frees up resources allocated by Get(). .

If you specify only the first parameter, Unget() decrements the link count and removes it from RAM if the resulting link count is zero. If you specify a PtLockSpec or a PtWatchSpec, this should match the PtLockSpec or PtWatchSpec used by the corresponding Get() function; Unget() will then remove the lock or the watch. Future versions of POET may do more. If you want to keep an object in memory you can call the object's Remember() method before calling Unget():

Jet* AnyJet;

WingsAcrossAmerica.JetSet->Get(AnyJet, 0, PtSTART);

DoSomething(AnyJet);

AnyJet->Remember(); // increments link count

WingsAcrossAmerica.JetSet->Unget(AnyJet); // object stays in RAM

. . . // do lots of stuff with object

AnyJet->Forget(); // now I am done with it!

Parameters:

Returns:

PtAllSet::Unlock()

Declaration:

Description:

Unlock the objects in the AllSet. This is the same as PtObjectSet:: Unlock(), but the depth mode in the PtLockSpec must always be PtFLAT.

Returns

PtAllSet::UnsetFilter()

Declaration:

Description:

Removes the current filter from the AllSet.

PtAllSet::UnsetWatch ()

Declaration:

Description:

Unsets a watch on the objects in the AllSet. This is the same as PtObjectSet:: UnsetWatch(), but the depth mode in the PtWatchSpec must always be PtFLAT.

Returns

PtAllSet::Watch()

Declaration:

Description:

Sets a watch on the objects in the AllSet. This is the same as PtObjectSet:: Watch(), but the depth mode in the PtWatchSpec must always be PtFLAT. Any other depth mode results in an error return without setting any watches.

If you are testing for stores, note that PtWATCH_STORE and PtWATCH_UPDATE do not detect when a new object is added to the AllSet. Use PtWATCH_INSERT for this.

If you set a watch on an AllSet, it is not triggered if an object belongs to the same class that the AllSet holds; it is not triggered by objects whose class is derived from it. Therefore, if you want a watch to apply to derived classes, you must also set the watch for the AllSets associated with the derived classes.

Returns

Copyright (c) 1996 POET Software, Inc. All rights reserved. Reproduction in whole or in part in any form or medium without the express permission of POET Software, Inc. is prohibited.