BCHJOB (Batch Job)

BCHJOB Command syntax diagram

 

Purpose

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 used for the new 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. Because the spool reader and the batch job must operate in the same name space in order for functions such as syntax checking to operate correctly, the current value of the auxiliary storage pool (ASP) group of the spool reader is used for the initial ASP group parameter of the batch job and the value in the job description is ignored.

 

Restrictions

  1. The BCHJOB command cannot be used from a work station.

  2. Two slashes must precede this command name when entering it in the data record: 
    //BCHJOB

  3. The user can separate the slashes from this command name with blank spaces, for example: 
    //   BCHJOB.

 

Optional Parameters

JOB
Specifies the name 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.

job-name: Specify the job's simple name used during processing.

JOBD
Specifies the qualified name of the job description used with this job.

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

*LIBL: All libraries in the library list are searched until the first match is found. 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. 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.

library-name: Specify the name of the library to be searched.

QBATCH: The IBM-supplied job description, QBATCH, in the QGPL library 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.)

job-description-name: Specify the qualified name of the job description.

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

*RDR: The job queue specified in the start reader or submit jobs command that reads this job is the job queue used.

*JOBD: The job queue named in this job description is used.

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

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

library-name: Specify the name of the library to be searched.

job-queue-name: Specify the qualified name of the job queue on which the submitted job is placed.

JOBPTY
Specifies the scheduling priority of the job. 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.

*JOBD: The scheduling priority specified in the job description is used for this job.

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

OUTPTY
Specifies the output priority for spooled files that are produced by this job. The highest priority is 1 and the lowest priority is 9. More information is in Commonly used parameters.

*JOBD: The output priority specified in the job description is used for this job.

output-priority: Specify a value, ranging from 1 through 9, for the priority of this job's output files.

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.

*JOBD: The value specified in the job description is used.

*SYSVAL: The print text is obtained from the system value QPRTTXT.

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

RTGDTA
Specifies the routing data used to start the first routing step in the job. The routing data is used to determine the routing entry that identifies the program that is the process routing step.

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 in the job description used with this job, is used.

*RQSDTA: The request data (up to 80 characters), specified in the RQSDTA parameter of this command, is used.

'routing-data': Specify the character string that is used as the routing data for starting the first routing step. Up to 80 characters of text can be entered, enclosed in apostrophes if necessary.

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 run or a string of characters used by another program. For example, if RTGDTA(QCMDB) is specified, the IBM-supplied batch subsystem, QBATCH, is used, a CL command is supplied, and it becomes a message that is read by the control language processor, QCMD. Or, if a user program is specified in the routing entry, the request data can specify information, such as the record number of the first record in a file processed.

Note: If a value other than * is specified for this parameter, the data that follows the JOB command is ignored (it is not to be used as request data).

*: The data following this BCHJOB 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 RTGDTA parameter of this command 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. Up to of 256 characters can be entered, enclosed in apostrophes if necessary. If a CL command is entered, it must be enclosed in single apostrophes, and where apostrophes would normally be used inside the command, double apostrophes must be used.

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. If checking is specified, the message severity that causes a syntax error to end processing of a command is also specified. This parameter is used only if RQSDTA(*) is specified.

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

message-severity: Specify whether the request data is checked for syntax as CL commands, and, if a syntax error occurs 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. Specify a value, ranging from 00 through 99, for the lowest message severity that causes running of the job to be suppressed. More information on message severity is in Commonly used parameters.

CURLIB
Specifies the name of the library being used as the current library for jobs initiated by this user profile.

*USRPRF: The current library specified for the job's user profile is used as the current library for the job. The user profile is specified in the job description, which is specified on the JOBD parameter.

*CRTDFT: There is not a current library for the submitted job. If objects are created into the current library, the QGPL library is used as the default current library.

current-library-name: Specify the name of a library used as the current library for this job.

INLLIBL
Specifies the initial user library list that is used to search for any OS/400 system object names that were specified without a library qualifier.

Note: Duplicating libraries in the library list is not allowed.

*JOBD: The library list in the job description used with this job is used as the initial user library list.

