Retrieve Job Information (QUSRJOBI) API


  Required Parameter Group:


  Optional Parameter Group 1:


  Optional Parameter Group 2:


  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 SQL Administrator function of IBM i through Application Administration in System i Navigator. The Change Function Usage Information (CHGFCNUSG) command, with a function ID of QIBM_DB_SQLADM, can also be used to change the list of authorized users.

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:

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:


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:


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.

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.



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.



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.



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.



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.



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.



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.



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.



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.



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.



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.



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.



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.



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.



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.



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:

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:

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:

Library ASP number. The numeric identifier of the ASP containing the library. The following values may be returned:

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.

Start of changePrestart 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:

Start of changePrestart 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. End of change

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.

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:

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.



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.



Error Messages



API introduced: V1R3

[ Back to top | >Work Management APIs | APIs by category ]