Documentation on the Extension Area Format used by PDF Mapping Programs

Resolving The Problem

This document provides information on the Extension Area Format that can be used by PDF user programs associated with the Infoprint Server for iSeries product. This information is taken directly from the MappingProgramOutputInformation.htm file that is located in the /QIBM/ProdData/OS400/PrintServicesFacility directory in the Integrated File System (IFS) after applying either of the following PTFs:

6.1 PTF SI36971 OSP-BASEDIR INCORRECT DOCUMENTATION OF THE PDF MAPPING PROGR
5.4 PTF SI36966 OSP-BASEDIR INCORRECT DOCUMENTATION OF THE PDF MAPPING PROGR

---

For more information on the Extension Area Format and PDF mapping program examples, please refer to Chapter 6. Using the PDF mapping program in the IBM® Redbooks™ IBM eServer iSeries Printing VII: Infoprint Server Implementation, which is available at:

http://publib-b.boulder.ibm.com/Redbooks.nsf/RedpaperAbstracts/redp3752.html?Open

and Appendix B. Mapping Program in the Infoprint Server for iSeries User's Guide (G544-5775-05) publication:

7.1	http://pic.dhe.ibm.com/infocenter/iseries/v6r1m0/topic/rzair/g5445775.pdf
6.1	http://pic.dhe.ibm.com/infocenter/iseries/v6r1m0/topic/rzair/g5445775.pdf
5.4	http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/books/g5445775.pdf

How the PDF Mapping Program is called by PSF/400 For a non-segmented spooled file, PSF/400 will call the map program twice. The first call is to get encryption settings, if any. The second call is to get distribution information. Note: If you wish to have either the PDF stream file or PDF spooled file encrypted, but not have the PDF emailed, you must do the following in your exit program to ensure that the PDF file is not e-mailed:
o	On the first call to the map program, set the Disposition of PDF e-mail field to '1'. The map program identifies the first call to it by checking that the first byte in the Path and name of PDF file field (declared in the Mapping Exit Program Input Information structure at offset 0x122) is a blank character (0x40).
o	On the second call to the map program, set the Disposition of PDF e-mail field to '0'. The map program identifies the second call to it by checking that the first byte in the Path and name of PDF file field (declared in the Mapping Exit Program Input Information structure at offset 0x122) is not a blank character (0x40).

Using a spreadsheet to calculate length and offset values

The IBM® Redbooks™ IBM eServer iSeries Printing VII: Infoprint Server Implementation includes a spreadsheet that can be used to help calculate the lengths and offsets in a PDF mapping program. This spreadsheet was designed prior to adding the following new fields to the end of the Extension Area Format:

Decimal Offset	Hex Offset	Field Name	Type	Description
100	64	PDFSENDER	CHAR(10)	Mail sender
110	6E	ENCRPTSTMF	CHAR(1)	Encrypt PDF stream file ** new **
111	6F	ENCRPTSPLF	CHAR(1)	Encrypt PDF spooled file ** new **

However, an updated spreadsheet is attached to this document:

mapping_program_output_data_structure_fields (updated).XLS

Note: Every attempt has been made to ensure the accuracy of this updated spreadsheet. However, this updated spreadsheet is provided "AS IS" with no guarantee of its accuracy.

---

Update to special instructions for APAR SE38166

The Extension Area Format documented in previous special instructions had omitted a field, Length of PDF file name for PDF attachment for e-mail. This field has always been defined in the header files used by customer PDF user programs. These special instructions have been updated to accurately reflect the definition of the Extension Area Format in the header files.

Special instructions for APAR SE38166

These are the special instructions for APAR SE38166. These instructions describe new function for PDF processing and the new fields added to the Extension Area Format that can be used by PDF user programs. The Extension Area Format was previously updated in APAR SE32012. The special instructions for APAR SE32012 are included.

Function added with APAR SE38166

