PIClass_getLibrary
PIClass_load
PIClass_lookup
PIClass_lookupOrLoad
PIConfigString_getString
PIConfig_findConfiguration
PIConfig_loadConfigurationFile
PIConfig_lookupTree
PIConfig_lookupValue
PIDBEx_new
PIDBIterator_atValidElement
PIDBIterator_current
PIDBIterator_delete
PIDBIterator_next
PIDBIterator_removeCurrent
PIDB_add
PIDB_delete
PIDB_getFastKey
PIDB_getIterator
PIDB_getParent
PIDB_getRoot
PIDB_lookup
PIDB_new
PIDB_pidbflagsNameToNumber
PIDB_pidbtypeNameToNumber
PIDB_replace
PIIO_in
PIIO_out
PILibrary_load
PILibrary_lookup
PILibrary_lookupOrLoad
PILog_addMessage
PILog_newSink
PILog_writeDiagnostics
PILogic_execute
PIObject_copy
PIObject_delete
PIObject_getClass
PIObject_getConfigurationDB
PIObject_getDB
PIObject_getName
PIObject_getUserData
PIObject_load
PIObject_loadEx
PIObject_loadFromLine
PIObject_new
PIObject_readParameters
PIObject_setConfigurationDB
PIObject_setDB
PIObject_setUserData
PIProgram_dbgDump
PIProgram_enter
PIUserType_getValue


Name:
PIClass_getLibrary

Synopsis:
const PIDLL *PIClass_getLibrary( const PIClass *pClass )

Description:
Return the library object associated with this class.

Notes:

Return Values:
Returns NULL on failure.

Errors:
PIAPI_EINVAL if pClass is NULL.

See Also:

Return to index


Name:
PIClass_load

Synopsis:
const PIClass *PIClass_load( PIDB *pDB, PIConfig *pConfig, const char *pClassName )

Description:
Attempts to load a class with name pClassName from a definition in the parsed configuration DB pConfigDB. If pConfigDB is NULL then PIConfig_findConfiguration() is used to find the configuration DB from pDB.

Notes:
If the class library has not already been loaded PIClass_loadClass will attempt to load it using PILibrary_load().

Return Values:
On success PIClass_load() returns a const pointer to the specified class.

Errors:
PIAPI_EINVAL if pDB or pClassName is NULL. PIAPI_ERROR if another error occurred.

See Also:

Return to index


Name:
PIClass_lookup

Synopsis:
const PIClass *PIClass_lookup( PIDB *pDB, const char *pClassName );

Description:
Looks under the root node of pDB for a PIDB tree with a key of PIDBKEY_LIBRARIES and then under that for a PIDB with a key of PIDBKEY_CLASSES, then searches within this tree for an element with key pClassName. If found this element is returned.

Notes:

Return Values:
On success PIClass_lookup() returns a const pointer to the specified class.

Errors:
PIAPI_EINVAL if pDB or pClassName is NULL. PIAPI_ERROR if another error occurred.

See Also:

Return to index


Name:
PIClass_lookupOrLoad

Synopsis:
const PIClass *PIClass_lookupOrLoad( PIDB *pDB, PIConfig *pConfig, const char *pClassName )

Description:
This function first attempts to find an existing class using PIClass_lookup(). If that fails it attempts to load the class from the parsed configuration DB pConfigDB using PIClass_load().

Notes:
See PIClass_lookup() and PIClass_load() for more details.

Return Values:
On success PIClass_lookup() returns a const pointer to the specified class.

Errors:
PIAPI_EINVAL if pDB or pClassName is NULL. PIAPI_ERROR if another error occurred.

See Also:

Return to index


Name:
PIConfigString_getString

Synopsis:
const char *PIConfigString_getString( PIConfigString *pString )

Description:
Returns the string value of a given PIConfigString data structure.

Notes:

Return Values:
Returns a pointer to the string of the given PIConfigString data structure.

Errors:
On error PIConfigString_getString() returns NULL.

See Also:

Return to index


Name:
PIConfig_findConfiguration

Synopsis:
PIConfig *PIConfig_findConfiguration( PIDB *pDB )

Description:
Search under the PIDB tree node pDB for another tree with the key PIDBKEY_CONFIGURATION. The tree hierarchy is search recusively upwards from the node pDB until the configuration tree is found or the root node is reached with no match.

Notes:
This function is implemented as PIConfig *PIDB_Lookup( pDB, <internal type>, PIDBKEY_CONFIGURATION, PIDBFLAG_PROPAGATEUP )

