RunWorksheet - Maple Help

DocumentTools

 RunWorksheet
 execute a worksheet as a procedure

 Calling Sequence RunWorksheet(ws, var_init)

Parameters

 ws - string ; name of the file containing the worksheet to run var_init - (optional) list(symbol=anything) ; list of equations of the form symbol = expression, specifying the initial values for the corresponding variables in ws outputs - (optional) list({symbol,string}) ; list of variables and/or command strings inheritlibname - (optional,cmaple only) truefalse ; indicate whether the worksheet process should inherit the current value of libname. The default is true.

Description

 • 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.  Names 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.
 • The worksheet filename ws can be either fully qualified or be relative to the value of currentdir.
 • 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 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.
 • RunWorksheet can be used in a workbook together with a worksheet with password protection.  For an example, see Password-Protected Workbook Example. For more information, see The Workbook File Format and Password Protecting Workbook Pages.

Example Using RunWorksheet

 1 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;
 2 Create another section entitled Calculation with this line:
 > return a+b^2+c^3;
 3 Under the File menu, open Document Properties.  Add a new attribute InputSectionTitle.  For its value, enter Inputs.
 4 Save this worksheet as test.mw in the current directory.
 5 In another worksheet, execute the following command to run the worksheet:
 > DocumentTools[RunWorksheet]( "test.mw", [a=-1, b=4] );
 ${42}$ (1)
 • 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).