com.ibm.iseries.collectionservices
Class PerformanceDataReporter

java.lang.Object
  |
  +--com.ibm.iseries.collectionservices.PerformanceDataReporter

public class PerformanceDataReporter
extends java.lang.Object

PerformanceDataReporter class is a Java equivalent of User-defined Transaction APIs, which enable applications to send performance-related information to Performance Explorer and Collection Services.
For more information about User-defined Transaction APIs, go to iSeries Information Center.

Since:
V5R2M0

Field Summary
static java.lang.String copyright
           
 
Constructor Summary
PerformanceDataReporter()
          This constructor will create a new instance of PerformanceDataReporter class with performance reporting turned on.
PerformanceDataReporter(boolean enableReporting)
          With this constructor user can control initial state of performance reporting for new instance of PerformanceDataReporter class.
 
Method Summary
 boolean addTracePoint(byte[] applicationId, byte[] eventSubtypeId, byte[] pexData, int pexDataLength)
          If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause a generic trace record to be logged.
 boolean addTracePoint(byte[] applicationId, byte[] eventSubtypeId, java.lang.String pexData)
          If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause a generic trace record to be logged.
 void disableReporting()
          This method disables reporting of performance data for this instance of PerformanceDataReporter class.
 void enableReporting()
          This method enables reporting of performance data for this instance of PerformanceDataReporter class.
 boolean endTransaction(byte[] applicationId, int transactionId, byte[] pexData, int pexDataLength, long[] transactionStartTime, long[] collectionSvcsData)
          If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause performance data to be collected for end of transaction.
 boolean endTransaction(byte[] applicationId, int transactionId, java.lang.String pexData, long[] transactionStartTime, long[] collectionSvcsData)
          If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause performance data to be collected for end of transaction.
static boolean isPDCActive()
          This method tests if this thread is in an active PDC trace collection.
 boolean isReportingEnabled()
          This method tests if reporting of performance data is currently enabled for this instance of PerformanceDataReporter class.
static boolean isUsrtnsActive()
          This method tests if Collection Services collector is active and collects performance data for *USRTNS category.
 boolean logTransaction(byte[] applicationId, int transactionId, byte[] pexData, int pexDataLength)
          If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause additional transaction data to be logged.
 boolean logTransaction(byte[] applicationId, int transactionId, java.lang.String pexData)
          If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause additional transaction data to be logged.
 boolean startTransaction(byte[] applicationId, int transactionId, byte[] pexData, int pexDataLength, long[] transactionStartTime)
          If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause performance data to be collected for start of transaction.
 boolean startTransaction(byte[] applicationId, int transactionId, java.lang.String pexData, long[] transactionStartTime)
          If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause performance data to be collected for start of transaction.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

copyright

public static final java.lang.String copyright
Constructor Detail

PerformanceDataReporter

public PerformanceDataReporter(boolean enableReporting)
With this constructor user can control initial state of performance reporting for new instance of PerformanceDataReporter class.

Parameters:
enableReporting - Initial state of performance reporting for new instance of PerformanceDataReporter class.

PerformanceDataReporter

public PerformanceDataReporter()
This constructor will create a new instance of PerformanceDataReporter class with performance reporting turned on.
Method Detail

enableReporting

public void enableReporting()
This method enables reporting of performance data for this instance of PerformanceDataReporter class.
Both PEX trace data and Collection Services sample performance data are enabled.

disableReporting

public void disableReporting()
This method disables reporting of performance data for this instance of PerformanceDataReporter class.
Both PEX trace data and Collection Services sample performance data are disabled.

isReportingEnabled

public boolean isReportingEnabled()
This method tests if reporting of performance data is currently enabled for this instance of PerformanceDataReporter class.

Returns:
true if reporting of performance data is enabled, false otherwise.

isPDCActive

public static boolean isPDCActive()
This method tests if this thread is in an active PDC trace collection.

