![[Toc]](../../toc.gif)
![[Index]](/idx.gif)
DosStartSession
Bindings: C, MASM
This call allows a program to start another program in a session.
DosStartSession (StartData, SessID, ProcID)
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:
o A far address to a NULL string.
o A NULL pointer (a far address equal to zero).
o 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:
o A far address to a NULL string.
o A NULL pointer (a far address equal to zero).
o 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:
o A far address to a NULL string.
o A NULL pointer (a far address equal to zero).
o 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:
o A far address to a NULL string
o A NULL pointer (a far address equal to zero)
o 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.
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:
1. 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:
o 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.
o 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.
o When a session terminates, all of its descendants (children,
grandchildren, and so forth) are terminated.
Application Type Consideration:
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.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs