z/TPF

z/TPF

z/TPF

The z/TPF group is dedicated to sharing news, knowledge, and insights about the z/TPF product family. Consisting of IBMers and users, this community collaborates to advance the potential of high-volume, high-throughput transaction technology.

 View Only

JAM recycle service

By Jim Johnston posted Tue July 18, 2023 03:58 PM

  

The unique online program management for the z/TPF system is one of many successful architectural strategies that has established z/TPF as an industry leader for reliability, availability, and serviceability (RAS).  Historically, long-running applications (for example, InetD, debug server, and others) have used the E-type loader recycle interface to determine whether a relevant program has changed. The application could specify to the interface what programs to monitor in addition to the programs the interface monitors by default.  The interface would return to the application and identify whether a recycle was required based on at least one of the specified program versions changing since the last interface call.  As a result, an operator could update programs on a live system without having to know the dependencies of the long running applications and without having to know which applications to recycle.

With the introduction of the version control file system and common deployment, applications (such as long-running applications that use DFDL, REST, and Java) have experienced an increase in both file and program dependencies.  The increase in file use has driven the need to enhance existing recycle support to include file monitoring in addition to the existing program monitoring support. This enhancement aims to facilitate long-running processes that use DFDL, REST, or Java without requiring operator intervention.

Today recycle coordination for JAMs (z/TPF application managers for Java) is managed by the JAM monitor program that runs every second.  The monitor compares the JAM cluster activation number to the system activation number. If the two activation numbers are different, the JAM cluster is recycled.  With PJ47021 (JAM recycle service) applied, the JAM monitor was updated to use existing JAM REST infrastructure (based on CXF JAX-RS) to send a request to all JVMs in every active JAM cluster.  If a JAM cluster activation number is different from the system activation number, the enhanced tpf_etype_loader_recycle_interface function is called is called for each JVM in the JAM cluster.  If the recycle interface determines that no recycle is required for the JAM, each JVM activation number is updated to the current system activation number.  The following diagram depicts the high-level decision-making logic of when to recycle a JAM before and after JAM recycle services (PJ47021).

By default, the JAM recycle service is automatically enabled. To disable the service, the <AutoRecycle> element in the JAM descriptor must be set to NO.  Artifact types that can be monitored by the JAM recycle service include programs, files, or directories. 

To assist the developer in creating a list of programs and files that eventually get passed to the recycle interface, the JAM recycle service will automatically discover some of those artifacts based on existing information known by the JAM or JVMs.  This has the added benefit of reducing maintenance costs of having to update the recycle service based on changing configurations (think updating to a newer version of a dependency that is specified in the JAM’s classpath).   The JAM recycle service provides the following automatically discovered artifacts in addition to manually specified artifacts:

·        The Java artifacts that are defined in the java.class.path property of the JVM.

·        The JAM descriptor.

·        Files for a specific version of the Java Runtime Environment (JRE) that the JAM is running against. For example, the JRE might be Java 8 or Java 11.

·        IBM® designated JAM infrastructure programs and files that require the JAM to recycle.

There are 2 primary ways for manually specifying artifacts to monitor.  The first way is to specify artifacts in the JAM descriptor.  JAM recycle service provides 3 new JAM descriptor elements that the service parses and monitors for that JAM only.  The following example shows how to specify the monitor type that is used for each element. Each entry is delimited by a space. The directory specifications in the <AutoRecycleDirs> element are nonrecursive. The specifications for these elements are scoped to the same JAM that is configured by the descriptor.

<AutoRecyclePrograms> QZZ5 QZZ8 UENV </AutoRecyclePrograms>

<AutoRecycleFiles> /etc/passwd /etc/hosts </AutoRecycleFiles>

<AutoRecycleDirs> /certs /sys/tpf_pbfiles/apps/kafka/producers </AutoRecycleDirs>

The second method is intended for artifacts that need to be monitored for all JAMs.  The common artifacts can be monitored with the /sys/tpf_pbfiles/apps/tpfjax/jam.mon file. Similarly, you can specify programs, files, and directories to monitor in the jam.mon file.

The following example shows how to update the jam.mon file so that the previous example monitors the same artifacts across all JAMs in the same subsystem.

#JAM Recycle Monitor File

#If entry is a file or directory then it must be an absolute path

#Entries can be in any order and of mixed type

#Entries must be one per line

#Example Entries:

QZZ5

/sys/certs

/etc/passwd

UENV

/sys/tpf_pbfiles/apps/kafka/producers

QZZ8

/etc/hosts

In addition, the JAM recycle service provides two related user exits in the ujam.c segment. The ujam_recycle_preHook user exit is called before the JAM is recycled and the ujam_recycle_postHook user exit is called after the JAM is recycled.  A possible use case for the user exits is if you need to add code before and after a JAM is recycled in order to collect statistics or coordinate with other distributed systems.

For more information about APAR PJ47021, see the APEDIT.

1 comment
57 views

Permalink

https://community.ibm.com/community/user/blogs/jim-johnston1/2023/07/18/jam-recycle-service-blog-post

Comments

Glen Lillen
Sat February 28, 2026 01:17 PM

I actually have the same question because I’m trying to fully understand how the enhanced recycle support behaves in more complex z/TPF environments, especially with the additional file and directory monitoring layered on top of the traditional program monitoring. The automatic discovery of artifacts through the JVM classpath and JRE version makes sense conceptually, but I’m curious how predictable the recycle behavior is in practice when both manually specified and automatically discovered artifacts are involved. For example, if a file changes that’s indirectly referenced through a dependency update, is the detection always consistent across all JAMs, or are there edge cases where a recycle might not trigger as expected?

I’m also wondering about best practices when deciding between descriptor-based monitoring and the global jam.mon file. It seems powerful to monitor artifacts across all JAMs, but I imagine there could be performance or maintenance implications if the list grows too large. Additionally, I’d be interested to hear how others are using the ujam_recycle_preHook and postHook exits in real-world deployments particularly for coordination with external systems or logging. It makes me think of how a company like Atlanta eWaste Solutions structures its own service billing. Even though they specialize in electronics recycling, their invoices still need to be categorized properly in a client’s books often under waste management, sanitation services, or facility maintenance rather than something broad like miscellaneous expenses. If anyone has guidance or experience tuning this setup for reliability without causing unnecessary recycles, I’d really appreciate the insight because I’m trying to wrap my head around the same concerns.