PDFing Home PageProgramming for PDFing
Spooled-files sent to PDFing contain not only the text to be converted but also the spooled-file's attributes. The various attributes of a spooled-file may be set at different times, by different OS400 commands. When a spooled-file is sent to PDFing, PDFing will read its attributes and, based on their values, determine the processing to be applied.
You can set up PDFing so that a spooled-file's name, user-data or form type attribute values will automatically select a markup file, which specifies a set of processing parameters applied to a spooled-file. Please note that when TRANSFORM(*YES) is specified for the *OUTQ writing to PDFing,  this "transform" process removes all spooled-file attributes, excepting file-name, user-name and user-defined-text. Please see our documentation for host-print-transform which describes how to send all the attributes, even when a spooled-file must be "transformed".
You can specify tags as values for either or both of the user-defined data and user-defined text attributes. PDFing recognizes the tags in these attribute values and sets the processing parameters for this spooled-file accordingly. Tags provide the means for you to specify (for instance) the destination of an e-mail or the name of a markup file. Please note that any parameter values set by tags will always override the corresponding configuration and markup parameters.
You can also specify where attribute values are to be inserted into the text of an email message or they can be used to form (part of) a document's file name.
Finally, you may create a script that will be interpreted by the language Lua for PDFing which is "embedded " in PDFing. This script can automatically set the processing parameters for a spooled-file, based on the file's attributes and text-contents.


Before a new spooled-file is opened, you may use the OVRPRTF command to specify an alternative name for this spooled-file:
OVRPRTF FILE(EXAMPLE) SPLFNAME(NEWNAME)
If you want to specify particular processing options for files of this name, you can create a "markup" file named newname.mku that defines the processing options. Then, provided that one of the default markup values is set to *FILENAME, any spooled-files named NEWNAME will processed as specified by the particular options in this "markup" file.


Before a new spooled-file is opened, you may use the OVRPRTF command to specify the value of this attribute:
OVRPRTF FILE(EXAMPLE) USERDTA(TESTING)
After a spooled-file has been created, you may use the CHGSPLFA command to change the value of this attribute:
CHGSPLFA FILE(EXAMPLE) JOB(*) SPLNBR(*LAST) USERDTA(TESTING)
If you want to specify particular processing options for files with this user-data, you can create a "markup" file named testing.mku that defines the processing options. Then, provided that one of the default markup values is set to *USERDATA, any spooled-files with a user-data value of TESTING will be processed as specified by the particular options in this "markup" file
Please see our documentation for host-print-transform which describes how to send this attribute with the spooled-file text, even when a spooled-file must be "transformed".


Before a new spooled-file is opened, you may use the OVRPRTF command to specify the value of this attribute:
OVRPRTF FILE(EXAMPLE) FORMTYPE(INVOICE)
After a spooled-file has been created, you may use the CHGSPLFA command to change the value of this attribute:
CHGSPLFA FILE(EXAMPLE) JOB(*) SPLNBR(*LAST) FORMTYPE(INVOICE)
If you want to specify particular processing options for files of this form-type, you can create a "markup" file named invoice.mku that defines the processing options. Then, provided that one of the default markup values is set to *FORMTYPE, any spooled-files of form-type INVOICE will be processed as specified by the particular options in this "markup" file
Please see our documentation for host-print-transform which describes how to send this attribute with the spooled-file text, even when a spooled-file must be "transformed".


You may configure PDFing so that, depending on the incoming spooled-file's name, user-data and form-type attributes a markup file is selected automatically and its processing parameters are applied for this spooled-file. If the name of a markup file is specified by the EDM tag, then specified markup file is always used.
The destination page of the configuration form allows you to specify values for one or more of the controls labelled "Default Markup". The values you enter here are replaced at run-time by the corresponding attribute values from the incoming spooled-file and the result string is used to locate a markup file of this name. If the file exists, then its processing parameters are applied for this spooled-file.

PDFing Default Markup
For instance, if you specify *USERDATA in the control, and a spooled-file with a value of TEST as its *USERDATA attribute is received, then PDFing will attempt to locate a markup file named TEST. If a markup file of this name exists, then the processing parameters specified in the file will be applied.
The control values are evaluated in sequence, so you may prioritise the way in which markup files are selected. You may specify any value you like for these controls, including any combination of special-characters. This gives you more control over the way in which markup files can be named.


Before a new spooled-file is opened, you may use the OVRPRTF command to specify up to 255 characters of "user-defined data" for the new spooled-file. Any "tags" specified here override the value of corresponding "tags" that may have been specified for the user-defined text attribute. An example of specifying the value of the "user-defined data" attribute follows:
OVRPRTF FILE(EXAMPLE) USRDFNDTA('EMA=recipient@thehost')
Here the command USRDFNDTA parameter contains a "tag" which specifies an e-mail address as the destination of the documents produced from this spooled-file. After a job executes this OVRPRTF command and creates spooled-file: EXAMPLE, the value of this "User Defined Data" parameter is saved with the report text. When processed by PDFing the spooled-file will be sent to: recipient@thehost. Use command: WRKSPLFA to check the user-defined data which will be sent with a spooled-file. You can also use option: 8 from the display presented by commands: WRKOUTQ WRKSPLF etc. to check this attribute value.
After a spooled-file has been created, you may use the CHGSPLFA command to change the value of this attribute:
CHGSPLFA FILE(EXAMPLE) JOB(*) SPLNBR(*LAST) +
USRDFNDTA('EMA=another@thehost')
To specify the subject-line of the email, as well, use command:
CHGSPLFA FILE(EXAMPLE) JOB(*) SPLNBR(*LAST) +
USRDFNDTA('EMA=another@thehost EMS=The Subject Line')
You may also specify the name of the markup file to be applied to this spooled-file, using command:
CHGSPLFA FILE(EXAMPLE) JOB(*) SPLNBR(*LAST) +
USRDFNDTA('EDM=example')
Please see our documentation for host-print-transform which describes how to send this attribute with the spooled-file text, even when a spooled-file must be "transformed".


When OS400 opens a new spooled-file, the "User Print Information" information associated with the job's user-profile is saved with the report data as the value of the spooled-file's "User Defined Text" attribute. as the user creates spooled-files. Please note that this information will only be sent when DESTOPT(*USRDFNTXT) (note the exact spelling!) has been specified for the output-queue. Also, note that each "tag" string entered into "User Print Information" must not include any spaces; because you may want to include blank spaces, PDFing implements URL encoding.
You may use the OS400 CHGUSRPRTI command to specify up to 100 characters of "User Print Information" for your own profile and (with sufficient authority) any other OS400 user profile. Once set, all spooled-files created by the user will contain a copy of this user print information in its "User Defined Text" attribute. To specify your own user print information, use command:
CHGUSRPRTI USER(*CURRENT) TEXT('EMA=recipient@thehost')
Here the TEXT parameter contains a "tag" which specifies the destination e-mail address for the current user. Any spooled files created by the user after this change to their user-print information, and processed by PDFing will be sent to: recipient@thehost If you want to specify more than one e-mail address, use command:
CHGUSRPRTI USER(*CURRENT) TEXT('EMA=one@thehost;two@thehost;three@thehost')
Here the TEXT parameter specifies a series of e-mail addresses for the current user. Any spooled files created by the user after this change to their user-print information, and processed by PDFing will be sent to: one@thehost , two@thehost and three@thehost. The (;) semi-colon character acts as the delimiter between e-mail addresses.
Use command WRKSPLFA to check the user-defined text which will be sent with a spooled-file. You can also use option: 8 from the display presented by commands: WRKOUTQ WRKSPLF etc. to check this attribute value.
Because "User Defined Text" is only written once (when the spooled-file is created), it cannot be changed by the CHGSPLFA command. However OS400 application program interfaces (API) allow you to duplicate a spooled-file and change the "User Defined Data" at the same time. We have created the OS400 utility commands SNDPDFSPLF and DUPPDFSPLF which allows you to duplicate a spooled-file and change its attributes at the same time.
If you use OS400 command SNDTCPSPLF to send a spooled-file to PDFing, the user-defined-text is not sent. However, you may specify the same tags in the DESTOPT() parameter of the command, these "tag" strings must be URL encoded. If you specify that our host-print-transform programis used with this comnand,  all spooled-file attributes, including user-defined-text, will be sent.
Spooled-files produced from OS400 software packages like EZPRINT and FORMSPRINT remove any "user-defined-text" specified in the original spooled-file. However, "user-defined data" is processed correctly.


In this document, we have described how to specify the User-Defined-Data and User-Defined-Text attribute values. The following is a complete list of the "tags" that PDFing will recognize.
Each instruction has the format Exx=sssssssss, where Exx= is the tag-type and sssssssss is the tag-text. You can specify any combination of these tags but each tag should be specified only once and each tag must be separated from the following tag by at least one blank space.
ECA=n
Specifies spooled-file to ASCII conversion, where n switches conversion to ASCII, off (0) or on (1).

ECP=n
Specifies spooled-file to PDF conversion, where n switches conversion to PDF, off (0) or on (1).

ECR=n
Specifies spooled-file to RTF conversion, where n switches conversion to RTF, off (0) or on (1).

ECX=n
Specifies spooled-file to Excel conversion, where n switches conversion to Excel, off (0) or on (1).

ECX=xxxxxx
Specifies spooled-file to Excel conversion, where xxxxxx specifies the name of the "example" Excel file.

ECZ=n
Specifies zip-file creation to archive files resulting from the conversion, where n switches creation of a zip-file, off (0) or on (1).

ECZ=ppppppp
Specifies zip-file creation, where ppppppp is the password required to open the zip-file.

EDC=n
where n specifies the level of PDF compression required from 0 - 9.

EDK=keywords
Specifies key-words for PDF and RTF documents.

EDM=markupname
Specifies the name of the Mark Up file (not including the file extension) containing processing parameters to be applied to the spooled-file.

EDN=documentname
Specifies the name of the PDF document-name to be used when e-mailing or saving to disk. Reserved characters will be replaced by the underline character.

EDO=P
Specifies the orientation Landscape or Portrait of the PDF document.

EDS=asubject
Specifies the subject of the PDF document.

EDT=atitle
Specifies the title of the PDF document.

EEC=n
Specifies "digital-signing" of the PDF file, where 0 switches digital-signing off, and any positive number selects the signing-certificate to be used.

EEM=ppppppp
Specifies encryption of the PDF file, where ppppppp is the master password required to edit the PDF.

EEU=ppppppp
Specifies encryption of the PDF file, where ppppppp is the user password required to read the PDF.

EET=nnnnn
Specifies other encryption PDF parameters. corresponding to those options on the [Security] page, where n switches the option, off (0) or on (1).

EHP=n
Controls processing of PCL macros. where n=0 specifies that any previously saved PCL commands are deleted, n=1 specifies that this spooled-file contains PCL commands which are to be saved and then added to the start of any AFPDS spooled-files that are subsequently processed by PDFing and n=2 specifies that this spooled-file contains PCL commands which are to be added to previously saved PCL commands.

EHN=nnnnnnn
where nnnnnnn specifies that the name of a file containing PCL commands which has previously been created and saved in the \Markup directory. These PCL commands are then added to the start of this AFPDS spooled-file before processing by PDFing.

EMA=ssssssss
Specifies the e-mail address or other destinations of the PDF document. Several email addresses may be specified but each address must be delimited by a semi-colon (;) character.

EMA=*
Specifies that the e-mail address is to be derived from the base configuration or markup parameters. You should only specify this tag value in the user-defined data attribute when you need to override the EMA= tag value in the user-defined text.

EMF=fromaddr@host.com
where fromaddr@host.com specifies the e-mail "from" address.

EMG=replytoaddr@host.com
where replyroaddr@host.com specifies the e-mail "reply to" address. If not specified, the "reply to" address is the same as the "from address".

EMH=n
Specifies if the spooled-file is to be "held" before emailing, where n switches the hold state off (0) or on (1).

EML=nnnnn
Specifies the CCSID of the job that created the spooled-file.

EMN=ssssssss
Specifies the recipient of a notification message. This tag normally applies only when the documents created from a spooled-file are saved to disk and e-mailed, but see other destinations for a list of options.

EMR=n
Specifies that the e-mail recipent is asked to return a receipt, where n switches receipting, off (0) or on (1).

EMS=asubject
Specifies the subject of the e-mail.

EMV=n
Specifies which SMTP server processes the email. Where 1 specifies the server described on the [System] page of the configuration form, 2 specifies the server described on the [SMTP2] page of the configuration form, and 0 specifies that either server can process the email.

EMX=ttttttt
where ttttttt is any arbitrary text string which replaces the special character &X in email subject and body text etc.

EMY=ttttttt
where ttttttt is any arbitrary text string which replaces the special character &Y in email subject and body text etc.

EMZ=ttttttt
where ttttttt is any arbitrary text string which replaces the special character &Z in email subject and body text etc.

ENA=n
Specifies whether a notification messsage (see tag EMN above) has the converted documents attached, where n switches attaching off (0) or on (1).

ENU=sssss
Specifies the "Notify" URL from where saved documents can be retrieved by a web-browser (see tag EMN above). The special character &R in email subject and body text etc. is replaced by this URL concatenated with the saved document's file-name.

EPC=n
Specifies the number of copies to be printed, where n is the number of copies.

EPN=sssss
Specifies the printer name. See printer addresses for more information.

The tag text-string may itself contain these special characters which are replaced at run-time by each spooled-file's attribute values.
Please note that any parameter values specified by "tags" will always override the corresponding configuration and markup parameters.


The disposition of the document(s) produced from a spooled-file may be specified using the appropriate tag as described above. Any such tag values will override the parameter values specified in the destination page of the configuration and markup forms. PDFing processes a destination value according to its format, the possible formats are described below:
Any Email Address or Addresses
Any string not conforming to one of the following formats is assumed to be an email address. You can use a ; (semi-colon) character to delimit a list of email addresses. You can prefix email addresses with TO: or CC: or BCC: to determine how email addresses are presented to email recipients.

Any Valid Directory
This destination is assumed when the destination text begins with the string X:\dddd , where X is a local or networked disk drive, and dddd is a valid directory name. PDFing will copy the document(s) to this directory. You should use network drive names carefully as the NT Service version of PDFing will use the System log-in by default.

Any valid UNC Location
This destination is assumed when the destination text begins with the string \\UUU\DDD , where UUU is the name of a remote computer and DDD is a storage-device on the remote computer. UNC stands for the Microsoft Universal Naming Convention.

A Pre-defined List of Addresses
A list destination begins with the string *LIST*. The text following this string should be the (optional) name of a mail-list (not including the file extension) and an (optional) lookup-code. If no mail-list is specified then the mark-up name (if specified) will be used as the mail-list name. If this destination includes a colon character (:) character, then any text following this colon is used by PDFing to select any address(es) in the mail-list where the address-code matches this text. If no "selection text" is specified, PDFing will select all the addresses in the mail-list.

A "Set" Name
It is possible for PDFing to delay sending a spooled-file until all the spooled-files in a set have been received and then to send all the spooled-files in this set as attachments to a single email. Each spooled-file in the set of spooled-files must have a "send to destination" value specified as: *SET*sssss, where sssssss specifies the set name. The last spooled-file of a set must also specify an email address (or addresses) as the "notify address" value. When the last spooled-file of the set is received, all the spooled-files saved for this set, will be attached to an email sent to the "notify address".

A "Merge" Name
It is possible for PDFing to delay sending a spooled-file until all the spooled-files in a set have been received and then to merge all PDF files in this set into one PDF document. Each spooled-file in the set of spooled-files must have a "send to destination" value specified as: *MERGE*sssss, where sssssss specifies the set name. The last spooled-file of a set must also specify some valid destination as the "notify address" value. When the last spooled-file of the set is received, the merged PDF may be attached to an email and sent to the "notify address", saved to a disk location specified in the "notify address" and/or printed.

A "Zip" Name
It is possible for PDFing to delay sending a spooled-file until all the spooled-files in a set have been received and then to send all the spooled-files in this set as a single zip-archive attached to a single email. Each spooled-file in the set of spooled-files must have a "send to destination"" value specified as: *ZIP*zzzzz, where zzzzz specifies the set name and also the name of the zip-archive.The last spooled-file of a set must also specify an email address (or addresses) as the "notify address" value. When the last spooled-file of the set is received, all the spooled-files saved for this set, will be added into a new zip-archive which is then attached to an email sent to the "notify address".

A Printer (-p)
Because you may not enter asterisk * characters in to an e-mail address-list, but you want to specify printing and (optionally) the printer-name corresponding to an address-code, this form -p of the printer directive is provided. Specify the number of copies by using -pn , where n specifies the number of copies. The remaining characters in the string specify the printer-name. See printer addresses for more information.

A Printer (*PRINT*)
If you just want PDFing to print the spooled-file, specify the destination *PRINT* and PDFing will print a single copy to the default printer. You may also specify the number of copies, by using the form: *PRINT*n , where n specifies the number of copies. See printer addresses for more information.

A NULL address
A NULL destination is specified by the string *NULL* or -n. You may use a NULL addresses to override any default addresses or disk-locations, so that PDFing will not perform that particular processing step.

The Keep Directory
This destination is assumed when the destination text begins with the string *KEEP*. The rest of the text following this string is the name of a directory within the \PDFing\Keep sub-directory.

The specified destination may contain the following special characters which are replaced at run-time by each spooled-file's attribute values.


Certain special characters can be used to represent particular attribute values of a spooled-file, or text-strings selected from the spooled-file. When special characters are used in an instruction tag or entered as (part of) a configuration or markup parameter, they are replaced at run-time by values derived from the spooled-file being converted.
&d
is replaced by the date and time when the spooled-file was created. (If Available)

