Table of Contents
Table of Contentsclass PtQueryPtQuery is the base class from which all PTXX-generated query classes are derived, and it contains functions like OpenBracket(), CloseBracket(), and SetBoolOp() which are frequently used when specifying queries. The query specification functions generated by PTXX make calls directly to PtQuery functions like PutMember(), PutObjId(), and PutSortMember(); these functions are documented here, but most programs will not want to call them directly.
Instead, you will use the query specification functions which PTXX generates for your classes. These are documented in the chapter "PTXX-generated classes" in this reference guide, or in the chapter "Queries" in the programmer's guide.
PtQuery: class summary| Files to include | Class declaration | Base class |
| poet.hxx | ptquery.hxx | (MemQueue) |
| constructor | PtQuery(PtQueryType = PtINFIX, dword ID = 0); |
| destructor | virtual ~PtQuery(); |
| Clear | void Clear(); |
| CloseBracket | int CloseBracket(); |
| GetClassId | virtual PtClassId& GetClassId() = 0; |
| GetType | inline PtQueryType* GetType(); |
| Next | inline PtQuery* Next(); |
| OpenBracket | int OpenBracket(); |
| PutMember | int PutMember(PtClassId&, word memberpos, PtTypeId, word numarrayelm, void* value, PtCmpOp opcode,dword val = 1l, PtCmpOp op = 0); |
| PutObjId | int PutObjId(PtClassId& , word memberpos, word numarr, PtOnDemand& oid, dword val = 1l, PtCmpOp op = 0); |
| PutSortMember | int PutSortMember(PtClassId& , word memberpos, PtTypeId, word numarrayelm, PtSortOp order); |
| PutSubQuery | int PutSubQuery(PtClassId& , word memberpos, PtQuery* , dword val = 1l, PtCmpOp op = 0, PtClassId* pQClid=0); |
| Rewind | void Rewind(); |
| SetBoolOp | int SetBoolOp(PtBoolOp opcode); |
| SetConstant | int SetConstant(bool); |
PtQuery::PtQuery() - PtQuery::PtQuery(PtQueryType = PtINFIX, dword ID=0)
Constructor. In general, you will not create a PtQuery directly, but will call the constructor for a PTXX-generated query class. This is a pure virtual function, so you can not call it directly.
Queries may use either infix or prefix form. If you specify queries using the generated query specification classes, all queries are in infix form, but they are translated to prefix form in the POET engine.
| PtQueryType = PtINFIX | PtINFIX or PtPREFIX. |
| dword ID=0 | Query identifier. Please do not specify this parameter, the default is what you need. |
PtQuery::~PtQuery() - virtual PtQuery::~PtQuery()
- void PtQuery::Clear()
Clears the query specification; after this function is called, the query specification is empty and you can use the PtQuery to formulate a new query.
PtQuery::CloseBracket() - int PtQuery::CloseBracket()
OpenBracket() and CloseBracket() are used to specify the precedence for queries. CloseBracket() closes a "parentheses" which was opened with OpenBracket().
PtQuery::GetClassId() - virtual PtClassId& PtQuery::GetClassId() = 0
Returns the PtClassId for the PtQuery - this is the class for which the query specification describes; e.g., for a PersonQuery, this would be the PtClassId for Person.
PtQuery::GetType() - inline PtQueryType* PtQuery::GetType()
Returns the query type, which will be PtINFIX or PtPREFIX.
PtQuery::Next() - inline PtQuery* PtQuery::Next()
If a query has sub-queries, all sub-queries are placed in one linear linked list, which is transformed to a tree before the query is processed. You can use this function to traverse the linked list by starting with the highest level query and calling the Next() function. Next() returns 0 if there are no more sub-queries.
This function may be useful if you are allocating sub-queries on the heap and need to find all sub-queries in order to delete them. To do this, start with the highest-level query, and always get the next query before deleting the current one.
PtQuery::OpenBracket() - int PtQuery::OpenBracket()
OpenBracket() and CloseBracket() are used to specify precedence for queries. Open Bracket opens a "parentheses". See the chapter on Queries in the Programmer's Guide for details.
PtQuery::PutMember() - int PtQuery::PutMember(PtClassId& , word memberpos, PtTypeId,word numarrayelm, void* value, PtCmpOp opcode,dword val = 1l, PtCmpOp op = 0)
This function specifies a value for a data member comparison. It is called by the PTXX-generated query specification functions - you should not normally call this function directly.
| PtClassId& | The class in which this member is declared. |
| word memberpos | The member position within the class in which the member is declared. |
| PtTypeId | The type identifier (e.g. PtSTRING_T, PtCHAR_T). See PtTypeId for a complete list of C++ and Type Manager types. |
| word numarrayelm | The number of array elements; if the member is not an array, this should be 1. |
| void* value | Pointer to the data to which these data members should be compared. The PtTypeId is used to interpret the type of this data. Should be zero if you only want to test the number of elements in a set. |
| PtCmpOp opcode | The comparison operator (e.g. PtEQ, PtGT). See PtCmpOp for a complete list of PtCmpOps. |
| dword val = 1l | This parameter and the next are used to specify counting conditions for the query. This parameter tells the number of set or array elements which must meet the conditions specified in the PtQuery. If the data member is not a set or array, this parameter should be 1. |
| PtCmpOp op = 0 | The comparison operator for the counting condition (e.g. PtEQ, PtGT). See PtCmpOp for a complete list of PtCmpOps. |
| 0 | Success. |
| non-zero | Invalid specification. |
PTXX calls this function to specify conditions based on the data members of each class. For example, when it encounters the following class declaration:
PTXX generates this query specification function:
PtQuery::PutObjId() - int PtQuery::PutObjId(PtClassId& , word memberpos, word numarr, PtOnDemand& oid, dword val = 1l, PtCmpOp op = 0)
- int PtQuery::PutObjId(PtClassId& , word memberpos, word numarr, PtObject* oid, dword val = 1l, PtCmpOp op = 0)
Each of these is described separately below.
- int PtQuery::PutObjId(PtClassId& , word memberpos, word numarr, PtOnDemand& oid, dword val = 1l, PtCmpOp op = 0)
Specifies conditions based on pointers, references, or ondemands to other objects. There are two versions of the PutObjId() function: this one takes a pointer to an ondemand which references the object, and the other takes a pointer to an instance of the object. PutObjId() is called by the PTXX-generated query specification functions - you should not normally call this function directly.
| PtClassId& | The class in which this member is declared. |
| word memberpos | The member position within the class in which the member is declared. |
| word numarr | The number of array elements; if the member is not an array, this should be 1. |
| PtOnDemand& oid | An ondemand containing a reference to the object identity which is to be sought. |
| dword val = 1l | This parameter and the next are used to specify counting conditions for the query. This parameter tells the number of set or array elements which must meet the conditions specified in the PtQuery. If the data member is not a set or array, this parameter should be 1. |
| PtCmpOp op = 0 | The comparison operator for the counting condition (e.g. PtEQ, PtGT). See PtCmpOp for a complete list of PtCmpOps. |
| 0 | Success. |
| non-zero | Invalid specification. |
PTXX uses this to specify conditions based on pointers, references, or ondemands to other objects. For instance, when it encounters the following class declaration:
PTXX generates this query specification function:
- int PtQuery::PutObjId(PtClassId& , word memberpos, word numarr, PtObject* oid, dword val = 1l, PtCmpOp op = 0)
Specifies conditions based on pointers, references, or ondemands to other objects. There are two versions of the PutObjId() function: this one takes a pointer to the object, and the other takes a pointer to an ondemand which references the object. PutObjId() is called by the PTXX-generated query specification functions - you should not normally call this function directly.
| PtClassId& | The class in which this member is declared. |
| word memberpos | The member position within the class in which the member is declared. |
| word numarr | The number of array elements; if the member is not an array, this should be 1. |
| PtObject* oid | A pointer to an instance of this object. The object identity will be extracted from the object for the query specification. |
| dword val = 1l | This parameter and the next are used to specify counting conditions for the query. This parameter tells the number of set or array elements which must meet the conditions specified in the PtQuery. If the data member is not a set or array, this parameter should be 1. |
| PtCmpOp op = 0 | The comparison operator for the counting condition (e.g. PtEQ, PtGT). See PtCmpOp for a complete list of PtCmpOps. |
| 0 | Success. |
| non-zero | Invalid specification. |
PTXX uses this to specify conditions based on pointers, references, or ondemands to other objects. For instance, when it encounters the following class declaration:
PTXX generates the following query specificaiton function:
PtQuery::PutSortMember() - int PtQuery::PutSortMember(PtClassId& , word memberpos, PtTypeId,word numarrayelm, PtSortOp order)
Specifies the sort order for the result set of a query. This function is called by the PTXX-generated SortBy() functions - you should not normally call this function directly.
| PtClassId& | The class in which this member is declared. |
| word memberpos | The member position within the class in which the member is declared. |
| PtTypeId | The type identifier (e.g. PtSTRING_T, PtCHAR_T). See PtTypeId for a complete list of C++ and Type Manager types. |
| word numarrayelm | The number of array elements; if the member is not an array, this should be 1. |
| PtSortOp order | PtASCENDING or PtDESCENDING |
| 0 | Success. |
| non-zero | Invalid specification. |
PTXX uses this to create SortBy() functions for generated query classes. For instance, when PTXX encounters the following class declaration:
It generates this SortBy() method for the class:
PtQuery::PutSubQuery() - int PtQuery::PutSubQuery(PtClassId& , word memberpos, PtQuery* , dword val = 1l, PtCmpOp op = 0, PtClassId* pQClid=0)
Specifies query conditions for nested queries. This function is called by the PTXX-generated query specification functions - you should not normally call this function directly
| PtClassId& | The class in which this ondemand, pointer, or reference is declared. |
| word memberpos | The member position within the class in which the above member is declared. |
| PtQuery* | A PtQuery which contains the query specification to be applied to the referenced class. May be zero if you only want to test the number of elements in a set. |
| dword val = 1l | This parameter and the next are used to specify counting conditions for the query. This parameter tells the number of set or array elements which must meet the conditions specified in the PtQuery. If the data member is not a set or array, this parameter should be 1. |
| PtCmpOp op = 0 | The comparison operator for the counting condition (e.g. PtEQ, PtGT). See PtCmpOp for a complete list of PtCmpOps. |
| PtClassId* pQClid=0 | Internal. Use the default parameter. |
| 0 | Success. |
| non-zero | Invalid specification. |
PTXX uses this to specify nested query conditions for generated query specification classes. For instance, given the following class declaration:
PTXX generates the following function to specify query conditions based on the member PointerToPersistent:
PtQuery::Rewind() - void PtQuery::Rewind()
Rewinds a query. You should not normally need to call this function. Once a query specification has been used, it must be rewound before it can be used again, but the Query() function does this automatically.
PtQuery::SetBoolOp() - int PtQuery::SetBoolOp(PtBoolOp opcode)
Sets a boolean operation for combining conditions. A PtBoolOp may be PtAND, PtOR, PtXOR, PtNOT, PtNAND, PtNOR, or PtNXOR. See PtBoolOp for details.
| 0 | Success |
| non-zero | Error |
- PersonQuery MyQuery; MyQuery.SetName ("Le*ers", PtEQ); MyQuery.SetBoolOp (PtOR); MyQuery.SetContact ("Le*ers", PtEQ);
- int PtQuery::SetConstant(bool)
Sets a flag which determines whether an empty query matches all entries for the class or no entries for the class.
| bool = PtTRUE | PtTRUE | An empty query should match all objects of the class - this is the default behavior. |
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.