Return Values:
Returns a pointer to the configuration tree or NULL if it was not found.

Errors:
Returns NULL is pDB is NULL.

See Also:

Return to index


Name:
PIConfig_loadConfigurationFile

Synopsis:
int PIConfig_loadConfigurationFile( PIDB *pDB, const char *pFileName, PIConfig **ppConfigDB )

Description:
Parse the configuration file pFileName and place the parsed contents in a new DB tree under the specified tree pDB, with the key PIDBKEY_CONFIGURATION. If ppConfigDB is non-NULL and a configuration tree is created the pointer to the new configuration tree will be placed in ppConfigDB.

Notes:
In all cases where pDB and pFileName are non-NULL a new child DB tree with the key PIDBKEY_CONFIGURATION will be added under the tree pDB.

Return Values:
On complete success PIConfig_loadConfigurationFile() will return zero (PIAPI_COMPLETED). Other errors may be returned as described below.

Errors:
PIAPI_EINVAL if pDB or pFileName is NULL. PIAPI_ERROR if an error occurred while parsing the configuration file. [PIAPI_WARNING] this error code may be returned if a warning was generated while parsing the configuraton file. Currently PIAPI_COMPLETED will be returned when a configuration file is loaded with only warnings.

See Also:

Return to index


Name:
PIConfig_lookupTree

Synopsis:
PIConfig *PIConfig_lookupTree( PIConfig *pConfig, const char *pKey, char *pInfoBuffer, int iLen )

Description:
Lookup the configuration tree with the key pKey in pConfig. If the definition is found and pInfoBuffer is non-NULL a description of the location where the tree was defined will be written into it, up to iLen characters.

Notes:
A configuration file tree is of the following form

	<key>
	  ...
	  ...
	</key>
	
The exact format of the description placed in pInfoBuffer is subject to change but may include the following information: If multiple defintions for a key are found within pConfig then the first will be returned.

Return Values:
Returns a PIConfig structure. The functions PIConfig_lookupValue() and PIConfig_lookupTree() can be used to find definitions and trees within this tree.

Errors:
Returns NULL if a tree with the specified key was not found within this key.

See Also:

Return to index


Name:
PIConfig_lookupValue

Synopsis:
const char *PIConfig_lookupValue( PIConfig *pConfig, const char *pKey, char *pInfoBuffer, int iLen )

Description:
Lookup a value within the specified configuration tree. If the value is found and pInfoBuffer is non-NULL a description of the location where the value was defined will be written into it, up to iLen characters.

Notes:
A configuration file definition line is of the form

	<key>=<value> <additional values>
	
The exact format of the description placed in pInfoBuffer is subject to change but may include the following information: If multiple definitions for a key are found within pConfig then the first will be returned.

Return Values:
Returns a pointer to the value for the key pKey under the configuration tree. PIConfig_lookupValue() returns NULL if no match is found.

Errors:
Returns NULL if pConfig is NULL.

See Also:

Return to index


Name:
PIDBEx_new

Synopsis:
PIDB *PIDBEx_new( PIDB *pParent, const char *pName, void *(* fnLookup)( PIDB *, int, const char *, int ) )

Description:
Creates a new PIDB of extended type PIDBEx. This tree supports a lookup callback where lookups on the tree will invoke the user supplied lookup function.

Notes:
Use of this callback function on instances of this extended tree type can be overriden by adding the PIDBFLAG_NOCALLBACK flag to the flags passed to PIDB_lookup() or PIDB_getIterator().

Return Values:
Returns a pointer to the new child PIDB tree on success.

Errors:
Returns NULL if fnLookup is NULL.

See Also:

Return to index


Name:
PIDBIterator_atValidElement

Synopsis:
int PIDBIterator_atValidElement( PIDBIterator *pIter )

Description:
Returns a boolean result indicating whether not the PIDBIterator_current() may be used to retrieve an element from the iterator.

Notes:

Return Values:
Returns non-zero (PIAPI_TRUE) if an element may be read, otherwise zero (PIAPI_FALSE) the iterator has exhausted matching elements.

Errors:
Returns PIAPI_FALSE if pIter is NULL.

See Also:

Return to index


Name:
PIDBIterator_current

Synopsis:
void *PIDBIterator_current( PIDBIterator *pIter, const char **ppKey )

Description:
Returns the value of the current element of the iterator. If ppKey is not NULL it will be set to point to the key of the retrieved element.

