This topic applies only on the z/OS operating system.

Modify command

You can issue the modify command from the MVS™ console to dynamically modify product operations.

You can use the modify command to display the status of various server components and activities, including the following components:
  • Active controllers
  • Trace settings
  • Servants
  • Sessions
  • Java™ virtual machine (JVM) heap
  • Java trace

Use the following format when entering the modify command.

f <server>, parameters

server is the short name for the server to which the modify command is directed. This argument is required.

Parameters

The following parameters are valid for the modify command:

CANCEL
Used to cancel the specified server.

You can specify the following options for the CANCEL parameter:

ARMRESTART
Specifies whether you are using the application response management (ARM) agent and want ARM to restart the server after it terminates. If you do not specify the ARMRESTART option on the CANCEL parameter, ARM does not restart the server.
HELP
Specifies that you want to see the help information that describes the CANCEL syntax.
Avoid trouble: You cannot use the CANCEL parameter to cancel a cluster from the MVS console. You must individually cancel each of the servers that make up the cluster.gotcha
HEAPDUMP
Used to generate a JVM heapdump for the controller, and for all of the servants that are associated with that controller.
JAVACORE
Used to generate a JVM core dump for the controller, and for all of the servants that are associated with that controller.
JAVATDUMP
Used to generate a JVM-initiated TDUMP for all of the servant address spaces. You can also use the JAVA_DUMP_TDUMP_PATTERN native environment variable to specify the TDUMP dataset name.
STACKTRACE
Used to log the Java stack traceback for all Java threads in the server to the error log.
SMF,REQUEST,ON
Used to turn on the creation of SMF 120-9 records.
SMF,REQUEST,OFF
Used to turn off the creation of SMF 120-9 records.
SMF,REQUEST,CPU,ON
Used to turn on the collection of data for the CPU Usage Breakdown Section of the SMF 120-9 record whenever that record is created.
SMF,REQUEST,CPU,OFF
Used to turn off the collection of data for the CPU Usage Breakdown Section of the SMF 120-9 record. When this parameter is specified, records that are created have zeroes for this section in the location triplets at the top of the record.
SMF,REQUEST,SECURITY,ON
Used to turn on the collection of data for the Security Data Section of the SMF 120-9 record whenever that record is created
SMF,REQUEST,SECURITY,OFF
Used to turn off the collection of data for the Security Data Section of the SMF 120-9 record. When this parameter is specified, records that are created have zeroes for this section in the location triplets at the top of the record.
SMF,REQUEST,TIMESTAMPS,ON
Used to turn on the collection of data for the Formatted Timestamps Section of the SMF 120-9 record whenever that record is created
SMF,REQUEST,TIMESTAMPS,OFF
Used to turn off the collection of data for the Formatted Timestamps Section of the SMF 120-9 record. When this parameter is specified, records that are created have zeroes for this section in the location triplets at the top of the record.
TIMEOUT_DELAY=n
Used to dynamically alter the timeout delay option variable, control_region_timeout_delay, to n seconds. This modify command is used, in conjunction with the TIMEOUTDUMPACTION modify command, to set a timeout delay that enables the specified dump action, such as JAVACORE, to complete when a timeout occurs. The dump actions specified on the TIMEOUTDUMPACTION modify command require a timeout delay that enables the servant to complete the dump action before the servant terminates.

After the specified dump is processed, you can reissue this command to change the value of the control_region_timeout_delay variable back to its previous setting without recycling the server.

TIMEOUTDUMPACTION=n
Used to indicate which of the following actions is performed whenever a timeout occurs for work that has been dispatched to a servant when the control_region_timeout_delay property is set to a non-zero value:
  • If NONE, or none is specified, no dump is taken.
  • If JAVACORE or javacore is specified, a Java core dump is taken.
  • If SVCDUMP or svcdump is specified, an SVC dump is taken.
  • If JAVATDUMP or javatdump is specified, a JVM-initiated TDUMP is taken.
    Note: The control_region_timeout_delay property must be configured to a length of time that is long enough for the servant to collect the JAVATDUMP before the controller terminates the servant. The TIMEOUT_DELAY modify command can be used to dynamically change the value of the control_region_timeout_delay property.
TIMEOUTDUMPACTIONSESSION=n
Used to indicate which of the following actions is performed whenever a timeout occurs for an HTTP, HTTPS, SIP, or SIPS request that has been dispatched to a servant, and the corresponding recovery property is set to SESSION:
  • If NONE, or none is specified, no dump is taken.
  • If JAVACORE or javacore is specified, a Java core dump is taken.
  • If SVCDUMP or svcdump is specified, an SVC dump is taken.
  • If JAVATDUMP or javatdump is specified, a JVM-initiated TDUMP is taken
Following is a list of the corresponding recovery properties:
  • protocol_http_timeout_output_recovery
  • protocol_https_timeout_output_recovery
  • protocol_sip_timeout_output_recovery
  • protocol_sips_timeout_output_recovery
TRACEALL=n
Used to establish a general trace level for the server.
The following values are valid trace levels. Typically, you should specify a value of 1.
  • 0: no tracing is performed
  • 1: tracing is performed when an exception occurs
  • 2: basic tracing is performed
  • 3: detailed tracing for all components is performed.
Avoid trouble: Be careful when using a level of 3 because this level of tracing might yield more data than is practical for you to review.gotcha
TRACEBASIC=n
Used to specify the product components for which you want to turn on a basic level of tracing.
This command has the ability to override a different tracing level established by TRACEALL for those components.
Avoid trouble: Do not change this variable unless directed to do so by IBM® Support. gotcha

The following table shows the values you can specify for this parameter. You can specify one or more of these values for either TRACEBASIC or TRACEDETAIL:

Value Product component
0 RAS
1 Common Utilities
3 COMM
4 ORB
6 OTS
7 Shasta
9 z/OS® Wrappers
A Daemon
E Security
F Externalization
J (Should only be used under the direction of IBM Support) JRas
L Java EE
TRACEDETAIL=n
Used to specify the product components for which you want to turn on a detailed level of tracing.
This command activates the most detailed tracing for the specified product components and overrides different settings inTRACEALL. The selected components are identified by their component IDs, which are the same IDs as the ones listed for the TRACEBASIC parameter. Subcomponents, specified by numbers, receive detailed traces. Other parts of the product receive tracing as specified on the TRACEALL parameter.
Avoid trouble: Do not change this variable unless directed to do so by IBM Support.gotcha
TRACESPECIFIC=xxyyyzzz
Used to specify tracing overrides for specific product trace points.
Trace points are specified by 8-digit, hexadecimal numbers. To specify more than one trace point, use parentheses and separate the numbers with commas. You can also specify an environment variable name by enclosing the name in single quotation marks. The value of the environment variable is processed as if you had specified that value on the TRACESPECIFIC parameter.
Avoid trouble: Do not use TRACESPECIFIC unless directed by IBM Support.gotcha
TRACE_EXCLUDE_SPECIFIC=xxyyyzzz
Used to specify product trace points to exclude.
Trace points to exclude are specified by 8-digit, hexadecimal numbers. To specify more than one trace point, use parentheses and separate the numbers with commas. You can also specify an environment variable name by enclosing the name in single quotation marks. The value of the environment variable is processed as if you had specified that value on the TRACE_EXCLUDE_SPECIFIC parameter. You can use the TRACE_EXCLUDE_SPECIFIC parameter as a mask to turn off traces that are currently turned on. For example, use the TRACESPECIFIC parameter to turn on tracing for a whole part of the product, and then use the TRACE_EXCLUDE_SPECIFIC parameter to turn off one trace within that part of the product.
Avoid trouble: Do not use TRACE_EXCLUDE_SPECIFIC parameter unless you are directed to do so by IBM Support.gotcha
TRACEINIT
Used to reset to the initial trace settings.
TRACENONE
Used to turn off all trace settings.
TRACETOSYSPRINT={YES|NO}
Used to select whether to send the trace to SYSPRINT.

Specifying YES sends the trace to SYSPRINT, and specifying NO stops the sending of the trace to SYSPRINT.

TRACETOTRCFILE={YES|NO}
Used to specify whether or not to direct the trace to the TRCFILE DD card.

