CHGJOBD (Change Job Description)

CHGJOBD Command syntax diagram

 

Purpose

The Change Job Description (CHGJOBD) command changes the job-related attributes specified for a job description object through the Create Job Description (CRTJOBD) command.

Any attribute, except the public authority attribute, may be changed. More information on changing object authorizations is in the descriptions of the Revoke Object Authority (RVKOBJAUT) command and Grant Object Authority (GRTOBJAUT) command.

 

Restrictions

1. The user of this command must have operational authority for the user profile named in the USER parameter.
   
2. The user of this command must have object operational and object management authorities for the job description, and execute authority for the library in which the job description resides is also required.
   
3. To change the ACGCDE parameter to a value other than *USRPRF, the user must have *USE authority to the Change Accounting Code (CHGACGCDE) command.

 

Required Parameters

JOBD

Specifies the qualified name of the job description being changed.

Note:

You cannot specify the job description QSYSJOBD on this parameter. This job description is the backup job description for the system and cannot be changed by the user.

The name of the job description can be qualified by one of the following library values:

*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: Specify the name of the library to be searched.

job-description-name: Specify the job description name being changed.

 

Optional Parameters

USER

Specifies the name of the user profile associated with this job description. The names QSECOFR, QSPL, QDOC, QDBSHR, QRJE, QTSTRQS, QDFTOWN, and QSYS are not valid entries for this parameter.

*SAME: The value does not change.

*RQD: A user profile name is required to get access to the job description. For work station entries, a password must be entered when signing on the work station; the associated user name becomes the user profile name used for the job. *RQD is not valid for job descriptions specified for job entries that start automatically, or for those used by the Batch Job (BCHJOB) command. It is valid on the Submit Job (SBMJOB) command only if USER(*CURRENT) is specified.

user-name: Specify the user name that identifies the user profile associated with batch jobs using this job description. For interactive jobs, this is the default user name used for signing on the system without typing a password.

JOBQ

Specifies the qualified name of the job queue on which this job is placed.

*SAME: The name of the job queue does not change.

The name of the job queue can be qualified by one of the following library values:

*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: Specify the name of the library to be searched.

job-queue-name: Specify the qualified name of the job queue associated with this job description.

If the job queue does not exist when the job description is changed, a library qualifier must be specified because the job queue name is retained in the job description.

JOBPTY

Specifies the scheduling priority for jobs that use this job description. Valid values range from 1 through 9, where 1 is the highest priority and 9 is the lowest priority. More information is in Commonly used parameters.

*SAME: The value does not change.

scheduling-priority: Specify a value, ranging from 1 through 9, for the scheduling priority for jobs that use this job description.

OUTPTY

Specifies the output priority of spooled files produced by jobs that use this job description. Valid values range from 1 through 9. The highest priority is 1 and the lowest priority is 9. More information is in Commonly used parameters.

*SAME: The value does not change.

output-priority: Specify a value, ranging from 1 through 9, for the output priority of the spooled files produced by jobs that use this job description.

PRTTXT

Specifies up to 30 characters of text to be printed at the bottom of each page of output. More information is in Commonly used parameters.

*SAME: The value does not change.

*SYSVAL: The system value, QPRTTXT, is used.

*BLANK: Text is not specified.

'print-text': Specify up to 30 characters, enclosed in apostrophes, to be printed at the bottom of each page.

ACGCDE

Specifies the accounting code used when logging system resource use for a job having this job description. To specify an accounting code other than *USRPRF, the user must have *USE authority for the Change Accounting Code (CHGACGCDE) command.

*SAME: The value does not change.

*USRPRF: The accounting code for jobs using this job description is obtained from the user profile for the job.

*BLANK: An accounting code consisting of 15 blanks is assigned to jobs that use this job description.

'accounting-code': Specify the character string that is used as the accounting code for jobs that use this job description and have accounting statistics logged in the system accounting journal QSYS/QACGJRN. If less than 15 characters are entered, the string is padded with blanks on the right. Note that the character string '*USRPRF' is considered a special value that cannot be used as an accounting code on this command.