*SYSVAL: The system default library list is used. It contains the library names that were specified in the system values, QSYSLIBL and QUSRLIBL, at the time that the job is started.

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

library-name: Specify the names of one or more libraries that are the user portion of the library list and are used by this job. No more than 25 names can be specified; the libraries are searched in the order in which they are listed.

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. (This type of end is considered an abnormal end.) 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.

*JOBD: The severity limit specified in the job description used with this batch job determines when the job is ended.

message-severity: Specify a value, ranging from 00 through 99, for 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 can be up to a severity level of 50, a value of 50 or lower may be specified for a job being ended 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.

Element 1: Message level

*JOBD: The value specified for message logging in the job description is used.

message-level: Specify a value, ranging from 0 through 4, that specifies the message logging level used for this job's messages. For more information on the message levels, refer to the message-level variable under the CRTJOBD command's LOG parameter.

Element 2: Message Severity

*JOBD: The value specified for message logging in the job description is used.

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

*JOBD: The value specified for message logging in the job description is used.

*MSG: Only 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 commands that can be logged are logged to the job log through 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 has been specified in the 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.

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

INQMSGRPY
Specifies the way that predefined messages are answered (that is, predefined messages that are sent as a result of running this job). The user can specify that no change is made in the way that predefined messages are answered, that all inquiry messages require a reply, that a default reply be issued, or that the system reply list is checked for a matching reply as each predefined inquiry message is sent. Refer to the Add Reply List Entry (ADDRPYLE) command description for more information.

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

PRTDEV
Specifies the qualified name of the default printer device for this job. If OUTQ(*DEV) is specified, the file is placed on an output queue with the same name as the printer.

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

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

*JOBD: The printer device name specified in the job description is used.

printer-device-name: Specify the name of the printer device used.

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.

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

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

*JOBD: The output queue named in the job description used with this job is the default output queue.

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

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

library-name: Specify the name of the library to be searched.

out-queue-name: Specify the name of the default output queue used by this job.

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.

*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 spooled file is held until released by the Release Spool File (RLSSPLF) command.

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.

job-date: Specify the date when the job is started. The value must be entered using the system date format specified by the system value, QDATFMT.

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. For example, if a certain switch is on, another program can be called. The job switches may also be valid in other high-level languages (HLL) programs. Only zeros (off) and ones (on) can be specified in the 8-digit character string.

*JOBD: The value specified in the job description is the first setting for this job's switches.

switch-settings: Specify any combination of eight zeros and ones that is used as the first switch setting for this job.

MSGQ
Specifies the qualified name of the message queue to which messages are sent.

Note: If an abnormal ending occurs, the help text of the completion message that is sent specifies the possible causes.

*NONE: No completion message is sent.

*USRPRF: The message queue specified on the user profile of the user submitting this job is used.

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

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

library-name: Specify the name of the library to be searched.

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

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

*USRPRF: The sort table specified for the job's user profile is used. The user profile is specified in the job description, which is specified on the 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.

The name of the sort sequence table can be qualified by one of the following library values:

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

library-name: Specify the name of the library to be searched.

table-name: Specify the name of the sort sequence table to be used with this job.

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 prompt (SORTSEQ 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 JOBD parameter.

*SYSVAL: The system value QLANGID is used.

language-ID: Specify the language identifier to be used by the job.

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

*SYSVAL: The system value QCNTRYID is used.

country-or-region-ID: Specify the country or region identifier to be used by the job.

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

A CCSID is a 16-bit number identifying a specific set of encoding scheme identifiers, character set identifiers, code page identifiers, and additional coding-related information that uniquely identifies the coded graphic representation used.

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

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

*HEX: The CCSID 65535 is used.

coded-character-set-id: Specify the CCSID. More information on valid CCSIDs is in the Globalization topic in the Information Center.

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 QJOBMSGQMX (system value), at the time the job is started, determines 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.

*JOBD: The value specified in the job description determines the action that should be taken.

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

Examples for BCHJOB

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. The inquiry message control attribute for the job is set to "*SYSRPYL". 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, which 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 changed 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 for BCHJOB

*ESCAPE Messages

CPF1374
BCHJOB command not valid in current environment.