Batch Job (BCHJOB)

The Batch Job (BCHJOB) command indicates the beginning of a batch job in a batch input stream. It can also specify different values for the attributes for the job instead of the ones specified in the job description or user profile for this job. The values contained in the job description or in the user profile named in that job description are used for most parameters not coded in the BCHJOB command.

Restrictions:

The user that issues the Start Data Base Reader (STRDBRDR), Submit Data Base Jobs (SBMDBJOB), Start Diskette Reader (STRDKTRDR), or Submit Diskette Jobs (SBMDKTJOB) command is considered the user issuing the the BCHJOB command.

  1. To use this command, the user that issues the BCHJOB command must have:
    • use (*USE) authority to the job description (JOBD) and execute (*EXECUTE) authority to the library that contains that job description.
    • use (*USE) authority to the job queue (JOBQ) and execute (*EXECUTE) authority to the library that contains that job queue.
    • use (*USE) authority to all libraries specified for the system value QSYSLIBL, the Current library (CURLIB) parameter, and the Initial library list (INLLIBL) parameter.
    • use (*USE) and add (*ADD) authority to the message queue (MSGQ) and execute (*EXECUTE) authority to the library. that contains that message queue.
    • use (*USE) authority to the user profile in the job description.
    • execute (*EXECUTE) authority to all of the device descriptions in the auxiliary storage pool (ASP) group of the job's name space.
  2. The user specified in the job description of the submitted job must have:
    • use (*USE) authority to the job description (JOBD).
    • read (*READ) authority to the output queue (OUTQ) and execute (*EXECUTE) authority to the library that contains that output queue.
    • use (*USE) authority to all libraries specified for the system value QSYSLIBL, the Current library (CURLIB) parameter, and the Initial library list (INLLIBL) parameter.
    • use (*USE) authority to the sort sequence table (SRTSEQ) and execute (*EXECUTE) authority to the library that contains that sort sequence table.
    • use (*USE) authority to all of the device descriptions in the Initial ASP group (INLASPGRP) of the job description.
  3. The BCHJOB command cannot be used from a work station.
  4. Two slashes must precede this command name when entering it in the data record: //BCHJOB or // BCHJOB. (The user can separate the slashes from the command name with blank spaces).
  5. The current value of the auxiliary storage pool (ASP) group for the thread issuing the Submit Data Base Jobs (SBMDBJOB) or Submit Diskette Jobs (SBMDKTJOB) command is used for the initial ASP group parameter of the submitted batch job. Similarly, the current value of the ASP group for the thread issuing the Start Data Base Reader (STRDBRDR) or Start Diskette Reader (STRDKTRDR) command is used for the initial ASP group parameter of the spool reader job and is used for the initial ASP group parameter of the submitted batch job. The initial ASP group value in the job description is ignored. The processing of the BCHJOB command and the processing of spool reader functions such as syntax checking must operate in the name space used by the batch job.

Parameters