Specifying YES sends the trace to the TRCFILE DD card, and specifying NO stops the sending of the trace to the TRCFILE DD card.

TRACEJAVA
Modify the Java trace string.

The Java trace specification is used to control Java tracing and conforms to the Java trace specification rules. *=all=enabled means to enable all types of tracing for all registered trace components.

HELP
Used to display a list of all the keywords that you can use with the modify command.

You can also use the HELP parameter after the CANCEL, and DISPLAY parameters to display lists of all the keywords you can use with either of these parameters.

PAUSELISTENERS
Used to prevent work from being accepted into the server. Use this parameter to shut down the communication listeners and purge any pending work in the work registry.
WLM_MIN_MAX=min,max
Used to dynamically modify the minimum and maximum number of servants settings (wlm_minimumSRCount and wlm_maximumSRCount). WLM will dynamically adjust the current number of active servants to fit within the new constraints. Note that the new settings will not necessarily take effect immediately; WLM will work toward the new minimum and maximum targets as quickly as possible, considering factors such as resource availability and workload.
Avoid trouble: The WLM_MIN_MAX command is ignored for a server that is configured with a single server dynamic application environment, that is the wlm_dynapplenv_single_server property is set to 1.gotcha
RESUMELISTENERS
Used to restart the communication listeners after issuing a modify command that includes the PAUSELISTENERS parameter. This parameter allows new work to be accepted into the server.
DISPLAY
Used to display the name of the server, the system name where the server is running, and the current code level.