Notes:
The results are undefined if the iterator does not point at a valid element. The function PIDBIterator_atValidElement can be used to verify the status of the iterator object. In general the iterator object return elements in no particular order. However, elements with the exact same key will be retrieved in the order in which they were placed in the tree.

Return Values:
Returns the current object from the iterator. The type of the object depends on the value of iType. The pointer should be cast to a pointer of the appropriate type, typically the typecasts would be as follows

iTypeCastRemark
PIDBTYPE_TREEPIDB *a tree node
PIDBTYPE_STRINGconst char *character array
PIDBTYPE_RFC822const char *character array
PIDBTYPE_OPAQUEvoid *generic pointer
PIDBTYPE_USERvoidnot defined

Errors:
Returns NULL is pIter is NULL.

See Also:

Return to index


Name:
PIDBIterator_delete

Synopsis:
int PIDBIterator_delete( PIDBIterator *pIter )

Description:
Destroys the iterator object and frees any associated memory.

Notes:

Return Values:
On success PIDBIterator_delete() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_EINVAL if pIter is NULL

See Also:

Return to index


Name:
PIDBIterator_next

Synopsis:
int PIDBIterator_next( PIDBIterator *pIter )

Description:
Increments an iterator objects internal pointers to point at The next valid PIDB element.

Notes:
The results are undefined if the iterator does not point at a valid element. The function PIDBIterator_atValidElement should be used at PIIterator_next and before PIDBIterator_next to verify that the iterator points at a valid PIDB element.

Return Values:
On success PIDBIterator_next() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_EINVAL if pIter is NULL

See Also:

Return to index


Name:
PIDBIterator_removeCurrent

Synopsis:
int PIDBIterator_removeCurrent( PIDBIterator *pIter )

Description:
Remove and destroy the current element of the iterator pIter.

Notes:

Return Values:
On success PIDBIterator_removeCurrent() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_EINVAL if pIter is NULL

See Also:

Return to index


Name:
PIDB_add

Synopsis:
int PIDB_add( PIDB *pTree, int iType, const char *pKey, void *pValue, int iFlags )

Description:
Adds a child element into a PIDB tree. The action performed on the opaque pointer pValue depends on the value of iType.

PIDBTYPE_TREE
pValue must be a pointer to a valid PIDB tree. This tree is in specified tree as a child node. Note that child trees are automatically placed in thier parents tree when they are created, explicitly adding them a second time may cause serious problems when the tree is recursively free'd with PIDB_delete(). Use this only to attach a child tree which was created with a NULL value for parameter pParent in the call to PIDB_new().
PIDBTYPE_STRING
pValue must be a pointer to a null terminated character array. A copy of the string is generated and stored in the current tree.
PIDBTYPE_RFC822
This type is created, maintained and used in the same way as type PIDBTYPE_STRING. The important difference between PIDBTYPE_STRING and PIDBTYPE_RFC822 is that PIDBTYPE_STRING is in all repects case sensitive, whereas PIDBTYPE_RFC822 is in all respects case in-sensitive.
PIDBTYPE_OPAQUE
pValue is stored in the tree as an unknown pointer. Note that the user is responsible for free'ing memory allocated at pValue, if any. This is different from other tree types where the object referenced by pValue will be cleaned up and memory free'd when the tree is destroyed.
PIDBTYPE_USER
This type requires that pValue is an object of a type not specified in this interface. Pending this specification this type is for internal use only.
The value iFlags is formed by OR'ing together the following values

PIDBFLAG_FASTKEY
The value pKey is assumed to be a symbol table entry so PIDB_add() skips the hashing and offset logic. This improves performance on repeated DB actions at the cost of initial setup using PIDB_getFastKey().

Notes:
The type PIDBTYPE_USER is under development and its behaviour is subject to change.

Return Values:
On success PIDB_add returns zero (PIAPI_COMPLETED). Otherwise an error occured as described below.

Errors:
PIAPI_EINVAL An invalid value for iType was used or pTree was NULL PIAPI_EXHAUSTED Memory could not be allocated to complete the function.

See Also:

Return to index


Name:
PIDB_delete

Synopsis:
int PIDB_delete( PIDB *pTree )

Description:
Destructs a root PIDB tree created by PIDB_new( NULL ).

Notes:

Return Values:
On success PIDB_delete returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_EINVAL is returned if pTree is NULL. If pTree is a child node of another tree then PIAPI_ERROR is returned.

