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.
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:
-
for + (plus sign) use %2B
- for = (equals sign) use %3D
- for % (percent sign) use %25
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.