DosStartSession (OS/2 1.x)

Legacy Function Warning
It is recommended to use a newer replacement for this function.
Replacement:	DosStartSession
Remarks:	This page list the older version of the function for reference.

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:

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:

0 - Start session in foreground.

1 - Start session in background.

traceopt (USHORT) : Specifies tracing options for the program started in the new session:

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