Difference between revisions of "DosStartSession"
From EDM2
m (→Sample Code) |
m |
||
Line 3: | Line 3: | ||
===Parameters=== | ===Parameters=== | ||
− | ;PSTARTDATA ''psd'' (input) | + | ;PSTARTDATA ''psd'' (input): Pointer to a STARTDATA-struct which contains information about the session to start. |
− | : 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->Length'' (input) | + | ; USHORT ''psd->Related'' (input): Start the new session independent or as a child. Values are: |
− | : 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. | + | ::0 SSF_RELATED_INDEPENDENT Start new session independent of the calling session |
− | ; USHORT ''psd->Related'' (input) | + | ::1 SSF_RELATED_CHILD Start new session as a child session to the calling session |
− | : Start the new session independent or as a child. Values are: | + | ; 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 | |
− | ; USHORT ''psd->FgBg'' (input) | + | ::2 SSF_TRACEOPT_TRACEALL Trace all descendant sessions. A termination queue must be supplied and Related must be SSF_RELATED_CHILD (=1). |
− | : Start the new session in the foreground or in the background. Values are: | + | ; 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. | |
− | ; USHORT ''psd->TraceOpt'' (input) | + | ; 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. |
− | : Specifies whether the program started in the new session should be executed under conditions for tracing. Values are: | + | ; 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 | |
− | ; PSZ ''psd->PgmTitle'' (input) | + | ::7 SSF_TYPE_WINDOWEDVDM DOS window |
− | : 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. | + | :Additional values for Windows programs: |
− | ; PSZ ''psd->PgmName'' (input) | + | ::15 PROG_31_STDSEAMLESSVDM Windows 3.1 program in its own windowed session |
− | : Pointer to a string containing a fully qualified pathname of the program to load. | + | ::16 PROG_31_STDSEAMLESSCOMMON Windows 3.1 program in a common windowed session |
− | ; PBYTE ''psd->PgmInputs'' (input) | + | ::17 PROG_31_ENHSEAMLESSVDM Windows 3.1 program in enhanced compatibility mode in its own windowed session |
− | : 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. | + | ::18 PROG_31_ENHSEAMLESSCOMMON Windows 3.1 program in enhanced compatibility mode in a common windowed session |
− | ; PBYTE ''psd->TermQ'' (input) | + | ::19 PROG_31_ENH Windows 3.1 program in enhanced compatibility mode in a full screen session |
− | : 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. | + | ::20 PROG_31_STD Windows 3.1 program in a full screen session |
− | ; PBYTE ''psd->Environment'' (input) | + | ;PSZ ''psd->IconFile'' (input):Pointer to string containing a fully qualified pathname of an .ICO file. NULL for using the default icon. |
− | : 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. | + | ;ULONG ''psd->PgmHandle'' (input):Program handle returned from either WinAddProgram or WinQueryProgramHandle. 0 if these functions are not used. |
− | ; USHORT ''psd->InheritOpt'' (input) | + | ;USHORT ''psd->PgmControl'' (input):Specifies the initial attributes for a OS/2 window or DOS window session. Values are: |
− | : Specifies whether the new session will inherit open file handles and environment from the calling process. 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 | |
− | ; USHORT ''psd->SessionType'' (input) | + | ::8 SSF_CONTROL_NOAUTOCLOSE Window will not close after the program has ended. |
− | : Specifies the type of session to start. Values are: | + | ::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. | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | ;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: | + | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | ; 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=== | ===Returns=== | ||
APIRET rc | APIRET rc | ||
− | 0 | + | 0 NO_ERROR |
− | 369 | + | 369 ERROR_SMG_INVALID_SESSION_ID |
− | 418 | + | 418 ERROR_SMG_INVALID_CALL |
− | 460 | + | 460 ERROR_SMG_PROCESS_NOT_PARENT |
− | 463 | + | 463 ERROR_SMG_RETRY_SUB_ALLOC |
===Include Info=== | ===Include Info=== |
Revision as of 22:34, 9 October 2020
Contents
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; }