This article describes the Email Notification Facility, the Synchronization Notification feature, the BC1PMLIF email interface program, and the BC1PNTFY notification utility, and also includes information on interfacing with
Common Components and Services.
Endevoris enabled by creating the mainframe ID and email ID table, ESMTPTBL. This table maps mainframe user IDs to email IDs or group names. When an email notification event occurs, the invoked program scans the ESMTPTBL table for an appropriate match. The program searches the table for a matching mainframe ID. If a match is found, an email addressed to the associated email ID is sent. If no match is found, no email is sent.
However, if you code the DFTID=USERID parameter in the ESMTPTBL, instead of bypassing unlisted IDs,
Endevorwill construct an email address with the
Endevoruser ID suffixed with the default domain. If your site has defined email aliases for all your mainframe user IDs, coding of DFTID=USERID allows you to reduce the size of the ESMTPTBL and makes it easier to maintain.
The email interface utility BC1PMLIF allows you to write simple email programs without having an in-depth knowledge of the NOTIFY block or the ESMTP table lookup.
Email Notification Components
The following components are provided as part of the Email Notification Facility:
- $ESMTPMacro that builds a table (ESMTPTBL) that maps mainframe IDs to email IDs.
- ESMTPTBLTable created by the macro $ESMTP to map mainframe IDs to email IDs.
- BC1JTABLSample JCL used to assemble and link any of the Tables, including the ESMTPTBL table.
The $ESMTP Macro
The macro, $ESMTP, builds the mainframe ID and email ID table, ESMTPTBL. The macro has a section for global information and a section for each mainframe user ID.
The JCL to assemble and link this macro is located in iprfx.iqual.CSIQJCL. The resulting load module, ESMTPTBL, must reside in the
EndevorAPF-authorized library (uprfx.uqual or iprfx.iqual.CSIQAUTH).
The global information section includes the following fields:
- ATSIGNUse this field to specify the byte value that replaces the @ sign in email addresses. You can specify any value, except 00 and 40. For example, ATSIGN=80. The default value is 7C.
- HOSTNAMENJE node name of the z/OS system where SMTP is running.
- DFTDOMAINDomain name to be used in email addresses. You can override this field in the mainframe ID section.
- MAILFROMDefines a default MAIL FROM value. The value is free form andEndevorneither does syntax checking on the parameter nor appends a hostname to it.The MAIL FROM value can be defined in several ways. The value that is used is the one that is found first in the following search order:
- DFTURLURL whereChange Manager Enterprise Workbenchis running. You can override this field in the mainframe ID section.
- DFTID=USERIDIfEndevorcannot find the USERID in ESMTPTBL and DFTID=USERID is coded,Endevorattempts to send an email to the mainframe user ID by constructing an email address with theEndevoruser ID suffixed with the default domain. Without DTFID=USERID,Endevordoes not send an email if it cannot find the mainframe user ID in ESMTPTBL. This parameter does not override email addresses in ESMTPTBL. If an invalid address is found in ESMTPTBL, no email is sent to that user ID.To enable the default ID feature, only one value is permitted (DFTID=USERID). If the value is omitted, or coded as null (DFTID=), then the parameter has no effect.
- SMTPTASKNAMEThe name of the SMTP address space. The default is SMTP and is rarely subject to change.
- SMTPCLASSThe SYSOUT CLASS associated with the SMTP task. The default is B and is rarely subject to change.
The mainframe ID/email ID section includes the following fields:
- HOSTNAMENJE node name of the z/OS system where SMTP is running.
- MFIDThe mainframe user ID or package approver group name. This field can contain up to 16 character.
- EMAILIDThe portion of the email ID that precedes the @. This field size is unlimited.
- DOMAINThe portion of the email ID that follows the @. If not specified, the global default domain is used. This parameter supports an environment where email IDs might be defined in multiple domains.
- URLThe URL whereChange Manager Enterprise Workbenchis running. If not specified, the global default URL is used. This parameter enables you to point users to different implementations ofChange Manager Enterprise Workbench.
Disable Notification for Specific Users
To completely disable notifications for a particular user, simply provide a dummy or invalid email address. The default does not override any explicitly coded email address; therefore, if you leave an invalid email address in ESMTPTBL, no email is actually delivered to that particular user.
A sample ESMTPTBL table is provided in the Tables library. The sample ESMTPTBL includes the DFTID=USERID parameter, which enables
Endevorto construct email addresses from the
Endevoruser ID and the default domain. If your ESMTPTBL includes DFTID=USERID, when a package is cast requiring an approval from one or more users not defined in the table, for example peter01 and sally02,
Endevorwill send an email to [email protected] and [email protected], in addition to emails to users defined in the table.
The JCL that can be used to assemble and link-edit tables, including ESMTPTBL, is located in member BC1JTABL, provided in the JCL library (
iprfx.iqual.CSIQJCL). An alternative is to employ an SMP/E USERMOD to accomplish this.
Synchronization Notificationfeature immediately sends an email to the element change owner, when an element is changed or added higher in the software lifecycle map and is found to be out-of-sync with the element located lower in the map.
Out-of-sync elementsare instances of the same element with the element at the higher location in the software lifecycle map having change levels that are not reflected in the element located lower in the map. These elements are out of synchronization (out of sync).
source sync checkoccurs whenever an element is changed or arrives at a new location in the lifecycle map. All instances of that element located lower in the software lifecycle map are checked to determine if the newly changed or added element is out of synchronization (out of sync) with the elements located lower in the map. The source sync check verifies the last level time stamp of the element at the higher lifecycle location against the base level time stamp of the lower elements. If the dates do not match, a source management's synchronization check function is invoked for these elements to determine if they are actually out of sync.
Provided Synchronization Notification has been enabled by the administrator, it is initiated by the following activities:
- The element actions: Add, Update, Move, Restore, Transfer C1-C1, and Transfer from Archive.
- The Quick Edit actions: Create and Edit.
- The Search and Replace utility.
For each out-of-sync element found, an email is sent to the owner associated with the last source change level of the element located lower in the map than the newly changed or added element. However, if a change level does not exist yet, the email is sent to the last element action user ID. In addition, a message is written to the action log to record the out-of-sync elements. In foreground, if an action causes out-of-sync elements, the "route sync problem" text appears on the action's panel, unless this message is suppressed by the administrator.
If email notification is not already set up at your site, the administrator must set it up in order for this feature to work.
Enable Synchronization Notification
To let users know when an element is added up the software lifecycle map that is out of synchronization with their element located lower in the map, the administrator can enable synchronization notification.
If email notification is not already set up at your site, the administrator must set it up in order for this feature to work. For details, see Email Notification.
Follow these steps:
- Set the severity level of the out-of-sync messages written to the action log, by setting [email protected]= parameter in the C1DEFLTS table to one of the options.
- Mark an environment as the starting location in the software lifecycle where you want source sync checks to be performed. In the Type=Environment section of the C1DEFLTS table, set the [email protected] parameter to Y ([email protected]=Y,) for this environment. The options for this parameter are as follows:
- [email protected]=[Y,N],Y-The environment is a source synchronization location.N-Default. The environment isnota source synchronization location.Blank-If no option is specified (for example, [email protected]=,) then the option defaults to N.Specifies whether the Environment, Stage location is a source synchronization location. If [email protected]=Y, when an action adds or moves an element to this location, or to any location higher up the map, a sync check is performed. If an element located lower in the map is not in sync with the new element, a synchronization notification email is sent to the owner of the out-of-sync element at the lower location. If more than one [email protected] is specified in C1DEFLTS, regardless of its specification ([email protected]=, [email protected]=N, or [email protected]=Y,) all [email protected] parameters after the first one in the map are ignored.
Example: Synchronization Notification - Starting Point in the Software lifecycle Map
Assume that your site's C1DEFLTS table maps environment DEV to QA1, maps QA1 to QA2, and maps QA2 to PRD. If the C1DEFLTS table definition of QA2 has [email protected] set to Y, then QA2 and PRD are synchronization locations. It is not necessary to mark PRD.
Source Synch Check Email Format
A separate email notification is given for each out-of-sync element. The email is formated as follows. The "Package : package" text line is omitted if the element is not associated with a package.
User id has just placed element name type name version level vvll in SCM at location: Env : environment System : system Subsystem: subsystem Stage ID : id With CCID: ccid Comment: comment Package : package Your element vvll at location below is now out-of-sync with the above element. Env : environment System : system Subsystem: subsystem Stage ID : id With CCID: ccid Comment: comment Package : package
View Synchronization Notification Settings
There are several ways to check the C1DEFLTS settings in effect at your site for the Synchronization Notification function.
- To see if source sync checking is enabled and what severity level is assigned to the action log messages, you can check the site options using either of the following methods:
- See the panel Site Information from C1DEFLTS. The Function Control section of the panel includes the following fields: Sync Sev Msg and Sourc Sync Check.
- Run a Site Options Settings report, which lists the Source Sync Chk and Sync Sev Msg fields in the C1DEFLTS section of the report.
- To see if an environment is an active source synchronization location, you can use either of the following methods:
- See the Environment Information panel's field Out-of-Sync Alerts.
- Use the CSV utility's List Environment function and view the SYNC LOC field in the returned data.
- If your site uses the API, the API List Site and List Environment requests return Source Notification settings.
Email Interface Program BC1PMLIF
You can write free format email messages to be sent during
Endevorprocessing. The email interface program BC1PMLIF allows you to do this without having an in depth knowledge about the $NOTIFY block and or the ESMTP table lookup.
Your program can call BC1PMLIF at exit points or in processors with an easy to use parameter list. BC1PMLIF formats the required internal control blocks and calls the existing
Endevoremail interface modules. The following parameter list is passed to BC1PMLIF. The first two parameters are mandatory, and the others are optional.
- MYSMTP-MESSAGE (132 bytes)Error message return area
- MYSMTP-USERID (8 bytes)Mainframe USERID used to lookup the email address in ESMTPTBL
- MYSMTP-FROM (50 bytes)Email FROM line, no embedded spaces are allowed.
- MYSMTP-SUBJECT (50 bytes)Email SUBJECT line, embedded spaces are allowed.
- MYSMTP-TEXTTwo byte counter followed bynnlines of data. Up to 99 lines of 133 bytes are allowed. Email line count, Email text area.
- MYSMTP-URL (1 byte)Includes the default URL value of ESMTPTBL in the email. If no default URL is coded in ESMTPTBL (DFTURL=,) then no URL is included in the email. Can contain Y or any other 1-byte value; the content of the passed value is not important.
BC1PMLIF uses the
EndevorESMTPTBL to translate the Mainframe User ID name into an email address. Then it formats the message and sends it to the email server. If BC1PMLIF detects any errors during execution, it sets a non-zero return code and posts an error message in the Error Message area.
A sample COBOL program that uses BC1PMLIF is provided as member CALLMLIF in the installation source library.
Notification Utility BC1PNTFY
The Notification utility (BC1PNTFY) allows you to alert people, such as
Endevorusers and package approvers, of the occurrence of various
Endevorevents. It can be called by user exit programs, and by
Endevoritself. Messages can be sent using the following four protocols:
- SMTP (email)
Several sample user exit programs are provided with. The source for these exit programs is located in the iprfx.iqual.CSIQOPTN library.
How to Configure the Notification Utility
Configuring the Notification utility to send messages to your
Endevorusers and package approvers consists of two basic steps:
- Modify the exit program to pass the values for the universal parameters to the control block.
- Modify the exit program to pass the values for the protocol-specific parameters to the control block.
The following sections explain these parameters and their values.
Regardless of which protocol you use to send the notification, the exit program always needs to pass certain parameters to the control block. The following table describes these parameters. Information is given for both assembler and COBOL. Copybooks and Dsects are provided in iprfx.iqual.CSIQOPTN for use in your programs. See members $NOTIFY and NOTIFYDS for assembler and COBOL.
- NOTFTYPE (assembler)
- NOTI-NOTIFY-TYPE (COBOL)Specifies the protocol you want to use to send the message. The possible values are:
- Blank (uses default protocol)
- NOTMSGTX (assembler)
- NOTI-MESSAGE-TEXT (COBOL)80-character text field used to specify the message.If you select a value ofVfor the NOTMSGVF parameter, this field is not used.
- NOTFUSER (assembler)
- NOTI-USER (COBOL)The ID of the user or users that will receive the notification. The type of ID depends on the protocol used to send the message.
Depending on which protocol you want to use to send the notification to your users and package approvers, the exit program must pass certain protocol-specific parameters to the control block, in addition to the universal parameters discussed in the previous section.
The following sections describe these protocol-specific parameters.
If you are using the SMTP protocol to inform your users and package approvers of an
Endevorevent, use the following information for the SMTP-specific parameters that the exit program must pass to the control block. Information is provided for assembler.
- NOTATSIGNThis field allows you to override the default character used to construct email addresses. When no value is entered,Endevoruses the default value, which can be @ sign, or the value coded in $ESMTP table. Specify one byte hexadecimal value, or leave the field blank if you do not want to override the default value. :
- NOTMSGVFIndicates whether the message text format is fixed or variable length. The possible values are:If you selectF, or do not select a value, use the NOTMSGTX parameter to specify the message text. Do not use the NOTSMTPM parameter.F-Fixed length. This is the default setting.V-Variable length.
- NOTSIZEIndicates the size field in the $NOTIFY control block.
- NOTMSGMXIndicates the maximum message length. Required only if the value of NOTMSGVF isV.
- NOTSMTPMThe address of the email text. The text must be in the following format:LLLLmessage-text
- LLLL-The length (in binary) of the message text.
- message-text-The message text.
- NOTSMTPS50-character text field used for the email's subject field.
- NOTMSGLPText field used to specify the message.
- If NOTMSGVF is F, then the data string is treated as a string of fixed records. Fixed records are 84 bytes long, with a 4-byte address of the next record (zero - end), and 80 bytes of text content.
- If NOTMSGVF is V, then the data string is treated as a string of variable records, instead of as a string of a single variable record. The variable record format is a 4-byte address of the next record (zero - end), a 2-byte length of string, and nn bytes of string content (up to 32K bytes).
- NOTFROMA four-byte field that allows you to specify a FROM USER for the emails that are sent. The field should contain the address of an area of up to 50 bytes containing the FROM-ID that is to be used in emails. No spaces are allowed in the FROM-USER field. If the address is zeros,Endevoruses a default FROM USER definition.
For a sample exit program that illustrates how to use these parameters, see XIT7MAIL in the iprfx.iqual.CSIQOPTN library.
For more information about XIT7MAIL, see the
API and Exits.
If you are using the TSO protocol to inform your users and package approvers of an
Endevorevent, refer to the following table for the TSO-specific parameters that the exit program must pass to the control block. Information is provided for both assembler and COBOL.
- NTSOALLU (assembler)
- NOTI-SET-ALL-USER-OPT (COBOL)Specifies whether you want to send the message to all TSO users. The possible values are:N-Do not send the message to all TSO users. This is the default setting.Y-Send the message to all TSO users.Note:If you selectY, the NOTFUSER (assembler) or NOTI-USER (COBOL) field must be left blank.
- NTSOLOGN (assembler)
- NOTI-SET-LOGON-OPT (COBOL)Specifies when users receive the message. The possible values are:Y-Users receive the message when they log in to TSO. This is the default setting.N-Users do not receive the message when they log in to TSO.
- NTSOSAVE (assembler)
- NOTI-SET-SAVE-OPT (COBOL)Specifies whether you want to save the message in a broadcast set. The possible values are:N-(Default) Do not save the message in a broadcast set.Y-Save the message in a broadcast set.
If you are using the TPX protocol to inform your users and package approvers of an
Endevorevent, refer to the following table for the TPX-specific parameters that the exit program must pass to the control block. Information is provided for both assembler and COBOL.
- NTPXJOBN (assembler)
- NOTI-TPX-JOB-NAME (COBOL)The site-specific name of the TPX started task. This is a required entry.
- NTPXTYPE (assembler)
- NOTI-USERID-OPTION (COBOL)Specifies the type of TPX call to issue. The possible values are:U-(Default) USERID.L-LISTIDT-TERMIDA-APPLIDS-SESSION IDNote:If you want to send the message to all TPX users, this field must be left blank.
- NTPXALL (assembler)
- NOTI-ALL-OPTION (COBOL)Specifies whether you want to send the message to all TPX users. The possible values are:N-(Default) Do not send the message to all TPX users.Y-Send the message to all TPX users.Note:If you selectY, the NTPXTYPE (assembler) or NOTI-USERID-OPTION (COBOL) field must be left blank.
- NTPXSAVE (assembler)
- NOTI-SAVE-OPTION (COBOL)Specifies whether the message will be saved for the user. The possible values are:Y-(Default)Save the message for the user.N-Do not save the message for the user.
- NTPXBREK (assembler)
- NOTI-BREAK-IN-OPTION (COBOL)Specifies whether you want users in an active TPX session to receive messages immediately. The possible values are:N-(Default) The Notification utility does not interrupt active TPX sessions.Y-The Notification utility interrupts active TPX sessions and will display the message. The user can then decide to save or delete the message before returning to the session.
If you are using the XMIT protocol to inform your users and package approvers of an
Endevorevent, refer to the following table for the XMIT-specific parameters that the exit program must pass to the control block. Information is provided for both assembler and COBOL.
- NXMTNODE (assembler)
- NOTI-NJE-NODE (COBOL)The site-specific NJE target node name. This is a required entry
- NOTERMSG (assembler).
- NOTI-XMIT-MESSAGE (COBOL)The Notification utility fills in this field if there has been an error. This field should be moved to the exit block error message field.
- NXMTUNON (assembler only)Specifies whether you want the Notification utility to append the NONOTIFY operand to the XMIT command. The possible values are:N-(Default) Do not append the NONOTIFY operand to the XMIT command.Y-Append the NONOTIFY operand to the XMIT command.
Common Components and Services
Endevor, you can trap messages issued by
Endevoruser exits and processor programs and display them on the
Common Components and ServicesEvent Console. Once alerted to the event, the Event Console administrator can respond appropriately.
For example, with this facility you can notify an
Endevoradministrator when an
Endevorpackage has been denied by one of the package approvers or if an attempt to move an element into the production environment fails.
Let's look at the following message to understand how events issued from
Endevorcan be used by CCS Event Manager. Let's assume this message appears on the Event Console:
%CATD_I_060, SNMPTRAP: -c public 791 172.24.255.255 <productname>.machine.name 6 1 00:00:00 1 OID: machine.public.name 6 1 00:00:00 1 OID: 22.214.171.124.4.1.7126.96.36.199.1 &per.iso.org.dod.internet.private.enterprises.7188.8.131.52.1 VALUE:ENF00000 THIS IS A TEST OFEndevorMESSAGING
The bold portion of the message is the value submitted by user code and the non-bold part was added by CCS Event Management routines. Let's assume this message is associated with a rule that looks for the unique trap id, 184.108.40.206.4.1.7220.127.116.11, of all client-defined
Endevormessages. When it encounters this message id, it routes the messages to a secondary console that logs and prints each message for later review.
Endevoradministrator to structuresd the contents of their messages in a way that allows the message to be trapped and forwarded by CCS Event Manager.
CCS allows a 102-byte message field to be displayed on the Event Console. When you construct a message to be sent to CCS, consider including the following information:
- A unique message identifier
- A severity code
- The date and time
- Endevorinventory location information
- A detailed description of the error
You should also try to delimit message components with a space or a standard character to simplify forming events and rules.
How the Interface Works
The following illustration shows how
Endevorsends messages to the CCS Event Manager. From
Endevor, you can code a user exit or a processor program and REXX procedure to invoke the
EndevorInterface, which in turn traps message and sends events to the CCS Event Manager. An IP address table determines which Event Console receives the event.
The CCS Event Manager takes the free-format 102-byte message and adds control and system information before routing the entire message composite to the indicated consoles. Once the message is received at each console, CCS Event Management detects messages based upon string content and takes action using the message action facilities of Event Management.
Procedures for calling the interface from a user exit or from a processor are described next, followed by information about creating the CCS IP address table.
Calling the Interface from a User Exit
One method of calling the
EndevorInterface is to code an
Endevoruser exit program. The user exit program must call the user exit interface assembler program, BC1PTRPO.
The BC1PTRPO user exit interface program requires the following two parameters:
- MessageA102 byte message field which is passed 'as-is' to the Event Console.
- Result-areaAn 80-byte field into which BC1PTRPO returns the result of the Event submission. If the Event submission is successful, it contains "OK" as the first two characters, padded with spaces. Otherwise, it contains the reason for the Event submission failure.
The user exit must build the message and interrogate the result area. Writing user exits assumes you have a working knowledge of
Endevoruser exit architecture. A sample user exit is delivered as member XIT3MSG, in the iprfx.iqual.CSIQOPTN library.
Calling the Interface from a Processor
Another way of calling the
EndevorInterface utilizes an
Endevorprocessor which executes a REXX procedure. The REXX procedure must call the REXX procedure interface program, BC1PTRAP.
The BC1PTRAP REXX procedure interface program is an assembler program which is called with one parameter and returns a result message to the REXX procedure. It requires the following parameters:
- MessageA 102 byte message field which is passed 'as-is' to the Event Console.
- Result-areaA field where BC1PTRAP returns the result of the Event submission. If the Event submission is successful, it contains "*-ok" as the first four characters, padded with spaces. Otherwise, it contains the reason for the Event submission failure.
The REXX procedure must build the message and interrogate the result area.
Sample Processor Fragment
To call the
EndevorInterface from an
Endevorprocessor, you should refer to the sample processor fragment shown next, in combination with the REXX procedure sample, ENFSAMP, that follows.
//****************************************************** //* CREATE TEMPORARY INPUT FILE TO SEND A MESSAGE * //****************************************************** //MSGBLD EXEC PGM=IEBGENER //SYSPRINT DD SYSOUT=* //SYSUT2 DD // DSN=BC1USERID..TEMPMSG,DCB=(RECFM=FB,LRECL=80,BLKSIZE=8000), // SPACE=(TRK,2,1) //SYSUT1 DD * EX 'uprfx.uqual.ISRCLIB(ENFSAMP)' 'ENF00000 &C1ACTION. &C1ELEMENT'. //SYSIN DD DUMMY //****************************************************** //* SEND A UNICENTER TNG EVENT IN FOREGROUND** //* NOTE: ATTEMPTING TO RUN THIS STEP IN BG** //* WILL RESULT IN RC=5** //****************************************************** //SMSGFG EXEC PGM=BC1PTMP0,MAXRC=5, // PARM='BC1USERID..TEMPMSG' //STEPLIB DD DSN=iprfx.iqual.CSIQAUTU,DISP=SHR // DD DSN=iprfx.iqual.CSIQLOAD,DISP=SHR //SYSTERM DD DSN=&&PARMLIST.,DISP=(OLD,PASS) //SYSTSPRT DD DSN=&&PARMLIST.,DISP=(OLD,PASS) //SYSPRINT DD DSN=&&PARMLIST.,DISP=(OLD,PASS) //SYSOUT DD DSN=&&PARMLIST.,DISP=(OLD,PASS) //***************************************************** //* SEND A UNICENTER TNG EVENT IN BACKGROUND * //***************************************************** //SMSGBG EXEC PGM=IKJEFT01, // COND=((5,NE,SMSGFG),(5,LT)),MAXRC=7 //SYSTSPRT DD DSN=&&PARMLIST.,DISP=(OLD,PASS) //SYSTSIN DD DSN=&&TEMPMSG.,DISP=OLD
Sample REXX Procedure
The REXX procedure, ENFSAMP, passes a message to the
EndevorREXX interface program, BC1PTRAP. Any error conditions are passed back to the REXX procedure using standard REXX WORD return protocol.
The following REXX procedure corresponds to the previous processor fragment:
/* REXX */ ARG child_prm msgid = WORD(child_prm,1) prm1 = WORD(child_prm,2) prm2 = WORD(child_prm,3) "ISPEXEC LIBDEF ISPLLIB DATASET ID('iprfx.iqual.CSIQLOAD')" /*Note* The length of a REXX generated message */ /*Note* must be 2 bytes less than the maximum */ /*Note* 104 to account for the enclosing quotes*/ message= msgid||" A "||prm1||" OF "||prm2||" FAILED" message=LEFT(message,102) y=BC1PTRAP(message) IF WORD(y,1)/="*-ok" THEN DO SAY "Return from BC1TRAP0 is "||WORD(y,1) SAY "Reason is "||WORD(y,2) END ELSE SAY "Message successfully sent" "ISPEXEC LIBDEF ISPLLIB" EXIT