Report Help file errors here (Part 2)

[JohnOne]

Indeed, I was just illustrating that SetExtended() does not return second value parameter to anything else but Itself.

And that is part of the ambiguity.

[Melba23]

guinness,

I am assuming you were addressing me - if not my apologies for my presumption.

expandcollapse popup

###Function###
SetError

###Description###
Manually set the value of the @error (and optionally @extended) macro.

###Syntax###
SetError ( code [, extended = 0 [, return value = 1 ]] )


###Parameters###
@@ParamTable@@
code
    The required value (integer) to set into the @error macro.
extended
    [optional] The required value (integer) to set into the @extended macro.  This sets the 

same macro as the SetExtended() function.
return value
    [optional] The value to be returned by the function - defaults to 1 if no parameter used.
@@End@@

###ReturnValue###
The return value parameter (default = 1)
@error and @extended will be set to the values set in the function call (both default = 0)


###Remarks###
When entering a function @error is set to 0.  Unless SetError() is called, then @error will 

remain 0 when the function ends.  This means that in order for @error to be set after a function, 

it must be explicitly set. This also means you may need to backup the status of @error in a 

variable if you are testing it in a While-WEnd loop.
The extended parameter is optional. It is provided as a way to set both @error and @extended at 

the same time. If only @extended needs set, then it is recommended to use the SetExtended() 

function instead.
@error is limited between the values of -2147483647 to 2147483647.


###Related###
SetExtended


###Example###
@@IncludeExample@@

#include <Constants.au3>

$vRet = Example()

MsgBox($MB_SYSTEMMODAL, "", "Return value = " & $vRet & @CRLF & _
                            "Value of @error is: " & @error & @CRLF & _
                            "Value of @extended is: " & @extended)

Func Example()
    Return SetError(3, 10, "Return value")
EndFunc

M23

[Melba23]

JohnOne,
 

SetExtended() does not return second value parameter to anything else but Itself

As Mhz has explained, the function is really meant to be used with Return when the return value parameter has some meaning. I quite agree that it has no use when the function is called elsewhere, but then does it really matter in that case?

For example, why bother to check the return value to the SetExtended function here:

#include <Constants.au3>

$vRet = Example(5)

MsgBox($MB_SYSTEMMODAL, "", "Return value = " & $vRet & @CRLF & _
                            "Value of @error is: " & @error & @CRLF & _
                            "Value of @extended is: " & @extended)

Func Example($vVar)
    If $vVar > 10 Then
        SetExtended(-1)
    Else
        SetExtended($vVar)
    EndIf
    Return
EndFunc

M23

[JohnOne]

I know and you know how to properly use it M, but I'm certain beginners wont.

Definitely a better example you made too, but if it's meant to be used with return then it probably ought to be documented.

As should the fact it always returns either the value to pass or 1, even if it fails to set @extended when passed a bad parameter.

In the spirit of making the help file concise and accurate is all really.

Cheers M23.

[AZJIO]

SetError(1)

The expected value should be 0.

[guinness]

Thanks Melba23 for that.

[czardas]

