Change Job (QWTCHGJB) API

The Change Job (QWTCHGJB) API changes some of the attributes of a job or thread. The attributes changed are determined by the job change information parameter.

The current value of most of the job attributes can be retrieved with the List Job (QUSLJOB) API, the Open List of Jobs (QGYOLJOB) API, the Retrieve Current Attributes (QWCRTVCA) API, the Retrieve Job Information (QUSRJOBI) API or the Retrieve Thread Attributes (QWTRTVTA) API.

If an error occurs, the error code will have a general failure error and the specific error will need to be retrieved out of the job message queue of the job that issued this API call.

The QWTCHGJB API changes a list of attributes similar to the attributes changed with the Change Job (CHGJOB) command.

Authorities and Locks

Job Authority

The API must be called from within the job that is being changed, 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 that is being changed. Otherwise, the caller of the API must be running under a user profile that has job control (*JOBCTL) special authority.

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.

Job control (*JOBCTL) special authority is needed for the following attributes to be changed:

• Default wait time
• Purge
• Run priority
• Run priority (thread)
• Time slice
• Time slice end pool

Command Authority

*USE authority to the Change Accounting Code (CHGACGCDE) command is needed to change the job accounting code attribute.

Object Authority

If changing the job queue, *USE authority is required for the object, and *EXECUTE authority is required for the library. If changing the output queue, *READ authority is required for the object, and *EXECUTE authority is required for the library. In addition, the caller must be authorized to the output queue currently associated with the job that is being changed. If changing the sort sequence table, *USE authority is required for the object, and *EXECUTE authority is required for the library.

If using the JOBC0300 format to change attributes that are retrieved from the job description, *USE authority is required for the job description and *EXECUTE authority is required for the library. If changing the ASP group information, *USE authority is required for all ASP devices in the ASP group. If changing the current library or the initial library list, *USE authority is required for the libraries.

Required Parameter Group

Qualified job name

INPUT; CHAR(26)

The name of the job for which the attributes are to be changed. If this value is *INT, the internal job identifier will be used. The qualified job name has three parts:

Job name	CHAR(10). A specific job name or one of the following special values: * The job or thread in which this program is running. The rest of the qualified job name parameter must be blank. This special value must be used when using the JOBC0200 or JOBC0300 format. *INT The internal job identifier locates the job. The user name and job number must be blank. This is only valid for the JOBC0100 format. *THREAD The job information is specified in the Job or thread identification information parameter. This special value must be used when using the JOBC0400 format. The user name, job number, and internal job identifier must be blank when using *THREAD. This is valid for the JOBC0400 format only.
User name	CHAR(10). A specific user profile name, or blanks when the job name is a special value.
Job number	CHAR(6). A specific job number, or blanks when the job name is a special value.

Internal job identifier

INPUT; CHAR(16)

The internal identifier for the job. The QUSLJOB API creates this identifier. If you do not specify *INT for the job name parameter, this parameter must be blanks. With this parameter, the system can locate the job more quickly than with a fully qualified job name.

Format name

INPUT; CHAR(8)

The format of the list of job or thread attributes to be changed. You must use one of the following format names:

JOBC0100	Basic change job list. To be used when changing the attributes of your job or the attributes of another job. This format will not change any specific attributes of a thread. This format will function the same way that the CHGJOB command works.
JOBC0200	Basic change job list for changing the attributes of your own thread. The special value of '*' must be used for the job name. See Field Descriptions for Valid Keys for the scope of each of the valid key fields. If no scope is mentioned, the attribute is scoped to the job. Note: The scope of selected attributes may change over time. Currently there are only a few attributes that are scoped to the thread. The attributes that are not scoped to the thread will be updated at the job level. This will affect all threads running under this job. As attributes become scoped to the thread, attributes changed with this format will then be changed for the current thread and will not affect other threads.
JOBC0300	Change select attributes to user profile values. This format is intended to be used after a swap user profile. The special value of '*' must be used for the job name. This format will be functionally similar to the Change Prestart Job (CHGPJ) command. See Field Descriptions for Valid Keys for the scope of each of the valid key fields. If no scope is mentioned, the attribute is scoped to the job. Note: The attributes for a thread will be updated at the job level if the specific attributes are not currently defined at the thread level. Selected attributes may be moved to the thread level in a later release.
JOBC0400	Change select attributes of a specific thread. The special value of '*THREAD' must be used for the job name.

Job change information

INPUT; CHAR(*)

The information for the job that you want to change. The information must be in the following format:

Number of variable length records

BINARY(4). The total number of all the variable length records. If this value is less than 1, an error message is returned.

