Richard,

I think that those examples are special cases that return EXTENDED information, and return 0 on success, the opposite of what this and many other functions do.

As for the rest of the comments...

If you expect a function to return non-zero data, it should return zero or null in the case of an error, and exit with the error value. This allows
Code:

If Func()
  ; got a reply - don't care, just do!
Else
  ; No reply - there's a problem, check @ERROR
EndIf

- or -
Code:

$X = Func()
If $X
  ; got a reply - OK to process the data
Else
  ; No reply - there's a problem, check @ERROR
EndIf


Conversely, if a function normally does not return specific data, it is helpful to return status info (which may or may not be the ERROR code). Look at the ExistKey/KeyExist functions. These return Status, one inverted, the other "fixed" to return true. The original one returned "success", which wasn't too helpful when doing simple "If ExistKey()" tests. The newer function returns status, not error info.

Think about your Open example.. the sample in the book looks something like
Code:

If Open(1, 'Filename', 2) = 0

Which is generally what I see in UDFs that use it. However, consider
Code:

$RC = -3
$Ct = 0
While $RC = -3 And $Ct < 10
  $RC = Open(1, 'Filename', 2) = 0
  $Ct = $Ct + 1
  If $RC = -3  Sleep .5 EndIf
Loop

This allows code to be more robust in an environment where many copies of a script may need to access a file. This is a simplified example, but should illustrate the point of checking the status returned.

In this UDF example, and the one Doc is referring to, the UDF returns a specific value - valid data. Even worse, the UDFs return strings of numbers (Strings, because they may have dashes). Returning a pure number as an error is counter-intuitive. It should return a null (empty string) if it usully returns strings, and a zero if it usually returns numbers. If returning zero as a numeric value is valid, then the calling code should ALWAYS check the ERROR macro.

Mode A - Either I get data (non-zero, non-null) or I don't, and if I don't, I check the ERROR macro for more info.

Mode B - I don't expect data, so if I get some, it's a problem and should check the value further, and possibly the @ERROR macro.

One last example.. Consider a UDF that updates some data repository (file, database, registry). It normally returns nothing, indicating success. It performs a "complex" validation process before writing the data, and if it fails validation, it exits with error 87.

Hmm, bad data. What kind of bad data?
The value returned might have the following meanings:
0 = Success
-1 = Out of Bounds - Low
1 = Out of Bounds - High
2 = Incorrect data type (not number)
3 = Null value supplied
4 = System Error

Of course, a return of 4 would indicate that some other error occurred, and would be identified by the exit value in the ERROR macro.

Bottom line, I'm definitly against arbitrarily returning ERROR values as data unless the conditions warrant as outlined above.

Glenn
_________________________
Actually I am a Rocket Scientist! \:D