JES2Mail and JES2FTP

Robert H. LaBayne
Data-21
Session 8422
March 24, 2000 - Monday 1:30 pm
Email: [email protected]
Benefits
More Trees
Less Paper
 JES2Mail
Input Process Output
Reports: Encode in PDF, HTML, RTF or
text
JES (2 or 3) SYSOUT EMail
Use Script language to:
Sequential Datasets SMTP Standard
Split into sub-reports
ASA or MCC controls Extract data for spreadsheets MIME Encoded
attachments
Sequential Files: Build Bookmarks for PDF
Non-Report Messages
TO:, CC:, BCC
Configuration Insert or create Overlays (Forms) addresses

Report Script Language Distribution Lists

 JES2FTP
Input Process Output

Reports:
Encode in PDF, HTML, or text FTP Server
JES (2 or 3) SYSOUT Use Script language to: Host Sequential File
Sequential Datasets Split into sub-reports
Sequential Files: Build Bookmarks for PDF

Configuration Publish HTML ‘page set’

Report Split Language

 Delivered File Formats
! PDF – Adobe Portable Document Format
– Use Acrobat reader (Free from Adobe)
– JES2Mail supports Overlays
– Outline (Bookmarks) panel can be created
! HTML – Hypertext Markup Language
! RTF – Rich (Revisable) Text Format (JES2Mail)
! ASCII – Plain text
! Comma Delimited Data (JES2Mail).
– The data from a report can be extracted and coded into
this spreadsheet friendly format.
 Operation
! Run as batch job or
! Run as JESWriter started task.
– Uses SAPI for JES access
– Works with JES2 or JES3
! Both OE and Non-OE versions supplied
! OE version uses about 20% less CPU
! OS/390 required (OE, TCP/IP, LE, etc)
! Does not use SMTP server on Host
 JES2Mail Flowchart
PDF
Business
Applicaiton

Mainframe Server HTML

SMTP
JES RTF
2 or 3 JES2Mail TCP/IP Mail
Server

TEXT

Configuration
and Report Comma
Delimited
Ruleset Files Extract
 JES2FTP Flowchart
Business
Applicaiton

Mainframe
PDF
Server

Direct

FTP
JES HTML
2 or 3 JES2FTP TCP/IP File
Sever

TEXT

Configuration
and Report
Ruleset Files
 Report Script Language
! Primarily used to split report into sub-reports
– ‘Break’ on fixed or variable fields
– Can ‘scan’ for data in the report page
! Extract data from report for:
– Dynamic cover page construction
– Addressing (email address is in the report)
– Use as key to a ‘lookup’ table for address
» I.e. Sales Manager ID to Email address
– Routing and formatting decisions
» Different Overlays for different pages based on content
! Designate data for comma delimited secondary
attachment.
 Source of Email Addresses
! The ‘Report Description Ruleset’
! The Report Script Language
! The SYSOUT itself
! An “OUTPUT” JCL statement
! A table lookup, using data from the report
itself as a key. Such as customer number.
 Report Splitting
Sales Report
Account Mgr:
Sales Report 12345
Account Mgr:
12345 [email protected]

JES2Mail
[email protected] Sales Report
Account Mgr:
22222

[email protected]
Sales Manager
Email Address
Table
Sales Report
Account Mgr:
33333
Report
RuleSet
Script
Files
Language
 International Language Support
! Internally we use the IBM-1047 Open Systems
character set.
! Set the LocalCodePage parameter in the
configuration file. For Example:
LocalCodePage: IBM-
LocalCodePage: IBM-273 (Germany)
LocalCodePage:
LocalCodePage: IBM-
IBM-284 (France)
! EBCDIC to ASCII is handled by in internal table.
To override and use IBM translation, code
statement such as:
ASCIICodePage:
ASCIICodePage: ISO8859-
ISO8859-1
 Installation
! Download and expand the distribution library. The .exe is
a self extracting zip file. Or use the CD-ROM.
! Upload the .BIN members into a predefined PDS. Use
FTP or IND$File. Just remember to upload as binary.
! Modify supplied JCL to Linkedit:
– JES2Mail is the non-
non- OE version or
– J2MOE is compiled with Open Edition or
– PREJ2M is a pre Prelinkedit object. This is only needed for
Interlink/Sterling/CA installation.
! Ready to go for batch mode.
! For JESWriter mode, RACF authority is needed for the
started task to access OMVS
 Configuration File (CONFIG)
