Endevor email notification trace EN$TRNTF

Products

• Endevor

Issue/Introduction

This article documents the Endevor email notification trace, which can be used to debug notification emails produced by endevor.

Environment

Release: ALL 

Resolution

The endevor email notification facility produces trace data for each email it produces whenever ddname EN$TRNTF is allocated to the jobstep.

To allocate EN$TRNTF in a batch run, it is enough to add the following DDs to the JCL:

//BSTERR DD SYSOUT=*
//EN$TRNTF DD SYSOUT=*

To allocate it in a foreground run, the following command may be used:

TSO ALLOC FI(EN$TRNTF) SYSOUT(X)
TSO ALLOC FI(BSTERR) SYSOUT(X)

This command may be issued at any point before the email is generated

The trace prints to ddname BSTERR and consists of a small snap dump of each and every record that the notification interface sends to the SMTP processing started task which is selected to process the emails. For example:

07:18:22:14 DATA WRITTEN BY BC1PNTFY
3B62E0FC (+0000)   C8C5D3D6 40C8D6E2 E3D5C1D4 C5404040   40404040 40404040 40404040 40404040   *HELO HOSTNAME                   *
3B62E11C (+0020)   40404040 40404040 40404040 40404040   40404040 40404040 40404040 40404040   *                                *
3B62E13C (+0040)   40404040 40404040 40404040 40404040                                         *                *

Each record dumped by the trace is prefixed by a fixed title (DATA WRITTEN BY BC1PNTFY). The columns in each block are:

• Storage address where the data resides
• Hex offset from the start of the block
• 32 bytes of data in hex format
• Same data in character format

If the SMTP started task does not send the emails as expected, this trace may be used to examine the email addresses set by Endevor and also to ensure that the whole message adheres to the SMTP protocol.

Additionally, if the BC1PMLIF interface routine is used, this routine writes snap dumps of the parameter blocks passed to it by the caller, under headings:

• PARMLIST - List of up to 6 pointers to the other parameter blocks.
• PMSGAREA - Message area (output parameter)
• USER ID
• MAILFROM
• SUBJECT
• TEXT CT - Number of text lines passed
• 1ST LINE
• URL?

HINT:
A helpful trick is changing the SMTPCLASS to some held sysout class (other than the default 'B') so that it could just sit around on the held queue (not be immediately processed).
By doing so, it is possible to see what is sent to ESMTP in plain text, which is much more readable than the snap dumps written by EN$TRNTF.

To change the SMTPCLASS value, ESMTPTBL email definition table needs to be edited to specify the new SMTPCLASS value in the first $ESMTP macro invocation. For example:

*---------------------------------------------------------------------*
* FIRST INVOCATION - DEFINE "GLOBAL" VALUES                            
*---------------------------------------------------------------------*
         $ESMTP HOSTNAME=hostname,                                     X
               DFTDOMAIN=emaildomain.com,                              X
               DFTID=USERID,                                           X
               SMTPCLASS=X        Where X is the sysout held class.                                       


Note that ESMTPTBL needs to be reassembled/relinked in order for the changes to be in effect. For the assemble/link jcl sample, please see *.CSIQJCL(BC1JTABL).
//ESMTPTBL EXEC ASMLNK,MEMBER=ESMTPTBL