# Loading and Executing an Application

The File folio provides six functions to load and run executable code:

- `LoadProgram()`
- `LoadProgramPrio()`
- `LoadCode()`
- `UnloadCode()`
- `ExecuteAsSubroutine()`
- `ExecuteAsThread()`

## Loading and Launching a Task

`LoadProgram()` loads an executable file from disk and launches a new task which executes the code in the file.

  `Item LoadProgram(char *cmdLine);`

The only argument of this function is a command line to interpret. The first component of the command line is taken as the name of the file to load. The entire command line is passed to the new task as `argc` and `argv` in the `main()` function. The file name component of the command line specifies either a fully qualified pathname, or a pathname relative to the current directory.

The priority of the new task is the same as the priority of the current task. If the task should have a different priority, use the `LoadProgramPrio()` function.

`LoadProgramPrio()` is identical to `LoadProgram()` except that it specifies a task priority for the new task.

  `Item LoadProgramPrio(char *cmdLine, int32 priority);`

You give this function a command line to interpret. The first component of the command line is taken as the name of the file to load. Like `LoadProgram()`, the entire command line is passed to the new task as `argc` and `argv` in the `main()` function. The file name component of the command line specifies either a fully qualified pathname, or a pathname relative to the current directory.

The `priority` argument specifies the task priority for the new task. If you simply want the new task to have the same priority as the current task, use the `LoadProgram()` function instead. Alternatively, passing a negative priority to this function will also give the new task the same priority as the current task. `LoadProgram()` and `LoadProgramPrio()` will set the current directory of the newly created task to the directory from which the executable was loaded.

## Loading a Code Module

`LoadCode()` loads an executable file from disk into memory. Once loaded, the code can be spawned as a thread, or executed as a subroutine.

  `Err LoadCode(char *fileName, CodeHandle *code);`

In order to work correctly with this and associated functions, the executable file being loaded must have been linked with threadstartup.o or subroutinestartup.o instead of cstartup.o

This function requires the name of the executable file to load, as well as a pointer to a `CodeHandle` variable, where the handle for the loaded code will be stored.

`Note: code` must point to a valid `CodeHandle` variable, because LoadCode() uses this location to put a pointer to the loaded code.

## Executing a Loaded Code Module

To execute the loaded code, you must call either the `ExecuteAsThread()` function or the `ExecuteAsSubroutine()` function. If the loaded code is reentrant, the same loaded code can be spawned multiple times simultaneously as a thread.

`ExecuteAsSubroutine()` executes a chunk of code that was previously loaded from disk using`LoadCode()`.

  `int32 ExecuteAsSubroutine(CodeHandle code, int32 argc, char **argv);`

This function runs the code as a subroutine of the current task or thread.To work correctly, code that is run as a subroutine should be linked with subroutinestartup.o instead of the usual cstartup.o

The parameters in `argc` and `argv` are passed directly to the `main()` entry point of the loaded code. The return value of this function is the value returned by `main()` of the code being run.

The values you supply for `argc` and `argv` are irrelevant to this function. They are simply passed through to the loaded code. Therefore, their meaning must be agreed upon by the caller of this function, and by the loaded code.

`ExecuteAsThread()` executes a chunk of code that was previously loaded from disk using `LoadCode()`. This function executes code that will execute as a thread of the current task.

  `Item ExecuteAsThread(CodeHandle code, int32 argc, char **argv, char *threadName, int32 priority);`

To work correctly, code being run as a thread should be linked with threadstartup.o instead of the usual cstartup.o

The `argc` and `argv` parameters are passed directly to the `main()` entry point of the loaded code.The values you supply for `argc` and `argv` are irrelevant to this function. They are simply passed through to the loaded code. Therefore, their meaning must be agreed upon by the caller of this function, and by the loaded code. `threadName` specifies the name of the thread. `priority` specifies the priority the new thread should have. Providing a negative priority makes the thread inherit the priority of the current task or thread.

## Unloading a Code Module

Once you are done using the loaded code, you can remove it from memory by passing the code handle to the `UnloadCode()` function. `UnloadCode()` frees any resources allocated by `LoadCode()`. Once `UnloadCode()` has been called, the code handle supplied becomes invalid and cannot be used again.