2.10 ERROR SYSTEM
2.10.1 Basic Concepts
The purpose of the error system is to provide, at workstation level, facilities to :
· log errors generated by local processes either in the local workstation or in a remote workstation according to where the error stack is located.
· Provide tools to browse through the logged errors. (On-line Monitoring of incoming errors is provided by the logMonitor utility )
· Create and maintain the error definiton files
The complete functionality of the error system is fully supported under CCS_LITE
When an error condition is generated, in some software layer, an error context is built to allow reporting of the error condition to the upper layers.
CCS provides an error structure of type ccsERROR to store the error context. This error structure is normally filled in by the subroutine where the error occured, and passed back to the calling level.
The ccsERROR structure contains :
·
The description of the current error. The table below shows the information related to a single error description : the user is required to provide a few fields for the error description while the rest is automatically filled by the error system, as described below.
|
|
Fields to be provided by the user |
| moduleId |
Error IdentificationName of the module to which the the routine belongs. |
| Location |
Name of the routine/function where the error occurred |
| Error Number |
Error Identification : this is a mnemonic associated to each error. |
|
|
Fields Automatically filled by the error system |
| Time Stamp |
String representing the time when the error occurred. |
| envName |
Name of the environment where the stack is stored |
| procName |
Name of the process where the error occurred |
| procNum |
Process Id number |
| StackId |
Error stack Identification. This is a counter shared by all processes in the same RTAP environment, therefore the pair (Environment Name + StackId) is unique in the system.
|
| Sequence Number |
Defines the order of the error generation within the stack. The sequence number is automatically generated inside the error system. |
| Run Time Parameters |
Textual description of the error : this is a single line up to 255 characters long |
·
A stack containing all the sequence of errors generated by the lower levels. This includes errors coming from an LCU and sent back to the sender of the command through the message system.
Every layer of software receiving an error from a lower layer is allowed to modify the error structure to produce an error context having a meaning for the next higher layer. Each time a new error is `added' to the ccsERROR structure , the previous is stored in the stack and the `Sequence Number' is increased.
Therefore to handle the generation of errors by a sequence of nested routines or processes, the chain of errors is linked by the parameters Sequence Number and stackId to form a 'virtual' structure called error stack.
2.10.2 Stack Manipulation
The error generated in a routine is reported back to the calling routine.
Each ccsERROR structure has its own error stack and error are not logged until the application closes the stack or special conditions occur, such as :
· When the
environment variable errDEBUG is defined -.e.g.- setenv errDEBUG on - errors are immediately logged. This mode has been introduced to help debug the programs and see the logs associated to errors which are eventually recovered.
· When the number of logs exceeds maximum size of the error stack (
errSTACK_SIZE). In this case all errors in the stack are logged and the stack emptied : further errors are stored in the stack with increasing sequence number.
Errors are generated in a cascade sequence until either the error is automatically recovered or the 'main' of the application is reached.
The application should clean the error structure and the associated stack (
errResetStack)
· Error Cannot Be Recovered
| In a ` Routine ` |
The routine adds its own error to the existing stack (errAdd or errSysAdd )
This set of related errors are grouped together under the same error stack and a sequence number defines the order of the error generation. |
| In ` main ` |
The application can add its own error to the stack. It logs the whole stack and cleans the error structure (errCloseStack) |
Special application might generate several error stacks which need to be merged together : the routine errMergeStack provides the possibility to merge the stack of two error structures into a single one.
Error Reporting from an LCU
When the execution of a task involves processes running in a LCU -i.e.- send a command to the LCU - the mechanism of error reporting works as follows :
1. Process 'Proc1' in WS-1 ask process 'Proc2' on LCU to perform an action
2. Proc2 executes and gets into an error condition.
3. Errors generated by Proc2 are delivered to the local log server (
lccServer) which sends them to the
logManager of the WS reporting node
4. Proc2 sends back to Proc1 an error reply. This reply tells Proc1 that errors in Proc2 have occurred and are logged on WS2, with a given stackId (23).
5. When Proc1 receives the error reply, the local error structure is automatically set within the message system subroutines to the values specified in the error reply in order to identify the error stack.
· Recover the error and consequently close the stack (errCloseStack() ): last error condition is be logged, and the error context is cleared.
· Generate a sequence of errors which is logged as part of the same stack of the LCU errors.
From the application point of view the handling of errors is based on the following :
· Error generated by processes running on a LCU are logged in the WS reporting node
· Errors belonging to the same stack are logged on the same node (WS), regardless where the first error log was generated (WS or LCU)
This picture shows a simple example of handling of errors during the execution of a task involving Proc1 running on a WS1 and Proc2 running on a LCU
This picture shows an example of handling of errors during the execution of a task involving Proc1 running on WS1 and Proc2 running on a LCU, but having WS2 as error reporting node
2.10.3 Logging of Errors generated by UNIX or RTAP Routines
Routines interfaced with systems having a different error handling, namely UNIX and RTAP must use the special routine errSysAdd() which :
· Logs the errors generated in by RTAP or UNIX systems
· Sets the error structure according to the equivalent CCS error condition
The log contains the following UNIX related information :
Error Number UNIX Global error number (
errno)
Run Time Parameters. UNIX error message.
In case of error RTAP generates its own error stack and each element of the stack is logged.
The log contains the following RTAP related information :
location RTAP function name
Error Number RTAP error number
Run Time Parameters. RTAP Error errorString + messageString.
Where errorString is a textual description of the error and messageString
is an optional message usually provided by the routine that detected
the error and giving further details on the error condition.
2.10.4 Data Structures
2.10.4.1 Error Log Format
Error Logs are created via the CCS logging system, and thus are composed of three parts :
It is automatically pre-pended to the logs by the UNIX daemon process syslogd.
It is filled automatically by the logging system
It is built by the error system and contains the following elements:
Time Stamp Time when the error occurred
Process Number Process identification number.
Location Name of the routine/function where the error occurred.
Error Number Error Identification
Severity Error Severity : Warning, Serious, Fatal
StackId. Error stack Identification. This is a counter shared by all
processes in the same RTAP environment, therefore the pair
(Environment Name + StackId) is unique in the system.
Sequence Number. Defines the order of the error generation within the stack.
Run Time Parameters. Describes the nature of the error.
2.10.4.2 Error Configuration Files
The error system uses the following files :
These files must be manipulated with the errEditor utility. Do not manually edit them.
.
The Error Include File contains all the `#define' statements for all mnemonics to be included into source files.
The name of the file is moduleErrors.h (e.g. : ccsErrors.h) and it is generated automatically from the error definition file using the utility errEditor.
2.10.4.3 Error Definition File
Each VLT software module must provide an ASCII file containing the definition of all the module's errors.
Errors are defined in records with the following structure :
Error Offset Offset to be applied to the error number : it can also be defined as a
numerical expression of different offsets -e.g.- offset1 + offset2.
The numerical values of the symbols that identify the offsets must be
`defined' at the beginning of the file (see example at the end of the
Error Number It must be
greater than 0 and can be grouped in families of related errors
with a gap between error codes belonging to different families in order to
add other errors later on.
Suggestion : split the families in multiple of 10.
Error Severity Can be one of the following:
Warning,
Serious,
Fatal.
The values are identified by
W,
S and
F respectively.
Warning Returned when the requested action (Command, function)
fails but the
system is still completely under control, and
is still able to operate, possibly with degraded
Serious The system cannot perform what it was supposed to do,
but there is no neeed to shut down.
Attempts to recover can be performed manually.
Fatal The requested action cannot be performed, and the system
is left in an abnormal state which generates an ALARM.
This condition usually stops the correct functioning
of the system performing the action and requires a
shutdown to bring it back to normal.
Error Format It always starts with the error mnemonic of the error followed by a text
specifying the error condition.
The error format description looks like a 'printf format' containing
conversion specifications to be applied to the arguments describing the
Help Reference This field specifies the nameof the file containing the help information
The name of the file should be
<mnemonic>.hlp if the file contains
only references to that error.
Several helps can be also merged into a single file : in this case the name
of the file should still contain the module name and the "hlp " extension.
These files are stored under
$VLTROOT/ERRORS/HELP.
The error Mnemonic is used to identify the specific error in the programmatic interface and has the following format :
where :
<mod> Specifies the module name
mnemonic Describes the error condition. It is derived from the description of the
error condition by taking the most significant words and concatenate
them through
'_' (underscore).
The Error definition File arranges these information in three row, each containing
1. Error Number, Error Severity, Error Offset
An example of error definition file is the following :
# Error Definition File Created on Nov 22 11:39:22 1994
# This file has been generated by utility errEditor
# !!!!!!!!!!!!!! DO NOT MANUALLY EDIT THIS FILE !!!!!!!!!!!!!!
ccsERR_DB_OPEN : Failure opening (%s) database
ccsERR_DB_CLOSE : Error Closing (%s) environment
ccsERR_DB_GET_HANDLE : Cannot get handle for environment (%s)
ccsERR_DB_INV_LINK : Invalid connection identifier
ccsERR_DB_INV_ACTION : Invalid Action Code (%d)
The error definition file is generated automatically by utility
errEditor.
2.10.5 errEditor
The utility errEditor is an interactive utility which allows to create and modify the error definition file of a module.
· The utility must be run from a sub-directory of the local module.
· The environment variables VLTROOT and INTROOT must be defined.
Calling errEditor from the shell, the following GUI appears :
The Menu Bar includes the following menus :
File Menu
| New |
Create a new Error Definition File |
| Read Only` |
Read an existing error definition file without the possibility to modify it. In this mode the file is searched on both INTROOT and VLTROOT. All functions allowing the user to edit the current configuration are disabled as well as those to generate and install the error deinition file. |
| Open |
Open an error configuration files located in the current module. This mode allows the user to modify an existing file. |
| Generate Files |
Generates the the following files : - Index and Error definition files under ../ERRORS - Include file under ../include |
| Quit |
Exit the Utility. The user is warned if the error definitions have been modified and the file needs to be `saved' |
Options Menu
| Show Include File |
Displays the current error include file. |
| Show Definition File |
Displays the current error definition file. |
| Show Index File |
Displays the current error index files. |
| Cleanup Help Files |
Deletes unused help files under ../ERRORS/HELP. |
| Check All Log Formats |
Checks if there are "%s" strings and substitute them into the default "%.80s" |
Install Menu
| Install Files |
Installs the current index, error definition and include files under $INTROOT |
Help Menu
| Extended Help |
Not Yet Implemented |
The Short Help Area at the bottom of the panel is used to convey messages to the user about the completion status of an operatio
2.10.5.1 Startup
When the tool is called, the user can use the "File" menu to choose one of the following actions :
New Start a new error definition file.
All the informations are cleared and the error mnemonic is set to the <mod>ERR_
waiting for th user to complete the definition.
Open Opens an already existing error definition file from the current module
-e.g.- it look for the file in the local ../ERRORS directory.
Open Opens an already existing error definition file looking in the standard
(Read Only) VLT diectories, that is , module, INTROOT and VLTROOT.
This mode allows the user to see the file but
no editing functions
Example -
Open the error configuration files of a given module
·
Select Open in the File Menu
The lists of all error appear on the main panel and are ready for modifications.
The first error in the list is highlighted.
Example -
Open the error configuration file in Read-Only mode
·
Select Open (Read Only) in the File Menu
The lists of all error appear on the main panel and are ready for modifications.
The first error in the list is highlighted.
The "File Path" shows the directory where the error definition file was read from.
The buttons ADD, REPLACE, CLEAR and DELETE at the bottom are all disabled to prevent the user to modify the error definitions, as well as some other functions used to generate the error definition files.
2.10.5.2 Error Configuration
The upper part of the error configuration panel contains entry fields to display and modify the definition of the selected error :
Error Mnemonic It always starts with "
<mod>ERR_". If this field specifies an existing
mnemonic, the
Return displays the definition of that error, otherwise
it clear the screen and sets automatically the name of the `Help File'.
Error Number It is an integer greater than 0. If the user attempts o REPLACE the current
definition with a `0', a warning is issued.
It the user ADD a new error with a `0' error number, a new error number is
automatically generated and a message appears in the `short help' area.
Error Severity Specifies the severity of the error
Error Format The error format description looks like a 'printf format' containing
conversion specifications to be applied to the arguments describing the
The error definition file contains the list of errors associated to a given module with a numbering system starting always with 1. On the other hand sometimes it is useful to have the range of errors starting with an offset -e.g.- this applies for example to the CCS module, as shown hereafter by the initial part of the CCS database error definition file.
# Error Definition File Created on Nov 22 11:39:22 1994
# This file has been generated by utility errEditor
# !!!!!!!!!!!!!! DO NOT MANUALLY EDIT THIS FILE !!!!!!!!!!!!!!
ccsERR_DB_OPEN : Failure opening (%s) database
ccsERR_DB_CLOSE : Error Closing (%s) environment
ccsERR_DB_GET_HANDLE : Cannot get handle for environment (%s)
Several error offsets can be defined in the same error definition file and,as shown in the following example , they can also be added together.
ErrorOffset Specifies the offset to be applied to the error number. This is defined by a
mnemonic whose value can be set by pushing `Set Offset'.
Default Offset Sets the error offset to the default `mnemonic'.
The default mnemonic has the format :
<mod>ErrOffset.
Set Offset Defines the value of the mnemonic used as error offset.
It contains three buttons :
Define Offset Add the offset definition to the list : if the offset mnemonic
already exists, its value is replaced with the current one.
Delete Offset Deletes the definition of the specified offset mnemonic.
Example -
Define an offset for the error number
This example shows how to define two error offsets and assign them to the same error definition.
·
Enter the following the definition in the "Error Offset" field
modErrOffset1 + modErrOffset2
·
Click on "Set Offset ..."
·
Enter modErrOffset1 and its value 3
· Click on "Define Offset"
·
Enter modErrOffset2 and its value 2
· Click on "Define Offset"
· Click on "..." to get the list of known defined offsets
· Click on "Cancel" to quit the dialog box
2.10.5.3 Help File Configuration
An ASCII text file can be associated to each error giving more extended description of the error condition. When the user selects an error definition the tool automatically shows the associated help text by reading each time the corresponding file.
In this way the user has always the possibility during editing to go back to the original text as long as he only modifies the copy on the screen and he does not
REPLACE the error definition.
Help File Name Specifies the name of the file containing `help' information about the error.
The `help' information has a `man page' format and can be specified in the text
The generated file has a header specifying the version number for the
VLT archiving system, but it is not shown by the tool.
Help Template Replace the current `help' text with a template to be used for the help
Clear Help Clears the content of the `help' text.
Restore Help File Looks for a file with the name
helpFileName.hlp~ in the ../EERORS/HELP
directory. This file is generated when the help file is not used in the error
Removal of not used help error files
During the generation of a new error definition file, the tool collects the names of all help error files which are not used. The user is explicetly asked to get rid of those files, in such a case the tool renames those files with the name "filename.hlp~".
Therefore not used file can be recovered by clicking on Restore Help File until the module is archived and the files must be deleted from the directory -.e.g.- the utility cmmCheckForArchive will display the list of files to be deleted.
2.10.5.4 Error Navigation and Editing
Navigation through the list of errors is supported by the following command :
Mouse Selection The whole list of errors is displayed in the listbox at the top of the panel and
the user can navigate through the list using the scroll bars and clicking on
a specific error to get its definition
The selected error becomes highlighted on the main panel and its definition
appears in the error configuration panel.
Arrows Allow the user to go stepwise back and forth through the list of errors.
The current error becomes highlighted on the main panel
Search Searches for an error with the same `
Number' or `
Mnemonic' as specified by
If the error is found, it appears highlighted on the main panel and its
definition appears in the error configuration panel otherwise all configuration
fields are cleared and a message will appear in the Short Help Text
Example -
Search for an error by number
·
Choose Search Mode `by Number'
Example -
Search for an error by mnemonic
·
Choose Search Mode `by mnemonic'
At the bottom of the panel there are buttons that allow the user to modify the error definition of the currently selected error.
All changes in the error definitions (except the ones regarding the help text associated to the error) are stored in the tool and the error definition file is changed only when a new one is created.
ADD Add the error definition as specified in the form.
The tool takes care of the following cases :
·
The mnemonic already exist - the operation is aborted.
·
The error number already exist or it is 0 - the error number is automatically changed with a new one.
REPLACE Replace the current error definition with the one specified in the form.
The tool takes care of the following cases :
·
The mnemonic already exists - the operation is aborted.
·
The error number already exist - the operation is aborted.
·
The mnemonic does not exist - a new error definition with that mnemonic is automatically generated.
Beware that the file containing the help text associated to the error definition is
automatically changed if modifications to the text occurred.
CLEAR Clears all fields in the form : this can be used to add a brand new error definition.
DELETE Deletes the current error and shows the next in the list.
In case of error conditions a message appears in the `short help' area
Example -
Modify an Existing Error definition
·
Select the error definition to be modified
·
Enter the new information in the appropriate fields
Example -
Add a new Error definition
· P
ush CLEAR : all fields are ready to get the new definition
·
Enter the new information in the appropriate fields
· P
ush ADD : The new error ia added to the list.
If the specified error number or error mnemonic are already used by another error definition,
a message will appear in the Short Help Text at the bottom of the panel.
Example -
Copy an exiting definition to a new error
This is useful when the user needs to add a new definition which differ from an exiting one by small details.
·
Select the definition to be used for the new error
·
Change the error mnemonic to the new one
· Change the error number if one wants a specific value otherwise the next available value will be used.
· P
ush ADD : The new error definition is created and added to the list.
Example -
Delete an Error
The error definition is replaced with the one of the next error
2.10.5.5 Generation of Error Definition Files
The utility generates three ASCII files :
mod_ERRORS File containing the error definitions
modErrors.h Error Include File
modERRORS.IDX File used by the error system to access the definition of a specific error.
The
Install Menu Entry is used to install the generated files into the INTROOT directory.
This is typically used during development.
2.10.6 Programmatic Interface
The programmatic interface consist of the following routines :
errResetStack This routine initializes the current error structure and must be used at the
beginning of each application and whenever an error condition has been
recovered.
A call to errResetStack is included in ccsInit, therefore the error
structure is automatically initialized at the beginning of the application.
However, if several error structures must be used simultaneously, all
but the one already initialized in ccsInit must be initialized with this
errSetStack() Sets the error strucure returned by VLT routines according to the error
reply sent from another process. (
Used internally by the message system)
errAdd This routine allows the application to log the error generated by the
previous routine and to modify the returned error structure of the
current routine according to the local error condition.
The CCS routines must be interfaced with systems having a different error handling, namely UNIX and RTAP. This cases are handled by the special routine errSysAdd.
errSysAdd This routine allows the application to log the error generated routines
belonging to SW packages which do not belong to the VLT software .
In addition it modifies the returned error structure of the current routine
according to the local error condition.
errConvRtapErr It takes the top error of the RTAP error stack and converts it into an
equivalent CCS error number. This normally used after a call to a
RTAP routine in order to get the error number to pass to errSysAdd().
errCopy() Copy the current `error context' of one ccsERROR structure into another.
The associated stack is not copied : this routines has been introduced
for backward compatibility with the programs which made use of memcpy
to copy error structures.
errMergeStack() Merge the stack associated to two different error structures into a single one.
The destination error structure will contain the merging of the two stacks.
errPrint() Prints on the screen the content of the error structure with the following
Environment : wte13 StackId : 3 Sequence : 4
Process Number : PROC_NUM Process Name : errBasicTest
Environment : WSName StackId : 15 Sequence : 2
Error Number : 7 Severity : W
Module : mod Location : errBasicTest.c
Error Text : modERR_LINK : Failure on channel ( 15 )
errCloseStack It is used when the application reaches the top level and the last error of the
sequence cannot be recovered. The error contained in the local error
structure is logged, the stack closed and it resets the local error structure.
errDisplay() Calls the error dialog to notify the user about an application error and
disappears only wher the user acknowledge the presence of the error.
The error dialog provides the following information :
- Name of the Process where the error occurred
It is used when the application reaches the top level and the last error of the
sequence cannot be recovered : during the execution the
stack is closed
and the local error structure reset
A flag controls whether the application is suspended until the user
The dialog contains two button :
-
OK Acknowledge the error and quit the error dialog
-
Show Stack Allows the user to see the whole error stack.
The utility errShowStack is used to displays a given the
error stack as described in the next paragraph.
-
Show Help Displays the help page associated to the error.
The error dialog is by default called during the execution of errDisplay,
but the user can use the
environment variable NO_ERR_DISPLAY
to change the behaviour as follows :
-
setenv NO_ERR_DISPLAY : the error dialog is not called during the
execution of errDisplay() and the error structure is printed on the screen.
-
unsetenv NO_ERR_DISPLAY :resumes the default behaviour
errIsReason It allows the user to look for a specific error in the error stack.
The routine scans the error stack until it finds an error matching both
<moduleId> and <errorNumber> or it reaches the end.
errInStack This is a simplified version of errIsReason returning a boolean value
according to whether the current stack contains an error or not
errLccToCcs Converts LCC errors to equivalent CCS errors : it takes the error at the
top of the stack and converts the error number into the equivalent CCS
2.10.7 Run-Time Checks
From version 2.33 of the error system we have introduced a run-time check to control if the user has passed the right number of arguments to the routines
errAdd and
errSysAdd. This check is especially important if the number of parameters is less than the number of `conversion specifications' used in the error format string, because it can end up with unexpected results.
Beside the correct case, the check can find that the number of parameters passed by the user can be bigger or lesser than the number of required arguments and it will process the two cases differently as described here after.
For a better explanation let's suppose to log an error with the following error format :
modERR_OPEN_FILE : Cannot access file ( %.80s )
The user provided `more' parameters than expected.
In this case the error system process the error which will correctly appear in the log file, but it also generate another log as a warning that the number of parameters passed by the user was too big.
<timeStamp> ... WARNING:error modERR_OPEN_FILE in errTestProtected.c called with too many arguments (2) expected (1)}
<timeStamp> ... errTestProtected.c 3 31 2 S modERR_OPEN_FILE: Cannot access file ( /a/b/myfile )
The user provided `less' parameters than expected.
In this case the error system cannot process the error, but it will log enough information to allow the user to trace back where in the code the error comes from. If this case is applied to the above error format, the erro system would log the following message :
2<timeStamp> ... errTestProtected 222 62 errTestProtected.c 3 29 2 S modERR_OPEN_FILE : Cannot process error too few arguments (0) expected (1)}
2.10.8 Utility errShowStack
This utility displays the set of errors belonging to a given stack :
the stack is displayed with the top-most error as first element.
For each error only the relevant parameters ( such as : error mnemonic , location , etc ..) are shown.
Additional information can be obtained by clicking on an error, and the bottom part is updated to show other parameters, such as : module name,process, date, etc ..
Get Help On Error Opens an additional window showing the "help" file associated to the
2.10.9 Diagnostic Logs
In case of errors the error system routines generate appropriate logs which are listed in each routine description. Examples of such errors can be : the error structure is a NULL pointer, failure reading a new stack identifier, wrong module identifier, etc
The following table specifies for each routine the possible error conditions and the associated log.
|
|
|
| Routine errAdd
NULL Pointer in error structure
Wrong ModuleId
Wrong Error Number |
(errAdd) parameter error is a NULL pointer
Cannot Access ERRORS/<module>ERRORS.IDX from INTROOT or VLTROOT
No Error Format available |
| Routine errCloseStack
NULL Pointer in error structure |
(errCloseStack) parameter error is a NULL pointer |
| Routine errDisplay
NULL Pointer in error structure |
(errDisplay) parameter error is a NULL pointer |
| Routine errMergeStack
NULL Pointer in error structures
Resulting stack is too big |
(errMergeStack) NULL pointer in parameter list
(errMergeStack) Stack (%d) TOO BIG : merging only top %d elements |
Routine errResetStack
NULL Pointer in error structure
|
NULL pointer to error structure |
Routine errSysAdd
NULL Pointer in input parameters
Not Existing sysModule
Wrong Error Number
|
(errSysAdd) parameter error or sysModule is a NULL pointer
(errSysAdd) not valid parameter sysModule <sysModule>
No Error Format available
|
| Other Internal Routines |
|
| Failure accessing the CCS Shared Memory Area
Failure retrieving the error definition file.
Error Stack is full |
Cannot get new error stack Id. This is reported only once , when the process starts.
Environment variable VLTROOT Not defined This file must exists at least under VLTROOT
(errPutInStack) Error Stack %-8d is FULL |
2.10.10 Programming : Rules and Examples
This section contains general remarks on the use of the error system routines.
· Refer to an error number by its mnemonic
· Refer to the module identifier through a
`#define' statement.
· Use the pre-compiler symbol
__FILE__ to indicate for the location parameter in errAdd() and errSysAdd().
· Parameter `format' in errAdd and errSysAdd is not used, so use an empty string (
"") instead. It is there for compatibility with LCC.
· Use the defined symbols
modRTAP and
modUNIX to identify parameter sysModule of routine errSysAdd to identify the RTAP or UNIX systems respectively.
This section contain examples of use of the error system routines with the following conventions :
·
<mod> represents a generic name for a module
· Only the code related to the handling of errors is shown
· Comments between the lines of the code are shown in
italic
EXAMPLE 1 : Shows which are the error functions to be used in the application's main and for which purposes.
int main (int argc, char *argv[])
ccsInit(argv[0],0,NULL,NULL,&error) /* This routine contains a call to errResetStack() */
if ( <mod>Funct1( ... , &error) == FAILURE )
The error cannot be recovered and there is no need to notify the user.
The errCloseStack() functions logs the whole error stack and then resets the error structure.
if ( <mod>Funct1( ... , &error) == FAILURE )
The error cannot be recovered and the user should be notified.
The application waits the user's acknowledgment before continuing.
The errDisplay() functions pops up the error dialog box showing the description of the last error in the stack
errDisplay(&error,ccsTRUE);
if ( <mod>Funct1( ... , &error) == FAILURE )
if (error.errorNumber == <mod>ERR_xxx)
errCloseStack(&error); /* Error cannot be recovered */
else if (error.errorNumber == <mod>ERR_yyy)
The error can be recovered : the errResetStack function clears the error structure.
insert code to recover the error ...; /* Error can be recovered */
EXAMPLE 2 : Shows how to process error conditions in a function : routine <mod>Funct1 calls another routine of the same module.
ccsCOMPL_STAT ccsFunct1 (.... , ccsERROR *error);
if (ccsFunct2(... ,error) == FAILURE)
if (error can be recovered)
The error can be recovered : the errResetStack() function clears the error structure.
The error cannot be recovered and the error must be returned back to the calling functions.
The errAdd() function sets the error context to the new error condition and adds the current error to the error stack.
errAdd(error,ccsMSG,ccsERR_MSG_SEND,__FILE__,"",p2);
EXAMPLE 3 : Shows how to process error conditions generated by a UNIX function.
Routine <mod>Funct2 makes a call to a UNIX routine and to a CCS routine. The errors generated by the UNIX routine is handled by errSysAdd which logs the generated UNIX error and sets the returned error structure error context to the associated error of module <mod>
ccsCOMPL_STAT <mod>Funct2(... , ccsERROR *error)
if ((fileHandle = open(filename,O_RDWR)) == -1)
The UNIX error is stored in the stack and the error context is set to the description given by the error mnemonic specified in the errSysAdd() function.
errSysAdd(error,<mod>,<mod>ERR_OPEN_FILE,__FILE__,"", modUNIX,filename);
if (dbReadSymbolic(...) == FAILURE)
errAdd(error,<mod>,<mod>ERR_READ,__FILE__,"",pointName);
EXAMPLE 4 : Shows how to process error conditions generated by a Rtap function.
Routine dbReadSymbolic calls a RTAP routine. The errors generated by the RTAP routine are handled by errSysAdd which logs the generated RTAP error and sets the returned error structure error context to the CCS error.
ccsCOMPL_STAT dbReadSymbolic( ... , ccsERROR *error)
if (rtReadDatabase(dbHandle,&readInfo) == FAILURE)
errConvRtapErr(&ccsErrNumber); /* Convert the RTAP error number */
/* into CCS error number */
case ccsERR_DB_INV_POINT:
case ccsERR_DB_INV_ALIAS:
errSysAdd(error,ccsDB,ccsERR_DB_INV_NAME,__FILE__,"", modRTAP,fullName);
errSysAdd(error,ccsDB,ccsERR_DB_READ,__FILE__,"", modRTAP,fullName);
EXAMPLE 4 : Shows how to propagate an error reply to the upper layers by using the built-in features of msgParseMsg().
ccsCOMPL_STAT <mod>Funct3 ( ... , ccsERROR *error)
/* send, for example, a message to an LCU */
/* Wait for the message reply */
if (msgRecvMsg(... , error) == FAILURE)
/* Process error condition ...*/
The name of the local error structure and the name of the structure containing the error reply is the same.
In this case the routine errParseMsg() automatically merges the two stacks.
if (msgParseMsg(... , error, error) == FAILURE)
/* Process error condition ... */
if (msgType == msgTYPE_ERROR_REPLY) {
Parameter `error' now containes the merging of local error structure and the reply error.
The errAdd() function sets the error context to the new error condition and adds the current error to the error stack.
errAdd(error,ccsMSG,ccsERR_MSG_SEND,__FILE__,"",p2);
/* Process other cases ... */
EXAMPLE 5 : Shows how to merge two error stacks.
ccsCOMPL_STAT <mod>Funct3 ( ... , ccsERROR *error)
if (<mod>Funct4(... , &err1) == FAILURE)
errMergeStack(error,&err1,errBOTTOM);
The errAdd() function sets the error context to the new error condition and adds the current error to the error stack.
errAdd(err1,<mod>,<mod>ERR_XXX,,__FILE__,"",...);
2.10.11 General Remarks
Error Menmonics
CCS already provides detailed information on the error conditions regarding operations such as : send a message, access the database, etc ..
Therefore applications built on top of CCS should use error menmonics addressing the functionality of the application rather than logging too detailed error description.
Here is an example of error stack generated by CCS showing that the first logs of the stack contain the detailed information on the reason why an operation failed. (For clarity only the text of the logs are reported).
rtE_DB_INV_POINT: Invalid Point in address REASON> Unresolved relative point name ``point1''
rtE_DB_INV_POINT: Invalid Point in address REASON> input::point1.attrName
rtE_DB_INV_POINT: Invalid Point in address REASON> :point1.attrName
ccsERR_DB_INV_NAME: Illegal DB name ( :point1.attrName)
ccsERR_SCAN_NEGOTIATION : Negotiation failed.
2.10.12 Configuration
none
Define the following environment variables
VLT_HELP_ROOT Defines the location of the error help files and is set to
2.10.13 Reference
errAdd() Logs the error (if any) generated at lower level and sets the returned error
structure according to the local error condition.
errCloseStack() Logs the error and resets the local error structure.
errConvRtapErr() Converts RTAP errors to equivalent CCS errors.
errCopy() Copies the current error context into another error structure.
Introduced for backward compatibility in place of memcpy.
errDisplay() Calls the error dialog to notify the user about an application error and waits
for the user acknowledgment.
errInStack() Returns a boolean value indicating if a given erro is in the stack.
errIsReason() Searches for a specific error in the error stack and returns its description
errLccToCcs() Converts LCC errors to equivalent CCS errors
errMergeStack() Merge stacks from two different error structures into a single one.
errPrint() Prints the error structure on the screen
errPrintStderr() Prints the error structure on the Stderr device
errResetStack() Resets the error structure returned by VLT routines
errSetStack() Sets the error strucure returned by VLT routines according to the error
errSysAdd() Logs the errors generated by UNIX or RTAP routines and set the returned
error structure according to the local error condition.
err.h Contains constants, types and function prototypes of the logging system
errEditor Interactive utility to create and modify the error configuration files.
errShowStack Utility to display all error belonging to a given error stack.
