PSF/400 Mapping Exit Program

The PSF/400 mapping exit program allows a customer to specify a routing tag instead of a mail address in the USRDFNDTA parameter of the printer file, using indices and Infoprint Server's CRTAFPDTA command, or the DDS STRPAGGRP parameter. The PSF/400 mapping exit program also allows a customer or vendor to provide a program to map a routing tag (such as a customer number) to one or more distribution actions, and configure the details of the distribution. The PDF file can be stored as a streamfile in the Integrated File System, respooled as AFP or PDF on an output queue, e-mailed, or any combination of those distributions. In addition, the mapping exit program allows configuration of those distributions, including the ability to specify the name of the PDF streamfile, the ability to specify the subject, encryption settings and additional attachments of the e-mail, or the output queue to spool the PDF.

This exit program is called for each successfully generated PDF file whenever a mapping exit program is speficied on the PDFMAPPGM parameter of the PSFCFG, and the PDFGEN parameter does not have a value of *NONE. Once PSF/400 has received notification from the virtual printer that all pages have been stacked, it calls the exit program for each PDF output file to resolve the routing tag information to the proper distribution action.

Authorities and Locks

None.

Required Parameter Group

Mapping exit input information

INPUT; CHAR(*)

The mapping exit program information that is input to the mapping exit program from the PSF/400 print writer. For the format and description of the information see, Mapping Exit Program Input Information.

Length of input information

INPUT; BINARY(4)

The length of the input information specified in the mapping exit input information to the mapping exit program parameter.

Mapping exit output information

OUTPUT; CHAR(*)

The information that is output from the mapping exit program to the PSF/400 print writer. For the format and description of this information, see mapping Exit Program Output Information.

Length of output information buffer

INPUT; BINARY(4)

The size, in bytes, of the mapping exit program output information buffer.

Length of output information available

OUTPUT; BINARY(4)

The length of the mapping exit program output information available. If this length is less than or equal to the length of the routing tag output information, all available information has been returned. If this length is greater than the length of the mapping program output information, only data up to the length provided is returned in the mapping exit program output information buffer.

Mapping Exit Program Input Information

The following table shows the structure for the input information that is passed to the PSF/400 Mapping exit program.

Printer File Parameter Table

Field Descriptions

Creation time stamp. The date and time the spooled file was created.

Formtype. The value from the Formtype parameter on the print file.

Job system name. The name of the system on which the spooled file was created.

Mail sender. The sender of the electronic mail. The value is specified on the printer file USRDFNDTA parameter or on the PSF configuration object PDFSENDER parameter. If no mail sender is identified on USRDFNDTA, the value from the PDFSENDER parameter of the PSF configuration object is used.

Mail server type. The mail server in use. Valid values are:

Routing tag. The mail address or routing tag specified on the printer file USRDFNDTA parameter or the DDS STRPAGGRP keyword. This is set to blanks ('40'X) if no value was provided by either parameter. It is possible that the mapping program could return mail addresses based on job, file, and USRDTA information. If both provide tag or address information, the DDS STRPAGGRP keyword takes precedence.

Output queue on which the spooled file is located. The outpue queue to which the writer was started.

Output queue library. The library that contains the output queue to which writer was started.

Path and name of PDF file. The path and name of the PDF file.

Path name CCSID. The CCSID of the path and name of the PDF file.

PDF mapping object library. Name of the PDF mapping object library, if one was specified on the PSFCFG object. This is set to blanks (X'40') if no value was provided on the PDFMAPBOBJ parameter of the PSFCFG object.

PDF mapping object name. Name of the PDF mapping object, if one was specified on the PSFCFG object. This is set to blanks (X'40') if no value was provided on the PDFMAPBOBJ parameter of the PSFCFG object.

Qualified job name. The qualified job name of the job that created the spool file that was converted to PDF. The data is comprised of the following information:

Reserved. An unused field.

Spooled file name. The name of the spooled file that was converted to PDF.

Spooled file number. The unique number of the spooled file that was converted to PDF.

User data. The value in the printer file USRDTA parameter. It contains blanks if USRDTA contains blanks.

Mapping Exit Program Output Information

The following table shows the structure for the output information from the Mapping exit program.

Offset		Type	Field
Dec	Hex
0	0	CHAR(1)	Disposition of PDF e-mail
1	1	CHAR(1)	More processing
2	2	CHAR(2)	Reserved - initialized to null
4	4	BINARY(4)	Length of message text (0 to 255 bytes)
8	8	BINARY(4)	Length of mail address data (0-16,000,000)
12	C	CHAR(255)	Message text data
267	10B	CHAR(1)	Reserved - initialized to null
268	10C	BINARY(4)	Offset to extension area
272	110	BINARY(4)	CCSID of message text data and subject
276	114	CHAR(1)	Disposition of PDF streamfile
277	115	CHAR(1)	Disposition of PDF spoolfile
278	116	CHAR(1)	Disposition of PDF error
279	117	CHAR(1)	Disposition of AFPDS spoolfile
280	118	BINARY(4)	Offset to message text data
284	122	CHAR(3)	Reserved - initialized to null
287	11F	CHAR(*)	E-mail addresses

Field Descriptions

CCSID of message text data and subject. The CCSID associated with the message text data and subject, if specified.

This field is used only when an SMTP mail server is specified in your PSF configuration object and must be set to zero otherwise.

This CCSID will be used to convert the data to Unicode for inclusion within the e-mail. The receiver of the e-mail may have to have the receiving e-mail program configured for the appropriate character set to be able to view the e-mail correctly.

Disposition of AFPDS spoolfile. Specifies whether the PDF should be spooled. If file is to be spooled as AFPDS, an output queue has to be defined on the PSFCFG or in the Spooled file AFPDS Distribution in the Output Queue Name field

Disposition of PDF e-mail. Specifies whether the PDF should be e-mailed.

Disposition of PDF error. This field can be used to signal to PSF/400 that an error was detected in the Exit Program. If this flag is set, PSF/400 will e-mail the PDF output to the e-mail address on the PSFCFG PDFADMIN, if one is available.

Disposition of PDF spoolfile. Specifies whether the PDF should be spooled. If file is to be spooled as PDF, an output queue has to be defined on the PSFCFG or in the Spooled file PDF Distribution in the Output Queue Name field

Disposition of PDF streamfile. Specifies whether the PDF should be stored as a stream file in the Integrated File System. If file is to be stored as a stream file, user will have to have the path name defined in the PSFCFG or specified in the PDF file name field of the Extension area format.

E-mail addresses. The e-mail addresses that should be used for sending the PDF file. They must be in the following format: ('e-mail address' 'e-mail address'..) Each address must be delimited by single quotes.

Length of e-mail address data. The length of the e-mail address data to be used in sending the PDF file. The maximum length allowed is 16 MB, since this is the largest value that can be used allocate a user space. If the PDF file should not be e-mailed, the length of the e-mail address data should be set to 0.

Length of message text data. The length of the message text to be used in sending the PDF file. This must be a value ranging from 0 to 255. If no message text is to be used in sending the PDF file, the length of the message text data should be set to 0.

Message text data. The message text data to be used in sending the PDF file. This value should be blanks if the text length is 0.

More processing. Whether the exit program should be called again because it has more processing to do for the same spooled file.

'0'(X'F0')

Do not call exit program again. Since this field occupies the offset of a field that was reserved in V5R1, a value of X'00' will be treated the same as 0 (X'F0') for compatability.

'1'(X'F1')

Call exit program again. The input information presented to the exit program is not modified. If at any point an error occurs while processing an e-mail:

• The exit program is not called again, irrespective of the setting for this field.
• The spooled file is held.

Offset to extension area. Offset from the beginning of this structure. The value specified for this entry must be a 4-byte multiple. A value of 0 indicates that the extension area is not being used. Refer to Extension area format for additional information.

Offset to message text data. Offset from the beginning of this structure. The value must be a 4-byte multiple Use this field if you specify more than 255 bytes of message text data. If you are using the Message text data field, specify a value of 0 for Offset to message text data.

Reserved - initialized to null. A reserved field.

Reserved (set to X'00'). A reserved field.

Extension area format

This format is specified only when needed. If your application has no need for it, specify a value of 0 for Offset to extension area in the e-mail exit program output information.

This format must begin on a 4-byte multiple. All offsets are computed from the beginning of the mapping exit program output information structure.

Field Descriptions

Length of BCC e-mail addresses. The length of the BCC e-mail address data to be used in sending the PDF file. This field is used only when an SMTP mail server is specified in your PSF configuration object; otherwise, it must be set to zero.

