Dump

java.lang.Object
- com.ibm.jvm.Dump

```
public class Dump
extends java.lang.Object
```
APIs used to cause RAS dumps. -Xdump must be enabled on the command line.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`HeapDump()` Cause a HeapDump to occur.
`static java.lang.String`	`heapDumpToFile()` Trigger a heap dump.
`static java.lang.String`	`heapDumpToFile(java.lang.String fileNamePattern)` Trigger a heap dump.
`static void`	`JavaDump()` Cause a JavaDump to occur.
`static java.lang.String`	`javaDumpToFile()` Trigger a java dump.
`static java.lang.String`	`javaDumpToFile(java.lang.String fileNamePattern)` Trigger a java dump.
`static java.lang.String[]`	`queryDumpOptions()` Returns the current dump configuration as an array of Strings.
`static void`	`resetDumpOptions()` Reset the JVM dump options to the settings specified when the JVM was started removing any additional configuration done since then.
`static void`	`setDumpOptions(java.lang.String dumpOptions)` Sets options for the dump subsystem.
`static void`	`SnapDump()` Trigger a snap dump.
`static java.lang.String`	`snapDumpToFile()` Trigger a snap dump.
`static java.lang.String`	`snapDumpToFile(java.lang.String fileNamePattern)` Trigger a snap dump.
`static void`	`SystemDump()` Trigger a SystemDump to occur.
`static java.lang.String`	`systemDumpToFile()` Trigger a system dump.
`static java.lang.String`	`systemDumpToFile(java.lang.String fileNamePattern)` Trigger a system dump.
`static java.lang.String`	`triggerDump(java.lang.String dumpOptions)` Trigger a dump with the specified options.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - JavaDump
```
public static void JavaDump()
```
    Cause a JavaDump to occur. A JavaDump is in a human-readable format, and summarizes the state of the JVM.
    
    Throws:
    
    java.lang.RuntimeException - if the vm does not contain RAS dump support
  - HeapDump
```
public static void HeapDump()
```
    Cause a HeapDump to occur. The default HeapDump format (phd files) is not human-readable and must be processed using available tools.
    
    Throws:
    
    java.lang.RuntimeException - if the vm does not contain RAS dump support
  - SystemDump
```
public static void SystemDump()
```
    Trigger a SystemDump to occur. A SystemDump is a platform-specific file that contains information about the active processes, threads, and system memory. System dumps are usually large.
    
    Throws:
    
    java.lang.RuntimeException - if the vm does not contain RAS dump support
  - SnapDump
```
public static void SnapDump()
```
    Trigger a snap dump. The snap dump format is not human-readable and must be processed using the trace formatting tool supplied with the IBM JVM. A security manager check will be made only if the system property com.ibm.jvm.enableLegacyDumpSecurity is set to "true" in which case a check will be made for com.ibm.jvm.DumpPermission
    
    Throws:
    
    java.lang.RuntimeException - if the vm does not contain RAS dump support
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to take this dump
  - javaDumpToFile
```
public static java.lang.String javaDumpToFile(java.lang.String fileNamePattern)
                                       throws InvalidDumpOptionException
```
    Trigger a java dump. A java dump is in a human-readable format, and summarizes the state of the JVM. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the IBM JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:
    - null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
    - Replacement (%) tokens were specified in the file name. These will have been expanded.
    - The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
    - The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.
    If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
    Parameters:
    
    fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens
    
    Returns:
    
    the file name that the dump was actually written to
    
    Throws:
    
    InvalidDumpOptionException - if the filename was invalid
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
  - javaDumpToFile
```
public static java.lang.String javaDumpToFile()
```
    Trigger a java dump. A java dump is in a human-readable format, and summarizes the state of the JVM. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
    
    Returns:
    
    the file name that the dump was actually written to
    
    Throws:
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
  - heapDumpToFile
```
public static java.lang.String heapDumpToFile(java.lang.String fileNamePattern)
                                       throws InvalidDumpOptionException
```
    Trigger a heap dump. The default heap dump format (a phd file) is not human-readable. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the IBM JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:
    - null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
    - Replacement (%) tokens were specified in the file name. These will have been expanded.
    - The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
    - The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.
    If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
    Parameters:
    
    fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens
    
    Returns:
    
    the file name that the dump was actually written to
    
    Throws:
    
    InvalidDumpOptionException - if the filename was invalid
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
  - heapDumpToFile
```
public static java.lang.String heapDumpToFile()
```
    Trigger a heap dump. The default heap dump format (a phd file) is not human-readable. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
    
    Returns:
    
    the file name that the dump was actually written to
    
    Throws:
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
  - systemDumpToFile
```
public static java.lang.String systemDumpToFile(java.lang.String fileNamePattern)
                                         throws InvalidDumpOptionException
```
    Trigger a system dump. A system dump is a platform-specific file that contains information about the active processes, threads, and system memory. System dumps are usually large. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the IBM JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:
    - null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
    - Replacement (%) tokens were specified in the file name. These will have been expanded.
    - The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
    - The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.
    If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
    Parameters:
    
    fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens
    
    Returns:
    
    the file name that the dump was actually written to
    
    Throws:
    
    InvalidDumpOptionException - if the filename was invalid
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
  - systemDumpToFile
```
public static java.lang.String systemDumpToFile()
```
    Trigger a system dump. A system dump is a platform-specific file that contains information about the active processes, threads, and system memory. System dumps are usually large. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
    
    Returns:
    
    the file name that the dump was actually written to
    
    Throws:
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
  - snapDumpToFile
