Using the ARM Services for Instrumenting Applications and for Managing ARM Transactions on z/OS

The services arm_start_transaction and arm_stop_transaction indicate the beginning and the end of an ARM transaction. Starting with z/OS® V1R10 the ARM services support using enclaves. Thus, ARM transactions can now be managed individually on z/OS.

To allow for transaction management, you must code the arm_bind_thread() and arm_unbind_thread() services in their applications to indicate that the current thread (TCB) is now performing on behalf of a specified transaction. Only when you use the arm_bind_thread() and arm_unbind_thread() services, WLM is able to track the thread. WLM can then assign the necessary resources to that unit of work to help the transaction to reach its goals.

Note:

The z/OS implementation of arm_bind_thread() and arm_unbind_thread() conform to the original EWLM R1 semantic specifications, for example, threads are implicitly unbound by arm_stop_transaction() or arm_discard_transaction().

A sample C-program IWMSARM4 that demonstrates the usage of the services and the new sub-buffers is available in SYS1.SAMPLIB(IWMSARM4). A sample JCL to compile, bind and run this application is provided in SYS1.SAMPLIB(IWMCARM4).

Figure 12. Typical synchronous application flow between applications (same z/OS system)

To understand the management of ARM transactions on z/OS it is important to understand that a distributed transaction on a single z/OS system is managed as a whole - even if it spans several address spaces (see Figure 12).

When WLM running on a z/OS system first detects of an ARM-instrumented transaction (when the first application A1 performs an arm_start_transaction in the example above) a management control block (enclave) is created. Later on, when application A2 performs its arm_start_transaction call, the same control block (enclave) is used to track the transaction. Of course it is necessary to pass the current_correlator c1 from the arm_start_transaction call in A1 to application A2 and use that correlator as the parent_correlator in the arm_start_transaction call in A2 (and equally so for additional applications A3, A4 etc.) The correlator is used by WLM to find out that A1 and A2 are working on behalf of the same transaction.

Each application in a transaction call sequence needs to indicate that it wants its transactions to be managed towards transaction goals (see next chapter). For example, if A1 has indicated transaction management, but A2 has not, and just because A1 passes a correlator to A2, A2 will not be managed towards transaction goals.

In an A1->A2->A3 scenario where every application correlates properly, but only A1 and A3 have indicated transaction management, A1 and A3 are managed together, but A2 is not.

z/OS ARM Sub-buffers to Support WLM management

Two z/OS-specific ARM sub-buffers support ARM-instrumented application on z/OS. The first one is for arm_register_application(), the second is for arm_start_transaction().

The sub-buffers are defined in header file <armewlm.h> and are located in data set SYS1.SIEAHDRV.H(ARM4EWLM). The sub-buffers have the following names:

These sub-buffers provide WLM with the information that it needs to connect to WLM for management purposes and to specify WLM classification attributes.

New Sub-buffer arm_subbuffer_zos_connect

Use sub-buffer arm_subbuffer_zos_connect to specify the attributes for the connection of the ARM-instrumented address space (application) to WLM. It can be provided as a sub-buffer with the format_id= ARM_SUBBUFFER_ZOS_CONNECT (-30400) on an arm_register_application service call. WLM needs this sub-buffer to manage individual transactions.

Figure 12 shows the layout of the sub-buffer and the parameters which can be passed to the arm_register_application service where:

Specify all character parameters in the character set that the application uses (arm_charset_t). There is no restriction for an application using EBCDIC (IBM-1047) or US-ASCII encoding. For UTF8 and UTF16, the strings are restricted to characters from the US-ASCII (codepoints 0..127) subset.

Figure 13. Sub-Buffer arm_subbuffer_zos_connect_t)

The subsys parameter also determines the subsystem type parameter that can be specified in the WLM Administrative Application, for example, the sample application in SYS1.SAMPLIB(IWMSARM4) refers to an subsystem type of “STOK" that could be defined in the WLM classification rules as follows:

New Sub-buffer arm_subbuffer_zos_classify

ARM service arm_start_transaction can associate a starting transaction to a WLM enclave. The new enclave has to be classified to a WLM service class. This is accomplished by passing the WLM classification attributes in a new (optional) z/OS sub-buffer arm_subbuffer_zos_classify with format_id=ARM_SUBBUFFER_ZOS_CLASSIFY (-30401). The values of the classification attributes can then be used in classification rules of the WLM Administrative Application to associate a specific service class with a transaction. If the sub-buffer is not present but arm_subbuffer_zos_connect has been specified on the arm_register_application call, the transaction will be assigned the default service class for the subsystem.

Figure 14 shows the layout of this sub-buffer and the parameters which can be passed to the arm_start_transaction service. The parameters are the same as those specified on the WLM IWM4CLSY service. Specify all character parameters in the character set that the application uses (arm_charset_t). There is no restriction for an application using EBCDIC (IBM-1047) or US-ASCII encoding. For UTF8 and UTF16 the strings are restricted to characters from US-ASCII (codepoints 0..127) subset.

Figure 14. Sub-Buffer arm_subbuffer_zos_classify