RTGDTA

Specifies the routing data used with this job description to start jobs. The routing data determines the routing entry in the subsystem description that identifies the program in which the job runs.

*SAME: The value does not change.

*RQSDTA: Up to the first 80 characters of the request data specified in the RQSDTA parameter are used as the routing data for the job.

'routing-data': Specify the character string, enclosed in apostrophes, that is used as the routing data for jobs that use this job description. For example, the value QCMDI is the routing data used by the IBM-supplied interactive subsystem (QINTER and QBASE) to route interactive jobs to the IBM-supplied control language processing unit, QCMD. Up to 80 characters can be specified.

RQSDTA

Specifies the request data placed as the last entry in the job's message queue for jobs using this job description. For example, when a CL command is supplied as request data, it becomes a message that can be read by the control language processing unit, QCMD if the job is routed to QCMD.

*SAME: The value does not change.

*NONE: No request data is placed in the job's message queue.

*RTGDTA: The routing data specified in the RTGDTA parameter is placed as the last entry in the job's message queue.

'request-data': Specify the character string placed as the last entry in the job's message queue as a single request. Up to 256 characters can be entered, enclosed in apostrophes. When a CL command is entered, it must be enclosed in single apostrophes, and where single apostrophes would normally be used inside the command, double apostrophes must be used instead.

SYNTAX

Specifies whether requests placed on the job message queue for jobs using this job description are syntax-checked as CL commands. When syntax checking is specified, the commands are checked for syntax as they are submitted instead of when the job is run. This provides an earlier diagnosis of syntax errors. If checking is specified, the message severity that causes a syntax error to end processing of a job is also specified.

*SAME: The value does not change.

*NOCHK: The request data is not checked for syntax as CL commands.

message-severity: Specify a value, ranging from 00 through 99, that specifies the lowest message severity that can cause running of a job to end. The request data is checked for syntax as CL commands; if a syntax error occurs that has severity equal to or greater than the error message severity specified here, the running of the job containing the erroneous command is suppressed. More information on message severity is in Commonly used parameters.

If the message severity is specified, it is used only when the job description is used by a job command that also has RQSDTA(*) specified and the requests are CL commands.

INLLIBL

Specifies the initial user part of the library list used for jobs that have this job description.

Note:

Duplicating libraries in the library list is not allowed.

More information on the use of library lists is in the CL Programming book.

*SAME: The value does not change.

*SYSVAL: The system default user library list is used for jobs that use this job description. The default library list contains the library names specified in the system values when a job using this job description is started.

*NONE: The user part of the initial library list is empty; only the system portion is used.

library-name: Specify the names of one or more libraries in the user part of the library list for jobs that use this job description. No more than 250 names can be specified; the libraries are searched in the same order as they are listed here.

ENDSEV

Specifies the message severity level of escape messages that can cause running of a batch job to end. The batch job is ended when a request in the batch input stream sends to the request processing program QCMD or QCL an escape message whose severity code is equal to or greater than that specified. This parameter value is compared with the severity of an escape message not monitored that occurs as a result of running a noncompiled CL command in a batch job. More information on message severity is in Commonly used parameters.

*SAME: The value does not change.

message-severity: Specify a value ranging from 00 through 50 for the message severity of an escape message that results from a request in the batch input stream and ends the jobs that use this job description. Because escape messages typically have a maximum severity level of 50, a value of 50 or lower must be specified to end a job as a result of an escape message. An unhandled escape message whose severity is equal to or greater than the value specified causes the job to be canceled. More information on message severity is in Commonly used parameters.

LOG

Specifies the message logging values used to determine the amount and type of information sent to the job log by this job. This parameter has three elements: the message (or logging) level, the message severity, and the level of message text. If no values are specified on this parameter, the values specified in the job description associated with this job are used.

Element 1: Message Level

The message level specifies the type of information that is logged.

*SAME: The value does not change.

message-level: Specify a value, ranging from 0 through 4, for the message logging level used for the job's messages. For a description of the message levels, refer to the message level variable description in the LOG parameter of the CRTJOBD command.

