Note: IBM OS/2 will return a spurious error about not being able to start the session in the foreground if the session that includes the START command itself is not the current foreground session. This error is benign.
The START command starts a new session, invoking an instance of the command interpreter as the first process running in that session. The command and arguments passed to the START command are passed to the command interpreter, allowing command to be a built in command or a script if desired.
The new session can optionally have an associated console, which in turn can either be displayed as a window (with the display adapter hardware in graphics mode) or full screen (with the display adapter hardware in text mode). Processes that are part of the session can either be attached to the session's console or detached from it. To run a process in the current session but detached from the session's console, use the DETACH command instead.
Individual processes also have types, which may influence their behaviour. Processes can be either graphical (i.e. they use Presentation Manager) or textual (i.e. console mode).
Data can be passed to processes as a hint as to how they should display their main window. These hints are also applied to the session's console if it has one and if it is windowed.
If the first non-option argument to START begins with a quotation character, it is taken to be the a quoted string giving the title for the session (which will be used in the Window List and the session manager in IBM OS/2). The command to run is the next non-option argument.
If the first non-option argument to START does not begin with a quotation mark, it is taken to be the command to run, and the default session title (which is determined by the operating system) is used.
To resolve the ambiguity where the command to be run must be enclosed in quotation marks, such as is the case if it is the name of a program file that contains spaces, and yet it is not desired to set an explicit title, use the /PGM option. Without the /PGM option, the command, since it begins with a quotation mark, will be taken to be the session title, and the command to run will be taken from the first word of the arguments.
If the /C option is used, the name of the command interpreter is taken from the value of the COMSPEC environment variable, and a /C option is prepended to the command line that is passed by START to the command interpreter, telling the command interpreter not to enter interactive mode once it has finished processing its command line (if any). If the COMSPEC environment variable does not exist, START will fall back to using the name "CMD" for the non-interactive command interpreter.
If the /K option is used, the name of the command interpreter is taken from the value of the OS2_SHELL environment variable, and a /K option is prepended to the command line that is passed by START to the command interpreter, telling the command interpreter to enter interactive mode once it has finished processing its command line (if any). If the OS2_SHELL environment variable does not exist, START will fall back to using the COMSPEC environment variable for the name of the interactive command interpreter, or "CMD" if that environment variable also does not exist.
If neither the /K nor the /C option is used, nothing is prepended to the command line that is passed by START to the command interpreter. The assumption is that the command interpreter will follow the convention of entering interactive mode by default, so the name of the interactive command interpreter is determined in the same way as if the /K option were used.
Note: Always use an explicit /C or /K option if OS2_SHELL (or COMSPEC, if OS2_SHELL does not exist) points to the 16-bit CMD supplied with IBM OS/2. The 16-bit CMD supplied with IBM OS/2 contains a feature inherited from COMMAND on MS/PC-DOS version 2.0 whereby unless it is passed an explicit /C or /K option the first argument on its command line is taken to be a directory name. Considering the reasons for its existence on DOS, which are to do with reloading "transient" code and data into memory, this feature has absolutely no use, and no reason for existence in an OS/2 command interpreter. It should never have been included in the 16-bit CMD supplied with IBM OS/2. The only reason that it cannot be considered an outright bug is that IBM documents it. In any case, when the START command is not given an explicit /C or /K option, it will not pass an explicit /C or /K option to the command interpreter that it spawns. With the 16-bit CMD supplied with IBM OS/2 this will cause unexpected behaviour. Neither TEXTCMD nor JP Software's 4OS2 contain this needless, pointless, useless, and downright silly relic of MS/PC-DOS version 2.0. For best results, set OS2_SHELL to point to either one of them, rather than to the 16-bit CMD supplied with IBM OS/2.
The /MAX, /MIN, /HIDE, and /NOCLOSE options are hints passed to the new process as to how it should display its main window.
The /PM and /TXT options control the type of the process that is run in the new session. In the absence of an explicit type, the type of the process will be the same as the type of the START command process itself. The /PM option forces the process type to be graphical and the /TXT option forces the process type to be textual.
The /WIN and /FS options are the inverses of each other, and simply control whether the new session's console is displayed as a window or full screen. They have no effect on processes of graphical type (i.e. those started with the /PM option or if the type of the START command process itself is graphical and no explicit type was specified) because graphical processes do not have consoles by default.
Note: Because of an irregularity in the IBM OS/2 system API, they also have no effect unless the type of the process is explicitly specified as textual with the /TXT option. If no explicit type for the process is specified, and the type of the START command process itself is textual, then the new session's console will be displayed as a window if Presentation Manager has been started.
Using START on its own, therefore, with no options and no command and arguments, will start an interactive command interpreter running in a new session, whose name was given by the value of the OS2_SHELL environment variable and which is the same type of process as the START command itself.