See Also:

Return to index


Name:
PIDB_getFastKey

Synopsis:
const char *PIDB_getFastKey( const char *pKey, int iType )

Description:
Returns a pointer to a symbol table entry for the key pKey and PIDB type iType. This symbol table entry then then be used in calls to PIDB_lookup() and PIDB_getIterator() with the PIDBFLAG_FASTKEY to avoid the overhead of hashing and symbol table lookup.

Notes:
This function is useful where a key is used multiple times. The fast key can be generated once and reused across all invocations of PIDB_lookup() and PIDB_getIterator(). This significantly improves performance.

Return Values:
On success PIDB_getFastKey() returns a new key. Returns NULL on failure.

Errors:
Returns NULL if pKey is NULL or no memory space is available.

See Also:

Return to index


Name:
PIDB_getIterator

Synopsis:
PIDBIterator *PIDB_getIterator( PIDB *pTree, int iType, const char *pKey, int iFlags )

Description:
Returns a pointer to an PIDBIterator object which to traverse the specified tree for elements of type iType which match the key pKey. If pKey is NULL all objects with type iType will be matched. The following flags may be OR'ed together to form the value iFlags: PIDBFLAG_PROPAGATEUP The current tree will first be searched and then the parent tree. The recursively search all trees up the tree hierarchy to the root node. PIDBFLAG_NOCALLBACK This flag disables use the the callback functions in DB tree's created with callback hook functions via PIDBEx_new(). This flag is typically used in the implementation of callback functions for PIDBEx when PIDB_lookup() or PIDB_getIterator() would cause a recursive invokation of the callback function. PIDBFLAG_FASTKEY This flag indicates that the key pKey is an optimized key generated by PIDB_getFastKey().

Notes:
The iterator object should be free'd with PIDBIterator_delete() when it is no longer needed.

Return Values:
On success a pointer to an PIDBIterator object is returned. The functions PIDBIterator_atValidElement(), PIDBIterator_current(), PIDBIterator_next() and PIDBIterator_delete() are used to access and manipulate the iterator.

Errors:
NULL is returned if pTree is NULL, iType invalid or memory could not be allocated for the PIDBIterator object.

See Also:

Return to index


Name:
PIDB_getParent

Synopsis:
PIDB *PIDB_getParent( PIDB *pTree )

Description:
Returns the parent tree of the specified PIDB tree.

Notes:

Return Values:
Returns a pointer to the parent tree or NULL if the specified tree is the top of the tree hierarchy.

Errors:
NULL if pTree is NULL

See Also:

Return to index


Name:
PIDB_getRoot

Synopsis:
int PIDB_getRoot( PIDB *pTree )

Description:
Returns the root node of a PIDB tree hierarchy.

Notes:

Return Values:
On success PIDB_getRoot() returns the root node of the PIDB tree hierarchy.

Errors:
If pTree is NULL PIDB_getRoot() returns NULL.

See Also:

Return to index


Name:
PIDB_lookup

Synopsis:
void *PIDB_lookup( PIDB *pTree, int iType, const char *pKey, int iFlags )

Description:
Searches the PIDB tree for the first occurence of the an element which matches the key. If pKey is NULL then the first element of the specified type will be returned. See PIDB_getIterator() for the use of the parameter iFlags.

Notes:
This function cannot be used to distinguish between an unsuccessful search and a successful search where the value of the matched element is NULL. In these cases an PIDBIterator object should be used to scan the tree, see PIDB_getIterator.

Return Values:
On success the reference of the first element is returned. The type of the value depends on the specified value of iType. See PIDB_add for a full description of possible types. See PIDBIterator_current for a description of appropriate PIDBTYPE to C typecast mappings. NULL is returned if no match was found.

Errors:
If pTree is NULL or iType is out of range then PIDB_lookup() returns NULL.

See Also:

Return to index


Name:
PIDB_new

Synopsis:
PIDB *PIDB_new( PIDB *pParent, const char *pName )

Description:
Creates a new PIDB tree under the specified parent node with the specified name. If pParent is NULL, then the generated node will be the root of a new PIDB tree hierarchy. If a new child tree is successfully generated it is automatically added into the parent tree's list of child nodes with a type of PIDBTYPE_TREE and a key of pName. If pParent is NULL then a new root tree node is generated. This tree should be free'd with PIDB_delete() when it is no longer needed.

