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:

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:

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:

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:

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:

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:

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:

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.

Sample Code

/* 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;
}