Return Value to COPIAFACTS from $run command

RUNVALUE lineno [value]

The RUNVALUE program may be placed in a batch or command file run from a $run command to return a value to the CopiaFacts program. The value is made available in the RUN_VALUE system variable in an infobox visited in the call after the one which spawned the program or batch file. If the value is omitted the variable is set to an empty value.

The correct CopiaFacts line number and nodename, separated by an underscore character, must be specified on the RUNVALUE command line. This requires that the @LNUM and @NODEID variables must be passed to the batch file as a parameter. The RUNVALUE program will return a non-zero exit code (which can be tested through ERRORLEVEL) if the passing of the value fails. This will happen if CopiaFacts is not running or if the line is not currently running an external process through $run.

The value is limited to 255 characters.  If you wish to send non-ASCII characters, they should be encoded as UTF-8.

Your applications can also use the same technique as does RUNVALUE to pass a value back when spawned by the $run command.  Since the CopiaFacts line number is required to do this, you must also include @LNUM_@NODEID as a parameter in the command to be executed.  To pass back a value, your program should do the following:

Use EnumWindows() to locate the window where GetWindowText() receives the string "CopiaFacts Engine".

Create and populate a COPYDATASTRUCT as follows:

  dwData = (lnum << 16) + 0xbbbb;

  cbData = strlen(message)

  lpData = message

Use SendMessage() to send a WM_COPYDATA message to the window, passing the COPYDATASTRUCT in lParam.

If the message is successfully processed by the CopiaFacts engine, SendMessage() will return 0.  Note that your application can only use this technique when it is being called from a $run command.  These messages are reported in the engine trace file when 'Trace IIF actions' is enabled.

Example:

Assume that the @LNUM variable is passed to the command file as its third parameter:

REM TEST.CMD parameters: filename key lnum nodeid

@ECHO parm1=%1 parm2=%2 parm3=%3 parm4=%4

RUNVALUE %3_%4

RUN_A_PROGRAM %1 %2

IF ERRORLEVEL RUNVALUE %3_%4 ERROR