Documentation Center

  • Trial Software
  • Product Updates

Verify Options

For many standard MuPAD® procedures, you can use different options. If a MuPAD procedure accepts options, it has an embedded mechanism for collecting and verifying these options. For example, the solve function accepts the Real option. The option indicates that the solver must return only real solutions and accepts the values TRUE and FALSE. If an option accepts only TRUE and FALSE values, you can provide the option name without specifying its value:

solve(x^4 - 1 = 0, x, Real)

If you do not specify the Real option, the solver uses the default option value FALSE, and returns all complex solutions of the equation:

solve(x^4 - 1 = 0, x)

You can explicitly specify the option-value pair, for example, Real = TRUE or Real = FALSE:

solve(x^4 - 1 = 0, x, Real = TRUE);
solve(x^4 - 1 = 0, x, Real = FALSE)

If you provide an unexpected option (for example, if you spell the option name incorrectly), MuPAD issues an error indicating the wrong option. If there are several wrong options, MuPAD indicates the first wrong option:

solve(x^4 - 1 = 0, x, Rea, Rel)
Error: The argument number 3 is invalid.
  Evaluating: solvelib::getOptions

You can embed the same option checking mechanism in your own procedures. For this task, MuPAD provides the prog::getOptions function, which collects and verifies options used during a procedure call. When a user calls your procedure, prog::getOptions scans all arguments and returns a table that contains all expected options and their values. It also returns a list of all unexpected options.

When you pass arguments to prog::getOptions, always use the following order. The first argument of prog::getOptions is the number n + 1, where n is the number of required (non-optional) arguments of the procedure. Then you must provide the list of all actual arguments followed by the table of all acceptable options and their default values. To access a sequence of all arguments of a procedure call, including required arguments and options, use the args function.

The following example demonstrates the procedure that accepts the numeric coefficients a, b, and c and solves the quadratic equation ax2 + bx + c = 0 using these coefficients. The procedure solveQuadraticEqn requires the user to provide three numeric values. Therefore, if you embed prog::getOptions into this procedure, the first parameter of prog::getOptions must be the number 4. The procedure also accepts the optional argument PositiveOnly. If the value of PositiveOnly is TRUE, the procedure returns only positive solutions of the quadratic equation. If the value is FALSE, the procedure returns all solutions. The following function call to prog::getOptions sets the default option value PositiveOnly = FALSE:

solveQuadraticEqn := proc(a:Type::Numeric, b:Type::Numeric,
                                           c:Type::Numeric)
local options, S;
begin
  options := prog::getOptions(4, [args()],
             table(PositiveOnly = FALSE));
  S := solve(a*x^2 + b*x + c = 0, x);
  if options[1][PositiveOnly] = TRUE then
    S := select(S, testtype, Type::Positive)
  end_if:
  return(S)
end_proc:

If you call solveQuadraticEqn without the PositiveOnly option, the procedure returns all solutions of the quadratic equation:

solveQuadraticEqn(2, 3, -9)

If you use the PositiveOnly option, the procedure returns only positive solutions:

solveQuadraticEqn(2, 3, -9, PositiveOnly)

By default, prog::getOptions does not error when it finds an unexpected option (an option that is not listed in the table of accepted options). Instead, it collects all unexpected options and returns them in a separate list. Thus, the procedure solveQuadraticEqn does not issue an error when you spell the option name incorrectly:

solveQuadraticEqn(2, 3, -9, Positive)

The prog::getOptions function can issue an error when it finds an unexpected option. In a function call to prog::getOptions, the fourth argument indicates whether prog::getOptions must silently collect unexpected options or issue an error. This argument is optional. By default, it is set to FALSE. To issue an error instead of listing unexpected arguments, use TRUE as the fourth argument of prog::getOptions:

solveQuadraticEqn := proc(a:Type::Numeric, b:Type::Numeric,
                                           c:Type::Numeric)
local options, S;
begin
  options := prog::getOptions(4, [args()],
       table(PositiveOnly = FALSE), TRUE);
  S := solve(a*x^2 + b*x + c = 0, x);
  if options[1][PositiveOnly] = TRUE then
    S := select(S, testtype, Type::Positive)
  end_if:
  return(S)
end_proc:

Now, the procedure solveQuadraticEqn issues an error. The error message indicates the wrong option:

solveQuadraticEqn(2, 3, -9, Positive)
Error: The argument number 4 is invalid.
  Evaluating: solveQuadraticEqn
Was this topic helpful?