CRTJOBD (Create Job Description)
CRTJOBD Command syntax diagram
Purpose
The Create Job Description (CRTJOBD) command creates a job description object that contains a specific set of job-related attributes that can be used by one or more jobs. The attributes determine how each job is run on the system. The same job description can be used by multiple jobs. The values in the job description are usually used as the default values of the corresponding parameters in the Batch Job (BCHJOB) and Submit Job (SBMJOB) commands when their parameters are not specified.
The values in the job description can be overridden by the values specified in the BCHJOB and SBMJOB commands.
Restrictions
- To use this command, the user must have object operational authority for
the user profile specified on the USER parameter (if any); that is, the user
must have the authority to start a job on behalf of that user.
- The user must also have *ADD authority for the library where the job description is placed. To create a job description with an accounting code (ACGCDE) parameter 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 created.
The name of the job description can be qualified by one of the following library values:
-
*CURLIB: The job description is created in the current library for the job. 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 where the job description is created.
job-description-name: Specify the name of the job description being created.
-
Optional Parameters
- USER
- Specifies the name of the user profile associated with this job
description. The names QSECOFR, QSPL, QDOC, QDBSHR, QRJE, QTSTRQS, and QDFTOWN
are not valid entries for this parameter.
*RQD: A user name is required to use the job description. For work station entries, enter your password when you sign on at the work station; the associated user name becomes the 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 BCHJOB command. It is valid on the SBMJOB command only if USER(*CURRENT) is specified.
user-name: Specify the user name that identifies the user profile associated with batch jobs that use this job description. For interactive jobs, this is the default user name used when signing on without entering a password.
- JOBQ
- Specifies the qualified name of the job queue on which this job is placed.
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.
QBATCH: The QBATCH job queue is the queue on which the jobs are placed.
job-queue-name: Specify the qualified name of the job queue that is associated with this job description.
If the job queue does not exist when the job description is created, a library qualifier must be specified because the name of the qualified job queue is retained in the job description.
-
- JOBPTY
- Specifies the scheduling priority for each job that uses this job
description. The highest priority is 1 and the lowest priority is 9. More
information on this parameter is in Commonly
used parameters.
5: The scheduling priority that any job using this job description is 5.
scheduling-priority: Specify the scheduling priority for any job using this job description. Valid values range from 1 through 9.
- OUTPTY
- Specifies the output priority for spooled files that are produced by jobs
using this job description. The highest priority is 1 and the lowest priority
is 9. More information on this parameter is in Commonly used parameters.
5: The output priority for spooled files produced using this job description is 5.
output-priority: Specify the priority of spooled files produced using this job description. Valid values range from 1 through 9.
- PRTTXT
- Specifies up to 30 characters of text to be printed at the bottom of each
page of output. More information on this parameter is in Commonly used parameters.
*SYSVAL: The system value, QPRTTXT, is used.
*BLANK: Text is not specified.
'print-text': Specify the character string that is printed at the bottom of each page. Up to 30 characters can be entered, enclosed in apostrophes.
- 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.
Note: If the job is submitted by the SBMJOB command, the submitter's accounting code is used. *USRPRF: The accounting code for jobs using this job description is obtained from the job's user profile.
*BLANK: An accounting code 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 on the right with blanks. Note that the character string '*USRPRF' is considered a special value, and cannot be used as an accounting code on this command.
- RTGDTA
- Specifies the routing data that is used with this job description to start
jobs. The routing data is used to determine the routing entry in the subsystem
description that identifies the program where the job runs.
QCMDI: The default routing data QCMDI is used by the IBM-supplied interactive subsystem to route the job to the IBM-supplied control language processor QCMD in the QSYS library.
*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) to route interactive jobs to the IBM-supplied control language processor QCMD. Up to 80 characters can be entered.
- RQSDTA
- Specifies the request data that is 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 on a Submit Job (SBMJOB) command, it
becomes a message that can be read by the control language processor, QCMD (if
the submitted job is routed to QCMD).
*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 that is 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 apostrophes would normally be used inside the character string, double apostrophes must be used instead.
- SYNTAX
- Specifies whether requests placed on the job's message queue are checked
for syntax as CL commands. When syntax checking is specified, the commands are
checked for syntax as they are submitted rather than when the job is run, thus
providing 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. More information on this parameter is in Commonly used parameters.
*NOCHK: The request data is not checked for syntax as CL commands. 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.
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 CL command syntax; if a syntax error occurs that has severity equal to or greater than the error message severity specified here, the running of the job is suppressed.
- INLLIBL
- Specifies the first user portion of the library list that is used for jobs
using 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.
*SYSVAL: The system default user library list is used for jobs that use this job description. The default user library list contains the library names that were specified in the system value QUSRLIBL at the time that a job using this job description is started.
*NONE: The user portion of the first library list is empty; only the system portion is used.
library-name: Specify the names of one or more libraries that are in the user portion 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 a
batch job to end. The batch job is ended when a request in the batch input
stream sends an escape message whose severity code is greater than or equal to
that specified here to the request processing program. This parameter value is
compared with the severity of any unmonitored escape message 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.
30: An escape message resulting from a request in the batch input stream whose severity is equal to or greater than 30 causes the job to end.
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 that causes the job using this job description to end. Because escape messages typically go up to a severity level of 50, a value of 50 or lower must be specified for a job to end 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 end. 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.
Note: If no values are specified for the LOG parameter, the values 4, 0, and *NOLIST are assumed by the system. Element 1: Message Level
The message level specifies the type of information that is logged.
Notes
- A high-level message is one that is sent to the program
message queue of the program that receives the request message. For example,
QCMD is an IBM-supplied request processing program that receives request
messages.
- Several system displays provide a retrieve function (the F9 key) which gets a logged command into a command line. Commands are not necessarily logged unless the logging level is set to 3 or 4. If the logging level is set to 0, 1, or 2, each command that is completed cannot be retrieved into a command line because the logging level causes the command to be removed from the job log. When each command is completed, it cannot be retrieved into a command line if the message logging level for the job causes the command to be removed from the job log.
The logging levels are described below:
- 0
- No messages are logged.
- 1
- All messages sent to the job's external message queue with a severity
greater than or equal to the message logging severity are logged. This includes
the indications of job start, job end, and job completion status.
- 2
- The following information is logged:
- Logging level 1 information
- Request messages which result in a high-level message with a severity code greater than or equal to the message logging severity. Both the request message and all associated messages are logged.
- Logging level 1 information
- 3
- The following information is logged:
- Logging level 1 and 2 information
- All request messages
- Commands run by a CL program are logged if it is allowed by the logging of CL programs job attribute and the log attribute of the CL program.
- Logging level 1 and 2 information
- 4
- The following information is logged:
- All request messages and all messages with a severity greater than or equal
to the message logging severity, including trace messages.
- Commands run by a CL program are logged if it is allowed by the logging of CL programs job attribute and the log attribute of the CL program.
- All request messages and all messages with a severity greater than or equal
to the message logging severity, including trace messages.
4: A message logging level of 4 is used for jobs that use this job description.
message-level: Specify the message logging level used for jobs that use this job description.
Valid values range from 0 through 4.
Element 2: Message Severity
- A high-level message is one that is sent to the program
message queue of the program that receives the request message. For example,
QCMD is an IBM-supplied request processing program that receives request
messages.
- 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. More information on this parameter is in Commonly used parameters.
0: A message severity level of 0 is used for jobs that use this job description.
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.
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.
*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.
*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.
For an interactive job, the LOG parameter value on the SIGNOFF command takes precedence over the LOG parameter value specified for the job.
- LOGCLPGM
- Specifies whether the loggable commands that are 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.
*NO: Commands in a CL program are not logged to the job log.
*YES: Commands in a CL program are logged to the job log.
- INQMSGRPY
- Specifies the way that inquiry messages are answered for jobs that use this
job description. The user can specify that inquiry messages are to be answered
in the usual manner, that a default reply be issued, or that if certain
conditions are met, an answer is issued to the inquiry based on those
conditions. The conditions met are listed in the system reply list entries;
refer to the Add Reply List Entry (ADDRPYLE) command description for more
information.
*RQD: An answer is required for any inquiry message that occurs while a job is running under 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 there is an entry for any inquiry message issued as a result of running a job under this job description. If a match occurs, the reply value in that entry is used. If no entry exists for that message, the inquiry is issued.
- 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. *USRPRF: The printer device name for jobs using this description is obtained from the user profile of the job at the time 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 that is used with this job description.
- OUTQ
- Specifies the qualified name of the output queue.
*USRPRF: The output queue name for jobs using this job description is obtained from the user profile of 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 qualified name of the default output queue that is used with this job description.
If the output queue does not exist when the job description is created, a library qualifier must be specified because the 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.
*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 to the job that uses this job
description when the job is started.
*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 that is used as the job date for the job being started. The format that is currently specified for the system value QDATFMT must be used. The QDATFMT system value is in the Work Management
book.
- SWS
- Specifies the initial settings for a group of eight job switches used by
jobs that use this job description. Only zeros (off) and ones (on) can be used.
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
could be called. The job switches may also be valid in other high-level
language (HLL) programs.
00000000: The first setting for the job switches is all zeros for jobs that use this job description.
switch-settings: Specify any combination of eight zeros and ones that is used as the first switch setting for jobs using this job description.
- DEVRCYACN
- Specifies the recovery action to take for the job when an input/output
error is encountered on the *REQUESTER device for interactive jobs that use
this job description.
Note: This attribute is ignored for non-interactive jobs. *SYSVAL: The system value, QDEVRCYACN, is used as the device recovery action for this job description.
*MSG: The application program requesting the input/output operation receives an error message that indicates 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 screen prior to the error must be redisplayed.
*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 no request processor is available, the ENDRQS command fails, and the 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 they reach the end of the time slice.
*SYSVAL: The value in QTSEPOOL (system value) at the time the job is started 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.
- AUT
- Specifies the authority given to users who do not have specific authority
to the job description, who are not on an authorization list, and whose user
group has no specific authority to the job description. More information on
this parameter is in Commonly used
parameters.
*LIBCRTAUT: The public authority for the job description is taken from the value on the CRTAUT parameter of the target library (the library that is to contain the job description). The public authority is determined when the job description is created. If the CRTAUT value for the library changes after the job description is created, the new value does not affect any existing objects.
*CHANGE: The user can perform all operations on the object except those limited to the owner or controlled by object existence authority and object management authority. The user can change and perform basic functions on the object. Change authority provides object operational authority and all data authority.
*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the job description.
*USE: The user can perform basic operations on the job description, such as displaying its contents or using the job description to start a job. The user cannot change the job description. *USE authority provides object operational authority, read authority, and execute authority.
*EXCLUDE: The user cannot access the job description.
authorization-list-name: Specify the name of the authorization list used.
- TEXT
- Specifies the text that briefly describes the job description. More
information on this parameter is in Commonly
used parameters.
*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.
*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.
*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.
*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.
*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.
*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 CRTJOBD
Example 1: Creating a Job Description for Interactive Jobs
CRTJOBD JOBD(INT4) USER(*RQD)
RTGDTA(QCMDI) INQMSGRPY(*SYSRPYL)
TEXT('Interactive #4 job description
for Department 127')
This command creates a job description named INT4 in the user's current library. This job description is for interactive jobs and is used by Department 127. When you sign on, type your password. The characters QCMDI are used as routing data that is compared with the routing table of the subsystem where the job is run. All inquiry messages are compared to the entries in the system reply list to determine whether a reply is issued automatically.
Example 2: Creating a Job Description for Jobs on a Specified Queue
CRTJOBD JOBD(BATCH3) USER(*RQD)
JOBQ(NIGHTQ) JOBPTY(4) OUTPTY(4)
ACGCDE(NIGHTQ012345)
RTGDTA(QCMDB) TEXT('Batch #3 job
description for high pty night work')
This command creates a job description named BATCH3 in the user's current library. The jobs using this description are placed on the job queue NIGHTQ. The priority for jobs using this description and their spooled output is 4. QCMDB is the routing data that is compared with entries in the routing table of the subsystem where the job runs. The accounting code of NIGHTQ012345 is used when recording accounting statistics for jobs that use this job description.
Example 3: Specifying Request Data
CRTJOBD JOBD(PAYWK) USER(QPGMR) RTGDTA(QCMDB)
RQSDTA('CALL PAY025 PARM(WEEKLY UNION)')
This command creates a job description named PAYWK in the user's current library. Jobs using this job description run under the IBM-supplied user profile for the programmer, QPGMR, and use the accounting code found in that user profile. If the job is started via the SBMJOB command, the accounting code of the person submitting the command is automatically used. The routing data QCMDB is compared with entries in the routing table of the subsystem where the job is run. The request data passed to the command processing program is a CALL command that names the application program that is run and passes a parameter to it.
Error messages for CRTJOBD
*ESCAPE Messages
- CPF1621
- Job description &1 not created in library &2.