System i: Programming Message Handling APIs - IBM

v The primary output file contains one record for each message selected for inclusion in the job log. A
record in the primary output file contains the essential information of the message: message ID,
message type, message severity, time sent, sender and receiver information, and the message data.
v Output to a secondary output file can also be produced. Secondary output is optional and is controlled
by providing an output file name for the secondary file. Secondary output consists of the first and
second level text for a message. The first and second level text has all message data inserted and is an
image of the print line. Since there can be more than one print line for first and second level text, there
can be more than one secondary record for a message. Thus, for a single message, the primary file
contains one record and the secondary file contains one or more records. For example, if the print
image for first level text is 2 print lines and the second level is 4 print lines, there are 6 records
produced for the message in the secondary file. With the 1 primary record, there would be a total of 7
records produced for that message.
For detailed information about the formats of the primary output file and secondary output file, see CL
programming topic.
This API does not influence the DSPJOBLOG CL command when OUTPUT(*OUTFILE) is specified on the
command. If OUTPUT(*OUTFILE) is specified on the command, the primary job log information is
written to the file specified on the command, and no message filtering is performed. If
OUTPUT(*APIDFN) is specified on the command, the files specified by the call to the API are used for
output, and message filtering is performed by the call to this API. The error message queue is not used
so any errors are returned to the issuer of the DSPJOBLOG command.
If the DSPJOBLOG command is used with the files prepared by this API, note the following:
v The files specified on the API are prepared only once, when the API is called. Preparing the files
includes clearing the members of any existing data if requested on the API. The files prepared by this
API can be used on several calls of the DSPJOBLOG command. However, the members are not cleared
between calls.
v Each time the DSPJOBLOG command is called, the output is added to whatever is already in the
members. Additionally, at end of job, the final records for the job log are added to the members.
v If the members need to be cleared between calls of the DSPJOBLOG command or before the job ends,
call the API again or use the CLRPFM (Clear Physical File Member) command.
This API does not override the LOG job attribute for the job or the LOG attribute on the SIGNOFF CL
command. The LOG job attribute controls whether any job log is to be produced and controls whether
second level text is to be logged.
Authorities and Locks
Authorization to the specified output file(s) is checked when this API is used. If the specified output
file(s) does not exist, this API creates them. Additionally, if the output file member(s) does not exist, this
API adds a new member by the specified name to the output file(s). The authorization checking is
performed using the user profile the API was called under. If an output file needs to be created, the user
profile the API was called under becomes the owner of the output file. Public authority to files created by
this API is controlled by the library containing those files. Public authority for objects created into a
library is controlled by the CRTAUT parameter on the CRTLIB or CHGLIB command.
Output file library authority:
v *EXECUTE required in all cases.
v *ADD required when the output file or member does not exist.
Output file authority:
v *OBJOPR, *OBJMGT, *ADD required in all cases.
v *DLT required to clear the member of existing records.
Message Handling APIs 7