How can I send email from PCL if any of the text values might include special characters?

Products

Alchemist TPX - Session Management Vman Session Management for z/OS

Issue/Introduction

Environment

Release:
Component: ALCMST

Resolution

Quite often the email to send would only contain the contents of Alchemist variables where special characters would not be encountered. In that case, code the PCL to use a simple inline data method, such as this:

//EMAIL  PROC
//  FREE NOTETXT,COND
//  ALLOCATE NOTETXT,SYSOUT=(B,SMTP) 
//  OPEN NOTETXT,OUTPUT,ACCESS=SEQUENTIAL,RECFM=FB,LRECL=80,
//       BLKSIZE=6160
...SET values as required for use within email text
//  SET SUBBY = '&PCLUSERID'<<F,L>>
//  SET SUBNAME = '&ASRRID.SUBNM'<<F,F+18>>
...
//  WRITE NOTETXT,*,FORMAT=(,SUB)
HELO xxx
MAIL FROM:<########@EXAMPLE.COM>
...
   REQUESTOR: &SUBNAME. (&SUBBY.)
...
//  CLOSE NOTETXT
//  FREE NOTETXT

However, if any of the variables contain special characters, it would be best to set the value of the text line to a variable then write that one line to the file. Continue like this one line at a time, coding the PCL to avoid symbolic substitution where necessary.

It can be especially troublesome for PCL if a creative user enters a "&" within a variable and PCL is coded with symbolics, e.g. using &variablename. This will prompt recursive attempts to resolve the &variables. Request Description is a notorious field for this type of thing. Double and single quotes will also cause headaches. Here is an example of how to accommodate this possibility:

//EMAIL    PROC                                                         
//********************************************************************* 
//* EMAIL: CALLED TO SEND AN E-MAIL MESSAGE                           * 
//* EXECUTION ENVIRONMENT: ANYWHERE                                   * 
//*                                                                   * 
//* SYMBOLIC PARAMETERS:   FROM          - WHOM THE E-MAIL IS FROM    * 
//*                        TO            - ARRAY OF E-MAIL TO's       * 
//*                        CC            - ARRAY OF E-MAIL FROM'S     * 
//*                        TITLE         - TITLE OF THE E-MAIL        * 
//*                        DETAILS       - ARRAY OF DETAIL LINES      * 
//*                                                                   * 
//* RETURN CODES EXPECTED: 0  - SUCCESSFUL                            * 
//*                                                                   * 
//********************************************************************* 
// ALLOCATE NOTETXT,SYSOUT=(B,SMTP)                                    
// OPEN NOTETXT,OUTPUT,ACCESS=SEQUENTIAL,RECFM=FB,LRECL=80,            
//       BLKSIZE=6160                                                   
// SET LINE = 'HELO xxx'                               
// WRITE NOTETXT,LINE                                                  
// SET LINE = 'MAIL FROM:<&[email protected]>'                       
// WRITE NOTETXT,LINE                                                  
...
// SET LINE = 'DESCRIPTION: ':ASRRID.DESC(1)<<1,30>>                    
// WRITE NOTETXT,LINE  
// SET LINE = '             ':ASRRID.DESC(2)<<1,30>>                    
// WRITE NOTETXT,LINE                            
...                                     
// CLOSE NOTETXT                                 
// FREE NOTETXT,COND                             
// EXIT 0

This Frequently Asked Question applies to all supported releases of ESP Alchemist.