Microsoft KB Archive/37479

COBOL 3.0 Example Calling DosStartSession API in MS OS/2

PSS ID Number: Q37479 Article last modified on 04-20-1993

3.00 OS/2

The information in this article applies to:

- Microsoft COBOL for OS/2, version 3.0

Summary: The example below demonstrates how to make the DosStartSession API call from a COBOL program running in MS OS/2 protected mode. Some of the requirements are that you compile with the PCOBOL compiler and LINK with the /NOP option as illustrated below. The COBOL.DIR file should contain the LITLINK directive so the compiler can generate a machine-code call to the DOSCALLS.LIB module. The COBOL.DIR file should contain only the LITLINK directive.

More Information: In the example below, the program BEEPC.EXE is started as a new screen group. BEEPC.EXE is located in the directory C:. The entire path and program name must be specified in the program name parameter of the DosStartSession API call. The compile line is as follows: PCOBOL DOSSTART.COB; The link line is as follows: LINK DOSSTART/NOP/NOD,,,PCOBOL+DOSCALLS; Note: the DOSCALLS.LIB should be in a directory pointed to by the LibPath environment variable in CONFIG.SYS or CONFIG.OS2. For more information on this subject, please see the “Microsoft Operating System/2 Programmer’s Toolkit Programmer’s Reference” manual. The following is a code example:

  $SET ANS85 OSVS
  * ANS85 is needed to enable the 'end-if' (scope delimiter)
  * syntax and OSVS is needed for 'return-code'
   Identification division.
   Program-Id.  DOSSTART.
   Data division.
   Working-storage section.
   01 dos-start-params.
  * Use COMP-5 to ensure suitable byte order for i86 CPU
  * Start-data is passed to the API call
    03 start-data.
        05 start-data-Length           pic x(2) comp-5 value 24.
        05 start-data-Related          pic x(2) comp-5.
        05 start-data-FgBg             pic x(2) comp-5.
        05 start-data-TraceOpt         pic x(2) comp-5.
        05 start-data-PgmTitle         pic x(4) comp-5.
        05 start-data-PgmName          pointer.
        05 start-data-PgmInputs        pointer.
        05 start-data-TermQ            pic x(4) comp-5 value 0.
  * SessID and PID may be returned by the API call, but are
  * not used in this example.
   03 sessID            pic x(4) comp-5.
   03 PID               pic x(4) comp-5.
  * The program name must be in ASCIIZ format, and *MUST* be
  * fully qualified - that is, it must include the drive & path
   01 program-name.
     03 filler         pic x(16)     value "C:\OS2\BEEPC.EXE".
     03 filler         pic x         value x"00".
  * A command-line could be passed to the session here
   01 argument         pic x(64) value spaces.
   01 temp             pic x.
   procedure division.
   initialization-para.
  * Start process as a child (could be independent)
    move 1 to start-data-related
  * Run in foreground (not background)
    move 0 to start-data-FgBg
  * No need for tracing
    move 0 to start-data-TraceOpt
  * Title can be null, to use name as title
    move 0 to start-data-PgmTitle
  * Point to the pgm name from start-data
    set start-data-PgmName to address of program-name
  * Point to the arguments, blank in this example
    set start-data-PgmInputs to address of argument
  * No queues are used in this example
    move 0 to start-data-TermQ.
   start-the-session.
    display "calling DosStartSession now"
  * The OS/2 API parameters are in Pascal order
  * (reverse COBOL order):
    call "DosStartSession"
    using by reference PID
       by reference SessID
       by reference start-data
    if return-code = 0
       display "session executed ok"
    else
        display
        "startsession failed : return code = " return-code
    end-if.
   wait-here.
    display "press enter to return to OS/2" with no advancing
    accept temp
    stop run.