CallUSM starts the user-supplied module (USM, a Windows executable) specified by FName and passes a set of commands to it which are contained in the stringlist USMCtrl. The commands can be of any format, it is up to the developer of the USM to correctly interpret them (the USM will receive the commands in exactly the same form as stored in the USMCtrl parameter).
FName can contain either the full path of the USM or just the filename. If you omit the full path, assumes that the USM is stored in the script directory.
The function CallUSM returns the following error codes:
0 ... everything is OK, the USM has been successfully called
-1 ... the file FName does not exist
-2 ... the specified USM is not an executable
-3 ... an unknown error occurred when starting the USM
The USM has to conform to the following minimal requirements:
- Initialization during startup:
- Check the number of calling parameters and their contents
- If usmname and/or semaphdir are not defined, abort the USM issuing the appropriate message to the GUI (no communication to is possible at this moment)
- Processing of received messages: The USM has to respond at least to the command KILL by first issuing the DONEEXIT message with error number ERR_KILLED and then killing itself. Make sure that the KILL command can be received and processed even during lengthy operations.
- Communicating Results: The USM should communicate results to by pushing matrices on the global matrix stack MatStack.
- Final status feedback to : When the module has (successfully) finished its task, it has to send the DONEEXIT message before closing itself.