(The official version of this article was made available in January, 2004.)

Invocation and return of 1st-level adjunct program from a live 2nd-level system.

Timothy D. Greer

Disclosed is a method to invoke, from a live 2nd-level system, a program in the 1st-level adjunct. Using this method, the 2nd-level system continues to run unimpeded, except for the time while the adjunct is actually running. The adjunct program can be invoked from a program running in a virtual machine of the 2nd-level system, and return codes and other output can be returned from the adjunct program to the program on the 2nd-level system virtual machine.

The VM operating system presents each user with its own virtual machine. A virtual machine can have an adjunct machine, which in many respects behaves as a separate virtual machine. The first virtual machine is known as the primary. The primary and the adjunct share certain resources, and in particular they share time: exactly one of the two is running at a given time. A user selects whether the adjunct or the primary is to run using the CP (Control Program) commands ADJUNCT START (to initialize the adjunct), ADJUNCT STOP (to return to the primary), ADJUNCT BEGIN (to switch from primary to adjunct) and ADJUNCT END (to terminate the adjunct). When the adjunct is running, the primary is frozen, and vice versa.

VM also facilitates use of guest operating systems. A VM user can run an operating system in the primary (or the adjunct, or both). That operating system is known as a 2nd-level system to distinguish it and its users from the lower level operating system, the 1st-level system on which the original user is running. An important use of the adjunct is with this environment, where the adjunct is able to retain the characteristics of a 1st-level user while the 2nd-level system exists in the primary. A person can run programs and execute 1st-level commands in the adjunct without having to take down the 2nd-level system. In particular, the adjunct may be used to examine the 2nd-level system while it is frozen (display memory data, for example).

A problem with this arrangement is that the movement between the primary and the adjunct is manual. The usual practice is to use a programmed key (PA1) to cause the primary to drop into 1st-level CP READ, then issue ADJUNCT BEGIN to get to the adjunct. Since ADJUNCT BEGIN is a CP command, there is no facility for invoking a program on the adjunct as part of that command. Rather, one must invoke the desired program or other action with a subsequent command.

The PA1 step to drop into 1st-level CP READ can be circumvented by using diagnose x'08' on VM. This can be arranged on 2nd-level VM operating systems by adding a CP exit to invoke the diagnose x'08'. See author Tim Greer's http://www.vm.ibm.com/download/packages/descript.cgi?CP1STLVL for example. The diagnose x'08' can be invoked from other 2nd-level operating systems in a similar manner. Thus one can invoke the ADJUNCT BEGIN command directly from a guest of the 2nd-level system. However, this simply freezes the primary and unfreezes the adjunct. Additional steps are required if the guest of the 2nd-level system is to direct the adjunct to do something.

To actually invoke a program on the adjunct from the 2nd-level guest, two additional steps are used. First, at some earlier time, a program is started on the adjunct. This program simply loops, checking a data file for new instructions. This data file may be only read-accessible to the adjunct, but is write-accessed by the primary. Before invoking ADJUNCT BEGIN via diagnose x'08', the guest of the 2nd-level system needs to write information such as the program name and input parameters to the data file. A time stamp is also written so that the looping program in the adjunct knows that the data is new. When the looping program sees new data, it performs the task indicated (typically, invoking another program), writes any output to a second data file, and then invokes the ADJUNCT STOP command. The primary is able to see the output recorded in the second data file. This second data file may be read-only for the primary. A simple implementation would have the looping program be an intermediary, calling a REXX exec when new data appears in the data file. The intermediary may gather returning exec error results, or simply allow the exec to handle all output details.

By passing both inputs and outputs via files, using the diagnose x'08' for the ADJUNCT BEGIN command, and keeping the looping program in the adjunct, guests of the 2nd-level system may cause the adjunct to take almost any action desired. When the ADJUNCT STOP is issued, the primary again becomes unfrozen, so the perception on the 2nd-level system is that a subroutine was called and returned. The adjunct is again frozen, so it is not wasting CPU cycles, but the next time ADJUNCT BEGIN is invoked, it will still be looping, so it will be ready to check again for new work.

An alternate implementation is to use reserved locations in the memory of the adjunct and/or primary to pass requests and results, rather than using files.

Return to the author's home page.