The coordination exit

GDDM V3R2 Base Application Programming Reference

The coordination exit

GDDM V3R2 Base Application Programming Reference
SC33-0868-02

A coordination exit can be defined by specifying the coordination exit address in the array parameter of the WSCRT call; for a description of this, see "The GDDM calls" in topic 3.0.

Function: By providing a coordination exit when creating an operator window, a task manager allows the use of that window by independent applications running their own instances of GDDM.

Figure 25. The coordination exit routine

Whether a GDDM instance is being used by a task manager, or by a single application, the basics of a windowing program are the same:

The first DSOPEN in a GDDM program opens the real display device with the (WINDOW,YES) processing option. This automatically creates a default operator window, and associates the real display device with it.
The program then divides the screen of the real display device into one or more operator windows.
Subsequent DSOPEN calls open one or more virtual display devices and associate each with an operator window. (Under a task manager, the subsequent DSOPENs would be in each application.)
Each application (under a task manager) or each function (under a single application) then communicates with the terminal user through an operator window conceptually situated in front of a virtual screen, and can behave as if it had complete control of a real screen.

A virtual device can itself be opened with the (WINDOW,YES) processing option. Operator windows created for this virtual device are further subdivisions of the real screen. So, although you can conceptually define hierarchies of operator windows, they do not appear inside each other. Rather, they are displayed as peers, according to their priorities.

When you first create a number of overlapping operator windows in an application, the viewing order depends on the order that you create the operator windows in. The operator window that you create first is at the bottom of the viewing order, and the operator window that you create last is at the top. On the display screen, each operator window appears in front of the operator windows that are below it in the viewing order. The topmost window is the active operator window.

In a single application not running under a task manager, the current operator window is always the candidate operator window; which is the operator window with which the next virtual device to be opened will be associated.

When you have several applications running concurrently under a task manager, only one of those applications is actually executing, while the others are waiting because they have unsatisfied reads outstanding. Each of the applications can have a current operator window. But no matter how many devices or applications there may be, only that operator window made current by the most recently executed WSCRT, WSSEL, or WSIO call is the candidate operator window; which is the operator window with which the next virtual device to be opened will be associated.

The way that GDDM makes it possible for several application programs to share the screen is by allowing the task manager to intervene in the execution of the program's input/output calls. When each operator window is created, the task manager specifies (in the first array element of the last parameter of the WSCRT call) the address of a coordination exit routine. This runs in the application program subtask, and is invoked by GDDM whenever the application calls a function that requires input/output for the terminal - an ASREAD call, typically. The numbers in the figure represent the following events:

An input/output call is issued by the application, causing GDDM to invoke the coordination exit routine.
The exit routine, when invoked, must post the task-manager task and wait. The task manager must then call WSIO, the coordinated output/input call. The WSIO call updates all the windows on the screen. WSIO also returns the identifier of the topmost window on the screen. The task manager uses this to find out which subtask to post. It then posts that subtask and waits.
When the task manager posts the subtask, control passes back to the coordination exit routine, which in turn returns control to GDDM.
Control then returns to the ASREAD (or other application input/output call). GDDM completes the processing of this call, and passes control back to the application program. Any input data entered by the terminal user is then available to the application.

The purpose of the coordination exit routine is to switch control from the subtask to the main task, or the other way round. There is a direction parameter to tell it which way to switch.

How to specify a coordination exit: A coordination exit is specified as part of the WSCRT call. For more information, see the description of the WSCRT call in the "The GDDM calls" in topic 3.0.

Parameters: The parameters for coordination exits are as follows:


     R13 -> A 72-byte save area
     R14 -> The return address
     R15 -> The entry point of the exit
     R1  -> The parameter address list, in standard
            variable parm-list format:
                  ADDR1 -> AAB     (Char(8))
                  ADDR2 -> UXBLOCK ((3) Fixed(31))
                  ADDR3 -> DIRECTN (Fixed(31))

Parameters AAB and UXBLOCK are described under "GDDM user-exit conventions" in topic 22.3.2. Additional parameters are as follows:

DIRECTN

The direction in which the exit is to pass control. Possible values are:

0

Pass control from the sub-task to the main task

1

Pass control from the main task to the sub-task.

The exit may not change this parameter.

Feedback values: On return, the exit must set R15 as follows:

0: Successful completion
8: Sub-task terminated abnormally.

Notices | Terms of use | Support | Contact z/OS