error using IELinkClickByText

[philkryder]

I'm getting some results where objects cease to be objects which causes errors.

So, I've become more meticulous with error checking after function calls.
In the code below, I've reproduced a simple example from the example 1 script in the AutoIt help for _IELinkClickByText

I get a return value of -1, which the AutoIt help indicates should set @error and @extended.
But,
As seen in the console log below,  
$vReturn is a -1, but, both @error And @extended are 0.
I had expected that the return of -1 would be accompanied by one of the @error values of 1-9 and @extended would indicate which parameter was the cause.
? what concept am I missing here? Thanks! PhilKryder

; Open browser with basic example, click on the link with text "user forum"

#include <IE.au3>

    Local $vReturn
    Local $iErrorSave
    Local $iExtendedSave

    Local $oIE = _IE_Example("basic")
    $vReturn = _IELinkClickByText($oIE, "user forum")

    $iErrorSave =  @error
    $iExtendedSave = @extended




    Local $sMsg
        $sMsg = ""
        $sMsg = $sMsg &  (@CRLF) &  ("   $vReturn>" &$vReturn & "<" )
        $sMsg = $sMsg &  (@CRLF) &  ("   $iErrorSave>" & $iErrorSave & "<" )
        $sMsg = $sMsg &  (@CRLF) &  ("   $iExtendedSave>" & $iExtendedSave & "<" )
        $sMsg = $sMsg &  (@CRLF)


    ConsoleWrite ($sMsg)

===========================Begin Console Log:
>"C:\Program Files\AutoIt3\SciTE\..\AutoIt3.exe" "C:\Program Files\AutoIt3\SciTE\AutoIt3Wrapper\AutoIt3Wrapper.au3" /run /prod /ErrorStdOut /in "R:\Operations\MacroTools\_autoitTesting\reproducers\_IELinkClickByText.au3" /UserParams    
+>15:18:21 Starting AutoIt3Wrapper v.15.920.938.0 SciTE v.3.6.0.0   Keyboard:00010409  OS:WIN_7/Service Pack 1  CPU:X64 OS:X86    Environment(Language:0409)
+>         SciTEDir => C:\Program Files\AutoIt3\SciTE   UserDir => C:\Users\Pkryder\AppData\Local\AutoIt v3\SciTE\AutoIt3Wrapper   SCITE_USERHOME => C:\Users\Pkryder\AppData\Local\AutoIt v3\SciTE 
>Running AU3Check (3.3.14.2)  from:C:\Program Files\AutoIt3  input:R:\Operations\MacroTools\_autoitTesting\reproducers\_IELinkClickByText.au3
+>15:18:22 AU3Check ended.rc:0
>Running:(3.3.14.2):C:\Program Files\AutoIt3\autoit3.exe "R:\Operations\MacroTools\_autoitTesting\reproducers\_IELinkClickByText.au3"    
--> Press Ctrl+Alt+Break to Restart or Ctrl+Break to Stop

   $vReturn>-1<
   $iErrorSave>0<
   $iExtendedSave>0<
+>15:18:35 AutoIt3.exe ended.rc:0
+>15:18:35 AutoIt3Wrapper Finished.
>Exit code: 0    Time: 15.62
======================= end Console Log

From AutoIt Help:
Return Value

Success:	none.
Failure:	0 or -1 and sets the @error flag to non-zero.
@error:	1 ($_IEStatus_GeneralError) - General Error 2 ($_IEStatus_COMError) - COM Error in Object reference 3 ($_IEStatus_InvalidDataType) - Invalid Data Type 4 ($_IEStatus_InvalidObjectType) - Invalid Object Type 6 ($_IEStatus_LoadWaitTimeout) - Load Wait Timeout 7 ($_IEStatus_NoMatch) - No Match 8 ($_IEStatus_AccessIsDenied) - Access Is Denied 9 ($_IEStatus_ClientDisconnected) - Client Disconnected
@extended:	Contains invalid parameter number

[mLipok]

I be able to check this night 

[philkryder]

any help?

[Danp2]

Looking at the code, it consistently returns 0 when an error has occurred and -1 on success.

[mLipok]

@philkryder you find an obvious bug in this UDF, as when you look in:

Func _IELinkClickByText(ByRef $oObject, $sLinkText, $iIndex = 0, $iWait = 1)
    If Not IsObj($oObject) Then
        __IEConsoleWriteError("Error", "_IELinkClickByText", "$_IESTATUS_InvalidDataType")
        Return SetError($_IESTATUS_InvalidDataType, 1, 0)
    EndIf
    ;
    Local $iFound = 0, $sModeLinktext, $oLinks = $oObject.document.links
    $iIndex = Number($iIndex)
    For $oLink In $oLinks
        $sModeLinktext = String($oLink.outerText)
        If $sModeLinktext = $sLinkText Then
            If ($iFound = $iIndex) Then
                $oLink.click()
                If @error Then ; Trap COM error, report and return
                    __IEConsoleWriteError("Error", "_IELinkClickByText", "$_IESTATUS_COMError", @error)
                    Return SetError($_IESTATUS_ComError, @error, 0)
                EndIf
                If $iWait Then
                    _IELoadWait($oObject)
                    Return SetError(@error, 0, -1)
                EndIf
                Return SetError($_IESTATUS_Success, 0, -1)
            EndIf
            $iFound = $iFound + 1
        EndIf
    Next
    __IEConsoleWriteError("Warning", "_IELinkClickByText", "$_IESTATUS_NoMatch")
    Return SetError($_IESTATUS_NoMatch, 0, 0) ; Could be caused by parameter 2, 3 or both
EndFunc   ;==>_IELinkClickByText

Then you can see there is:

Return SetError($_IESTATUS_Success, 0, -1)

According to the HelpFile it should be like this:

Return SetError($_IESTATUS_Success, 0)

You can find the same bug in other IE function, for example _IEImgClick()

 

mLipok

 

Edited October 11, 2015 by mLipok

[philkryder]

so, 
Is this a help file error that will be fixed in the docs?
Or,
Will IE.AU3 be changed?

Do the mods watch for things like this
or, should I open an error report?

also, in the short term, should I ignore the return value and just check @error?

One last thing, 
When the help reads that the SUCCESS return is NONE - 
What does that mean? 
What exactly gets assigned when functions return NONE?
Am I correct in using a Variant?

Edited October 11, 2015 by philkryder

[BrewManNH]

The function could return anything when the Success value is stated as none, in other words you are not to rely on the return value except to look for an error condition. Supposedly, as long as the return value isn't 0 or -1, then it wasn't an error.

[kylomas]

 Supposedly, as long as the return value isn't 0 or -1, then it wasn't an error.

That is not the way I'm reading the Help file.  Your original statement is correct...

The function could return anything when the Success value is stated as none 

So I read that as "the return value is meaningless if @‌ERROR = 0".  In this case I think the return value is meaningless regardless of success or failure and only @ERROR should be used to determine success/failure.

@‌mlipok - Do you think there is a bug because @‌EXTENDED is set to -1?

kylomas 

[mLipok]

@‌mlipok - Do you think there is a bug because @‌EXTENDED is set to -1?

No.

This function set @extended = 0

 

HelpFile says:

Failure:

0 or -1 and sets the @error flag to non-zero.

and BrewManNH is right

as long as the return value isn't 0 or -1, then it wasn't an error.

This function return -1 and exactly this showing to us OP repro snippet    $vReturn>-1<
This function works correctly (clicking in link), but return value is misleading , and this is a bug.

Because in function _IELinkClickByText

Return SetError($_IESTATUS_Success, 0, -1)

 @error  is set to $_IESTATUS_Success and Return Value as -1 which according to HelpFile mean Failure

So why this function return $_IESTATUS_Success together with -1 ?

After all -1 mean Failure <> $_IESTATUS_Success

I hope now I make this clear.

 

mLipok

Edited October 12, 2015 by mLipok

[BrewManNH]

I just remembered a thread that DaleHolm posted in regards to the IE UDF a few years back when I complained about the return values.

It's a design choice to have an ambiguous return value, and you should only be checking for @error.

 

[mLipok]

So this is realy strange "design choice" but also issue with the documentation (exactly like DaleHohm said).
As many other function in this UDF return 1 as success and 0 as failure (_IEAction , _IEFormElementSetValue, _IEFormReset ....)

Thanks for this link @BrewManNH

mLipok

[philkryder]

The function could return anything when the Success value is stated as none, in other words you are not to rely on the return value except to look for an error condition. Supposedly, as long as the return value isn't 0 or -1, then it wasn't an error.

part of my question was what does NONE mean? is it a null string or some kind of "nothing" object?

I'm now thinking that the DOCs are simply wrong and should read that the return is always -1,
and we should check @error instead. Is it always the case in UDFs that @error will always be ZERO 
If the UDF ran successfully?
Or,
are there some/any failures that return @error of Zero?

Thanks to you folks who showed that the final arbiter of documentation is to go read the code itself.

