Manual

Hello World

After installing Exodus, you can develop Exodus programs from any operating system command line.

Any programs you develop are stored in the same directory as their source code. They are also copied to an folder in your home directory - Exodus on Windows and bin or lib on other operating systems. These folders are added to the end of your path by the Exodus installer. This means that, as long as you are logged in as the developing user, and there is no similarly named program early on in your path (e.g. operating system commands) you can use any developed program from any command line. To make any programs available to other users you must arrange for the programs to be copied to some directory on their path.

Edit

Use Exodus's all-in-one editor+compiler+cataloger 'edic'

edic hello1

edic will give you a skeleton Exodus program which you can develop as you wish.

There must be one and only one "function main()" statement and this is run when the program is started.

By convention, main() must return an integer value. If desired, this can be used to indicate "success" with zero or "failure" with some error number.

The programinit() and programexit() lines are required and provide all the standard multivalue system variables using a simple C++ class macro.

#include <exodus/program.h>

programinit()

function main() {
        printl("hello1 says 'Hello World!'");
        return 0;
}

programexit()

Save and compile

Make any changes you want in to the skeleton and save it.

NB If you just want to try out the skeleton program as is then you must still explicitly save it otherwise if you just exit without saving, edic will assume you have changed your mind and that no longer want the hello1 program, and will cancel. For the default editor (nano), explicit save is usually Ctrl+O.

On saving hello1, edic will compile and catalog it.

Run

To run/open/execute your new hello1 program just type its name.

hello1

and the output is ...

hello1 says 'Hello World!'

Local subroutines

To simulate classic multivalue basic's "gosub/return" in Exodus, you can add additional subroutines and functions above or below your "main" function.

Local subroutines and functions (including the "main" function) can be any order. There is no rule that functions must appear before or above the code that calls them.

Simple Example

Here is hello1 modified to call a subroutine that says something.

The word "gosub" is just there for classical clarity. It could be omitted. It could also be replaced by "call" which is also a throwaway word. While gosub and call are interchangeable, if you are going to use them at all, it is probably a good idea to use "gosub funcx()" to indicate internal subroutines and "call funcx()" to indicate external subroutines.

All functions/subroutines must fall between the programinit() and programexit() lines, and cannot be nested otherwise compilation will fail.

#include <exodus/program.h>

programinit()

function main() {
        printl("hello1 says 'Hello World!'");

        gosub subr1();

        return 0;
}

subroutine subr1() {
        printl("subr1 says 'Hello'");
}

programexit()

output:

hello1 says 'Hello World!'
subr1 says 'Hello'

Subroutine and Function Parameters (Arguments)

Parameter names must be prefixed by "in", "out" or "io" to indicate if they are inbound, outbound or both.

Inbound parameters (prefixed with "in") cannot be amended within the function and the compiler will enforce this. This provides a guarantee to the programmer calling the subroutine or functions that their inbound parameters will not be modified by calling the function. Inbound parameters may be provided by the calling program either as a variable or as raw data like "xyz" or 123 etc.

In/Outbound parameters ("io") must be provided by the calling program in the form of a variable and not raw data. The function can both read and write into these parameters.

Outbound parameters ("out") are indicate to the programmer using the function how it works. Outbound parameters are actually no different from in/outbound parameters. There is no simple way to enforce "write only" parameters using the underlying C++ language.

All the usual C++ parameters are also allowed for example "int arg1" or "const char* arg1" etc. This might be useful in special cases or where performance is critical.

External functions and subroutines

Editing and compiling external subroutines and functions in Exodus is identical to normal programs except:

1. the word "program" becomes "library" so we have "library.h", "libraryinit()" and "libraryexit()".
2. function main can have any parameters you like, for example: "function main(in arg1, in arg2, out arg3)

NB The name of the function internally must be main and NOT the name of the function so we still have "function main(...)" but this time it can have parameter names.

Example func1

edic func1

#include <exodus/library.h>

libraryinit()

function main(in arg1, out arg2) {
        printl("func1 says 'Hello World!'");
        arg2="arg1 was "^arg1;
        return 999;
}

libraryexit()

Example prog1 using func1

Compiling func1 created a func1.h file that is required to "glue" func1 into any program that wants to use func1.

To use func1 in any program or external subroutine or function, you need to insert an #include "func1.h" somewhere between "programinit()" and "programexit()" - and not within the body of any function or subroutine.

edic prog1

#include <exodus/program.h>

programinit()

//you must "declare" that we want to use func1
#include "func1.h"

function main() {
        printl("prog1 says 'Hello World!'");

        //we print what func1 returns, and also what func1 returns in arg2
        var arg2;
        printl(   func1("myarg1",arg2)   );
        printl(arg2);

        return 0;
}

programexit()

run prog1

prog1

output:

prog1 says 'Hello World!'
func1 says 'Hello World!'
999
arg1 was myarg1

Functions versus Subroutines

Functions can be used anywhere an expression would be used whereas subroutines can only be used as statements.

The same principle applies to both internal and external subroutines/functions.

Both subroutines and functions can return information in any of their "out" or "io" arguments.

The word "call" or "gosub" before the use of a function or subroutine is optional and can be omitted.

Functions

Functions return a value so the calling program can use a function anywhere an expression is required, for example on the right hand side of an assignment.

var yy=funcx(xx);

Even though a function returns a value, it can be ignored.

call funcx(xx);
gosub funcx(xx);
funcx(xx);

Subroutines

Subroutines do not return a value so they can only be used as statements.

call subrx(xx);   
gosub subrx(xx);  
subrx(xx);        
var yy=subrx(xx); //will not compile

Differences between Exodus's Internal Subroutines and Functions and those of classic multivalue basic

Exodus's local subroutines and functions are very different from and arguably much better than classic multivalue local subroutines since they can be called with parameters, have their own set of variables. They can also return values and therefore be used as functions.

Exodus Internal Subroutines and Functions:

1. can be called with parameters e.g. gosub funcx(xx,yy,zz)
2. all variables are private except for program global variables (preventing many bugs)
3. can return a result e.g. abc=funcx(xx,yy,zz)

Essentially they are identical to *external* functions and subroutines except that 1) they are written in the main program and 2) they have access to the programs global variables.

They do not have any access to the variables of the calling program unless they are passed as parameters or are defined as global variables.

They only have one entry point whereas in classic multivalue basic you can jump into the middle of any local subroutine. To simulate this type of coding in in Exodus you must create nested subroutines or functions.

The old RETURN TO XYZ syntax is not supported at all and such code must be redesigned to eliminate it.

Using internal subroutines and functions internally instead of externally

Exodus allows some classic multivalue basic external subroutines and functions to be implemented as local subroutines/functions thereby allowing you to keep a programs source all in one file where desired. This is a major improvement in source code management. You can still make external subroutines and functions where that is the best strategy, for example to provide some feature to more than one program.

In classic multivalue basic, if you wanted to implement some function to be used in expression you had to implement it as an external function requiring a separate source code file. If this function was applicable only to one program then splitting it into a separate source file is likely to be an unwanted but unavoidable outcome.

In classic multivalue basic, or you wanted to call a subroutine with parameters, or you wanted to be sure that a subroutine would not accidentally overright main program variables, you had to implement it as an external subroutine or function.

Therefore a classic multivalue program would sometimes end up as a set of separately compiled source code even when the best thing would be to keep it all together in one source file.

NB Exodus internal subroutines and functions have access to the global variables of the main program so you might want them to make them external to make sure that there is no risk that they touch any global variable.