Loading and Executing an Application

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

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.