53
Chapter 4. Using the Infoprint Server for iSeries PDF transform
125
4.7.2 Addressing your e-mail with USRDTA and an e-mail exit program
In the previous section, it was indicated that in V5R1, the USRDFNDTA
parameter must be specified in the printer file before running the application. It is
not available for use in the Change Spooled File Attribute (CHGSPLFA)
command.
If you do not have access to make the required application changes prior to
creating the spooled file, there is an alternate technique you can use. This
involves entering a unique value in the USRDTA parameter of the spooled file.
This parameter is available from the CHGSPLFA command, as well as the
CRTPRTF, CHGPRTF, or OVRPRTF commands. This method requires using an
e-mail exit program to convert the 10-character value used in the USRDTA
parameter to a valid e-mail address.
This corresponds to branch (B) in Figure 78.
4.7.2.1 PSFCFG for single e-mail, with exit program
Figure 82 illustrates the parameters used by Create PSF Configuration that are
used to send single e-mail files if using an e-mail exit.
Figure 82. PSF configuration object for single e-mail, no user exit program
You need to complete the following parameters:
• Generate PDF output (PDFGEN): Specify
*MAIL
to generate the PDF file as
an e-mail attachment.
• PDF device emulation type (PDFDEVTYPE): IBM recommends setting this
to
*IP40300
, which corresponds to the functions of an IBM Infoprint 40 set to
300 dots per inch.
• PDF paper size drawer 1 and 2 (PDFPPRDWR1 and PDFPPRDWR2): Set
this to the paper size used by the application.
• Multiple PDF files (PDFMULT): Set this to
*NO
to send each file as a single
e-mail.
• PDF data queue (PDFDTAQ): Specifies the name and library of the data
queue where PDF logs the transformation completion notifications. If you
specify this parameter, the data queue must exist and have a minimum length
Create PSF Configuration (CRTPSFCFG)
Type choices, press Enter.
PSF configuration . . . . . . . > EMAIL1EXIT Name
Library . . . . . . . . . . . QGPL Name, *CURLIB
Generate PDF output . . . . . . > *MAIL *NONE, *SPLF, *STMF, *MAIL
PDF device emulation type . . . > *IP40300 *IP40240, *IP40300, *P4028...
PDF paper size drawer 1 . . . . *LETTER *LETTER, *LEGAL...
PDF paper size drawer 2 . . . . *LETTER *LETTER, *LEGAL...
Multiple PDF files . . . . . . . *NO *NO, *YES
PDF data queue . . . . . . . . . > PDFDTAQ Name, *NONE
Library . . . . . . . . . . . > QGPL Name, *CURLIB
Sender of electronic mail . . . > EMAILMGR Name, *SPLFOWN, QSPLJOB
PDF user program . . . . . . . . EXIT1 Name, *NONE
Library . . . . . . . . . . . QGPL Name, *CURLIB
Text 'description' . . . . . . . > 'Email PDF files as single file with exit'
50
126
iSeries Printing VI: Delivering the Output of e-business
of 752 characters. See E.2, “PDF data queue structure” on page 346, for
additional information.
• Sender of electronic mail (PDFSENDER): Specifies the sender from whom
the PDF output file is e-mailed. The sender must be a valid user profile and be
enrolled in the system distribution directory. Any non-delivery messages
caused by invalid e-mail addresses is sent to this user. For additional
information on non-delivery messages, see Chapter 14, “End-to-end example”
on page 283.
• PDF user program (PDFMAPPGM): Specify the name and library of the user
e-mail exit program. This program is used to look up a valid e-mail address
based on the information in the USRDTA field.
4.7.2.2 Printer DEVD for single e-mail, with exit program
Create a device description that uses this PSF Configuration object by specifying:
CRTDEVPRT DEVD(EMAIL1EXIT)
DEVCLS(*LAN)
TYPE(*IPDS)
MODEL(0)
LANATTACH(*IP)
AFP(*YES)
PORT(5004)
FONT(416 12)
RMTLOCNAME('127.0.0.1')
USRDFNOBJ(QGPL/EMAIL1EXIT *PSFCFG)
TEXT('Use for PDF email, single files, with exit pgm')
4.7.2.3 Changing the value for USRDTA
The User Data field may be modified using the Change Spooled File Attributes
(CHGSPLFA) command. You may specify up to 10 characters. A quick way is to
do this interactively. Display a list of your spooled files using a command such as
WRKSPLF or WRKOUTQ. Then enter option
2
next to the desired spooled file
and type the USRDTA information on the command line.
In Figure 83, you see an example of the Work with All Spooled Files (WRKSPLF)
display. The User Data for the first spooled file is already set. The process is
about to be repeated for the second spooled file.
Figure 83. Changing the USRDTA value for a spooled file
Work with All Spooled Files
Type options, press Enter.
1=Send 2=Change 3=Hold 4=Delete 5=Display 6=Release 7=Messages
8=Attributes 9=Work with printing status
Device or Total Cur
Opt File User Queue User Data Sts Pages Page Copy
EMAIL MSHNIER MSHNIER CUST000426 RDY 8 1
2 EMAIL MSHNIER MSHNIER RDY 8 1
Bottom
Parameters for options 1, 2, 3 or command
===> usrdta(CUST000136)
F3=Exit F10=View 4 F11=View 2 F12=Cancel F22=Printers F24=More keys
45
Chapter 4. Using the Infoprint Server for iSeries PDF transform
127
From within a program, you can override or change the USRDTA field by placing a
CALL to the system program QCMDEXC.
4.7.2.4 Exit program to map USRDTA
The name and library of the e-mail exit program are specified in the PSF
Configuration object. Each time Infoprint Server process a PDF file that is to be
sent as an e-mail, the exit program is called.
Information about the input spooled file is passed to the exit program via the input
data structure. The program uses this information to look up or generate a valid
e-mail address. In addition, the exit program may also be used to build a message
of up to 255 characters. This message appears in the body of the e-mail, along
with the PDF attachment. The e-mail address and message are passed back to
Infoprint Server via an output data structure.
In this scenario, we use the value from the USRDTA field, which is made available
to the program via positions 647 to 656 of the input data structure. This value is
used in a lookup operation to an external file to obtain the e-mail address and
optionally other information that may be used in the custom message.
A sample of a e-mail exit program is found in E.1, “E-mail exit program” on
page 343. Along with the generation of the e-mail address and message, it also
performs some additional tasks in the case of a failure of the lookup operation. It
may be used as a template for addressing using USRDTA with some minor
modifications. Consider the following points:
• Note that the USRDTA field is made available to the exit program in positions
647 to 656 of the Input Data Structure (INPUTDS).
• The existing sample uses the first six characters from the MAILTAG field as
key to the lookup operation. Modify the program to use the 10-character
USRDTA field.
• Modify the LOOKUP file to match the expected data from the USRDTA field. In
particular, change the length of the key field.
• The result of the LOOKUP program returns one or more e-mail addresses,
which you pass via the ADDRESS field in Output Data Structure (OUTDS)
starting in position 288. In the sample program, a length of 255 was assigned
to this field. If necessary, the length may be changed up to 16 MB long.
• Customize the Message and not-found actions to suit your specific application
needs.
4.8 Creating multiple PDF files
In previous sections, we describe how to set up the PSF Configuration object to
generate single files on the IFS, single spooled files, or single e-mails. Infoprint
Server for iSeries enhances these operations by providing the means to take one
original spooled file and generate multiple PDF files in the IFS, multiple new PDF
spooled files, or multiple files being directed to different e-mail destinations.
You may need to do this is if your application generates one spooled file
containing multiple customer statements. You want to segment it on statement
boundary to generate multiple PDF files.
50
128
iSeries Printing VI: Delivering the Output of e-business
4.8.1 PSF configuration object for multiple PDF files
The PSF configuration object used to create multiple files for print, storage, or
e-mail is similar to the corresponding PSF Configuration object used for single
files for each of the three file types. The main difference is that the parameter
Multiple PDF files (PDFMULT) is now set to *YES.
Figure 84 shows an example of the parameters used to create a PSF
Configuration object to generate multiple PDF files. In this particular case, the
files are to be sent via e-mail, and a user exit program is specified.
Figure 84. PSF configuration object for multiple PDF file
To generate the multiple PDF spooled files or multiple files on the IFS, refer to the
PSF Configuration objects described 4.5, “Creating a PDF file for storing in the
IFS” on page 112. To generate multiple files, change the value for Multiple PDF
Files from *NO to
*YES
.
4.8.2 Printer file for multiple PDF file
Create a device description that uses the PSF configuration object for creating
multiple PDF files by specifying:
CRTDEVPRT DEVD(EMAILMULT)
DEVCLS(*LAN)
TYPE(*IPDS)
MODEL(0)
LANATTACH(*IP)
AFP(*YES)
PORT(5005)
FONT(416 12)
RMTLOCNAME('127.0.0.1')
USRDFNOBJ(QGPL/EMAILMULT *PSFCFG)
TEXT('Use for PDF email, single files, with exit pgm')
4.8.3 Segmenting the spooled file
Whether you are generating multiple PDF files to be re-spooled in an output
queue, placed in the IFS, or sent as an e-mail, you need a way to tell the PDF
subsystem of Infoprint Manager for iSeries how you want it to break up the
Create PSF Configuration (CRTPSFCFG)
Type choices, press Enter.
PSF configuration . . . . . . . > EMAILMULT Name
Library . . . . . . . . . . . QGPL Name, *CURLIB
Generate PDF output . . . . . . > *MAIL *NONE, *SPLF, *STMF, *MAIL
PDF device emulation type . . . > *IP40300 *IP40240, *IP40300, *P4028...
PDF paper size drawer 1 . . . . *LETTER *LETTER, *LEGAL...
PDF paper size drawer 2 . . . . *LETTER *LETTER, *LEGAL...
Multiple PDF files . . . . . . . *YES *NO, *YES
PDF data queue . . . . . . . . . > PDFDTAQ Name, *NONE
Library . . . . . . . . . . . > QGPL Name, *CURLIB
Sender of electronic mail . . . > EMAILMGR Name, *SPLFOWN, QSPLJOB
PDF user program . . . . . . . . EXITMULT Name, *NONE
Library . . . . . . . . . . . QGPL Name, *CURLIB
Text 'description' . . . . . . . > 'Email PDF files as multiples'
44
Chapter 4. Using the Infoprint Server for iSeries PDF transform
129
original spooled file. This is done by inserting
group tag
records into the spooled
file.
There are three ways to generate applications with group tags:
• Using DDS printer file keywords
• Using the Infoprint Server Create AFP Data (CRTAFPDTA) command to
generate index information
• Using the AFP Toolbox APIs
In the case of e-mail delivery, you need to provide valid e-mail addresses to the
PDF subsystem. The information provided by the group tag record may contain a
valid address, in which case, an e-mail exit program may not be necessary. If the
tag is more generic, for example a customer number, you must use the e-mail exit
program to look up the e-mail address.
This section describes the three methods of inserting the group tag records used
by all three delivery methods. It also covers specific information on specifying an
e-mail address, with and without the use of an e-mail exit program. Referring
back to the address decision tree in Figure 78 on page 121, this section covers
the branches labeled C and D.
4.8.3.1 Using DDS printer file for indexing
If you have access to the original application program and DDS,
and
are in a
position where you can generate your spooled files as AFPDS, you can use the
DDS record-level keywords, STRPAGGRP and ENDPAGGRP, to tell Infoprint
Server for iSeries how to break the original file into groups of pages. This
corresponds to branch C in Figure 78 on page 121.
One PDF file is generated between every STRPAGGRP and ENDPAGGRP
keyword pair. If you choose to specify groups, all of the data must be inside a
group. Groups of pages cannot be nested or overlapped, each group must be
ended with the ENDPAGGRP keyword before another can begin.
The group name should be unique within a document. The maximum number of
characters in the group name is 250.
The group name may be hard coded into the DDS. However, it is more likely that
it would be passed as a variable using
program-to-system fields
.
Program-to-system fields are defined by entering a “P” in position 38 of the DDS
specification for the field. The program would supply the value, which in turn,
would be used as a parameter for the STRPAGGRP keyword.
The examples in Figure 85 show how to specify the STRPAGGRP and
ENDPAGGRP keywords.
45
130
iSeries Printing VI: Delivering the Output of e-business
Figure 85. Examples of the STRPAGGRP and ENDPAGGRP keyword
In the example, the STRPAGGRP keyword in RECORD1 contains a valid e-mail
address. An e-mail exit program is not necessary if this format is used.
RECORD2 starts a group named CUST68839. If this tag were used for an e-mail
application, an exit program must be used to map that to a valid e-mail address.
RECORD3 illustrates the use of a program-to-system field. The program would
assign a value to the field GROUP, just as it would any other field you would
normally print. The difference is that there is a “P” in position 38 of the
specifications. This tells DDS not to print the field, but rather, to use it as a
variable in one of the other keywords, in this case, STRPAGGRP. The use of an
exit program would be determined by whether the value for GROUP was a valid
e-mail address or just a key to a lookup file.
RECORD4 uses the ENDPAGGRP keyword to end a group that was previously
started with the STRPAGGRP keyword.
In the example of an invoice or statement, consider using the STRPAGGRP
keyword immediately after writing the invoice header or address information, and
the ENDPAGGRP after writing the totals or summary information.
Using the exit program with the STRPAGGRP keyword
If you are generating your PDF files for the e-mail function, and the value used in
the STRPAGGRP keyword is a valid e-mail address, you do not necessarily need
an e-mail exit program. You may choose to use one if you want to add a message
to the body of the e-mail.
You may find it convenient to keep the maintenance and selection of e-mail
addresses separate from the application program that generates the spooled file.
For example, an invoice program already has the customer number available, so
the modifications to output it with the STRPAGGRP keyword are not extensive. A
separate set of programs and files can be used to maintain the e-mail address
lists. The e-mail exit program is then used to map the tag used in STRPAGGRP
with the valid address.
The e-mail exit program sample in E.1, “E-mail exit program” on page 343, may
be used as a template. The value provided by STRPAGGRP is available as the
Mail Tag field of the input data structure. Use this (or a substring) to look up the
e-mail address.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....
A R RECORD1
A STRPAGGRP('CUST68839')
A
A R RECORD2
A STRPAGGRP('simon_h@uk.ibm.com')
A
A R RECORD3 STRPAGGRP(&GROUP)
A GROUP 50A P
A R RECORD4 ENDPAGGRP
46
Chapter 4. Using the Infoprint Server for iSeries PDF transform
131
4.8.3.2 Using CRTAFPDTA indexing
The Create AFP Data (CRTAFPDTA) command may be an alternative to using the
DDS keywords STRPAGGRP and ENDPAGGRP to segment the spooled file.
These DDS keywords require you to generate spooled files that are in AFPDS
format and modify the DDS. There are a number of common scenarios where
these conditions may not be met:
• If the spooled file is generated as line data and uses a page definitions for
formatting. This is the case for users of Infoprint Designer for iSeries using the
Layout tool.
• The spooled files are generated using program-defined printer files. This is
common if the application was originally written for the IBM System/36.
• The spooled files are generated by a purchased package and you do not have
the ability or access to make the required modifications to the program and
DDS source.
If you find that any of the above conditions apply, you need an alternate method
to instruct Infoprint Server how to break up your file and destination to whom the
segments are to be mailed. The CRTAFPDTA command, which is another
component of Infoprint Server for iSeries, may be the solution.
This corresponds to branch D in Figure 78 on page 121.
Requirements for using CRTAFPDTA
The CRTAFPDTA command has two important requirements that must be met in
order to use it to generate the index records:
• The input spooled file must be in line data format.
• The information used to generate the index information must be in predictable
positions within the printer file.
Line data
If you are using Infoprint Designer for iSeries to create your application, you are
generating line data in order to use the page definitions generated by the Layout
function.
Many other applications on the iSeries generate SCS data stream. These are
often heritage applications originally written for the S/36 or ERP applications that
do not provide any formatting capability. Line data is very similar to SCS. If you
have the ability to change or override the printer file, it is an easy task to convert
it to produce line data instead. You can use either of the following commands:
CHGPRTF mylib/myprtfile DEVTYPE(*LINE)
OVRPRTF mylib/myprtfile DEVTYPE(*LINE)
Section 2.10.1, “Changing printer file to *LINE data” on page 82, describes a
technique to create a separate printer file with the appropriate parameters and
place it higher up in the library list. This technique may help you generate line
data for use with CRTAFPDTA.
Predictable data positions
The indexing function of CRTAFPDTA needs to know where to look in the spooled
file for the information it needs to identify the break points between the different
parts of the spooled data. If the file is to be sent as an e-mail, you need to provide
48
132
iSeries Printing VI: Delivering the Output of e-business
meaningful data, such as customer number to use for the lookup operation in the
e-mail exit program.
Refer to the Chapter 4, “Using the Infoprint Server for iSeries PDF transform” on
page 103, and to Chapter 5, “Infoprint Server for iSeries: CRTAFPDTA” on
page 149, for a detailed explanation on how to setup the CRTAFPDTA command
to identify the segments of the spooled file and add index records.
Using CRTAFPDTA for PDF creation
The CRTAFPDTA command generates output on the IFS. If the target directory is
in the QSYS.LIB subsystem, the data can be accessed as a physical file member.
The PDF generation in Infoprint Server works on spooled files. The data in the
physical file created by CRTAFPDTA must be re-spooled using the Print AFP
Data (PRTAFPDTA) command before it is converted to PDF.
Chapter 14, “End-to-end example” on page 283, describes a complete scenario,
from developing an application using Infoprint Designer and sending multiple PDF
files as e-mail attachments. It includes detailed step-by-step instructions for each
stage of the process:
• Modifications to the Infoprint Designer project (if necessary)
• A single, one-time modification to the application (if necessary)
• Using CRTAFPDTA to index the data
• Using PRTAFPDTA to re-spool the indexed file
• Viewing the indexed spooled file with the AFP Viewer
• Creating a PSF configuration object and an output queue for PDF conversion
• Creating an exit program to lookup e-mail addresses
• Monitoring for undeliverable mail
• Other maintenance tasks
If you are using CRTAFPDTA to index your spooled file in order to generate
multiple PDF files, please refer that the appropriate sections of that chapter.
Using the e-mail exit program with CRTAFPDTA
The exit program in E.1, “E-mail exit program” on page 343, was designed to be
used with the index keys generated by CRTAFPDTA. Customize it to suit your
individual requirements.
The data generated as the key tag field has an eight-character numeric string
appended to ensure that the keys are unique. You need to perform a substring
operation to separate out the key, such as the customer number, prior to
performing the lookup function.
4.8.3.3 Using the AFP Toolbox
The AFP Toolbox is a package that contains procedure function calls to be
included in an RPG, COBOL, or C++ program. It is intended for a highly skilled
programmer to build AFPDS applications directly. See 1.1.5, “AFP PrintSuite –
AFP Toolbox” on page 11, for more information.
The AFP Toolbox includes procedures for Begin Group and End Group, which
work in a similar fashion to the DDS keywords STRPAGGRP and ENDPAGGRP.
For specific syntax information, see the
IBM AFP Toolbox for Multiple Operating
Systems User's Guide
, S544-5292.
Documents you may be interested
Documents you may be interested