Notes:
If memory cannot be allocated for the new tree, a special handler will be invoked in a method specific to the build and configuration of the server library. For more information see the specific notes for the library release.

Return Values:
Returns a pointer to the new child PIDB tree, or NULL if insufficent memory was available.

Errors:

See Also:

Return to index


Name:
PIDB_pidbflagsNameToNumber

Synopsis:
int PIDB_pidbflagsNameToNumber( const char *pFlags )

Description:
Returns the integer value of the flags represented by the string pFlags. The string pFlags may contain many flags seperated by the pipe ('|') character.

pTypeReturn code
"PROPAGATEUP"PIDBFLAG_TREE
"NOCALLBACK"PIDBFLAG_NOCALLBACK
"FASTKEY"PIDBFLAG_FASTKEY
Comparision in not case sensitive.

Notes:
Whitespace in the string pFlags is allowed and will be ignored in matching the flags. The flags PIDBFLAG_NOCALLBACK and PIDBTYPE_FASTKEY have little use in the context of persistence and are included only for completeness.

Return Values:
Returns the value formed by bitwise OR'ing the flags together. If no flags are matched or the value pFlags is NULL, PIDB_pidbflagsNameToNumber returns zero (PIDBFLAG_NONE).

Errors:
This function does not generate an error. Unrecognised flags are ignored.

See Also:
PIDB_pidbtypeNameToNumber

Return to index


Name:
PIDB_pidbtypeNameToNumber

Synopsis:
int PIDB_pidbtypeNameToNumber( const char *pType )

Description:
Returns the integer value of the name pType, effectively mapping, the string pType to return values as follows:-

pTypeReturn code
"TREE"PIDBTYPE_TREE
"STRING"PIDBTYPE_STRING
"RFC822"PIDBTYPE_RFC822
"OPAQUE"PIDBTYPE_OPAQUE
"USER"PIDBTYPE_USER
Comparision in not case sensitive.

Notes:

Return Values:
If the string pType could not be matched PIDB_pidbtypeNameToNumber() returns PIDBTYPE_INVALID.

Errors:
On error PIDB_pidbtypeNameToNumber() returns PIDBTYPE_INVALID.

See Also:
PIDB_pidbflagsNameToNumber

Return to index


Name:
PIDB_replace

Synopsis:
int PIDB_replace( PIDB *pTree, int iType, const char *pKey, void *pValue, int iFlags )

Description:
Replaces the first instance of the value corresponding to pKey in the DB pTree. The new entry will be created even if a previous entry could not be found. PIDB_add() describes the parameters iType and iFlags. Additionally iFlags may have the following flag set PIDBFLAG_PROPAGATEUP Search upwards from the current tree to parent trees to find a match.

Notes:

Return Values:
On success PIDB_replace returns zero (PIAPI_COMPLETED). Otherwise an error occured as described below.

Errors:
PIAPI_EINVAL An invalid value for iType was used or pTree was NULL PIAPI_EXHAUSTED Memory could not be allocated to complete the function.

See Also:

Return to index


Name:
PIIO_in

Synopsis:
int PIIO_in( PIObject *pObj, void *pData, int iLen, int *piReceived, int iArgc, const char *ppArgv[] )

Description:
Read a block of data from the IO object pObj into the buffer pData. Up to iLen bytes may be read. On success the number bytes read is written to the integer pointer to by piReceived Optional additional parameters may be passed to the IO object, the parameters iArgc and ppArgv specify the number of elements in an array of values and the array of values respectively.

Notes:
On normal channel close (gracefull socket or pipe close) PIAPI_COMPLETED is returned and the value at piReceived set to zero.

Return Values:
On success PIAPI_COMPLETED is returned.

Errors:
On error PIAPI_ERROR is returned.

See Also:
PIIO_out

Return to index


Name:
PIIO_out

Synopsis:
int PIIO_out( PIObject *pObj, void *pData, int iLen, int *piSent, int iArgc, const char *ppArgv[] )

Description:
Send a block of data in buffer pData with length iLen into the IO object pObj. On success the value at piSent is set to the number of bytes written. Optional additional parameters may be passed to the IO object, the parameters iArgc and ppArgv specify the number of elements in an array of values and the array of values respectively.

Notes:

Return Values:
On success PIAPI_COMPLETED is returned.

Errors:
On error PIAPI_ERROR is returned.

See Also:
PIIO_in

Return to index


Name:
PILibrary_load

Synopsis:
const PILibrary *PILibrary_load( PIDB *pDB, PIConfig *pConfig, const char *pLibraryName )

Description:
Attempts to load the library with name pLibraryName from the parsed configuration file pConfigDB. If pConfigDB is NULL then PIConfig_findConfiguration() is used to find the configuration DB from pDB.

Notes:

Return Values:
On success PILibrary_load() returns a const pointer to the a new PILibrary object.

Errors:
PIAPI_EINVAL if pDB or pLibraryName is NULL. PIAPI_ERROR if another error occurred.

See Also:

Return to index


Name:
PILibrary_lookup

Synopsis:
const PILibrary *PILibrary_lookup( PIDB *pDB, const char *pLibraryName );

Description:
Looks under the root node of pDB for a PIDB tree with a key of PIDBKEY_LIBRARIES, then searches within this tree for an element with key pLibraryName. If found this element is returned.

Notes:

Return Values:
On success PILibrary_lookup() returns a const pointer to a new PILibrary object.

Errors:
PIAPI_EINVAL if pDB or pLibraryName is NULL. PIAPI_ERROR if another error occurred.

See Also:

Return to index


Name:
PILibrary_lookupOrLoad

Synopsis:
const PILibrary *PILibrary_lookupOrLoad( PIDB *pDB, PIConfig *pConfig, const char *pLibraryName )

Description:
This function first attempts to find an existing library using PILibrary_lookup(). If that fails it attempts to load the library from the parsed configuration DB pConfigDB using PILibrary_load().

Notes:
See PILibrary_lookup() and PILibrary_load() for more details.

Return Values:
On success PILibrary_lookup() returns a const pointer to the specificed PILibrary object.

Errors:
PIAPI_EINVAL if pDB or pLibraryName is NULL. PIAPI_ERROR if another error occurred.

See Also:

Return to index


Name:
PILog_addMessage

Synopsis:
int PILog_addMessage( PIDB *pDB, PIConfig *pConfig, int iType, const char *pFormat, ... );

Description:
Log a message concerning initialization from a configuration file. PILog_addMessage() will automatically include information from parsed configuration DB pConfig. pFormat is a printf() compatible format string. PILog_addMessage() takes a variable number of arguments. The number and type of arguments should be compatible with printf() directives. The flag iType indicates whether the item should be logged as an error or a warning, it may contain one of the following values:- PILOG_ERROR PILOG_WARNING PILOG_ALL

Notes:
PILog_addMessage() looks under the root DB for a DB with a key of PIDBKEY_DIAGNOSTICS.

Return Values:
On success PILog_addMessage() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_EINVAL if pDB or pFormat is NULL. PIAPI_ERROR if another error occurred.

See Also:

Return to index


Name:
PILog_newSink

Synopsis:
int PILog_newSink( int iType, const char *pParam )

Description:
Sets a new sink for logged messages. Messages can be sent to the main program DB (default), to a file (path to file is given by parameter pParam), or to a standard stream. The following flags for iType dictate the new sink.

Notes:
Current logging to a file via this mechanism is not implemented, attempting to set the log sink to a file will result in an error code of PIAPI_NOTSUPPORTED.

Return Values:
On success PILog_newSink() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_EINVAL if iType is PILOG_FILE and pParam is NULL. PIAPI_ERROR if another error occurred. PIAPI_NOTSUPPRTED as described under notes.

See Also:

Return to index


Name:
PILog_writeDiagnostics

Synopsis:
int PILog_writeDiagnostics( PIDB *pDB, int iFlags, const char *pFileName )

Description:
Write the contents of the diagnostics DB to the file pFileName. The value iFlags is the inclusive-or of diagnostic types to write, the macro PILOG_ALL can be used to specify all message types. If pFileName is NULL the output will be written to the standard output.

Notes:
PILog_writeDiagnostics() looks under the root DB for a DB with a key of PIDBKEY_DIAGNOSTICS.

Return Values:
On success PILog_writeDiagnostics() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_EINVAL if pDB is NULL. PIAPI_ERROR if another error occurred.

See Also:

Return to index


Name:
PILogic_execute

Synopsis:
int PILogic_execute( PIObject *pObj, int iArgc, const char *ppArgv[] )

Description:
Execute the logic performed by the logic object pObj. Optional additional parameters may be passed to the logic object, the parameters iArgc and ppArgv specify the number of elements in an array of values and the array of values respectively.

Notes:

Return Values:
On success PIAPI_COMPLETED is returned.

