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.