! PostOffice: address of SMTP Mail Server
! OurDomainName: This host’s name.
! AuthCode:, SplitAuthCode:,
OverlayAuthCode: Set expiration codes
! Trace:
– Min, Std, Full, Dump, Debug
 Simple Email (File mode)
! Send non-report text or HTML messages
! Good for initial ‘Smoke’ testing
! Can attach text or binary files
! Statements supported:
– To:, CC: BCC: - Address
– From: Address
– Subject:
– Date:
– Attach: filename
» Binary or Text
» Can assign new filename
 Sample Filemode Message Job
//JES2MAIL EXEC PGM=JES2MAIL
//LOGFILE DD SYSOUT=*
//CONFIG DD DSN=CASI.ERPR000.CONFIG,DISP=SHR
//STEPLIB DD DSN=CASI.ERPR000.LOAD,DISP=SHR
// DD DSN=SYS1.SCEERUN,DISP=SHR
//SYSIN DD *
TRACE=FULL
FILE=DD:MESSAGE
END
//MESSAGE DD *
to: [email protected]
from: [email protected]
date:
subject: Test message 1
attach: hlq.datafile.pds(jmail1) type:text as:jmail1.txt
(Blank Line)
This is the body of the message.
. (Period)
//
 Configuraton File (Cont)
! JESWaitOnXXXX: Specify primary selection
– XXXXX can be Writer, DestId, Class UserID
! Ruleset: xxxxx
– Key to selection the Ruleset file for processing
– Used in JESWriter Mode
– Designates the PDS member of the CONFIG file.
– Specific or symbolic:
» &DestID
» &FormName
» Others available.
 Ruleset
! The Ruleset is the main focal point for
determining how to process the report.
! A Ruleset is a sequential file or PDS member that
contains from one to many Report Description
statements.
! The first (or only) Report Description is the
default set.
! Each Report Description is separated by a blank
line.
! The statements specify email addresses,
formatting options, report recognition, script
processing, and overlay usage.
 Rulesets Designation
! There are three mechanisms to get to the ruleset.
– JESWriter Mode
» The Ruleset configuration statement
» An explicit RuleSet
RuleSet=
= xxxx in the UserParm of an Output
statement.
– Batch Mode
» Explicate RULESET= command
! Within the Ruleset, the specific Report
Description is determined by a “RecognizeBy”
statement.
! If a report matches several Report Descriptions, it
is processed by each one. Not just the first.
 Ruleset Example:
! Assume that we have set up one Ruleset for each destination.
Within the Ruleset (RULE1), we want to use the FormName
(PDFLAND) to determine how the report is processed.
! The DD statement for the SYSOUT would be something like:

//OUT1 OUTPUT FORMS=PDFLAND,WRITER=JES2MAIL,DEST=RULE1

//PRINT DD SYSOUT=*,OUTPUT=*.OUT1
--- OR ---
//PRINT DD SYSOUT=(A,JES2MAIL,PDFLAND),DEST=RULE1
 Ruleset Example (RULE1):
Name: Default name for RULE1 Ruleset ID: RTF
to: UserID
[email protected]
@Email.company.com
[email protected] recognizeby:
recognizeby : FormName
FormName:: RTF
PackageType=
PackageType =textasa to: UserID
[email protected]
@Email.company.com
Base64=yes PackageType:
PackageType : RTF
coverpage:
coverpage : cover Fontsize=8
Fontsize=8
coverpage:
coverpage : no
ID: HTML font: roman Palatino

recognizeby:
recognizeby : FormName
FormName:: html ID: TEXT
to: UserID
[email protected]
@Email.company.com
PackageType=html
PackageType =html recognizeby:
recognizeby : FormName
FormName:: text
fontSize:
fontSize: 2 to: UserID
[email protected]
@Email.company.com
font: Courier PackageType=text
PackageType=text
coverpage:
coverpage : No
ID: SCRIPT
ID: PDFLand recognizeby:
recognizeby : formname
formname:: SCRIPT
recognizeby:
recognizeby : FormName
FormName:: PDFLAND Name: Name Ruleset ID: SCRIPT
to: UserID
[email protected]
@Email.company.com PackageType=pdf
PackageType=
PackageType:
PackageType : PDF splitscript:
splitscript: script1
Fontsize=9
Fontsize=9
PageHeight:
PageHeight : 8.5
PageWidth:
PageWidth : 11
 Flow of Report to Mail Server