Variable length records.

The attributes of the job to change and the data used for the change. For the specific format of the variable length record, see Formats for Variable Length Record.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Optional Parameter Group

Job or thread identification information

INPUT; CHAR(*)

The information that is used to identify the thread within a job for which specified attributes are to be changed. See Format of job or thread identification information for details.

Format of job or thread identification information

INPUT; CHAR(8)

The format of the job or thread identification information. The possible format names are:

JIDF0100	See Format of job or thread identification information for details on the job identification information.
JIDF0200	See Format of job or thread identification information for details on the job identification information.

Note: If the thread handle is available, Format JIDF0200 provides a faster method of accessing a thread that is not the current thread than Format JIDF0100.

Formats for Variable Length Record

The following tables define the format for the variable length records.

JOBC0100, JOBC0200 and JOBC0400 Format: The layout of the JOBC0100, JOBC0200 and JOBC0400 format is the same layout as the information returned with the List Job (QUSLJOB) API.

JOBC0300 Format: The JOBC0300 format is for changing attributes to values specified in either the current user profile or the initial user profile.

If the length of the data is longer than the key field's data length, the data will be truncated at the right. No message will be issued.

If the length of the data is smaller than the key field's data length, the data will be padded with blanks at the right. No message will be issued.

It is not an error to specify a key more than once. If duplicate keys are specified, the last specified value for that key is used.

Each variable length record must be 4-byte aligned. If not, unpredictable results may occur.

Field Descriptions for JOBC0100, JOBC0200, JOBC0300 and JOBC0400 Formats

Data. The data for the attribute that is to be changed. The data for the JOBC0100, JOBC0200, JOBC0300 and JOBC0400 formats is defined in the key list section.

Key. The key for the attribute to be changed. See Valid Keys for the list of valid keys.

Length of data. The length of the data for the key field.

Length of attribute information. The total length of input information for this attribute. This value is used to increment to the next attribute in the list.

Reserved. An ignored field. This field must be blanks.

Type of data. The type of input data. This field is provided to maintain the same format layout that is used in the List Job (QUSLJOB) API. This field will not cause any conversion to occur.

Valid Keys

The following table contains a list of the valid keys for the JOBC0100 formats. See Field Descriptions for Valid Keys for the descriptions of the valid key fields.

Key	Type	Description
0201	CHAR(10)	Break message handling
0302	BINARY(4)	Coded character set ID
0303	CHAR(8)	Country or region ID
0311	CHAR(10)	Character identifier control
0318	CHAR(15)	Client IP address - IPv4 (job)
0405	CHAR(4)	Date format
0406	CHAR(1)	Date separator
0408	CHAR(5)	DDM conversation handling
0409	BINARY(4)	Default wait
0410	CHAR(13)	Device recovery action
0413	CHAR(8)	Decimal format
0901	CHAR(10)	Inquiry message reply
1001	CHAR(15)	Job accounting code
1002	CHAR(7)	Job date
1004	CHAR(20)	Job queue name - qualified
1005	CHAR(2)	Job queue priority
1006	CHAR(8)	Job switches
1007	CHAR(10)	Job message queue full action
1018	CHAR(10)	Job log output
1201	CHAR(8)	Language ID
1202	CHAR(1)	Logging level
1203	CHAR(10)	Logging of CL programs
1204	BINARY(4)	Logging severity
1205	CHAR(7)	Logging text
1501	CHAR(20)	Output queue name - qualified
1502	CHAR(2)	Output queue priority
1601	CHAR(10)	Print key format
1602	CHAR(30)	Print text
1603	CHAR(10)	Printer device name
1604	CHAR(4)	Purge
1802	BINARY(4)	Run priority (job)
1901	CHAR(20)	Sort sequence table - qualified
1902	CHAR(10)	Status message handling
1911	CHAR(30)	Server type
1920	CHAR(10)	Schedule date
1921	CHAR(8)	Schedule time
1922	CHAR(1)	Server mode for Structured Query Language
1982	CHAR(10)	Spooled file action
2001	CHAR(1)	Time separator
2002	BINARY(4)	Time slice
2003	CHAR(10)	Time-slice end pool

The following table contains a list of the valid keys for the JOBC0200 formats. See Field Descriptions for Valid Keys for the descriptions of the valid key fields.

