STARTDATA
STARTDATA
Start session data
Type
USHORT Length USHORT Related USHORT FgBg USHORT TraceOpt PSZ PgmTitle PSZ PgmName PBYTE PgmInputs PBYTE TermQ PBYTE Environment USHORT InheritOpt USHORT SessionType PSZ IconFile ULONG PgmHandle USHORT PgmControl USHORT InitXPos USHORT InitYPos USHORT InitXSize USHORT InitYSize USHORT Reserved PSZ ObjectBuffer ULONG ObjectBuffLen
C Declaration Method
typedef struct
Fields
Length The length of the data structure, in bytes, including Length
itself.
A length of at least 32 bytes must be used to start a DOS
session with the session type specified. A length greater than
32 is not allowed if the Session Manager detects that the
Presentation Manager is not present.
When a Length of 24 or 30 bytes is specified, DosStartSession
initializes the missing parameters to 0. This allows the Shell
to provide values for the missing information, based on the
installation file entry for the program being started.
Specify a Length of 30 bytes to use the environment and
inheritance features of the system. Specify a Length of 50 bytes
to specify the type of session to start, and to define data for
windows.
A Length of 60 bytes allows you to use all of the functions
provided by DosStartSession.
Related An indicator which specifies whether the session created is
related to the calling session.
The values of this field are as follows:
0 SSF_RELATED_INDEPENDENT
New session is an independent session (not related).
1 SSF_RELATED_CHILD
New session is a child session (related).
An independent session cannot be controlled by the calling
program. It may not be specified as the target of
DosSelectSession, DosSetSession or DosStopSession. The TermQ
field is ignored for independent sessions.
FgBg An indicator which specifies whether the new session should be
started in the foreground or background.
If a windowed session is started in the foreground, the new
session will be given the window focus. The values of this field
are described in the following list:
0 SSF_FGBG_FORE Start session in foreground
1 SSF_FGBG_BACK Start session in background
TraceOpt An indicator which specifies whether the program started in the
new session should be executed under conditions for tracing.
The values of this field are described in the following list:
0 SSF_TRACEOPT_NONE No trace.
1 SSF_TRACEOPT_TRACE Trace with no notification of descendants.
2 SSF_TRACEOPT_TRACEALL Trace all descendant sessions.
Related equals 1 and a termination queue must be supplied when
this value is specified.
PgmTitle Address of an ASCIIZ string that contains the program title.
The string can be up to 61 bytes long, including the terminating
byte of 0. If the address specified is 0, or if the ASCIIZ
string is null, then the initial title is PgmName minus any
leading drive and path information.
PgmName The address of an ASCIIZ string that contains the file
specification of the program to be loaded.
If the address specified is 0, or if the ASCIIZ string is null,
then the program identified by the PgmHandle is started in the
new session.
PgmInputs Either 0 or the address of an ASCIIZ string that contains the
input arguments to be passed to the program.
TermQ Either 0 or the address of an ASCIIZ string that contains the
file specification of a system queue.
This field is ignored when Related is set to
SSF_RELATED_INDEPENDENT.
Environment The address of an environment string to be passed to the program
started in the new session.
This parameter may be used for independent or related
DosStartSession functions.
When the Environment field is 0, the program in the new session
inherits the environment of the Shell if the InheritOpt field is
equal to SSF_INHERTOPT_SHELL, or the environment of the program
issuing DosStartSession if the InheritOpt field is equal to
SSF_INHERTOPT_PARENT.
DOS Sessions
By default, the DOS session processes the AUTOEXEC.BAT file on
the DOS startup drive. Environment variables may be set in the
AUTOEXEC.BAT file or by specifying them via this parameter. Any
setting available from the DOS setting notebook may also be set
here. For instance, to have D:\MYEXEC.BAT run instead of
AUTOEXEC.BAT, enable direct access to the hardware timer,
disable the break key, and set the real memory size to
256K, specify the environment string as:
myenv = "DOS_AUTOEXEC=D:\\MYEXEC.BAT\0
HW_TIMER=1\0DOS_BREAK=0\0OS_RMSIZE=256\0";
InheritOpt Specifies whether the program started in the new session should
inherit the calling program's environment and open file handles.
The values of this field are described in the following list:
0 SSF_INHERTOPT_SHELL
Inherit the Shell's environment.
1 SSF_INHERTOPT_PARENT
Inherit the environment of the program issuing the
DosStartSession call.
The InheritOpt field may be used for independent or related
DosStartSession functions. Therefore, a DosStartSession function
with the InheritOpt field equal to SSF_INHERTOPT_PARENT is
equivalent to DosExecPgm, except that the new program does not
inherit the priority of the parent process, or the keyboard and
video characteristics associated
with the parent session. Also, a parent process/child process
relationship is not established.
The InheritOpt field for a DOS session is different than the
InheritOpt field for a non-DOS session. An InheritOpt value of
SSF_INHERTOPT_PARENT for a DOS session only inherits the
parent's current drive and path. It does not inherit the
parent's environment.
SessionType The type of session that should be created for this program.
The values of this field are shown in the list below:
0 SSF_TYPE_DEFAULT
Use the PgmHandle data, or allow the Shell to establish the
session type.
1 SSF_TYPE_FULLSCREEN
Start the program in a full-screen session.
2 SSF_TYPE_WINDOWABLEVIO
Start the program in a windowed session for programs using
the Base Video Subsystem.
3 SSF_TYPE_PM.
Start the program in a windowed session for programs using
the Presentation Manager (including AVIO calls).
4 SSF_TYPE_VDM
Start the program in a full-screen DOS session.
7 SSF_TYPE_WINDOWEDVDM
Start the program in a windowed DOS session.
IconFile Either 0 or the address of an ASCIIZ string that contains the
file specification of an icon definition.
If you do not provide an icon file name with DosStartSession,
the system looks for an associated icon file (with a file
extension of .ICO, or an extended attribute of .ICON). The
system provides a default icon if an icon file name is not
provided with DosStartSession.
PgmHandle Either 0 or the program handle.
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 with DosStartSession to override the information in
the installation file for this invocation of the program.
PgmControl An indicator which specifies the initial state for a windowed
application. This field is ignored for full-screen sessions.
The bits in this field have the following values:
Bit Description
15 SSF_CONTROL_SETPOS (0x8000) Use specified size and position
4-14 Reserved
3 SSF_CONTROL_NOAUTOCLOSE (0x0008) No Auto Close
2 SSF_CONTROL_MINIMIZE (0x0004) Minimize
1 SSF_CONTROL_MAXIMIZE (0x0002) Maximize
0 SSF_CONTROL_INVISIBLE (0x0001) Invisible
0 SSF_CONTROL_VISIBLE (0x0000) Visible
Note: The "No Auto Close" bit is used only for VIO
Windowable applications, and is ignored for all other
types of applications.
InitXPos The initial x-coordinate, in pels, for the initial session
window. Coordinates (0,0) indicate the bottom left corner of the
display. This field is ignored for full-screen sessions.
InitYPos The initial y-coordinate, in pels, for the initial session
window. Coordinates (0,0) indicate the bottom left corner of the
display. This field is ignored for full-screen sessions.
InitXSize The initial x extent, in pels, for the initial session window.
This field is ignored for full-screen sessions.
InitYSize The initial y extent, in pels, for the initial session window.
This field is ignored for full-screen sessions.
Reserved Reserved; must be zero.
ObjectBuffer Buffer in which the name of the object that contributed to the
failure of DosExecPgm is returned.
The name of the object is usually the name of a dynamic link
library that could not be loaded.
DosStartSession calls DosExecPgm to start all full-screen, VIO
windowed, and Presentation Manager programs.
ObjectBuffLen The length, in bytes, of the buffer pointed to by ObjectBuffer.