APAR SE38166 adds PSF support for encrypting PDF files output as stream files and spooled files. This support requires specifying encryption specifications for e-mail with either a PDF mapping object or a PDF user program. If you use a PDF user program, you must get the new header files with the PTF for APAR SE38183. Encryption specifications can be specified for e-mail only. This PTF provides a method for using the e-mail encryption specifications for stream files and spooled files and the ability to control whether the e-mail is sent. The method for indicating whether a stream file or spooled file is to be encrypted differs, depending on whether a PDF mapping object or a customized user exit program is used.

Using a PDF mapping object

You can specify parameter PDFENCRYPT on the printer file's USRDFNDTA parameter. Shown below are examples of using PDFENCRYPT.

PDF Encryption (PDFENCRYPT)

Specifies whether the stream file or spooled file PDF distribution options are encrypted and whether the e-mail is to be sent. This parameter is used only when a PDF map object and the default IBM-supplied mapping program are specified in a PSF configuration object. PDFENCRYPT is ignored when a PDF user program is used or encryption is not specified. Using this parameter requires encryption values to be specified either in the selected PDF map object entry for email distribution. The values specified for PDFENCRYPT let you specify which distribution options output an encrypted PDF file. If encryption is not specified for an email distribution, this parameter is ignored. You can specify one or more of the values with this parameter except when a value of *NONE is specified. If you choose to split a spooled file into multiple groups, the values specified for PDFENCRYPT apply to every group in the spooled file.

*NONE
Encryption and e-mail distribution options are not specified at the spooled file level. The encryption values specified in a PDF map object are used. Specifying PDFENCRYPT(*NONE) is the same as not specifying PDFENCRYPT. A value of *NONE cannot not be specified with any other values. If other values are specified with *NONE they are ignored.

*NOMAIL
The e-mail is not sent. If this value is not specified, the e-mail is sent.
Use *NOMAIL to encrypt a stream file or spooled file without sending an e-mail.

*STMF
The generated PDF file placed in a stream file is encrypted.
If this value is not specified and a stream file is generated, the stream file is not encrypted.
If the stream file distribution option is not specified, this value is ignored.

*SPLF
The PDF file placed in a spooled file is encrypted.
If this value is not specified and a spooled file is generated, the spooled file is not encrypted
If the spooled file distribution option is not specified, this parameter is ignored.

Examples of using PDFENCRYPT

Shown below are examples of using the PDFENCRYPT parameter. For each of the examples, you must perform the steps shown below in addition to the steps shown for each example.

o Specify the e-mail distribution option in a PDF map object entry or segment.
o Specify encryption values for the e-mail distribution option.
o Specify the name of the PDF map object with parameter PDFMAP in the PSF configuration object used by PSF.
o Specify the default IBM-supplied user program with parameter PDFMAPPGM in the PSF configuration object used by PSF.

Example #1
You want a spooled file converted to an encrypted PDF, e-mailed and written as an encrypted PDF to the integrated file system. You must do the following:

o Specify the stream file distribution option in the PDF map object entry or segment.
o Specify the following on the printer file or spooled file's attributes (CHGSPLFA): USRDFNDTA('PDFENCRYPT(*STMF)').

Example #2
You want a spooled file converted to an encrypted PDF, not e-mailed and spooled as an encrypted PDF. You must do the following:

o Specify the spooled file distribution option in the PDF map object entry or segment.
o Specify the following on the printer file or spooled file's attributes (CHGSPLFA): USRDFNDTA('PDFENCRYPT(*SPLF *NOMAIL)').

Example #3
You want a spooled file converted to an encrypted PDF, not e-mailed, spooled as an encrypted PDF and written as an encrypted PDF to the integrated file system. You must do the following:

o Specify the stream file distribution option in the PDF map object entry or segment.
o Specify the spooled file distribution option in the PDF map object entry or segment.
o Specify the following on the printer file or spooled file's attributes (CHGSPLFA): USRDFNDTA('PDFENCRYPT(*NOMAIL *STMF *SPLF)').