Key	Type	Description
0201	CHAR(10)	Break message handling
0302	BINARY(4)	Coded character set ID
0303	CHAR(8)	Country or region ID
0311	CHAR(10)	Character identifier control
0318	CHAR(15)	Client IP address - IPv4 (job)
0405	CHAR(4)	Date format
0406	CHAR(1)	Date separator
0408	CHAR(5)	DDM conversation handling
0409	BINARY(4)	Default wait
0410	CHAR(13)	Device recovery action
0413	CHAR(8)	Decimal format
0901	CHAR(10)	Inquiry message reply
1001	CHAR(15)	Job accounting code
1002	CHAR(7)	Job date
1004	CHAR(20)	Job queue name - qualified
1005	CHAR(2)	Job queue priority
1006	CHAR(8)	Job switches
1007	CHAR(10)	Job message queue full action
1018	CHAR(10)	Job log output
1201	CHAR(8)	Language ID
1202	CHAR(1)	Logging level
1203	CHAR(10)	Logging of CL programs
1204	BINARY(4)	Logging severity
1205	CHAR(7)	Logging text
1501	CHAR(20)	Output queue name - qualified
1502	CHAR(2)	Output queue priority
1601	CHAR(10)	Print key format
1602	CHAR(30)	Print text
1603	CHAR(10)	Printer device name
1604	CHAR(4)	Purge
1802	BINARY(4)	Run priority (job)
1804	BINARY(4)	Run priority (thread)
1901	CHAR(20)	Sort sequence table - qualified
1902	CHAR(10)	Status message handling
1911	CHAR(30)	Server type
1920	CHAR(10)	Schedule date
1921	CHAR(8)	Schedule time
1922	CHAR(1)	Server mode for Structured Query Language
1982	CHAR(10)	Spooled file action
2001	CHAR(1)	Time separator
2002	BINARY(4)	Time slice
2003	CHAR(10)	Time-slice end pool

The following table contains a list of the valid keys for the JOBC0300 format. See Field Descriptions for Valid Keys for the descriptions of the valid key fields.

The following table contains a list of the valid keys for the JOBC0400 format. See Field Descriptions for Valid Keys for the descriptions of the valid key fields.

Field Descriptions for Valid Keys

All keys for JOBC0300 format. All the keys that are valid for the JOBC0300 format will be changed. The list of keys is subject to change at a later time. If other attributes are added to this key in the future, no change will be needed for them to take effect. If this key (2701) is specified, no other keys can be specified. Even though specifying this key is similar to specifying a list of all the keys that are valid for the JOBC0300 format, the error handling is different. Errors encountered when changing some of the attributes will not cause the change request to fail, although a diagnostic message may be sent. Errors with ASP group information (key 0104), Current library (key 0310), and Initial library list (key 0910) are considered critical and will stop the change request. In general, errors that would prevent a job from starting will cause the change request to fail. If multiple threads are active, attributes that cannot be changed in a safe manner will be ignored and a diagnostic message will be sent. See the Usage Notes for a list of attributes that can be changed in a safe manner. The following keys will be changed by this key:

The attributes that can be set from the locale (coded character set ID and sort sequence table) based on the locale job attributes field (that is retrieved out of the same user profile specified on the locale field) take precedence over the values that are retrieved from the user profile.

This key is valid for the JOBC0300 format only. The possible values are:

ASP group information. The name of the auxiliary storage pool (ASP) group that is associated with this thread. The ASP group name is the name of the primary ASP device within the ASP group. The libraries in the independent ASPs in the new ASP group plus the libraries in the system ASP (ASP number 1) and basic user ASPs (ASP numbers 2-32) form the library name space and all libraries in the library list of this thread are required to be in the new library name space. Therefore, when the ASP group is updated, the libraries in the system part of the library list, the product libraries, the current library and the libraries in the user part of the library list will also be updated.

The libraries currently in the system part of the library list that are found in the system ASP or any configured basic user ASP are used as the new system part of the library list. The product libraries that are found in the system ASP or any configured basic user ASP are used as the new product libraries. If the current library is being changed (either with key 0310 or key 2701), the value specified will be used. Otherwise, the library name in the current library entry of the library list is used as the new current library if the library is found in the system ASP or any configured basic user ASP. If the library name in the current entry is not found in the system ASP or any basic user ASP, the current library entry will be removed from the library list. If the user part of the library list is being changed (either with key 0910 or key 2701), the value specified will be used. Otherwise, the libraries currently in the user part of the library list that are found in the system ASP or any configured basic user ASP are used as the new user part of the library list.

This key is valid for the JOBC0300 format only. The following values are possible:

Break message handling. How this job handles break messages. This key isvalid for the JOBC0100 and JOBC0200 formats only . The possible values are:

