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).
int ret_code = iimPlay ( String macro [, int timeout] )
- 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).
(2) iimPlay ("c:\MyMacros\macro1.iim") - Full path*
(3) iimPlay ("Test\macro1") - Relative path* to the iMacros Macros folder
(4) iimPlayCode ("URL GOTO....") (old: iimPlay ("CODE:URL GOTO....") => Code Example, Tips: see note below.
For example: "c:\\MyMacros\\macro1.iim"
- int timeout
- The optional timeout value. If iimPlay does not return before 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 several timeouts inside a macro. The iimPlay timeout is typically triggered by a browser crash, a browser freeze or if the macro runtime exceeds this value.
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 Scripting Interface specific error codes that deal with unexpected errors timeouts or browser crashes.
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.iimOpen() 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.iimOpen() iret = imacros.iimPlayCode(mycode)
- The recommended method for playing a macro generated on-the-fly is to assign the entire macro to a single string and then use one call to iimPlayCode to play the macro. While it is possible to use multiple calls to iimPlayCode to play each line of your macro separately, keep in mind that each time you call iimPlay or iimPlayCode, 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 Editor "Code Generator" (in the File menu) for converting your macro to inline code, or use the standalone iMacros Code Creator (no longer supported but still works well!).
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 -1700 error code. In the corresponding error message (see iimGetErrorText) the maximum index is given. You can use this value, for example, to always select the last entry of a changing drop down list.
ret = iim1.iimOpen("-fx") ret = iim1.iimPlay("MyScript.js")