Planimate command line options
Planimate supports command line options, a key purpose being to run models in batch mode. In batch mode there are no graphics and the platform itself should not pop any windows up under normal circumstances. The engine optimises itself, avoiding graphical processing and user interaction checking.
Most of the options apply both to a Planimate developer EXE and a compiled Planimate Based Application. Note that the treatment of "filename" is different between the two.
This page documents the options as at Planimate 5.32r
Overview
In these examples pl.exe means a standard developer EXE and pba.exe means a compiled Planimate based application EXE.
pl.exe modelname
Loads model as if loaded from file menu
pl.exe modelname /SCENARIO=dataname
Loads model as if loaded from file menu. s.LoadFileNamePath will be set to dataname when the model is run.
pba.exe dataname
Loads application and sets s.LoadFileNamePath (a string) to dataname. Its equivalent to using the /SCENARIO=dataname when using the editor EXE and a m
Running and Batching
/RUN
This causes a model to start running. It serves no purpose for a PBA.
/BATCH
Runs the model without opening the main window. The model should be configured to not interact with the user (no popups, dialogs etc). Any yes/no dialogs are automatically confirmed to the affirmative.
In batch mode s.BackgroundRun is set non zero. The model can use this to avoid UI.
/BATCH and /RUN should be used together when running a MDL file in batch mode.
/SAVEONEXIT
Saves the model upon exit. This serves no purpose for a PBA.
Window Control
/MAXIMISE
Causes the main window to open as maximised. Not useful with /BATCH.
/NOCLOSE
Hides the standard close box, system menu and minimise/maximise controls. Not useful with /BATCH.
Data and Environment
/JOBID=string
Sets s.JobID string. This is useful where the same scenario is being run with different parameters (perhaps set by /INIFILE)
This field is included in xml packets sent by Planimate TCP/IP broadcast sockets. It is useful when an external server needs to determe where a packet has come from. Currently Planimate XML sockets do not read this field from an inbound XML packet.
/LOGIN=file
Enables running PL/PBA under different user credentials. file specifies a file created with a separate credentials creation utility. See below.
/SHARES=file
Specifies INI file containing shares to map. This is useful in conjunction with /LOGIN since a new user loses access to shares mapped by the original user context. See below.
/INIFILE=file
Uses this file for loaded attribute settings, login and share map names, depending on the sections that exist in the file.
Debugging
/DEBUGFILE
Enables writing of PLANIMAT.DBG file into the program's directory. Additional details on platform errors and memory diagnostics are written to this file.
/DEBUGPORT=n
Instead of logging to a file, diagnostics are written to serial port COMn using the port's default communications settings.
/DEBUGIP
Sets up a TCP/IP listener on port 23 for debug diagnostics.
/DEBUGDLL
Enables debugging of loaded DLLs using Visual Studio. Normally PL loads DLLs directly from memory, enabling DLLs to be used without actual DLL files being created. This option disables the memory loader, since debugging a DLL requires that the standard system LoadLibrary services are used.
/DEBUGODBC
This enables more descriptive ODBC error messages
/?
Shows a summary of the commands.
Special
/MAKEEXEKEY=file
Make a standalone EXE keyed with the supplied application key file. Requires that a model name is provided.
/MAKEDLL
By itself, it creates a DLL version of PL which can be called with the dotNET wrapper or directly from other languages. This is distinct from PL calling a DLL from a routine.
Used together with /MAKEEXEKEY, it will create the PBA as a DLL which can be incorporated into a dotNET application. Creating a DLL is also an option in the PBA creation dialog.
The Planimate dotNET wrapper is provided as an open source interface to Planimate as a DLL.
/EXETITLE=title
This is useful with /MAKEEXEKEY and enables the title of a created application to be overridden.
WARNING - this resaves the model, setting the new title.
Batch Mode Details
Error Logging
When running a model in batch mode, no standard windows are displayed. Instead the platform logs any errors to planimat.dbg and details in _plerror.txt. Hence its useful including /DEBUGFILE when /BATCH is used.
Return Error Codes
The following error codes are returned:
| Code | Description |
|---|---|
| 0 | Model completed (Quit from Exit object) or ran out of events / paused. |
| 1 | Error in command line |
| 2 | The EXE path is too deep, put the EXE in a higher level folder. |
| 3 | Unused |
| 4 | Unused |
| 5 | License key error |
| 6 | Error loading resources/DB file. Should never occur for a PBA. |
| 7 | Error loading model specified on command line. Should never occur for a PBA. |
| 8 | Planimate was forced to quit by the operating system |
| 9 | Model run terminated by a model fatal error. _plerror.txt and PLANIMAT.DBG will contain details that would have appeared to the user in interactive mode. |
Model Exit
Batch runs require that the model automatically exit when it is complete. Unless the model naturally runs out of events, the best way to do this is with a forced quit Exit object:
Add an [EXIT] object configured with a stop count of 1, stop mode "Stop All Runs And Quit". The Exit options "Show Objects Window" and "Display Message" should be off.
Arrange for an item to enter this exit object once the run has completed. This could be triggered by a broadcast (eg: _run Pause) or somewhere in the model which knows things are finished.
Running Under Different Credentials
Running as a different user
Using /LOGIN, a model or PBA can run under different credentials to the user that launches it. This is useful in secure environments where the model needs to access data that the user should not be able to browse to.
The shortcut which launches the PL/PBA exe needs to include the /LOGIN=file command line option, where file points to a password file. This file is generated using the ODBC Password Generator EXE. This is provided to licensed users upon request.
The generator EXE is used to create an encrypted file for Planimate containing the username and password of an account on the local machine to use. If a domain controller is used, the username entered in the password generator can be of the form "user@domain".
If /LOGIN is used and there is a problem opening the file or verifying the password, an error will be given and the application will close.
The user account which launches the PL/PBA must have SE_TCB_NAME privilege and in some cases SE_CHANGE_NOTIFY_NAME as well. The target account must have SE_LOGON_INTERACTIVE privilege.
When /LOGIN is used to run a Planimate session under a different user credential, it causes a new user context to be set up which will not have any of the shares that the original account mapped.
Planimate can create new mappings for itself using /SHARES=inifilename
The file spec specified can be the model INI file (but does not need to be). The file should have a section called [shares] and within that, one or more local drive / network name pairs, both in double quotes.
[Shares] "o:" "\\laptop\work1" "p:" "\\pippa\media"
If any of the shares fail to map, PL will give an error and not load.