Character identifier control. The character identifier control for the job. This attribute controls the type of CCSID conversion that occurs for display files, printer files, and panel groups. The *CHRIDCTL special value must be specified on the CHRID command parameter on the create, change, or override command for display files, printer files, and panel groups before this attribute will be used.

The possible values for the JOBC0100 and JOBC0200 formats are:

The possible values for the JOBC0300 format are:

Client IP address - IPv4 (job). The IPv4 address of the client for which the thread of this server is servicing currently. This key is valid for the JOBC0200 format only. A value of blanks indicates that the thread is not currently servicing a client. A value of hexadecimal zeros is not allowed. An address is expressed in standard dotted-decimal form www.xxx.yyy.zzz; for example, 130.99.128.1. This field is not required to be an IP address. A change to this attribute in a secondary thread is possible, however, it is essentially meaningless as only the attribute for the inital thread can be retrieved using the Retrieve Job Information (QUSRJOBI) API. For further information on retrieving the Client IP address - IPv4 or IPv6 that has been implicity set by the operating system, see the Retrieve Thread Attribute (QWTRTVTA) API.

Coded character set ID. The coded character set identifier used for this job.

The possible values for the JOBC0100 and JOBC0200 formats are:

The possible values for the JOBC0300 format are:

Country or region ID. The country or region identifier associated with this job.

The possible values for the JOBC0100 and JOBC0200 formats are:

The possible values for the JOBC0300 format are:

Current library. The name of the current library that is associated with this thread. This key is valid for the JOBC0300 format only. The following values are possible:

Date format. The format that the date is presented in. This key is only valid for the JOBC0100 and JOBC0200 formats. The following values are possible:

Date separator. The value used to separate days, months, and years when presenting a date. This key is valid for the JOBC0100 and JOBC0200 formats only. The following values are possible:

DDM conversation handling. Specifies whether the connections using distributed data management (DDM) protocols remain active when they are not being used. The connections include APPC conversations, active TCP/IP connections or Opti-Connect connections. The DDM protocols are used in Distributed Relational Database Architecture (DRDA) applications, DDM applications, or DB2 Multisystem applications. This key is only valid for the JOBC0100 and JOBC0200 formats. The following values are possible:

Decimal format. The type of zero suppression and the decimal point character. This key is only valid for the JOBC0100 and JOBC0200 formats. The following values are possible:

Default wait. The default maximum time (in seconds) that a thread in the job waits for a system instruction, such as a LOCK machine interface (MI) instruction, to acquire a resource. This default wait time is used when a wait time is not otherwise specified for a given situation. Normally, this is the amount of time the user is willing to wait for the system before the request is ended. If the job consists of multiple routing steps, a change to this attribute during a routing step does not apply to subsequent routing steps. The valid range is 1 through 9999999. A value of -1 specifies to change to no maximum wait time. This key is valid for the JOBC0100 and JOBC0200 formats only.

Device recovery action. The action taken for interactive jobs when an I/O error occurs for the job's requesting program device. This key is valid for the JOBC0100 and JOBC0200 formats only. The possible values are:

Home directory. The name of the home directory for the integrated file system that is associated with this thread. If the home directory associated with this thread was retrieved from the same user profile that is being specified by either *INLUSR or *CURUSR, then the home directory will not be changed for this thread, even if that user profile's home directory has been changed. If you change the home directory, the job's current working directory will not change. This key is valid for the JOBC0300 format only. The following values are possible:

Initial library list. The initial user part of the library list that is associated with this thread. This key is only valid for the JOBC0300 format. The possible values are:

Inquiry message reply. How the job answers inquiry messages. This key is only valid for the JOBC0100 and JOBC0200 formats. The possible values are:

Job accounting code. An identifier assigned to the job by the system to collect resource use information for the job when job accounting is active. The user who is changing this field must have authority to the CHGACGCDE CL command. If the user does not have the proper authority, this field is ignored and processing continues.

The possible values for the JOBC0100 and JOBC0200 formats are:

The possible values for the JOBC0300 format are:

Job date. The date that is assigned to the job. It is in the format CYYMMDD where C is the century, YY is the year, MM is the month, and DD is the day. A 0 for the century flag indicates years 19xx and a 1 indicates years 20xx. This value will only be changed for jobs whose status is *JOBQ or *ACTIVE. This key is only valid for the JOBC0100 and JOBC0200 formats.

Job log output. How the job log will be produced when the job completes. This does not affect job logs produced when the message queue is full and the job message queue full action specifies *PRTWRAP. Messages in the job message queue are written to a spooled file, from which the job log can be printed, unless the Control Job Log Output (QMHCTLJL) API was used in the job to specify that the messages in the job log are to be written to a database file. The job log output value can be changed at any time until the job log has been produced or removed.

