List Job Schedule Entries (QWCLSCDE) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | Job schedule entry name | Input | Char(10) |
| 4 | Continuation handle | Input | Char(16) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The List Job Schedule Entries (QWCLSCDE) API lists the entries in the job schedule, QDFTJOBSCD. A subset of the list can be created by using the job schedule entry name parameter. The generated list replaces any existing list in the user space.
The QWCLSCDE API produces a list similar to the list produced by the Work with Job Schedule Entries (WRKJOBSCDE) command.
Authorities and Locks
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
- User Space Lock
- *EXCLRD
- Job Schedule Entry Authority
- *JOBCTL or the adder of the entry if using format SCDL0200
- Job Schedule Authority
- *USE
- Job Schedule Library Authority
- *EXECUTE
- Job Schedule Lock
- *SHRRD
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The user space that is to receive the created list. The first 10 characters contain the user space name, and the second 10 characters contain the name of the library where the user space is located. You can use these special values for the library name:
*CURLIB The job's current library *LIBL The library list
- Format name
- INPUT; CHAR(8)
The content and format of the information returned for each member. The possible format names are:
SCDL0100 Basic job schedule entries list. SCDL0200 Detailed job schedule entries list. This format requires more processing than the SCDL0100 format. For more information, see SCDL0100 Format or SCDL0200 Format.
- Job schedule entry name
- INPUT; CHAR(10)
The job schedule entry about which to retrieve information. This can be used to create a subset of job schedule entries by using the following values:
*ALL All of the job schedule entries are returned in the list. generic* All of the job schedule entries beginning with the generic value are returned in the list. name The job schedule entries with the given name are returned in the list.
- Continuation handle
- INPUT; CHAR(16)
The value returned to the user in the header section when a partial list is returned. The possible values are:
blank This will start at the beginning of the list. value The entries after this value matching the job schedule entry name specified will be returned in the list. For more information on using this value to process a partial list, see Partial list considerations.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of the Generated Lists
The file member list consists of:
- A user area
- A generic header
- An input parameter section
- A header section
- A list data section:
- SCDL0100 format
- SCDL0200 format
For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections. For detailed descriptions of the fields in the list returned, see Field Descriptions.
When you retrieve list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid. For examples of how to process lists, see Examples: APIs and exit programs.
Input Parameter Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name |
| 10 | A | CHAR(10) | User space library name |
| 20 | 14 | CHAR(8) | Format name |
| 28 | 1C | CHAR(10) | Job schedule entry name |
| 44 | 2C | CHAR(16) | Continuation handle |
Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job schedule entry name used |
| 10 | A | CHAR(16) | Continuation handle |
SCDL0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Information status |
| 1 | 1 | CHAR(10) | Job name |
| 11 | B | CHAR(10) | Entry number |
| 21 | 15 | CHAR(10) | Scheduled date |
| 31 | 1F | CHAR(70) | Scheduled days |
| 101 | 65 | CHAR(6) | Scheduled time |
| 107 | 6B | CHAR(10) | Frequency |
| 117 | 75 | ARRAY(5) of CHAR(10) | Relative day of the month |
| 167 | A7 | CHAR(10) | Recovery action |
| 177 | B1 | CHAR(10) | Next submission date |
| 187 | BB | CHAR(10) | Status |
| 197 | C5 | CHAR(10) | Job queue name |
| 207 | CF | CHAR(10) | Job queue library name |
| 217 | D9 | CHAR(10) | User profile of entry adder |
| 227 | E3 | CHAR(10) | Last submission date |
| 237 | ED | CHAR(6) | Last submission time |
| 243 | F3 | CHAR(50) | Text |
| 293 | 125 | CHAR(23) | Reserved |
SCDL0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Returns everything from format SCDL0100 | |
| 316 | 13C | CHAR(10) | Job queue status |
| 326 | 146 | ARRAY(20) of CHAR(10) | Dates omitted |
| 526 | 20E | CHAR(10) | Job description name |
| 536 | 218 | CHAR(10) | Job description library name |
| 546 | 222 | CHAR(10) | User profile for submitted job |
| 556 | 22C | CHAR(10) | Message queue name |
| 566 | 236 | CHAR(10) | Message queue library name |
| 576 | 240 | CHAR(10) | Save entry |
| 586 | 24A | CHAR(10) | Last submission job name |
| 596 | 254 | CHAR(10) | Last submission user name |
| 606 | 25E | CHAR(6) | Last submission job number |
| 612 | 26E | CHAR(10) | Last attempted submission date |
| 622 | 26E | CHAR(6) | Last attempted submission time |
| 628 | 274 | CHAR(10) | Status of last attempted submission |
| 638 | 27E | CHAR(2) | Reserved |
| 640 | 280 | BINARY(4) | Length of command string |
| 644 | 284 | CHAR(512) | Command |
Field Descriptions
Command. A command that runs in the submitted batch job if the routing program used when this batch job is started is the IBM-supplied default routing program QCMD. Because this command is used for the request data, this parameter takes the place of any value specified for the RQSDTA parameter in the job description.
Continuation handle. The value used to process a partial list. This value is put in the header section when a partial list is returned. For more information on processing a partial list, see Partial list considerations.
Dates omitted. Specifies up to 20 dates when the job should not be submitted. The dates will be in the format CYYMMDD, where C is the century, YY is the year, MM is the month, and DD is the day. A 0 for the century flag indicates years 19xx and a 1 indicates years 20xx. If no omit dates are specified, this field contains hexadecimal zeros.
Entry number. The entry number assigned to the job schedule entry. The entry number can range from 000001 through 999999.
Format name. The content and format of the information returned for each job schedule entry.
Frequency. How often the job schedule entry is to be submitted to run. Valid values are:
| *ONCE | The job schedule entry does not repeat. |
| *WEEKLY | The job schedule entry is submitted on the same day of each week at the scheduled time. |
| *MONTHLY | The job schedule entry is submitted on the same day of each month at the scheduled time. |
Information status. Whether or not the entry information could be successfully retrieved.
| blank | No errors occurred. All information is returned for this entry. |
| A | Insufficient authority to entry. Only the SCDL0100 information is returned for this entry. The rest of the entry is blank. |
| L | The entry is locked. Only the SCDL0100 information is returned for this entry. The rest of the entry is blank. |
Job description name. The name of the job description used for the job schedule entry.
| *USRPRF | The job description in the user profile under which the job runs is used as the job description of the job schedule entry. |
| job description name | The name of the job description used for the job schedule entry. |
Job description library name. The name of the library in which the job description is located.
Job name. The job name associated with the job schedule entry.
Job queue library name. The name of the library in which the specified job queue resides.
Job queue name. The name of the job queue where the job should be placed when it is submitted. Valid values are:
| *JOBD | The job is placed in the job queue named in the specified job description. |
| job queue name | The name of the job queue where the job is placed when it is submitted. |
Job queue status. The current status of the job queue. Valid values are:
| blank | The job queue name specified *JOBD, the job queue could not be found, or the job queue is damaged. |
| HLD | The job queue is held. The job queue is not allocated to a subsystem. |
| RLS | The job queue is released. The job queue is not allocated to a subsystem. |
| HLD/SBS | The job queue is held. The job queue is allocated to a subsystem. |
| RLS/SBS | The job queue is released. The job queue is allocated to a subsystem. |
| LOCKED | The job queue is locked, and the status could not be obtained. |
Job schedule entry name used. The job name used to identify the job schedule entry.
Last attempted submission date. The date on which a job could have been last submitted. The value is returned in the format CYYMMDD, where C is the century, YY is the year, MM is the month, and DD is the day. A 0 for the century flag indicates years 19xx and a 1 indicates years 20xx. If no submission has been attempted, this field contains hexadecimal zeros.
Last attempted submission time. The time at which a job could have been last submitted from this entry. The value is returned in the format HHMMSS, where HH is hours, MM is minutes, and SS is seconds. If no submission has been attempted, this field contains hexadecimal zeros.
Last submission date. The date on which a job was last submitted from this entry. The value is returned in the format CYYMMDD, where C is the century, YY is the year, MM is the month, and DD is the day. A 0 for the century flag indicates years 19xx and a 1 indicates years 20xx. If there has been no previous submission, this field contains hexadecimal zeros.
Last submission job name. The job name of the last job that was submitted from this entry. If there has been no previous submission, this field contains blanks.
Last submission job number. The job number of the last job that was submitted from this entry. If there has been no previous submission, this field contains blanks.
Last submission time. The time at which a job was last submitted from this entry. The value is returned in the format HHMMSS, where HH is hours, MM is minutes, and SS is seconds. If there has been no previous submission, this field contains hexadecimal zeros.
Last submission user name. The user name of the last job that was submitted from this entry. If there has been no previous submission, this field contains blanks.
Length of command string. The length of the command string specified in the command field.
Message queue name. The name of the message queue, if any, to which a completion message is sent when the job is submitted. A completion message is sent when the submitted job has completed running, and error messages are sent if the Submit Job (SBMJOB) command fails for some reason. Valid values are:
| *USRPRF | A completion message is sent to the message queue specified in the user profile associated with the job schedule entry. |
| *NONE | Messages are not sent to a user-specified message queue. In this case, completion messages are not sent, but error messages are sent to the QSYSOPR message queue. |
| message queue name | The name of the message queue where the messages are sent. |
Message queue library name. The library in which the message queue is located.
Next submission date. The next date that a job from this entry is scheduled to be submitted. The next submission date is returned in the format CYYMMDD, where C is the century, YY is the year, MM is the month, and DD is the day. A 0 for the century flag indicates years 19xx and a 1 indicates years 20xx. If this entry has a status of SAV, this field contains hexadecimal zeros.
Recovery action. The action that will happen if the job cannot be submitted at the designated time because the system is powered down or the system is in the restricted state. The action specified by this parameter then occurs when the system is IPLed or when the system comes out of the restricted state. This parameter does not pertain to the situation where a job was held (by the user) when the designated time elapsed and then released (by the user) at a later time. Also, the recovery action does not pertain to timer events that elapse as a result of changes to the QTIME system value. Valid values are:
| *SBMRLS | Submit the job in the released state (RLS). |
| *SBMHLD | Submit the job in the held state (HLD). |
| *NOSBM | No job is submitted. |
Relative day of the month. The relative day of the month the job should be submitted to run. A total of five values can be returned. If no relative day of the month was specified, this area contains blanks. Valid values are:
| 1-5 | The job should be submitted on the specified day of the week every first, second, third, fourth, or fifth week of the month. |
| *LAST | The job should be submitted on the last specified day of the week each month. |
Reserved. An ignored field.
Save entry. Whether or not an entry that has FRQ(*ONCE) specified should be kept in the job schedule after the job has been submitted.
| *NO | This entry will not be kept after the job is submitted. |
| *YES | This entry will be kept after the job is submitted. |
Scheduled date. The date that the job will be submitted. Valid values are:
| *CURRENT | The current date will be used. |
| *MONTHSTR | The first day of the month will be used. |
| *MONTHEND | The last day of the month will be used. |
| *NONE | A scheduled date was not specified. |
| date | An actual date in the format CYYMMDD, where C is the century, YY is the year, MM is the month, and DD is the day. A 0 for the century flag indicates years 19xx and a 1 indicates years 20xx. |
Scheduled days. The day of the week that the job will be submitted. A total of seven values can be returned. Valid values are:
| *ALL | The job will be submitted every day. This cannot be specified with any other values. |
| *NONE | A scheduled day is not specified. This cannot be specified with any other values. |
| *MON | The job will be submitted on Monday. |
| *TUE | The job will be submitted on Tuesday. |
| *WED | The job will be submitted on Wednesday. |
| *THU | The job will be submitted on Thursday. |
| *FRI | The job will be submitted on Friday. |
| *SAT | The job will be submitted on Saturday. |
| *SUN | The job will be submitted on Sunday. |
Scheduled time. The time (on the scheduled date) when the job will be submitted to run. This value is returned in the format HHMMSS, where HH is the hours, MM is the minutes, and SS is the seconds.
Status. The status of the job schedule entry. Valid values are:
| SCD | The entry is scheduled. |
| HLD | The entry is held. |
| SAV | The entry is saved. |
Status of last attempted submission. The action that occurred the last time the system could have submitted a job from this entry. Valid values are:
| 0 | Job not previously submitted. |
| 1 | Job successfully submitted. |
| 2 | Last job submission failed. Check the message queue for details. |
| 3 | Job not submitted due to held status. |
| 4 | Job submitted after scheduled time as specified by recovery action. |
| 5 | Job not submitted as specified by recovery action. |
Text. Text that briefly describes the job schedule entry. If no text was specified, this field contains blanks.
User profile for submitted job. The user profile under which the job will be submitted. Valid values are:
| *JOBD | The user profile named in the specified job description is used for the job. |
| user name | The name of the user profile that is used for the job. |
User profile of entry adder. The user profile that created this entry.
User space library name. The library name or special value specified in the call to this API.
User space name. The name of the user space that receives the list.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1629 E | Not authorized to job schedule &1. |
| CPF1632 E | Job schedule entry &3 number &4 damaged. |
| CPF1637 E | Job schedule &1 in library &2 in use. |
| CPF1640 E | Job schedule &1 in library &2 does not exist. |
| CPF1641 E | Job schedule &1 in library &2 damaged. |
| CPF1643 E | Job schedule entry name not valid. |
| 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. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF811A E | User space &4 in &9 damaged. |
| CPF812C E | Job schedule &4 in &9 damaged. |
| CPF8122 E | &8 damage on library &4. |
| 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. |
| 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. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R2