1. JOB creates SYSOUT with appropriate DD statement.
2. JES(2 or 3) passes the report to JES2Mail.
3. JES2Mail opens the connection to the Post Office.
4. JES2Mail determines which RuleSet file to use.
5. The SYSOUT file is opened, and the first page is read
into memory.
6. JES2Mail searches the Report Descriptions for matching
‘RecognizeBy’ statements.
7. The report is formatted according to the instructions and
sent to the SMTP Mail Server for delivery.
8. After checking to see if more SYSOUTs are ready, we
disconnect from the Mail Server, and go back to wait
mode.
 RecognizeBy Statement
! The RecognizeBy statement controls which
Report Description to use within the Ruleset
– RecognizeBy:
» JOBName
» ProcName
» StepName
» Output Class
» FormName
» DestID
» DDName
» FlashName
» FCBName
» Text content on the first page of the report. In either a fixed
position or by scanning.
 Email Address from JCL
! JES2Mail can also get email processing options
directly from the generating JOB’s JCL.
! For example:
//OUT1 OUTPUT WRITER=JES2MAIL,
// USERDATA=(“RULESET: RULE2”,
// “REPID: PDFLAND”
// “Subject: Sales Report”),
// ADDRESS=(“To: [email protected]
[email protected]”,
”,
// “CC: copyuser
[email protected]”)
@email.company.com”)
//PRINT DD SYSOUT=*,OUTPUT=*.OUT1

! Advantage: Don’t have to create a Ruleset for each destination.

! Disadvantage: More JCL to change if user’s address changes.
! The Ruleset
Ruleset,, RULE2, is the same as RULE1, except the To: statements
are removed.
 Email addresses
! Address support for multiple destinations.
! Addresses are used for To:, CC:, BCC: and From:
statements.
! Email address can be just the user@domain
format, as in:
[email protected]
! Or with A human readable name, as in:
Bob LaBayne <[email protected]>
! Or a file reference to a route list, as in:
@list=HLQ.FILE.NAME
 Filename Designations
! A filename that begins with “DD:”, refers to
a DD statement.
! A filename less than nine characters, is a
member of the CONFIG PDS
! Otherwise the filename is fully qualified
dataset name.
Report Processing Language
 Report Script Language
! Invoked by the SplitScript: statement in Report
Description in Ruleset
! Required for Report splitting (Bursting) operations
! Can extract data from the report page to:
– Use for Email address
– Use as key to ‘lookup’ an email address in a table
– Make an entry into the Outline portion of a PDF file
– Create the secondary Comma Delimited data file.
– Insert data into the message header fields
– Insert data into the cover page.
» Very useful when the cover page is to be a HTML formatted
page.
! Dynamically select the Overlay for the page.
 Script Procedure Sections
! )InitialPage
– Performed only once
– Best place to define variables
– The ‘First page’ of report is available for processing
! )OnSubReportBegin
– Performed at the beginning of each sub-report, after a
report break is detected.
– The ‘first page’ of sub-report is available for
processing.
! )OnEachPage
– Performed for each page
– If present, the section must include an explicit
OutputPage() statement to generate the page.
Script Procedure Sections (cont).
! )Break
– Performed on each page to set break variables
» Either set ZBreakValue to a value from the report
ZBreakValue = StringAt
StringAt(3:25,
(3:25, 8)
» Or set ZBreak to 1 to trigger the break.
ZBreak = 1

! In non procedure sections

– Statements can be used in non-procedure sections by
placing a ‘#’ in column 1.
– Usually used to dynamically include or not various
addressing or other statements.
– Variable values can be inserted by encode the variable
is “&” and “;”.
To: &ToVar
&ToVar;@&
;@&ZOurDomainName
ZOurDomainName;;
 Script Non- procedure Sections
! )MessageHeading
– Contains To, From, CC, Bcc addressing
– Subject statement
– Date statement
– Attachments other than report
! )CoverPage
– Define the coverpage for the attached report.
– Can be in plain text or HTML
! Include nested files
– The /Insert statement can be used to insert additional
files.
– Nesting can be 10 levels deep.
 Variables
