DosStartSession (OS/2 1.x)
Description
This call allows a program to start another program in a session.
Syntax
DosStartSession
(StartData, SessID, ProcID)
Parameters
- StartData (PSTARTDATA) - input
- Address of the start session structure:
length (USHORT) : Length in bytes of the data structure, including length. A length of 24 bytes may be specified for OS/2 1.0 applications, or for applications that do not take advantage of the environment or windowing data.
A length of 30 bytes may be specified for OS/2 applications that want to use only the environment and inheritance features.
A length of 50 bytes may be selected for applications that want to use all the functions provided by DosStartSession. However, a length of 50 bytes is not allowed if the Session Manager detects that the Presentation Manager is not present.
related (USHORT) : Specifies whether the session created is related to the calling session, with the following values:
Value Definition 0 New session is an independent session (not related). 1 New session is a child session (related).
An independent session is not a child session and cannot be controlled by the calling program. It cannot be specified as the target of DosSelectSession, DosSetSession, or DosStopSession. Note that termq is ignored for independent sessions, and the value of zero is returned for the SessID and ProcID parameters.
The calling program (parent session) may specify a child session as the target of DosSelectSession, DosSetSession, and DosStopSession, for related sessions. The SessID and ProcID parameters, and termq, are applicable only when related = 1 is specified.
Note also that for related sessions, although a parent session/child session relationship is established, a parent process/child process relationship is not established.
fgbg (USHORT) : Specifies whether the new session should be started in the foreground or background:
Value Definition 0 Start session in foreground. 1 Start session in background.
traceopt (USHORT) : Specifies tracing options for the program started in the new session:
Value Definition 0 Trace off. 1 Trace on; no notification of descendants. 2 Trace on; all descendant sessions.
For traceopt = 2, a termination queue must be supplied and related set to 1. Refer to "Debugger Considerations" in the Remarks section for additional information.
pgmtitle (PSZ) : A far pointer to an ASCIIZ string containing the program title. The string can be up to 61 bytes long, including the terminating byte of 0. If pgmtitle is zero or a NULL pointer, then DosStartSession defaults the program title to the name pgmname points to, minus any leading drive and path information.
pgmname (PSZ) : Can be one of the following:
- A far address to a NULL string.
- A NULL pointer (a far address equal to zero).
- An address of an ASCIIZ string containing the fully qualified drive, path, and file name of the program to be loaded. If pgmname is a far address to a NULL string, or if it is a NULL pointer, the program name defaults to the command processor defined in the CONFIG.SYS/PROTSHELL statement. For example, if PROTSHELL=PMSHELL.EXE CMD.EXE, the program name defaults to CMD.EXE. pgminputs (PBYTE)
A far pointer to an ASCIIZ string containing the input arguments to be passed to the program.
Note: The maximum value allowed for the combined length of pgmname and pgminputs is 1024 characters. For more information on pgmname and pgminputs, see "Program Name/Program Input Considerations:" in the Remarks section.
termq (PBYTE) : Can be one of the following:
- A far address to a NULL string.
- A NULL pointer (a far address equal to zero).
- A far pointer to an ASCIIZ string containing the fully qualified path and file name of an OS/2 queue created by a DosCreateQueue request. See "Parent/Child Termination Considerations" in the Remarks section for additional information.
The process that originally issued the DosStartSession request, also issues DosReadQueue. Because this is the only process that has addressability to the notification data element, it is important that the NoWait parameter of DosReadQueue is set equal to zero. This process must also issue DosFreeSeg to free the segment containing the data element after it reads and processes the data element.
environment (PBYTE) : Can be one of the following:
- A far address to a NULL string.
- A NULL pointer (a far address equal to zero).
- A far pointer to an ASCIIZ environment string (see DosExecPgm) to be passed to the program started in the new session; it may be used for independent or related DosStartSession calls. When environment = 0 (content of the string is not specified and a far address of 0 is passed), the program in the new session inherits the environment of the Shell if inheritopt = 0, or the environment of the program issuing the DosStartSession call if inheritopt = 1.
inheritopt (USHORT) : Specifies whether the program started in the new session should inherit the calling process' environment and open file handles:
Value Definition
0 Inherit from Shell process
1 Inherit from calling process. Note that inheritopt is applicable whether the
session being started is an independent or related session. After the DosStartSession
request has completed, the new program's parent process is the Shell, not the process
that issued the DosStartSession call. See "Parent/Child Relationships" in the Remarks section.
sessiontype (USHORT) : Type of session that should be created for this program:
Value Definition 0 Use pgmhandle or allow the Shell to establish the session type 1 Full screen session 2 Text-windowed session for programs using the Base Video Subsystem 3 Presentation Manager session.
iconfile (PSZ): Can be one of the following:
- A far address to a NULL string
- A NULL pointer (a far address equal to zero)
- A far pointer to an ASCIIZ string containing the fully qualified drive, path and file name of an icon definition. The system provides an icon for windowed applications if an icon file name is not provided on the DosStartSession call.
pgmhandle (ULONG) : This is either 0 or the program handle returned by the WinAddProgram call. The program handle identifies the program in the installation file to be started, the program title, the session type, and the initial window size and position. However, information may be specified on the DosStartSession call to override the information in the installation file for this invocation of the program.
See "Program Handle Considerations:" in the Remarks section for more information.
pgmcontrol (USHORT) : Specifies the initial state for a windowed application. This parameter is ignored for full-screen sessions. The initial window state may be defined as a combination of the following bit values:
Bit Description 15 Use specified position and size. 14-4 Reserved and must be set to zero. 3 No auto close (for windowed session only). 2 Minimize. 1 Maximize. 0 Invisible.
initxpos (USHORT) : Initial X coordinate in pels for the initial session window. Coordinates (0,0) indicate the bottom left corner of the display. This parameter is ignored for full-screen sessions.
initypos (USHORT) : Initial Y coordinate in pels for the initial session window. Coordinates (0,0) indicate the bottom left corner of the display. It is ignored for full-screen sessions.
initxsize (USHORT) : Initial X extent in pels for the initial session window. It is ignored for full-screen sessions.
initysize (USHORT) : Initial Y extent in pels for the initial session window. It is ignored for full-screen sessions.
- SessID (PUSHORT) - output : Address of the session ID associated with the child session created. SessID is returned only when the value specified for related is 1. The SessID returned can be specified on subsequent calls to DosSelectSession, DosSetSession, and DosStopSession.
- ProcID (PUSHORT) - output
- Address of the process ID associated with the child process created. ProcID is returned only when the value specified for related is 1. The ProcID returned may not be used on any OS/2 calls, for example, DosSetPrty, that require a parent process/child process relationship. See "Parent/Child Relationships" in the Remarks section.
Return Code
rc (USHORT) - return
Return code descriptions are:
- 0 NO_ERROR
- 370 ERROR_SMG_NO_SESSIONS
- 418 ERROR_SMG_INVALID_CALL
- 453 ERROR_SMG_INVALID_START_MODE
- 454 ERROR_SMG_INVALID_RELATED_OPT
- 457 ERROR_SMG_START_IN_BACKGROUND
- 460 ERROR_SMG_PROCESS_NOT_PARENT
- 461 ERROR_SMG_INVALID_DATA_LENGTH
- 478 ERROR_SMG_INVALID_TRACE_OPTION
- 491 ERROR _ SMG _ INVALID _ PROGRAM _ TYPE
- 492 ERROR _ SMG _ INVALID _ PGM _ CONTROL
- 493 ERROR _ SMG _ INVALID _ INHERIT _ OPT
- 503 ERROR _ SMG _ INVALID _ DEBUG _ PARMS
Any error code returned from DosOpen, DosLoadModule, and DosExecPgm is also possible from DosStartSession.
Remarks
When a length of 24 bytes is specified, DosStartSession assumes the iconfile, pgmhandle, sessiontype, pgmcontrol, initxpos, initypos, initxsize, and initysize parameters to be 0. A value of 0 allows the Shell to establish the program title, icon definition, session type, program control, window size, and window position for the specified program. Foreground/Background Considerations:
If fgbg = 0 is specified, and if neither the calling program nor any of its descendant sessions is executing in the foreground, the new session is started in the background. The ERROR_SMG_START_IN_BACKGROUND error code is also returned in this case. The foreground session for windowed applications is the session of the application that owns the window focus. Parent/Child Relationships:
When related = 1 is specified, 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. The ProcID returned by DosStartSession may not be used by any OS/2 calls (for example, DosSetPrty) that require a parent process/child process relationship. Once a process has issued a DosStartSession, specifying related = 1, no other process within that session may issue related DosStartSession calls until all the dependent sessions have terminated. Debugger Considerations:
Debuggers may want to debug all processes associated with an application, no matter how the process was started (DosExecPgm or DosStartSession). A special trace option, traceopt = 2, has been provided for this purpose. When traceopt = 2 is specified, the debugger must also supply the name of an existing queue as the termination queue name and related = 1 on the DosStartSession call.
The Session Manager notifies the debugger whenever a new session is created through DosStartSession from the initial session started with traceopt = 2 or from any descending session. The queue is posted regardless of how the new session is started: related, independent, with or without inheritance, and is executed for tracing. It is the responsibility of the debugger to resume the new process' execution through DosPtrace.
The debugger must issue DosReadQueue to receive notification when a child session is created. The word containing the request parameter returned by DosReadQueue is one. The data element structure returned has the following format:
Size Definition WORD Session ID WORD Process ID WORD Parent Session ID WORD Parent Process ID
DosReadQueue, with the NoWait parameter set to zero, should be issued by the debugger. 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 containing the data element using DosFreeSeg.
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.
Some debuggers may enhance usability by using more than one display. Therefore, when a debugger registers with the Session Manager by using a traceopt of 2, the debugger is allowed to update the physical video buffer in the range of B000-B7FF, as long as the foreground session is a descendant of the debugger. The debugger is not allowed to update the physical video buffer when a session is switched into the foreground that is not a descendant of the debugger or when a popup occurs. Program Name/Program Input 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 drive, path, and file name of the application to be loaded for pgminputs. If the /C parameter is inserted at the beginning of the pgminputs string, the session terminates when the application program terminates. If the /K parameter is inserted at the beginning of the pgminputs string, the operator sees the OS/2 command line prompt displayed when the application terminates. The operator can then either enter the name of another program or command to execute or enter the OS/2 EXIT command to terminate the session.
When the pgmname is accessed with a far address of 0 or the ASCIIZ string is null, the program specified as a parameter to the Shell in the PROTSHELL statement in the CONFIG.SYS file is executed and passed the specified pgminputs. This is the OS/2 mode command processor (CMD.EXE) by default.
When pgmname is equal to the command processor named on the PROTSHELL statement in CONFIG.SYS, or when the pgmname = NULL and length = 24 or 30 bytes, either the command processor named in CONFIG.SYS or the default CMD.EXE is started within the same session as the caller of DosStartSession. Program Handle Considerations:
If a process issues a DosStartSession specifying only the program handle, it must change to the working directory before it issues the DosStartSession, and start the new process inherited. If a process is started with inheritopt = 0, that process must change to the correct directory. Parent/Child Termination Considerations:
A parent session has only one termination queue. The parent creates the termination queue before it issues its first DosStartSession call specifying the name of the queue. An application can use the termination queue for another purpose by passing a unique request parameter through the DosWriteQueue/DosReadQueue interface. Request parameter values 0 through 99 are reserved for OS/2. Request parameter values greater than 99 are available for application use.
If a parent session specifies the termq parameter on more than one DosStartSession call, the parameter is ignored on subsequent calls. Once a parent establishes a termination queue, the queue is posted when any child session terminates. 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. The termq data element structure has the following format:
Size Description WORD Session ID of child WORD Result code.
When a child session terminates, the result code returned in the termq data element is the result code of the program specified by pgmname assuming either:
The program is executed directly with no intermediate secondary command (CMD.EXE) process, or 2.
The program is executed indirectly through a secondary command (CMD.EXE) process and the /C parameter is specified.
If the program is executed indirectly through a secondary command (CMD.EXE) process and the /K parameter is specified, the result code of the processed command is returned.
When a child session running in the foreground terminates, the parent session becomes the foreground session. When a parent session terminates, any child sessions it created with DosStartSession, specifying related = 1, are terminated. When an independent session, created specifying related = 0, running in the foreground terminates, the Shell chooses the next foreground session. Descendant Considerations:
A session started through DosStartSession may in turn issue DosStartSession. These rules apply:
- The SessID specified on DosSelectSession, DosSetSession, and DosStopSession may be only the SessID of an immediate child session, not a grandchild session, and so forth.
- Suppose a bond is established between session A and its immediate child session B, and another bond is established between session B and its immediate child session C. When the operator selects session A, session C is brought to the foreground. See DosSetSession for a description of what establishing a bond means.
- When a session terminates, all of its descendants (children,grandchildren ,andsoforth )areterminated .
ApplicationTypeConsideration :
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.
Example Code
C Binding
typedef struct _STARTDATA { /* stdata */
USHORT cb; /* length of data structure in bytes */
USHORT Related; /* 0=independent session, 1=child session */
USHORT FgBg; /* 0=start in foreground, 1=start in background */
USHORT TraceOpt; /* 0=no trace, 1=trace */
PSZ PgmTitle; /* address of program title */
PSZ PgmName; /* address of program name */
PBYTE PgmInputs; /* input arguments */
PBYTE TermQ; /* address of program queue name */
PBYTE Environment; /* address of environment string */
USHORT InheritOpt; /* inherit option (shell of program) */
USHORT SessionType; /* session type (standard, windowed, ...) */
PSZ IconFile; /* address of icon definition */
ULONG PgmHandle; /* program handle */
USHORT PgmControl; /* initial state of windowed application */
USHORT InitXPos; /* x coordinate of initial session window */
USHORT InitYPos; /* y coordinate of initial session window */
USHORT InitXSize; /* initial size of x */
USHORT InitYSize; /* initial size of y */
} STARTDATA;
#define INCL_DOSSESMGR
USHORT rc = DosStartSession(StartData, SessID, PID);
PSTARTDATA StartData; /* Start session data */
PUSHORT SessID; /* Session ID (returned) */
PUSHORT PID; /* Process ID (returned) */
USHORT rc; /* return code */
MASM Binding
STARTDATA struc stdata_Length dw ? ;length of data structure in bytes stdata_Related dw ? ;0=independent session, 1=child session stdata_FgBg dw ? ;0=start in foreground, 1=start in background stdata_TraceOpt dw ? ;0=no trace, 1=trace stdata_PgmTitle dd ? ;address of program title stdata_PgmName dd ? ;address of program name stdata_PgmInputs dd ? ;input arguments stdata_TermQ dd ? ;address of program queue name stdata_Environment dd ? ;address of environment string stdata_InheritOpt dw ? ;inherit option (shell of program) stdata_SessionType dw ? ;session type (standard, windowed, ...) stdata_IconFile dd ? ;address of icon definition stdata_PgmHandle dd ? ;program handle stdata_PgmControl dw ? ;initial state of windowed application stdata_InitXPos dw ? ;x coordinate of initial session window stdata_InitYPos dw ? ;y coordinate of initial session window stdata_InitXSize dw ? ;initial size of x stdata_InitYSize dw ? ;initial size of y STARTDATA ends EXTRN DosStartSession:FAR INCL_DOSSESMGR EQU 1 PUSH@ OTHER StartData ;Start session data PUSH@ WORD SessID ;Session ID (returned) PUSH@ WORD PID ;Process ID (returned) CALL DosStartSession Returns WORD