Control Job Log Output (QMHCTLJL) API

The Control Job Log Output (QMHCTLJL) API controls the production of a job log when the related job ends or when the job message queue becomes full and the print-wrap option is in effect for the job. The API can only influence the job log for the job in which it is used. The API can be used to control:

• The destination of the job log.
• The amount of message information written to the job log.
• The occurrence of messages in the job log.

To have an effect on the job log, the API must be called before the job ends. It can be called in an initial program for the job.

This API does not produce a job log; rather, the API captures the control information specified on the parameters and retains the information until job log production. The API also prepares the output files for job log production. When job log production occurs, such as at end of job, the control information and the prepared output files direct the job log to the output file.

If the API is not used, normal job log production occurs. That is, all messages in the job message queue for the job are written to a spooled file from which the job log can be printed. If the API is used, no spooled file is produced. Instead, the messages are written into one or two output files, depending upon the amount of information requested. Once the API is used, the options selected remain in effect for the current job until the API is called again. Each time the API is used, the selected options can be changed. The options in effect when the job ends or when the job message queue becomes full are the ones used to produce the job log.

One or two output files can be produced at job log production time.

• 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.
  
  
• 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.

Detailed information about the formats of the primary output file and secondary output file is provided in the 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:

• 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.
• 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.
• 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:

• *EXECUTE required in all cases.
• *ADD required when the output file or member does not exist.

Output file authority:

• *OBJOPR, *OBJMGT, *ADD required in all cases.
• *DLT required to clear the member of existing records.

Required Parameter Group

Output file names structure

INPUT; CHAR(65)

Provides information about the primary and secondary files and members.

Output file names structure format

INPUT; CHAR(8)

The format of the output file names structure parameter. This must be set to CTLJ0100. See CTLJ0100 Output File Names Structure for details about this format.

Message filter array

INPUT; CHAR(*)

An array of zero or more elements. Each element in the array defines a test applied against each message before it is written to the output file. The tests are performed in the order they appear in the array. A message is rejected and not written to the output file if any one test defined in the array is true for the message. A message is selected and written to the output file if all tests defined in the array are false for the message.

Each array element specifies a message severity, message type, and message ID. If a message has a message severity less than or equal to the specified severity, has the specified type, and has a message ID equal to the specified ID, the test is true and the message is not written to the output file. Processing stops on the rejected message and the next message is processed.

If a message meets one or two of the criteria but not all three, the test is false and the test defined by the next array element is applied. If all array elements have been applied to the message and none have been found true, the message is written to the output file.

Number of message filter elements

INPUT; BINARY(4)

The number of elements in the Message filter array parameter. The value must be greater than or equal to 0 but less than or equal to 255. If no message filtering is to be done during job log production, this parameter must be set to 0.

Qualified error message queue name

INPUT; CHAR(20)

The qualified name of a message queue to which a message should be sent to record any errors detected during the production of the job log to an output file. The first 10 characters of this parameter contain the message queue name and the second 10 characters contain the library name. A library name must be specified. The special values *CURLIB and *LIBL cannot be used. QTEMP cannot be specified as the library name. The message queue name specified cannot be QHST or QSYSMSG.

The following special value can be used for the message queue name of this parameter:

*NONE	No messages are sent. If errors occur during job log production to an output file, there is no record of what the error was or the action taken in response to the error.
*SYSOPR	Send the messages to the system operator's message queue, QSYSOPR.

If a qualified message queue name is provided and that message queue does not exist or is unusable at job log production time, any messages are sent to *SYSOPR.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

CTLJ0100 Output File Names Structure

The following table shows the layout of the output file names structure for format CTLJ0100.

Message Filter Array Elements

The following table shows the structure of an array element in the message filter array parameter. This structure is repeated for each element in the array.

Field Descriptions

Member replace option. Specifies if an existing member of either the primary or secondary file is to be cleared. If the member is to be cleared, it is cleared when this API is called. If a member contains existing records and is not cleared, at job log production time, the new records are added to the member and the existing records are left unchanged. Use one of the following special values:

Message ID. The message ID to test each message against. The following special values can be used in place of a message ID:

A generic message ID can be used in place of a specific message ID. A generic message ID is an ID in which the last 2 or 4 characters are 0. For example, CPF2400 and CPF0000 are generic IDs. A generic ID represents a range of IDs rather than a single ID. A generic ID of the form XXXnn00 represents all IDs from XXXnn00 through XXXnnFF. A generic ID of the form XXX0000 represents all IDs from XXX0000 through XXXFFFF.

When a generic ID is specified, any message ID within the range of the generic ID is considered to match the generic ID. The message severity to test each message against. If severity is not important in rejecting a message use 99 as the value for this field. When 99 is used, each message's severity is less than or equal and, as a result, message type and message ID will determine if a message is selected or rejected.

Message type. The message type to test each message for. Use one of the following special values:

Output file names structure length. The length of this structure. This must be set to a value of 65.

Primary file member name. The name of the member within the primary file used for the primary job log information.

If a member of the specified name does not exist, a member by that name is added to the primary file by this API.

If a member by the specified name does exist, this API will clear the member if the Member replace option field of this structure specifies replace. Otherwise, the member is not cleared. At job log production time, new records are added to the member and any existing records are left unchanged.

The following special value can be used in this field:

Qualified primary file name. The qualified name of the primary output file. This field consists of two parts. The first 10 positions contain the file name and the second 10 positions contain the library name. A specific library name can be provided or the special values *CURLIB and *LIBL can be used. QTEMP cannot be used as a library name.

If an output file by the specified name does not exist when this API is called, one is created by that name in the specified library. If the library was specified as *LIBL, the file is created in the current library. If *LIBL or *CURLIB was specified and there is no current library, the file is created in QGPL. The file is created with the attributes MAXRCDS and MAXMBRS set to *NOMAX.

The following special value can be used in this field:

The API does not allow the primary file specification to be overridden by the use of the Override Database File (OVRDBF) command. The primary file also cannot be overridden at job log production time. The file object determined to be the primary file used by this API is the one used at job log production time. If the file does not exist at job log production time, the job log is redirected to a spooled file.

The primary file must be a local physical file; it cannot be a DDM file.

Qualified secondary file name. The name of the file into which the secondary job log information is written. The parameter consists of two parts. The first 10 positions to contain the file name and the second 10 positions contain the library name. A library name can be provided or the special values *CURLIB and *LIBL can be used. QTEMP cannot be used for the library name.

If an output file by the specified name does not exist when the API is called, one is created by that name in the specified library. If the library was specified as *LIBL, the file is created in the current library. If *LIBL or *CURLIB was specified and there is no current library, the file is created in QGPL. The file attributes MAXRCDS and MAXMBRS are set to *NOMAX.

The following special value can be used in this field:

The API does not allow the secondary file specification to be overridden by the use of the OVRDBF command. The secondary file also cannot be overridden at job log production time. The file object determined to be the secondary file by this API is used at job log production time. If the file does not exist at job log production time, the job log automatically redirects to a spooled file.

The secondary file must be a local physical file; it cannot be a DDM file.

Reserved. This field must be set to binary zeros.

Secondary file member name. The name of the member within the secondary file used for the secondary job log information.

If a member of the specified name does not exist, a member by that name is added to the secondary file.

If a member by the specified name does exist, the member is cleared if the Member replace option field of this structure specifies replace. Otherwise, the member is not cleared. At job log production time, new records are added to the member and any existing records are left unchanged.

The following special value can be used in this field:

CCSID Considerations

CCSID conversion is allowed on any field in the primary file with the exception of the field QMHMDT, which contains the message data or immediate message text. The QMHMDT field is defined with a CCSID of 65535 so conversion does not occur on this field when the record is written. CCSID processing is done on the message data when the message is sent. The CCSID that the QMHMDT field data is in is stored in the record with the message data. The CCSID is placed in field QMHCID.

CCSID conversion is allowed for any field in the secondary file except for the field QMHLIN which contains a line of message text. This field is defined with CCSID 65535. The message text has completed CCSID processing before the record is written to the file. The CCSID the message text is in is stored in field QMHSID.

The model files QAMHJLPR and QAMHJLSC specify no CCSID definitions other than the two fields mentioned previously. CCSID processing for the remaining fields is allowed to default.

Detailed information about the fields mentioned in this discussion is provided in the CL Programming topic.

Error Considerations

During job log production to an output file, different types of errors can be encountered. Some errors allow the job log to be written to the output file but the information in a record can be incomplete. Other errors can prevent the job log from being written to the output file. For example, when the output file has been deleted between the time this API has been run and job log production starts. Other errors, such as when a member becomes full, allow a certain number of records to be written but not all. Whenever an error is encountered, an informational message is written to the user or workstation queue specified by the API parameter. If the API parameter specifies *NONE, these messages are not written.

If the error is such that the data can still be written to the output file, even though it can be incomplete, processing continues and at the end of job log production there are output file(s) and member(s) which contains the information that could be written. For example, if the message data for a message needs to be truncated to 3000 characters, production of the job log to the output file continues but a message is sent to record the fact that the message data was truncated.

If the error is such that no data can be written, the job log automatically redirects to a spooled file. This occurs if the objects, determined by the API to be the output files, are deleted, damaged, or otherwise unusable at the time job log production started. If any such error is encountered on the primary or secondary output file, this redirection to a spooled file occurs. A message is sent to the specified message queue to record that the job log has been redirected to a spooled file.

If only certain records are written to the output file, the remaining messages are redirected to a spooled file. A message is sent to notify of this.

Job Message Queue Full Considerations

If the print-wrap option is used to control the action to take when a job message queue becomes full, consider the following when using this API to direct the output to an output file.

Each time the job message queue becomes full, records are written to the output file for those messages that are being removed from the job message queue. All new records are added to the member. The Member replace option specified on this API has an effect only when this API is preparing the output file for use. It has no effect when the records are written to the output file. For the print-wrap option, the member contains the complete set of messages for the job rather than a partial set.

For long running jobs, it is possible that the job message queue can become full and the output file member also becomes full. If the member becomes full, output is automatically redirected to a spooled file until the API is run another time to specify a new member to use.

Changing the action from print-wrap to wrap will stop the production of records to the file(s). When the job ends or if the action is changed back to print-wrap, records are again written to the file(s).

Usage Notes

This API can be called from the initial thread of a multithreaded job to control the job log output for all threads. It should not be called from a secondary thread.

Error Messages

Job Log Production Messages