[ Home |
Alpha index |
Topic index |
Tutorials |
Download |
Feedback ]
The OS/2 API Project
DosStartSession
[ Syntax |
Params |
Returns |
Include |
Usage |
Structs |
Gotchas |
Code |
Also ]
Syntax
rc = 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 of 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
#define INCL_DOSSESMGR
#include <os2.h>
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.
Relevant Structures
typedef struct _STARTDATA
{
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;
} STARTDATA, *PSTARTDATA;
Gotchas
Sample Code
<![CDATA[
/* Start a child process and return it's session ID.
Wait for the session to end and get it's session ID
from the termination queue */
#define INCL_DOSQUEUES
/* For Queue commands */
#define INCL_DOSSESMGR
/* For DosStartSession */
#define INCL_DOSMEMMGR
/* For DosFreeMem */
#include <os2.h>
#include <stdio.h>
/* For printf */
#include <memory.h>
/* For memset */
typedef struct _CHILDINFO { /* Define a structure for the queue data */
USHORT usSessionID;
USHORT usReturn;
} CHILDINFO;
int main()
{
HQUEUE hqQueue; /* Queue handle */
REQUESTDATA rdRequest; /* Request data for the queue */
ULONG ulSzData; /* Size of the queue data */
BYTE bPriority; /* For the queue */
PVOID pvData; /* Pointer to the queue data */
STARTDATA sd; /* Start Data for DosStartSession */
PID pid; /* PID for the started child session */
ULONG ulSession; /* Session ID for the child session */
APIRET rc; /* Return code from API's */
memset(&sd,0,sizeof(STARTDATA)); /* Clear the STARTDATA structure,
so we only initialize the values we care about */
sd.Length = sizeof(STARTDATA); /* Set size of STARTDATA, use the default */
sd.Related = SSF_RELATED_CHILD; /* Start a child session */
sd.PgmName="F:\\OS2\\APPS\\EPM.EXE"; /* Name and path of the app to start */
sd.TermQ="\\QUEUES\\CHILD.QUE"; /* Name of the termination queue */
/* Create a queue */
if(!(rc = DosCreateQueue(&hqQueue, QUE_FIFO | QUE_CONVERT_ADDRESS,"\\QUEUES\\CHILD.QUE")))
{
/* Start the child session */
if(!(rc=DosStartSession(&sd, &ulSession, &pid)))
{
/* Print the session ID for the child session */
printf("SessionID: %d\n",(USHORT)ulSession);
/* Wait for the child session to end (you'll have to end it in some other way */
if(!(rc=DosReadQueue(hqQueue, &rdRequest, &ulSzData, &pvData, 0, 0, &bPriority, 0)))
{
/* Print the session ID read from the queue */
printf("SessionID: %d\n", ((CHILDINFO*)pvData)->usSessionID);
/* Free the memory of the queue data element read */
DosFreeMem(pvData);
}
else
{
printf("Error in DosReadQueue: %d", (int)rc);
}
}
else
{
printf("Error in DosStartSession: %d\n", (int)rc);
}
DosCloseQueue(hqQueue);
}
else
{
printf("Error in DosCreateQueue: %d\n", (int)rc);
}
return 0;
}
]]>
See Also
DosStopSession,
DosSetSession,
DosSelectSession,
DosExecPgm
Author
Oscar Gustafsson -
oscar@lysator.liu.se
Additions
Last modified September 21/1996
Please send all errors, comments, and suggestions to:
timur@vnet.ibm.com
The OS/2 API Project |
DosStartSession |