Microsoft KB Archive/65479

How to Call VioPopUp from a Protected Mode COBOL Program

PSS ID Number: Q65479 Article last modified on 11-19-1990

3.00 3.00a 4.00 OS/2

Summary: A protected mode COBOL program that is running in a background session can temporarily seize control of the screen and interact with the user, regardless of which session is currently in the foreground. This is accomplished by calling the OS/2 API function VioPopUp. Below is a sample program that demonstrates how to do this. This information applies to Microsoft COBOL Compiler versions 3.00 and 3.00a for MS OS/2 and to Microsoft COBOL Professional Development System (PDS) version 4.00 for MS OS/2.

More Information: VioPopUp takes the following two parameters:

If bit 0 of the first parameter is set, VioPopUp will wait until a pop-up is available. If bit 0 is cleared, then VioPopUp will return immediately with an error if a pop-up is not available. If bit 1 of the first parameter is set, the pop-up will be transparent. This means that if the display is already in a text mode, no mode change will occur and the screen contents and cursor position will not be disturbed. Session switching will also be disabled. If the display is not in a text mode, the pop-up will have no special affect on any other process. If bit 1 of the first parameter is cleared, the pop-up will be nontransparent. This means that the display will be put into an 80-by-25 text mode, the screen cleared, and the cursor placed into the upper-left corner. Session switching will also be disabled. During a pop-up, all other processes run normally, except that they can’t interact with the user or modify the physical display. Any attempt at these actions are blocked until the process in pop-up mode calls the API function VioEndPopUp. When this happens, the pop-up process reverts to the background, the process that was in the foreground when the pop-up occurred regains its status, and the physical display is restored. Microsoft COBOL versions 3.00, 3.00a, and 4.00 can call OS/2 API functions directly by prefixing the name of the function with a double underscore (__) and linking with the DOSCALLS.LIB library. Note that a WORD in COBOL has a picture clause of 9(4) COMP-5. Also, data items preceded by PTR must be passed using the BY REFERENCE clause in the CALL statement; otherwise, BY VALUE is used. Furthermore, the parameters must be passed to the API function in the reverse order because the API functions use a calling convention that is the reverse of COBOL’s. For more information on calling OS/2 API functions from COBOL 3.00 and 3.00a, see part 9 of the “Release Notes” section of “Microsoft COBOL Compiler 3.0: Operating Guide.” For more information on VioPopUp and VioEndPopUp, see Pages 113-115 of “Advanced OS/2 Programming” by Ray Duncan (Microsoft Press, 1989). The following sample program generates a pop-up, displays a message while in the pop-up, and then ends the pop-up. Before doing so, it lets the user choose the type of pop-up (transparent or nontransparent) and then emits five delayed beeps to allow the user to switch sessions. To compile and link the program in COBOL 3.00/3.00a, enter the following at the OS/2 command prompt: pcobol cobpopup; link /nop cobpopup adis adisinit adiskey,,,pcobol doscalls; The compile lines for COBOL PDS 4.00 are as follows: cobol cobpopup; link cobpopup adis adisinit adiskey,,,coblib os2;

COBPOPUP.CBL
$SET ANS85 IDENTIFICATION DIVISION. PROGRAM-ID. CobPopUp. DATA DIVISION. WORKING-STORAGE SECTION. *  Options for pop-up (wait/no wait, transparent or not). 01 Flags    PIC 9(4) COMP-5. *  Refers to the default screen group. 01 Handle   PIC 9(4) COMP-5 VALUE 0. *  Delay in milliseconds passed to DosSleep. 01 Delay    PIC 9(8) COMP-5 VALUE 1000. *  Used to poll the keyboard. 01 KeyCode  PIC X.   PROCEDURE DIVISION. *  Loop until the user chooses a valid option. PERFORM UNTIL (Flags = 1) OR (Flags = 3) *     Prompt the user for an option. DISPLAY &quot;Transparent (1) or Nontransparent (2) pop-up?&quot; ACCEPT KeyCode *     Setting bit 0 tells OS/2 to wait until a pop-up is  *      available. Bit 1 must be set for transparent mode. EVALUATE KeyCode WHEN &quot;1&quot; MOVE 3 TO Flags WHEN &quot;2&quot; MOVE 1 TO Flags WHEN OTHER DISPLAY &quot;Invalid option!&quot; CALL X&quot;E5&quot; END-EVALUATE END-PERFORM. *  Delay so user has time to switch sessions. PERFORM 5 TIMES CALL X&quot;E5&quot; CALL &quot;__DosSleep&quot; USING BY VALUE Delay END-PERFORM. *  Start the popup. CALL &quot;__VioPopUp&quot; USING BY VALUE    Handle, BY REFERENCE Flags. *  Display a message and wait for a key to be pressed. DISPLAY &quot;Surprise!&quot;  AT 1236 WITH FOREGROUND-COLOR 13 BACKGROUND-COLOR 1. DISPLAY &quot;Hit any key&quot; AT 2535 WITH FOREGROUND-COLOR 13 BACKGROUND-COLOR 1. CALL X&quot;83&quot; USING KeyCode. *  End the pop-up and terminate the program. CALL &quot;__VioEndPopUp&quot; USING BY VALUE Handle. STOP RUN. Copyright Microsoft Corporation 1990.