Using JavaScript in T/HIS

Using JavaScript in T/HIS.

Human-readable JavaScripts need to be compiled , meaning turned from something human-readable into a set of instructions that a computer can understand; and then run in their compiled form. They can be changed and rerun in their modified form at any time without having to exit and re-enter T/HIS, making the "write, test, modify, re-test" development cycle very quick and easy.

Compiling and Running a script

Run Will both compile and run the script unless it contains syntax errors, in which case it stops with an error message when compilation fails. Debug Starts the JavaScript debugger, JaDe to debug the script. Check Only compiles the script, reporting any errors found, and does not run it. Encrypt A script can be encrypted so that the source code is hidden but the script can still be run (when compiling and running the script T/HIS decrypts the file in memory). Once encrypted, the source code cannot be retrieved by an ordinary user, so make sure that you keep the original file somewhere safe. As a last resort contact Oasys Ltd Support, who can decrypt the script if required. If a script is split up into separate files by Use, the files are all combined together into the main file before encrypting. Merge If a script is split up into separate files by Use, the files are all combined together into a single file. This may be useful if you want to give the script to someone else and you do not want to have to give lots of different files. GUI Builder Opens the GUI Builder to interactively build GUIs for your script. Running Enables you to view (and kill) any scripts that are currently running

Knowing which scripts are running

When scripts are running in T/HIS, they are shown in the Running submenu.

Use the Running button to toggle between the list of scripts that are currently running, and the tree of available scripts.

To kill/terminate a running script, highlight the script(s) in the tree and press Kill.

Alternatively, to kill all the scripts that are currently running use Kill all.

File encodings for scripts

Version 10.0 of T/HIS introduced the ability for unicode text to be used on widgets created in a script. Previous versions of T/HIS only supported English text so the default ASCII encoding was used for script files (this is still the default encoding for script files).

If you want to use unicode text in widgets then you must use a file encoding that is capable to representing the unicode 'characters' you require. The File encoding popup allows you to change the file encoding used when reading the script file. T/HIS supports the following file encodings:

Please contact Oasys Ltd Support if you have problems or require another encoding to be supported.

To show the unicode text the appropriate font must be used. This can be set using the preferences this*cjk_unix_font and this*cjk_windows_font .

Dealing with errors in scripts

Script errors come in two forms:

Garbage Collection memory size Whenever a javascript creates an object, array or string variable, some memory needs to be allocated by the computer. When the variable goes out of scope (is no longer reachable) this memory needs to be returned. This is done automatically in JavaScript by a process called garbage collection. The garbage collection process runs periodically when this memory use reaches a certain level. To be able to do this, the garbage collection process itself also requires a small amount of memory to keep track of all of the variables. Prior to version 22.0, this garbage collection memory was a fixed size and had to be allocated before any scripts could run. The default size for this was 25Mb and there was a textbox on the script panel to change this to a larger value if required.. In T/HIS 22.0 the garbage collection memory is now expanded automatically as required to run the script(s). There is no longer any need to give the garbage collection memory size, so the textbox to specify the memory has been removed.  However, if you know in advance that your script has to retain a large number of objects, arrays, strings etc in memory then it might be beneficial to start the script with a larger memory, rather than letting T/HIS gradually increase the memory.  This can be done using the this*javascript_memory_size preference or adding a special memory comment at the top of the script. The maximum size of garbage collection memory that T/HIS can allocate is 4Gb. Note that this is the memory for the 'garbage collection' process, NOT the total memory for the script. The total memory for the script could be significantly higher than this value. If T/HIS is being run on a machine that is shared by several users and you want to limit the size of the memory for scripts, rather than expanding it automatically to 4Gb you can use the preference oasys*javascript_maximum_memory_size

Assigning Scripts to Shortcut Keys If a script is to be run repeatedly, it can be convenient to set up a shortcut to it. From within the JavaScript menu the script can be assigned to one of the 12 function keys. Alternatively, the JavaScript can be assigned to any key using the Shortcut menu. Maintaining a library of JavaScripts It is also convenient to have a library of scripts in a defined location. By default T/HIS looks in $OA_INSTALL/this_library/scripts , but you can define a different directory by setting the preference: this*script_directory: some_different_directory_name in your oa_pref file. All scripts found in the relevant directory will be listed in the JavaScript panel, as shown in this example.

Using the "description:" comment at the top of a script to identify its purpose.

To help to identify scripts special comments are searched for in the top 10 lines of each script, and if description: is found, for example the comment line:

// description: Some description of the script's purpose

Then the description line is shown as hover text when the mouse is placed over that filename. For example the line:

// description: Colour curve by model number

Will result in the hover text " Colour curve by model number " appearing when the mouse hovers over the button to launch the script.

Using the "name:" comment at the top of a script to change its name

Normally the name shown for a script will be its filename, stripped of any leading pathname and trailing ".js" extension.

However if the string name: is found in the first ten lines of the script, then the following name will be used instead. For example the line:

// name: Colour By Model

Will result in the script appearing with the name " Colour By Model " in tha JavaScript panel. This does not affect the actual name of the script, only the name on its library button.

Using the "memory:" comment at the top of a script to change the initial garbage collection memory

Very occasionally the initial memory required for garbage collection needs to be changed.

If the string memory: is found in the first ten lines of the script, then the size given will be used for the memory (unless the size in the memory textbox is larger than this value). For example the line:

// memory: 50

Will result in the script initially using 50Mb for garbage collection memory.  T/HIS will automatically expand the memory required for garbage collection as necessary. See Garbage Collection Memory Size for more details.

Using the "encoding:" comment at the top of a script to change the encoding

By default the encoding used for scripts is LATIN1

If the string encoding: is found in a comment on the first twenty lines of the script, then the encoding will automatically be used for the script. The allowed values are UTF8 or UTF-8 for UTF- 8 encoding and ShiftJIS , Shift-JIS or sjis for Shift-JIS encoding.

For example the line:

// encoding: UTF8

Will result in the UTF-8 encoding being used for the script.

Using the "module:" comment at the top of a script for ES6 modules

T/HIS has to compile scripts that use ES6 modules differently to 'normal' scripts. If a script has the extension .mjs then T/HIS will automatically compile the script to use ES6 modules. Alternatively, if the file has a different extension, the module comment can be used to tell T/HIS that this file needs to be compiled to support ES6 modules.

If the string module: TRUE is found in a comment on the first twenty lines of the script, then the script will be compiled with ES6 module support.

For example the line:

// module: TRUE

Will result in the script being compiled with ES6 module support.