Example #4
You want a spooled file converted to an encrypted PDF, not e-mailed, spooled as a PDF without encryption and written as an encrypted PDF to the integrated file system. You must do the following:

o Specify the stream file distribution option in the PDF map object entry or segment.
o Specify the spooled file distribution option in the PDF map object entry or segment.
o Specify the following on the printer file or spooled file's attributes (CHGSPLFA): USRDFNDTA('PDFENCRYPT(*STMF *NOMAIL)').

---

Using a customized PDF user program

Two fields have been added to the Extension Area Format: Encrypt PDF stream file and Encrypt PDF spooled file. These fields allow you to specify whether PDF stream files or PDF spooled files should be encrypted. In either case, you must specify encryption settings as if you were going to e-mail the PDF. If you don't wish to e-mail the PDF, you can use the existing field Disposition of PDF e-mail in the Mapping Program Output Information Structure to control whether the e-mail is sent.

Note that passwords returned by a PDF user program must always be in clear text. If PSF dumps the PDF user program interface because of an error in values specified by a PDF user program, the PDF master and user passwords, if specified, are output as binary zeroes in the dump. The actual passwords passed to PSF are not modified.

Shown below are the changes to the Extension Area Format as documented on page 185 of Infoprint Server for iSeries User's Guide Version 5, Release 4.0. The header files containing the Extension Area Format are updated with APAR SE38183. The PDFENCRYPT parameter is ignored when a customized PDF user program is specified.

Extension Area Format

Decimal Offset	Hex Offset	Field Name	Type	Description
0	0	EXTLEN	BINARY(4)	Length of extension area format
4	4	SUBOFF	BINARY(4)	Offset to subject
8	8	SUBLEN	BINARY(4)	Length of subject
12	C	RPLYOFF	BINARY(4)	Offset to ReplyTo e-mail address
16	10	RPLYLEN	BINARY(4)	Length of ReplyTo e-mail address)
20	14	CCOFF	BINARY(4)	Offset to CC e-mail addresses
24	18	CCLEN	BINARY(4)	Length of CC e-mail addresses
28	1C	BCCOFF	BINARY(4)	Offset to BCC e-mail addressesa
32	20	BCCLEN	BINARY(4)	Length of BCC e-mail addresses
36	24	BDYPTHOFF	BINARY(4)	Offset to list of path names for body of e-mail
40	28	DIRPTHOFF	BINARY(4)	Offset to path name for directory for files
44	2C	DIRPTHLEN	BINARY(4)	Length of path name for directory for files
48	30	ATTPTHOFF	BINARY(4)	Offset to list of path names of attachments
52	34	STMFNAMOFF	BINARY(4)	Offset to PDF file name for storing as a file
56	38	STMFNAMLEN	BINARY(4)	Length of PDF file name for storing as a file
60	3C	EATTNAMOFF	BINARY(4)	Offset to file name for PDF attachment for e-mail
64	40	EATTNAMLEN	BINARY(4)	Length of file name for PDF attachment for e-mail
68	44	PUBAUTOFF	BINARY(4)	Offset to PDF file public authority
72	48	PUBAUTLEN	BINARY(4)	Length of PDF file public authority
76	4C	PDFSPLOFF	BINARY(4)	Offset to spooled file PDF distribution
80	50	PDFSPLLEN	BINARY(4)	Length of spooled file PDF distribution
84	54	AFPSPLOFF	BINARY(4)	Offset to spooled file AFP distribution
88	58	AFPSPLLEN	BINARY(4)	Length of spooled file AFP distribution
92	5C	ENCRPTOFF	BINARY(4)	Offset to PDF encryption information
96	60	ENCRPTLEN	BINARY(4)	Length of PDF encryption information
100	64	PDFSENDER	CHAR(10)	Mail sender
110	6E	ENCRPTSTMF	CHAR(1)	Encrypt PDF stream file ** new **
111	6F	ENCRPTSPLF	CHAR(1)	Encrypt PDF spooled file ** new **

