File CommandLine.html    Author McKeeman    Copyright © 2007    index

xcom Command Line

Preliminary

To run a program, call xcom from the MATLAB command line. Example:

    >> xcom 'x:=139-11*2'
    x := 117

gives the result shown. The quotes are not needed unless there is a MATLAB-significant character such as blank or semicolon in the input.

From within the mxcom main directory

    >> xcom x/pi.x
    integer input: nterms=100
    pi := 3.136593
    delta := 0.010000

compiles and runs the program pi.x. The program requests input. You enter 100 (say) and the program then runs to completion and reports its results as noted above.

You can call the same program as a subprogram. The caller will provide the input (in this case 100).

   >> xcom x/pi.x -srcDump x/callpi.x
   begin source code ----
   ' FILE:    callpi.x
   ` PURPOSE: compute pi to n terms
   ` METHOD:  4*(1 - 1/3 + 1/5 - 1/7 + 1/9...)
   `          Number of terms is input

   pi100, eps := pi := 100;

   end   source code ----
   pi100 := 3.136593
   eps := 0.010000

In this case xcom compiles the two programs, dumps the source for the second one, then runs the last program in the argument list. That program in turn calls the first program to compute pi (again using 100 terms of the alternating harmonic series).

The xcom arguments: X files, X text and flags

The main call to xcom takes a list of arguments. As command dual (usual call) the arguments are blank-separated as shown in the example above. (Note: arguments cannot contain characters that will catch the attention of MATLAB, such as blank or semicolon. An xcom argument can be wrapped in quote-marks if necessary, preventing MATLAB from interpreting the contents.)

If the argument is a valid X file name, the file will be read and the contained text taken as input. If the argument starts with a '-', it will be taken as a flag. Otherwise, the argument will be taken as X source text. Flags are either global or effect only the following argument.

xcom help

From MATLAB, in the mxcom directory, try

      >> help xcom

You will see a lot of information, including the set of possible flags in the help output. Most of the M files in the mxcom directory also have help. For example, try

      >> help Cfg

Errors

When something goes wrong, xcom uses the MATLAB error function to report the trouble. The assumption is that the user is only interested in what is wrong with the X program. xcom therefore supresses the normal MATLAB stack dump. But, if you are trying to debug your version of xcom, the MATLAB stack carries essential information. In this case pass the flag

      -matlabStack

to xcom and see it all.

Loops

If you are so unfortunate as to write an X program with an infinite loop, there is no recovery. CTRL-C is ignored. Kill MATLAB. Start over. You might want to run under emulation to isolate the error. CTRL-C does work in this case.

Dumps and Traces

In general, most xcom modules have a trace facility and/or dump facility. A dump is a formatted output of the final internal state of an object. A trace is a formatted output of the results as they are computed. You can try the flags in the help list one or more at a time. For example

    >> xcom -noExecute -symDump x/pi.x
    Symbols ---------- start dump ------------
      1: pi: ty=fn use=
      2: p2: ty=real use=left|right
      3: i: ty=integer use=left|right
      4: nterms: ty=integer use=right
      5: t: ty=real use=left|right
      6: p1: ty=real use=left|right
      7: res: ty=real use=left
      8: delta: ty=real use=left
    Symbols ---------- end dump ------------

will dump the symbol table for pi.x and not execute the program.

Unit Tests, Trials and Times

In the mxcom directory

    >> addpath tests trials times

Each of these directories contains tests implemented in M. Try each of

    >> testAll()
    >> tryAll()
    >> timeAll()

Eventually these tests consume about 1/2 of the development work: you are encoueraged to add a feature, add a trial, add a test, and (perhaps) time the feature.

Interactive Execution

Since xcom eventually makes machine code and executes it, the xcom developer needs a way to "watch it run". Try

    >> xcom -interactive -asmTrace 'x,y:=13.0+17.1,100+101'

What you will see is the assembly language translation followed by the start of an instruction-by-instruction trace. For each prompt

    step=

reply with an ENTER (or 1 followed by ENTER) to see the result after every instruction. You can actually give the prompt any MATLAB integer value. A step value larger than 1 steps forward, skipping over some output. A negative value steps back. Note:The emulation does not implement the X function call, so as a practical matter, it can only be used on one dot-x file.