| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified job description name | Input | Char(20) |
| 5 | Error code | I/O | Char(*) |
The Retrieve Job Description Information (QWDRJOBD) API retrieves information from a job description object and places it into a single variable in the calling program. The amount of information returned depends on the size of the variable. The information returned is the same information returned by the Display Job Description (DSPJOBD) command.
The variable that is to receive the information requested. You can specify the size of this area to be smaller than the format requested if you specify the length of receiver variable parameter correctly. As a result, the API returns only the data that the area can hold.
The length of the receiver variable. If this value is larger than the actual size of the receiver variable, the result may not be predictable. The minimum length is 8 bytes.
The format of the job description information to be returned. You can use this format:
| JOBD0100 | Basic job description information. For details, see JOBD0100 Format. |
The name of the job description whose contents are to be retrieved. The first 10 characters contain the name of the job description, and the second 10 characters contain the name of the library where the job description is located. You can use these special values for the library name:
| *CURLIB | The job's current library |
| *LIBL | The library list |
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following table describes the information that is returned in the receiver variable for the JOBD0100 format. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Job description name |
| 18 | 12 | CHAR(10) | Job description library name |
| 28 | 1C | CHAR(10) | User name |
| 38 | 26 | CHAR(8) | Job date |
| 46 | 2E | CHAR(8) | Job switches |
| 54 | 36 | CHAR(10) | Job queue name |
| 64 | 40 | CHAR(10) | Job queue library name |
| 74 | 4A | CHAR(2) | Job queue priority |
| 76 | 4C | CHAR(10) | Hold on job queue |
| 86 | 56 | CHAR(10) | Output queue name |
| 96 | 60 | CHAR(10) | Output queue library name |
| 106 | 6A | CHAR(2) | Output queue priority |
| 108 | 6C | CHAR(10) | Printer device name |
| 118 | 76 | CHAR(30) | Print text |
| 148 | 94 | BINARY(4) | Syntax check severity |
| 152 | 98 | BINARY(4) | End severity |
| 156 | 9C | BINARY(4) | Message logging severity |
| 160 | A0 | CHAR(1) | Message logging level |
| 161 | A1 | CHAR(10) | Message logging text |
| 171 | AB | CHAR(10) | Logging of CL programs |
| 181 | B5 | CHAR(10) | Inquiry message reply |
| 191 | BF | CHAR(13) | Device recovery action |
| 204 | CC | CHAR(10) | Time-slice end pool |
| 214 | D6 | CHAR(15) | Accounting code |
| 229 | E5 | CHAR(80) | Routing data |
| 309 | 135 | CHAR(50) | Text description |
| 359 | 167 | CHAR(1) | Reserved |
| 360 | 168 | BINARY(4) | Offset to initial library list |
| 364 | 16C | BINARY(4) | Number of libraries in initial library list |
| 368 | 170 | BINARY(4) | Offset to request data |
| 372 | 174 | BINARY(4) | Length of request data |
| 376 | 178 | BINARY(4) | Job message queue maximum size |
| 380 | 17C | CHAR(10) | Job message queue full action |
| 390 | 186 | CHAR(10) | CYMD job date |
| 400 | 190 | CHAR(10) | Allow multiple threads |
| 410 | 19A | CHAR(10) | Spooled file action |
| 420 | 1A4 | BINARY(4) | Offset to initial ASP group information |
| 424 | 1A8 | BINARY(4) | Number of initial ASP group information entries |
| 428 | 1AC | BINARY(4) | Length of one initial ASP group information entry |
| 432 | 1B0 | CHAR(10) | DDM conversation |
| 442 | 1BA | CHAR(10) | Job log output |
| 452 | 1C4 | CHAR(*) | Reserved |
| * | * | ARRAY (*) of CHAR(11) | Initial library list |
| * | * | CHAR(*) | Request data |
| Array(*) of CHAR(*) | Initial ASP group information entry | ||
The initial auxiliary storage pool (ASP) group information entry describes the data that is returned for each group in the job description's initial ASP group.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| The fields repeat for each entry returned in the initial ASP group information. | CHAR(10) | ASP group name | |
| CHAR(*) | Reserved | ||
Accounting code. An identifier assigned to jobs that use this job description. This code is used to collect system resource use information. If the special value *USRPRF is specified, the accounting code used for jobs using this job description is obtained from the job's user profile.
Allow multiple threads. Whether or not the job is allowed to run with multiple user threads. This attribute does not prevent the operating system from creating system threads in the job. The possible values are *YES and *NO. This 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 by 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 that are used exclusively with functions that create multiple user threads.
ASP group name. The name of the ASP group. This is the name of the primary ASP device in an ASP group or the name of an ASP device description. This specifies the initial ASP group setting for jobs using this job description.
Bytes available. The length of all data available to return. All available data is returned if enough space is provided.
Bytes returned. The length of all data actually returned. If the data is truncated because the receiver variable was not sufficiently large to hold all of the data available, this value will be less than the bytes available.
CYMD job date. The date that will be assigned to jobs using this job description when they are started. The possible values are:
| *SYSVAL | The value in the QDATE system value is used at the time the job is started. |
| job-date | The date to be used at the time the job is started. The format of the field returned in CYYMMDD where C is the century, YY is the year, MM is the month, and DD is the day. A 0 for the century indicates years 19xx and a 1 indicates years 20xx. The field is padded on the right with blanks. |
DDM conversation. Whether the Distributed Data Management conversations are kept or dropped when they are not being used. The possible values are:
| *KEEP | The system keeps DDM conversation connections active when there are no users. |
| *DROP | The system ends a DDM-allocated conversation when there are no users. |
Device recovery action. The action to take when an I/O error occurs for the interactive job's requesting program device. The possible values are:
| *SYSVAL | The value in the system value QDEVRCYACN at the time the job is started is used as the device recovery action for this job description. |
| *MSG | Signals the I/O error message to the application and lets the application program perform error recovery. |
| *DSCMSG | Disconnects the job when an I/O error occurs. When the job reconnects, the system sends a message to the application program, indicating the job has reconnected and that the workstation device has recovered. |
| *DSCENDRQS | Disconnects the job when an I/O error occurs. When the job reconnects, the system sends the End Request (ENDRQS) command to return control to the previous request level. |
| *ENDJOB | Ends the job when an I/O error occurs. A message is sent to the job's log and to the history log (QHST). This message indicates that the job ended because of a device error. |
| *ENDJOBNOLIST | Ends the job when an I/O error occurs. There is no job log produced for the job. The system sends a message to the history log (QHST). This message indicates that the job ended because of a device error. |
End severity. The message severity level of escape messages that can cause a batch job to end. The batch job ends when a request in the batch input stream sends an escape message, whose severity is equal to or greater than this value, to the request processing program. The possible values are from 0 through 99.
Hold on job queue. Whether jobs using this job description are put on the job queue in the hold condition. The possible values are *YES and *NO.
Initial ASP group information. The list of initial ASP groups for jobs that use this job description. This does not include the system ASP or basic user ASPs.
Initial library list. The initial library list that is used for jobs that use this job description. Only the libraries in the user portion of the library list are included.
Note: The data is an array of 11-byte entries, each entry consisting of a 10-byte library name that is left-justified with a blank pad at the end. The 11-byte entries can be easily used in CL commands. The number of libraries in the initial library list tells how many entries are contained in the array.
Inquiry message reply. How inquiry messages are answered for jobs that use this job description.
| *RQD | The job requires an answer for any inquiry messages that occur while the job is running. |
| *DFT | The system uses the default message reply to answer any inquiry messages issued while the job is running. The default reply is either defined in the message description or is the default system reply. |
| *SYSRPYL | The system reply list is checked to see if there is an entry for an inquiry message issued while the job is running. If a match occurs, the system uses the reply value for that entry. If no entry exists for that message, the system uses an inquiry message. |
Job date. The date that will be assigned to jobs using this job description when they are started. The possible values are:
| *SYSVAL | The value in the QDATE system value is used at the time the job is started. |
| job-date | The date to be used at the time the job is started. This date is in the format specified for the DATFMT job attribute. |
Job description library name. The name of the library in which the job description resides.
Job description name. The name of the job description about which information is being returned.
Job log output. How the job log will be produced when the job completes. This does not affect job logs produced when the message queue is full and the job message queue full action specifies *PRTWRAP. Messages in the job message queue are written to a spooled file, from which the job log can be printed, unless the Control Job Log Output (QMHCTLJL) API was used in the job to specify that the messages in the job log are to be written to a database file.
The job log output value can be changed at any time until the job log has been produced or removed. To change the job log output value for a job, use the Change Job (QWTCHGJB) API or the Change Job (CHGJOB) command.
The job log can be displayed at any time until the job log has been produced or removed. To display the job log, use the Display Job Log (DSPJOBLOG) command.
The job log can be removed when the job has completed and the job log has not yet been produced or removed. To remove the job log, use the Remove Pending Job Log (QWTRMVJL) API or the End Job (ENDJOB) command.
The possible values are:
| *SYSVAL | The value is specified by the QLOGOUTPUT system value. |
| *JOBLOGSVR | The job log will be produced by a job log server. For more information about job log servers, refer to the Start Job Log Server (STRLOGSVR) command. |
| *JOBEND | The job log will be produced by the job itself. If the job cannot produce its own job log, the job log will be produced by a job log server. For example, a job does not produce its own job log when the system is processing a Power Down System (PWRDWNSYS) command. |
| *PND | The job log will not be produced. The job log remains pending until removed. |
Job message queue maximum size. The maximum size (in megabytes) of the job message queue. The possible values are:
| 0 | The maximum size set by system value QJOBMSGMX at the time the job is started. |
| 2-64 | The maximum size of the job message queue in megabytes. |
Job message queue full action. The action taken when the job message queue becomes full. The possible values are:
| *SYSVAL | The value is specified by the system value QJOBMSGQFL. |
| *NOWRAP | When the message queue becomes full, do not wrap. This action will cause the job to end. |
| *WRAP | When the message queue becomes full, wrap to the beginning and start filling again. |
| *PRTWRAP | When the message queue becomes full, wrap the job queue and print the messages that are being overlaid. |
Job queue library name. The library of the job queue into which batch jobs using this job description are placed.
Job queue name. The name of the job queue into which batch jobs using this job description are placed.
Job queue priority. The scheduling priority of each job that uses this job description. The highest priority is 1 and the lowest priority is 9.
Job switches. The initial settings for a group of eight job switches used by jobs that use this job description. These switches can be set or tested in a program and used to control a program's flow. The possible values are '0' (off) and '1' (on).
Length of one initial ASP group information entry. The length of one initial ASP group information entry. Zero indicates that jobs using this job description do not have an initial ASP group.
Length of request data. The length of all available request data, in bytes. If the receiver variable was not sufficiently large to hold all of the request data available, the amount of request data actually returned may be less than this value.
Logging of CL programs. Whether or not commands are logged for CL programs that are run. The possible values are *YES and *NO.
Message logging level. The type of information logged. Possible types 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 indication of job start, job end and job completion status. |
| 2 | The following information is logged:
|
| 3 | The following information is logged:
|
| 4 | The following information is logged:
|
Message logging severity. The severity level that is used in conjunction with the logging level to determine which error messages are logged in the job log. The possible values are from 0 through 99.
Message logging text. The level of message text that is written in the job log when a message is logged according to the logging level and logging severity. The possible values are:
| *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. |
Number of initial ASP group information entries. The number of entries in the job description's initial ASP group information. Zero indicates that jobs using this job description do not have an initial ASP group.
Number of libraries in initial library list. The number of libraries in the user portion of the initial library list.
Offset to initial ASP group information. The offset in characters (bytes) from the beginning of the structure to the first ASP group information entry. Zero indicates that jobs using this job description do not have an initial ASP group.
Offset to initial library list. The offset from the beginning of the structure to the start of the initial library list.
Offset to request data. The offset from the beginning of the structure to the start of the request data.
Output queue library name. The name of the library in which the output queue resides.
Output queue name. The name of the default output queue that is used for spooled output produced by jobs that use this job description.
| *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 with the same name as the printer device for this job description is used. |
| *WRKSTN | The output queue name is obtained from the device description from which this job is started. |
| output-queue-name | The name of the output queue for this job description. |
Output queue priority. 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.
Print text. The line of text (if any) that is printed at the bottom of each page of printed output for jobs using this job description. If the special value *SYSVAL is specified, the value in the system value QPRTTXT is used for jobs using this job description.
Printer device name. The name of the printer device or the source for the name of the printer device that is used for all spooled files created by jobs that use this job description.
| *USRPRF | The printer device name is obtained from the user profile of the job at the time the job is started. |
| *SYSVAL | The value in the system value QPRTDEV at the time the job is started is used as the printer device name. |
| *WRKSTN | The printer device name is obtained from the work station where the job was started. |
| printer-device-name | The name of the printer device that is used with this job description. |
Request data. The request data that is placed as the last entry in the job's message queue for jobs that use this job description. The possible values are:
| *NONE | No request data is placed in the job's message queue. |
| *RTGDTA | The data specified in the routing data parameter is placed as the last entry in the job's message queue. |
| request-data | The request data to use for jobs that use this job description. |
Reserved. An ignored field.
Routing data. The routing data that is used with this job description to start jobs. The possible values are:
| 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 request data field are used as the routing data for the job. |
| routing-data | The routing data to use for jobs that use this job description. |
Spooled file action. Specifies whether spooled files can be accessed through job interfaces once a job has completed its normal activity.
| *KEEP | When the job completes its activity, as long as at least one spooled file for the job exists in the system auxiliary storage pool (ASP 1) or in a basic user ASP (ASPs 2-32), the spooled files are kept with the job and the status of the job is updated to indicate that the job has completed. If all remaining spooled files for the job are in independent ASPs (ASPs 33-255), the spooled files will be detached from the job and the job will be removed from the system. |
| *DETACH | Spooled files are detached from the job when the job completes its activity. |
| *SYSVAL | The jobs using this job description will take the spooled file action specified by the QSPLFACN system value. |
Syntax check severity. Whether requests placed on the job's message queue are checked for syntax as CL commands, and the message severity that causes a syntax error to end processing of a job. The possible values are:
| -1 | The request data is not checked for syntax as CL commands. This is equivalent to *NOCHK. |
| 0-99 | Specifies the lowest message severity that causes a running job to end. The request data is checked for syntax as CL commands, and, if a syntax error occurs that is greater than or equal to the error message severity specified here, the running of the job that contains the erroneous command is suppressed. |
Text description. The user text, if any, used to briefly describe the job description.
Time-slice end pool. Whether interactive jobs using this job description should be moved to another main storage pool when they reach time-slice end. The possible values are:
| *SYSVAL | The system value is used. |
| *NONE | The job is not moved when it reaches time-slice end. |
| *BASE | The job is moved to the base pool when it reaches time-slice end. |
User name. The name of the user profile associated with this job description. If *RQD is specified, a user name is required to use the job description.
| Message ID | Error Message Text |
|---|---|
| CPF1618 E | Job description &1 in library &2 damaged. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |