Main Page | Modules

Exception log manipulation functions.


Functions

void fwUkl1ExceptionLog_setLogName (const string &logName, bool deleteOld, bool create, dyn_string &exceptionInfo)
string fwUkl1ExceptionLog_getLogName ()
void fwUkl1ExceptionLog_create (dyn_string &exceptionInfo)
void fwUkl1ExceptionLog_delete (dyn_string &exceptionInfo)
void fwUkl1ExceptionLog_clear (dyn_string &exceptionInfo)
void fwUkl1ExceptionLog_submit (dyn_string &exceptionInfo, string baseNode="")
void fwUkl1ExceptionLog_setDisplayTreeName (const string &treeName, dyn_string &exceptionInfo)
string fwUkl1ExceptionLog_getDisplayTreeName (dyn_string &exceptionInfo)
void fwUkl1ExceptionLog_connect (const string &treeName)
void fwUkl1ExceptionLog_displayCB (string dpe, dyn_string asNewData)
string _fwUkl1ExceptionLog_generateCode (const dyn_string &exceptionLog)

Detailed Description

Contains the functions that are used to create the exception log, including the data point type. Functions are provided for submitting to the log as well as displaying the exceptions that are generated by the log. The display mechanism can be set up as a call back routine to monitor changes in the exception log and then display them appropriately.

Function Documentation

string _fwUkl1ExceptionLog_generateCode const dyn_string &  exceptionLog  ) 
 

Returns an unique identifier for that can be used to label an exception chain before it is submitted to the exception log.

Parameters:
exceptionLog The array of strings that contains the exception log. This can only handle exceptions that have been stored within the HW DP exception log. This is the only way to guaranty that the exception information has been tagged with a unique ID, which it is the aim of this function to return.
Returns:
string The unique ID that can be used as a string. It must be submitted as a string for the exception code.
The function is quite robust and will return a unique ID in almost all cases. It will return a postive ID if the function completes normally. It will return a negative ID if the function failed to determine the previous unique ID and was forced to generate a new one randomly. In the event that it cannot find a unique ID then it will return 0.

void fwUkl1ExceptionLog_clear dyn_string &  exceptionInfo  ) 
 

Removes all the exceptions in the current exception log.

Parameters:
exceptionInfo Contains information about exceptions that may have occured during the function execution.
Returns:
void.

void fwUkl1ExceptionLog_connect const string &  treeName  ) 
 

Sets up a connect()ion between the exception log data point and the function that is used to parse the exception log display.

Parameters:
treeName Name of the PVSS tree shape that the exception log should be displayed on.
Returns:
void.
If the exception log is found not to exist then it will be created. In the event that the exception log cannot be connected to or the tree shape does not exist, an exception will be displayed via fwUkl1ExceptionHandling_display().

Example

   (...)
   //Part of a PVSS tree shape initialisation function, created in GEDI.
   //Get the name of the shape that we are initialising.
   const string treeName = this.name();
   //Now call the connect function.
   fwUkl1ExceptionLog_connect(treeName);
   //Will either have successfully connected to the log or will display an exception chain in this tree.
   (...)

void fwUkl1ExceptionLog_create dyn_string &  exceptionInfo  ) 
 

Used to create an exception log for use with the library functions. If the log already exists it will return with no errors. The log name is taken from the global variable gsFwUkl1ExceptionLogDp, which can accessed through set/getFwUkl1ExceptionLog_getLogName().

Parameters:
exceptionInfo Contains details about any exception information that occured during the creation of the log. if exception information is present then the log does not exist.
Returns:
void.

void fwUkl1ExceptionLog_delete dyn_string &  exceptionInfo  ) 
 

Deletes the existing exception log.

Parameters:
exceptionInfo Contains information about any exceptions that may occur during the function call.
Returns:
void.
If the log is delete and none recreated then the next call to submit or any attempt to set up a call back function will recreate the log.

void fwUkl1ExceptionLog_displayCB string  dpe,
dyn_string  asNewData
 

A call back function that can be used to display the exceptions contained within the exception log.

Parameters:
dpe Name of the data point element that the call back function is connected to.
asNewData A dyn_string containing the information that is contained in the data point.
Returns:
void.
Example
   (...)
   //First set the name of the tree that we wish to use to display the exception log.
   //Holds any exception information that may occur.
   dyn_string exceptionInfo;
   int exInfoSize = dynlen(exceptionInfo);
   //Set the name of the tree to display the exception log.
   fwUkl1ExceptionLog_setDisplayTreeName(treeName, exceptionInfo);
   //Check for errors here, only continue if everything is ok.

   //...assuming everything is good, check for the existance of the exception log.
   fwUkl1ExceptionLog_create(exceptionInfo);
   //Again check for errors here, only continue if everything is ok.

   //...assuming everything is good connect this function to the exception log.
   dpConnect("fwUkl1ExceptionLog_displayCB", gsFwUkl1ExceptionLogDp + "." + FWUKL1_EXCEPTION_LOG_DPE);
   //Check for errors.
   dyn_errClass err = getLastError();
   if (0 < dynlen(err)) {
     //Datapoint element doesn't exist can't check for errors!
     //Raise an exception.
     fwUkl1Exception_raise(exceptionInfo, "WARNING", "fwUkl1ExceptionLog_connect(): Failed to establish a call back function for the exception log data point. Future submitted errors will not be display in this tree.", "");
     //Pop up an exception demostrating the error that occured.
     fwUkl1ExceptionHandling_display(exceptionInfo);
     exInfoSize = dynlen(exceptionInfo);
   }//if(0<dynlen(err))
   (...)

