Program Startup

Running a Program under the CLI

There are two ways you can run a program. First, you can run your program under a CLI (also known as the Shell). Second, you can run your program under the Workbench. This section describes the first of the two ways.

Running a program under the CLI (Shell) is a little like using an old- fashioned line-oriented teletype (TTY) system although you might find a Shell useful, for example, to port your program over to your Amiga as a first step in development. To load and enter your program, you simply type the name of the file that contains the binary and possible follow this with a number of arguments.

Initial Environment in C

When programming in C, you should always include the startup code as the first element in the linker input. This means that the linker enters your program as the startup code entry point. This section of code scans the argument list and makes the arguments available in "argv", with the number of arguments in "argc" as usual. It also opens the AmigaDOS library and calls Input(), Output() and ErrorOutput() for you, placing the resulting file handles into "stdin", "stdout" and "stderr". It then calls the ISO C function "main".

Failure of Routines

Most AmigaDOS routines return a zero if they fail; the exceptions are the Read() and Write() calls that return minus 1 on finding an error. If you receive an error return, you can call IoErr() to obtain more information on the failure. IoErr() returns an integer that corresponds to a full error code, and you may wish to take different actions depending on exactly why the call failed. A complete list of error codes and messages can be found in AmigaDOS Error Messages.

Terminating a Program

To exit from a program, it is sufficient to simply return from the _start vector. In this case, you should provide a return code. This is zero if your program succeeded; otherwise, it is a positive number. If you return a nonzero number, then the CLI notices an error. Depending on the current fail value (set by the command FAILAT), a noninteractive CLI, such as one running a command script set up by the EXECUTE command, terminates. A program written in C can simply return from "main" which returns to the startup code.

It is important at this stage to stress that AmigaDOS does not control any resources; this is left entirely up to the programmer. Any files that a user program opens must be closed before the program terminates. Likewise, any locks it obtains must be freed, any code it loads must be unloaded, and any memory it allocates returned. Of course, there may be cases when you do not wish to return all resources, for example, when you have written a program that loads a code segment into memory for later use. This is perfectly acceptable, but you must have a mechanism for eventually returning any memory, file locks, and so on.

Running a Program Under the Workbench

To run a program under the Workbench, you need to appreciate the different ways in which a program may be run on the Amiga. Under the CLI your program is running as part of the CLI process. It can inherit I/O streams and other information from the CLI, such as the arguments you provided.

If a program is running under the Workbench, then AmigaDOS starts it as a new process running at the same time as Workbench. Workbench loads the program and then sends it a message to get it started. You must therefore wait for this initial message before you start to do anything. You must retain the message and return it to Workbench when your program has finished, so that Workbench can unload the code of your program.

For C programmers, this is all done by the startup routine.

You should also note that a program running as a new process initiated by Workbench has no default input and output streams. The startup routine will provide these streams for you.