The job log can be displayed at any time until the job log has been produced or removed. To display the job log, use the Display Job Log (DSPJOBLOG) command.

The job log can be removed when the job has completed and the job log has not yet been produced or removed. To remove the job log, use the Remove Pending Job Log (QWTRMVJL) API or the End Job (ENDJOB) command.

The possible values are:

*SYSVAL	The value is specified by the QLOGOUTPUT system value.
*JOBLOGSVR	The job log will be produced by a job log server. For more information about job log servers, refer to the Start Job Log Server (STRLOGSVR) command.
*JOBEND	The job log will be produced by the job itself. If the job cannot produce its own job log, the job log will be produced by a job log server. For example, a job does not produce its own job log when the system is processing a Power Down System (PWRDWNSYS) command.
*PND	The job log will not be produced. The job log remains pending until removed.

Job message queue full action. The action to take when the message queue is full. This key is only valid for the JOBC0100 and JOBC0200 formats. The possible values are:

Job queue name - qualified. The qualified name of the job queue that the job is to be on. The format of the qualified name is a 10-character simple object name followed by a 10-character library name. This value is valid for jobs whose status is *JOBQ. For jobs with a status of *OUTQ or *ACTIVE, an error will be signaled. This key is valid for the JOBC0100 and JOBC0200 formats only.

Job queue priority. The scheduling priority of the job compared to other jobs on the same job queue. The highest priority is 0 and the lowest is 9. This value is valid for jobs whose status is *JOBQ or *ACTIVE. For jobs with a status of *OUTQ, an error will be signaled. This key is only valid for the JOBC0100 and JOBC0200 formats.

Job switches. The current setting of the job switches that are used by this job. Specify any combination of eight 0's, 1's, or X's to change the job switch settings. If a switch value is not being changed, enter an X in the position that represents that switch. This key is only valid for the JOBC0100 and JOBC0200 formats.

Language ID. The language identifier that is associated with this job. The language identifier is used when *LANGIDUNQ or *LANGIDSHR is specified on the sort sequence parameter. If the job CCSID is 65535, this parameter is also used to determine the value of the job default CCSID.

The possible values for the JOBC0100 and JOBC0200 formats are:

The possible values for the JOBC0300 format are:

Locale. The path name of the locale that is assigned to the LANG environment variables. Several job attributes can be set from the locale based on the values from the locale job attributes (locale job attributes are retrieved from the same user profile as the locale). The attributes that can be changed are CCSID, date format, date separator, sort sequence, time separator, and decimal format. This key is only valid for the JOBC0300 format. The possible values are:

Logging level. What type of information is logged. This key is valid for the JOBC0100 and JOBC0200 formats only. The possible values are:

Logging of CL programs. Whether or not commands are logged for CL programs that are run. The possible values are *YES and *NO. This key is valid for the JOBC0100 and JOBC0200 formats only.

Logging severity. The severity level that is used in conjunction with the logging level to determine which error messages are logged in the job log. The values range from 00 through 99. This key is valid for the JOBC0100 and JOBC0200 formats only.

Logging text. The level of message text that is written in the job log when a message is logged according to the logging level and logging severity. This key is valid for the JOBC0100 and JOBC0200 formats only. The possible values are:

Output queue name. The name of the default output queue that is used for spooled output produced by this job. The default output queue is only for spooled printer files that specify *JOB for the output queue. The possible values for the JOBC0300 format are:

Output queue name - qualified. The qualified name of the default output queue that is used for spooled output produced by this job. The default output queue is only for spooled printer files that specify *JOB for the output queue. The format of the qualified name is a 10-character simple object name followed by a 10-character library name.

Output queue name.

CHAR(10). The specific name of the output queue that is used. If a special value is specified, it must be the only value in the field.

The possible values for the JOBC0100 and JOBC0200 formats are:

*DEV	The DEV parameter is determined by one of these printer file commands: Create Printer File (CRTPRTF), Change Printer File (CHGPRTF), or Override with Printer File (OVRPRTF).
*WRKSTN	The default output queue that is used with this job is the output queue that is assigned to the work station associated with the job at the time the job is started.
*USRPRF	The output queue name specified in the user profile under which this thread was initially running is used.
output-queue-name	The name and library of the default output queue that is used by the job. Specify the library name last (left-adjusted and padded with blanks) preceded by the output queue name.

Output queue library name.

