DosStartSession

From EDM2
(Redirected from OS2 API:DosStartSession)
Jump to: navigation, search

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;

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

See Also