```
public static java.lang.String snapDumpToFile(java.lang.String fileNamePattern)
                                       throws InvalidDumpOptionException
```
    Trigger a snap dump. The snap dump format is not human-readable and must be processed using the trace formatting tool supplied with the IBM JVM. The JVM will attempt to write the file to the specified file name. This may include replacement tokens as documented in the section on dump agents in the documentation for the IBM JVM. A string containing the actual file name written to is returned. This may not be the same as the requested filename for several reasons:
    - null or the empty string were specified, this will cause the JVM to write the dump to the default location based on the current dump settings and return that path.
    - Replacement (%) tokens were specified in the file name. These will have been expanded.
    - The full path is returned, if only a file name with no directory was specified the full path with the directory the dump was written to will be returned.
    - The JVM couldn't write to the specified location. In this case it will attempt to write the dump to another location, unless -Xdump:nofailover was specified on the command line.
    If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
    Parameters:
    
    fileNamePattern - the file name to write to, which may be null, empty or include replacement tokens
    
    Returns:
    
    the file name that the dump was actually written to
    
    Throws:
    
    InvalidDumpOptionException - if the filename was invalid
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
  - snapDumpToFile
```
public static java.lang.String snapDumpToFile()
```
    Trigger a snap dump. The snap dump format is not human-readable and must be processed using the trace formatting tool supplied with the IBM JVM. The JVM will attempt to write the file to the default location. A string containing the actual file name written to is returned. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
    
    Returns:
    
    the file name that the dump was actually written to
    
    Throws:
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
  - triggerDump
```
public static java.lang.String triggerDump(java.lang.String dumpOptions)
                                    throws InvalidDumpOptionException
```
    Trigger a dump with the specified options. This method will trigger a dump of the specified type, with the specified options, immediately. The dump type and options are specified using the same string parameters as the -Xdump flag as described in the section on dump agents in the documentation for the IBM JVM. Settings that do not apply to dumps that occur immediately ("range=", "priority=", "filter=", "events=", "none" and "defaults") will be ignored. The "opts=" setting is supported if an option is used that causes two dumps to occur only the filename for the first will be returned. If a filename is specified for the dump it may contain replacement strings as specified in the documentation. In addition if a dump cannot be created with the specified filename the JVM may attempt to write it to another location. For these reasons you should always use the file name that is returned from this function when looking for the dump rather than the name you supplied. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown. If a "tool" dump is requested an additional check for com.ibm.jvm.ToolDumpPermission will also be made.
    
    Parameters:
    
    dumpOptions - a dump settings string
    
    Returns:
    
    The file name of the dump that was created. The String "-" means the dump was written to stderr.
    
    Throws:
    
    java.lang.RuntimeException - if the vm does not contain RAS dump support
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to trigger this dump
    
    InvalidDumpOptionException - If the dump options are invalid or the dump operation fails
    
    java.lang.NullPointerException - if dumpSettings is null
  - setDumpOptions
```
public static void setDumpOptions(java.lang.String dumpOptions)
                           throws InvalidDumpOptionException,
                                  DumpConfigurationUnavailableException
```
    Sets options for the dump subsystem. The dump option is passed in as an String. Use the same syntax as the -Xdump command-line option, with the initial -Xdump: omitted. See Using the -Xdump option as described in the section on dump agents in the documentation for the IBM JVM. This method may throw a DumpConfigurationUnavailableException if the dump configuration cannot be altered. If this occurs it will usually be because a dump event is currently being handled. As this can take some time depending on the dumps being generated an exception is thrown rather than this call blocking the calling thread potentially for minutes. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown. If a "tool" dump is specified an additional check for com.ibm.jvm.ToolDumpPermission will also be made.
    
    Parameters:
    
    dumpOptions - the options string to set
    
    Throws:
    
    InvalidDumpOptionException - if the specified option cannot be set or is incorrect
    
    DumpConfigurationUnavailableException - If the dump configuration cannot be changed because a dump is currently in progress
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to change the dump settings
    
    java.lang.NullPointerException - if options is null
  - queryDumpOptions
```
public static java.lang.String[] queryDumpOptions()
```
    Returns the current dump configuration as an array of Strings. The syntax of the option Strings is the same as the -Xdump command-line option, with the initial -Xdump: omitted. See Using the -Xdump option in the section on dump agents in the documentation for the IBM JVM. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
    
    Returns:
    
    the options strings
    
    Throws:
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to read the dump settings
  - resetDumpOptions
```
public static void resetDumpOptions()
                             throws DumpConfigurationUnavailableException
```
    Reset the JVM dump options to the settings specified when the JVM was started removing any additional configuration done since then. This method may throw a DumpConfigurationUnavailableException if the dump configuration cannot be altered. If this occurs it will usually be because a dump event is currently being handled. As this can take some time depending on the dumps being generated an exception is thrown rather than this call blocking the calling thread potentially for minutes. If a security manager exists a permission check for com.ibm.jvm.DumpPermission will be made, if this fails a SecurityException will be thrown.
    
    Throws:
    
    DumpConfigurationUnavailableException - if the dump configuration cannot be changed because a dump is currently in progress
    
    java.lang.SecurityException - if there is a security manager and it doesn't allow the checks required to change the dump settings

Methods inherited from class java.lang.Object

JavaDump

HeapDump

SystemDump

SnapDump

javaDumpToFile

javaDumpToFile

heapDumpToFile

heapDumpToFile

systemDumpToFile

systemDumpToFile

snapDumpToFile

snapDumpToFile

triggerDump

setDumpOptions

queryDumpOptions

resetDumpOptions