Modify commands on z/OS

On the z/OS® platform, you can modify Liberty by using MVS™ operator commands that are supported by a Liberty server process or that are supported by the Angel process.

MODIFY commands that are 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, you must configure the Application Security feature, version 2.0 or later.

Display information about interrupted requests

You 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, you 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:
    f BBOS001,display,interrupts,details
  • 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:
    f BBOS001,display,interrupts,age=30
    The following command displays detailed information about the requests that are older than 20 seconds:
    f BBOS001,display,interrupts,age=20,details
  • 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:
    f BBOS001,display,interrupts,timedout
    The following command displays detailed information about the requests that are currently considered to be hung.
    f BBOS001,display,interrupts,timedout,details
  • request=<value> - Use to display detailed information about the specified request.

    The following command displays detailed information about request ABcdE1+fgH_JJ.
     f BBOS001,display,interrupts,request='ABcdE1+fgH_JJ'

If you 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, you must configure the requestTiming-*.* feature.
File update refresh
The following modify command processes pending file updates.
MODIFY [jobname.]identifier,REFRESH,<parameter>
You 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: 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 Controlling dynamic updates. For more information about the configDropins directory, see Using the configuration dropins folder to specify server configuration. For more information about application deployment, see Deploying 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 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 dump package. The following Java dump types are valid:
  • THREAD for a Java core dump
  • HEAP for a Java heap dump

MODIFY commands that are 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