Table of Contents
Table of Contentsclass PtRootPtRoot is a class which is used to administer the open PtBase objects in your program. It contains a list of all open databases, and will always ensure that each database is opened only once in the program. To make this work, do not call PtBase::Open() or PtBase::Connect() directly; instead, use the function PtRoot::GetBase() to connect to the server and open the database.
In previous versions of POET, databases were created and opened using the PtBase, and there was no PtRoot. The advantage of using a PtRoot is that the PtRoot can ensure that the resources for each PtBase are allocated only - each PtBase you open requires file handles and RAM, and it takes time to open a database. GetBase() makes sure that you do not incur this overhead when you open a database a second time (footnote #1) . You can still open a PtBase the old way, as long as you call InitPOET() first (see the description for PtBase for an example of this).
PtRoot also allows you to install a login function which will be called if you attempt to log in to a database which has user authorization enabled. The function which does this is called PtRoot:: SetUserNameFunction(). Finally, PtRoot allows you to specify a link repair function which will be called if foreign database references can not be resolved. The name of the function which does this is PtRoot:: SetLinkRepairFunction().
footnote #1:
PtRoot: class summary| Files to include | Class declaration | Base class |
| poet.hxx | ptbsroot.hxx | none |
| constructor | PtRoot(); |
| destructor | ~PtRoot(); |
| DeleteUnusedBases | int DeleteUnusedBases(); |
| GetBase | int GetBase(PtString server, PtString database, PtBase*&, PtOpenMode = PtOPEN_RW, PtClassDict* = 0 ); |
| GetConfigFile | inline PtConfig* GetConfigFile(); |
| GetConfigFileName | PtString& GetConfigFileName(); |
| GetDictionary | int GetDictionary(PtString server, PtString name, PtClassDict*& ); |
| GetWorkspace | int GetWorkspace(PtBase* parent, PtString server, PtString name, PtWorkspace*&); |
| IsOpen | PtBool IsOpen(PtDateTime &id, PtBase** pBase = 0); |
| MapName | int MapName(const PtString& sname, const PtString& name, PtString& mappedname); |
| SetConfigFile | void SetConfigFile(PtString&); |
| SetRepairLink | RepairLinkFunc SetRepairLink(RepairLinkFunc newFunction); |
| SetUserNameFunction | UserNameFunc SetUserNameFunction(UserNameFunc newFunction); |
| UngetBase | int UngetBase(PtBase* ); |
| UngetDictionary | int UngetDictionary(PtClassDict* ); |
| UngetWorkspace | int UngetWorkspace(PtWorkspace*); |
PtRoot::PtRoot() - PtRoot::PtRoot()
Constructor. You should not call this constructor directly; instead, you should create one PtRoot using the global function InitPOET(). Once you have done this, you can access the PtRoot using the static function PtBase:: POET().
- InitPOET();
- PtBase* pObjBase;
- PtBase::POET()->GetBase("LOCAL", "base", pObjBase);
- PtRoot::~PtRoot()
Destructor. You should not call this directly. Instead, you should call DeinitPOET().
PtRoot::DeleteUnusedBases() - int PtRoot::DeleteUnusedBases()
Steps through the list of open databases and removes any unused databases from their foreign database tables.
PtRoot::GetBase() - int PtRoot::GetBase(PtString server, PtString database, PtBase*&, PtOpenMode = PtOPEN_RW, PtClassDict* = 0)
Connects to the server and opens the database, setting the PtBase pointer to the address of the resulting PtBase. PtRoot keeps a list of all open databases, and GetBase() never opens a database a second time if the database is already in the list. Instead, it increments a link count for the database and simply sets the PtBase pointer. Therefore, you must call UngetBase() when you are done with the pointer. You should call UngetBase() even if GetBase() returns an error; in order to allow you to examine the PtBase to see what went wrong, POET returns a valid PtBase pointer even if you could not open the database. You can use this to examine the logical and physical database names which were used to try to open the database.
Since PtString has a cast operator, you do not need to cast the parameters to strings.
- PtBase* pObjBase;
- InitPOET();
- int err = PtBase::POET()->GetBase("LOCAL","base",pObjBase);
- if (err < 0)
- {
- PtBase::POET()->UngetBase(pObjBase);
- ErrorExit("Could not open database", err);
- }
// Now you can use the database if no error code was returned. // When you are done with it, remember to call UngetBase()!!! PtBase::POET()->UngetBase(pObjBase); | >0 | Link count for the PtBase |
| ERR_PTC_NOCONNECTION | Unable to connect. The server is down, wrong server name, name resolution for the server is not working, something is wrong with your network installation... |
| ERR_PT_TOO_MANY_USERS | You can not connect because there are too many users on server for your current site license. |
| ERR_PT_NO_DATABASE | The database files could not be found |
| ERR_PT_FACTORY_NOT_FOUND | Could not find the class factory table for your schema. |
| ERR_PT_NO_DICTIONARY | The dictionary could not be found. This can happen if somebody moved the database or the dictionary. |
PtRoot::GetConfigFile() - inline PtConfig* PtRoot::GetConfigFile()
Returns a pointer to the active configuration file object. This object can then be queried to obtain information about the current configuration, such as database mappings.
PtRoot::GetConfigFileName() - PtString& PtRoot::GetConfigFileName()
Returns the filename of the active configuration file. This file contains various parameters, such as database mappings, which can be used to modify the behavior of certain POET functionality.
PtRoot::GetDictionary() - int PtRoot::GetDictionary(PtString server, PtString name, PtClassDict*& )
This function acts just like GetBase(), but instead of setting a pointer to the PtBase for the database, it sets a pointer to the PtClassDict for the dictionary.
PtRoot::GetWorkspace() - int PtRoot::GetWorkspace(PtBase* parent, PtString server, PtString name, PtWorkspace*&)
This function acts just like GetBase(), but instead of setting a pointer to the PtBase for the database, it sets a pointer to the workspace identified by the name parameter.
PtRoot::IsOpen() - PtBool PtRoot::IsOpen(PtDateTime &id, PtBase** pBase = 0)
- PtBool PtRoot::IsOpen(const PtString& name, PtBase** pBase = 0)
- PtBool PtRoot::IsOpen(const PtString& name, int whatKind = PtLOOKUP_BASE|PtLOOKUP_DICTIONARY|PtLOOKUP_WORKSPACE, PtBase** pBase = 0)
- PtBool PtRoot::IsOpen(const PtString& server, const PtString& name, PtBase** pBase = 0)
Returns PtTRUE if the indicated database, dictionary or workspace is currently open, PtFALSE otherwise. The pBase parameter, if provided, will be set to point to the database in question if it is open. The various overloaded versions of this method enable the user to look up an object based on creation time, database name or database and server name. The values PtLOOKUP_BASE, PtLOOKUP_DICTIONARY and PtLOOKUP_WORKSPACE can also be used individually or separately to indicate the type of object which should be searched for.
PtRoot::MapName() - int PtRoot::MapName(const PtString& sname, const PtString& name, PtString& mappedname)
Given a server and database name, sets the value of mappedname to the corresponding mapped database name. This name is built using the database name mappings in the active configuration file. The mapped file name is the name that will actually be used when attempting to open the database. The server name is required since, if the database is not present locally, the server is responsible for mapping the name.
- // Active POET.CFG file contains the following line: // base=c:/mybases/base10
- PtString mappedname;
- int err = PtBase::POET()->MapName("LOCAL","base",mappedname);
- // mappedname is set to "c:/mybases/base10"
- void PtRoot::SetConfigFile(PtString&)
Indicates the name of the file which should be used by POET to get information about the current configuration, such a database name mappings, buffer sizes, etc. This overrides any environment variables which may have to be set to indicate the location of this file.
PtRoot::SetRepairLink() - RepairLinkFunc PtRoot::SetRepairLink(RepairLinkFunc newFunction)
Installs a callback function which will be called if a foreign database can not be found at runtime. This can be used to increase the availability and reliability of an application by making information available on more than one server. For instance, suppose you have an application which accesses information in a remote database which is always kept up-to-date. If you cannot access the server for the remote database then you might be able to find the same information in an older version which resides on a different server.
- PtBase::POET()->SetRepairLink(RepairLink)
A link-repair callback function is a normal C function which takes three parameters:
When POET is unable to resolve a cross-database pointer it calls our function, passing us the name of the server and the database as parameters. The return value from the link repair function tells POET what to do next:
| Return code | Meaning |
| PtEXCIGNORE | Don't try to resolve the reference. Returns ERR_PT_FOREIGN_REFERENCE. |
| PtEXCABORT | Don't try to resolve the reference. Set the reference to 0 and return ERR_PT_FOREIGN_REFERENCE. |
| PtEXCFAIL | Don't try to resolve the reference. Return ERR_PT_NO_DATABASE. |
| PtEXCRETRY | Try again with different names (which our callback function should have provided!). Place the new names in the foreign database table. |
For example, we might check to see if we are trying to access the data entry server; if so, we will change to the backup server and tell POET to try to resolve the reference again.
PtRoot::SetUserNameFunction() - UserNameFunc PtRoot::SetUserNameFunction(UserNameFunc newFunction)
Installs a login function which will be called any time the PtRoot tries to open a database which has user authorization enabled.
- PtBase::POET()->SetUserNameFunction(&MyGetUserName);
A pointer to the previously installed login function.
The login function must fill in the name and password of the user. It does not need to determine if the name and password are correct - POET will do that for you. All your function has to do is fill in the name and password and return PtEXCRETRY to tell POET to see if they are valid. Many user interfaces allow the user to press a cancel button if they realize that they no longer know the password and want to stop trying. If this happens, you should return PtEXCFAIL.
Suppose we have a dialog box with two fields, one for the user name and one for the password, and our dialog box has an OK button and a cancel button. Our login function might look like this:
PtRoot::UngetBase() - int PtRoot::UngetBase(PtBase* )
Returns the PtBase to the PtRoot. The PtRoot keeps a link count for each PtBase; when each GetBase() call is matched by an UngetBase() call, the PtRoot knows when the PtBase is no longer in use. When the PtBase is no longer in use, the PtRoot closes the PtBase and disconnects it from the server.
PtRoot::UngetDictionary() - int PtRoot::UngetDictionary(PtClassDict* )
Returns the PtClassDict to the PtRoot. The PtClassDict is deleted when one UngetDictionary() is done for each GetDictionary() which returned a pointer to this particular PtClassDict.
PtRoot::UngetWorkspace() - int PtRoot::UngetWorkspace(PtWorkspace*)
Returns the PtWorkspace to the PtRoot. The PtWorkspace is deleted when one UngetWorkspace() is done for each GetWorkspace() which returned a pointer to this particular PtClassDict.
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.