DocumentTools - Maple Help

Online Help

All Products    Maple    MapleSim

Home : Support : Online Help : Programming : Document Tools : DocumentTools/RunWorksheet





execute a worksheet as a procedure


Calling Sequence



Example Using RunWorksheet

Calling Sequence

RunWorksheet(ws, var_init)




string ; name of the file containing the worksheet to run



(optional) list(symbol=anything) ; list of equations of the form symbol = expression, specifying the initial values for the corresponding variables in ws



IMPORTANT: This function is experimental and subject to change.


The RunWorksheet function invokes the worksheet ws as if it were a procedure.  The variables appearing on the left-hand sides of equations in the var_init parameter are initialized to their corresponding right-hand side values.


The worksheet filename ws can be either fully qualified or be relative to the value of currentdir.


The invoked 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.


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.

Example Using RunWorksheet


Create a 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 in the current directory.


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

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



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).

See Also


Document Properties


Insert a Section




Download Help Document

Was this information helpful?

Please add your Comment (Optional)
E-mail Address (Optional)
What is ? This question helps us to combat spam