Note: The Length of extension area format field will typically be set to 110 if using the Mail sender field, or to 112 if using the Encrypt PDF stream file or Encrypt PDF spooled file fields.

New Field Descriptions

Encrypt PDF stream file. Use the e-mail encryption setting for a PDF stream file.

Valid values are as follows:

'0' (X'F0')	Do not encrypt the PDF stream file.
'1' (X'F1')	Encrypt the PDF stream file.

Encrypt PDF spooled file. Use the e-mail encryption setting for a PDF spooled file.

Valid values are as follows:

'0' (X'F0')	Do not encrypt the PDF spooled file.
'1' (X'F1')	Encrypt the PDF spooled file.

Function added with APAR SE32012

APAR SE32012 and its corequisites add PSF for i5/OS support for the use of an apostrophe in the local name of an e-mail address when a PDF map program or a PDF map object is being used. This support is added for SMTP only; PSF does not support the use of an apostrophe in a local name when PDFMAILSVR(*SNDDST) is specified in a PSF configuration object. Prior to the PTFs associated with these APARs, an apostrophe could be used only in the situations described below.

o USRDFNDTA spooled file attribute specified on screen. Enter two apostrophes for each apostrophe in the local name. For example, SydneyO'Malley@abl.gov.uk would be entered as SydneyO''Malley@abl.gov.uk.
o USRDFNDTA printer file attribute specified programmatically using API QSPCRTSP. Applications must specify a single apostrophe in the local name.
o Convert to PDF in System i Navigator. In the Address field, specify a single apostrophe in the local name.

With the new support, apostrophes in the local name may also be specified in the situations listed below.

o PDF map object. Always use a single apostrophe in both of the following situations:
-- Listing e-mail addresses on the command interface.
-- Listing e-mail addresses stored in a stream file.
o PSF user program. Use a single apostrophe in the e-mail addresses, and use commas to separate e-mail addresses. In order to use this new method you must use new field PDF Email Comma Delimiter in the Mapping Program Output Information Structure, which is documented below.

Mapping Program Input Information Structure

Documented below is a modified version of the Mapping Program Output Information Structure from the Infoprint Server for iSeries User's Guide Version 5, Release 4.0.

Mapping Program Input Information Structure

Decimal Offset	Hex Offset	Field Name	Type	Description
0	0	JOBNAM	CHAR(26)	Qualified job name
26	1A	SPLFID	CHAR(10)	Spooled file name
36	24	SPLNO	BINARY(4)	Spooled file number
40	28	MAILTAG	CHAR(250)	Routing tag
290	122	PDFFILE	CHAR(340)	Path and name of PDF file
630	276	SVRTYPE	CHAR(1)	Mail server type
631	277	RES1	CHAR(1)	Reserved
632	278	PATHCCSID	BINARY(4)	Path and name CCSID
636	272	SENDER	CHAR(10)	Mail sender
646	286	USRDTA	CHAR(10)	User data (USRDTA)
656	290	SYSNAME	CHAR(8)	Job system name
664	298	TIMESTMP	CHAR(8)	Creation time stamp
672	2A0	OUTQ	CHAR(10)	Output queue on which the spooled file is located
682	2AA	OUTQLIB	CHAR(10)	Output queue library
692	2B4	MAPOBJ	CHAR(10)	PDF map object name
702	2BE	MAPOLIB	CHAR(10)	PDF map object library
712	2C8	FORMTYPE	CHAR(10)	Formtype

Mapping Program Output Information Structure

Documented below is a change to the Mapping Program Output Information Structure as documented on page 182 of Infoprint Server for iSeries User's Guide Version 5, Release 4.0. The CHAR(1) reserved field at decimal offset 267 has been replaced with a CHAR(1) field called PDF Email Comma Delimiter.

Mapping Program Output Information Structure