Errors:
On error PIAPI_ERROR or PIAPI_ABORT is returned.

See Also:

Return to index


Name:
PIObject_copy

Synopsis:
PIObject *PIObject_copy( PIObject *pObject, int iArgc, const char *ppArgv[] )

Description:
Make an exact copy of an object. The new objects constructor function will be invoked with the arguments iArgc and ppArgv.

Notes:

Return Values:
Returns a pointer to the new object, or NULL if an error occurred.

Errors:
Returns NULL if pObject is NULL or memory could not be allocated for the copy operation.

See Also:

Return to index


Name:
PIObject_delete

Synopsis:
int PIObject_delete( PIObject *pObj, int iArgc, const char *ppArgv[] )

Description:
Destroy and free memory associated with the object pObj. The objects destructor function will be passed the parameters iArgc and ppArgv.

Notes:

Return Values:
On success PIObject_delete() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_EINVAL is returned if pObj is NULL.

See Also:

Return to index


Name:
PIObject_getClass

Synopsis:
const PIClass *PIObject_getClass( const PIObject *pObj )

Description:
Returns a reference to the class object of this object.

Notes:

Return Values:
Returns a reference to the class object of this object.

Errors:
Returns NULL is pObj is NULL.

See Also:

Return to index


Name:
PIObject_getConfigurationDB

Synopsis:
PIConfig *PIObject_getConfigurationDB( const PIObject *pObj )

Description:
Returns the configuration DB associated with an object.

Notes:

Return Values:
Returns the configuration DB associated with this object.

Errors:
Returns NULL is pObj is NULL.

See Also:

Return to index


Name:
PIObject_getDB

Synopsis:
PIDB *PIObject_getDB( const PIObject *pObj )

Description:
Returns the DB associated with this object.

Notes:

Return Values:
Returns the DB associcated with this object.

Errors:

See Also:

Return to index


Name:
PIObject_getName

Synopsis:
const char *PIObject_getName( const PIObject *pObj )

Description:
Returns an objects name.

Notes:

Return Values:
Returns the object's name.

Errors:
Returns NULL is pObj is NULL.

See Also:

Return to index


Name:
PIObject_getUserData

Synopsis:
void *PIObject_getUserData( const PIObject *pObj )

Description:
Return the value previously set for this object by PIObject_setUserData().

Notes:
The user data field is NULL initialized when the object instance is created.

Return Values:
Returns user defined value for this object.

Errors:
Returns NULL is pObj is NULL.

See Also:

Return to index


Name:
PIObject_load

Synopsis:
PIObject *PIObject_load( PIDB *pDB, PIConfig *pConfig, const char *pName, int iArgc, const char *ppArgv[] )

Description:
Create an instance of an object from a class reference and the parsed configuration tree pConfigDB. If pConfigDB is NULL then the DB tree hierarchy will be searched upwards from pDB to find a tree whose key is PIDBKEY_CONFIGURATION. If the class of the object is not known the function PIClass_lookupOrLoad() will be invoked to attempt to load the class. The constructor function of the object's classes is invoked on the new object with the arguments iArgc and ppArgv before it is returned from this function.

Notes:
The configuration file reference to an object is of the form

		<Object>
		Name=[object name]
		Class=[class name]
		...
		...
		</Object>
	

Return Values:
Returns a pointer to the new object, or NULL if an error occurred.

Errors:

See Also:
PIObject_loadEx PIObject_loadFromLine

Return to index


Name:
PIObject_loadEx

Synopsis:
PIObject *PIObject_loadEx( const PIObject *pParent, const char *pObjectKey)

Description:
Create an instance of an object from a parent object reference. The configuration tree of the parent will be used to lookup the object line by the given object key. PIObject_loadFromLine will be used to load the object.

Notes:

Return Values:
Returns a pointer to the new object, or NULL if an error occurred.

Errors:

See Also:
PIObject_load PIObject_loadFromLine

Return to index


Name:
PIObject_loadFromLine

Synopsis:
PIObject *PIObject_loadFromLine( PIDB *pDB, PIConfig *pConfig, const char *pObjectLine )

Description:
Create an instance of an object from a class reference and the parsed configuration tree pConfigDB and the given object line. The parameter pObjectLine is tokenized and the result is handed over to PIObject_load to construct the object finally.

Notes:
The string pObjectLine contains the object name in the leading position and the constructor arguments all separated by whitespaces.