Length of CC e-mail addresses. The length of the CC e-mail address data to be used in sending the PDF file. This field is used only when an SMTP mail server is specified in your PSF configuration object; otherwise, it must be set to zero.

Length of file name for PDF attachment for e-mail Length of the file name used to rename the PDF attachment for e-mail distribution. This field is only used when Disposition for PDF e-mail is set to '1'; otherwise, it must be set to zero.

Length of extension area format. The length of the extension area format. Specify one of the following values:

Length of path name for directory for files. The length of the path name containing the directory for which files may be stored. This field is used only when an SMTP mail server is specified in your PSF configuration object; otherwise, it must be set to zero.

Length of PDF encryption information . The length of the PDF file encryption information. This field is used only when PDF encryption information is specified; otherwise, it must be set to zero.

Length of PDF file name for storing as a streamfile. The length of the PDF file name used when Disposition of PDF streamfile is set to 1. This field is used only when Disposition of PDF streamfile is set to '1'; otherwise, it must be set to zero.

Length of PDF file public authority The length of public authority to the PDF file. This field is used only when the PDF file is to be stored as a stream file and the PDF Streamfile Disposition is equal to '1'; otherwise, it must be set to zero.

Length of spooled file AFP distribution The length of the AFP spooled file distribution information. This field is used only when a additional spooled file information is specified; otherwise, it must be set to zero.

Length of spooled file PDF distribution The length of the PDF spooled file distribution information. This field is used only when additional spooled file information is specified; otherwise, it must be set to zero.

Length of ReplyTo e-mail address. The length of the ReplyTo e-mail address. This field is used only when an SMTP mail server is specified in your PSF configuration object; otherwise, it must be set to zero.

Length of subject The length of the character string to be used as the subject text. Maximum length is 255. Data longer than the maximum length will be truncated.

Offset to BCC e-mail addresses. Offset to BCC e-mail addresses. This area contains the BCC e-mail addresses that should be used for sending the PDF file. These addresses must be in the following form: ('e-mail address' 'e-mail address'...). Each e-mail address must be delimited by single quotes.

A value of 0 indicates that BCC e-mail addresses are not specified. This field is used only when an SMTP mail server is specified in your PSF configuration object; otherwise, it must be set to zero.

Mail sender. The name to be used for the sender of the electronic mail. Pad the field with blanks ('40'X), if necessary.

Offset to CC e-mail addresses. Offset to BCC e-mail addresses. This area contains the CC e-mail addresses that should be used for sending the PDF file. These addresses must be in the following form: ('e-mail address' 'e-mail address'...). Each e-mail address must be delimited by single quotes.

A value of 0 indicates that CC e-mail addresses are not specified. This field is used only when an SMTP mail server is specified in your PSF configuration object; otherwise, it must be set to zero.

Offset to file name for PDF attachment for e-mail The offset to the file name that will be used for the PDF output that is attached to the e-mail when Disposition of PDF e-mail is sequal to '1'. If Disposition of PDF e-mail is set to one, and this field is set to '0', PSF will determine a default file name to use. If Disposition of PDF e-mail is set to 0, this field must be set to zero as well.

Offset to list of path names of attachments. The offset to the list of path names listing the attachments. One or more attachments may be specified. The PDF file you are sending must not be listed here; otherwise, it will be attached again. A value of 0 indicates that no attachments are specified.

If you have specified a directory to be used for files (see Offset to path name for directory for files), then the path name specified for this field will be appended to the value specified for the directory. If you have not specified a directory to be used for files, the path name specified for each attachment must be fully resolved. These files must be in the Integrated File System. Please note the following:

• PSF can only access file systems that are threadsafe; therefore, you must specify a file system that is threadsafe. The following files systems are not threadsafe:
  
  
  • QNetware
  • QFileSvr.400
  • Network File System (NFS)
  • QDLS
  
  
• All files must be encoded in a CCSID that matches the CCSID/CodePage of the target system.

Refer to Stream file format for information on the format to use when specifying this information. This field is used only when an SMTP mail server is specified in your PSF configuration object; otherwise, it must be set to zero.

Offset to list of path names for body of e-mail. Offset to list of path names listing the files to be used for the body of the e-mail. One or more files may be specified. The PDF file you are sending must not be listed here or it will be attached again. A value of 0 indicates that a stream file is not specified.