string fwUkl1ExceptionLog_getDisplayTreeName dyn_string &  exceptionInfo  ) 
 

Returns the name of the PVSS tree shape that will be used by the fwUkl1ExceptionLog_displayCB function to display the exception log data.

Parameters:
exceptionInfo Contains information about exceptions that are encountered during the function execution.
Returns:
string Name of the PVSS tree shape that will be used. This always returns the name of the current tree that has been set, however a check is made as to whether the shape exists. A none existent shape is signaled via the exceptionInfo parameter.
Example:
   (...)
   //Wish to get the current name of the tree being used by the fwExceptionLog_displayCB().
   //exceptionInfo will tell us if it is valid.
   dyn_string exceptionInfo;
   const string currentTreeDisplayName = fwUkl1ExceptionLog_getDisplayTreeName(exceptionInfo);
   //The tree name will always be what is currently in use, check for errors to see if it will work.
   if ( 0 != dynlen(exceptionInfo) ) {
     //We can use the name in functions that require a PVSS tree shape.
   }//if(0!=dynlen(exceptionInfo))
   else {
     //Tree shape is not recognised by PVSS need to take action...
   }//else(0!=dynlen(exceptionInfo))
   (...)

string fwUkl1ExceptionLog_getLogName  ) 
 

Returns the name of the current exception log.

Returns:
string Name of the current exception log.

void fwUkl1ExceptionLog_setDisplayTreeName const string &  treeName,
dyn_string &  exceptionInfo
 

Sets the name of the PVSS tree shape that the fwUkl1ExceptionLog_displayCB() should use to display the exception data.

Parameters:
treeName Name of the PVSS tree shape that is to be used. A check is made for the existance of this shape, if the shape is found not to exist then it will not be set and the tree name will be left unchanged. An exception is raised in this case.
exceptionInfo Contains information about exceptions that may have occured.
Returns:
void.

void fwUkl1ExceptionLog_setLogName const string &  logName,
bool  deleteOld,
bool  create,
dyn_string &  exceptionInfo
 

Sets the name of the data point that is to be used for the exception log. Can also be used to create the data point if desired.

Parameters:
logName Name of the log that is to be created.
deleteOld If TRUE this deletes the existing exception log, if one can be found. If FALSE any existing log is not checked for.
create If TRUE then the new exception log is created, if FALSE then it is not. It is important to note that the next call to submit will create the new exception log anyway.
exceptionInfo Contains information about any exceptions that may occur during the function call.
Returns:
void.

void fwUkl1ExceptionLog_submit dyn_string &  exceptionInfo,
string  baseNode = ""
 

Submits an exception chain to the exception log. Takes a name for the base node that the exception chain should appear under in the exception tree. If exceptionInfo is empty then the function will just return.

Parameters:
exceptionInfo Exception chain that is to be displayed. It will be cleared by a call to this function.
baseNode This is an optional parameter. It can be used to group exceptions under specific node in the exception tree and could be used, for example, to have all errors relating to a specific UKL1 board always occur beneath that node in the tree. Defaults to an empty string, in this case a unique identifier is generated for the base node.
Returns:
void.
If the exception log does not exist then one will be created, the name of which is a User defined variable in the library. If this function fails to complete an exception will be raise()d to note why it failed and then fwUkl1ExceptionHandling_display() will used to display the exception chain. In all cases the exceptionInfo dyn_string will be cleared by a call to this function.

Example

   (...)
   //Create a dyn_string to hold the exception information.
   dyn_string exceptionInfo;
   //Call a function, that could generate an error.
   thisFunction(exceptionInfo);
   //If an error has been generated it will be submitted to the log, otherwise nothing will occur.
   //All future exceptions that are submit()ted with "myNode" will be placed under the "myNode" entry in the exception tree.
   fwUkl1ExceptionLog_submit(exceptionInfo, "myNode");
   //Note that exception info is now definately empty, for example a call to fwUkl1ExceptionHandling_display() would do nothing.
   (...)


Generated on Fri Jun 8 14:46:30 2007 by  doxygen 1.3.9.1