Keyword Description Choices Notes
JOB Job name Name, *JOBD Optional, Positional 1
JOBD Job description Qualified object name Optional, Positional 2
Qualifier 1: Job description Name, QBATCH
Qualifier 2: Library Name, *LIBL, *CURLIB
JOBQ Job queue Single values: *RDR, *JOBD
Other values: Qualified object name
Optional, Positional 3
Qualifier 1: Job queue Name
Qualifier 2: Library Name, *LIBL, *CURLIB
PRTDEV Print device Name, *USRPRF, *SYSVAL, *JOBD Optional
OUTQ Output queue Single values: *USRPRF, *DEV, *JOBD
Other values: Qualified object name
Optional
Qualifier 1: Output queue Name
Qualifier 2: Library Name, *LIBL, *CURLIB
JOBPTY Job priority (on JOBQ) 1-9, *JOBD Optional, Positional 4
OUTPTY Output priority (on OUTQ) 1-9, *JOBD Optional, Positional 5
PRTTXT Print text Character value, *JOBD, *BLANK, *SYSVAL Optional
RTGDTA Routing data Character value, QCMDB, *JOBD, *RQSDTA Optional
RQSDTA Request data or command Character value, *, *JOBD, *NONE, *RTGDTA Optional
SYNTAX CL syntax check 0-99, *JOBD, *NOCHK Optional
CURLIB Current library Name, *USRPRF, *CRTDFT Optional
INLLIBL Initial library list Single values: *JOBD, *SYSVAL, *NONE
Other values (up to 25 repetitions): Name
Optional
ENDSEV End severity 0-99, *JOBD Optional
LOG Message logging Element list Optional
Element 1: Level 0-4, *JOBD
Element 2: Severity 0-99, *JOBD
Element 3: Text *JOBD, *MSG, *SECLVL, *NOLIST
LOGCLPGM Log CL program commands *JOBD, *NO, *YES Optional
INQMSGRPY Inquiry message reply *JOBD, *RQD, *DFT, *SYSRPYL Optional
HOLD Hold on job queue *JOBD, *NO, *YES Optional
DATE Job date Date, *JOBD, *SYSVAL Optional
SWS Job switches Character value, *JOBD Optional
MSGQ Message queue Single values: *NONE, *USRPRF
Other values: Qualified object name
Optional
Qualifier 1: Message queue Name
Qualifier 2: Library Name, *LIBL, *CURLIB
SRTSEQ Sort sequence Single values: *USRPRF, *SYSVAL, *HEX, *LANGIDUNQ, *LANGIDSHR
Other values: Qualified object name
Optional
Qualifier 1: Sort sequence Name
Qualifier 2: Library Name, *LIBL, *CURLIB
LANGID Language ID Character value, *USRPRF, *SYSVAL Optional
CNTRYID Country or region ID Character value, *USRPRF, *SYSVAL Optional
CCSID Coded character set ID 1-65535, *USRPRF, *SYSVAL, *HEX Optional
JOBMSGQMX Job message queue maximum size 2-64, *JOBD, *SYSVAL Optional
JOBMSGQFL Job message queue full action *JOBD, *SYSVAL, *NOWRAP, *WRAP, *PRTWRAP Optional

Job name (JOB)

Specifies the name that is associated with the job when it is processed by the system.

*JOBD
The simple name of the job description used with this job is the name of the job itself.
name
Specify the simple name of the job used while it is being processed by the system.

Job description (JOBD)

Specifies the job description used with the job.

Qualifier 1: Job description

