| Previous Topic (None) | Up (Contents) | Next Topic (Scripting) |
Scripting Overview
Scripts can be used to customize various aspects of Deadline, including creating custom plug-ins, submitting jobs to the queue, or automating specific tasks after a job completes. The scripting language that Deadline uses is Python, which is integrated into Deadline using IronPython. The benefit to using IronPython is that the it makes the .NET libraries available to programmers, while maintaining full compatibility with the Python language. See the IronPython documentation for more details.
In addition to running scripts in the context of plug-ins, Monitor scripts, or Job scripts, you can also run general scripts from the command line using Deadline Command. For example, if you have a script called c:\myscript.py, you could execute it using this command:
DeadlineCommand -ExecuteScript "c:\myscript.py"
General Deadline Scripting Functions
These are some general Deadline functions that can be called from your scripts, regardless of the context in which they are used. To use them, you must use this import line in your script:
from Deadline.Scripting import *
String Utilities
All functions are called by using StringUtils.function
| Function | Description |
| string[] FromSemicolonSeparatedString( string list, bool allowEmptyTokens ) | Returns a string array from a semicolon separated string. You have the option to allow empty tokens. |
| string[] FromSemicolonSeparatedString( string list ) | Returns a string array from a semicolon separated string. |
| string[] FromCommaSeparatedString( string list, bool allowEmptyTokens ) | Returns a string array from a comma separated string. You have the option to allow empty tokens. |
| string[] FromCommaSeparatedString( string list ) | Returns a string array from a comma separated string. |
| string ToCommaSeparatedString( string[] list, bool includeSpaces ) | Converts a string array to a semicolon seperated string. |
| string ToSemicolonSeparatedString( string[] list, bool includeSpaces ) | Converts a string array to a semicolon seperated string. |
| string GetNumeralKeyFromPath( string pathWithNumeralKey, char[] numeralKeyChars ) | Retrieves the numeral key (based on the specified numeral key characters) from the specified path. |
| string GetNumeralKeyFromPath( string pathWithNumeralKey, char[] numeralKeyChars, bool allowEmptyNumeralKey ) | Retrieves the numeral key (based on the specified numeral key characters) from the specified path. If allowEmptyNumeralKey is False, an InvalidOperationException will be thrown if the specified path doesn't contain a numerical key. |
| string ReplaceNumeralKey( string pathWithNumeralKey, string numeralKey, int index, bool padExtra ) | Replaces the specified numeralKey in the specified path with the specified index. If padExtra is True, extra padding will be added if necessary to ensure the entire number is inserted into the numeral key. |
| string ToZeroPaddedString( int value, int length ) | Creates a string of the desired length containing the given value, padded with zeros. |
| string ToZeroPaddedString( int value, int length, bool strictLength ) | Creates a string of the desired length containing the given value, padded with zeros. The strictLenght< value indicates whether or not to allow the length of value to be greater than the length specified. |
| bool IsEmpty( string str ) | Checks if the specified string is empty. |
| string RemoveWhitespace( string str ) | Removes all whitespace from the specified string, including tabs and end of line characters. |
| string Pad( string str, int desiredLength, char fillCharacter ) | Pads the specified string with the fill character to achieve the desired length. |
| float ParseLeadingNumber( string list ) | Parses the number at the begining of the specified string. |
Path Utilities
All functions are called by using PathUtils.function
| Function | Description |
| bool IsPathLocal( string path ) | Returns True if the path has the root 'c:', 'd:', or 'e:'. |
| bool IsPathLocal( string path, string root ) | Check if the root of the given path matches the given root. |
| bool IsPathLocal( string path, string[] roots ) | Check if the root of the given path matches any of the roots in the given array. |
| bool IsPathUNC( string path ) | Returns True if the path is a UNC path. |
| bool IsPathRooted( string path ) | Returns True if the path rooted. |
| string ToPlatformIndependentPath( string path ) | Replaces all slashes in the path with the proper slash depending on the platform. |
| string ChangeFilename( string path, string filename ) | Changes the filename in the path. |
| string MapNetworkPath( string localPath, string remotePath, string username, string password, bool force ) | Maps a network path. If no authorization is required, you can leave the username and password blank. |
| string MapNetworkPath( string localOrRemotePath, bool force ) | Unmaps a network drive. |
Frame Utilities
All functions are called by using FrameUtils.function
| Function | Description |
| bool FrameRangeValid( string frameRange ) | Returns True if the given frameRange is a valid Deadline frame range. |
| int[] Parse( string frameRange ) | Converts the frame string to a frame list. The frames are automatically placed in ascending order. |
| int[] Parse( string frameRange, bool reorderFrames ) | Converts the frame string to a frame list. The frames are automatically placed in ascending order if reorderFrames is True. |
| string GetFrameStringFromFilename( string filename ) | Returns the padding of the specified filename. |
| int GetFrameNumberFromFilename( string filename ) | Returns the number obtained from the specified filename's padding. |
| int GetPaddingSizeFromFilename( string filename ) | Returns the length of the padding for the specified filename. |
| string GetLowerFrameFilename( string filename, int startFrame, int paddingSize ) | If the directory that the specified file is in contains a range of filenames with similar padding, the filename with the lowest frame number is returned. |
| int GetLowerFrameRange( string filename, int startFrame, int paddingSize ) | If the directory that the specified file is in contains a range of filenames with similar padding, the lowest frame number is returned. |
| int GetUpperFrameRange( string filename, int startFrame, int paddingSize) | If the directory that the specified file is in contains a range of filenames with similar padding, the highest frame number is returned. |
| int SubstituteFrameNumber( string filename, int frame ) | Returns the specified filename with its padding replaced with the specified frame number. |
| string GetFilenameWithoutPadding( string filename ) | Returns the specified filename with its padding removed. |
| int RequiredPaddingSize( int frame ) | Returns the minimum length of the padding required for the specified frame number. |
Process Utilities
All functions are called by using ProcessUtils.function
| Function | Description |
| Process SpawnProcess( string executable ) | Spawns a process. |
| Process SpawnProcess( string executable, string arguments ) | Spawns a process. |
| Process SpawnProcess( string executable, string arguments, string workingDirectory ) | Spawns a process. |
| Process SpawnProcess( string executable, string arguments, string workingDirectory, ProcessWindowStyle windowStyle ) | Spawns a process. |
| Process SpawnProcess( string executable, string arguments, string workingDirectory, ProcessWindowStyle windowStyle, bool redirectStdOutput ) | Spawns a process. |
| Process ShellExecute( string filename) | Shell executes the specified filename. |
| Process ShellExecute( string filename, string verb ) | Shell executes the specified filename using the specified verb. |
| bool WaitForExit( Process process, int timeoutMilliseconds ) | Waits for a process to exit. |
| bool IsProcessRunning( string name ) | Checks if a process is running. |
| bool KillProcesses( string name ) | Kills all processes with the given name. |
| bool WaitForProcessToStart( string name , int timeoutMilliseconds ) | Returns True if the process with the given name starts before the timeout. |
Script Utilities
All functions are called by using ScriptUtils.function
| Function | Description |
| string GetRootDirectory() | Returns the root directory of the Deadline repository. |
| string GetPluginsDirectory() | Returns the plugin directory of the Deadline repository. |
| string GetSlavesDirectory() | Returns the slaves directory of the Deadline repository. |
| string GetPulseDirectory() | Returns the pulse directory of the Deadline repository. |
| string GetJobsDirectory() | Returns the jobs directory of the Deadline repository. |
| string GetJobDropDirectory() | Returns the drop jobs directory of the Deadline repository. |
| string GetLimitGroupsDirectory() | Returns the limit group directory of the Deadline repository. |
| string GetUsersDirectory() | Returns the users directory of the Deadline repository. |
| string GetSettingsDirectory() | Returns the settings directory of the Deadline repository. |
| string GetSubmissionDirectory() | Returns the submission directory of the Deadline repository. |
| string GetTrashDirectory() | Returns the trash directory of the Deadline repository. |
| string GetUsersHomeDirecotry() | Returns the home directory of the Deadline client. |
| string GetUsersSettingsDirectory() | Returns the user settings directory of the Deadline client. |
| string GetDeadlineTempPath() | Returns the temp directory of the Deadline client. |
| array GetPluginNames() | Returns the list of plugin names. |
| array GetPoolNames() | Returns the list of pool names. |
| array GetGroupNames() | Returns the list of group names. |
| array GetSlaveNames() | Returns the list of slave names. |
| array GetPulseNames() | Returns the list of pulse names. |
| array GetJobIds() | Returns the list of job IDs. |
| array GetArchivedJobIds() | Returns the list of archived job IDs. |
| array GetLimitGroupNames() | Returns the list of limit group names. |
| array GetUserNames() | Returns the list of user names. |
| array GetSubmissionScriptFilenames() | Returns the list of monitor submission script filenames. |
| array GetMonitorJobScriptFilenames() | Returns the list of monitor job script filenames. |
| array GetMonitorSlaveScriptFilenames() | Returns the list of monitor slave script filenames. |
| array GetGeneralScriptFilenames() | Returns the list of general monitor script filenames. |
| void LogText( string line ) | Writes to the log of the application calling the script (either the Monitor or the Slave). |
User Interface Scripting
If you are creating scripts for the Monitor, or to be executed using Deadline Command, you have ability to create user interfaces to gather data from the users. This is a necessity when creating Submission scripts, and comes in handy when creating other scripts as well. All user interface development is done obtaining a reference to the ScriptDialog object, and calling this reference's member functions. To get a reference to this object, use this line of code:
scriptDialog = DeadlineScriptEngine.GetScriptDialog()
Now you can use this reference to create and show a dialog as shown here:
scriptDialog.SetSize( 200, 400 ) scriptDialog.SetTitle( "This Is A Script Dialog" ) scriptDialog.AddRow() scriptDialog.AddControl( "Label", "LabelControl", "Enter Data", 80, -1 ) scriptDialog.AddControl( "TextBox", "TextControl", "", 100, -1 ) scriptDialog.EndRow() scriptDialog.ShowDialog( False )
Check out the submission scripts in \\your\repository\scripts\Submission for excellent examples on how to create your own dialogs and retrieve the data from the user.
Script Dialog Member Functions
There are many more member functions available, all called using scriptDialog.function.
| Function | Description |
| void SetSize( int width, int height ) | Sets the size of the dialog. |
| void SetTitle( string title ) | Sets the dialog's title. |
| void SetIcon( string filename ) | Sets the dialog's icon to the icon provided by the given filename. |
| void ShowDialog( bool modal ) | Shows the script dialog. |
| void CloseDialog() | Closes the dialog. |
| void AddRow() | Add a new row to the dialog. |
| void Endrow() | Ends the current row. Should be called after the controls have been added to the current row. |
| void AddTabControl( string name, int width, int height ) | Add a new tab control to the dialog with the given name. |
| void EndTabControl() | Ends the current tab control. Should be called after the tabs have been added to the current tab control. |
| void AddTab( string name ) | Add a new tab to the current tab control, where the given name is the text that appears on the tab. Must be called between calls to AddTabControl() and EndTabControl(). |
| void EndTab() | Ends the current tab. Should be called after the controls have been added to the current tab. |
| ScriptControl AddControl( string name, string type, object defaultValue ) | Adds a basic control to the dialog with a default width and height. |
| ScriptControl AddControl( string name, string type, object defaultValue, int width, int height ) | Adds a basic control to the dialog with the given width and height. |
| ScriptControl AddRangeControl( string name, string type, float defaultValue, float min, float max, int decimals, float increment ) | Adds a range control to the dialog with a default width and height. |
| ScriptControl AddRangeControl( string name, string type, float defaultValue, float min, float max, int decimals, float increment, int width, int height ) | Adds a range control to the dialog with the given width and height. |
| ScriptControl AddSelectionControl( string name, string type, object defaultValue, string filter ) | Adds a selection control to the dialog with a default width and height. The filter option is only used when adding file browser selection controls. |
| ScriptControl AddSelectionControl( string name, string type, object defaultValue, string filter, int width, int height ) | Adds a selection control to the dialog with the given width and height. The filter option is only used when adding file browser selection controls. |
| ScriptControl AddComboControl( string name, string type, string defaultValue, string[] items ) | Adds a combo box control to the dialog with a default width and height. |
| ScriptControl AddComboControl( string name, string type, string defaultValue, string[] items, int width, int height ) | Adds a combo box control to the dialog with the given width and height. |
| ScriptControl AddRadioControl( string name, string type, bool defaultValue, string groupName ) | Adds a radio button control to the dialog with a default width and height. All radio buttons in the same group will automatically check/uncheck themselves when another radio button is checked. |
| ScriptControl AddRadioControl( string name, string type, bool defaultValue, string groupName, int width, int height ) | Adds a radio button control to the dialog with the given width and height. All radio buttons in the same group will automatically check/uncheck themselves when another radio button is checked. |
| object GetValue( string name ) | Returns the value of the control identified by the name specified. |
| void SetValue( string name, object value ) | Sets the value of the control identified by the name specified. |
| bool GetEnabled( string name ) | Returns whether or not the control identified by the name specified is enabled. |
| void SetEnabled( string name, bool enabled ) | Sets whether or not the control identified by the name specified is enabled. |
| array GetItems( string name ) | Returns the items in the combo box control identified by the name specified. |
| void SetItems( string name, array items ) | Sets the items in the combo box control identified by the name specified. |
| void LoadSettings( string filename, string[] controlNames ) | Loads the sticky settings for the controls specified in the controlNames. |
| void SaveSettings( string filename, string[] controlNames ) | Saves the sticky settings for the controls specified in the controlNames. |
Script Dialog Controls
These are the different controls that can be added to the dialog.
| Control Type | Control Group |
| SeparatorControl | Basic |
| LabelControl | Basic |
| TextControl | Basic |
| MultilineTextControl | Basic |
| ReadOnlyTextControl | Basic |
| CheckBoxControl | Basic |
| ButtonControl | Basic |
| PoolComboControl | Basic |
| GroupComboControl | Basic |
| DependencyControl | Basic |
| LimitGroupControl | Basic |
| MachineListControl | Basic |
| OnJobCompleteControl | Basic |
| MultiFileBrowserControl | Selection |
| FileBrowserControl | Selection |
| FileSaverControl | Selection |
| FolderBrowserControl | Selection |
| RangeControl | Range |
| SliderControl | Range |
| ComboControl | Combo |
Script Dialog Events
You can set up events to call functions when a value for a particular control has been modified. First, you need a reference to the control you want to create the event handler. Every function that adds a control to the Script Dialog returns a reference to the control that was just added. For example:
textControl = scriptDialog.AddControl( "MyTextControl", "TextControl", "This is a test" )
Then to create the event handler, add the following:
textControl.ValueModified += TextValueChanged
Finally, you need to define the handler function:
def TextValueChanged( *args ):
...
do something
...
Again, there are many examples of this in the Submission scripts found in \\your\repository\scripts\Submission.