Skip to main content

SA Engine Command Line Interface

🚀 Interactive documentation
This page uses Wasm code blocks so you can run the examples directly in the browser.

SA Engine is developed command-line first and everything that can be achieved through other front ends can also be done on the command line. This makes it suitable for automation.

Starting SA Engine in a Command Prompt​

  1. Make sure the sa.engine\bin directory has been added to your PATH environment variable, or navigate to that folder in you terminal window.

  2. Run the executable: sa.engine

You can now interact with SA Engine and execute functions or queries.

Command line options​

To get a list of available flags when starting sa.engine, use sa.engine -help, sa.engine -h or sa.engine -?. This will show all available options:

sa.engine [image_file | -i lisp_file]
          [-e edge[@[host][:port]]] [[-s | -S] server[@[host][:port]]]
          [[-n | -N] [nameserver][:port]]] [-c client[@[host][:port]]]
          [-o osql] [-O osql_file] [-q query_language]
          [-l lisp] [-L lisp_file]
          [-f sa_home_folder] [-x] [-K] [-r out_file]
          [-h | -?]

Attaching code to run​

Instead of starting sa.engine and interacting by typing code afterwards, its possible to attach code to run when starting. Use -o to attach a string of OSQL code, or -O to submit a path to an OSQL file to be executed. Similarily, use -l to attach a string of lisp code, or -L to submit a path to a Lisp file.

It is possible to attach several strings or paths to code, which will then be executed in order from left to right.

sa.engine -o "create function example()->Charstring as 'hello';" -o "example();"

It is also possible to attach SQL queries for searching stored functions, using the -q flag. This is a debugging functionality and should normally not be used.

Closing with an exit code​

To close down SA Engine, execute the command quit;. To start SA Engine, execute some code, and then close, this comand can be added as the last OSQL string: 

sa.engine -o "models:test('my-model')" -o "quit;"

quit; closes with an exit code, which will be OK if all attached code has executed without error, and otherwise not.

Managing the output channel​

There are two types of output from SA Engine, printed results, and return values. Printed results are for example the results of evaluated functions and queries, while return values are the execution results (OK if a query is sucessful and otherwise an error). When executing validate statements, the results are also returned.

By defualt, when starting sa.engine and interacting, both of these outputs are written to the command window. When running code with the -o or -l flags, by default only the results are written to the command window. An easy way to get more output is to use the print function. This will write the result to the return stream as well.

sa.engine -o "print(system_version());" -o "quit;"

The output stream can be redirected to a file using the -r out-file option. This will write everything that would be written to the terminal window to the out-file instead. If the file doesn't exist, it will be created. If it does exist, the output will be appended.

sa.engine -r output.txt -o "print(system_version());" -o "quit;"

Setting the SA home folder​

The SA home folder is where SA Engine will look for user models. It is set using the -f option. Typically, if you want to interact with models, SA home should be set to the folder named SA in a hierarchy looking like this:

my-repository
└─ SA/
   ├─ models/
   └─ models-releases/

If you're placed in my-repository when starting:

sa.engine -f SA -o "models:test('my-model')" -o "quit;"

Managing federations​

To manage your federation without using the graphical UIs, a useful topic is Peer Management.

Some functionality is also available directly in the CLI:

-n: Start a nameserver (-N for a separate process)
-K: Kill all servers in the federation and exit
-c: Start a client
-e: Start edge listener (-E for a separate process)
-s: Start a SAS (-S for a separate process)

These commands can be used to start instances of SA Engine with different purposes.

Local federation​

As an example, to create a small local federation with a client, a nameserver and an edge:

sa.engine -N my_nameserver
sa.engine

This will start a nameserver my_nameserver in a seperate process, and then another instance of sa.engine. It is also possible to start the nameserver from inside sa.engine using a query; start_nameserver("my_nameserver").

To connect the other instance to the nameserver, run the query:

reregister("me"); // register this peer in the nameserver
other_peers(); // verify by listing all other peers, this will include the nameserver

reregister also accepts a host id or port.

doc("reregister");

Now it is possible to connect edges to the local federation, as long as the edge has access to the local federations network. Check the ip of your federation:

my_local_ip();

In your sa.engine edge instance, run

edge_listener("my-edge-name@<local-ip>");

Now, verify in the original "me" sa.engine instance:

listening_edges();
edge_status();
other_peers();

Cleaning​

SA Engine creates some temporary files in the configured SA Home directory. To clean this up before starting, use the -x flag.

It is good practice to do such cleaning in automated tests, if the environment is reused.

sa.engine -f SA -x -o "models:test('my-model')" -o "quit;"

Configuring the image file​

SA Engine stores its state, such as defined functions, in an image file. It is possible to supply a path to a specific file that you want to use. If not supplied, the default will be used.

sa.engine my/path/sa.engine.dmp

With the -i lisp_file option, an empty system is started and initialized by running lisp_file. This is a debugging functionality and should normally not be used.