Modify commands on z/OS

On the z/OS platform, we can modify Liberty using MVS operator commands supported by a Liberty server process or supported by the Angel process.

MODIFY commands supported by a Liberty server process

Clear the authentication cache

The following MODIFY command clears all users that are cached in the Liberty authentication cache:

MODIFY [jobname.]identifier,CACHE,CLEAR,AUTH

To use this MODIFY command, configure the Application Security feature, version 2.0 or later.

Display information about interrupted requests

We can display summary or detailed information about all interrupted requests, interrupted requests that are timed out, and interrupted requests that are older than a specified number of seconds. Or, we can display detailed information about a particular request.

To display information about interrupted requests, use the following command:

MODIFY [jobname.]identifier,display,interrupts,<parameters>

Valid parameters are:

details - Use to display information about interrupted requests. The following command displays detailed information about interrupted requests:
age=<value> - Use to display information about requests that are older than the value specified. The following command displays summary information about the requests that are older than 30 seconds:
The following command displays detailed information about the requests that are older than 20 seconds:
timedout - Use to display information about the requests that are currently considered to be hung. The following command displays summary information about the requests that are currently considered to be hung:
The following command displays detailed information about the requests that are currently considered to be hung.
request=<value> - Use to display detailed information about the specified request. The following command displays detailed information about request ABcdE1+fgH_JJ.

If we do not specify any parameters, summary information about all interrupted requests is displayed.

Display work counts

To display the counts of the request activity, run the following MODIFY command:

MODIFY [jobname.]identifier,DISPLAY,WORK

The following table describes each of the request activity counts that is displayed:

Request activity	Description
Total Requests	The total requests since the server started
Total Active Requests	The total requests currently in progress
Total Slow Requests	The total requests in progress that are slow
Total Hung Requests	The total requests in progress that are hung

The DELTA value shown next to the Total Requests value is the difference between this Total Request value and the Total Request value for the previous time the MODIFY command ran.

Important: To use this modify command, configure the requestTiming-*.* feature.

File update refresh

The following modify command processes pending file updates.

MODIFY [jobname.]identifier,REFRESH,<parameter>

We can specify the following parameters:

CONFIG: Specify this parameter to process pending configuration updates. The updateTrigger attribute on the config element that is in the server.xml file must also be set to mbean.
Configuration processing applies to the server.xml file, any files it includes, and any configuration files placed in the configDropins directory.
APPS: Specify this parameter to process pending application updates. The updateTrigger attribute on the applicationMonitor element that is in the server.xml file must also be set to mbean.

KEYSTORE: Specify this parameter to refresh the keystore configurations for the server. Specifying the keystore parameter reloads file-based keystores from disk, and reloads SAF-based key rings from SAF.
This parameter can reload SAF-based key rings from SAF only when the updateTrigger attribute in the keyStore element configuration is set to mbean, which is the default value. If the updateTrigger attribute is set to polled or disabled, the command returns an error. To refresh a specific keystore, add ,ID=configid to the command, where configid is the configuration ID of a keystore in the server.xml file.

For example, in the following sample configuration, a default keystore is configured in the server.xml

!-- inbound (HTTPS) keystore -->
    <keyStore id=defaultKeyStore password={xor}EjoyPTot
      location=${server.config.dir}/resources/security/key.jks />

To refresh the certificates in this keystore, specify the keystore parameter:

F servername,REFRESH,KEYSTORE,ID=defaultKeyStore

Note that the ID element is not case sensitive and quotation marks are not part of the MODIFY command syntax. The string should not be quoted in the MODIFY command.

For more information about dynamic updates, see Control dynamic updates. For more information about the configDropins directory, see Use the configuration dropins folder to specify server configuration. For more information about application deployment, see Deploy applications in Liberty.

Trace enablement

The following example shows the MODIFY command to enable tracing for the specified Liberty server:

MODIFY [jobname.]identifier,LOGGING='<trace_specification>'

Substitute the value trace_specification for a valid trace specification. For more information, see Liberty: Logging and Trace.

Transaction dumps

The following example shows the MODIFY command to request a transaction dump from the specified Liberty server:

MODIFY [jobname.]identifier,tdump

SVC dumps

To start an SVC dump, the server must be authorized with read access to the BBG.AUTHMOD.BBGZSAFM.ZOSDUMP resource profile in the SERVER class. The following example shows sample RACF commands for authorizing the server, where <userid> is the user ID assigned to the server:

RDEF SERVER BBG.AUTHMOD.BBGZSAFM.ZOSDUMP UACC(NONE)
PERMIT BBG.AUTHMOD.BBGZSAFM.ZOSDUMP CLASS(SERVER) ACCESS(READ) ID(username)
SETR RACLIST(SERVER) GENERIC(SERVER) REFR

The following example shows the MODIFY command to request an SVC dump from the specified Liberty server:

MODIFY [jobname.]identifier,svcdump

Java heap dumps

The following example shows the MODIFY command to request a Java virtual machine (JVM) heap dump from the specified Liberty server:

MODIFY [jobname.]identifier,HEAPDUMP

Java core dumps

The following example shows the MODIFY command to request a JVM core dump from the specified Liberty server:

MODIFY [jobname.]identifier,JAVACORE

Server dumps

The following example shows the MODIFY command to request a server diagnostic dump from the specified Liberty server:

MODIFY [jobname.]identifier,DUMP[,INCLUDE=<JAVA_DUMP_1>,<JAVA_DUMP_2>,...]

The INCLUDE parameter is optional. If the INCLUDE parameter is specified, any Java dumps that are listed on the INCLUDE parameter are requested and included in the server diagnostic dump package. The following Java dump types are valid:

THREAD for a Java core dump
HEAP for a Java heap dump

MODIFY commands supported by the Angel process

Code version

The following example shows the MODIFY command to display the version of Angel code that is loaded:

MODIFY [jobname.]identifier,VERSION

Enable or disable tracing

The following example shows the MODIFY command to enable or disable tracing for the Angel code:

MODIFY [jobname.]identifier,TRACE=[Y|N]

Select Y to enable tracing, or select N to disable tracing.

Display servers

The following example shows the MODIFY command to display a list of servers that are currently connected to the Angel code:

MODIFY [jobname.]identifier,DISPLAY,SERVERS

To also display the respective PIDs for each server, use the following MODIFY command:

MODIFY [jobname.]identifier,DISPLAY,SERVERS,PID