Returns:
true if this thread is in an active PDC trace collection, false otherwise. (PDC - Performance Data Collector).

isUsrtnsActive

public static boolean isUsrtnsActive()
This method tests if Collection Services collector is active and collects performance data for *USRTNS category.

Returns:
true if Collection Services collector is active and collects performance data for *USRTNS category, false otherwise.

startTransaction

public boolean startTransaction(byte[] applicationId,
                                int transactionId,
                                byte[] pexData,
                                int pexDataLength,
                                long[] transactionStartTime)
If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause performance data to be collected for start of transaction.

Performance data is collected in the following way:

Note that for the data to be collected for PEX, PDC trace data collection should be active for this thread; and for the data to be collected for Collection Services, collector should be active and collection for *USRTNS category should be turned on.

For more details see Start Transaction (qypeStartTransaction) API.

Parameters:
applicationId - The application identifier (or transaction type identifier). The user must input character data coded in CCSID 37. (If data is not in CCSID 37, application identifier may not be printable, when query is run on QAYPEMIUSR file for PEX data or QAPMUSRTNS file for Collection Services data.) The user can convert a java string to CCSID 37 as follows:
byte[] convertedData = stringToConvert.getBytes("cp037")
Application identifier is padded by EBCDIC blanks to 20 bytes. Excess bytes are ignored.
This parameter should not be null.
transactionId - Unique transaction identifier. Native code will handle this identifier as a 32-bit unsigned integer. Therefore negative transactionId will be interpreted as a very large positive number.
This parameter should not be null.
pexData - The user data to be logged in a trace record.
pexDataLength - The length of data in pexData paramater. If this length is greater than the size of pexData array, the actual size will be used. The maximum length of data is 3840 bytes. Any excess data will be ignored.
transactionStartTime - Transaction start time in MI timestamp format will be returned in the first element of this array.

Returns:
true if reporting is enabled and no exceptions were detected in processing, false otherwise.

startTransaction

public boolean startTransaction(byte[] applicationId,
                                int transactionId,
                                java.lang.String pexData,
                                long[] transactionStartTime)
If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause performance data to be collected for start of transaction.

Performance data is collected in the following way:

Note that for the data to be collected for PEX, PDC trace data collection should be active for this thread; and for the data to be collected for Collection Services, collector should be active and collection for *USRTNS category should be turned on.

For more details see Start Transaction (qypeStartTransaction) API.

Parameters:
applicationId - The application identifier (or transaction type identifier). The user must input character data coded in CCSID 37. (If data is not in CCSID 37, application identifier may not be printable, when query is run on QAYPEMIUSR file for PEX data or QAPMUSRTNS file for Collection Services data.) The user can convert a java string to CCSID 37 as follows:
byte[] convertedData = stringToConvert.getBytes("cp037")
Application identifier is padded by EBCDIC blanks to 20 bytes. Excess bytes are ignored.
This parameter should not be null.
transactionId - Unique transaction identifier. Native code will handle this identifier as a 32-bit unsigned integer. Therefore negative transactionId will be interpreted as a very large positive number.
pexData - The user data to be logged in a trace record. The maximum length of pexData string is 3840 characters. Any excess data will be ignored.
transactionStartTime - Transaction start time in MI timestamp format will be returned in the first element of this array.

Returns:
true if reporting is enabled and no exceptions were detected in processing, false otherwise.

endTransaction

public boolean endTransaction(byte[] applicationId,
                              int transactionId,
                              byte[] pexData,
                              int pexDataLength,
                              long[] transactionStartTime,
                              long[] collectionSvcsData)
If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause performance data to be collected for end of transaction.

Performance data is collected in the following way:

Note that for the data to be collected for PEX, PDC trace data collection should be active for this thread; and for the data to be collected for Collection Services, collector should be active and collection for *USRTNS category should be turned on.

For more details see End Transaction (qypeEndTransaction) API.