After thinking about the earlier discussion about the == operator in AutoIt v3.3.9.13 beta, I would like to suggest the following subtle difference. It might make a difference - then again comparisons of unknown variable type may be something you want to avoid (I'm all for it):

Current statement:

This operator should only be used for string comparisons that need to be case sensitive.

 

Replace with:

This operator should only be used if string comparisons need to be case sensitive.

Edited July 31, 2013 by czardas

[guinness]

Done.

[czardas]

That was quick - thanks. If a dev says change it back then I'll shut up.

[guinness]

You're welcome. Do you mean forever? 0_-

[czardas]

Do you mean forever? 0_-

 

No don't be silly. Sometimes I just feel like I put my foot in my mouth. It's very easy to misinterpret things of great complexity such as exist in programming, and wording things can be very difficult.

Edited July 31, 2013 by czardas

[jchd]

Sometimes I just feel like I put my foot in my mouth.

 

Geez, you're more flexible than I am.

I simply say BS. It's more effective to look like a jerk and that never break bones nor inflict painful postures to joins. QED

[czardas]

@JCHD - I like using these obscure idioms. It's good for the advanced non-native speakers of English to encounter them. By the way, I pasted some words of your sentence into Google (postures to joins) and it came up with Yoga (the perfect solution).

Edited July 31, 2013 by czardas

[jchd]

That's what I had in mind, up to that!

[MHz]

SetError(1)

The expected value should be 0.

I agree. The sane default return value for SetError and SetExtended is 0.

Bug Ticket #2375

It is the code that requires the fixing. It has needed fixing since the very beginning. Hopefully good reason will succeed for change.

[jaberwacky]

The link for Opt in the online helpfile is a 404: http://www.autoitscript.com/autoit3/docs/functions/Opt.htm

[jaberwacky]

The Function definition for _FileWriteFromArray is not the same as that described by the helpfile.

Func _FileWriteFromArray($File, $a_Array, $i_Base = 0, $i_UBound = 0, $s_Delim = "|")

_FileWriteFromArray ( $sFilePath, ByRef Const $aArray [, $iBase = Default [, $iUBound = Default [, $sDelimeter = "|"]]] )

Oh, nevermind.  Control+J brought me to the production definiton even though I have beta installed. Edit: Silly me I assumed that beta would take over the main spot for hotkeys. oops.

Anyways, $aArray is declared const byref which seems to be pretty much unnecessary.

Edited August 1, 2013 by jaberwocky6669

[guinness]

The link for Opt in the online helpfile is a 404: http://www.autoitscript.com/autoit3/docs/functions/Opt.htm

Already fixed. But the changes are behind the scenes for now.

Anyways, $aArray is declared const byref which seems to be pretty much unnecessary.

I will leave it I think, but I know what you mean.

[guinness]

Unofficial guidelines I have been using for creating the Examples. Through trial and error & feedback from the Devs.

• If the example is more than say 5 lines, wrap in a function called Example. Just use common sense with this point.
• Follow UDF standards for variable renaming. (Only for consistency purposes.)
• Use descriptive comments.
• Don't use magic numbers. If you need to, then think about adding a constant value to the appropriate constant UDF.
• Use MsgBox instead of ConsoleWrite, as not everybody uses SciTE or an editor that captures StdOut.
• Don't use 3rd specific applications e.g. AutoItWrapper directives unless necessary.
• Use Tidy on the example.
• Ensure the example passes #AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7
• Use appropriate variable declaration, if it's not a Global variable then don't declare it as Global e.g.

#include <Constants.au3>

Local $vVar = "Some variable" ; This variable is in "Global space", but it's not referenced anywhere else and thus is Local.
Global $sGlobal = "This is used inside functions." ; This variable is Global as it's used outside of the spope it was declared in.

MsgBox($MB_SYSTEMMODAL, "", $vVar)

Func SomeFunc()
    ; Do something.
    Local $sString = "String"
    ConsoleWrite($sString & @CRLF)
EndFunc   ;==>SomeFunc

Func AnotherFunc()
    ; Do something.
    Local $sStringEx = $sGlobal ; Just an example guys!!!
    ConsoleWrite($sStringEx & @CRLF)
EndFunc   ;==>SomeFunc

[czardas]

I agree. The sane default return value for SetError and SetExtended is 0.

Bug Ticket #2375

 

In the ticket you say:

Functions default to a 0 return value.

 

I am wondering if this is a general statement, or just for SetError() and SetExtended(). The reason I ask is that some UDF functions return 1 on success. I presumed the authors knew what they were doing and copied this behaviour.

---

@jchd I can't really get my foot in my mouth. I could have done it a few years back.

Edited August 1, 2013 by czardas