! Variable types:
– String - Up to 255 characters long
– Int – Full word int
– POS – Position
! LineNo :Column – As in 3:25
LineNo:Column
! Upper left is 0:0, lower right can be 255:255
– Case insensitive
– Can be defined in any section, just must be defined
before use.
! System Variables usually begin with “Z”. (Just by
convention, there are no reserved variable prefixes
or the like).
Sample Report
 Example of script
)InitialPage
Define(SUBTITLEPOS, POS);
Define(FROMVAR, String);
Define(TOVAR, String);
Define(LENDER, String);
FROMVAR = "[email protected]
"[email protected]"
.com"
SUBTITLEPOS = LocateText
LocateText(“
(“Servicer
Servicer:: ") ;FIND THE SERVICER
SUBTITLEPOS = SUBTITLEPOS + 0:11 ;BUMP PAST TAG
 Example of script
)OnSubReportBegin
LENDER = StringAt
StringAt(SUBTITLEPOS,
(SUBTITLEPOS, 20) ;GET LENDER ID
ToVar = LOOKUP(TABLE, "LENTAB", LENDER) ;Lookup address
if(ToVar
if( ToVar == "") ;Was lookup good?
Define(ERRORMSG, String) ;No
ToVar = "defaultuser
"[email protected]"
@company.com" ;Set default dest
ERRORMSG = "Unknown Lender: " + Lender ;create Error msg
Display(Error, ERRORMSG) ;Write Error msg
else
Define(MSGLINE, String)
MSGLINE = “Servicer
“Servicer:: " + Lender + " Addressed to: " + ToVar
ToVar;;
Display(Min, MSGLINE)
endif
 Example of script
)BREAK
ZBreakValue = STRINGAT(SUBTITLEPOS, 20) ;Break on Lender

if(ZLPageNo > 1000)

if(ZLPageNo ;Break on 1000
pages
Zbreak = 1
endif
 Example of script
)MessageHeading
to: &ToVar
&ToVar;;
from: &FROMVAR;
SUBJECT: Funds Disbursement Report for &Lender;
Attach: hlq
hlq.data.file
.data.file type: Bin as: “datafile
“datafile..abc
abc”
”
 Example of script
)CoverPage html
<html>
<Head>
<title>
LENDER DISBURSEMENT REPORT
</title>
</head>
<body>
<bold>Lender:</bold> &Lender; <br
<br>
>
OurDomainName:
OurDomainName: &zOurDomainName
&zOurDomainName;; <br>
<br>
JobName:
JobName: &Zjobname
&Zjobname;
; <br>
<br>
</body>
</html>
 JCL Example
//JMAIL4C JOB …
//*
//JES2MAIL EXEC PGM=JES2MAIL
//LOGFILE DD SYSOUT=*
//CONFIG DD DSN=HLQ.JES2MAIL.CONFIG,DISP=SHR
//STEPLIB DD DSN=HLQ.JES2MAIL.LOAD,DISP=SHR
// DD DSN=SYS1.SCEERUN,DISP=SHR
//SYSIN DD *
TRACE=std
RULESET=DD:RULE
REPORT=HLQ.REPORT.FILE
END
//RULE DD *
NAME: REVENUE REPORT TEST
TO: [email protected]
PACKAGETYPE=PDF
FONTSIZE=8
Font: Courier
ORIENTATION: L
SPLITSCRIPT: SCRIPT1
PDF Overlays
 Overlay Definition File
! Invoked from the Ruleset Statement:
Overlay: xxxxx
! Can define a dynamically created ‘stock paper’
form. (Green bar)
! Can be based on a graphically created PDF form.
Such as an Invoice, or IRS form.
! The supplied PrepHost PC program will convert
(extract) a page from a PDF file and convert it into
an Overlay file, ready for uploading and use by
JES2Mail.
! With the Script language, different overlays can be
applied to each page of the report.
Green Bar Example
IRS Sample W2
Letterhead From Sweden
 The Overlay ‘Source’ PDF
! Government forms are available on Web sites.
! The graphic artist that designed the form.
! Create your own:
– Create the overlay document with PC document tools,
such as MS Word, Adobe PageMaker, etc.
– Convert the ‘Document’ into a PDF file using Adobe
Acrobat (Full version, not the ‘reader).

Note: Don’t ‘scan’ a blank document and generate the

PDF. It works, but the scans are usually huge files.
 Flow of Overlay process
Orignal 'Master' Sales Report
PDF File
Account Mgr:
12345 Sales Report
Account Mgr:
12345
[email protected]
PREPHOST
PC program JES2Mail

Upload
overlay
to host.

Stored Overlay Report RuleSet

Overlay Definition Script Files
 Overlay use - Ruleset

ID: GreenBar
Name: Greenbar Stock Paper
recognizeby: formname: Greenbar
to: &DestID;@casisoft.com
PackageType=pdf
Fontsize=9
font: Courier
Overlay=Greenbar (Link to Overlay Definition)

Overlay statement specifies filename (PDS Member) of an

Overlay Definition Set
 Overlay Definition – Stock

OverLayName: GreenBar
type: Stock
BarColor: LiteGreen
LinesPerInch: 8
StockStyle: Bar
LinesPerBar: 4
TextColor: Black
BarLineColor: Red
OffsetVertical: -2
OffsetHorizontal: -1
TopMargin: .5
BottomMargin: .5
LeftMargin: .5
RightMargin: .5
PageHeight: 8.5
PageWidth: 11
 Overlay Definition – Form

OverLayName: irsw2
FILENAME: HLQ.JES2MAIL.PDFFORM(IRSW2) (The overlay file)
type: Form
LinesPerInch: 6
OffsetVertical: -7
OffsetHorizontal: -3
AlignmentPage: No
TopMargin: .5
BottomMargin: .5
LeftMargin: 1.0
RightMargin: .5
Comma Delimited Data Extract
 Comma Delimited Extract
! Generates a second attachment file ready for
spread sheet use
! Controlled by the script language
! Fields can be parsed by a character string (such as
two blank characters)
! Field can be parsed according to a ‘Mask’
! Handles US and non-US numbers
! Can specify the desired ‘separator’ character,
other than a comma.
Sales Report Sample
Excel Spread Sheet
 Comma Delimited Sample Script

)OnSubreportbegin
zExtractFileName = "ExtractData.csv"
ExtractData(Comma, " ", 5:2, 5:199)

)OnEachPage
ExtractData(Comma, "25x,11z,13z,13z,13z,13z,13z,13z,13z ", 7:2)
outputpage();
//JES2MAIL EXEC PGM=JES2MAIL
//LOGFILE DD SYSOUT=*
//CONFIG DD DSN=CASI.ERPR000.CONFIG,DISP=SHR
//STEPLIB DD DSN=CASI.ERPR000.LOAD,DISP=SHR
// DD DSN=SYS1.SCEERUN,DISP=SHR
//SYSIN DD *
TRACE=STD
RULESET=DD:RULE
REPORT=HLQ.REPORT.FILENAME
END
//RULE DD *
NAME: PDF REPORT TEST
TO: Sam Snead <[email protected]>
FROM: JES2MAIL@&OurDomainName;
PACKAGETYPE=PDF
FONTSIZE=8
Font: Courier
ORIENTATION: L
Overlay: GreenBar
SPLITSCRIPT: DD:SCRIPT
//SCRIPT DD *
)OnSubreportbegin
zExtractFileName = "ExtractData.csv"
ExtractData(Comma, " ", 5:2, 5:199)
)OnEachPage
ExtractData(Comma, "25x,11z,13z,13z,13z,13z,13z,13z,13z ", 7:2)
outputpage();
PDF Bookmarks (Outlines)
 PDF Outline (Bookmarks)
! Available to both JES2FTP and JES2Mail
! Up to four levels of indexing
! Allows instant ‘jumping’ to specific pages
in PDF report
! When present, the PDF is set to
automatically open and show the book mark
panel of Acrobat
Bookmark Example
 BookMark Script

)OnEachPage
Define(Name, string)
OutputPage()
Name = StringAt(14:6, 25)
OutLine(1, Name)

! Note: Issue the OutLine statement AFTER the OutputPage

 For Further Information
! Download JES2Mail or JES2FTP from:

WWW.DATA21.COM

Or contact sales:
David Kennedy at 310-792-1773
[email protected]
For technical questions:
Bob LaBayne at 760-772-4262 or
[email protected]