Parameters:
applicationId - The application identifier (or transaction type identifier). The user must input character data coded in CCSID 37. (If data is not in CCSID 37, application identifier may not be printable, when query is run on QAYPEMIUSR file for PEX data or QAPMUSRTNS file for Collection Services data.) The user can convert a java string to CCSID 37 as follows:
byte[] convertedData = stringToConvert.getBytes("cp037")
Application identifier is padded by EBCDIC blanks to 20 bytes. Excess bytes are ignored.
This parameter should not be null.
transactionId - Unique transaction identifier. Native code will handle this identifier as a 32-bit unsigned integer. Therefore negative transactionId will be interpreted as a very large positive number.
pexData - The user data to be logged in a trace record.
pexDataLength - The length of data in pexData paramater. If this length is greater than the size of pexData array, the actual size will be used. The maximum length of data is 3840 bytes. Any excess data will be ignored.
transactionStartTime - The first element of this array should contain transaction start time in MI timestamp format as returned from startTransaction method.
collectionSvcsData - This array may contain between 0 and 16 counters, which will be accumulated by Collection Services for this transaction. Excess counters will be ignored. Native code will handle these counters as 64-bit unsigned integers. Therefore negative values will be interpreted as very large positive numbers.

Returns:
true if reporting is enabled and no exceptions were detected in processing, false otherwise.

endTransaction

public boolean endTransaction(byte[] applicationId,
                              int transactionId,
                              java.lang.String pexData,
                              long[] transactionStartTime,
                              long[] collectionSvcsData)
If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause performance data to be collected for end of transaction.

Performance data is collected in the following way:

Note that for the data to be collected for PEX, PDC trace data collection should be active for this thread; and for the data to be collected for Collection Services, collector should be active and collection for *USRTNS category should be turned on.

For more details see End Transaction (qypeEndTransaction) API.

Parameters:
applicationId - The application identifier (or transaction type identifier). The user must input character data coded in CCSID 37. (If data is not in CCSID 37, application identifier may not be printable, when query is run on QAYPEMIUSR file for PEX data or QAPMUSRTNS file for Collection Services data.) The user can convert a java string to CCSID 37 as follows:
byte[] convertedData = stringToConvert.getBytes("cp037")
Application identifier is padded by EBCDIC blanks to 20 bytes. Excess bytes are ignored.
This parameter should not be null.
transactionId - Unique transaction identifier. Native code will handle this identifier as a 32-bit unsigned integer. Therefore negative transactionId will be interpreted as a very large positive number.
pexData - The user data to be logged in a trace record. The maximum length of pexData string is 3840 characters. Any excess data will be ignored.
transactionStartTime - The first element of this array should contain transaction start time in MI timestamp format as returned from startTransaction method.
collectionSvcsData - This array may contain between 0 and 16 counters, which will be accumulated by Collection Services for this transaction. Excess counters will be ignored. Native code will handle these counters as 64-bit unsigned integers. Therefore negative values will be interpreted as very large positive numbers.

Returns:
true if reporting is enabled and no exceptions were detected in processing, false otherwise.

logTransaction

public boolean logTransaction(byte[] applicationId,
                              int transactionId,
                              byte[] pexData,
                              int pexDataLength)
If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause additional transaction data to be logged.

Note that for the data to be collected, PDC trace data collection should be active for this thread.

For more details see Log Transaction (qypeLogTransaction) API.

Parameters:
applicationId - The application identifier (or transaction type identifier). The user must input character data coded in CCSID 37. (If data is not in CCSID 37, application identifier may not be printable, when query is run on QAYPEMIUSR file.) The user can convert a java string to CCSID 37 as follows:
byte[] convertedData = stringToConvert.getBytes("cp037")
Application identifier is padded by EBCDIC blanks to 20 bytes. Excess bytes are ignored.
This parameter should not be null.
transactionId - Unique transaction identifier. Native code will handle this identifier as a 32-bit unsigned integer. Therefore negative transactionId will be interpreted as a very large positive number.
pexData - The user data to be logged in a trace record.
pexDataLength - The length of data in pexData paramater. If this length is greater than the size of pexData array, the actual size will be used. The maximum length of data is 3840 bytes. Any excess data will be ignored.