You can specify the following options for this parameter:

  • SERVERS displays the name of the server at which the command is directed, the system name, and the code level for each active server in the sysplex that is in the same cell.
  • SERVANTS: displays a list of the address space identifiers (ASIDs) of the servants that are attached to the server against which you issued the display command.
  • TRACE displays trace information for a server controller. You can further modify this command with one of the following options:
    • SRS displays trace information for all servants, one at a time.
    • ALL displays trace information for the controller and all servants one at a time.
    • JAVA displays the Java trace string settings for a server controller. You can further modify this command with one of the following options:
      • SRS displays Java trace information for all servants, one at a time.
      • ALL displays Java trace information for the controller and all servants one at a time.
      • HELP displays a list of all the keywords that you can use with the modify display trace Java command.
    • HELP displays a list of all the keywords that you can use with the modify display trace command.
  • JVMHEAP displays the JVM heap information for a server controller. You can further modify this command with one of the following options:
    • SRS displays the JVM heap information for all servants, one at a time.
    • ALL displays the JVM heap information for the controller and all servants, one at a time.
    • HELP displays a list of all the keywords that you can use with the modify display Javaheap command.
  • LISTENERS displays the connection instance name, associated IP address, and listening port number. The associated IP address can display an asterisk (*) as a wildcard.
  • CONNECTIONS displays each connection instance name and a count of the number of connections. Each connection instance is on a separate line. You can further modify this command with one of the following options:
    • NAME='name' displays the number of associated connections for the specified connection instance 'name'. If the connection name is located but has zero connections, the command returns a count of zero. If the connection name is not found, the command returns an error message.
    • LIST displays the remote host information for all of the connections of each of the connection instances. If a connection instance name has no connections, the command returns only the connection instance name.
    • LIST, NAME='name' displays the remote host information for all connections of a specified connection instance 'name' .
  • HELP displays a list of all the keywords that you can use with the modify command.
  • ERRLOG displays the last ten entries in the error log. You can further modify this option with one of the following options:
    • SRS displays the last ten entries in the error log for all servants, one at a time.
    • HELP displays a list of all the keywords you can use with the modify display error log command.
  • MODE displays the run bit mode.
  • WORK displays the work element counts for the server. You can further modify this option with one of the following options:
    • EJB displays Enterprise JavaBeans™ (EJB) request count information. You can modify this option with one of the following options:
      • SRS displays EJB request count information for all servants, one at a time.
      • HELP displays a list of all the keywords you can use with the modify display work EJB command.
    • SERVLET displays servlet request count information. You can modify this option with one of the following options:
      • SRS displays servlet request count information for all servants, one at a time.
      • HELP displays a list of all the keywords you can use with the modify display work servlet command.
    • MDB displays message-driven bean (MDB) request count information. You can further modify this command with one of the following options:
      • SRS displays MDB request count information for all servants, one at a time.
      • HELP displays a list of all the keywords you can use with the modify display work MDB command.
    • SIP displays Session Initiation Protocol (SIP) request count information. You can modify this option with one of the following options:
      • SRS displays SIP request count information for all servants, one at a time.
      • HELP displays a list of all the keywords you can use with the modify display work SIP command.
    • SUMMARY displays summary request count information.
      • SRS displays summary request count information for all servants, one at a time.
      • HELP displays a list of all the keywords you can use with the modify display work summary command.
    • ALL displays all request count information.
      • SRS displays all request count information for all servants, one at a time.
      • STATS displays all detailed statistics.
      • HELP displays a list of all the keywords you can use with the modify display work all command.
    • CLINFO displays work classification information.
    • HELP displays a list of all the keywords you can use with the modify display work command.
  • Fast Response Cache Accelerator (FRCA). Display FRCA cache statistics as follows:
    • f <servername>,display,frca
    • f <servername>,display,frca,content
    • f <servername>,display,frca,stats
  • [Fix Pack 4 or later] ADAPTER
    • STATUS

      Displays the status of the optimized local adapters component.

    • REGISTRATIONS

      Displays a list of optimized local adapters clients connected to this server.

    • DAEMONRGES

      Displays a list of optimized local adapters clients connected to any server in this daemon group.

    • SEARCHRGES

      Displays a list of optimized local adapters clients connected to any server in this daemon group, matching search criteria.

  • [Fix Pack 12 or later] OLATRACE=j j j j j j j j

    OLATRACE is a keyword with a parameter that specifies the jobname associated with the optimized local adapter exploiter with trace records that are to be displayed. The jobname can be a particular job or can be a single asterik to extract all adapter trace records.

    Formats and displays optimized local adapter trace records to the WebSphere Application Server SYSOUT, if tracing is enabled. To enable adapter tracing for specific registrations or for broad situations, see the topic, Using optimized local adapters diagnostic information.

    Examples:

    F <server>, DISPLAY, OLATRACE=jjjjjjjj
    • Display any available trace data for job WOLAJOB1:

      F BBOS001, DISPLAY, OLATRACE=WOLAJOB1

    • Display all available optimized local adapter data:

      F BBOS001, DISPLAY, OLATRACE=*

    In both examples, the system dumps matching trace records to the server's SYSOUT spool data. For a given use of the modify DISPLAY OLATRACE command, the trace report in SYSOUT is delimited by a header and footer line as follows:
    ******** OLATRACE modify command output start ****************************\n";
    ******** Trace records for jobname: <jjjjjjjjj>
    < formatted trace records > ******** End of OLATRACE modify command output ***************************

Example

You cannot cancel a cluster from the MVS console. Instead, you must cancel each of the servers that make up the cluster.

Example 1: The following command cancels the bbo6acr server:
f bbo6acr,cancel
Example 2: The following command cancels the bbo6acr server and instructs ARM to restart the bbo6acr server after the terminate process completes:
f bbo6acr,cancel,armrestart

Example: Establishing a general level of trace

To establish a general trace level for the server using scripting, use the following command:
f server,traceall=n

Valid trace levels are 0 (none), 1 (exception), 2 (basic), and 3 (detailed tracing). Under normal conditions and in production, use 1 (exception).

Example: The following command will turn on exception level tracing for the bbo6acr server:
f bbo6acr,traceall=1
Here is a sample display:
f bbo6acr,traceall=1
BBOO0211I MODIFY COMMAND TRACEALL=1 COMPLETED SUCCESSFULLY

This example demonstrates how to specify the WebSphere® for z/OS® components for which you want to switch on a basic level of tracing.