Element 2: Message Severity

The severity level that is used in conjunction with the logging level to determine which error messages are logged in the job log of jobs using this job description.

*SAME: The value does not change.

message-severity: Specify a value, ranging from 00 through 99, that is used in conjunction with the logging level to determine which error messages are logged in the job log. More information on message severity is in Commonly used parameters.

Element 3: Message Text Level

The level of message text that is written to the job log when a message is logged according to the logging level and the logging severity.

*SAME: The value does not change.

*MSG: Only the message text is written to the job log.

*SECLVL: Both the message text and the message help (cause and recovery) of the error message are written to the job log.

*NOLIST: If the job ends normally, no job log is produced. If the job ends abnormally (if the job end code is 20 or higher), a job log is produced. The messages that appear in the job log contain both the message text and the message help.

LOGCLPGM

Specifies whether the loggable commands logged and run in a control language program are logged to the job log by way of the CL program's message queue. This parameter sets the status of the job's logging flag. If *NO is specified, the logging flag status is off and CL commands are not logged. If *YES is specified and the LOG(*JOB) value is specified in the Create CL Program (CRTCLPGM) command, all commands in the CL program that can be logged are logged to the job log.

For more information on request logging, refer to the LOG parameter in the CRTCLPGM command description.

*SAME: The value does not change.

*NO: The commands in a CL program are not logged to the job log.

*YES: The commands in a CL program are logged to the job log.

INQMSGRPY

Specifies the action taken when a predefined inquiry message is issued by a job that uses this job description. The conditions that must be met are listed in the system reply list entries. Refer to the ADDRPYLE (Add Reply List Entry) command description for more information.

*SAME: The value does not change.

*RQD: A reply is required for any predefined inquiry message issued by a job that uses this job description.

*DFT: The default reply to the inquiry message is sent. If no default reply is specified in the message description of the inquiry message, the system default reply, *N, is used.

*SYSRPYL: The system reply list is checked to determine whether an entry matches the message identifier and optional compare value for any inquiry message issued by a job that uses this job description. If a match occurs, the reply value in that reply list entry is used. If no entry exists for that message, a reply is required.

PRTDEV

Specifies the name of the default printer device for this job. If the printer file being used to create the output specifies to spool the file, the spooled file is placed on the device's output queue, which is named the same as the device.

Note:

This assumes the defaults are specified on the OUTQ parameter for the printer file, job description, user profile and workstation.

*SAME: The value does not change.

*USRPRF: The name of the printer device for jobs using this job description is taken from the user profile for the job when the job is started.

*SYSVAL: The value specified in the system value QPRTDEV is used.

*WRKSTN: The output queue assigned to the user's work station is used.

printer-device-name: Specify the name of the printer device used with this job description.

OUTQ

Specifies the qualified name of the output queue used for spooled printer files that specify OUTQ(*JOB). This change does not affect files already created in active jobs or files in completed jobs in which the files were spooled.

*SAME: The value does not change.

*USRPRF: The output queue name for jobs using this job description is taken from the user profile for the job at the time the job is started.

*DEV: The output queue specified on the PRTDEV parameter is used.

*WRKSTN: The output queue assigned to the user's work station is used.

The name of the output queue can be qualified by one of the following library values:

*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: Specify the name of the library to be searched.

output-queue-name: Specify the name of the default output queue used by jobs that use this job description.

If the output queue does not exist when the job description is changed, a library qualifier must be specified, because the qualified output queue name is retained in the job description.

HOLD

Specifies whether jobs using this job description are placed on the job queue in the hold condition. A job placed on the job queue in the hold condition is held until it is either released by the Release Job (RLSJOB) command or canceled by the End Job (ENDJOB) or Clear Job Queue (CLRJOBQ) command. If the job is not run before the next power-down of the system, the job queue can be cleared (and the job ended) when the next initial program load (IPL) is done.

*SAME: The value does not change.

*NO: Jobs using this job description are not held when they are put on the job queue.

*YES: The spooled file is held until released by the Release Spool File (RLSSPLF) command.

DATE

Specifies the date that is assigned for jobs that use this job description.