Decimal Offset	Hex Offset	Field Name	Type	Description
0	0	MAILDISP	CHAR(1)	Disposition of PDF e-mail
1	1	CALLAGIN	CHAR(1)	More processing
2	2	RES2	CHAR(2)	Reserved (set each byte to X'00')
4	4	MSGLEN	BINARY(4)	Length of message text (0 - 255 bytes)
8	8	ADRRLEN	BINARY(4)	Length of mail address (0 - 16,000,000)
12	C	MSGTEXT	CHAR(255)	Message text
267	10B	RES3	CHAR(1)	PDF E-mail Comma Delimiter
268	10C	EXTOFF	BINARY(4)	Offset to extension area
272	110	CCSID	BINARY(4)	CCSID of message text and subject
276	114	STMFDISP	CHAR(1)	Disposition of PDF Stream file
277	115	SPLFDISP	CHAR(1)	Disposition of PDF Spooled file
278	116	PDFERRDISP	CHAR(1)	Disposition of PDF Error
279	117	AFPSPLFDISP	CHAR(1)	Disposition of AFPDS Spooled file
280	118	ERR	BINARY(4)	Offset to message text data
284	11C	RES4	CHAR(3)	Reserved (set each byte to X'00')
287	11F	ADDRESS	CHAR(*)	E-mail address

PDF Email Comma Delimiter
Specifies whether all e-mail addresses are separated by the default delimiter (single quotation marks) or a comma. The default delimiter, for example, is used as follows: 'name1@domain1' 'name2@domain2'. The comma delimiter, for example, is used as follows: name1@domain1, name2@domain2.

If your program is using this field, a comma is not required if just a single e-mail address is specified. Using the comma as a delimiter is helpful if your application requires the use of e-mail addresses which have an apostrophe as part of the local name.

Valid values are as follows:

'0' (X'F0')

The default delimiter, an apostrophe, is being used. This field occupies the offset of a field that was reserved in Infoprint Server 5.1. Therefore, X'00' is treated the same as '0' (X'F0') for compatibility.

'1' (X'F1')

A comma is being used as a delimiter. Your application must use a comma as a delimiter when specifying more than one e-mail address for TO, CC and BCC. When specifying a single address, no comma is required. Do not use enclosing single apostrophes for any e-mail address, including ReplyTo. This support is provided for SMTP mail servers only. Use of a comma delimiter is not supported when PDFMAILSVR(*SNDDST) is specified in a PSF configuration object.

Spooled File PDF Encryption Format

Documented below is the Spooled FIle PDF Encryption Format structure as documented on page 195 of Infoprint Server for iSeries User's Guide Version 5, Release 4.0.

Use this format to specify security options for the e-amiled PDF output. If you do not want to specify encryption, specify '0' for Offset to PDF encryption information.

Spooled File PDF Encryption Format

Decimal Offset	Hex Offset	Field Name (Example)	Type	Description
0	0	PDFMSTRPW	CHAR(32)	PDF master password
32	20	PDFUSERPW	CHAR(32)	PDF user password
64	40	PDFPRINT	CHAR(1)	PDF print
65	41	PDFDOCCHG	CHAR(1)	PDF document change
66	42	PDFCOPY	CHAR(1)	PDF copy
67	43	PDFENCLVL	CHAR(1)	PDF encryption level
68	44	PDFCNTACC	CHAR(1)	PDF content access enablement
69	45	PDFCHGCMT	CHAR(1)	PDF change comments
70	46	PDFDOCASB	CHAR(1)	PDF document assembly

PDF master password
Specify the PDF master password required to change the security settings for the PDF file. When password-protected, the PDF file can be opened with either the user password or master password.

If you set any security restrictions in the file, you should specify a master password. Otherwise, anyone who opens the file could remove the restrictions. If you specify a master password and specify *NONE for the user password, users can view the PDF file but cannot change the security settings. If you specify any encryption options, you must specify a user password, a master password, or both.

Valid values are as follows:

X'00'	There is no PDF master password on this document.
password	A string of 32 alphanumeric characters. Only use these characters: ‘A’-‘Z’, ‘a’-‘z’, ‘0’-‘9’. If your password is not 32 characters long, you must pad the password with X'00' or X'40' (not both) to make the 32 character length.

PDF user password
Specify the password required for the user to open the PDF file. When password-protected, the PDF file can be opened with either the user password or master password.

If you set any security restrictions in the file, you should specify a master password. Otherwise, anyone who opens the file can change the restrictions. If you specify any encryption options, you must specify a user password, a master password, or both.

Valid values are as follows:

X'00'	There is no user password on this document.
password	A string of 32 alphanumeric characters. Only use these characters: ‘A’-‘Z’, ‘a’-‘z’, ‘0’-‘9’. If your password is not 32 characters long, you must pad the password with X'00' or X'40' (not both) to make the 32 character length.

PDF print
Specify the PDF viewer’s security settings for printing the PDF document.

Valid values are as follows:

'0' (X'F0')	Printing is not allowed.
'1' (X'F1')	Printing is allowed.
'2' (X'F2')	Only low resolution printing is allowed. You can only specify this value if you also specify 128-bit encryption.

Important: The information on the PDF Print variable was incorrect prior to 7 February, 2014. This correct information comes from the PSF/400 Mapping Exit Program topic in the IBM i 7.1 Information Center, which is available at:

http://pic.dhe.ibm.com/infocenter/iseries/v7r1m0/index.jsp?topic=%2Fapis%2Fxpsf400email.htm

PDF document change
Specify the PDF viewer’s security settings for changing the PDF document.

Valid values are as follows:

'0' (X'F0')	Change is not allowed. Users cannot create form fields or make any other changes. You cannot specify PDF document assembly = ‘1’ (yes) if you specify that change is not allowed.
'1' (X'F1')	The user can change the document.

PDF copy
Specify the PDF viewer’s security settings for copying from the PDF document. Content access is disabled if you specify both of these:

PDF copy = ‘0’ (Copy is not allowed)
PDF encryption level = ‘1’ (40-bit)

Valid values are as follows:

'0' (X'F0')	Copy is not allowed.
'1' (X'F1')	Copy is allowed.

PDF encryption level
Specify the encryption level the PDF document using the PDF viewer’s encryption settings. If you do not want the file encrypted, specify ‘0’ for offset to encryption information.

Valid values are as follows:

'1' (X'F1')	40-bit encryption (Adobe Acrobat 3.X and 4.X) Content access is always disabled if you specify both of these: PDF encryption level = ‘1’ (40-bit) PDF copy = ‘0’ (Copy is not allowed)
'2' (X'F2')	128-bit encryption (Adobe Acrobat 5.0)

PDF content access enablement
Specify the PDF viewer’s encryption settings for content access for the visually impaired to the PDF document. This is only configurable with 128-bit encryption. For 40-bit encryption, set this field to ‘0’. Content access is always disabled if you specify both of these:

PDF encryption level = ‘1’ (40-bit)
PDF copy = ‘0’ (Copy is not allowed)

Valid values are as follows:

'0' (X'F0')	Content access is not enabled.
'1' (X'F1')	Content access is enabled.

PDF change comments
Specify whether users have the authority to add or change comments (annotations) or form fields in the PDF document.

Valid values are as follows:

'0' (X'F0')	Users cannot add or change comments or form fields in the PDF file. Users can fill in form fields.
'1' (X'F1')	Users can add or change comments and form fields in the PDF file.

PDF document assembly
Specify the PDF viewer’s security settings for document assembly from the PDF document. This is only configurable with 128-bit encryption. For 40-bit encryption, set this field to ‘0’.

Valid values are as follows:

'0' (X'F0')	Document assembly is not allowed.
'1' (X'F1')	The user is allowed document assembly.

The user can insert, delete, and rotate pages, and create bookmarks and thumbnails. You can only specify this value if you also specify 128-bit encryption and PDF document change = ‘1’ (yes).