CHAR(10). The name of the library that contains the output queue. The library name must follow the output queue name. The possible values are:

*LIBL	All libraries in the job's library list are searched until the first match is found.
*CURLIB	The current library for the job is used to locate the name of the spooled output queue. If no library is specified as the current library for the job, QGPL is used.
library-name	Specify the name of the library where the spooled output queue is located.

Output queue priority. The output priority for spooled output files that this job produces. The highest priority is 0, and the lowest is 9.

The possible CHAR(2) values for the JOBC0100 and JOBC0200 formats are:

The possible CHAR(10) values for the JOBC0300 format are:

Printer device name. The printer device used for printing output from this job.

The possible values for the JOBC0100 and JOBC0200 formats are:

The possible values for the JOBC0300 format are:

Print key format. Whether border and header information is provided when the Print key is pressed. This key is only valid for the JOBC0100 and JOBC0200 formats. The possible values are:

Print text. The line of text (if any) that is printed at the bottom of each page of printed output for the job. The possible values for the JOBC0100 and JOBC0200 formats are:

The possible values for the JOBC0300 format are:

Purge. Whether or not the job is eligible to be moved out of main storage and put into auxiliary storage at the end of a time slice or when entering a long wait (such as waiting for a work station user's response). This attribute is ignored when more than one thread is active within the job. If the job consists of multiple routing steps, a change to this attribute during a routing step does not apply to subsequent routing steps. This key is valid for the JOBC0100 and JOBC0200 formats only. The possible values are:

Run priority (job). The priority at which the job or thread competes for the processing unit relative to other jobs and threads that are active at the same time. The run priority ranges from 1 (highest priority) to 99 (lowest priority). This value represents the relative (not absolute) importance of the job or thread. For example, a run priority of 25 is not twice as important as a run priority of 50. If the job consists of multiple routing steps, a change to this attribute during a routing step does not apply to subsequent routing steps. This key is valid for the JOBC0100 and JOBC0200 formats only. This key can be used to change the current thread using the JOBC0200 format, but when changing a specific thread, the JOBC0400 format should be used with the Run priority (thread) key.

The possible values for the JOBC0100 format are:

The possible values for the JOBC0200 format are:

Run priority (thread). The run priority for the thread relative to the priority of the other threads that are running in the system. The range of values are from 1 (highest priority) to 99 (lowest priority). The value may never be higher than the run priority for the job in which the thread is running. If a priority higher than the job's is entered, an error is returned. This key is valid for the JOBC0200 and JOBC0400 format only.

Schedule date. The date on which the submitted job becomes eligible to run.

If your system or your job is configured to use the Julian date format, *MONTHSTR and *MONTHEND are calculated as if the system or job did not use the Julian date format. This key is only valid for the JOBC0100 format. The possible values are:

Schedule time. The time on the scheduled date at which the job becomes eligible to run. This key is valid for the JOBC0100 format only.

Note: Although the time can be specified to the second, the load on the system may affect the exact time at which the job becomes eligible to run.

The possible values are:

Server mode for Structured Query Language. Whether or not Structured Query Language (SQL) statements should run in a separate server job. This key is only valid for the JOBC0200 format. The possible values are:

Server type. The type of server represented by the job. This key is valid for the JOBC0200 format only. A value of blanks indicates that the job is not part of a server. A value of hexadecimal zeros is not allowed. IBM servers start with QIBM.

Sort sequence table. The sort sequence table to be used for string comparisons for this job. The possible values for the JOBC0300 format are:

Sort sequence table - qualified. The qualified name of the sort sequence table to be used for string comparisons for this job. The format of the qualified name is a 10-character simple object name followed by a 10-character library name. The sort sequence table consists of 2 parts:

Sort sequence table name

CHAR(10). The specific name of the sort sequence table. The possible values for the JOBC0100 and JOBC0200 formats are:

*SYSVAL	The system value QSRTSEQ is used.
*USRPRF	The sort sequence table specified in the user profile under which this thread was initially running is used.
*HEX	A sort sequence table is not used. The hexadecimal values of the characters are used to determine the sort sequence.
*LANGIDUNQ	A unique-weight sort table is used.
*LANGIDSHR	A shared-weight sort table is used.
table-name	The name of the sort sequence table to be used with this job. The table name must be preceded by the library name, left-adjusted, and padded with blanks.

Sort sequence library

CHAR(10). The sort sequence table library that is associated with this job. The possible values are:

*LIBL	All libraries in the job's library list are searched until the first match is found.
*CURLIB	The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.
library-name	The name of the library to be searched. This must be specified after the sort sequence table name and must be left-adjusted and padded with blanks.

Spooled file action. Whether spooled files can be accessed through job interfaces once a job has completed its normal activity.

Status message handling. Whether you want status messages displayed for this job. The possible values for the JOBC0100 and JOBC0200 formats are:

The possible values for the JOBC0300 format are:

Time separator. The value used to separate hours, minutes, and seconds when presenting a time. This key is only valid for the JOBC0100 and JOBC0200 formats. The possible values are:

Time slice. The maximum amount of processor time (in milliseconds) given to each thread in this job before other threads (in this job or in other jobs) are given the opportunity to run. The time slice establishes the amount of time that is needed by a thread in the job to accomplish a meaningful amount of processing. At the end of the time slice, the thread might be put in an inactive state so that other threads can become active in the storage pool. If the job consists of multiple routing steps, a change to this attribute during a routing step does not apply to subsequent routing steps. Valid values range from 1 through 9999999 (that is, 9 999 999 milliseconds or 9999.999 seconds). Although you can specify a value of less than 8, the system takes a minimum of 8 milliseconds to run a process. If you display a job's run attributes, the time slice value is never less than 8. This key is valid for the JOBC0100 and JOBC0200 formats only.

Time-slice end pool. Whether you want interactive jobs moved to another main storage pool at the end of the time slice. This key is only valid for the JOBC0100 and JOBC0200 formats. The possible values are:

Format of job or thread identification information

Format JIDF0100 is the format of the information needed to identify the job and the thread for which the thread's attributes will be changed. This format supports several special values that can help in identifying the thread.

Format JIDF0200 is the format of the information needed to identify the thread for which the thread's attributes will be changed. This format is to be used when referencing a specific thread for which you already have the thread handle.

Note: If the thread handle is available, Format JIDF0200 provides a faster method of accessing a thread that is not the current thread than Format JIDF0100.

JIDF0100 format.

Field Descriptions

Internal job identifier. The internal identifier for the job. The List Job (QUSLJOB) API returns 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.

Job name. A specific job name or one of the following special values:

Job number. A specific job number, or blanks when the job name specified is a special value.

Reserved. An unused field. This field must contain hexadecimal zeros.

Thread identifier. A value that uniquely identifies a thread within a job. If a thread identifier is specified, a thread indicator must also be specified. If the thread indicator is not 0, this field must contain hexadecimal zeros.

Thread indicator. A value that is used to specify the thread within the job. If a thread indicator is specified, a thread identifier must be specified also. The following values are supported:

Note: For all of the supported values, the combination of the internal job identifier, job name, job number, and user name fields must also identify the job containing the thread.

User name. A specific user profile name, or blanks when the job name specified is a special value.

JIDF0200 format.

Field Descriptions

Internal job identifier. The internal identifier for the job. The List Job (QUSLJOB) API returns 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.

Job name. A specific job name or one of the following special values:

Job number. A specific job number, or blanks when the job name specified is a special value.

Reserved. An unused field. This field must contain hexadecimal zeros.

Thread handle. A value that addresses a particular thread within a job. While the thread identifier uniquely identifies the thread within the job, the thread handle can improve performance when referencing the thread. A valid thread handle must be specified. The thread handle is returned on several other interfaces.

Thread identifier. A value which uniquely identifies a thread within a job. A valid thread identifier must be specified.

User name. A specific user profile name, or blanks when the job name specified is a special value.

Usage Notes

How to determine the format to use

The JOBC0100 format is to be used to change an attribute that is scoped to the job. This format will change the attribute for either the job that the request is issued from or for any other job that is on the system.

The JOBC0200 format is to be used to change an attribute for the thread that the request is being issued from. This will change the attribute at the thread level for attributes that are scoped to the thread and will change the attribute at the job level for attributes that are scoped to the job. For attributes that are scoped to the thread, there may be multiple threads active when the change is requested. The change will only affect the current thread. The other active threads will not be affected by the change. The attributes that are scoped to the job may only be changed if there are no secondary threads active, so as to not affect other threads. If a job attribute needs to be changed by a secondary thread or while secondary threads are active, the JOBC0100 format should be used.

The JOBC0300 format may be used after a set user profile has been done with the Set Profile (QWTSETP) API. This format will perform job-initialization type activities. When a job is started, information for various attributes is retrieved from the user profile that the job is starting under. This format will perform a similar function for either the user profile that the thread is currently running under or for the user profile that the thread was initiated under. For attributes that are scoped to the thread, if this format is called with multiple threads active, the change will only affect the current thread. Attributes that are scoped to the job may only be changed if there are no secondary threads active.

The JOBC0400 format is to be used to change an attribute that is scoped to the thread. It allows changing a thread other than the current thread as well as the current thread.

Considerations for attribute scope and thread safety

In the Attribute Scope and Thread Safety table, the Attribute column shows the key identifier and the text description for the attribute.

The Scope column shows whether the attribute is scoped to the job or to the thread. Attributes changed with this API may be scoped to the job or to the current thread. Some attributes that are scoped to the job could be moved to the thread level in a future release. If that were to occur, this API would be updated to change the thread attribute.

The Format columns indicate whether the attributes are considered to be threadsafe when being changed for that format.

The following describes the terminology used in the Format columns:

Attribute Scope and Thread Safety
Attribute	Scope	JOBC0100	JOBC0200	JOBC0300	JOBC0400
0104: ASP group information	Current thread			Threadsafe
0201: Break message handling	Job	Threadsafe	Single threaded only
0302: Coded character set ID	Job	Threadsafe	Single threaded only	Single threaded only
0303: Country or region ID	Job	Threadsafe	Single threaded only	Single threaded only
0310: Current library	Current thread			Threadsafe
0311: Character identifier control	Job	Threadsafe	Single threaded only	Single threaded only
0318: Client IP address - IPv4 (job)	Job		Initial thread only1
0405: Date format	Job	Threadsafe	Single threaded only
0406: Date separator	Job	Threadsafe	Single threaded only
0408: DDM conversation	Job	No	No
0409: Default wait	Job	Threadsafe	Single threaded only
0410: Device recovery action	Job	Threadsafe	Single threaded only
0413: Decimal format	Job	Threadsafe	Single threaded only
0801: Home directory	Current thread			Threadsafe
0901: Inquiry message reply	Job	Threadsafe	Single threaded only
0910: Initial library list	Current thread			Threadsafe
1001: Job accounting code	Job	No	No	No
1002: Job date	Job	Threadsafe	Single threaded only
1004: Job queue name - qualified	Job	Threadsafe	Single threaded only
1005: Job queue priority	Job	Threadsafe	Single threaded only
1006: Job switches	Job	Threadsafe	Single threaded only
1007: Job message queue full action	Job	Threadsafe	Single threaded only
1018: Job log output	Job	Threadsafe	Single threaded only
1201: Language ID	Job	Threadsafe	Single threaded only	Single threaded only
1202: Logging level	Job	Threadsafe	Single threaded only
1203: Logging of CL programs	Job	Threadsafe	Single threaded only
1204: Logging severity	Job	Threadsafe	Single threaded only
1205: Logging text	Job	Threadsafe	Single threaded only
1210: Locale	Job			No
1501: Output queue name	Job			Single threaded only
1501: Output queue name - qualified	Job	Threadsafe	Single threaded only
1502: Output queue priority	Job	Threadsafe	Single threaded only	Single threaded only
1601: Print key format	Job	Threadsafe	Single threaded only
1602: Print text	Job	Threadsafe	Single threaded only	Single threaded only
1603: Printer device name	Job	Threadsafe	Single threaded only	Single threaded only
1604: Purge	Job	Threadsafe	Single threaded only
1802: Run priority (job)	Job	Threadsafe
1802: Run priority (job)	Current thread		Threadsafe
1804: Run priority (thread)	Current thread		Threadsafe
1804: Run priority (thread)	Thread				Threadsafe
1901: Sort sequence table	Job			Single threaded only
1901: Sort sequence table - qualified	Job	Threadsafe	Single threaded only
1902: Status message handling	Job	Threadsafe	Single threaded only	Single threaded only
1911: Server type	Job		Single threaded only
1920: Schedule date	Job	No
1921: Schedule time	Job	No
1922: Server mode for Structured Query Language	Job		Single threaded only
1982: Spooled file action	Job	Threadsafe	Single threaded only
2001: Time separator	Job	Threadsafe	Single threaded only
2002: Time slice	Job	Threadsafe	Single threaded only
2003: Time-slice end pool	Job	Threadsafe	Single threaded only
2701: All keys for JOBC0300 format	See the specific keys in this table			See the specific keys in this table
1 A change to this attribute in a secondary thread is possible; however, it is essentially meaningless as only the attribute for the inital thread can be retrieved using the Retrieve Job Information (QUSRJOBI) API. This key has no correlation to the attribute set by the system. For further information on retrieving the Client IP address - IPv4 or IPv6 that has been implicity set by the operating system, see the Retrieve Thread Attribute (QWTRTVTA) API.

Error Messages