Running scripts with Hull Clone

Hull Clone is a command line utility that allows standalone batch processing in a CADMATIC Hull project. You can use JavaScript with the Hull Clone feature to execute heavy operations such as updating or recalculating all blocks, updating hull shapes and changes of reference planes, and preparing blocks for CADMATIC Outfitting. This can be done with any machine that has access to project data.

The Hull Server can be put in a Models only mode for faster generation of 3D models. In this mode, not all logistical data is being calculated, it is only meant for generating missing 3D models. This mode can only be enabled from Hull Clone ( executeInHullServer("models_only on")).

Hull Clone uses the MuJS JavaScript interpreter to parse the JavaScript code. MuJS implements ECMAScript specification ECMA-262. Any JavaScript code supported by ECMA-262 can be used in the Hull Clone scripts. For information about the MuJS JavaScript interpreter, visit https://mujs.com.

Important: The Hull Clone feature requires a Hull Structure license to be present, but the license will not be used. Also the license server name must be defined. Hull Clone reads the license server host name from the %DM_NLC_HOST% environment variable. If this value is not available, Hull Clone will not run. The license server host name can be defined when installing CADMATIC Hull, as License Server on the License page of the Setup Wizard.

Running scripts

To use Hull Clone you run the hullclone.exe executable file from the Windows Command Prompt window. The hullclone.exe file is by default located in the %ncgbin% folder (C:\cadmatic\<project folder>\nupashull\windowsNT\ncgbin\).

When running hullclone.exe, you must first define the path to the target project and then enter the commands. Optionally you can specify a JavaScript file to be run. Paths to the target project and the JavaScript file can be absolute or relative (relative to the folder where Hull Clone is run from). In a COS (distributed) project Hull Clone works inside the Hull subfolder of the project folder <project>.pms. However, only the project folder needs to be specified in the command line. Hull Clone will automatically add the subfolder.

  1. At start-up, hullclone.exe accesses the project specified in the command line, sets the required environment variables, starts a hull server, and either a NAPA or HDB shape database.

  2. Once this initialization is done, the code contained in the JavaScript file specified in the command line is executed.

Syntax

{hullclone} {/c dde|tcp_ip} {/debug} {Hull project} {JavaScript} {--|/jsArgs js_arg_1 js_arg2 .... js_argn}

Where:

  • {hullclone} is the path to the CADMATIC Hull installation folder including the path \nupashull\windowsNT\ncgbin\hullclone.

  • {/c dde|tcp_ip} – the option /c is used to enable TCP/IP communication or to explicitly enable DDE communication. If not given, the default communication method is DDE.

  • {/debug} is the option to output also the debug messages.

  • {Hull project} is the path to the project folder \projects2021T2\Present2021T2, for example.

  • {JavaScript} is the script including the path: \myscripts\Hull_Clone\recalculate.js.

  • {--|/jsArgs js_arg_1 js_arg2 .... js_argn} is the option to pass values from the command line directly to the JavaScript engine. The values must be preceded either by two dashes -- or /jsArgs. Any value which is separated with a space and is placed after one of these options will be added to the JavaScript variable process.argv.

Variables and commands

In addition to the standard JavaScript functions supported by ECMA-262, the following CADMATIC Hull specific variables and commands are available. A global array holding the block names is also available.

Variable

Type

Description
blocks String array A list of the names of each block in the project that is not shadowed at the current site

process.argv

String array

All command line parameters that are separated with a space and given to the Hull Clone executable after a double dash -- or /jsArgs.

Command

Argument

Return type

Description

blockFolder

 

String

Returns the active block folder.

currentBlock

 

String

Returns the active block name.

currentGroup

 

String

Returns the active block group name.

currentNorms

 

String

Returns the active norms name.

currentProject

 

String

Returns the active project name.

executeInHullServer

 

Boolean

Sends a DDE command to Hull Server. It can also be used to enable/disable the Models only mode in Hull Server.
getEnv Environment name * String Retrieves the value of the environment "name". If the requested name does not exist, returns the null object.
getUsers

Block name

username: string,

pid:integer,

processname: string,

host: string,

timestamp: integer,

utctime: string

Retrieves a list of user processes that are active in a given block.

The function provides the following information for each user:

  • username – Windows user account under which the user process is running

  • pid – The process id of the process

  • processname – The name of the process the user is running

  • host – The machine on which the process is running

  • timestamp – The unix timestamp at which the user process started in the block

  • utctime – A human-readable formatted string of the timestamp in the UTC time zone
hullBinPath

 

String

Returns the binary path of the Hull installation. Also available as the value of the %NCGBIN% environment variable used by the Hull Clone process and CADMATIC Hull.

hullTempPath

 

String

Returns the binary path of the Hull temporary folder. Also available as the value of the %NCTMP% environment variable used by the Hull Clone process and CADMATIC Hull.

in3Dblock

 

Boolean

Returns when the active block is a 3D block.

inRefSurfBlock

 

Boolean

Returns whether or not the active block is a reference surface block.

inVirtualBlock

 

Boolean

Returns whether or not the active block is virtual.

is3Dblock

Block name

Boolean

Returns when the specified block is a 3D construction block (that is, 2D blocks and predefined blocks are not returned).

isRefSurfBlock

Block name

Boolean

Returns whether or not the specified block is a reference surface block.

isVirtualBlock

Block name

Boolean

Returns whether or not the specified block is a virtual block.

leaveActiveBlock

Block name

Boolean

Releases locks in the active block, and removes environment variables that were set when the block was opened.

normsFolder

 

String

Returns the active norms folder.

projectFolder

 

String

Returns the active project folder.
setEnv Environment name, Environment value * void Assigns the environment value to the environment "name".

sleepMilliSeconds

Integer

void

Pauses the script for at least the given amount of milliseconds.

sleepSeconds

Integer

void

Pauses the script for at least the given amount of seconds.

startHullServer

 

 

Starts the Hull Server.

startTimer

Timer name

Boolean

Starts a named timer. Multiple timers with different names can be active at the same time.

stopHullServer

 

 

Stops the Hull Server.

stopTimer

Timer name

Double

Stops a named timer. Returns the elapsed time between starting and stopping the named timer. After this the same name can be used again to start a new timer.

system

DOS command

Boolean

Executes the specified command.

system (extended)

Executable,
Executable parameters,
optionally Timeout in minutes

cmdOke: boolean,

exitcode: integer,

status: integer,

output: string

Run the given executable with the given parameters.

The system automatically executes this version of the system command when two arguments are passed.

Optionally a timeout in minutes can be given. If the executable takes longer than the given timeout to finish, it will be aborted.

The function returns a JavaScript Object with four members:

  • CmdOke – true if the command finishes properly with return code 0

  • exitcode – the return code of the executable

  • status – an integer code indicating how the executable finished:

    • 0 – finished normally

    • 1 – did not start

    • 2 – failed to abort after the given timeout, still running

    • 3 – aborted after the given timeout

  • output – the combined output produced by the executable on stdout and stderr

waitForHullServer

 

void

Pauses execution of the script until the hull server queue is empty.

* For both Environment name and Environment value the actual values should be enclosed in double quotes. If backslashes are needed in a path, double backslashes should be used.

See Recalculating all blocks for an example script.

Environment variables

Any environment variable that is available in the Hull application can be used in Hull Clone. They are part of the environment in which Hull Clone process executes. See Recalculating all blocks for an example of a batch file that runs the Hull Clone script with the correct environment settings.

Variable

Description
DM_NLC_HOST This variable must be available and it must store the host of the license server.
HULLCENTRE This variable contains the value of the full path to the Hull Centre. It must be set before the project is accessed for the first time after it was added to COS as a new project, or after converting the project from CADMATIC Hull Classic. The value will be stored in the projectsiteinfo.xml file, which is located in the %PROJECTFOLDER%/administration/ folder.
NUPAS_CAM_SERVER_LOGFILE

When present, this variable should contain the full path of a log file.

The Hull Server will automatically enable the setting Show Process Output and log the output to the given file.
NCG_SETTINGS_CFG

If multiple Norms Configurations are defined, this variable can be set to a non-default value.

The syntax is: ###:name. For example:

001:myconfig

The function provides the following information:

  • ### – number of the configuration

  • name – name of the configuration

The name can be omitted only when used from Hull Clone.

NCTMP

By default Hull Clone creates a temporary scratch folder at startup, which is used as %NCTMP%. The folder is removed when the Hull Clone process stops.

The environment variable can be set before starting the Hull Clone process.

  • If it is set to an existing folder, Hull Clone uses that instead of creating a new temporary folder. Also in this case Hull Clone will not remove the folder when it stops.

  • If it is set to a non-existing folder, or Hull Clone cannot write to the folder, it will fall back to the default behavior.