DosStartSession (OS/2 1.x)

From EDM2
Jump to: navigation, search

This call allows a program to start another program in a session.

Syntax

DosStartSession (StartData, SessID, ProcID)

Parameters

StartData (PSTARTDATA) - input 
Address of the start session structure
SessID (PUSHORT) - output
Address of the session ID associated with the child session created. SessID is returned only when the value specified for related is 1. The SessID returned can be specified on subsequent calls to DosSelectSession, DosSetSession, and DosStopSession.
ProcID (PUSHORT) - output
Address of the process ID associated with the child process created. ProcID is returned only when the value specified for related is 1. The ProcID returned may not be used on any OS/2 calls, for example, DosSetPrty, that require a parent process/child process relationship. See "Parent/Child Relationships" in the Remarks section.

Return Code

rc (USHORT) - return
Return code descriptions are:
  • 0 NO_ERROR
  • 370 ERROR_SMG_NO_SESSIONS
  • 418 ERROR_SMG_INVALID_CALL
  • 453 ERROR_SMG_INVALID_START_MODE
  • 454 ERROR_SMG_INVALID_RELATED_OPT
  • 457 ERROR_SMG_START_IN_BACKGROUND
  • 460 ERROR_SMG_PROCESS_NOT_PARENT
  • 461 ERROR_SMG_INVALID_DATA_LENGTH
  • 478 ERROR_SMG_INVALID_TRACE_OPTION
  • 491 ERROR_SMG_INVALID_PROGRAM_TYPE
  • 492 ERROR_SMG_INVALID_PGM_CONTROL
  • 493 ERROR_SMG_INVALID_INHERIT_OPT
  • 503 ERROR_SMG_INVALID_DEBUG_PARMS

Any error code returned from DosOpen, DosLoadModule, and DosExecPgm is also possible from DosStartSession.

Remarks

When a length of 24 bytes is specified, DosStartSession assumes the iconfile, pgmhandle, sessiontype, pgmcontrol, initxpos, initypos, initxsize, and initysize parameters to be 0. A value of 0 allows the Shell to establish the program title, icon definition, session type, program control, window size, and window position for the specified program.

Foreground/Background Considerations
If fgbg = 0 is specified, and if neither the calling program nor any of its descendant sessions is executing in the foreground, the new session is started in the background. The ERROR_SMG_START_IN_BACKGROUND error code is also returned in this case. The foreground session for windowed applications is the session of the application that owns the window focus.
Parent/Child Relationships
When related = 1 is specified, DosStartSession establishes a parent session/child session relationship. A parent process/child process relationship is not established. The parent process is the Shell process, just as if the operator had started the program from the Shell menu. The ProcID returned by DosStartSession may not be used by any OS/2 calls (for example, DosSetPrty) that require a parent process/child process relationship. Once a process has issued a DosStartSession, specifying related = 1, no other process within that session may issue related DosStartSession calls until all the dependent sessions have terminated.
Debugger Considerations
Debuggers may want to debug all processes associated with an application, no matter how the process was started (DosExecPgm or DosStartSession). A special trace option, traceopt = 2, has been provided for this purpose. When traceopt = 2 is specified, the debugger must also supply the name of an existing queue as the termination queue name and related = 1 on the DosStartSession call.
The Session Manager notifies the debugger whenever a new session is created through DosStartSession from the initial session started with traceopt = 2 or from any descending session. The queue is posted regardless of how the new session is started: related, independent, with or without inheritance, and is executed for tracing. It is the responsibility of the debugger to resume the new process' execution through DosPtrace.
The debugger must issue DosReadQueue to receive notification when a child session is created. The word containing the request parameter returned by DosReadQueue is one. The data element structure returned has the following format: 
Size    Definition 
WORD    Session ID
WORD    Process ID
WORD    Parent Session ID
WORD    Parent Process ID
DosReadQueue, with the NoWait parameter set to zero, should be issued by the debugger. This is the only process that has addressability to the notification data element. After reading and processing the data element, the debugger must free the segment containing the data element using DosFreeSeg.
The debugger may use DosSelectSession to switch itself or any descendant session into the foreground whenever the current foreground session is a descendant of the debugger.
Some debuggers may enhance usability by using more than one display. Therefore, when a debugger registers with the Session Manager by using a traceopt of 2, the debugger is allowed to update the physical video buffer in the range of B000-B7FF, as long as the foreground session is a descendant of the debugger. The debugger is not allowed to update the physical video buffer when a session is switched into the foreground that is not a descendant of the debugger or when a popup occurs.
Program Name/Program Input Considerations
The program identified by pgmname is executed directly with no intermediate secondary command

(CMD.EXE) process. Alternatively, the program can be executed indirectly through a secondary command (CMD.EXE) process by specifying CMD.EXE for pgmname and by specifying either /C or /K followed by the drive, path, and file name of the application to be loaded for pgminputs. If the /C parameter is inserted at the beginning of the pgminputs string, the session terminates when the application program terminates. If the /K parameter is inserted at the beginning of the pgminputs string, the operator sees the OS/2 command line prompt displayed when the application terminates. The operator can then either enter the name of another program or command to execute or enter the OS/2 EXIT command to terminate the session.

