DosStartSession

Syntax
DosStartSession( psd, pulIDSession, ppid )

Parameters

 * PSTARTDATA psd (input)
 * Pointer to a STARTDATA-struct which contains information about the session to start.


 * USHORT psd->Length (input)
 * The length can be set to either 24, 30, 32, 50, or 60 bytes depending on what features you want to use. At least 32 must be used to start a DOS session with the session type specified. A Length greater than 32 is not allowed if the Presentation Manager is not present. When setting Length to 24 or 30, DosStartSession initializes the missing parameters to zero. This allows the shell to provide values for missing information. A Length of 30 will use the environment and inheritance features of the system. Specifying a length of 50 will let you specify the type of session to start and to define data for windows. Finally, a length of 60(=sizeof(STARTDATA)) will let you use all the functions provided.


 * USHORT psd->Related (input)
 * Start the new session independent or as a child. Values are:

Value Name                    Description 0    SSF_RELATED_INDEPENDENT  Start new session independent of the calling session 1    SSF_RELATED_CHILD        Start new session as a child session to the calling session
 * USHORT psd->FgBg (input)
 * Start the new session in the foreground or in the background. Values are:

Value Name           Description 0     SSF_FGBG_FORE  Start new session in foreground 1     SSF_FGBG_BACK  Start new session in background
 * USHORT psd->TraceOpt (input)
 * Specifies whether the program started in the new session should be executed under conditions for tracing. Values are:

Value Name                   Description 0     SSF_TRACEOPT_NONE      No trace 1     SSF_TRACEOPT_TRACE     Trace with no notification of                               descendants 2     SSF_TRACEOPT_TRACEALL  Trace all descendant sessions. A termination queue must be                              supplied and Related must be                               SSF_RELATED_CHILD (=1).
 * PSZ psd->PgmTitle (input)
 * Pointer to a string containing the name of the program to be called, used for any windows or task list. If NULL the name of the executable is used.


 * PSZ psd->PgmName (input)
 * Pointer to a string containing a fully qualified pathname of the program to load.


 * PBYTE psd->PgmInputs (input)
 * Pointer to strings containing the arguments to be passed to the program. First string contains the name of the executable. After the last string an additional null character must be inserted.


 * PBYTE psd->TermQ (input)
 * Pointer to a string which contains the name of a queue, "the termination queue", to be notified when the program ends. NULL for no queue. The data sent to the queue is on the form: USHORT Session ID, USHORT Return Code.


 * PBYTE psd->Environment (input)
 * Pointer to strings containing environments variables on the form variable=value. The last string is followed by an additional null character. This field is reserved for DOS sessions and must always be zero. Use AUTOEXEC.BAT to define environment variables.


 * USHORT psd->InheritOpt (input)
 * Specifies whether the new session will inherit open file handles and environment from the calling process. Values are:

Value Name                  Description 0     SSF_INHERTOPT_SHELL   Inherit from the shell 1     SSF_INHERTOPT_PARENT  Inherit from the calling process
 * USHORT psd->SessionType (input)
 * Specifies the type of session to start. Values are:

Value Name                    Description 0     SSF_TYPE_DEFAULT        Use program's type 1     SSF_TYPE_FULLSCREEN     OS/2 full screen 2     SSF_TYPE_WINDOWABLEVIO  OS/2 window 3     SSF_TYPE_PM             Presentation Manager 4     SSF_TYPE_VDM            DOS full screen 7     SSF_TYPE_WINDOWEDVDM    DOS window Additional values for Windows programs: Value Name                       Description 15    PROG_31_STDSEAMLESSVDM     Windows 3.1 program in its own windowed session 16    PROG_31_STDSEAMLESSCOMMON  Windows 3.1 program in a common windowed session 17    PROG_31_ENHSEAMLESSVDM     Windows 3.1 program in enhanced compatibility mode in its own windowed session 18    PROG_31_ENHSEAMLESSCOMMON  Windows 3.1 program in enhanced compatibility mode in a common windowed session 19    PROG_31_ENH                Windows 3.1 program in enhanced compatibility mode in a full screen session 20    PROG_31_STD                Windows 3.1 program in a full screen session
 * PSZ psd->IconFile (input)
 * Pointer to string containing a fully qualified pathname of an .ICO file. NULL for using the default icon.


 * ULONG psd->PgmHandle (input)
 * Program handle returned from either WinAddProgram or WinQueryProgramHandle. 0 if these functions are not used.


 * USHORT psd->PgmControl (input)
 * Specifies the initial attributes for a OS/2 window or DOS window session. Values are:

Value Name                     Description 0     SSF_CONTROL_VISIBLE      Window is visible 1     SSF_CONTROL_INVISIBLE    Window is invisible 2     SSF_CONTROL_MAXIMIZE     Window is maximized 4     SSF_CONTROL_MINIMIZE     Window is minimized 8     SSF_CONTROL_NOAUTOCLOSE  Window will not close after the program has ended. 32768 SSF_CONTROL_SETPOS       Use InitXPos, InitYPos, InitXSize, and InitYSize for the size and placement.
 * USHORT psd->InitXPos (input)
 * X-position of a windowed session. Must use SSF_CONTROL_SETPOS.


 * USHORT psd->InitYPos (input)
 * Y-position of a windowed session. Must use SSF_CONTROL_SETPOS.


 * USHORT psd->InitXSize (input)
 * X-size of a windowed session. Must use SSF_CONTROL_SETPOS.


 * USHORT psd->InitYSize (input)
 * Y-size of a windowed session. Must use SSF_CONTROL_SETPOS.


 * USHORT psd->Reserved (input)
 * Reserved word for fufture use. Set to 0.


 * PSZ psd->ObjectBuffer (input)
 * Pointer to a buffer which will contain the name of the contributing object in case of a failure of DosExecPgm. DosStartSession calls DosExecPgm to start all full-screen, VIO windowed and Presentation Manager programs.


 * ULONG psd->ObjectBuffLen (input)
 * Length of ObjectBuffer. In bytes.


 * PULONG pulIDSession (output)
 * Pointer to a doubleword which will contain the session ID of the child session started. Only returned when the value of psd->Related is 1.


 * PPID ppid (output)
 * Pointer to a doubleword which will contain the process ID the child session started. Only returned when the value of psd->Related is 1.

Returns
APIRET rc 0       NO_ERROR 369    ERROR_SMG_INVALID_SESSION_ID 418    ERROR_SMG_INVALID_CALL 460    ERROR_SMG_PROCESS_NOT_PARENT 463    ERROR_SMG_RETRY_SUB_ALLOC

Include Info

 * 1) define INCL_DOSSESMGR
 * 2) include 

Usage Explanation
DosStartSession is used to start another session, this session can be of any type, as opposed to sessions started with DosExecPgm, and they can be either independent or child sessions. If the session is a child session, you may use DosSelectSession, DosSetSession and DosStopSession to manipulate the child sessions features. You can only manipulate a child session and not any grandchild sessions or other descendant.