The order in which you list these files determines the order in which they are placed in the body (message portion) of the e-mail. Files are placed in the body in the order in which they are specified. If you have specified Message text data, this is placed in the body of the e-mail first. These files must be in the Integrated File System. Please note the following:

• PSF can only access file systems that are threadsafe; therefore, you must specify a file system that is threadsafe. The following files systems are not threadsafe:
  
  
  • QNetware
  • QFileSvr.400
  • Network File System (NFS)
  • QDLS
• All files must be encoded in a CCSID that matches the CCSID/CodePage of the target system.

Refer to Stream file format for information on the format to use when specifying this information.

The CCSID of the file is used if a code page conversion is required.

If a file is not text, it will be placed as an attachment to the e-mail. For example, if you specify a sound file to be part of the body of the e-mail, it will actually be an attachment.

This field is used only when an SMTP mail server is specified in your PSF configuration object; otherwise, it must be set to zero.

Offset to path name for directory for files The offset to a path name containing the directory for which files may be stored. This path name must be fully resolved. If you use this field, then path names of specified attachments and body files will be appended to the path name specified at the offset for this field.

A value of 0 indicates that a path name is not specified. If a value of 0 is specified, you must specify the complete path name for all listed files used for the body of the e-mail and as attachments to the e-mail.

This directory is specified by using a value of 1 in the use-specified directory field in the Base format. This format is used when specifying files to be used as attachments or as part of the body of the e-mail. If you specify 0 for the Use specified directory field, then that particular file must have its full path specified.

This field is used only when an SMTP mail server is specified in your PSF configuration object; otherwise, it must be set to zero.

Offset PDF encryption information. The offset to the PDF file encryption information. Refer to PDF spool file distribution format for information on the format to use when specifying this information. A value of 0 indicates that no encryption information is specified.

Offset to PDF file name for storing as a file. The offset to the file name the PDF will be stored as in the Integrated File System. Requires that the Disposition of PDF streamfile be set to 1. If Disposition of PDF streamfile is set to 1, a value of 0 in this field indicates that PSF/400 will determine a default file name to be used.

Offset to PDF file public authority. The offset to the public authorities specified for the PDF stream file.

Valid Authority Values

*ALL

PSF specifies *RWX for the Public data authority and *ALL for the Public object authorities

*EXCLUDE

The users do not have any of the data authorities to the objects.

*RWX

The users are given *RWX authority to perform all operations on the object except those limited to the owner or controlled by object existence, object management, object alter, and object reference authority. The user can change the object and perform basic functions on the object. *RWX authority provides object operational authority and all the data authorities.

*RX

The users are given *RX authority to perform basic operations on the object, such as run a program or display the contents of a file. The user is prevented from changing the object. *RX authority provides object operational authority and read and execute authorities.

*RW

The users are given *RW authority to view the contents of an object and change the contents of an object. *RW authority provides object operational authority and data read, add, update, and delete authorities.

*WX

The users are given *WX authority to change the contents of an object and run a program or search a library or directory. *WX authority provides object operational authority and data add, update, delete, and execute authorities.

*R

The users are given *R authority to view the contents of an object. *R authority provides object operational authority and data read authority.

*W

The users are given *W authority to change the contents of an object. *W authority provides object operational authority and data add, update, and delete authorities.

*X

The users are given *X authority to run a program or search a library or directory. *X authority provides object operational authority and data execute authority.

Offset to spooled file AFP distribution. The offset to the AFP spooled file information. Refer to AFP spool file distribution format for information on the format to use when specifying this information. A value of 0 indicates that no spooled file information is specified.

Offset to spooled file PDF distribution. The offset to the PDF spooled file information. Refer to PDF spool file distribution format for information on the format to use when specifying this information. A value of 0 indicates that no spooled file information is specified.

Offset to ReplyTo e-mail address. Offset to ReplyTo e-mail address. Use this address if you wish to have replies to your e-mail be sent to an e-mail address other than the one specified for the FROM e-mail address.

The address must be in the following form: ('e-mail address').

A value of 0 indicates that ReplyTo e-mail addresses are not specified.

This field is used only when an SMTP mail server is specified in your PSF configuration object and must be set to zero otherwise.

