| 1 | Collector name | Input | Char(10) |
| 2 | Category name | Input | Char(10) |
| 3 | Collector definition | Input | Char(10) |
| 4 | CCSID | Input | Binary(4) |
| 5 | Data collection program attributes | Input | Char(*) |
| 6 | Category attributes | Input | Char(*) |
| 7 | Error Code | I/O | Char(*) |
The Register Collector Data Category (QypsRegCollectorDataCategory) API adds a user-defined data category to one or more collector definitions of the Collection Services function of Management Central.
API caller must have at least *USE authority to the user profile specified in the Data collection program attributes parameter.
The user profile specified in the Data collection program attributes parameter must have at least *USE authority to the specified job description.
The name of the collector where the user-defined data category will be
added. The only currently supported value is:
| *PFR | Performance Collector |
The unique name of the user-defined data category. The category name must be a valid *NAME (basic name) and all uppercase. See ELEM (Element) Statement in CL Reference for more information about *NAME. Names of user-defined data categories registered by IBM® products start with "Q". Non-IBM applications are discouraged from prefixing names of user-defined categories with "Q".
The collector definition that the user-defined data category will be added to. Only one collector definition may be specified. Specifying *STANDARD registers the category to the *STANDARD, *STANDARDP and *CUSTOM definitions. Specifying *STANDARDP registers the category to the *STANDARDP and *CUSTOM definitions. Specifying *CUSTOM registers the category to the *CUSTOM definition only. The possible values are:
The coded character set identifier (CCSID) for the user-defined data category. Refer to specific field descriptions to determine where the CCSID is applicable. The CCSID will be validated by the API. The default value is 0.
| 0 | Use the current job default CCSID. |
| CCSID | A valid CCSID number. The valid range for this parameter is 1 through 65533. |
The attributes of the data collection program associated with the category. For more information on the format of the attributes, see Format of Data Collection Program Attributes.
Additional attributes associated with the category. For more information on the format of the category attributes, see Format of Category Attributes.
The structure in which to return error information. For the format of the structure, see Error code parameter.
For detailed descriptions of the fields in this table, see Data Collection Program Attributes Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Binary(4) | Size of fixed portion of attributes |
| 4 | 4 | Char(10) | Program type |
| 14 | E | Char(8) | Parameter format |
| 22 | 16 | Char(10) | User profile |
| 32 | 20 | Char(20) | Qualified job description name |
| 52 | 34 | Char(20) | Qualified (service) program name |
| 72 | 48 | Binary(4) | Size of work area |
| 76 | 4C | Binary(4) | Offset to service program entry point name |
| 80 | 50 | Binary(4) | Length of service program entry point name |
| 84 | 54 | Binary(4) | Offset to Java™ class name |
| 88 | 58 | Binary(4) | Length of Java class name |
| 92 | 5C | Binary(4) | Offset to Java class path |
| 96 | 60 | Binary(4) | Length of Java class path |
| 100 | 64 | Binary(4) | Offset to category parameter string |
| 104 | 68 | Binary(4) | Length of category parameter string |
| 108 | 6C | Binary(4) | Offset to Java options array |
| 112 | 70 | Binary(4) | Number of entries in Java options array |
| 116 | 74 | Binary(4) | Reserved |
Overview of Offset/Length usage of variable length character data The variable length character data will follow the fixed portion of the Data collection program attributes structure and reside with the same address space. The offset to the variable length character data specified in the fixed portion of the structure is the offset in bytes from the beginning of the attribute structure to the first byte of the character data.
Length of category parameter string The length of the string passed in for the category parameter string. If 0 is specified then the null parameter string will be passed to the data collection program.
Length of Java class name The length of the string passed in for the Java class name. This parameter must be set to 0 if Program type is not *JVAPGM.
Length of Java class path The length of the string passed in for the Java class path. This parameter must be set to 0 if Program type is not *JVAPGM.
Length of service program entry point name The length of the string passed in for the service program entry point name. This parameter must be set to 0 if Program type is not *SRVPGM.
Number of entries in Java Options Array The number of entries in the Java Options Array (see Format of Java Options Array below). If set to 0, no options will be passed to the Java Virtual Machine (JVM). This parameter must be set to 0 if Program type is not *JVAPGM.
Offset to category parameter string The offset of the string passed in for the category parameter string. The category parameter string is a character string which is passed to the data collection program to customize its processing. The category parameter string must contain character data. The CCSID is applicable to the category parameter string. If 0 is specified then a null parameter string will be passed to the data collection program.
Offset to Java class name The offset in bytes to the string passed in for the Java class name. This parameter must be set to 0 if Program type is not *JVAPGM. The Java class name is the name of a Java class which implements the data collection program interface for this category. For more information about Java class name format, see the Java section in the IBM i Information Center. The CCSID is applicable to the Java class name.
Offset to Java class path The offset in bytes to the string passed in for the Java class path. This parameter must be set to 0 if Program type is not *JVAPGM. For more information about Java class name format, see the Java section in the IBM i Information Center. The CCSID is applicable to the Java class path.
Offset to Java options array The offset of the Java Options Array (see Format of Java Options Array below). The Java Options Array is an array of options passed to the JVM. If the offset is set to 0, no options will be passed to the JVM. This parameter must be set to 0 if Program type is not *JVAPGM. All options are character strings and the CCSID is applicable to them.
Offset to service program entry point name The offset in bytes to the string passed in for the service program entry point name. This parameter must be set to 0 if Program type is not *SRVPGM. The service program entry point name is the name of an entry point in a service program which implements the data collection program for this category.
Parameter format This field defines the format of the parameters passed to the data collection program when it is called by Collection Services to collect data for the category. The only format currently supported is PMDC0100.
Qualified job description name The job description which will be used by the Collection Services secondary job to run the data collection program. The first 10 characters contain the job description name and the next 10 characters contain the library name. The following special values can be used for the job description name:
| *JOB | Use the job description associated with the current job. The specified library parameter is ignored and must be filled with blank spaces or hex zeros. |
| *USER | Use the job description associated with the current user. The specified library parameter is ignored and must be filled with blank spaces or hex zeros. |
The following special values can be used for the library name:
| *CURLIB | The current library of the job executing this API. |
| *LIBL | Search the library list to find the specified job description. |
Qualified (service) program name The qualified name of a program object if Program type is *PGM or the qualified name of a service program object if Program type is *SRVPGM. The first 10 characters contain the program or service program name and the next 10 characters contain the library name. This parameter must be set to 0 if Program type is *JVAPGM.
Size of fixed portion of attributes The size in bytes of the fixed portion of the Data collection program attribute structure.
Size of work area The size in bytes of a work area Collection Services will provide to the data collection program to save state information between the calls. This parameter must be set to 0 if Program type is *JVAPGM.
User profile User profile which will be used by Collection Services to run the data collection program. The API caller must have at least *USE authority to this user profile.
For detailed descriptions of the fields in this table, see Java Options Array Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Binary(4) | Offset to Java option 1 |
| 4 | 4 | Binary(4) | Length of Java option 1 |
| 8 | 8 | Binary(4) | Offset to Java option 2 |
| 12 | C | Binary(4) | Length of Java option 2 |
| ... | |||
| Char(*) | Java option 1 | ||
| Char(*) | Java option 2 | ||
The Java options array contains an array of option settings which will be passed to the Java Virtual Machine (JVM) at Java initialization time. The number of elements in this array is determined by the Number of entries in Java options array field in the Data collection program attributes structure. This array is optional and is ignored when Program type is not *JVAPGM.
Java options are not validated and are passed to the JVM exactly as specified for the Registration API.
Length of Java option N
The length in bytes of the string passed in for the Nth Java option.
Offset to Java option N
The offset in bytes from the beginning of the Java Options Array to the string passed in for the Nth Java option. All Java options are character strings and the CCSID applies to them.
For detailed descriptions of the fields in this table, see Category attributes Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Binary(4) | Size of attribute structure |
| 4 | 4 | Binary(4) | Minimum collection interval |
| 8 | 8 | Binary(4) | Maximum collection interval |
| 12 | C | Binary(4) | Default collection interval |
| 16 | 10 | Char(27) | Qualified message file and message identifier |
| 43 | 2B | Char(50) | Text description |
| 93 | 5D | Char(3) | Reserved |
Default collection interval
The default interval to use when collecting data for a category in seconds. This may be specified as one of 15, 30, 60, 300, 900, 1800, or 3600 seconds. The following special value is allowed:
| 0 | Use the collector definition of the collector that the category is registered to. |
Minimum collection interval
The minimum interval this user-defined data category should be collected at. In other words, this represents the smallest interval of data collection. This may be specified as one of 15, 30, 60, 300, 900, 1800, or 3600 seconds. Specifying 0 represents no restriction on the minimum collection interval.
Maximum collection interval
The maximum interval this user-defined data category should be collected at. In other words, this represents the largest interval of data collection. This may be specified as one of 15, 30, 60, 300, 900, 1800, or 3600 seconds. Specifying 0 represents no restriction on the maximum collection interval.
Qualified message file and message identifier
The qualified message file and message identifier of the text description of the category. The first 10 characters contain the message file name, the next 10 characters contain the library name of the message file, and the final 7 characters contain the message identifier. If the text description is specified as a character string (in Text description field), this field should be set to all blanks or hex zeros. The possible values for the library are:
| *LIBL | Search the library list for the first occurrence of the message file. |
| Library name | The name of the library the message file resides in. |
Size of attribute structure
The size in bytes of the category attribute structure.
Text description
The text description associated with the category. The supplied CCSID will be applied to the text description. This parameter is ignored and must be filled with blank spaces or hex zeros if a qualified message file and message identifier has been specified.
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF222E E | &1 special authority is required. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPFB537 E | Error found in parameter &1 at offset &2. |
| CPFB538 E | Error found in parameter &1 at offset &2. |
| CPFB94C E | Collection interval value must be one of 15, 30, 60, 300, 900, 1800, or 3600 seconds. |
| CPFB94D E | Category name &1 aleady exists. |
Introduced: V5R2