DosStartSession allows an application to start another session, and to specify the name of the program to be started in that session.
A session can be thought of as a logical console, consisting of buffers for the screen, keyboard, and mouse.
New sessions may only be started in the foreground when the caller's session (or one of the caller's descendant sessions) is currently executing in the foreground. The foreground session for windowed applications is the session of the application that owns the window focus. The new session appears in the Shell switch list.
Any protect-mode application may start any other protect-mode application in a new session, regardless of the issuing program's session type.
You may use DosExecPgm to start a process that is of the same type as the starting process. Process types include Presentation Manager, text-windowed, and full-screen. You may not use DosExecPgm to start a process that is of a different type than the starting process.
You must use DosStartSession to start a new process from a process that is of a different type. For example, use DosStartSession to start a Presentation Manager process from a non-Presentation Manager process.
If you call DosStartSession from a detached process, the function returns ERROR_SMG_INVALID_CALL. This happens regardless of whether the session is to be started in the foreground or in the background. Detached processes are programs that:
Detached processes are started when:
See DosExecPgm for more information on detached processes.
Foreground/Background Considerations
DosStartSession will only start a new session in the foreground if the program issuing DosStartSession or a descendent session is executing in the foreground session. Otherwise, DosStartSession will override the foreground request and start the new session in the background. A unique error is returned, ERROR_SMG_START_IN_BACKGROUND, indicating that the new session was started in the background. An active popup window may also prevent the new session from starting in the foreground. The foreground session for windowed applications is the session of the application that owns the window focus. Therefore, when a windowed session is started in the foreground, the new session will be given the window focus.
Parent/Child Relationship
When you specify SSF_RELATED_CHILD for Related, DosStartSession establishes a parent session/child session relationship. A parent process/child process relationship is not established. The parent process is the shell process just as if the operator had started the program from the shell menu. Therefore, the ppid returned by DosStartSession may not be used with any system functions (for example, DosSetPriority) that require a parent process/child process relationship.
Once a process has issued DosStartSession specifying SSF_RELATED_CHILD for Related, no other process within that session can issue related DosStartSession functions until all the dependent sessions have ended.
Debugger Considerations
Debuggers may want to debug all processes associated with an application, no matter how the process was started (by DosExecPgm or DosStartSession). A special trace option, TraceOpt value 2, has been provided for this purpose. When a value of 2 is specified for TraceOpt, the debugger must also supply the name of an existing queue, and a value of 1 for Related, on the DosStartSession function.
The Session Manager notifies the debugger whenever a new session is created through DosStartSession from the initial session started with a value of 2 for TraceOpt, or from any descendant session. The queue is posted regardless of how the new session is started (related, independent, with or without inheritance).
Note: If the first session started by the parent process (debugger) ends, any messages generated by descendent sessions of the first session will not get posted to the parent process (debugger). For example, session A starts session B. Session B, in turn, starts session C and D. When session B ends, the messages from sessions C and D will not get posted to session A.
Sessions started without inheritance are executed for tracing. It is the responsibility of the debugger to resume execution of the new process.
The debugger must issue DosReadQueue to receive notification when a child session is created. The word containing the request parameter, returned by DosReadQueue, will have a value of 1. The data element structure has the following format:
Size
The debugger should issue DosReadQueue with the wait parameter set to 0. This is the only process that has addressability to the notification data element. After reading and processing the data element, the debugger must free the segment that contains the data element by issuing DosFreeMem.
The debugger may use DosSelectSession to switch itself or any descendant session into the foreground whenever the current foreground session is a descendant of the debugger.
PgmName and PgmInputs Considerations
The program identified by PgmName is executed directly, with no intermediate secondary command (CMD.EXE) process. Alternatively, the program can be executed indirectly through a secondary command (CMD.EXE) process by specifying CMD.EXE for PgmName, and by specifying either /C or /K followed by the file specification of the application to be loaded for PgmInputs. If the /C parameter is inserted at the beginning of the PgmInputs string, then when the application program ends, the session ends. If the /K parameter is inserted at the beginning of the PgmInputs string, then when the application ends, the operator sees the system command line prompt displayed. The operator can then either enter the name of another program or command to execute, or enter the EXIT command to end the session.
When the PgmName address is 0, or the ASCIIZ string is null, the program identified by the PgmHandle is started in the new session. If the PgmHandle is not specified, then the program specified as a parameter to the protect mode shell on the OS2_SHELL statement, or on the SHELL statement for a DOS session, in the configuration file (CONFIG.SYS) is executed and passed the specified PgmInputs. The default is the program name for the command processor (CMD.EXE for a non-DOS session, or COMMAND.COM for a DOS session).
The PgmName and PgmInputs strings combined length may not exceed 1024 characters.
Program Handle Considerations
If a process issues DosStartSession specifying only the program handle, then it must change to the working directory before issuing DosStartSession, and start the new process as inherited. If a process is started as non-inherited, it is up to that process to change to the correct directory.
Parent/Child Termination Considerations
The parent must create the termination queue prior to specifying the queue name on DosStartSession. The Session Manager will continue to notify the parent session through the specified queue as long as the process issuing DosStartSession remains a parent session. When all the child sessions for a particular parent session end, the termination queue is closed by the Session Manager. An existing queue name must be specified on the next DosStartSession function if the caller wants to continue receiving termination notification messages. The caller must use the same queue for all calls to DosStartSession.
The Session Manager writes a data element into the specified queue when any child session ends. The queue is posted regardless of who terminates the child session (for example, child, parent, or operator) and whether the termination is normal or abnormal.
A parent session issues DosReadQueue to receive notification when a child session has ended. The word that contains the request parameter, returned by DosReadQueue will be 0. The data element structure has the following format:
Size
The process that originally issued DosStartSession should issue DosReadQueue with the wait parameter set to 0. This is the only process that has addressability to the notification data element. After reading and processing the data element, the caller must free the segment containing the data element by issuing DosFreeMem.
An application may use the termination queue for additional interprocess communication, provided that a unique request identifier is passed via DosWriteQueue. Request identifier values 0 through 99 are reserved for the operating system. Request identifier values equal to or greater than 100 are available for application use.
When a child session ends, the result code returned in the TermQ data element is the result code of the program specified by PgmName assuming either:
Otherwise, the result code of CMD.EXE is returned.
When a child session is executing in the foreground at the time it ends, the parent session becomes the foreground session. When a parent session ends, all child sessions that it created with DosStartSession, specifying a value of 1 for Related, are ended. When an independent session, created specifying a value of 0 for Related, ends in the foreground, the Shell selects the next foreground session.
Grandchildren Considerations
A session started through DosStartSession may issue DosStartSession. The following rules apply: