Add PDF Map Entry (QPQAPME) API

The Add PDF Map Entry (QPQAPME) API inserts an entry into the specified PDF Map object. You can retrieve the current entries by using the Open List of PDF Map Information (QPQOLPM) API.

This API allows you to set up PDF mapping entries for spooled files you want processed after they have been converted to PDF.

There are two types of entries. Segmented and non-segmented. Segmented entries are for spooled files that are divided into multiple PDF files. The division is be based upon the use of the STRPAGGRP DDS keyword and other products such as the AFP Toolbox or the Infoprint Server. For all segmented entries of a spooled file, the input spooled file criteria(format APME0100), all the selection parameters should be the same except the mail tag information. Non-segmented entries are for spooled files that will be converted to one PDF file.

The entry consists of two parts:

• Selection for the input spooled file. You can specify which spooled file attributes should be used to match a spooled file being converted to PDF. This information is used by products , such as Infoprint Server to determine what additional processing needs to be done with the PDF file.

  The selection for the input spooled file includes such spool attributes as output queue name and library, spooled file name, job name,user name, user data, form type, mail tag, and also a sequence number. To allow for the input selection criteria of multiple entries in the PDF map which can match a particular spooled file, the entries are sorted in the order of the sequence number specified. Multiple entries can be a match for a spooled file because generic and *ALL are supported as part of input selection criteria, for example output queue, file, job name, user name, user data, and form type.

• PDF map actions for the spooled file. For each spooled file or segmented entry of a spooled file, you may define one or more map actions and their associated parameters. The supported actions are e-mail, stream file, PDF respool, and AFPDS respool.

For e-mail, you can enter the following additional information:

• Tolist, Copy Control, and Blind Copy Control
• Subject of email
• Body of e-mail
• Attachments (in addition to PDF spool file)
• Reply to address
• Mail sender

For stream file, you can enter the following additional information:

• Full path name where stream file will be stored in Integrated File System
• Authority for PDF stream file

For re-spooling PDF file, you can enter the following additional information:

• Output queue name
• File name
• User data
• User defined data
• Form type

For re-spooling AFPDS file, you can enter the following additional information:

• Output queue name
• File name
• User data
• User defined data
• Form type

When you request to add an entry to a PDF Map object, the request may not be successful in the following situations:

• The entry you requested to add already exists in the PDF Map. For non-segmented entries, the sequence number must be unique. For segmented entries (which all have the same sequence number), the mail tag must be unique.
• The user profile storage limit is exceeded when an entry is added.

Authorities and Locks

Library authority

*EXECUTE

PDF Map object authority

*CHANGE

PDF Map object lock

*EXCL

Required Parameter Group

Returned library name

OUTPUT; CHAR(10)

The name of the library that contains the PDF map object to which the entry was added if it was added successfully. This parameter is not set if the entry was not successfully added. This information helps you identify the specific library used when *LIBL or *CURLIB is specified in the qualified PDF map object name parameter.

Qualified Map object name

INPUT; CHAR(20)

The Map object for which you would like to add information. The qualified object name has two parts. The first 10 characters contain the object name.

The second 10 characters contain the name of the library in which the object is located.

The following special values are allowed:

*CURLIB	The job's current library is used to locate the object. If no library is specified as the current library for the job, the QGPL library is used.
*LIBL	The library list is used to locate the object.

The actual library that is used is returned in the Returned library name parameter.

PDF map entry spooled file attributes

INPUT; CHAR(*)

The PDF map entry spooled file attributes for the entry to be added to the PDF map object. The parameter uniquely identifies the entry in the PDF map object.

Specify which spooled file attributes should be used to match a spooled file being converted to PDF.

Length of PDF map entry spooled file attributes

INPUT; BINARY(4)

The length of the PDF map entry spooled file attributes parameter. This value must be greater than or equal to 4.

Format of PDF map entry spooled file attributes

INPUT; CHAR(8)

The format of the PDF map for the entry to be added to the PDF map object.

The valid format names are:

APME0100

Contains the input selection criteria for the entry. This includes a sequence number for the entry and spooled file information, such as output queue, spooled file name, job name, user name, user data, form type, and mail tag.

PDF mapping action

INPUT; CHAR(*)

The PDF mapping action for the entry to be added to the PDF map object.

See Format for PDF mapping action for details on the data structure.

Length of PDF mapping action

INPUT; BINARY(4)

The length of the PDF mapping action parameter. This value must be greater than or equal to 8.

Format of PDF mapping action

INPUT; CHAR(8)

The format of the PDF mapping action to be added to the PDF map object.

The valid format names are:

PMAP0100

Contains the mapping action for the entry. This can include mail information, PDF stream file information, PDF and AFPDS spooled file information, and a spooled file segmentation indicator.

Add type

INPUT; BINARY(4)

The type of add to be performed.

Valid values are:

1	Insert with replacement This value requests to replace the PDF map portion of the entry if the PDF map entry spooled file attributes is already in the PDF map object. If the entry does not exist, it will be added into the PDF map object.
2	Add without replacement This value requests to add the entry only if the PDF map entry spooled file attributes portion of the entry is not already in PDF map object. If the entry does not exist, it will be added into the PDF map object. If the entry is already in the PDF map object, an error is returned.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

APME0100 Format

For more details about the fields in the following table, see APME0100 Format Field Descriptions.

APME0100 Format Field Descriptions

Form type. The type of forms that should be loaded on the printer before this spooled file is printed. A least one form type or special value must be specified. This field can be used in conjunction with the output queue name, spooled file name, user, user data, and mail tag to select a spooled file to be processed.

The following special values can be used for the form type:

A default of *ALL is assumed if the form type is not specified.

Job name. The name of the job for the spooled file. At least one job name or special value must be specified. This field can be used in conjunction with the output queue name, spooled file name, form type, and mail tag to to select a spooled file to be processed.

The following special value is used for the job name:

A default of *ALL is assumed if the job name is not specified.

Mail tag. Specifies the mail tag for the spooled file. For non-segmented spooled files, the mail tag is specified on the CRTPRTF, CHGPRTF, or OVRPRTF commands using the USRDFNDTA parameter. For segmented spooled files, the mail tag is specified on the STRPAGGRP DDS keyword. This field can be used in conjunction with the output queue name, spooled file name, user, user data, and form type to select a spooled file to be processed.

Here is information on specifying a mail tag:

• Embedded blanks will be used as part of the mail tag.
• Do not use single quotes around the text string, as they will be interpreted as part of the text string.
• Case is preserved.

The following special values can be used for the mail tag:

A default of *ALL is assumed if the mail tag is not specified.

Output queue library name. The name of the library where the output queue resides.

Output queue name. The name of the output queue in which the spooled file is located. At least one output queue or special value must be specified. This field can be used in conjunction with the spooled file name, user, form type, and mail tag to select to select a spooled file to be processed.

The following special value is used for the output queue name:

Reserved - initalized to null. A reserved field.

Sequence number of entry. The user-defined sequence number for an entry in a PDF Map object. To allow for the input selection criteria of multiple entries in the PDF map that can match a particular spooled file, the entries are sorted in the order of the sequence numbers. Multiple entries can be a match for a spooled file because generic and *ALL are supported as part of input selection criteria, for example output queue, file, user name, user data, and form type.

Spooled file name. The name of the spooled file. At least one spooled file name or special value must be specified. This field can be used in conjunction with the output queue name, user, form type, and mail tag to to select a spooled file to be processed.

The following special value is used for the output queue name:

A default of *ALL is assumed if the spooled file name is not specified.

User data. The value of the user data. You must specify user data or a special value. This field can be used in conjunction with the output queue name, spooled file name, user, form type, and mail tag to selectto select a spooled file to be processed.

The following special value is used for the user data:

A default of *ALL is assumed if the user data is not specified.

User name. The name of the user that created the spooled file. At least one user name or special value must be specified. This field can be used in conjunction with the output queue name, spooled file name, form type, and mail tag to to select a spooled file to be processed.

The following special value is used for the output queue name:

A default of *ALL is assumed if the user name is not specified.

PMAP0100 Format

For more details about the fields in the following table, see PMAP0100 Field Descriptions.

PMAP0100 Field Descriptions

Length of AFPDS spooled file information. The size, in bytes, of the AFPDS Spooled file information entry. For information on the format of a Spooled file information entry, see AFPDS Spooled File Information Entry.

Length of mail information entry. The size, in bytes, of the mail information entry. For information on the format of a mail information entry, see Mail information Entry.

Length of PDF spooled file information. The size, in bytes, of the PDF spooled file information entry. For information on the format of a spooled file information entry, see PDF Spooled File Information Entry.

Length of PDF stream file information. The size, in bytes, of the PDF stream file information entry. This identifies the path where PSF/400 has written the PDF stream file. For information on the format of a stream file entry, see PDF Stream File Information Entry.

Offset to AFPDS spooled file information. The offset, in bytes, from the beginning of the PMAP0100 format structure, to an AFPDS Spooled File Information entry. If this value is 0, an AFPDS Spooled File Information entry is not specified.

Offset to mail information entry. The offset, in bytes, from the beginning of the PMAP0100 format, to a Mail information entry.

Offset to PDF spooled file information. The offset, in bytes, from the beginning of the PMAP0100 format, to a Spooled File Information entry.

Offset to PDF stream file information. The offset, in bytes, from the beginning of the PMAP0100 format, to a PDF Stream File Information entry.

Reserved - initalized to null. A reserved field.

Segmented entry. Indicates whether an entry is a segment. Segmented entries are for AFPDS spooled file that is divided into multiple PDF files. The division would be based upon the use of the STRPAGGRP DDS keyword, the Toolbox APIs, or sucs products as as Infoprint Server.

The following values are used:

If the segmented entry indicator is not specified, then 0 is assumed (entry is not segmented).

Text description. A brief description of the PDF Map entry.

Mail Information Entry

Information in this table should be filled in when e-mail is being requested for a PDF map. If e-mail is not being requested, the length of mail information and offset to mail information fields above should be set to 0. For more details about the fields in the following table, see Mail Information Entry Field Descriptions.

Mail Information Entry Field Descriptions

CCSID of message text and subject. The CCSID associated with the message text 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.

Change Comments in PDF file. This field is applicable only for an Encryption Level of *40RC4. Specifies whether users are allowed to add or change comments (annotations) or form fields in the PDF file.

The following special values are used:

Change PDF file. This field is applicable for Encryption levels *40RC4 and *128RC4. The definition is different for the type of Encryption level.

For an Encryption level of *40RC4, Change PDF file specifies whether users are allowed to change the document, or to prevent them from creating form fields, as well as making any other changes.

When the Encryption level is *40RC4, the following special values are used:

For an Encryption level of *128RCR, Change PDF file specifies the types of changes which are allowed for the PDF file.

When the Encryption level is *128RCR, the following special values are used:

Content Access to PDF file. Specifies whether content accessibility for the visually impaired is enabled for the PDF file.

This field is applicable only for an Encryption Level of *128RCR.

When the Encryption level is *128RCR, the following special values are used:

Copy PDF file. Specifies whether users are allowed to copy or extract text and graphics. Also specifies whether the accessibility interface is disabled.

This field is applicable for Encryption levels *40RC4 and *128RCR.

The following special values are used for Copy PDF file:

Encryption level. The encryption level for the PDF file.

The following special values are used for the encryption level:

Length of attachment e-mail entry. The size, in bytes, of each entry used for naming an e-mail attachment. Use one entry for each stream file. The entries must be concatenated, as in an array. For information on the format of a stream file entry, see Stream File Entry.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

Length of BCC e-mail address entry. The size, in bytes, of each E-mail Address entry used for the BCC of an e-mail. For information on the format of an e-mail addresses entry, see E-mail Address Entry.

Use stream file for BCC e-mail address entries should be set to 0.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

Length of BCC e-mail stream file. The size, in bytes, of the Stream File entry which lists the BCCs used for an e-mail. For information on the format of an e-mail addresses entry, see Stream File Entry.

Use stream file for BCC e-mail address entries should be set to 1.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

Length of Body of e-mail entry. The size, in bytes, of each entry used for naming a stream file placed into the body of the e-mail. Use one entry for each stream file. The entries must be concatenated, as in an array. For information on the format of a stream file entry, see Stream File Entry.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

Length of CC e-mail address entry. The size, in bytes, of each E-mail Address entry used for the CC of an e-mail. For information on the format of an e-mail addresses entry, see E-mail Address Entry.

Use stream file for CC e-mail address entries should be set to 0.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

Length of CC e-mail stream file. The size, in bytes, of the Stream File entry containing the stream file which lists the CCs used for an e-mail. For information on the format of a stream file entry, see Stream File Entry.

Use stream file for CC e-mail address entries should be set to 1.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

Length of message text. The size, in bytes, of the message text that getsplaced into the body of the e-mail.

The following special values can be used for the message text:

If the length of the message text is 0, then the default message text is obtained from message PQT4133 in message file QPQMSGF.

Length of PDF file for e-mail The size, in bytes, of a File Name Entry. This identifies the name to be used for the PDF file produced from a spooled file, that is attached to an e-mail. For information on the format of a file name entry, see File Name Entry.

Length of ReplyTo to e-mail address. The size, in bytes, of an E-mail Address entry used for the ReplyTo of an e-mail. For information on the format of an e-mail addresses entry, see E-mail Address Entry.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

The following special values can be used for the ReplyTo e-mail address:

Length of subject. The size, in bytes, of the text that is used for the subject of the e-mail.

The following special values can be used for the subject:

If the length of the subject is 0, then the default subject is obtained from message PQT4133 in message file QPQMSGF.

Length of TO e-mail address entry. The size, in bytes, of each E-mail Address entry used for the TO of an e-mail. For information on the format of an e-mail addresses entry, see E-mail Address Entry.

Use stream file for TO e-mail address entries should be set to 0.

The following special values can be used for the TO e-mail address entry:

Length of TO e-mail stream file. The size, in bytes, of the Stream File entry containing the stream file which lists the TOs used for an e-mail. If the stream file name is surrounded by quotes, use all characters within the quotes as the stream file name. For information on the format of an e-mail addresses entry, see Stream File Entry.

Use stream file for TO e-mail address entries should be set to X'F1'.

Mail Sender. The user profile from whom the e-mail is being sent.

The following special values can be used for the mail sender:

Number of attachment e-mail entries. The number of stream files to be attached to the e-mail. This value does not include the spooled file converted to PDF.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

Number of BCC e-mail address entries. The number of BCC e-mail addresses to be used for sending an e-mail.

Use stream file for BCC e-mail address entries should be set to 0.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

Number of Body of e-mail entries. The number of stream files to be placed into the body of the e-mail.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

Number of CC e-mail address entries. The number of CC e-mail addresses to be used for sending an e-mail.

Use stream file for CC e-mail address entries should be set to 0.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

Number of TO e-mail address entries. The number of TO e-mail addresses to be used for sending an e-mail.

Use stream file for TO e-mail address entries should be set to 0.

This field is used only when an SMTP mail server is specified in your PSF configuration object.

Offset to attachment e-mail entries. The offset, in bytes, from the beginning of the PMAP0100 format structure, to a list of attachment entries.

Offset to BCC e-mail address entries. The offset, in bytes, from the beginning of the PMAP0100 format structure, to a list of BCC e-mail address entries. This area contains the BCC e-mail addresses to which the PDF file is sent.

If Use stream file for BCC e-mail address entries is set to X'F1', then this value will be 0.

Offset to BCC e-mail stream file. The offset, in bytes, from the beginning of the PMAP0100 format structure, to a file name which contains a list of BCC e-mail address entries.

If Use stream file for BCC e-mail address entries is set to 0, then this value will be 0.

Offset to Body of e-mail entries. The offset, in bytes, from the beginning of the PMAP0100 format structure, to a list of Stream file entries.

Offset to CC e-mail address entries. The offset, in bytes, from the beginning of the PMAP0100 format structure, to a list of CC e-mail address entries. This area contains the CC e-mail addresses to which the PDF file is sent.

If Use stream file for CC e-mail address entries is set to 1, then this value will be 0.

Offset to CC e-mail stream file. The offset, in bytes, from the beginning of the PMAP0100 format structure, to a file name which contains a list of CC e-mail address entries.

If Use stream file for CC e-mail address entries is set to 0, then this value will be 0.

Offset to message text. The offset, in bytes, from the beginning of the PMAP0100 format, to the message text which gets placed in to the body of the e-mail.

Offset to subject. The offset, in bytes, to the subject of the e-mail. If this value is 0, a subject is not specified.

Offset to PDF file for e-mail The offset, in bytes, from the beginning of the PMAP0100 format, to the PDF File For E-mail Entry.

Offset to ReplyTo e-mail address. The offset, in bytes, from the beginning of the PMAP0100 format, to the E-mail ddress Entry for a ReplyTo e-mail address. If this value is 0, a ReplyTo e-mail address is not specified.

Offset to TO e-mail address entries. The offset, in bytes, from the beginning of the PMAP0100 format, to to a list of TO e-mail address entries. This area contains the TO e-mail addresses to which the PDF file is sent.

Offset to TO e-mail stream file. The offset, in bytes, from the beginning of the PMAP0100 format, to a file name which contains a list of TO e-mail address entries.

If Use stream file for TO e-mail address entries is set to 0, then this value will be 0.

Owner password. The owner password associated with the PDF file to be created.

This field is applicable for Encryption levels *40RC4 and *128RC4.

The following can be used for the owner password:

Print PDF file. This field is applicable for Encryption levels *40RC4 and *128RCR. The definition is different for the type of Encryption level.

For an Encryption level of *40RC4, Print PDF file specifies whether users are allowed to print the PDF file.

When the Encryption level is *40RC4, the following special values are used:

For an Encryption level of *128RC4, Print PDF file specifies print options for the PDF file.

When the Encryption level is *128RC4, the following special values are used:

Use stream file for BCC e-mail address entries. Indicates if a stream file containing BCC e-mail addresses is being used.

The following values are used:

Use stream file for CC e-mail address entries. Indicates if a stream file containing CC e-mail addresses is being used.

The following values are used:

Use stream file for TO e-mail address entries. Indicates if a stream file containing TO e-mail addresses is being used.

The following values are used:

User password. The user password associated with the PDF file to be created.

This field is applicable for Encryption levels *40RC4 and *128RC4.

The following can be used for the user password:

E-mail Address Entry

This table is used for mapping the TO, CC, BCC and ReplyTo e-mail addresses. For more details about the fields that can be used with the following table, see E-mail Address Entry Field Description.

E-mail Address Entry Field Description

E-mail address. An e-mail address.

For the TO e-mail address, the following special value can be specified:

Stream File Entry

This table is used for mapping the stream files that can be used for the Body, Attachment, TO, CC, and BCC stream files. Use one entry for each stream file. If you are specifying a stream file for the Body, the file extension (for example, txt or htm) must be specified in lower case. Otherwise, the file will be sent as an attachment. If necessary, the field is padded with blanks (X'40'). For more details about the fields that can be used with the following table, see Stream File Entry Field Description.

Stream File Entry Field Description

Stream file name. A path-qualified stream file name.

File Name Entry

This table is used for specifying a file name that is not path-qualifed. Use this entry for specifying a PDF file for e-mail entry. This will be the name of the attachment for the PDF file (original spooled file) that is included in the e-mail. For more details about the field that can be used with the following table, see File Name Entry Field Description.

File Name Entry Field Description

File name. A file name which does not contain path information.

PDF Stream File Information Entry

For more details about the fields in the following table, see PDF Stream File Information Entry Field Descriptions.

PDF Stream File Information Entry Field Descriptions

Length of PDF file name. The size, in bytes, of the Stream File entry which contains the PDF file name. For information on the format of a Stream File entry, see Stream File Entry.

Offset to PDF file name. The offset, in bytes, from the beginning of the PMAP0100 format, to the Stream File entry for a PDF file.

Public Authority. The public authority for the PDF stream file. The default is *EXCLUDE.

The following special values may be specified:

PDF Spooled File Information Entry

These fields are used for mapping the PDF spooled file information. If necessary, text fields are padded with blanks (X'40'). For more details about the fields in the following table, see PDF and AFPDS Spooled File Information Entry Field Descriptions.

AFPDS Spooled File Information Entry

These fields are used for mapping the AFPDS spooled file information. If necessary, text fields are padded with blanks (X'40'). For more details about the fields in the following table, see PDF and AFPDS Spooled File Information Entry Field Descriptions.

PDF and AFPDS Spooled File Information Entry Field Descriptions

Form type for output spooled file. The type of forms that should be loaded on the printer before this spooled file is printed. This is the value which will be used when a file is spooled.

The following special values can be used for the form type for output spooled file:

Output queue library name for output spooled file. The name of the library where the output queue for the file which will be spooled resides.

Output queue name for output spooled file. The name of the output queue to which the file to be spooled will be written.

The following special values can be used for the form type for output queue name for output spooled file:

Spooled file name for output spooled file. The name which will be used for the file that gets spooled.

The following special values can be used for the spooled file name for output spooled file:

User data for output spooled file. The user-specified data which will describe the file to be spooled.

The following special values can be used for the user data for output spooled file:

User defined data for output spooled file. The user-defined data that will be used for the file to be spooled.

The following special values can be used for the user defined data for output spooled file:

Error Messages