Enabling E-Mail and Fax Output

Background and Problem Definition

Users of the mainframe administrative systems have been able to direct report outputs to distributed (networked) printers or to CMS IDs for several years.  This has been possible through the use of a mainframe product, NetPrt or now IBM Printway, and a set of standards and utilities developed around the MVS-Output-Destination ADABAS file.  Since the original implementation of these facilities, there has been an interest in broadening the output options to include fax and e-mail (where report size permits).  It was thought that these would require definition on the MVS-Output-Destination table and the development of server systems to post process the outputs, similar to what NetPrt does.  This posed an intimidating and resource intensive barrier to addressing this need.  Then, due to experimentation with e-mailing of employee earnings statements, a new and different approach was conceived -- don't post process the output but instead pre prepare the necessary headers for these two types of output and then append the standard report output.  Although the final solution for e-mailing of output doesn't quite fit this scenario, the new concept allowed progress to go forward which has enabled providing e-mail or fax of standard system outputs with little development effort required.

Online and Batch

Since we produce reports and dynamically direct them to output destinations from both our Online Natural environment and from batch via online submitted Natural Jobs, separate solutions are required for these two points of origin.  (Later, we will also see that the processing required for e-mail is substantially different from that of fax which leads to four separate methods for addressing all requirements.)  For the online environment, users establish a default report output destination via their User Profile or select/change it via the RODS command.  The report is then produced via subprograms invoked from lists generated with this special option.  For e-mail or fax output, we need to obtain the address or phone number where the output is to be sent.  So rather than pre-defining these possibilities on the MVS-Output-Destination file it is much simpler to merely solicit this information from the user at the time the production of the output is requested.  In essence, this means allowing special output destination IDs of FAX or E-MAIL and then generating additional code into our list programs to perform the necessary processing when these options have been selected -- including asking the user for the phone number or e-mail address.

For batch output, a similar approach was used where the needed phone number or e-mail address is obtained at job submission time.  Techniques to accomplish this were a bit more involved since this information is only needed when these new output destinations have been selected from the fixed job submission screen.  Further, what is required for the two options is different.  However, this was accomplished by the addition of several fields and a new copycode member to edit the inputs.  Of course there are also JCL changes and new parameter assignments required.

Fax

With our current fax server, any reasonably sized report from the mainframe can be faxed as long as a standard header is pre-pended to the report.  In fact, NetPrt has had the fax server defined as a valid distributed printer for years.  Further, the fax server supports portrait (80 character) or landscape (132 character) print by setting an option in this header.  For online faxing, our list programs will now call UANFAXH to solicit and edit the fax phone number, the name of the individual the fax is intended for, and whether it should be produced landscape or portrait and then output the necessary header to report (1).  This is done preceding the call to the print generation program, which by standard also outputs to report (1).

For batch faxing, the phone number (with long distance authorization code) and recipient name are obtained by the job submission routine and assigned to JCL parameters.  The normal output class, form number, and destination are pre assigned to A, 0053, and NETPRT respectively -- NetPrt's definition of the fax server.  The batch job then executes the new program JOBFAXER which interprets the necessary parameters and outputs the fax header to the defined print DD.  (The print DD and the landscape vs portrait option are fixed in the JCL since they will not vary for a specific batch output.)  This is followed by the execution of the print generation program.

E-Mail

E-Mailing of output from UAFMVS1 can be done from the online Natural environment (with some special conventions and user exits) or from batch (using punch output vs print).  While it may be possible to output more than 80 characters per e-mail line, it has not been proven and would present many additional obstacles to be addressed.  Further, it is not deemed desirable since educating user's in how to handle even 80 characters in an e-mail message without having it automatically wrap is difficult enough.  So, e-mail output is restricted to 80 character reports and thus must not be allowed in situations where the report exceeds this width.  Due to restrictions in the manner of generating e-mail from the online environment and due to problems handling carriage control, reports to be e-mailed are directed to the edit source work area (Define Printer Output 'SOURCE') and then post processed from there.  The same technique is used online or batch, though accomplished through different utility routines.

For online e-mailing, our list programs will now direct the output to the source work area and after the report is produced call UANESWA to solicit and edit the address, the name of the individual receiving the e-mail, and a subject line.  These are pre filled with the user's e-mail address (if available from the User Profile/User file), name of the user (from the User file), and an optionally constructed subject line (via custom code).

For batch e-mailing, the e-mail address and name are obtained by the job submission routine and assigned to JCL parameters the same as for faxes.  The modifications necessary to support this are the same as for faxes, with the addition of a CMWKF10 DD SYSOUT=(B,SMTP).  Note that JOBFAXER is also used to accomplish this even though for faxes a header must be output first that precedes the report while for e-mail the report must be produced in the source work area and then post processed.  This is accomplished by JOBFAXER inputting the report program ID, doing a Define Printer Output 'SOURCE', Fetch Returning the program ID, and then calling UANESWAF to output to work file 10 the e-mail headers followed by the report.  Note: due to this technique the report program cannot contain a Define Printer statement and must direct its output to report (1).

Online How To

To enable fax or e-mail as an output option for online, merely regenerate you list (only super lists are supported, programs generated with macro PGZSL).  If the report produced in wider than 80 characters, the e-mail option must be disabled by adding the following code to the PFKMODS modifiable block (for whichever print PF key you have used):

  IF #DEFINE-PRINTER-NAME = 'E-MAIL' /* Not allowed here
    SET KEY PF12 NAMED ' '
  END-IF

A default subject line should also be constructed at the end of the PRINT modifiable block.  This can be done only when e-mailing is being performed and is accomplished by assigning a subject to the variable #PROMPT, something like the following:

  IF #DEFINE-PRINTER-NAME = 'E-MAIL'
    /* Build a subject line
    MOVE EDITED LSK.DATE-PAYROLL(#NSM-X) (EM=LLL^DD', 'YYYY)
        TO #PROMPT
    COMPRESS #PROMPT
        LSK.PAYROLL-TYPE(#NSM-X)
        INTO #PROMPT
    COMPRESS #PROMPT
        'Earnings Statement'
        INTO #PROMPT
  END-IF

Batch How To

Several steps are required to enable faxing and e-mailing output via the Natural online job submission facilities.  (As an example, see PAYROLL's EPJBDOE, EPNJOBS0, and EPMBDOEJ.)
  1. Ensure that the control variable #TV-FA is passed to the job submission subprograms within your library.  If not, add it as a parameter in xxOJOBS and to each xxNJOBSn subprogram.  It should probably follow the first two parameters, #MD-FA and #MI-FA.  For Example:
    2.   DEFINE DATA PARAMETER
  1 #MD-FA (C)
  1 #MI-FA (C)
  1 #TV-FA (C)                    /* 06-02-00
  2. Add the following variables within the redefinition of MSE.Native-Format-Parms within your job submission subprogram:

    3.   3 #E-MAIL-ADDR-FAX-NO          (A40) /* 06-02-00
      3 #E-MAIL-FAX-NAME             (A32) /* "
     

  3. Add the following variables as local fields within your job submission subprogram:

    4.   2 #EAFN-TAG                    (A8) /* 06-02-00
      2 #EFTN-TAG                    (A8) /* "
      2 #EF-CV                       (C)  /* "
     

  4. Ensure that the variables UV.USER-E-MAIL-ADDR and UV.USER-NAME are passed to your job submission map as parameters.

    5.  
  5. To the job submission map, add #EAFN-TAG and #E-MAIL-ADDR-FAX-NO just below the report output destination ID and #EFTN-TAG and #E-MAIL-FAX-NAME on the next line.  The two tag fields are output fields with the control variable #TV-FA.  The other two fields are modifiable with help routine 'UAHOTHER',= and control variable #EF-CV.  The map should look like the following (the first line contains the pre-existing #OUTPUT-DEST-ID and #OUTPUT-DEST-SHORT-DESC):

    6.   Report output destination ID:&XXXXXXXXXXXX+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
                          +XXXXXXXX&XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
                          +XXXXXXXX&XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
     

  6. Within the job submission map, replace the copycode UACRODIB invoked by a processing rule on #OUTPUT-DEST-ID with UACRODFE.  Some additional parameters are required by the new copycode, but will be exactly as follows given the above field names have been used consistently:

    7.   INCLUDE UACRODFE
           'MSE.#OUTPUT-DEST-ID'
           '#REPORT-DEST-CLASS'
           '#REPORT-DEST-FORM'
           '#REPORT-DEST-NODE'
           '#REPORT-DEST-ID'
           '#OUTPUT-DEST-SHORT-DESC'
           '''E-MAIL'''
           '#EF-CV'
           '#EAFN-TAG'
           '#E-MAIL-ADDR-FAX-NO'
           '#EFTN-TAG'
           '#E-MAIL-FAX-NAME'

    Note that the 7th parameter must be '''E-MAIL''' if e-mail output is allowed, otherwise any other constant value should be used there.
     

  7. Add the following internal subroutine to the job submission subprogram:

    8. DEFINE SUBROUTINE BUILD-EFAX-OUTPUT-DEST  /* 06-02-00
    * Output destination with E-Mail and Fax permitted, uses Parms 1-4
    * and a portion of 16
      RESET #JOB-PARMS(*)
      COMPRESS 'FORMS-DEST=FORMS='
        #REPORT-DEST-FORM
        ',DEST='''
        #REPORT-DEST-NODE '.' #REPORT-DEST-ID ''''
        INTO #JOB-PARMS(1) LEAVING NO SPACE
      COMPRESS 'O-CLASS=' #REPORT-DEST-CLASS
        #PARM-DELIMITER
        'O-DEST-ID=' #OUTPUT-DEST-ID
        INTO #JOB-PARMS(2) LEAVING NO SPACE
      SEPARATE #E-MAIL-ADDR-FAX-NO  /* Parse out any fax authorization code
        INTO #JOB-PARMS(3) REMAINDER #JOB-PARMS(16)
        WITH DELIMITER ','
      IF #JOB-PARMS(3) = ' '
        #JOB-PARMS(3) := 'N/A'
      END-IF
      COMPRESS 'TO-ADDR-NO=' #JOB-PARMS(3)
        INTO #JOB-PARMS(3) LEAVING NO SPACE
      COMPRESS 'AUTH-CD=' #JOB-PARMS(16)  /* In 16 so it is not logged
        INTO #JOB-PARMS(16) LEAVING NO SPACE
      IF #E-MAIL-FAX-NAME = ' '
        #JOB-PARMS(4) := 'TO-NAME=N/A'
      ELSE
        COMPRESS 'TO-NAME=' #E-MAIL-FAX-NAME
          INTO #JOB-PARMS(4) LEAVING NO SPACE
      END-IF
    END-SUBROUTINE

    This routine should be performed once the user has committed to submit the job, and will replace routine BUILD-OUTPUT-DEST which has typically been used.  Note that this routine utilizes the first four parms (and 16), and thus will require adjustment to the other job parameter assignments (Build-Output-Dest used only the first two) made for the specific job -- you will need to start assigning parameter values in the 5th occurrence.
     

  8. Within your JCL, add the following immediately before the execution of your batch report program:

    9. %L
    JOBFAXER
    [JOB-SEQ-NO],[O-DEST-ID],CMPRT0n,l
    [TO-ADDR-NO],[AUTH-CD]
    [TO-NAME]
    xxBrptpgm

    On the third line, two items require customization.  The CMPRT0n should be changed to match the report number on which the report is generated (1 - 9).  The lowercase l represents the landscape option for fax output only.  It should be left blank for portrait output or any non-blank value will result in landscape output.
     

  9. Within you JCL, if e-mail output is permitted a DD is required for work file 10 as follows:

    10. //NATBAT.CMWKF10 DD SYSOUT=(B,SMTP)   -- 06-02-00
     

  10. If e-mailing of output is permitted, any Define Printer statement must be removed from the batch program and the report must write to report (1).

Restrictions

If a batch program produces two or more reports in the same execution, E-mailing is not a valid option since both reports cannot be written to the source work area at the same time (nor can both be output to report (1)).  If this is required, the report program would have to restructured such that the multiple reports are generated in separate programs/subprograms sequentially.  Faxing of multiple reports can be accomplished by executing the JOBFAXER program twice preceding the execution of the report program, once for each CMPRT0n required.  One could be landscape and the other could be portrait as well.

The length/size of the report is a major consideration for either fax or e-mail output.  Faxing a large report will take considerable time, tieing up the fax server and the recepients fax machine.  If it fails mid-way for any reason, multiple attempts will likely occurr to get it transmitted.  E-mail output is restricted to the size of the source work area, if not by other e-mail constraints that might be applied on the sending or the receiving system.  Though a specific limit is not known for either of these options, it is suggested that some screening or reasonableness check be applied before permitting use of these options.

Management of the fax server is an unknown.  Testing has indicated that given valid numbers the above processes work reliably.  However, if incorrect fax numbers are provided or other unknown problems arise it will likely be difficult to track down the problem since management of the fax server (and NetPrt) is out of our hands.  Fax at your own risk.

Similarly, bad e-mail addresses and other system mal-functions will result in undelivered e-mail.  The user's e-mail address as defined on the User Profile is used as the sender (or BASIS@comp.uark.edu if none exist on the User Profile), so the e-mail should be returned their if undeliverable (and if that sending address actually exists).  Needless to say, tracking down delivery problems will be an on-going task as it is with print output.