Offset to subject The offset to the character string to be used as the subject text. A value of 0 indicates that a subject is not specified here. If you do not specify a subject, then the default subject is obtained from message PQT4133 in message file QPQMSGF.

If you have specified an SMTP mail server, the CCSID of message text data and subject will be used to convert the data to Unicode for inclusion within the e-mail. The receiver of the e-mail may have to have the receiving e-mail program configured for the appropriate character set to be able to view the e-mail correctly.

Integrated File System Authorizations

Authority to directories in the path where the stream file resides

*X

Public authority to stream files

*R

Stream file format

Use this format only when an SMTP mail server is specified in your PSF configuration object, and you are specifying the use of stream files for either the body of the e-mail or additional attachments.

Field Descriptions

Number of stream files specified. The number of stream files specified within this format.

Stream file information. The initial offset at which information for each stream file is positioned.

Refer to Individual Stream file information format. for information on the format to use when specifying this information. Use one instance of the base format for each stream file. Each instance of this format must be contiguous to the previous one.

Total length for stream file information. The total length for all data used with this structure. This field is included within the length. The value specified for this entry must be a 4-byte multiple.

Individual Stream file information format

Field Descriptions

Length of individual stream file format. The length of the structure used for the individual stream file format. This value must be 20.

Length of path name. The length of the path name that specifies the stream file.

Offset to path name. The offset to the path name that specifies the stream file. The offset is from the beginning of the base format in which this value is specified.

Use-specified directory. Whether the directory specified for stream files used as either attachments or in the body of the e-mail is to be prefixed to the name of the stream file. For example, if you have specified '/SpecialApp/customerOne/' for a directory of files in the extension area format, this value will be prefixed to stream file names when specified using this field. Valid values are:

Total length of individual stream file format. The total contiguous length used with this format, including this field. This value is used to determine the location of the next stream file information format. The value specified for this entry must be a 4-byte multiple.

Spooled file PDF distribution

Use this format when a PDF is to be spooled as a PDF Spoolfile.

Field Descriptions

Formtype The Form type to be used for the PDF spooled file.

Name of output queue to spool PDF. The name of the output queue that the PDF will be spooled on.

The following special values are supported for the library name:

Output queue library The library in which the output queue to spool PDF exists.

Spooled File Name The name used for the new spooled file.

The following special values are supported for the spooled file name:

User Data The user data for the PDF spooled file. The possible values are:

User Defined Data The user defined data for the PDF spooled file. The possible values are:

Spooled file AFPDS distribution

Use this format when a Spoolfile segment is to be spooled as a AFP Spoolfile.

Field Descriptions

Formtype The Form type to be used for the ADPDS spooled file.

Name of output queue to spool AFPDS The name of the output queue that the AFPDS will be spooled on.

The following special values are supported for the library name:

Output queue library The library in which the output queue to spool AFPDS exists.

Spooled File Name The name used for the new spooled file.

The following special values are supported for the spooled file name:

User Data The user data for the AFPDS spooled file. The possible values are:

User Defined Data The user defined data for the AFPDS spooled file. The possible values are:

PDF Encryption Structure

Use this format when a PDF is to be encrypted.

Field Descriptions

PDF Content Access Enablement. Specify the PDF viewer's security settings for content access to the PDF document.(Only configurable with 128-bit encryption.For 40-bit, set to '0'.)

PDF Changing Comments. Specify the PDF viewer's security settings for adding or modifying text annotations in the PDF document.

PDF Copy. Specify the PDF viewer's security settings for copying from the PDF document.

PDF Document Assembly. Specify the PDF viewer's security settings for document assembly from the PDF document.(Only configurable with 128-bit encryption. For 40-bit, set to '0'.)

PDF Document Changing. Specify the PDF viewer's security settings for changing the PDF document.

PDF Encryption Level. Specify the encryption level the PDF document using PDF Viewer security settings.

PDF Master Password. A string of up to 32 alphanumeric letters and/or numbers. Acceptable characters are A-Z, a-z and 0-9. X'00' will indicate that there is no password on this document.

PDF Printing. Specify the PDF viewer's security settings for printing the PDF document

PDF User Password. A string of up to 32 alphanumeric letters and/or numbers. Acceptable characters are A-Z, a-z and 0-9. X'00' will indicate that there is no password on this document.