Use the following command:
f server,tracebasic=(n,...)
Example 1: The following command will turn on a basic level of tracing for the Daemon component on server bbo6acr:
f bbo6acr,tracebasic=a
Here is a sample display:
f bbo6acr,TRACEBASIC=A
BBOO0211I MODIFY COMMAND TRACEBASIC=A COMPLETED SUCCESSFULLY
To specify the WebSphere for z/OS components for which you want to switch on a detailed level of tracing use the following command:
f server,tracedetail=(n,...)
Example 2: The following command will turn on a detailed level of tracing for security on server bbo6acr:
f bbo6acr,tracedetail=e
Here is a sample display:
f bbo6acr,TRACEDETAIL=E
BBOO0211I MODIFY COMMAND TRACEDETAIL=E COMPLETED SUCCESSFULLY
To set specific trace points using scripting, use the following command:
f server,tracespecific=n | (n,...)
Example 1: The following command will turn on the specific trace point 04006001:
f bbo6acr,tracespecific=04006001
Example 2: The following command will turn on the specific trace points 04006001 and 04006027:
f bbo6acr,tracespecific=(04006001,04006027)
Example 3: The following command will turn on the specific trace points set in the environment variable tracepoints:
f bbo6acr,tracespecific='tracepoints'
To exclude specific trace points using scripting, use the following command:
f server,trace_exclude_specific=n | (n,...)
Example: The tracespecific command below turns on tracing for a whole part and then the trace_exclude_specific turns off tracing for the point 04006031 within that part.:
f bbo6acr,tracespecific=04006000

f bbo6acr,trace_exclude_specific=04006031
To reset to the initial trace settings using scripting, use the following command:
f server,traceinit
To turn off tracing, use the following command line command:
f server,tracenone
To send the trace to SYSPRINT use the following command:
f server,tracetosysprint=yes
To stop sending the trace to SYSPRINT, use the following command:
f server,tracetosysprint=no

Example: Canceling application clusters and servers with the modify command

This example demonstrates how to cancel application clusters and servers with the modify command.

Before you begin: You cannot cancel a cluster from the MVS console. Instead, you must cancel each of the servers that make up the cluster.

Example 1: The following command will cancel the bbo6acr server:


f bbo6acr,cancel

Example 2: The following command will cancel the bbo6acr server and instruct ARM to restart it after it terminates:


f bbo6acr,cancel,armrestart

Example: Getting help for the modify command

You can get syntax help for the various levels of the modify command.

Example 1: Enter the following command to display a list of all the keywords that you can use with the modify command:
f bbo6acr,help
The resulting output is similar to the following example:
F bbo6acr,HELP
BBOO0178I THE COMMAND MODIFY MAY BE FOLLOWED BY ONE OF THE FOLLOWING KEYWORDS:
BBOO0179I CANCEL - CANCEL THIS CONTROL REGION
BBOO0179I TRACEALL - SET OVERALL TRACE LEVEL
BBOO0179I TRACEBASIC - SET BASIC TRACE COMPONENTS
BBOO0179I TRACEDETAIL - SET DETAILED TRACE COMPONENTS
BBOO0179I TRACESPECIFIC - SET SPECIFIC TRACE POINTS
BBOO0179I TRACEINIT - RESET TO INITIAL TRACE SETTINGS
BBOO0179I TRACENONE - TURN OFF ALL TRACING
BBOO0179I TRACETOSYSPRINT - SEND TRACE OUTPUT TO SYSPRINT (YES/NO)
BBOO0179I TRACETOTRCFILE - SEND TRACE OUTPUT TO TRCFILE DD CARD (YES/NO)
BBOO0179I DISPLAY - DISPLAY STATUS
BBOO0179I TRACE_EXCLUDE_SPECIFIC - EXCLUDE SPECIFIC TRACE POINTS
BBOO0179I TRACEJAVA - SET JAVA TRACE OPTIONS
BBOO0179I TRACETOTRCFILE - SEND TRACE OUTPUT TO TRCFILE (YES/NO)   
BBOO0179I MDBSTATS - MDB DETAILED STATISTICS                       
BBOO0179I PAUSELISTENERS - PAUSE THE COMMUNICATION LISTENERS       
BBOO0179I RESUMELISTENERS - RESUME THE COMMUNICATION LISTENERS           
BBOO0179I STACKTRACE - LOG JAVA THREAD STACK TRACEBACKS              
BBOO0179I TIMEOUTDUMPACTION - SET TIMEOUT DUMP ACTION               
BBOO0179I TIMEOUTDUMPACTIONSESSION - SET TIMEOUT DUMP ACTION SESSION
BBOO0179I WLM_MIN_MAX - RESET WLM MIN/MAX SERVANT SETTINGS 
Example 2: Enter the following command to display a list of all the keywords you can use with the modify display command:
f bbo6acr,display,help
The resulting output is similar to the following example:
 F BBOS001,DISPLAY,HELP                                                   
 BBOO0178I THE COMMAND DISPLAY, MAY BE FOLLOWED BY ONE OF THE FOLLOWING   
 124                                                                      
 KEYWORDS:                                                                
 BBOO0179I SERVERS - DISPLAY ACTIVE CONTROL PROCESSES                     
 BBOO0179I SERVANTS - DISPLAY SERVANT PROCESSES OWNED BY THIS CONTROL 126 
 PROCESS                                                                  
 BBOO0179I LISTENERS - DISPLAY LISTENERS                                  
 BBOO0179I CONNECTIONS - DISPLAY CONNECTION INFORMATION                   
 BBOO0179I TRACE - DISPLAY INFORMATION ABOUT TRACE SETTINGS               
 BBOO0179I JVMHEAP - DISPLAY JVM HEAP STATISTICS                          
 BBOO0179I WORK - DISPLAY WORK ELEMENTS                                   
 BBOO0179I ERRLOG - DISPLAY THE LAST 10 ENTRIES IN THE ERROR LOG          
 BBOO0179I MODE - DISPLAY THE EXECUTION BITMODE                           
 BBOO0188I END OF OUTPUT FOR COMMAND DISPLAY,HELP
