Program-directed postprocessing program format

You can use the program-directed postprocessing program to handle trace log output in a method of your choosing.

The program-directed postprocessing program must accept parameters as defined by the program-directed postprocessing program typedef.

Format

#include <tpf/itrl_pdpp.h>
typedef int (*program_directed_post_processing)(int  lastRequest,
                                                struct itrl_sessionInfo *info,
                                                unsigned int  JSONdocSize,
                                                char         *JSONdoc);

Parameters

lastRequest
One of the following the reasons that the program-directed postprocessing program is called:
TPF_TRLOG_PDPP_MORE_TO_COME
Indicates that another call will be made to the program after this call to the program is completed.
TPF_TRLOG_PDPP_LAST_REQUEST
Indicates that this is the last call to the program for the trace log session.
TPF_TRLOG_PDPP_LAST_REQUEST_WITH_ERROR
Indicates that an error occurred when the JSON document was being created for the trace entry. Because the JSON document could not be created, this is the last call to the program for the trace log session.
info
A pointer to the itrl_sessionInfo structure, which is defined in tpf/itrl_pdpp.h header file. This structure contains information about the ECB that was traced and the trace log session.
JSONdocSize
The size of the JSON document that the JSONdoc parameter points to.
JSONdoc
A pointer to the JSON document.

Return values

TPF_TRLOG_PDPP_NORMAL
Indicates a successful return.
TPF_TRLOG_PDPP_ERROR
Indicates that program-directed postprocessing encountered an error. When this value is returned, the following conditions occur:
  • An error message is sent to the console.
  • The program-directed postprocessing program is not called again for this trace log session.
  • Any data that remains for the trace log session is discarded.
TPF_TRLOG_PDPP_ERROR_SKIP_MSG
Indicates that program-directed postprocessing encountered an error. When this value is returned, the following conditions occur:
  • An error message is not sent to the console.
  • The program-directed postprocessing program is not called again for this trace log session.
  • Any data that remains for the trace log session is discarded.

Programming considerations

  • The program-directed postprocessing program typedef is defined in the tpf/itrl_pdpp.h header file.
  • To call the program-directed postprocessing program, you must specify the 4-character program name in the ITLGPGM or itlgpgm field of the TLOGC parameter block when the TLOGC macro or the tpf_tracelog_ext function is called. The TLOGC parameter block is mapped by using the IDSTLG assembler macro or the tpf/idstlg.h header file.
  • Program-directed postprocessing uses the TPF_CALL_BY_NAME function to call the program-directed postprocessing program.
  • If program-directed postprocessing allocates any storage such as ECB heap, program-directed postprocessing is responsible for releasing that storage.