*SAME: The value does not change.

*SYSVAL: The value in the QDATE system value at the time the job is started is used as the job date.

job-date: Specify the value used as the job date for the job being started. The format currently specified for the system value QDATFMT must be used. The Work Management book describes the QDATFMT system value.

SWS

Specifies the initial job switch settings for a group of eight job switches for jobs that use this job description. These switches can be set or tested in a CL program and used to control the flow of the program. For example, if a certain switch is on, another program may be called. The job switches may also be valid in other high-level language (HLL) programs. The only values that are valid for each single-digit switch are 0 (off) or 1 (on).

*SAME: The value does not change.

switch-settings: Specify any combination of eight 0's or 1's to change the job switch settings.

DEVRCYACN

Specifies the recovery action to take for the job when an input/output error is encountered on the *REQUESTER device (the device on which the user signed on the system) for interactive jobs that use this job description.

Note:

This attribute is ignored for non-interactive jobs.

*SAME: The value does not change.

*SYSVAL: The system value, QDEVRCYACN, is used as the device recovery action for this job.

*MSG: The application program requesting the input/output operation receives an error message which indicates that the input/output operation has failed.

*DSCMSG: The job is automatically disconnected. After the job is reconnected, it receives an error message indicating that an input/output error has occurred and that the device has been recovered. Even though the device has been recovered, the contents of the display when the error occurred must be shown again on the display.

*DSCENDRQS: The job is automatically disconnected. After the job is reconnected, the ENDRQS command is issued specifying the processor that made the previous request. If a request processor is unavailable, the ENDRQS command fails, and the error message issued during the DSCMSG case is signaled.

*ENDJOB: The job is ended with the *IMMED option. A job log is produced for the job.

*ENDJOBNOLIST: The job is ended with the *IMMED option. No job log is produced for the job.

TSEPOOL

Specifies whether interactive jobs are moved to another main storage pool when the end of the time slice is reached. When a long wait occurs, the job is moved back to the pool in which it was originally running. This may help minimize the effect on interactive response time.

*SAME: The value does not change.

*SYSVAL: The system value in QTSEPOOL is used as the time slice end pool action for this job description.

*NONE: The job is not moved when the end of the time slice is reached.

*BASE: The job is moved to the base pool when the end of the time slice is reached.

TEXT

Specifies the text that briefly describes the job description. More information is in Commonly used parameters.

*SAME: The value does not change.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

JOBMSGQMX

Specifies the maximum size of the job message queue.

*SAME: The job message queue maximum size will not change.

*SYSVAL: The value in QJOBMSGQMX (system value) at the time the job is started is used as the maximum size of the job message queue.

maximum-size-of-job-message-queue: Specify a value in the range of 2 to 64 megabytes.

JOBMSGQFL

Specifies the action that should be taken when the job message queue is full.

*SAME: The job message queue full option will not change.

*SYSVAL: The value specified for the QJOBMSGQFL system value is used.

*NOWRAP: The message queue does not wrap when it is full. This action ends the job.

*WRAP: The message queue wraps to the start of the message queue when full and starts filling the message queue again.

*PRTWRAP: The message queue wraps the job message queue when full and prints the messages that are being overlaid because of wrapping.

ALWMLTTHD

Specifies whether or not the job can run with multiple user threads. This attribute does not prevent the operating system from creating system threads in the job. This job attribute is not allowed to be changed once a job starts. This attribute applies to autostart jobs, prestart jobs, batch jobs submitted from job schedule entries and jobs started using the Submit Job (SBMJOB) and Batch Job (BCHJOB) commands. This attribute is ignored when starting all other types of jobs. This attribute should be set to *YES only in job descriptions used exclusively with functions that create multiple user threads.

*SAME: The value does not change.

*NO: The job cannot run with multiple user threads.

*YES: The job can run with multiple user threads.

INLASPGRP