Example 3: Enter the following command to display a list of all the keywords that you can use with the modify timeoutdumpaction or modify timeoutdumpactionsession command:
f bbos001,timeoutdumpactionsession=help
The resulting output is similar to the following example:
BBOO0178I THE COMMAND MODIFY TIMEOUTDUMPACTIONSESSION= MAY BE FOLLOWED BY
ONE OF the FOLLOWING KEYWORDS:   
BBOO0179I SVCDUMP - SVC DUMP  
BBOO0179I JAVACORE - JAVA CORE DUMP   
BBOO0179I NONE - NO DUMP                   
Example 4: Enter the following command to display a list of all the keywords that you can use with the modify display dpm command:
f bbos001,dpm,help                                                  
The resulting output is similar to the following example:
BBOO0178I THE COMMAND MODIFY DPM, MAY BE FOLLOWED BY ONE OF THE     
FOLLOWING KEYWORDS:                                            
BBOO0179I IIOP - IIOP DISPATCH PROGRESS MONITOR INTERVAL            
BOO0179I HTTP - HTTP DISPATCH PROGRESS MONITOR INTERVAL            
BOO0179I HTTPS - HTTPS DISPATCH PROGRESS MONITOR INTERVAL          
BOO0179I MDB - MDB DISPATCH PROGRESS MONITOR INTERVAL              
BOO0179I SIP - SIP DISPATCH PROGRESS MONITOR INTERVAL              
BOO0179I SIPS - SIPS DISPATCH PROGRESS MONITOR INTERVAL            
BOO0179I CLEAR_ALL - CLEAR ALL DISPATCH PROGRESS MONITOR SETTINGS  
BOO0179I DUMP_ACTION - DISPATCH PROGRESS MONITOR DUMP ACTION       
BOO0211I MODIFY COMMAND DPM, COMPLETED SUCCESSFULLY   

Example: Modifying the Java trace string

This example shows how to use a console command to modify a Java trace string.

To modify the Java trace string, use the following command:
f server, tracejava='trace specification'
Example: The following command enables all types of tracing for all registered trace components:
f bbo6acr,tracejava='*=all'
Note: The single quotes are a required part of the syntax.



Related tasks
Using MVS™ console commands
Related reference
[z/OS] SVC dumps
Reference topic    

Terms of Use | Feedback

Last updated: Oct 21, 2010 7:37:48 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=v701sca&product=was-nd-mp&topic=rxml_mvsmodify
File name: rxml_mvsmodify.html