QBATCH
The IBM-supplied job description QBATCH in library QGPL is used for the job. (The QGPL library must be in the library list used by the spooling reader that reads the job's input.)
name
Specify the name of the job description.

Qualifier 2: Library

*LIBL
All libraries in the library list are searched until a match is found. If the Initial library list (INLLIBL) parameter specifies *JOBD, the library list used to find the job description is the library list for the thread in which the BCHJOB command processing is done. If the INLLIBL parameter specifies a value other than *JOBD, the library list used to find the job description consists of the libraries named in the QSYSLIBL system value and the libraries specified by the INLLIBL parameter.
*CURLIB
If the INLLIBL parameter specifies *JOBD, the library list used to find the job description is the library list for the thread in which the BCHJOB command processing is done. The current library for the library list is searched. If no library is specified as the current library for the library list, the QGPL library is used. If the INLLIBL parameter specifies a value other than *JOBD, the QGPL library is used because the library list used to find the job description does not have a current library.
name
Specify the library where the job description is located.

Job queue (JOBQ)

Specifies the job queue in which this job is placed.

Single values

*RDR
The job queue specified in the Start Data Base Reader (STRDBRDR), Submit Data Base Jobs (SBMDBJOB), Start Diskette Reader (STRDKTRDR), or Submit Diskette Jobs (SBMDKTJOB) command that reads this job, is used.
*JOBD
The job queue named in the job description used with this job is used.

Qualifier 1: Job queue

name
Specify the name of the job queue.

Qualifier 2: Library

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

Print device (PRTDEV)

Specifies the name of the default printer device for this job.

*USRPRF
The printer device name specified for the job's user profile is used. The user profile is specified in the job description, which is specified on the Job description (JOBD) parameter. The printer device name is taken from the profile when this command is run.
*SYSVAL
The printer device specified in the system value, QPRTDEV, when this command is run is used.
*JOBD
The printer device specified in the job description is used.
name
Specify the name of the printer device used for this job.

Output queue (OUTQ)

Specifies the name of the default output queue that is used for spooled output produced by this job. This parameter only applies to spooled printer files that specify *JOB for the output queue.

Single values

*USRPRF
The output queue specified for the job's user profile is used. The user profile is specified in the job description, which is specified on the Job description (JOBD) parameter. The output queue name is taken from the profile when this command is run.
*DEV
The output queue associated with the printer device for the spooled file is used.
*JOBD
The output queue named in the job description used with this job is used.

Qualifier 1: Output queue

name
Specify the name of the output queue.

Qualifier 2: Library

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

Job priority (on JOBQ) (JOBPTY)

Specifies the job queue scheduling priority. The highest priority is 1 and the lowest priority is 9.

*JOBD
The scheduling priority specified in the job description is used.
1-9
Specify the scheduling priority.

Output priority (on OUTQ) (OUTPTY)

Specifies the output priority for spooled output files that are produced by this job. Valid values range from 1 through 9, where the highest priority is 1 and the lowest priority is 9.

*JOBD
The output priority specified in the job description is used.
1-9
Specify the priority of this job's output files.

Print text (PRTTXT)

Specifies the text that is printed at the bottom of each page of printed output and on separator pages.

*JOBD
The value specified in the job description is used.
*BLANK
No text is printed.
*SYSVAL
The print text is obtained from the system value, QPRTTXT.
character-value
Specify the character string that is printed at the bottom of each page. A maximum of 30 characters can be entered, enclosed in apostrophes if necessary.

Routing data (RTGDTA)

Specifies the routing data used to start the next routing step in the job. The routing data is used to determine the routing entry that identifies the program that the job runs.

QCMDB
The routing data used by the IBM-supplied batch subsystem to route batch jobs to the IBM-supplied control language processor QCMD is used.
*JOBD
The routing data used to start the first routing step is in the job description.
*RQSDTA
The first 80 characters of the request data specified in the Request data or command (RQSDTA) parameter of this command are also used as the routing data.
character-value
Specify the character string that is used as the routing data for starting the first routing step. A maximum of 80 characters can be entered, enclosed in apostrophes if necessary.

Request data or command (RQSDTA)

Specifies the request data that is placed as the last entry in this job's message queue. The request data can be a CL command to be run or a string of characters used by another program.

*
The data following this command is inserted into this job's message queue as request data. For example, the request data may be a group of CL commands that constitute the job.
*JOBD
The request data specified in the job description used by this job is placed as the last entry in this job's message queue.
*NONE
No request data is placed in the job's message queue.
*RTGDTA
The routing data in the Routing data (RTGDTA) parameter of this command is placed as the last entry in the job's message queue.
character-value
Specify the character string that is placed as the last entry in the job's message queue. A maximum of 256 characters can be entered, enclosed in apostrophes if necessary.

CL syntax check (SYNTAX)

Specifies whether requests placed on the job's message queue are checked for syntax as CL commands. When checking for syntax is specified, the commands are checked for syntax when they are submitted instead of when the job is run, providing an earlier diagnosis of syntax errors. This parameter is used only if an asterisk (*) is specified for the Request data or command (RQSDTA) parameter.

Restrictions:

*JOBD
The value in the job description used with this job determines whether the request data is checked for syntax and the message severity that is used.
*NOCHK
The request data for this job is not checked for syntax as CL commands.
0-99
Specify the lowest message severity that causes the running of the job to be suppressed. The request data is checked for syntax as CL commands. If a syntax error occurs with a severity that is equal to or greater than the error message severity specified, the running of the job that contains the command with errors is suppressed.

Current library (CURLIB)

Specifies the name of the current library associated with the job being run.

*USRPRF
The current library in the user profile, under which the batch job runs, is the current library for the batch job. The user profile is specified in the job description, which is specified on the Job description (JOBD) parameter.
*CRTDFT
There is no current library for the batch job. If objects are created in the current library, QGPL is used as the default current library.
name
Specify the library that is used as the current library of the batch job.

Initial library list (INLLIBL)

Specifies the initial user part of the library list that is used to search for any object names that were specified without a library qualifier.

Note: Duplication of library names in the library list is not allowed.

Single values

*JOBD
The user library list in the job description used with this job is used as the initial user part of the library list.
*SYSVAL
The system default user library list is used. It contains the library names that were specified in the system value QUSRLIBL at the time that the job is started.
*NONE
The user portion of the initial library list is empty.

Other values (up to 25 repetitions)

name
Specify the names of one or more libraries that are the user portion of the library list and are used by this job. The libraries are searched in the same order as they are listed.

End severity (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 to the request processing program an escape message whose severity code is equal to or greater than that specified.

*JOBD
The severity limit specified in the job description used with this batch job determines when the job is ended.
0-99
Specify the message severity of an escape message that results from a request in the batch input stream and that causes the job to end. Because escape messages sent to users typically have a maximum severity level of 50, a value of 50 or lower must be specified for a job being ended as a result of an escape message. An escape message whose severity is equal to or greater than the value specified that is not handled causes the job to end.

Message logging (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.

Element 1: Level

*JOBD
The value specified for message logging level in the job description is used.
0-4
Specifies the message logging level used for this job's messages. The possible logging levels are:
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.

Note: 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.

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.
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.

Element 2: Severity

*JOBD
The value specified for message logging severity in the job description is used.
0-99
Specify the message severity that is used in conjunction with the logging level to determine which error messages are logged in the job log.

Element 3: Text

*JOBD
The value specified for message logging text in the job description is used.
*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.

Log CL program commands (LOGCLPGM)

Specifies whether the 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 *JOB has been specified for the Message logging (LOG) parameter in the Create CL Program (CRTCLPGM) command, the flag set in the Log CL program commands (LOGCLPGM) parameter is used. Other values for the Message logging (LOG) parameter override the Log CL program commands (LOGCLPGM) parameter. The commands are logged in the same manner as the requests.

*JOBD
The value in the job description is used.
*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.

Inquiry message reply (INQMSGRPY)

Specifies the way that predefined messages that are sent as a result of running this job are answered. You can specify that the inquiry message reply control is taken from the job description, or that all inquiry messages require a reply, or that a default reply is issued, or that the system reply list is checked for a matching reply as each predefined inquiry message is sent.

*JOBD
The inquiry message reply control specified in the job description used with this job is started.
*RQD
A reply is required by the receiver of the inquiry message for all inquiry messages that occur during the running of this job.
*DFT
The default message reply is used to answer any inquiry messages issued during the running of this job.
*SYSRPYL
The system reply list is checked to see if there is an entry for any inquiry message issued as a result of running this job that has a message identifier and any comparison data that match the inquiry message identifier and message data. If a match occurs, the reply value in that entry is used. If no entry exists for that message, a reply is required.

Hold on job queue (HOLD)

Specifies whether this job is held at the time that it is put on the job queue. A job placed on the job queue in the hold state is held until it is released by the Release Job (RLSJOB) command or ended, either by the End Job (ENDJOB) command or by the Clear Job Queue (CLRJOBQ) command.

*JOBD
The value specified in the job description determines whether this job is held when it is put on the job queue.
*NO
The job is not held when it is put on the job queue.
*YES
The job is held when it is put on the job queue until it is released or ended.

Job date (DATE)

Specifies the date that is assigned to the job when it is started.

*JOBD
The date specified in the job description is used.
*SYSVAL
The value in the QDATE system value at the time the job is started is used.
date
Specify the value that is used as the job date when the job is started. The value must be entered using the date format specified by the DATFMT job attribute.

Job switches (SWS)

Specifies the first settings for a group of eight job switches used with this job. These switches can be set or tested in a CL program and used to control the flow of the program. Only 0's (off) and 1's (on) can be specified in the 8-digit character string.

*JOBD
The value specified in the job description is the first settings for this job's switches.
character-value
Specify any combination of eight zeros and ones that is used as the first switch setting for this job.

Message queue (MSGQ)

Specifies the message queue to which a completion message is sent when the submitted job has completed running, either normally or abnormally. If an abnormal ending occurs, the help information for the completion message specifies the possible causes.

Single values

*NONE
No completion message is sent.
*USRPRF
The message queue specified on the user profile of the user submitting this job is used.

Qualifier 1: Message queue

name
Specify the name of the message queue where the completion message is sent.

Qualifier 2: Library

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

Sort sequence (SRTSEQ)

Specifies the sort sequence table to be used for string comparisons for this job.

Single values

*USRPRF
The sort sequence table specified for the job's user profile is used. The user profile is specified in the job description, which is specified on the Job description (JOBD) parameter.
*SYSVAL
The system value QSRTSEQ 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.

Qualifier 1: Sort sequence

name
Specify the name of the sort sequence table.

Qualifier 2: Library

*LIBL
All libraries in the new job's library list are searched until the first match is found.
*CURLIB
The current library for the new job is searched. If no library is specified as the current library for the job, the QGPL library is used.
name
Specify the library where the sort sequence table is located.

Language ID (LANGID)

Specifies the language identifier to be associated with this job. The language identifier is used when *LANGIDUNQ or *LANGIDSHR is specified on the Sort sequence (SRTSEQ) parameter. If the job CCSID is 65535, this parameter is also used to determine the value of the job default CCSID (DFTCCSID).

*USRPRF
The language ID specified for the job's user profile is used. The user profile is specified in the job description, which is specified on the Job description (JOBD) parameter.
*SYSVAL
The system value QLANGID is used.
character-value
Specify the language identifier to be used by the job.

Country or region ID (CNTRYID)

Specifies the country or region identifier to be used by the job.

*USRPRF
The country or region ID specified for the job's user profile is used. The user profile is specified in the job description, which is specified on the Job description (JOBD) parameter.
*SYSVAL
The system value QCNTRYID is used.
character-value
Specify the country or region identifier to be used by the job.

Coded character set ID (CCSID)

Specifies the coded character set identifier (CCSID) to be used for the job.

*USRPRF
The CCSID specified for the job's user profile is used. The user profile is specified in the job description, which is specified on the Job description (JOBD) parameter.
*SYSVAL
The CCSID specified for the system value QCCSID is used.
*HEX
The CCSID 65535 is used.
1-65535
Specify the CCSID.

Job message queue maximum size (JOBMSGQMX)

Specifies the maximum size of the job message queue.

*JOBD
The value specified in the job description determines the maximum size of the job message queue.
SYSVAL
The value in system value QJOBMSGQMX, at the time the job is started determines the maximum size of the job message queue.
2-64
Specify the maximum size, in megabytes, of the job message queue.

Job message queue full action (JOBMSGQFL)

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

*JOBD
The value specified in the job description determines the action that should be taken.
*SYSVAL
The value specified for the system value QJOBMSGQFL 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.

Examples

Example 1: Checking System Reply List for Inquiry Message Entries

BCHJOB   JOBD(PAYROLL)  INQMSGRPY(*SYSRPYL)

This command begins the batch job called PAYROLL. An inquiry message that is sent (as a result of running this job) that has an entry in the system reply list is answered according to the reply in that reply list entry. For any inquiry message not represented in the reply list, a reply is required.

The job name is the same as the name of the job description used with the job. The library search list of the thread in which the BCHJOB command is processed determines where the job description PAYROLL is found. The auxiliary storage pool (ASP) group of the thread in which the BCHJOB command is processed is used as the initial ASP group of the new job. Values for other job attributes are taken from the job description PAYROLL or from the user profile named in the job description PAYROLL.

Example 2: Setting Job Switches

BCHJOB   JOBD(QGPL/QBATCH)  JOB(PAYROLL)  JOBQ(BATCH2)
         INLLIBL(PAYLIB) SWS(00101100)  DATE(010188)

This command begins a batch job called PAYROLL, which is run using attributes from the IBM-supplied job description for batch jobs, QBATCH. The job is placed on the job queue BATCH2. The library PAYLIB is the only library in the user portion of the library list. Switches are set for use in the job, and the date is set at January 1, 1988.

Example 3: Specifying Severity Levels

BCHJOB   JOBD(COMPILE)  JOBPTY(5)  SYNTAX(10)
         INLLIBL(MYCMDS)  ENDSEV(40)

This command begins a batch job called COMPILE. The job is run using all of the attributes described in the job description also named COMPILE, except for the initial ASP group and the parameters that are specified by this command. The library MYCMDS is the only library in the user portion of the library list to be used when the commands are checked for syntax or run. Syntax errors with a value equal to or greater than 10 end processing of the job. The job is assigned a scheduling priority of 5 and is run as long as no errors are encountered that cause an escape message to be sent that has a severity level of 40 or higher.

Error messages

*ESCAPE Messages

CPF1374
BCHJOB command not valid in current environment.