Returns:
true if reporting is enabled and no exceptions were detected in processing, false otherwise.

logTransaction

public boolean logTransaction(byte[] applicationId,
                              int transactionId,
                              java.lang.String pexData)
If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause additional transaction data to be logged.

Note that for the data to be collected, PDC trace data collection should be active for this thread.

For more details see Log Transaction (qypeLogTransaction) API.

Parameters:
applicationId - The application identifier (or transaction type identifier). The user must input character data coded in CCSID 37. (If data is not in CCSID 37, application identifier may not be printable, when query is run on QAYPEMIUSR file.) The user can convert a java string to CCSID 37 as follows:
byte[] convertedData = stringToConvert.getBytes("cp037")
Application identifier is padded by EBCDIC blanks to 20 bytes. Excess bytes are ignored.
This parameter should not be null.
transactionId - Unique transaction identifier. Native code will handle this identifier as a 32-bit unsigned integer. Therefore negative transactionId will be interpreted as a very large positive number.
pexData - The user data to be logged in a trace record. The maximum length of pexData string is 3840 characteres. Any excess data will be ignored.

Returns:
true if reporting is enabled and no exceptions were detected in processing, false otherwise.

addTracePoint

public boolean addTracePoint(byte[] applicationId,
                             byte[] eventSubtypeId,
                             byte[] pexData,
                             int pexDataLength)
If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause a generic trace record to be logged.

Note that for the data to be collected, PDC trace data collection should be active for this thread.

For more details see Add Trace Point (qypeAddTracePoint) API.

Parameters:
applicationId - The application identifier. The user must input character data coded in CCSID 37. (If data is not in CCSID 37, application identifier may not be printable, when query is run on QAYPEMIUSR file.) The user can convert a java string to CCSID 37 as follows:
byte[] convertedData = stringToConvert.getBytes("cp037")
Application identifier is padded by EBCDIC blanks to 20 bytes. Excess bytes are ignored.
This parameter should not be null.
eventSubTypeId - The subtype which identifies the user event, e.g. *MIEV24. Note that this parameter should be entered in CCSID 37.
The maximum length of this array is 10 bytes. Excess bytes are ignored.
This parameter should not be null.
pexData - The user data to be logged in a trace record.
pexDataLength - The length of data in pexData paramater. If this length is greater than the size of pexData array, the actual size will be used. The maximum length of data is 3986 bytes. Any excess data will be ignored.

Returns:
true if reporting is enabled and no exceptions were detected in processing, false otherwise.

addTracePoint

public boolean addTracePoint(byte[] applicationId,
                             byte[] eventSubtypeId,
                             java.lang.String pexData)
If reporting was turned on for this instance of PerformanceDataReporter class (see enableReporting method), this method will cause a generic trace record to be logged.

Note that for the data to be collected, PDC trace data collection should be active for this thread.

For more details see Add Trace Point (qypeAddTracePoint) API.

Parameters:
applicationId - The application identifier. The user must input character data coded in CCSID 37. (If data is not in CCSID 37, application identifier may not be printable, when query is run on QAYPEMIUSR file.) The user can convert a java string to CCSID 37 as follows:
byte[] convertedData = stringToConvert.getBytes("cp037")
Application identifier is padded by EBCDIC blanks to 20 bytes. Excess bytes are ignored.
This parameter should not be null.
eventSubTypeId - The subtype which identifies the user event, e.g. *MIEV24. Note that this parameter should be entered in CCSID 37.
The maximum length of this array is 10 bytes. Excess bytes are ignored.
This parameter should not be null.
pexData - The user data to be logged in a trace record. The maximum length of pexData string is 3986 characters. Any excess data will be ignored.

Returns:
true if reporting is enabled and no exceptions were detected in processing, false otherwise.