&f
is replaced by the OS400 form-type. (If Available)

&j
is replaced by the OS400 job name. (If Available)

&m
is replaced by the OS400 spooled-file number. (If Available)

&n
is replaced by the OS400 job number. (If Available)

&p
is replaced by the OS400 program name. (If Available)

&u
is replaced by the OS400 user-data. (If Available)

&B
is replaced by the text extracted from spooled-file text and used to "burst" the spooled-file.

&C
is replaced by the code extracted from spooled-file text and (optionally) used to look-up the email address(es).

&D
is replaced by the date & time on which the spooled-file was converted.

&F
is replaced by the name of the spooled-file.

&H
is replaced by the OS400 host name.

&J
is replaced by the PDFing job name.

&K
is replaced by the (comma-delimited) list of book-marks.

&L
is replaced by the local host name of the PC on which PDFing runs.

&N
is replaced by the name(s) of the documents.

&O
is replaced by the name of the user who originally created the spooled file.

&P
is replaced by the page count of the document(s).

&Q
is replaced by the LPD queue name.

&R
is replaced by the Notify URL text concatenated with the document name.

&S
is replaced by the attachment (PDF or ZIP) file size in kilobytes.

&T
is replaced by the "print-text" of the spooled-file.

&U
is replaced by the name of the user who created the spooled file.

&V
is replaced by the program name and version number of PDFing.

&X
is replaced by the special text-string, as specified by the "tag" EMX=ssssssss.

&1 - &24
are replaced by the text-strings, extracted by the markup Text specifications

You can also specify sub-strings of the replacement text by using the "built-in" %SST function. For example:
%SST(&F 2 5)
will extract a sub string of the spooled-file name, beginning at position two and ending at position six. The first parameter is one of the special-characters, the second is the start position and the third is the length of the sub-string.


Because each tag in the user-defined text attribute must be terminated by a space, included spaces are not allowed within the tag. PDFing understands a restricted form of URL encoding (RFC1522), where + (plus sign) may be used to indicate an included space within a tag string. Because of this change, the following special characters must be encoded when used within a tag string:
Note that % (percent sign) is followed by two hexadecimal digits that represent the equivalent ASCII character.
For example if you wanted to send the message with the subject:
This is an example using encoded characters: +=%
You need to create the following tag:
EMS=This+is+an+example+using+encoded+characters:+%2B%3D%25


PDFing now has an embedded scripting language called Lua for PDFing. You can write scripts in this language which examine the attributes and text of each spooled-file as it is received and conditionally set various parameter values. Lua scripts can also read files from disk, HTTP and FTP servers. This allows you to customise PDFing's operations to suit your particular requirements.
We also provide various programs which can be called from Lua to support specialised functionality such as adding PDF pages to the PDF produced by PDFing. Please see the list of optional Lua for PDFing programs.


You may download these utility commands from our web site, either as source code: pdfingsource.zip or as objects in a save file. pdfingsavf.zip Once these commands have been installed, their OS400 help text may be displayed or printed. The following is only a brief summary of their capabilities.
TSTCHARSET (Produce Test Page)
Allows the user to produce a test page for checking EBCDIC to ASCII translation by PDFing.

DUPPDFSPLF (Send PDF spooled-file)
Allows the user to make a duplicate copy of an existing spooled-file, change the user-defined-text and user-defined- data attributes and move the new spooled-file to the specified output-queue.

SETPDFDFT (Set PDF defaults)
Allows the user to set up user print information and performs the necessary validation processes such as checking for included blanks.

SNDPDFSPLF (Send PDF spooled-file)
Allows the user to make a duplicate copy of an existing spooled-file, change the user-defined-text attribute and move the new spooled-file to the specified output-queue.

WRKPDFSPLF (Work with PDF spooled-files)
Allows the user to display selected spooled-files and execute command SNDPDFSPLF on one or more spooled-files.

CHKPDFDFT (Check PDF defaults)
Supports above utility commands.

GETPDFDFT (Get PDF defaults)
Supports above utility commands.

UCVTDEC4 (Convert Decimal to Full Word)
Supports above utility commands.

UMOVERM (Move Error Messages)
Supports above utility commands.

USNDERM (Send Error Message)
Supports above utility commands.
We supply the source code to these commands so that you may inspect the code before you install it. Please feel free to modify these commands or to create new commands based on these examples.


This document ©Jane Hearn 2006-2014.