Job Notification Exit Point
Required Parameter: None
QSYSINC Member Name: EJOBNTFY
Exit Point Name: QIBM_QWT_JOBNOTIFY
Exit Point Format Name: NTFY0100
The Job Notification exit point can be used to log notification messages to data queues when IBM® i jobs go through the following transitions:
- A job is placed on a job queue.
- A job starts.
- A job ends.
The QIBM_QWT_JOBNOTIFY exit point registers a data queue and library, rather than an exit program and library. The program data that is associated with the data queue must contain the notification type, subsystem description, and subsystem description library.
The information will be retrieved from the registration facility when the subsystem starts, so the data queues must be registered before starting the subsystem. Any queues added to the registration facility after a subsystem is started will not be retrieved until the next time the subsystem starts. The length of the data queue(s) is retrieved by the subsystem when it is started. If a data queue is deleted and recreated with a different length, the subsystem must be restarted in order to use the new data queue size. Otherwise, it will continue sending the same size message.
While multiple subsystems can use the same data queue, each subsystem is limited to using a maximum of eight data queues. If more than eight data queues are registered for a subsystem, the specific data queues that will be selected are undefined.
If a job is submitted to a job queue or ended from a job queue that is not allocated by an active subsystem, a job queue notification message will be sent to a default data queue of QSYSDTAQ in library QSYS.
Use the Create Data Queue (CRTDTAQ) command to create any data queues to be used by this function, including the QSYSDTAQ mentioned previously. See Data Queue Attributes for additional information about the attributes of the data queues.
For the format of the job start and job end notification messages, see Format of Job Start and Job End Notification Messages. For the format of the job queue notification messages, see Format of Job Queue Notification Messages.
Authorities and Locks
- Job Authority
- A user must have job control (*JOBCTL) special authority
to add a data queue to the registration facility
or to remove a data queue from the registration facility.
- Object Authority
- A user must have change (*CHANGE) authority to the data queue and execute (*EXECUTE) authority to the data queue library to add a data queue to the registration facility or to remove a data queue from the registration facility. If the data queue does not exist, a user must have all object (*ALLOBJ) special authority to add a data queue to the registration facility or to remove a data queue from the registration facility.
Required Parameter
None.
Program Data
When you register the data queue, the following is required for the program data.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(4) | Notification type |
| 4 | 4 | CHAR(10) | Subsystem description |
| 14 | E | CHAR(10) | Subsystem description library |
Field Descriptions
Notification type. The type of notifications that are to be sent to the data queue. The following values are supported:
| 0001 | Job start notifications are sent to this data queue. |
| 0002 | Job end notifications are sent to this data queue. |
| 0003 | Job start and job end notifications are sent to this data queue. |
| 0004 | Job queue notifications are sent to this data queue. |
| 0005 | Job start and job queue notifications are sent to this data queue. |
| 0006 | Job end and job queue notifications are sent to this data queue. |
| 0007 | Job start, job end, and job queue notifications are sent to this data queue. |
Subsystem description. The name of the subsystem description for which this data queue is to be used. The following special value is supported:
| *ANY | The data queue is used for all subsystems. When this value is specified, the subsystem description library is ignored. |
Subsystem description library. The name of the library that contains the subsystem description. The following special value is supported:
| *ANY | The data queue is used for any subsystems that match the subsystem description name, regardless of the library. |
Data Queue Attributes
The following table lists several data queue attributes and the required values for the data queues that are used by this exit point.
| Attribute | Value |
|---|---|
| Maximum entry length | 144 or greater |
| Sequence | *KEYED |
| Key length | 4 |
As shown in the previous table, the data queue entries are received by key. The following keys are used with these data queues:
| 0001 | Data queue message is a job start notification message. |
| 0002 | Data queue message is a job end notification message. |
| 0004 | Data queue message is a job queue notification message. |
The "Maximum entry length" is suggested to be set to 144 or greater. However, the exit point will send as much message data as there is room for in the data queue if the "Maximum entry length" is less than 144.
Format of Job Start and Job End Notification Messages
For more information about this format, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Message identifier |
| 10 | A | CHAR(2) | Message format |
| 12 | C | CHAR(16) | Internal job identifier |
| 28 | 1C | CHAR(26) | Qualified job name |
| 54 | 36 | CHAR(20) | Qualified job queue name |
| 74 | 4A | CHAR(8) | Time-stamp job entered system |
| 82 | 52 | CHAR(8) | Time-stamp job started |
| 90 | 5A | CHAR(8) | Time-stamp job ended |
| 98 | 62 | CHAR(1) | Job type |
| 99 | 63 | CHAR(1) | Job subtype |
| 100 | 64 | BINARY(4) | Job end severity code |
| 104 | 68 | BINARY(8) | Processing time used |
| 112 | 70 | CHAR(10) | Job queue library ASP device name |
| 122 | 7A | CHAR(22) | Reserved |
Format of Job Queue Notification Messages
For more information about this format, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Message identifier |
| 10 | A | CHAR(2) | Message format |
| 12 | C | CHAR(16) | Internal job identifier |
| 28 | 1C | CHAR(26) | Qualified job name |
| 54 | 36 | CHAR(20) | Qualified job queue name |
| 74 | 4A | CHAR(8) | Time-stamp job entered system |
| 82 | 52 | CHAR(16) | Reserved |
| 98 | 62 | CHAR(1) | Job type |
| 99 | 63 | CHAR(1) | Job subtype |
| 100 | 64 | CHAR(12) | Reserved |
| 112 | 70 | CHAR(10) | Job queue library ASP device name |
| 122 | 7A | CHAR(22) | Reserved |
Field Descriptions
Internal job identifier. An input value to other APIs to increase the speed of locating the job on the system. Only IBM i APIs use this identifier. The identifier is not valid following an initial program load (IPL). If you attempt to use it after an IPL, an exception occurs.
Job end severity code. The return code of the job when it ended. See the CPF1164 message text for possible job ending codes and their meaning. This field will contain hex zeros when a job start notification message is sent.
Job queue library ASP device name. The name of the auxiliary storage pool (ASP) device description for the ASP containing the library for the job queue. This field will contain hex zeros when there is no job queue associated with the job. This field will contain a name or one of the following special values:
| *SYSBAS | The library is located in the system ASP or in a basic user ASP. |
| *N | The name of the ASP device cannot be determined. |
Job subtype. Additional information about the job type (if any exists). The possible values are:
| blank | The job has no special subtype or is not a valid job. |
| D | The job is an immediate job. |
| E | The job started with a procedure start request. |
| F | The job is a System i® Advanced 36® machine server job. |
| J | The job is a prestart job. |
| P | The job is a print driver job. |
| T | The job is a System/36™ multiple requester terminal (MRT) job. |
| U | Alternate spool user. |
Job type. The type of job. The possible values for this field are:
| blank | The job is not a valid job. |
| A | The job is an autostart job. |
| B | The job is a batch job. |
| I | The job is an interactive job. |
| M | The job is a subsystem monitor job. |
| R | The job is a spooled reader job. |
| S | The job is a system job. |
| W | The job is a spooled writer job. |
| X | The job is the SCPF system job. |
See Comparing Job Type and Subtype with the Work with Active Job Command for information about how the job type field and the job subtype field equate to the type field in the Work with Active Job (WRKACTJOB) command.
Message format. The format of the data in the job notification message. This field is always set to 01 for job start and job end notification messages, and is always set to 02 for job queue notification messages.
Message identifier. The type of message that is represented by this data queue entry. This field is always set to *JOBNOTIFY.
Processing time used. The amount of processing unit time used by the job, in milliseconds. This field will contain hex zeros when a job start notification message is sent.
Qualified job name. The name of the job that is associated with this notification message. The format of the qualified job name is a 10-character simple job name, a 10-character user name, and a 6-character job number. Each portion of the qualified job name is left-justified and padded with blanks on the right.
Qualified job queue name. The name of the job queue that the job was placed on, and the name of the library that contains the job queue. The format of the qualified name is a 10-character simple object name followed by a 10-character library name. Each portion of the qualified job queue name is left-justified and padded with blanks on the right. This field will contain hex zeros when there is no job queue associated with the job.
Reserved. An ignored field.
Time-stamp job ended. The date and time the job completed running on the system. This is in system time-stamp format. This field will contain hex zeros when a job start notification message is sent.
Time-stamp job entered system. The date and time the job entered the system. This is in system time-stamp format.
Time-stamp job started. The date and time the job began to run on the system. This is in system time-stamp format.
Usage Notes
- The notification messages may not be logged to the data queue if a DDM data
queue is specified for this exit point.
- The data queue should be in a library
in the system auxiliary storage pool (ASP) or in a basic user ASP.
- The Job Notification exit point cannot register two data queues that have
the same data queue name and library name and differ only by which independent
ASP the data queue is in.
- If the data queue exists in a library in an independent ASP,
the data queue may not be found
or a different data queue in a different independent ASP may be found.
The library name space of the thread sending the message determines
which data queue is found.
- The Job Notification exit point cannot register two data queues that have
the same data queue name and library name and differ only by which independent
ASP the data queue is in.
- The Convert Date and Time Format (QWCCVTDT) API can be used
to convert date and time values from one format to another format.
- When a job is ended from a job queue,
the Time-stamp job started and Processing time used fields
will contain hex zeros,
unless the job has previously run and transferred to the job queue.
- When a job has more than one routing step,
separate notifications are sent for each routing step.
Exit program introduced: V3R7