ws is the filename, either fully qualified or relative to the value of currentdir, of the worksheet to execute.

The variables appearing on the left-hand sides of equations in the var_init parameter are initialized to their corresponding right-hand side values.  Names can be prefixed with % in var_init represent embedded-components.  For example, %TextArea0 = 5 as part of var_init, will initialize the TextArea0 component value to 5.

Values can be extracted from the worksheet by specifying outputs=[list of names]. In addition to the names specified in outputs, command strings can be given in the outputs list.  These commands will be evaluated as a post-processing step after the worksheet is finished executing but while the worksheet state is still active.

The worksheet, ws must identify in its Document Properties a section which initializes via assignment statements the variables given in var_init. Specifically, within the Document Properties there must be an attribute with Attribute Name InputSectionTitle and whose value is the section name.

This section of the worksheet ws must have at least one assignment statement for each variable appearing on the left-hand side of an equation in var_init.  These assignment statements must use the assignment operator (:=) and should be the only statements appearing in their respective execution groups. (There can be other assignments or other Maple computations in this section, as well.)

If the invoked worksheet ws includes a return statement at the top level (not inside a procedure), the expression given in that return statement will be returned as the output of the RunWorksheet command.  Execution of the invoked worksheet ws stops when a top-level return is evaluated.

If the invoked worksheet ws does not include such a top-level return statement, the RunWorksheet command will have no output. That is, the value of the RunWorksheet call will be NULL.

ws can be either a filename, fully qualified or relative to the value of currentdir, or a URL supported by the Import command.

An equation specified in var_init overrides the first assignment to the variable specified on the left-hand side with the value given on the right-hand side.  There is no special formatting required in a Maple Flow document to enable it to be called via RunWorksheet.  

The default return value of the Maple Flow document is the value computed by the last math container in the document.

Values can also be extracted from the worksheet by specifying outputs.  If outputs is a list of names, RunWorksheet will return a list of equations where the right hand side is the name and the left hand side is the computed value.  If outputs is a Vector of names, the return value will be a Vector of the computed values, where the index of a returned value corresponds to the index of the name in the Vector given as outputs.

In addition to the names specified in outputs, command strings can be given in outputs.  These commands will be evaluated as a post-processing step after the worksheet is finished executing but while the worksheet state is still active.

Referencing typeset variable names (for example Greek letters or subscripts), can be tricky in a 1-D string.  RunWorksheet for Maple Flow supports the all option which causes all assigned variables from the document to be returned.  lprint can be used to display the 1-D representation of the returned variables names.  This 1-D representation can then be used in strings to reference those variables.

The Maple Flow document must have been saved in Maple Flow 2024.2.1 or newer in order to work with RunWorksheet.

Multiple values can be returned in an expression sequence.

The invoked worksheet runs "headless", meaning that it will not appear with a user interface.

The invoked worksheet runs in a new engine, so expressions whose subsequent evaluation may depend on the state of the engine in the calling worksheet cannot be passed in var_init.  This includes procedures and modules which are not lexically closed (for example, which use global or environment variables in their bodies).  To pass a procedure, table, matrix, vector, or array defined elsewhere in the calling worksheet, it is necessary to apply eval to the expression first.  For example, use g = eval(f) in var_init, where f is a user-defined procedure.

The worksheet ws can be a workbook URI to invoke a worksheet within a workbook. For more information, see The Workbook File Format and Referencing Files in a Workbook.

RunWorksheet can be used with a workbook containing a worksheet with password protection.  For an example, see Password-Protected Workbook Example. For more information, see Password Protecting Workbook Pages.

Create a Maple worksheet with a section entitled Inputs.  In that section, enter these assignments (each in its own execution group):

a := 1;

b := 2;

c := 3;

Create another section entitled Calculation with this line:

return a+b^2+c^3;

Under the File menu, open Document Properties.  Add a new attribute InputSectionTitle.  For its value, enter Inputs.

Save this worksheet as test.mw in the current directory.

In another worksheet, execute the following command to run the worksheet:

DocumentTools[RunWorksheet]( "test.mw", [a=-1, b=4] );

$42$

Note that it is not necessary to provide values for all (or any) of the variables appearing in the invoked worksheet's input section (but it is an error to try to provide a value for a variable which does not appear as the left-hand side of an assignment statement in that input section).

The example worksheet RunWorksheetExample.flow contains the following math containers:

a := 1

b := 2a

c := 3

a + b^2 + c^3

This example can be executed as follows:

flowfile := FileTools:-JoinPath( [ "example", "RunWorksheetExample.flow" ], base=datadir ):

DocumentTools:-RunWorksheet( flowfile );

$32$

DocumentTools:-RunWorksheet( flowfile, [a=-1,b=4] );

$42$

DocumentTools:-RunWorksheet( flowfile, [a=2], outputs=[b,c] );

$\left[b=4\,c=3\right]$