Multisystem Enclaves

Some work managers split large transactions across multiple systems in a parallel sysplex, improving the transaction's overall response time. These work managers can use multisystem enclaves to provide consistent management and reporting for these types of transactions.

Among the benefits of using multisystem enclaves:

• All parts of a split transaction are managed using the same service class. If the service class has multiple periods, the CPU usage of the entire transaction is used to switch periods.
• The enclave owner's SMF 30 record includes CPU time accumulated by all of the multisystem enclaves it owns, for all systems on which they executed. Remote system service is reported by individual system within the SMF 30 record.

A multisystem enclave begins as either an independent or dependent enclave on a single system. This enclave is called the “original” enclave. Note that WLM does not allow you to export work-dependent enclaves. If the work manager decides to involve other systems in the processing of the work unit, it issues IWMEXPT to “export” the enclave to other systems in the parallel sysplex. The export token it receives back from IWMEXPT is a sysplex-wide unique name that it must now pass along with the work request to other systems.

Each work manager in the supporting address spaces on other systems can now issue IWMIMPT to “import” the enclave onto its system. It passes the export token and receives a special enclave token that is valid for its system only. This new, supporting enclave is called a “foreign” enclave. The original enclave and the foreign enclaves are all referred to as one unit called a multisystem enclave.

When work has completed in a foreign enclave, the supporting work manager issues IWMUIMPT to “unimport” the enclave, and then signals its completion to the original work manager. When all of the supporting work managers have unimported their enclave, the original work manager issues IWMUEXPT to “unexport” the original enclave. When all work is finished, the original work manager that created the original enclave deletes it.

If your subsystem uses an enclave that it did not create for its processing, then you should use the registration services (IWMEREG, IWMEDREG) to protect the enclave against deletion by its owner while your subsystem is using it. The IWMUIMPT service delays the physical deletion of an enclave as long as the enclave is registered by any subsystem

Each work manager must first connect to WLM using the IWM4CON service, specifying EXPTIMPT=YES to enable exporting and importing. IWMEXPT, IWMIMPT, IWMUIMPT, and IWMUEXPT must all be invoked from the address space that connected.

WLM will automatically undo a work manager's export and import requests when:

• The work manager disconnects from WLM
• The work manager's connecting task or address space ends
• The work manager's system fails

If an export is undone, whether by the original work manager's request or due to WLM's recovery action, before all of the supporting work managers have completed their work in the foreign enclaves, the outstanding imports are handled as follows:

• An outstanding import on the same system as the original enclave is automatically undone. (When a work manager on the same system as the original work manager attempts to import the original enclave, it receives the original enclave token. It's not really “exported” at all.) The only effect will be a warning return code when the work manager attempts to unimport the enclave.
• An outstanding import on a foreign system will remain in effect. WLM provides no notification to the supporting work manager that the export has ended. The supporting work manager must learn of the failure through its own mechanisms and then terminate the work on its own.
• New import requests are rejected. The supporting work manager should terminate any work being done on behalf of the original work manager.

As a transaction flows from one work manager to another, it is possible that more than one work manager will split its processing across multiple systems. In this way, an original enclave can be exported multiple times, both by the original work manager and by other work managers. Each export request is tracked separately, and requires a corresponding unexport request. Multiple concurrent exports all share the same export token.

If a work manager on the original system attempts to import the original enclave, it will receive the enclave token of the original enclave. The work manager can schedule SRBs into or join tasks to the original enclave just as it would any other enclave on the same system.

Just as an enclave can be exported multiple times, it can also be imported multiple times by one or more supporting work managers. Each import request is tracked separately, and requires a corresponding unimport request. Multiple concurrent imports on a single system all share a single foreign enclave.

A foreign enclave cannot be exported — in other words, once an enclave has been imported onto a foreign system, it cannot be exported again from that system. If a work manager invokes IWMEXPT for a foreign enclave, it will receive a warning code along with the existing export token for that enclave.

For an example showing how to use multisystem enclaves, see Using a Multisystem Enclave.