When the pgmname is accessed with a far address of 0 or the ASCIIZ string is null, the program specified as a parameter to the Shell in the PROTSHELL statement in the CONFIG.SYS file is executed and passed the specified pgminputs. This is the OS/2 mode command processor (CMD.EXE) by default.
When pgmname is equal to the command processor named on the PROTSHELL statement in CONFIG.SYS, or when the pgmname = NULL and length = 24 or 30 bytes, either the command processor named in CONFIG.SYS or the default CMD.EXE is started within the same session as the caller of DosStartSession.
Program Handle Considerations
If a process issues a DosStartSession specifying only the program handle, it must change to the working directory before it issues the DosStartSession, and start the new process inherited. If a process is started with inheritopt = 0, that process must change to the correct directory.
Parent/Child Termination Considerations
A parent session has only one termination queue. The parent creates the termination queue before it issues its first DosStartSession call specifying the name of the queue. An application can use the termination queue for another purpose by passing a unique request parameter through the DosWriteQueue/DosReadQueue interface. Request parameter values 0 through 99 are reserved for OS/2. Request parameter values greater than 99 are available for application use.
If a parent session specifies the termq parameter on more than one DosStartSession call, the parameter is ignored on subsequent calls. Once a parent establishes a termination queue, the queue is posted when any child session terminates. The queue is posted regardless of who terminates the child session (for example, child, parent, or operator) and whether the termination is normal or abnormal. The termq data element structure has the following format: 
Size     Description 
WORD    Session ID of child 
WORD    Result code.
When a child session terminates, the result code returned in the termq data element is the result code of the program specified by pgmname assuming either:

The program is executed directly with no intermediate secondary command (CMD.EXE) process, or 2.

The program is executed indirectly through a secondary command (CMD.EXE) process and the /C parameter is specified.

If the program is executed indirectly through a secondary command (CMD.EXE) process and the /K parameter is specified, the result code of the processed command is returned.

When a child session running in the foreground terminates, the parent session becomes the foreground session. When a parent session terminates, any child sessions it created with DosStartSession, specifying related = 1, are terminated. When an independent session, created specifying related = 0, running in the foreground terminates, the Shell chooses the next foreground session.

Descendant Considerations

A session started through DosStartSession may in turn issue DosStartSession. These rules apply:

  • The SessID specified on DosSelectSession, DosSetSession, and DosStopSession may be only the SessID of an immediate child session, not a grandchild session, and so forth.
  • Suppose a bond is established between session A and its immediate child session B, and another bond is established between session B and its immediate child session C. When the operator selects session A, session C is brought to the foreground. See DosSetSession for a description of what establishing a bond means.
  • When a session terminates, all of its descendants (children, grandchildren, and so forth) are terminated.
ApplicationTypeConsideration
You may use DosExecPgm to start a process that is of the same type as the starting process. Process types include Presentation Manager, text-windowed, and full-screen. You may not use DosExecPgm to start a process that is of a different type than the starting process.
You must use DosStartSession to start a new process from a process that is of a different type. For example, use DosStartSession to start a Presentation Manager process from a non-Presentation Manager process.

Bindings

C

typedef struct _STARTDATA {   /* stdata */
 
  USHORT cb;                  /* length of data structure in bytes */
  USHORT Related;             /* 0=independent session, 1=child session */
  USHORT FgBg;             /* 0=start in foreground, 1=start in background */
  USHORT TraceOpt;            /* 0=no trace, 1=trace */
  PSZ    PgmTitle;            /* address of program title */
  PSZ    PgmName;             /* address of program name */
  PBYTE  PgmInputs;           /* input arguments */
  PBYTE  TermQ;               /* address of program queue name */
  PBYTE  Environment;         /* address of environment string */
  USHORT InheritOpt;          /* inherit option (shell of program) */
  USHORT SessionType;         /* session type (standard, windowed, ...) */
  PSZ    IconFile;            /* address of icon definition */
  ULONG  PgmHandle;           /* program handle */
  USHORT PgmControl;          /* initial state of windowed application */
  USHORT InitXPos;            /* x coordinate of initial session window */
  USHORT InitYPos;            /* y coordinate of initial session window */
  USHORT InitXSize;           /* initial size of x */
  USHORT InitYSize;           /* initial size of y */
 
} STARTDATA;

#define INCL_DOSSESMGR

USHORT  rc = DosStartSession(StartData, SessID, PID);

PSTARTDATA       StartData;     /* Start session data */
PUSHORT          SessID;        /* Session ID (returned) */
PUSHORT          PID;           /* Process ID (returned) */

USHORT           rc;            /* return code */

MASM

STARTDATA struc
 
  stdata_Length      dw  ? ;length of data structure in bytes
  stdata_Related     dw  ? ;0=independent session, 1=child session
  stdata_FgBg        dw  ? ;0=start in foreground, 1=start in background
  stdata_TraceOpt    dw  ? ;0=no trace, 1=trace
  stdata_PgmTitle    dd  ? ;address of program title
  stdata_PgmName     dd  ? ;address of program name
  stdata_PgmInputs   dd  ? ;input arguments
  stdata_TermQ       dd  ? ;address of program queue name
  stdata_Environment dd  ? ;address of environment string
  stdata_InheritOpt  dw  ? ;inherit option (shell of program)
  stdata_SessionType dw  ? ;session type (standard, windowed, ...)
  stdata_IconFile    dd  ? ;address of icon definition
  stdata_PgmHandle   dd  ? ;program handle
  stdata_PgmControl  dw  ? ;initial state of windowed application
  stdata_InitXPos    dw  ? ;x coordinate of initial session window
  stdata_InitYPos    dw  ? ;y coordinate of initial session window
  stdata_InitXSize   dw  ? ;initial size of x
  stdata_InitYSize   dw  ? ;initial size of y
 
STARTDATA ends

EXTRN  DosStartSession:FAR
INCL_DOSSESMGR      EQU 1

PUSH@  OTHER   StartData     ;Start session data
PUSH@  WORD    SessID        ;Session ID (returned)
PUSH@  WORD    PID           ;Process ID (returned)
CALL   DosStartSession

Returns WORD
Retrieved from "http://www.edm2.com/index.php?title=DosStartSession_(OS/2_1.x)&oldid=69974"