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 i5/OS jobs go through the following transitions:

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

None.


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(32) 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(44) Reserved


Field Descriptions

Internal job identifier. An input value to other APIs to increase the speed of locating the job on the system. Only i5/OS 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 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 an AS/400(R) Advanced 36(R) 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.

Refer to 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 is only filled in for job end notification messages when a job is ended from a job queue, and for job queue notification messages.

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

  1. The notification messages may not be logged to the data queue if a DDM data queue is specified for this exit point.

  2. It is recommended that the data queue exist in a library in the system auxiliary storage pool (ASP) or in a basic user ASP. It will not be found if it exists in a library in an independent ASP.
  3. The Convert Date and Time Format (QWCCVTDT) API can be used to convert date and time values from one format to another format.
  4. When a job is ended from a job queue, the time-stamp job entered system and processing time used fields will contain hex zeros, unless the job has previously run and transferred to the job queue.
Exit program introduced: V3R7
Top | Work Management APIs | APIs by category