iimPlay()

From iMacros
Revision as of 17:35, 25 February 2011 by Td (Talk | contribs)

Jump to: navigation, search

Plays a macro. After the macro has played all options that have been set with the iimSet command are reset. Use iimGetLastExtract to get the extracted text. Upon the next iimPlay() call, internal variables like !TIMEOUT_PAGE and !EXTRACT for instance, will also be reset to their default values.

There are two fundamentally different ways of playing a macro using the iimPlay command. The first is to specify the filename (without the extension) of the macro in the String macro parameter. The other is to generate macro code on-the-fly in your program, preceded by "CODE:", and pass it directly to iimPlay via the String macro parameter (see note below).

Syntax

int ret_code = iimPlay ( String macro [, int timeout] )

Parameters

  • String macro
    Either the macro's filename without the extension, a string holding macro commands or the macro code.

(1) iimPlay ("demo-download") - If you just supply the macro name, iMacros looks for the file in the standard macro folder (as specified in the Options dialog or iim.ini file).
(2) iimPlay ("c:\MyMacros\macro1.iim") - Full path
(3) iimPlay ("CODE:URL GOTO....") => Code Example, Tip: To convert text macros (iim files) into inline code use the free iMacros Code Creator.

  • int timeout
    The optional timeout value. If the command is not completed during this time span, the Scripting Interface returns a timeout error -3. No extraction data is returned in this case. The default value is 600 seconds. This is the timeout for the overall macro runtime. This value should not be confused with the timeout inside a macro, which is the timeout for a single macro step.. The iimPlay timeout is typically triggered by a browser crash, a browser freeze or if the macro runtime exceeds this value.

Error Handling

iimPlay returns a detailed error code for every problem encountered. Please see the Scripting Interface Return Codes and the general iMacros Error-Codes, which are transmitted via the iimPlay command back to the calling application.

The return codes of iimPlay can not only be used to deal with "big" issues such as web browser crashes etc, but are often simply used to react to missing elements on a website. So if an element is not found on a website, and then the TAG command reports an error, and iimPlay returns this error to the script. Example: If you extract book ISBN numbers, some books may not have an ISBN number and the TAG command reports a "not found" error.

The error codes of iimPlay are exactly the same that you get from the iMacros Browser/IE/Firefox itself. In addition, there there Interface specific error codes that deal with unexpected errors timeouts or browser crashes.

Examples

Play a macro located in the Macros\ directory of your iMacros installation (Visual Basic Script example):

Dim imacros, iret 
Set imacros = CreateObject("imacros") 
iret = imacros.iimInit() 
iret = imacros.iimPlay("mymacro") 

Play some on-the-fly generated code (Visual Basic Script example):

Dim imacros, iret, mycode, myURL 

myURL = "http://www.iopus.com"  

mycode = "URL GOTO=" + myURL + vbNewLine 
mycode = mycode + "TAG POS=1 TYPE=FONT ATTR=TXT:<SP><SP>Online<SP>Store" 

Set imacros = CreateObject("imacros") 
iret = imacros.iimInit() 
iret = imacros.iimPlay("CODE:" + mycode)

Firefox

In the iMacros for Firefox built-in Javascript Scripting Interface you have the option to add the relative path to the iimPlay command. Example: If your Javascript (JS) file is in the main directory, but the macros are in the "test1" subdirectory, then please use iimPlay ("test1/yourmacro"). (Note: This feature will be added to the general Scripting Interface in the near future, too.)

Notes

CODE:

  • The correct way for playing a macro generated-on-the fly is to assign the entire macro to a single string and then use one call to iimPlay to play the macro. Do not use iimPlay("CODE: ...") to play each line of your macro separately. Each time you call iimPlay, all of the iMacros internal variables are reset, and this can produce undesired results if you call each line of your macro this way.
  • Several commands in a macro generated on-the-fly must be separated by the CR (carriage return) symbol. These are vbNewLine or vbCrLf in Visual Basic or \r\n in C, C++ or C#.
  • Use the iMacros Code Creator for converting your macro to inline code. It's free and very handy and convenient!

Drop-down list boxes

  • If you start a macro via iimPlay which contains a TAG TYPE=SELECT... statement and the specified value is not in the drop down list then the iimPlay command returns an -251 error code. In the corresponding error message (see iimGetLastError) the maximum index is given. You can use this value, for example, to always select the last entry of a changing drop down list.

See Also

iimInit, iimDisplay, iimExit, iimGetLastError, iimGetLastExtract, iimTakeBrowserScreenshot