Specifies the initial setting for the auxiliary storage pool (ASP) group name for the initial thread of jobs using this job description. A thread can use the Set Auxiliary Storage Pool Group (SETASPGRP) command to change its library name space. When an ASP group is associated with a thread, all libraries in the independent ASPs in the ASP group are accessible and objects in those libraries can be referenced using regular library-qualified object name syntax. The libraries in the independent ASPs in the specified 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 for the thread.

*SAME: The value does not change.

*NONE: Specifies the initial thread of jobs using this job description will be started with no ASP group. The library name space will not include libraries from any ASP group. Only the libraries in the system ASP and any basic user ASPs will be in the library name space.

auxiliary-storage-pool-group-name: Specify the name of the ASP group to be set for the initial thread of jobs using this job description. The ASP group name is the name of the primary ASP device within the ASP group. All libraries from all ASPs in this ASP group will be included in the library name space.

SPLFACN

Specifies whether or not spooled files are accessed through job interfaces after the job ends. Keeping spooled files with jobs allows job commands such as Work with Submitted Jobs (WRKSBMJOB) to work with the spooled files even after the job has ended. Detaching spooled files from jobs reduces the use of system resources by allowing job structures to be recycled when the jobs end.

*SAME: The value does not change.

*SYSVAL: The value specified in the system value QSPLFACN is used.

*KEEP: When the job ends, the spooled files are kept with the job and the status of the job is updated to indicate that the job has completed.

*DETACH: When the job ends, the spooled files are detached from the job and the job is removed from the system.

Examples for CHGJOBD

Example 1: Setting Job Running and Output Priorities

CHGJOBD  JOBD(QGPL/QPGMR)  JOBPTY(2)  OUTPTY(2)

This command allows jobs using the IBM-supplied job description QPGMR in the QGPL library to process with a higher job and output priority than originally specified for QPGMR. QPGMR originally sets job running and output priorities at level 5. More information about the IBM-supplied job description parameter values is in the CL Programming book.

Example 2: Changing Priority Limits

Assume that the user profile was created as follows:

Part 1:

CRTUSRPRF  USRPRF(JLRAY)  PASSWORD(GAMMA)
  SPCAUT(*JOBCTL)  PTYLMT(4)  AUT(*NONE)

Then attempt to change the priority limits of the job description BATCH5 with the following command:

Part 2:

CHGJOBD   JOBD(BATCH5)  USER(JLRAY)  JOBPTY(1)
  OUTPTY(1)

Because the priority limit specified in the user profile takes precedence over any limit specified in a job description, an error message is sent and a priority of 4 is assumed for both job and output priority levels.

Example 3: Requiring a Password to Sign On at Work Station

CHGJOBD  JOBD(INT4)  USER(*RQD)  RTGDTA(QCMDI)
  LOG(*SAME)  ACGCDE('USERXYZ CODE123')  TEXT(*BLANK)

The USER parameter indicates the user of the job description INT4 must enter a password to sign on at a work station. The characters QCMDI are used as the routing data being compared with the routing table of the subsystem under which the job is run. All values of the LOG parameter list are not changed. Jobs that use this job description have accounting data recorded under the accounting code, 'USERXYZ CODE123', when job accounting is active. The text for this job description is changed to all blanks.

Example 4: Directing Jobs Using This System to a Specific Job Queue

CHGJOBD   JOBD(BATCH3)  JOBQ(NIGHTQ)  JOBPTY(4)
  OUTPTY(4)  RTGDTA(QCMDB)  INQMSGRPY(*DFT)
  TEXT('Batch #3 JOBD for high priority night work')

This command changes a job description named BATCH3 found in the library search list. The jobs using this description are now placed on the job queue NIGHTQ. The priority for jobs using this description and their spooled files is 4. QCMDB is the routing data that is compared with entries in the routing table of the subsystem where the job is run. The text is changed to indicate that this job description is for high priority night work. The INQMSGRPY parameter specifies that all messages of type *INQ that are issued from a job using this job description automatically causes the default reply message to be issued.

Error messages for CHGJOBD

*ESCAPE Messages

CPF1618

Job description &1 in library &2 damaged.

CPF1625

Job description &1 in library &2 not changed.

CPF88D2

PSF configuration &1 in library &2 not changed.