Retrieve Job Information (QUSRJOBI) API
Required Parameter Group:
1 | Receiver variable | Output | Char(*) |
2 | Length of receiver variable | Input | Binary(4) |
3 | Format name | Input | Char(8) |
4 | Qualified job name | Input | Char(26) |
5 | Internal job identifier | Input | Char(16) |
Optional Parameter Group 1:
6 | Error code | I/O | Char(*) |
Optional Parameter Group 2:
7 | Reset performance statistics | Input | Char(1) |
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The Retrieve Job Information (QUSRJOBI) API retrieves specific information about a job.
The QSYS2.GET_JOB_INFO table function can be used as an alternative to this API. See GET_JOB_INFO table function for more information.
Authorities and Locks
The following authority restrictions apply only when the API is called for format names JOBI0700, JOBI0750, JOBI0800, or JOBI0900. All other format names have no authority restrictions.
- Job Authority
-
When calling this API for format names JOBI0700, JOBI0750 or JOBI0800 the API
must be called from within the job for which the information is being retrieved
or the caller of the API must be running under a user profile that is the same
as the job user identity of the job for which the information is being
retrieved or the caller of the API must be running under a user profile that
has job control (*JOBCTL) special authority.
When calling this API for format name JOBI0900, the API must be called from
within the job for which the information is being retrieved or the caller
of the API must be running under a user profile that is the same as the
job user identity of the job for which the information is being retrieved
or the caller of the API must be running under a user profile that has
job control (*JOBCTL) special authority or be authorized to the
Database Administrator (QIBM_DB_SQLADM) function or the Database Information
(QIBM_DB_SYSMON) function through Application Administration
in IBM Navigator for i or the Change Function Usage Information (CHGFCNUSG)
command.
The job user identity is the name of the user profile by which a job is known to other jobs. It is described in more detail in the Work management topic collection.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the information requested. You can specify the size of this area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The format of the job information to be returned. The format names supported are:
JOBI0100 Basic performance information JOBI0150 Additional performance information JOBI0200 WRKACTJOB information JOBI0300 Job queue and output queue information JOBI0400 Job attribute information JOBI0500 Message logging information JOBI0600 Active job information JOBI0700 Library list information JOBI0750 Extended library list information JOBI0800 Active job signal information JOBI0900 Active job SQL information JOBI1000 Elapsed performance statistics Refer to Selecting a Job Information Format for details of each of the formats.
- Qualified job name
- INPUT; CHAR(26)
The name of the job for which information is to be returned. The qualified job name has three parts:
Job name CHAR(10). A specific job name or one of the following special values: * The job that this program is running in. The rest of the qualified job name parameter must be blank. *INT The internal job identifier locates the job. The user name and job number must be blank. User name CHAR(10). A specific user profile name, or blanks when the job name is a special value or *INT. Job number CHAR(6). A specific job number, or blanks when the job name specified is a special value or *INT.
- Internal job identifier
- INPUT; CHAR(16)
The internal identifier for the job. The List Job API, QUSLJOB, creates this identifier. If you do not specify *INT for the job name parameter, this parameter must contain blanks. With this parameter, the system can locate the job more quickly than with a job name.
Optional Parameter 1
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
Optional Parameter 2
- Reset performance statistics
- INPUT; CHAR(1)
The elapsed time and all fields that are part of the JOBI1000 format, which are based on the elapsed time, will be reset to zero. This field must be zero if other formats are specified. The default value for this field is zero. The following special values may be specified:
0 The performance statistics will not be reset. The elapsed time will be incremented and the fields in the JOBI1000 format will be recalculated based on the elapsed time interval. 1 The elapsed time and the fields in the JOBI1000 format will be reset to zero.
Selecting a Job Information Format
All formats may be called against multithreaded jobs; that is, single threaded Job A may retrieve job information about multithreaded Job B. Refer to Considerations for Attribute Scope and Thread Safety for thread safety information when calling these formats from within a multithreaded job.
The following section presents some of the performance characteristics of the different formats (primarily JOBI0100, JOBI0150, and JOBI0200). When formats return some of the same information, the performance effects are discussed. When a format contains information not available in other formats, performance is not discussed.
JOBI0100 | This format returns basic performance information about a job. It is faster than the JOBI0150 format and the JOBI0200 format (which also contain performance information). The reason that this format is faster is that it does not touch as many objects, causing less paging when retrieving information about the job. |
JOBI0150 | This format returns additional performance information, and is slower than the JOBI0100 format. It is similar to the JOBI0200 format, but is faster than that format because there is less paging involved in retrieving the information. |
JOBI0200 | This format returns information equivalent to that found on the Work with Active Jobs (WRKACTJOB) command. |
JOBI0300 | This format returns job queue and output queue information for a job, as well as information about the submitter's job if the job is a submitted batch job. |
JOBI0400 | This format primarily returns job attribute types of information, but has other types of information as well. |
JOBI0500 | This format returns message logging information. |
JOBI0600 | This format returns information about active jobs only. It is intended to supplement the JOBI0400 format. It retrieves information from several additional objects associated with the job, and therefore, it causes additional paging. |
JOBI0700 | This format returns library list information for an active job. |
JOBI0750 | This format returns library list information for an active job plus additional information about each library returned. |
JOBI0800 | This format returns signal information for an active job. |
JOBI0900 | This format returns SQL information for an active job. |
JOBI1000 | This format returns elapsed performance statistics. Performance values returned are based on an elapsed time (returned as part of this format). |
Each format returns information that is only valid for the status of certain jobs. For example, the JOBI0200 format only returns information for active jobs. Because the job status can change between the time the list is generated and the time the Retrieve Job Information API is called, you must design your application to handle this.
When requesting information about a job that has an unknown or incorrect job status for the format requested, the API returns the current status of the job and sets the remainder of the fields for that format to zeros and blanks. When requesting information about a job that is not valid, the API returns the job's status as blanks and sets the remainder of the fields for that format to zeros and blanks. Therefore, you should check the returned status of the job before processing the data. Each format description specifies each status for which the API returns complete information.
JOBI0100 Format
The JOBI0100 format information is valid for active jobs and jobs on queues. For jobs on queues, this format returns zeros or blanks for the attributes. If the Change Job (CHGJOB) command or Change Job (QWTCHGJB) API was run against a job on a *JOBQ, the attributes returned are the attributes specified on the Change Job request. If the job status changes to *OUTQ, the status field returned is *OUTQ and the API returns no information other than the number of bytes returned, the number of bytes available, the qualified job name, the job type, the job subtype, and the internal job identifier.
The JOBI0100 format returns the following job information. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Number of bytes returned |
4 | 4 | BINARY(4) | Number of bytes available |
8 | 8 | CHAR(10) | Job name |
18 | 12 | CHAR(10) | User name |
28 | 1C | CHAR(6) | Job number |
34 | 22 | CHAR(16) | Internal job identifier |
50 | 32 | CHAR(10) | Job status |
60 | 3C | CHAR(1) | Job type |
61 | 3D | CHAR(1) | Job subtype |
62 | 3E | CHAR(2) | Reserved |
64 | 40 | BINARY(4) | Run priority (job) |
68 | 44 | BINARY(4) | Time slice |
72 | 48 | BINARY(4) | Default wait |
76 | 4C | CHAR(10) | Purge |
JOBI0150 Format
The JOBI0150 format is valid for active jobs and jobs on job queues. For jobs on job queues, this format returns zeros or blanks for the attributes. If the Change Job (CHGJOB) command or Change Job (QWTCHGJB) API was run against a job on a job queue, the attributes returned are the attributes specified on the Change Job request. If the job status changes to *OUTQ, the status field returned is *OUTQ and the API returns no information other than the number of bytes returned, the number of bytes available, the qualified job name, the job type, the job subtype, and the internal job identifier.
The JOBI0150 format returns the following job information. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | Returns everything from format JOBI0100 | |
86 | 56 | CHAR(10) | Time-slice end pool |
96 | 60 | BINARY(4) | Processing unit time used, if less than 2,147,483,647 milliseconds |
100 | 64 | BINARY(4) | System pool identifier |
104 | 68 | BINARY(4) | Maximum processing unit time allowed |
108 | 6C | BINARY(4) | Temporary storage used, in kilobytes, if less than 2,147,483,647 |
112 | 70 | BINARY(4) | Maximum temporary storage allowed, in kilobytes, if less than 2,147,483,647 |
116 | 74 | BINARY(4) | Thread count |
120 | 78 | BINARY(4) | Maximum threads |
124 | 7C | BINARY(4), UNSIGNED | Temporary storage used, in megabytes |
128 | 80 | BINARY(4) | Maximum temporary storage, in megabytes |
132 | 84 | BINARY(4), UNSIGNED | Peak temporary storage used, in megabytes |
136 | 88 | BINARY(8), UNSIGNED | Processing unit time used - total for the job |
JOBI0200 Format
The JOBI0200 format is only valid for active jobs and is similar to the information supported by the Work with Active Jobs (WRKACTJOB) command. If the job status has changed to *OUTQ or *JOBQ, the status field is set appropriately, and no information other than the number of bytes returned, the number of bytes available, the qualified job name, the job type, the job subtype, and the internal job identifier is returned.
The JOBI0200 format returns the following job information. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Number of bytes returned |
4 | 4 | BINARY(4) | Number of bytes available |
8 | 8 | CHAR(10) | Job name |
18 | 12 | CHAR(10) | User name |
28 | 1C | CHAR(6) | Job number |
34 | 22 | CHAR(16) | Internal job identifier |
50 | 32 | CHAR(10) | Job status |
60 | 3C | CHAR(1) | Job type |
61 | 3D | CHAR(1) | Job subtype |
62 | 3E | CHAR(10) | Subsystem description name |
72 | 48 | BINARY(4) | Run priority (job) |
76 | 4C | BINARY(4) | System pool identifier |
80 | 50 | BINARY(4) | Processing unit time used, if less than 2,147,483,647 milliseconds |
84 | 54 | BINARY(4) | Number of auxiliary I/O requests, if less than 2,147,483,647 |
88 | 58 | BINARY(4) | Number of interactive transactions |
92 | 5C | BINARY(4) | Response time total |
96 | 60 | CHAR(1) | Function type |
97 | 61 | CHAR(10) | Function name |
107 | 6B | CHAR(4) | Active job status |
111 | 6F | BINARY(4) | Number of database lock waits |
115 | 73 | BINARY(4) | Number of internal machine lock waits |
119 | 77 | BINARY(4) | Number of nondatabase lock waits |
123 | 7B | BINARY(4) | Time spent on database lock waits |
127 | 7F | BINARY(4) | Time spent on internal machine lock waits |
131 | 83 | BINARY(4) | Time spent on nondatabase lock waits |
135 | 87 | CHAR(1) | Reserved |
136 | 88 | BINARY(4) | Current system pool identifier |
140 | 8C | BINARY(4) | Thread count |
144 | 90 | BINARY(8), UNSIGNED | Processing unit time used - total for the job |
152 | 98 | BINARY(8), UNSIGNED | Number of auxiliary I/O requests |
160 | A0 | BINARY(8), UNSIGNED | Processing unit time used for database - total for the job |
168 | A8 | BINARY(8), UNSIGNED | Page faults |
176 | B0 | CHAR(4) | Active job status for jobs ending |
180 | B4 | CHAR(10) | Memory pool name |
190 | BE | CHAR(1) | Message reply |
191 | BF | CHAR(4) | Message key, when active job waiting for a message |
195 | C3 | CHAR(10) | Message queue name, when active job waiting for a message |
205 | CD | CHAR(10) | Message queue library name, when active job waiting for a message |
215 | D7 | CHAR(10) | Message queue library ASP device name, when active job waiting for a message |
225 | E1 | CHAR(3) | Reserved |
228 | E4 | BINARY(4) | Prestart job reuse count |
232 | E8 | BINARY(4) | Prestart job maximum number of uses |
JOBI0300 Format
This format returns job queue and output queue information for a job, as well as information about the submitter's job. This information is valid for any job status. The JOBI0300 format returns the following job information. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Number of bytes returned |
4 | 4 | BINARY(4) | Number of bytes available |
8 | 8 | CHAR(10) | Job name |
18 | 12 | CHAR(10) | User name |
28 | 1C | CHAR(6) | Job number |
34 | 22 | CHAR(16) | Internal job identifier |
50 | 32 | CHAR(10) | Job status |
60 | 3C | CHAR(1) | Job type |
61 | 3D | CHAR(1) | Job subtype |
62 | 3E | CHAR(10) | Job queue name |
72 | 48 | CHAR(10) | Job queue library name |
82 | 52 | CHAR(2) | Job queue priority |
84 | 54 | CHAR(10) | Output queue name |
94 | 5E | CHAR(10) | Output queue library name |
104 | 68 | CHAR(2) | Output queue priority |
106 | 6A | CHAR(10) | Printer device name |
116 | 74 | CHAR(10) | Submitter's job name |
126 | 7E | CHAR(10) | Submitter's user name |
136 | 88 | CHAR(6) | Submitter's job number |
142 | 8E | CHAR(10) | Submitter's message queue name |
152 | 98 | CHAR(10) | Submitter's message queue library name |
162 | A2 | CHAR(10) | Status of job on the job queue |
172 | AC | CHAR(8) | Date and time job was put on this job queue |
180 | B4 | CHAR(7) | Job date |
187 | BB | CHAR(10) | Job queue library ASP device name |
JOBI0400 Format
This format primarily returns job attribute types of information, but has other types of information as well. This format is valid for any job status. The JOBI0400 format returns the following job information. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Number of bytes returned |
4 | 4 | BINARY(4) | Number of bytes available |
8 | 8 | CHAR(10) | Job name |
18 | 12 | CHAR(10) | User name |
28 | 1C | CHAR(6) | Job number |
34 | 22 | CHAR(16) | Internal job identifier |
50 | 32 | CHAR(10) | Job status |
60 | 3C | CHAR(1) | Job type |
61 | 3D | CHAR(1) | Job subtype |
62 | 3E | CHAR(13) | Date and time job entered system |
75 | 4B | CHAR(13) | Date and time job became active |
88 | 58 | CHAR(15) | Job accounting code |
103 | 67 | CHAR(10) | Job description name |
113 | 71 | CHAR(10) | Job description library name |
123 | 7B | CHAR(24) | Unit of work ID |
147 | 93 | CHAR(8) | Mode name |
155 | 9B | CHAR(10) | Inquiry message reply |
165 | A5 | CHAR(10) | Logging of CL programs |
175 | AF | CHAR(10) | Break message handling |
185 | B9 | CHAR(10) | Status message handling |
195 | C3 | CHAR(13) | Device recovery action |
208 | D0 | CHAR(10) | DDM conversation handling |
218 | DA | CHAR(1) | Date separator |
219 | DB | CHAR(4) | Date format |
223 | DF | CHAR(30) | Print text |
253 | FD | CHAR(10) | Submitter's job name |
263 | 107 | CHAR(10) | Submitter's user name |
273 | 111 | CHAR(6) | Submitter's job number |
279 | 117 | CHAR(10) | Submitter's message queue name |
289 | 121 | CHAR(10) | Submitter's message queue library name |
299 | 12B | CHAR(1) | Time separator |
300 | 12C | BINARY(4) | Coded character set ID |
304 | 130 | CHAR(8) | Date and time job is scheduled to run |
312 | 138 | CHAR(10) | Print key format |
322 | 142 | CHAR(10) | Sort sequence table name |
332 | 14C | CHAR(10) | Sort sequence library |
342 | 156 | CHAR(3) | Language ID |
345 | 159 | CHAR(2) | Country or region ID |
347 | 15B | CHAR(1) | Completion status |
348 | 15C | CHAR(1) | Signed-on job |
349 | 15D | CHAR(8) | Job switches |
357 | 165 | CHAR(10) | Job message queue full action |
367 | 16F | CHAR(1) | Reserved |
368 | 170 | BINARY(4) | Job message queue maximum size |
372 | 174 | BINARY(4) | Default coded character set identifier |
376 | 178 | CHAR(80) | Routing data |
456 | 1C8 | CHAR(1) | Decimal format |
457 | 1C9 | CHAR(10) | Character identifier control |
467 | 1D3 | CHAR(30) | Server type |
497 | 1F1 | CHAR(1) | Allow multiple threads |
498 | 1F2 | CHAR(1) | Job log pending |
499 | 1F3 | CHAR(1) | Reserved |
500 | 1F4 | BINARY(4) | Job end reason |
504 | 1F8 | BINARY(4) | Job type - enhanced |
508 | 1FC | CHAR(13) | Date and time job ended |
521 | 209 | CHAR(1) | Reserved |
522 | 20A | CHAR(10) | Spooled file action |
532 | 214 | BINARY(4) | Offset to ASP group information |
536 | 218 | BINARY(4) | Number of entries in ASP group information |
540 | 21C | BINARY(4) | Length of one ASP group information entry |
544 | 220 | CHAR(10) | Time zone description name |
554 | 22A | CHAR(10) | Job log output |
564 | 234 | CHAR(10) | Job description library ASP device name |
This field repeats for each ASP group information entry. | CHAR(*) | ASP group information entry (See Format of ASP Group Information Entry for more information.) |
Format of ASP Group Information Entry
The ASP group information entry describes the data that is returned for each ASP group in the ASP group information of the JOBI0400 format. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
The fields repeat for each ASP group. | CHAR(10) | ASP group name | |
CHAR(*) | Reserved |
JOBI0500 Format
This format returns message logging information. This format is valid for any job status. The JOBI0500 format returns the following job information. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Number of bytes returned |
4 | 4 | BINARY(4) | Number of bytes available |
8 | 8 | CHAR(10) | Job name |
18 | 12 | CHAR(10) | User name |
28 | 1C | CHAR(6) | Job number |
34 | 22 | CHAR(16) | Internal job identifier |
50 | 32 | CHAR(10) | Job status |
60 | 3C | CHAR(1) | Job type |
61 | 3D | CHAR(1) | Job subtype |
62 | 3E | CHAR(2) | Reserved |
64 | 40 | BINARY(4) | End severity |
68 | 44 | BINARY(4) | Logging severity |
72 | 48 | CHAR(1) | Logging level |
73 | 49 | CHAR(10) | Logging text |
JOBI0600 Format
The JOBI0600 format returns information about active jobs. If the job status changes to *JOBQ or *OUTQ, the status field is set appropriately, and no information other than the number of bytes returned, the number of bytes available, the qualified job name, the job type, the job subtype, and the internal job identifier is returned.
The JOBI0600 format returns the following job information. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Number of bytes returned |
4 | 4 | BINARY(4) | Number of bytes available |
8 | 8 | CHAR(10) | Job name |
18 | 12 | CHAR(10) | User name |
28 | 1C | CHAR(6) | Job number |
34 | 22 | CHAR(16) | Internal job identifier |
50 | 32 | CHAR(10) | Job status |
60 | 3C | CHAR(1) | Job type |
61 | 3D | CHAR(1) | Job subtype |
62 | 3E | CHAR(8) | Job switches |
70 | 46 | CHAR(1) | End status |
71 | 47 | CHAR(10) | Subsystem description name |
81 | 51 | CHAR(10) | Subsystem description library name |
91 | 5B | CHAR(10) | Current user profile |
101 | 65 | CHAR(1) | DBCS-capable |
102 | 66 | CHAR(1) | Exit key |
103 | 67 | CHAR(1) | Cancel key |
104 | 68 | BINARY(4) | Product return code |
108 | 6C | BINARY(4) | User return code |
112 | 70 | BINARY(4) | Program return code |
116 | 74 | CHAR(10) | Special environment |
126 | 7E | CHAR(10) | Device name |
136 | 88 | CHAR(10) | Group profile name |
146 | 92 | ARRAY(15) of CHAR(10) | Group profile name - supplemental |
296 | 128 | CHAR(10) | Job user identity |
306 | 132 | CHAR(1) | Job user identity setting |
307 | 133 | CHAR(15) | Client IP address - IPv4 |
322 | 142 | CHAR(2) | Reserved |
324 | 144 | BINARY(4) | Offset to time zone information |
328 | 148 | BINARY(4) | Length of time zone information |
332 | 14C | CHAR(4) | Day of week |
CHAR(*) | Time zone information (See Format of Time Zone Information for more information.) |
Format of Time Zone Information
The following table describes the data that is returned for the time zone information of the JOBI0600 format. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
CHAR(10) | Time zone description name | ||
CHAR(1) | Reserved | ||
CHAR(1) | Time zone Daylight Saving Time indicator | ||
BINARY(4) | Time zone current offset | ||
CHAR(50) | Time zone current full name | ||
CHAR(10) | Time zone current abbreviated name | ||
CHAR(7) | Time zone current message identifier | ||
CHAR(10) | Time zone message file name | ||
CHAR(10) | Time zone message file library | ||
CHAR(*) | Reserved |
JOBI0700 Format
The JOBI0700 format returns library list information for active jobs only. The format returns the actual length instead of the total length because all libraries may not exist. The JOBI0700 format returns the following job information. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Number of bytes returned |
4 | 4 | BINARY(4) | Number of bytes available |
8 | 8 | CHAR(10) | Job name |
18 | 12 | CHAR(10) | User name |
28 | 1C | CHAR(6) | Job number |
34 | 22 | CHAR(16) | Internal job identifier |
50 | 32 | CHAR(10) | Job status |
60 | 3C | CHAR(1) | Job type |
61 | 3D | CHAR(1) | Job subtype |
62 | 3E | CHAR(2) | Reserved |
64 | 40 | BINARY(4) | Number of libraries in SYSLIBL |
68 | 44 | BINARY(4) | Number of product libraries |
72 | 48 | BINARY(4) | Current library existence |
76 | 4C | BINARY(4) | Number of libraries in USRLIBL |
See note | See note | Array(*) of CHAR(11) | System library list |
See note | See note | Array(*) of CHAR(11) | Product libraries |
See note | See note | Array(*) of CHAR(11) | Current library |
See note | See note | Array(*) of CHAR(11) | User library list |
Note: The decimal and hexadecimal offsets depend on the number of libraries you have in the various parts of your library lists. The data is left-justified with a blank pad at the end. The array is sequential. It is an array or data structure. See the Control language topic collection for the total number of libraries that can be returned to you. |
JOBI0750 Format
The JOBI0750 format returns library list information for active jobs only along with additional information about each library. The JOBI0750 format returns the following library information for the active job. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Number of bytes returned |
4 | 4 | BINARY(4) | Number of bytes available |
8 | 8 | CHAR(10) | Job name |
18 | 12 | CHAR(10) | User name |
28 | 1C | CHAR(6) | Job number |
34 | 22 | CHAR(16) | Internal job identifier |
50 | 32 | CHAR(10) | Job status |
60 | 3C | CHAR(1) | Job type |
61 | 3D | CHAR(1) | Job subtype |
62 | 3E | CHAR(2) | Reserved |
64 | 40 | BINARY(4) | Offset to libraries in system library list |
68 | 44 | BINARY(4) | Number of libraries in system library list |
72 | 48 | BINARY(4) | Offset to product libraries |
76 | 4C | BINARY(4) | Number of product libraries |
80 | 50 | BINARY(4) | Offset to current library |
84 | 54 | BINARY(4) | Number of current libraries |
88 | 58 | BINARY(4) | Offset to libraries in user library list |
92 | 5C | BINARY(4) | Number of libraries in user library list |
96 | 60 | BINARY(4) | Length of one library array entry |
See note | See note | Array(*) of CHAR(*) | System library list (See Library Array Entry for format of library array entry.) |
See note | See note | Array(*) of CHAR(*) | Product libraries (See Library Array Entry for format of library array entry.) |
See note | See note | Array(*) of CHAR(*) | Current library (See Library Array Entry for format of library array entry.) |
See note | See note | Array(*) of CHAR(*) | User library list (See Library Array Entry for format of library array entry.) |
Note: The decimal and hexadecimal offsets depend on the number of libraries you have in the various parts of your library lists. The data is left-justified with a blank pad at the end. The array is sequential. It is an array or data structure. See the CL programming topic for the total number of libraries that can be returned. |
Library Array Entry
The library array entry describes the data that is returned for each library entry in the array of libraries on the JOBI0750 format. The name of the library as well as some extended information about the library is returned with this format. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
The fields repeat for each library object returned in the array. | CHAR(10) | Library name | |
CHAR(50) | Library text description | ||
BINARY(4) | Library ASP number | ||
CHAR(10) | Library ASP name | ||
CHAR(*) | Reserved |
JOBI0800 Format
The JOBI0800 format is only valid for active jobs. If the job status has changed to *OUTQ or *JOBQ, the status field is set appropriately, and no information other than the number of bytes returned, the number of bytes available, the qualified job name, and the internal job identifier is returned. If the signal status is 0, not enabled for signals, this format returns zeros or blanks for the attributes.
The JOBI0800 format returns the following job information. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Number of bytes returned |
4 | 4 | BINARY(4) | Number of bytes available |
8 | 8 | CHAR(10) | Job name |
18 | 12 | CHAR(10) | User name |
28 | 1C | CHAR(6) | Job number |
34 | 22 | CHAR(16) | Internal job identifier |
50 | 32 | CHAR(10) | Job status |
60 | 3C | CHAR(1) | Job type |
61 | 3D | CHAR(1) | Job subtype |
62 | 3E | CHAR(2) | Reserved |
64 | 40 | BINARY(4) | Signal status |
68 | 44 | CHAR(8) | Signal blocking mask |
76 | 4C | CHAR(8) | Pending signal set |
84 | 54 | BINARY(4) | Offset to signal monitor data |
88 | 58 | BINARY(4) | Number of signal monitors |
92 | 5C | BINARY(4) | Process ID number |
96 | 60 | Array(*) of CHAR(32) | Signal monitor data (for each signal monitor) |
These fields repeat for each signal monitor. | BINARY(4) | Signal number | |
BINARY(4) | Signal action | ||
BINARY(4) | Default signal action | ||
BINARY(4) | Maximum number of signals retained | ||
BINARY(4) | Current number of pending signals | ||
CHAR(12) | Reserved |
JOBI0900 Format
The JOBI0900 format is only valid for active jobs. If the job status has changed to *OUTQ or *JOBQ, the status field is set appropriately, and no information other than the number of bytes returned, the number of bytes available, the qualified job name, and the internal job identifier is returned. If the number of SQL open cursors is 0 and no SQL statements have ever been issued in the job, this format returns zeros or blanks for the attributes.
Note: Synchronization is not performed when you change or retrieve SQL data. If you try to retrieve SQL data for your own job and your job is not running multithreaded, then the retrieved data should be correct. If, however, you are retrieving SQL data for your own job and your job is running multithreaded or if you are retrieving data for a different job, the SQL data may not be correct because the SQL data is being changed at the same time that you are retrieving it.
The JOBI0900 format returns the following job information. For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Number of bytes returned |
4 | 4 | BINARY(4) | Number of bytes available |
8 | 8 | CHAR(10) | Job name |
18 | 12 | CHAR(10) | User name |
28 | 1C | CHAR(6) | Job number |
34 | 22 | CHAR(16) | Internal job identifier |
50 | 32 | CHAR(10) | Job status |
60 | 3C | CHAR(1) | Job type |
61 | 3D | CHAR(1) | Job subtype |
62 | 3E | CHAR(1) | Server mode for Structured Query Language |
63 | 3F | CHAR(1) | Routine type |
64 | 40 | BINARY(4) | Offset to SQL open cursor data |
68 | 44 | BINARY(4) | Size of SQL open cursor data |
72 | 48 | BINARY(4) | Number of SQL open cursors |
76 | 4C | BINARY(4) | Offset to current SQL statement |
80 | 50 | BINARY(4) | Length of current SQL statement |
84 | 54 | BINARY(4) | Status of current SQL statement |
88 | 58 | BINARY(4) | CCSID of current SQL statement |
92 | 5C | CHAR(18) | Relational Database name |
110 | 6E | CHAR(10) | SQL statement object name |
120 | 78 | CHAR(10) | SQL statement library name |
130 | 82 | CHAR(10) | SQL statement object type |
140 | 8C | CHAR(4) | Reserved |
144 | 90 | BINARY(8) | Cumulative number of SQL cursors - Full Opens |
152 | 98 | BINARY(8) | Cumulative number of SQL cursors - Pseudo Opens |
160 | A0 | BINARY(4) | Offset to current SQL statement name |
164 | A4 | BINARY(4) | Length of current SQL statement name |
168 | A8 | BINARY(4) | SQL current LOB locator count |
172 | AC | BINARY(4) | SQL activation group count |
176 | B0 | BINARY(8) | SQL current descriptor count |
184 | B8 | BINARY(8) | CLI current handle count |
192 | C0 | BINARY(4) | Offset to client accounting string |
196 | C4 | BINARY(4) | Length of client accounting string |
200 | C8 | BINARY(4) | Offset to client application name |
204 | CC | BINARY(4) | Length to client application name |
208 | D0 | BINARY(4) | Offset to client program identifier |
212 | D4 | BINARY(4) | Length to client program identifier |
216 | D8 | BINARY(4) | Offset to client user identifier |
220 | DC | BINARY(4) | Length of client user identifier |
224 | E0 | BINARY(4) | Offset to client workstation name |
228 | E4 | BINARY(4) | Length of client workstation name |
232 | E8 | BINARY(4) | Offset to interface name |
236 | EC | BINARY(4) | Length of interface name |
240 | F0 | BINARY(4) | Offset to interface type |
244 | F4 | BINARY(4) | Length of interface type |
248 | F8 | BINARY(4) | Offset to interface level |
252 | FC | BINARY(4) | Length of interface level |
256 | 100 | BINARY(4) | Number of SQL pseudo closed cursors |
260 | 104 | BINARY(4) | Local port number for server job |
264 | 108 | CHAR(1) | Client IP address for Server job type |
265 | 109 | CHAR(45) | Client IP address for Server job |
310 | 136 | CHAR(10) | Query options library name |
320 | 140 | CHAR(8) | Time-stamp SQL statement started |
328 | 148 | CHAR(28) | Server mode connecting job |
356 | 164 | CHAR(8) | Server mode connected thread |
364 | 16C | BINARY(4) | Number of result sets available in job |
368 | 170 | BINARY(4) | Number of unconsumed result sets available in job |
372 | 174 | BINARY(4) | Offset to routine schema name |
376 | 178 | BINARY(4) | Length of routine schema name |
380 | 17C | BINARY(4) | Offset to routine name |
384 | 180 | BINARY(4) | Length of routine name |
388 | 184 | BINARY(4) | Client port number |
392 | 188 | BINARY(4) | Offset to client host name |
396 | 18C | BINARY(4) | Length of client host name |
* | * | Array(*) of CHAR(96) | SQL open cursor data |
These fields repeat for each SQL open cursor | CHAR(10) | Object name for SQL cursor | |
CHAR(10) | Object library for SQL cursor | ||
CHAR(10) | Object type for SQL cursor | ||
CHAR(18) | SQL cursor name | ||
CHAR(18) | SQL statement name | ||
CHAR(2) | Reserved | ||
BIN(4) | Offset of extended SQL statement name | ||
BIN(4) | Length of extended SQL statement name | ||
BIN(4) | Offset of extended SQL cursor name | ||
BIN(4) | Length of extended SQL cursor name | ||
CHAR(12) | Reserved | ||
See note | CHAR(*) | Current SQL statement | |
See note | CHAR(*) | Extended SQL statement name | |
See note | CHAR(*) | Extended SQL cursor name | |
Note: The decimal and hexadecimal offsets depend on the number of SQL open cursors returned in the array. The maximum length of an SQL statement is 2097152 bytes. |
JOBI1000 Format
The JOBI1000 format is valid for active jobs only. This format returns performance statistics for the active job based on an elapsed time interval. The first call of this format for the specified job returns zeros for each attribute returned. Upon consecutive calls for the specified job, the values returned for each attribute are calculated based on the time that has elapsed since the last reset. The amount of time that has elapsed is returned as part of this format. If the job status has changed to *OUTQ or *JOBQ, the status field is set appropriately, and no information other than the number of bytes returned, the number of bytes available, qualified job name, job type, and the job subtype is returned.
When collecting performance statistics, it is important to provide an adequate time interval. The reported values reflect both the performance of the job that the API is looking at and the performance of the job that the API is running in. For example, you may see percentages greater than 100% because of the way the API interacts with the job that it is sampling.
For details about the fields listed, see Field Descriptions.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Number of bytes returned |
4 | 4 | BINARY(4) | Number of bytes available |
8 | 8 | CHAR(10) | Job name |
18 | 12 | CHAR(10) | User name |
28 | 1C | CHAR(6) | Job number |
34 | 22 | CHAR(16) | Internal job identifier |
50 | 32 | CHAR(10) | Job status |
60 | 3C | CHAR(1) | Job type |
61 | 3D | CHAR(1) | Job subtype |
62 | 3E | CHAR(2) | Reserved |
64 | 40 | BINARY(8), UNSIGNED | Elapsed time |
72 | 48 | BINARY(8), UNSIGNED | Disk I/O count during the elapsed time (job) |
80 | 50 | BINARY(8), UNSIGNED | Disk I/O count during the elapsed time - asynchronous I/O (job) |
88 | 58 | BINARY(8), UNSIGNED | Disk I/O count during the elapsed time - synchronous I/O (job) |
96 | 60 | BINARY(4) | Interactive response time - total during the elapsed time |
100 | 64 | BINARY(4) | Interactive transactions - count during the elapsed time |
104 | 68 | BINARY(4) | Processing unit used - percent during the elapsed time (job) |
108 | 6C | BINARY(4) | Processing unit used for database - percent during the elapsed time (job) |
112 | 70 | BINARY(8), UNSIGNED | Processing unit used - time during the elapsed time (job) |
120 | 78 | BINARY(8), UNSIGNED | Processing unit used for database - time during the elapsed time (job) |
128 | 80 | BINARY(8), UNSIGNED | Lock wait time - time during the elapsed time |
136 | 88 | BINARY(8), UNSIGNED | Page fault count during the elapsed time (job) |
Field Descriptions
Most field descriptions for this API are in Work Management API Attribute Descriptions (WMAttrDesc). Those field descriptions not found in the Work Management API Attribute Descriptions are listed below.
All fields are scoped to the job unless specifically noted. See Considerations for Attribute Scope and Thread Safety for complete details.
ASP group information entry. Specifies information about an auxiliary storage pool (ASP) group.
ASP group name. The name of the auxiliary storage pool (ASP) group. This is the name of the primary ASP in an ASP group or the name of an ASP device description. The following special values may also be returned:
*N | The name of the ASP group cannot be determined. |
CLI current handle count. The number of CLI handles which are active for the job. The limit for a job is 160,000. This count includes CLI statement handles, descriptor handles, environment handles and connection handles.
Client accounting string. The value of the client accounting string. Refer to the sqleseti()--Set Client Information documentation for more details about this Client Information SQL special register value.
Client application name. The value of the client application name. Refer to the sqleseti()--Set Client Information documentation for more details about this Client Information SQL special register value.
Client host name. The host name used by the current client to communicate with the server. A value appears only when the target job corresponds to a connection formed using the TCP/IP protocol.
Client IP address for Server job. The character form of the Client IP address for the database server job. If the target job is not a database server job (QRWTSRVR, QZDASOINIT or QSQSRVR), blanks will be returned. Refer to the Client IP address for server job type field to determine the IP format used by this field.
Client IP address for server job type. Indicates the format of data returned within the Client IP address for server job field. The valid values are:
'0' | No Client IP address is in use. |
'1' | IPv4 format. |
'2' | IPv6 format. |
Client port number. The port number used by the current client to communicate with the server. A value appears only when the target job corresponds to a connection formed using the TCP/IP protocol.
Client program identifier. The value of the client program identifier. Refer to the sqleseti()--Set Client Information API documentation for more details about this Client Information SQL special register value.
Client user identifier. The value of the client user identifier. Refer to the sqleseti()--Set Client Information documentation for more details about this Client Information SQL special register value.
Client workstation name. The value of the client workstation name. Refer to the sqleseti()--Set Client Information documentation for more details about this Client Information SQL special register value.
Cumulative number of SQL cursors - Full Opens. The total number of SQL cursors which have been full opened for the life of the job.
Cumulative number of SQL cursors - Pseudo Opens. The total number of SQL cursors which have been psuedo opened for the life of the job. Psuedo opens are also known as reused SQL cursors.
Extended SQL cursor name. The name of the SQL cursor.
Extended SQL statement name. The name of the SQL statement.
Interface level. The value of the client database interface level in the following form: "VVRRMMFP".
VV - Version
RR - Release
MM - Modification level
FP - Fix pack level (only applicable for certain interfaces)
For example: "05050001".
Interface name. The value of the client database interface name. For example: "System i Access for Windows, DB2/i5OS".
Interface type. The value of the client database interface type. For example: "ODBC".
Length of client accounting string. The length of the client accounting string.
Length of client application name. The length of the client application name.
Length of client program identifier. The length of the client program identifier.
Length of client user identifier. The length of the client user identifier.
Length of client workstation name. The length of the client workstation name.
Length of current SQL statement. The length of the current SQL statement. Zero indicates that a current SQL statement could not be returned. This can occur if an SQL statement has never been issued in the job, if the job is ending, if the program or package that contained the SQL statement no longer exists, or if the API is unable to access the SQL statement.
Length of current SQL statement name. The length of the current SQL statement name.
Length of extended SQL cursor name. The length of the Extended SQL cursor name.
Length of extended SQL statement name. The length of the Extended SQL statement name.
Length of interface level. The length of the interface level.
Length of interface name. The length of the interface name.
Length of interface type. The length of the interface type.
Length of one ASP group information entry. The length of an ASP group information entry. Zero indicates that an ASP group is not being used. Zero is also returned if the job status has changed to *OUTQ.
Length of one library array entry. The length of one entry in a library list array.
Length of routine name. The length of the routine name for the last routine invoked.
Length of routine schema name. The length of the schema name for the last routine invoked.
Length of time zone information. The length of the time zone information.
Library ASP name. The name of the ASP device that contains the library. The following special values may also be returned:
*SYSBAS | The library is located in the system ASP or in a basic user ASP. |
*N | The name of the ASP device cannot be determined. |
Library ASP number. The numeric identifier of the ASP containing the library. The following values may be returned:
1 | The library is located in the system ASP. |
2-32 | The library is located in a basic ASP. |
33-255 | The library is located in an independent ASP. |
-1 | The ASP number cannot be determined. |
Library name. The name of the library object.
Library text description. The text description of the library object. This field is blank if no text description is specified.
Local port number for server job. The local port number for the database server job. If the target job is not a database server job (QRWTSRVR, QZDASOINIT or QSQSRVR), 0 will be returned.
Number of current libraries. The number of current libraries in the library list of the initial thread.
Number of entries in ASP group information. The number of entries in the ASP group information. Zero indicates that an ASP group is not being used. Zero is also returned if the job status has changed to *OUTQ.
Number of libraries in system library list. The number of libraries in the system part of the library list of the initial thread.
Number of libraries in user library list. The number of libraries in the user library list of the initial thread.
Number of product libraries. The number of product libraries in the library list of the initial thread.
Number of result sets available in job. The current count of available result sets for the job.
Number of SQL open cursors. The number of SQL cursors that are currently open for the job.
Number of SQL pseudo closed cursors. The active number of pseudo closed cursors within the job. Pseudo closed cursors are cursors which have been closed by the application, but remain open within the database. A pseudo closed cursor may be reused when the same query is executed many times, resulting in a performance improvement on the open. Conversely, accumulating too many pseudo closed cursors within the job could have a negative impact on the storage footprint of the job.
Number of unconsumed result sets available in job. The cumulative count of unconsumed result sets that were discarded for the job.
Number of signal monitors. The number of signal monitors that are present for the job.
Offset to ASP group information. The offset from the start of the format to the start of the ASP group information. Zero indicates that an ASP group is not being used. Zero is also returned if the job status has changed to *OUTQ.
Offset to client accounting string. The offset from the start of the format to the start of the client accounting string.
Offset to client application name. The offset from the start of the format to the start of the client application name.
Offset to client program identifier. The offset from the start of the format to the start of the client program identifier.
Offset to client user identifier. The offset from the start of the format to the start of the client user identifier.
Offset to client workstation name. The offset from the start of the format to the start of the client workstation name.
Offset to current library. The offset from the start of the format to the start of the current library.
Offset to current SQL statement. The offset from the start of the format to the start of the current SQL statement.
Offset to current SQL statement Name. The offset from the start of the format to the start of the current SQL statement name.
Offset to extended SQL cursor name. The offset from the start of the format to the start of the Extended SQL cursor name.
Offset to extended SQL statement name. The offset from the start of the format to the start of the Extended SQL statement name.
Offset to interface level. The offset from the start of the format to the start of the interface level.
Offset to interface name. The offset from the start of the format to the start of the interface name.
Offset to interface type. The offset from the start of the format to the start of the interface type.
Offset to libraries in system library list. The offset from the start of the format to the start of the system library list.
Offset to libraries in user library list. The offset from the start of the format to the start of the user library list.
Offset to product libraries. The offset from the start of the format to the start of the product libraries.
Offset to routine name. The offset from the start of the format to the start of the routine name.
Offset to routine schema name. The offset from the start of the format to the start of the routine schema name.
Offset to signal monitor data. The offset from the start of the format to the start of the signal monitor data.
Offset to SQL open cursor data. The offset from the start of the format to the start of the SQL open cursor data.
Offset to time zone information. The offset from the start of the format to the start of the time zone information.
Prestart job maximum number of uses. The maximum number of times the prestart job can be used before it is ended. This is the same as the MAXUSE parameter on the Add Prestart Job Entry (ADDPJE) and Change Prestart Job Entry (CHGPJE) commands. If the job is not active or the job is not a prestart job, a value of zero is returned. The following values may be returned:
0 | The job is not active or the job is not a prestart job. |
1-1000 | The maximum number of uses. |
-1 | There is no maximum number of uses. This is the same as MAXUSE(*NOMAX). |
Prestart job reuse count. The number of times the prestart job has been used. The Prestart job reuse count is incremented between requests (ie. connections to a client). When the Prestart job reuse count exceeds the Prestart job maximum number of uses, the job is ended. If the job is not active or the job is not a prestart job, a value of zero is returned.
Query options library name. The library name of the query options file (QAQQINI) in use by this job. This field is set to blanks if no query options file is being used by the job. To understand how the query options file can be used, see the Controlling queries dynamically with the query options file QAQQINI topic.
Routine name. The name for the last routine invoked.
Routine schema name. The schema name for the last routine invoked.
Routine type. The type of the last routine that was invoked.
P | Procedure |
F | Function |
Server mode connected thread. If the job name of the target job for the QUSRJOBI() call is not QSQSRVR, then blanks will be returned for the Server mode connected thread. If the job name is QSQSRVR and the server mode job is in use, the thread identifier of the last thread to use this connection will be returned. When the Status of current SQL statement indicates that the SQL statement is not active, this field could refer to an application thread identifier which no longer exists.
Server mode connecting job. The qualified job name of the job which established the SQL Server Mode connection. If the job name of the target job for the QUSRJOBI() call is not QSQSRVR, then blanks will be returned for the Server mode connecting job. If the job name is QSQSRVR, then the qualified job name of the connecting job will be returned. This job name will be of the form 'xxxxxxxxxx/yyyyyyyyyy/zzzzzz', where x = job name, y = user name and z = job number. The name will be left justified, will not contain blanks within the name and will be padded with blanks on the right.
Size of SQL open cursor data. The size of a single entry for a given SQL cursor for the job. This information consists of the object name, object library, object type, SQL cursor name, and SQL statement name.
SQL activation group count. The number of activation groups, current and ended, that have executed SQL statements.
SQL current descriptor count. The number of SQL descriptors which are active for the job.
SQL cursor name. The name of the SQL cursor. If the name is longer than 18 characters, SQL cursor name will be set to blanks and the Length of Extended SQL cursor name and Offset to Extended SQL cursor name will be used to return the cursor name.
SQL current LOB locator count. The number of LOB locators which are active for the job. The SQL limit for a job is 16,000,000 unless the job is QSQSRVR, in which case it has a limit of 209,000.
SQL statement name. The name of the SQL statement. If the name is longer than 18 characters, SQL statement name will be set to blanks and the Length of Extended SQL statement name and Offset to Extended SQL statement name will be used to return the statement name.
SQL statement object name. The name of the object which contains the last SQL statement executed in the job. When the current SQL statement belongs to an SQL User Defined Function or an SQL Stored Procedure, the object name will be the external program name. The name will contain blanks when the SQL statement name is blank or when the SQL statement does not exist within a permanent object.
SQL statement library name. The library name for the SQL statement object. The name will contain blanks when the SQL statement name is blank or when the SQL statement does not exist within a permanent object.
SQL statement object type. The object type will be set when the SQL statement object name is not blanks. The following values may be returned:
*PGM | The current SQL statement resides within a program. |
*SRVPGM | The current SQL statement resides within a service program. |
*SQLPKG | The current SQL statement resides within an SQL package. |
Time zone information. Specifies information about the time zone description.
Time-stamp SQL statement started. The date and time the job began to run the SQL statement. This is in system time-stamp format. When the Status of current SQL statement indicates that the SQL statement is not active, this field will contain hex zeros. See Convert Date and Time Format (QWCCVTDT) API for more information about using this time-stamp format.
Comparing Job Type and Subtype with the Work with Active Job Command
The following table compares the job type and job subtype fields returned by the QUSRJOBI API to the type field on the Work with Active Job (WRKACTJOB) command.
WRKACTJOB and QUSRJOBI API Comparison | ||
---|---|---|
Job Type Field | Job Type | Job Subtype |
ASJ (Autostart) | A | blank |
BCH (Batch) | B | blank |
BCI (Batch immediate) | B | D |
EVK (Started by a program start request) | B | E |
INT (Interactive) | I | blank |
M36 (System i™ Advanced 36® machine server) | B | F |
MRT (Multiple requester terminal) | B | T |
PJ (Prestart job) | B | J |
PDJ (Print driver job) | W | P |
RDR (Reader) | R | blank |
SYS (System) | S or X | blank |
SBS (Subsystem monitor) | M | blank |
WTR (Writer) | W | blank |
blank (Alternative user subtype--not an active job) | B | U |
Usage Notes
Considerations for Attribute Scope and Thread Safety: This API is primarily intended for retrieving job attributes, but it also retrieves some attributes for the initial thread.
The Scope column of Attribute Scope and Thread Safety table that follows shows whether the attribute is scoped to the job or to the thread. If any attributes currently scoped to the job are moved to the thread level in the future, then this API will be changed to retrieve the value for the initial thread. This API cannot be used to retrieve attributes for a secondary thread.
The Threadsafe Access column of this table indicates whether retrieving a copy of the attribute is considered to be a threadsafe operation. When retrieving an attribute is not threadsafe, a partially updated value can be returned. When retrieving an attribute is threadsafe, the returned value is the value that was in effect at the time the value was retrieved but, by the time the returned value is used, the current value and the returned value could be different.
Yes: For this particular API, Yes indicates that an attribute can always be retrieved and can be considered correct, which includes thread safety. The API may be called from an initial or secondary thread to retrieve the attributes of the current job or a different job. The job whose attributes are being retrieved may be either single threaded or multithreaded.
Conditional; reason 1, same job: An attribute marked with this value can be safely retrieved from either an initial thread or a secondary thread, but can only be considered to be completely correct when retrieving one's own attribute. When retrieving the attribute from another job, the value retrieved may not be completely correct if the other job is changing the attribute while it is being retrieved.
Conditional; reason 2, initial thread: An attribute marked with this value can only be considered to be completely correct when retrieving one's own attribute and you are running in the initial thread. When retrieving the attribute from another job, you may be running in either an initial thread or a secondary thread, but in either case the value retrieved may not be completely correct if the other job is changing the attribute while it is being retrieved.
Conditional; reason 3, single threaded: An attribute marked with this value can only be considered to be completely correct when retrieving one's own attribute and you are running single threaded. When retrieving the attribute from another job, you may be running in either an initial thread or a secondary thread, but in either case the value retrieved may not be completely correct if the other job is changing the attribute while it is being retrieved.
Conditional; reason 4, active job: An attribute marked with this value can only be considered to be completely correct when retrieving the attribute of an active job. The API may be called from an initial or secondary thread to retrieve the attributes of the current job or a different job. The job whose attributes are being retrieved may be either single threaded or multithreaded. However, if the job whose attribute is being retrieved is on a job queue, the value retrieved may not be completely correct if the attribute is being changed while it is being retrieved.
Conditional; reason 5, not during prestart receive: An attribute marked with this value can be considered to be correct with the following exception. The value may not be completely correct if the attribute is being retrieved for a prestart job while the prestart job is receiving a new request. The API may be called from an initial or secondary thread to retrieve the attributes of the current job or a different job. The job whose attributes are being retrieved may be either single threaded or multithreaded.
No: An attribute marked with this value is not threadsafe, nor is it safe for retrieval when running single threaded. The value retrieved may not be completely correct if the value is being changed while it is being retrieved.
N/A; do not use: Thread safety is not applicable (N/A). The user return code field is the most recent return code set by any thread within the job. Many operating system functions run C code and change the value of the user return code. Changes to this field occur at times that cannot be predicted or controlled by user programming, even when the job is single-threaded. To receive a value returned by a called program, it is better to provide a parameter to receive that value than to rely on this job-scoped user return code field.
Attribute Scope and Thread Safety | ||
---|---|---|
Attribute | Scope | Threadsafe Access |
Active job status | Initial thread | No |
Active job status for jobs ending | Initial thread | No |
Allow multiple threads | Initial thread | Yes |
ASP group information entry | Initial thread | Yes |
Break message handling | Job | Yes |
Cancel key | Job | Yes |
CCSID of current SQL statement | Job | No |
Character identifier control | Job | Yes |
CLI current handle count | Job | No |
Client accounting string | Job | No |
Client application name | Job | No |
Client IP address - IPv4 | Initial thread | Conditional; reason 2 |
Client program identifier | Job | No |
Client user identifier | Job | No |
Client workstation name | Job | No |
Coded character set ID | Job | Yes |
Completion status | Job | Yes |
Country or region ID | Job | Yes |
Cumulative number of SQL cursors - Full Opens | Job | No |
Cumulative number of SQL cursors - Pseudo Opens | Job | No |
Current library | Initial thread | Yes |
Current library existence | Initial thread | Yes |
Current number of pending signals | Job | Yes |
Current system pool identifier | Initial thread | Yes |
Current user profile | Initial thread | Conditional; reason 2 |
Date and time job became active | Job | Yes |
Date and time job ended | Job | Yes |
Date and time job entered system | Job | Yes |
Date and time job is scheduled to run | Job | Yes |
Date and time the job was put on this job queue | Job | No |
Date format | Job | Yes |
Date separator | Job | Yes |
Day of week | Job | Yes |
DBCS-capable | Job | Yes |
DDM conversation handling | Job | Yes |
Decimal format | Job | Yes |
Default coded character set identifier | Job | Yes |
Default signal action | Job | Yes |
Default wait | Job | Yes |
Device name | Job | Yes |
Device recovery action | Job | Yes |
Disk I/O count during the elapsed time - asynchronous I/O (job) | Job | Yes |
Disk I/O count during the elapsed time - synchronous I/O (job) | Job | Yes |
Disk I/O count during the elapsed time (job) | Job | Yes |
Elapsed time | Job | Yes |
End severity | Job | Yes |
End status | Job | Yes |
Exit key | Job | Yes |
Function name | Initial thread | No |
Function type | Initial thread | No |
Group profile name | Initial thread | Conditional; reason 2 |
Group profile name - supplemental | Initial thread | Conditional; reason 2 |
Inquiry message reply | Job | Yes |
Interactive response time - total during the elapsed time | Job | Yes |
Interactive transactions - count during the elapsed time | Job | Yes |
Interface level | Job | No |
Interface name | Job | No |
Interface type | Job | No |
Internal job identifier | Job | Yes |
Job accounting code | Job | Conditional; reason 1 |
Job date | Job | Yes |
Job description library ASP device name | Job | Yes |
Job description library name | Job | Yes |
Job description name | Job | Yes |
Job end reason | Job | Yes |
Job local time | Job | Yes |
Job log output | Job | Yes |
Job log pending | Job | Yes |
Job message queue full action | Job | Yes |
Job message queue maximum size | Job | Yes |
Job name | Job | Yes |
Job number | Job | Yes |
Job queue library ASP device name | Job | Conditional; reason 3 |
Job queue library name | Job | Conditional; reason 3 |
Job queue name | Job | Conditional; reason 3 |
Job queue priority | Job | Yes |
Job status | Job | Yes |
Job subtype | Job | Yes |
Job switches | Job | Conditional; reason 4 |
Job type | Job | Yes |
Job type - enhanced | Job | Yes |
Job user identity | Job | Yes |
Job user identity setting | Job | Yes |
Language ID | Job | Yes |
Lock wait time - time during the elapsed time | Job | Yes |
Logging level | Job | Yes |
Logging of CL programs | Job | Yes |
Logging severity | Job | Yes |
Logging text | Job | Yes |
Maximum number of signals retained | Job | Yes |
Maximum processing unit time allowed | Routing step | Yes |
Maximum temporary storage allowed, in kilobytes, if less than 2,147,483,647 | Routing step | Yes |
Maximum temporary storage allowed, in megabytes | Routing step | Yes |
Maximum threads | Job | Yes |
Memory pool name | Job | Yes |
Message key, when active job waiting for a message | Initial thread | Yes |
Message queue library ASP device name, when active job waiting for a message | Initial thread | Yes |
Message queue library name, when active job waiting for a message | Initial thread | Yes |
Message queue name, when active job waiting for a message | Initial thread | Yes |
Message reply | Job | Yes |
Mode name | Job | Yes |
Number of auxiliary I/O requests | Job | Yes |
Number of auxiliary I/O requests, if less than 2,147,483,647 | Job | Yes |
Number of database lock waits | Initial thread | Yes |
Number of interactive transactions | Initial thread | Yes |
Number of internal machine lock waits | Initial thread | Yes |
Number of libraries in SYSLIBL | Initial thread | Yes |
Number of libraries in USRLIBL | Initial thread | Yes |
Number of nondatabase lock waits | Initial thread | Yes |
Number of product libraries | Initial thread | Yes |
Number of signal monitors | Job | Yes |
Number of SQL open cursors | Job | No |
Number of SQL pseudo closed cursors | Job | No |
Object library for SQL cursor | Job | No |
Object name for SQL cursor | Job | No |
Object type for SQL cursor | Job | No |
Output queue library name | Job | Conditional; reason 3 |
Output queue name | Job | Conditional; reason 3 |
Output queue priority | Job | Yes |
Page fault count during the elapsed time (job) | Job | Yes |
Peak temporary storage used, in megabytes | Job | Yes |
Pending signal set | Job | Yes |
Print key format | Job | Yes |
Print text | Job | Conditional; reason 3 |
Printer device name | Job | Conditional; reason 3 |
Process ID number | Job | Yes |
Processing unit time used - total for the job | Job | Yes |
Processing unit time used for database - total for the job | Job | Yes |
Processing unit time used, if less than 2,147,483,647 milliseconds | Job | Yes |
Processing unit used - percent during the elapsed time (job) | Job | Yes |
Processing unit used - time during the elapsed time (job) | Job | Yes |
Processing unit used for database - percent during the elapsed time (job) | Job | Yes |
Processing unit used for database - time during the elapsed time (job) | Job | Yes |
Product libraries | Initial thread | Yes |
Product return code | Job | Yes |
Program return code | Job | No |
Purge | Job | Yes |
Relational Database name | Job | No |
Response time total | Initial thread | Yes |
Run priority (job) | Job | Yes |
Server mode for Structured Query Language | Job | No |
Server mode connected thread | Job | Yes |
Server mode connecting job | Job | Yes |
Server type | Job | Conditional; reason 3 |
Signal action | Job | Yes |
Signal blocking mask | Initial thread | Yes |
Signal monitor data | Job | Yes |
Signal number | Job | Yes |
Signal status | Job | Yes |
Signed-on job | Job | Yes |
Size of SQL open cursor data | Job | No |
Sort sequence | Job | Conditional; reason 3 |
Sort sequence library | Job | Conditional; reason 3 |
Special environment | Job | Yes |
Spooled file action | Job | Yes |
SQL activation group count | Job | No |
SQL current descriptor count | Job | No |
SQL current LOB locator count | Job | No |
SQL cursor name | Job | No |
SQL open cursor data | Job | No |
SQL statement library name | Job | No |
SQL statement name | Job | No |
SQL statement object name | Job | No |
SQL statement object type | Job | No |
Status message handling | Job | Yes |
Status of current SQL statement | Job | No |
Status of job on the job queue | Job | Yes |
Submitter's job name | Job | Yes |
Submitter's job number | Job | Yes |
Submitter's message queue library name | Job | Yes |
Submitter's message queue name | Job | Yes |
Submitter's user name | Job | Yes |
Subsystem description library name | Job | Yes |
Subsystem description name | Job | Yes |
System library list | Initial thread | Yes |
System pool identifier | Job | Yes |
Temporary storage used, in kilobytes, if less than 2,147,483,647 | Job | Yes |
Temporary storage used, in megabytes | Job | Yes |
Thread count | Job | Yes |
Time separator | Job | Yes |
Time slice | Job | Conditional; reason 4 |
Time-slice end pool | Job | Yes |
Time spent on database lock waits | Initial thread | Yes |
Time spent on internal machine lock waits | Initial thread | Yes |
Time spent on nondatabase lock waits | Initial thread | Yes |
Time zone current abbreviated name | Job | Yes |
Time zone current full name | Job | Yes |
Time zone current message identifier | Job | Yes |
Time zone current offset | Job | Yes |
Time zone Daylight Saving Time indicator | Job | Yes |
Time zone description name | Job | Yes |
Time zone message file library | Job | Yes |
Time zone message file name | Job | Yes |
Unit of work ID | Job | Conditional; reason 5 |
User library list | Initial thread | Yes |
User name | Job | Yes |
User return code | Job | N/A; do not use |
Error Messages
Message ID | Error Message Text |
---|---|
CPF24B4 E | Severe error while addressing parameter list. |
CPF3CF1 E | Error code parameter not valid. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF3C19 E | Error occurred with receiver variable specified. |
CPF3C20 E | Error found by program &1. |
CPF3C21 E | Format name &1 is not valid. |
CPF3C24 E | Length of the receiver variable is not valid. |
CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
CPF3C51 E | Internal job identifier not valid. |
CPF3C52 E | Internal job identifier no longer valid. |
CPF3C53 E | Job &3/&2/&1 not found. |
CPF3C54 E | Job &3/&2/&1 currently not available. |
CPF3C55 E | Job &3/&2/&1 does not exist. |
CPF3C57 E | Not authorized to retrieve job information. |
CPF3C58 E | Job name specified is not valid. |
CPF3C59 E | Internal identifier is not blanks and job name is not *INT. |
CPF3C90 E | Literal value cannot be changed. |
CPF9820 E | Not authorized to use library &1. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V1R3