Since it has been a couple of years since the link that BrewManNH gave, 
??To whom do we address suggestions for help file changes?

 

 

 

 

 

 

[mLipok]

Is it always the case in UDFs that @error will always be ZERO 
If the UDF ran successfully?
Or,
are there some/any failures that return @error of Zero?

It would be very bad written UDF.

You can read here:

https://www.autoitscript.com/autoit3/docs/function_notes.htm

.....

@error = 0 ;is always success

.....

@error is always set to 0 when entering in a function.

....

 

 

 

 

Thanks to you folks who showed that the final arbiter of documentation is to go read the code itself.

It is always good to look in UDF function to learn, and in some case to search for issues solutions.

 

 

[BrewManNH]

part of my question was what does NONE mean? is it a null string or some kind of "nothing" object?
I'm now thinking that the DOCs are simply wrong and should read that the return is always -1,
and we should check @error instead. Is it always the case in UDFs that @error will always be ZERO 
If the UDF ran successfully?

When the return value is listed as returning NONE you should infer that the return value could be anything, or nothing, or null, or giraffes, or aardvarks, etc.  

Don't rely on the return value from functions that have that as the return value. Look for errors in @error. If errors aren't returned in @error, then the function is poorly written and needs a rewrite, which isn't the case in these functions. 

Also, if the help file says an error is indicated by returning -1 and it returns -1 on success, then it is wrong plain and simple.

 

[kylomas]

Don't rely on the return value from functions that have that as the return value. Look for errors in @error. If errors aren't returned in @error, then the function is poorly written and needs a rewrite, which isn't the case in these functions. 

Also, if the help file says an error is indicated by returning -1 and it returns -1 on success, then it is wrong plain and simple.

Pretty much what I said in post #8.  Dale's response in the link that BrewmanNH pointed to explains this perfectly.

@‌Milpok - This is what I thought you were referring to as a bug 

If $iWait Then
                    _IELoadWait($oObject)
                    Return SetError(@error, 0, -1)
                EndIf
                Return SetError($_IESTATUS_Success, 0, -1)

As you can see @‌EXTENDED is returned as -1 even though the function succeeded.  The return value is irrelevant as pointed out by Dale. 

I think we're pretty much all saying the same thing and it's nothing more than possible Help file ambiguity/contradiction/inconsistency/bug, you choose one.

This should probably be corrected given that new users are having trouble interpreting this.  I haven't looked at the work you are doing in the re-write but would be glad to assist with whatever testing/doc review you require.

kylomas

 

 

 

[BrewManNH]

@‌Milpok - This is what I thought you were referring to as a bug 

If $iWait Then
                    _IELoadWait($oObject)
                    Return SetError(@error, 0, -1)
                EndIf
                Return SetError($_IESTATUS_Success, 0, -1)

As you can see @‌EXTENDED is returned as -1 even though the function succeeded.  The return value is irrelevant as pointed out by Dale. 

 

No, Extended is returning 0, and the return value is -1, the second parameter is @extended, and the third is the return value. It's not a bug,but a documentation error.

 

I think we're pretty much all saying the same thing and it's nothing more than possible Help file ambiguity/contradiction/inconsistency/bug, you choose one.

This should probably be corrected given that new users are having trouble interpreting this.  I haven't looked at the work you are doing in the re-write but would be glad to assist with whatever testing/doc review you require.

I agree, the help file should be fixed, it's wrong as I pointed out 2 years ago, and hasn't been fixed. I thought it would have been fixed, but it appears that it hasn't.

[mLipok]

After all I agree this is "Documentations case", not the UDF.

 

I haven't looked at the work you are doing in the re-write but would be glad to assist with whatever testing/doc review you require.

Thanks.
Any help would be greatly appreciated.

 

mLipok

[kylomas]

No, Extended is returning 0, and the return value is -1, the second parameter is @extended, and the third is the return value. It's not a bug,but a documentation error.

D'oh...

@‌mLipok - Anything I can do...I'm prep'ing for a colonoscopy this week so my time is yours and the shitters...I'm going to take a look tonight at what you've been posting so far...  

[BrewManNH]

DI'm prep'ing for a colonoscopy this week so my time is yours and the shitters...I'm going to take a look tonight at what you've been posting so far...  

I've been there and done that, you won't be anywhere near a computer for more than 5 minutes at a time, unless you have a laptop on the toilet.

 

[kylomas]

Yea, had one 3 years ago...20 hours of prep for 45 minutes of stick'in and click'in...I'm scheduled at noon so it's gonna be a long night.