ExecScriptFile (function)
Allows PlanetPress Design documents to execute the content of an external script file. The document waits until the script has completed before resuming its own execution.
Note: This function does not support printer centric mode; results are undefined.
Syntax
ExecScriptFile(filename: string, parameters: string, scriptlanguage: integer) 
integer
Arguments
filename
Fully qualified path and name of the script to call and execute.
parameters
User-defined string value allowing a document to pass additional information to the script, such as data selections, PlanetPress Talk variables, etc..
scriptlanguage
The programming language in which the script is written. The valid values are:
| 0 | Auto-detect based on file extension: VBScript (.vbs) | JavaScript (.js) | Perl (.pl) | Python (.py) |
| 1 | VBScript |
| 2 | JavaScript |
| 3 | Perl |
| 4 | Python |
Return value
Successful execution of the external script file will return 0 by default, although this value may be set by users through the Script (system object) system variable. Note that some negative values are internally used to indicate different types of failure, always using negative values, which means conflicts may happen when users set the Script.ReturnValue variable with an existing negative value. The proper practice is thus to return only positive values.
Here are the existing negative values:
| -1 | Script file does not exist or is not accessible. |
| -2 | Invalid script language. |
| -3 | Error during script execution. |
Use of PlanetPress APIs within called scripts
When a script is called from within PlanetPress Design using ExecScriptFile(), all of the PlanetPress environment is available to the script, including the Watch, Metadata, Capture and Alambic objects.
Using these objects from a script within a Design document is not supported and can lead to unexpected results. Furthermore, setting a Watch variable or job info from within the script will not return this value to the document, as these values are always passed once when the document is called, never during execution.
Accessing Parameters from the script
The parameters value is a string which is sent to the executed script. It is available using the Script.Paramstring system variable from within the code. If you want to send multiple parameters, you will have to separate them with a special character and use this character as a separator to split the string or create an array with it, such as (example in JavaScript):
params = Script.Paramstring.split(";")
Code Example
ExecScriptFile('c:\myScript.vbs', 'name;'+@(1,1,10), 1)
Sample Scripts
2 sample scripts are available with any PlanetPress Suite installation.
They are are located in C:\Documents and Settings\All Users\Application Data\Objectif Lune\PlanetPress Suite N\Scripts, where N is the PlanetPress Suite version number. These 2 sample scripts are used by PlanetPress Design's Excel Graph functionality, allowing to insert a business graphic from a Microsoft Excel file.