ErrSet

Sets the error-checking mode. When Mode is set to 0 and an error occurs that causes a component to stop executing, Citect SCADA halts the execution of the Cicode task that caused the error, and generates a hardware error.

You can perform error checking by setting Mode to 1 and using the IsError() function to trap errors. When the type of error is determined, you can control what happens under particular error conditions. Errset(1) can be used for parts of Cicode when task termination is undesirable, working around the underlying issue in the Cicode. After executing ErrSet(1), Citect SCADA will not automatically check for errors, and the user can manually check for errors using the Cicode function IsError() after a line of code is executed.

Note: ErrSet(1) is NOT global, and when used it will only affect all functions within the particular thread in which it has been called. It is recommended that you apply ErrSet() around specific small segments of Cicode that are problematic (i.e. single Cicode statements), and not around large sections of code.

The operation of the ErrSet function is unique to each Cicode task. If you enable user error checking for one task, it does not enable error checking for any other tasks.

It is important to note that ErrSet(1) and ErrSet(0) are intended to be used in pairs. When a thread starts, the error check level is 0 (Citect SCADA will halt your code on errors). Each time ErrSet(1) is called, the level is incremented by 1 (with a maximum of 1000). When ErrSet(0) is called the level is decremented by 1 (with a minimum of 0). Citect SCADA will only halt your code on errors if the error check level equals 0. It does not cause a problem to call ErrSet(1) when the level is already 1000, or to call ErrSet(0) when the level is already 0. The code will just continue to run at the current error check level.

If each function calls ErrSet(1) and ErrSet(0) in pairs, there won't be a problem. However, much user Cicode does not do this reliably. For example, if there are multiple RETURN statements in a function it would need to have an ErrSet(0) before each return to make sure the level was reset. It's also common practice to put ErrSet(1) at the beginning of each function with no corresponding ErrSet(0). To avoid problems, you can use the ErrSetLevel() function instead of ErrSet(). It allows you to set the level to any number (0 - 1000), but could be used to just set it to 0 or 1 to enable or disable Citect SCADA's automatic error checking instead of letting the error check level build up to higher numbers.

Syntax

ErrSet(Mode)

Mode:

Error-checking mode:

0 - default - Citect SCADA will check for errors.

1 - The user needs to check for errors.

Return Value

0 (zero) if successful, otherwise an error is returned.

Related Functions

IsError, ErrSetHw, ErrSetLevel

Example

ErrSet(1);
Test=Var/0;

DevWrite(hDevice, "data to write");
nError=IsError();
! Sets Error to 273 (divide by zero).

Example

If you wish to find code that does not correctly use ErrSet(), you can set the citect.ini parameter [Code] EnableErrorLogging=1 This parameter is available in Citect SCADA 7.50 Service Pack 1, Patch 7 and later. When enabled, it will log an error message and the Cicode function stack to the syslog file when the error check level reaches 100 or 1000:

ErrSet: Error check level has reached 100; usually this means there are mismatches between ErrSet(1) and ErrSet(0). Call Stack:

ReadFile(10001 {Good});

hFile            = 100 {Good, 2016-10-21T10:55:26}

nRow             = 100 {Good, 2016-10-21T10:55:26}

ErrSet: Error check level has reached 1000; usually this means there are mismatches between ErrSet(1) and ErrSet(0). It won't be increased any more. Call stack:

ReadFile(10001 {Good});

hFile            = 1000 {Good, 2016-10-21T10:55:26}

nRow             = 1000 {Good, 2016-10-21T10:55:26}

Example

Since the ErrSet() state persists until the thread terminates, it is good to avoid leaving it in a different state than it was when your function started. For example, the following code checks if a page exists (which would cause a fatal error if it doesn't exist). This could be called from various other Cicode functions in the project. So, it uses ErrSetLevel() but saves the previous level number that is returned. At the end of the function it sets the previous error level again.

// Returns TRUE if the specified page exists, otherwise returns FALSE

INT FUNCTION PageExists(STRING sPage)

INT nErrLevelPrev = ErrSetLevel(1);

IsError();               //Reset the last error number

PageFileInfo(sPage, 0);

ErrSetLevel(nErrLevelPrev);

RETURN IsError() = 0;    //Any error indicates PageFileInfo() failed

END

See Also

Error Functions

Published June 2018