Return Values:
Returns a pointer to the new object, or NULL if an error occurred.

Errors:

See Also:
PIObject_load PIObject_loadEx

Return to index


Name:
PIObject_new

Synopsis:
PIObject *PIObject_new( const PIClass *pClass, PIDB *pDB, PIConfig *pConfig, const char *pName, int iArgc, const char *ppArgv[] )

Description:
Create an instance of an object from a class directly without using a parsed configuration tree. The object will be created with class pClass, DB pDB, ConfigDB pConfig, and name pName. The object's constructor function will be invoked with the parameters iArgc and ppArgv.

Notes:

Return Values:
Returns a pointer to the new object, or NULL if an error occurred.

Errors:

See Also:

Return to index


Name:
PIObject_readParameters

Synopsis:
int PIObject_readParameters( PIObject *pParent, int iArgc, const char *ppArgv[], int (* fnParameters)( void *, const char *, const char *, const char * ), void *pParam )

Description:
Read in the configuration parameters of an object during construction. This function will loop over all parameters passed in ppArgv, and hand over the pre-processed parameters together with pParam to the callback function fnParameters.

Notes:
The parameter line will be tokenized and de-quoted, i.e. the parameters are of the general form

		key1="value1"
		key2="value2"
		...
	

Return Values:
Returns non-zero on success, zero on failure.

Errors:

See Also:

Return to index


Name:
PIObject_setConfigurationDB

Synopsis:
int PIObject_setConfigurationDB( PIObject *pObj, PIConfig *pConfig )

Description:
Sets the configuration DB of the associated object.

Notes:

Return Values:
On success PIObject_setConfigurationDB() returns zero (PIAPI_COMPLETED).

Errors:
If either of pObj or pConfig are NULL, PIObject_setConfigurationDB() returns PIAPI_EINVAL.

See Also:

Return to index


Name:
PIObject_setDB

Synopsis:
int PIObject_setDB( PIObject *pObj, PIDB *pDB )

Description:
Sets the DB associated with this object.

Notes:

Return Values:
PIObject_setDB() returns zero (PIAPI_COMPLETED) on success.

Errors:
PIAPI_EINVAL is pObj is NULL.

See Also:

Return to index


Name:
PIObject_setUserData

Synopsis:
int PIObject_setUserData( PIObject *pObj, void *pNewValue )

Description:
Sets the user data field in the object to pNewValue. This value can be retrieved later with a call to PIObject_getUserData().

Notes:

Return Values:
On success PIObject_setUserData() returns zero (PIAPI_COMPLETED).

Errors:
If pObj is NULL PIObject_setUserData() returns PIAPI_EINVAL.

See Also:

Return to index


Name:
PIProgram_dbgDump

Synopsis:
int PIProgram_dbgDump( PIDB *pDB, const char *pDumpFile )

Description:
Dump the entire contents of the database referenced by pDB to the file pDumpFile. The file is opened in write truncate mode. If pDumpFile is NULL PIProgram_dbgDump will attempt to write data to the standard output stream.

Notes:
PIProgram_dbgDump formats the data in a hierarchical tree format.

Return Values:
On success PIProgram_dbgDump() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_EINVAL if pDB is NULL. PIAPI_ERROR if another error occurred.

See Also:

Return to index


Name:
PIProgram_enter

Synopsis:
int PIProgram_enter( const char *pProgramName, int iVersion, PIProgramFn fn )

Description:
Initializes the program database and platform facilities. If successful it invokes the user supplied function fn.

Notes:
PIProgam_enter should be invoked with the value PIPROGRAM_VERSION_1_0 for parameter iVersion. PIProgram_enter automatically invokes PIPlatform_enter with the platform version PIPLATFORM_VERSION_1_0 to initialize multithreading and custom memory management facilities. The parameter pProgramName should be passed argv[0] from the main() entry point to the program. This may be used by certain platform implementations.

Return Values:
On success PIProgram_enter() returns zero (PIAPI_COMPLETED)

Errors:
PIAPI_EINVAL if iVersion is not supported or fn is NULL. PIAPI_ERROR if another error occurred.

See Also:

Return to index


Name:
PIUserType_getValue

Synopsis:
void *PIUserType_getValue( PIUserType *pUserType )

Description:
Returns the value associated with a PIUserType data structure.

Notes:

Return Values:
On success PIUserType_getValue returns the value associated with the PIUserType data structure. Returns NULL if pUserType is not valid.

Errors:

See Also:

Return to index