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.

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.
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.
The BCHJOB command cannot be used from a work station.
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).
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

Top

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.

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.

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:

The Start Data Base Reader (STRDBRDR) and Start Diskette Reader (STRDKTRDR) commands support syntax checking. This provides the ability to check authorizations to commands.
The user must have use (*USE) authority to the command and execute (*EXECUTE) authority to the library that contains that command.

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

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.

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.

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.

Batch Job (BCHJOB)

Parameters

Job name (JOB)

Job description (JOBD)

Job queue (JOBQ)

Print device (PRTDEV)

Output queue (OUTQ)

Job priority (on JOBQ) (JOBPTY)

Output priority (on OUTQ) (OUTPTY)

Print text (PRTTXT)

Routing data (RTGDTA)

Request data or command (RQSDTA)

CL syntax check (SYNTAX)

Current library (CURLIB)

Initial library list (INLLIBL)

End severity (ENDSEV)

Message logging (LOG)

Log CL program commands (LOGCLPGM)

Inquiry message reply (INQMSGRPY)

Hold on job queue (HOLD)

Job date (DATE)

Job switches (SWS)

Message queue (MSGQ)

Sort sequence (SRTSEQ)

Language ID (LANGID)

Country or region ID (CNTRYID)

Coded character set ID (CCSID)

Job message queue maximum size (JOBMSGQMX)

Job message queue full action (JOBMSGQFL)

Examples

Error messages