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, , 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 ... ... The exact format of the description placed in pInfoBuffer is subject to change but may include the following information:- - The filename from which the value was read. - The line number within the file where the value was found. - The character position within the line where the key definition was found. For configuration files with content-type x-pi-internal/x-scl1.0 (.conf or .scl) this will be the length of the line. 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= The exact format of the description placed in pInfoBuffer is subject to change but may include the following information:-

• The filename from which the value was read.
• The line number within the file where the value was found.

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 PIDBTYPE_TREE PIDB * a tree node PIDBTYPE_STRING const char * character array PIDBTYPE_S_RFC822 const char * character array PIDBTYPE_C_RFC822 const char * character array PIDBTYPE_OPAQUE void * generic pointer PIDBTYPE_USER void not 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.

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: PIDBFLAGS_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.

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:-

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.

PILOG_DB - main program DB, under subtree 'Diagnostics'. PILOG_FILE - a file, path is specified by parameter pParam. PILOG_STDOUT - the stdout stream. PILOG_STDERR - the stderr stream.

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