PDFing Home Page Lua for PDFing
PDFing includes an embedded "little" language called Lua. Users can write a simple script that can analyse the attributes and text-contents of incoming spooled-files. If required, the script can specify values for the parameters the control the way that PDFing will process a spooled file.
This embedded language is based on Lua version 4. Basic information about Lua functions, operators and control structures is provided in this document. You may download the Lua 4 reference manual from the L4X web site at www.pdfing.com/l4x. An integrated development environment for L4X is available. This includes program: L4p.exe for editing and testing lua scripts for pdfing.
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.


Using Lua to control PDFing
To use Lua, the user should create file \Markup\PDFingScript.lua , which must define at least one of the following functions:
function Event.OnBeginConvert(Page, Message, Job)

end
function Event.OnBeginSecure(Page, Message, Job)

end
function Event.OnEndConvert(Page, Message, Job)

end
The OnBeginConvert function is called by PDFing when a spooled-file is received, before it is converted. This function accepts three parameters:
Page - a Lua table containing fields derived from the first page of the spooled-file text. The user script can use these values to determine the appropriate values for the fields of the Message table.
Message - a LUA table containing fields which define how PDFing will process a spooled-file. The field values set by the OnBeginConvert function of your script will specify how PDFing will process this job's spooled-file. It is possible to add new fields to this table for your own particular purposes, as the new field values can be read by the OnBeginSecure and OnEndConvert functions.
Job - a LUA table containing fields derived from the spooled-files attributes. The user script can use these values to determine the appropriate values for the fields of the Message table.
The function OnBeginSecure is called by PDFing after a spooled-file has been converted to a PDF, but the PDF has not been secured. This function takes the same three parameters: Page, Message and Job.
The function OnEndConvert is called by PDFing after all spooled-file conversion is complete. This function takes the same three parameters: Page, Message and Job.
If you are testing a script using the debugger, then the script must call function:
-- Required for debugging (must be last statement)
Pdfing.Debug()
as the last statement of a script. This runs your script in debugging mode, but is not required (and will be ignored) when running in PDFing.
Some Examples are provided at the end of this document.


Input LUA Table: Page
This table provides information about the text contents of the spooled-file which is being processed by PDFing.
Fields of table: Page
Field Name Type Comments
getlines() function getlines(frompage [, fromline, toline])
Returns a table containing the specified lines of text. The field named: n in the returned table contains the number of text-lines in the table. The other fields in this table each contain one line of text and may be referenced by the lua index operator: [1] through [n].
writeline() function writeline(page, line, text)
Write the contents of the text parameter to the specified page and line of a new intermediate file. This new file is the one that will be converted to a PDF file. Each line of text within a page can only be written once and all pages must be written in page sequence. This function can only be used with "un-transformed" *SCS spooled-files. Please consult the author of PDFing before using this function!
linecount number (readonly) The number of lines in the spooled-file page in process.
lineno number (readonly) The line number of the spooled-file text line in process.
pagecount number (readonly) The number of pages in the spooled-file.
pageno number (readonly) The page number of the spooled-file in process.
maxline number (readonly) The maximum number of lines in any page of text.
maxpos number (readonly) The maximum number of positions in any line of text.
text string (readonly) The text from the spooled-file text line in process.
texts[] table of strings A Lua table of text lines from the spooled-file page in process. A particular line of text can be refenced by the index operator, for example: texts[2]


Input/Output LUA table: Message
This table allows your script to assign values to the following fields, which control how PDFing will process the current spooled-file. Changes to this table are only effective when performed in the Event.OnBeginConvert() function.
You may also add your own named fields to this table. This will allow you to save values calculated in the Event.OnBeginConvert() function for use in the Event.OnBeginSecure() and Event.OnEndConvert() functions, without creating global variables.
Fields of table: Message
Field Name Type Comments
addtoset() function Message.addtoset(filename, [before])
Call this function to add a file to a set of files. The first parameter is the file-name, the second (optional) parameter controls whether the file is added to the set after (0) or before (1) the files of this job. For example: Message.addtoset("D:\\Temp\\another.pdf", 1) You may specify an alternative file-name, to be used when the the file is sent by email, for example: Message.addtoset("D:\\Temp\\another.pdf>alias", 1) The file received by email will then be: alias.pdf.
holdfontabs() function Message.holdfonttabs(tab1, tab2, ...)
Call this function to de-activate specified tabs on the [Fonts] of the selected markup. Each of the (one or more) parameters specifies a tab-number to be de-activated.
lookupaddress() function Message.lookupaddress(mail_list, [code], [separator])
Call this function to return a list of email addresses from a mail-list. The first parameter is the name of a mail-list, the second (optional) parameter is the code used to select addresses and the third (optional) parameter is the separator character inserted between each address. If you want this function to return all addresses in a mail-list, omit the second parameter or pass nil.
markup string Specifies the name (not including extension) of a Markup file which will be used for this job's processing parameters. If you specify a single asterisk "*", this re-sets all processing parameters to their configuration default values.
createpdf boolean Specify 0 - Do not create PDF file from the spooled-file.
Specify 1 - Create a PDF file from the spooled-file.
createasc boolean Specify 0 - Do not create an ASCII-text file from the spooled-file.
Specify 1 - Create an ASCII-text file from the spooled-file.
creatertf boolean Specify 0 - Do not create an RTF file from the spooled-file.
Specify 1 - Create an RTF file from the spooled-file.
createexl boolean Specify 0 - Do not create an Excel file from the spooled-file.
Specify 1 - Create an Excel file from the spooled-file.
exltemplate string Specifies the name (not including extension) of a "template" excel file for use when converting a spooled-file to excel.
createzip boolean Specify 0 - Do not create a ZIP archive for attached files.
Specify 1 - Create a ZIP archive for attached-files.
zipname string Specifies the name of the ZIP archive file. (Overrides Message.docname)
zippassword string Specifies the password for the ZIP archive file.
docname string Specifies the name-prefix of the file(s) when saved to disk or attached to email.
doctitle string Specifies the title of the PDF file.
docsubject string Specifies the subject of the PDF file.
docauthor string Specifies the author of the PDF file.
dockeywords string Specifies the key-words of the PDF file.
docaddproperties boolean Specify 0 - Do not set file-properties.
Specify 1 - Set file-properties using PDF title, subject and author.
docencryptmaster string Specifies the owner/master password for the PDF file.
docencryptuser string Specifies the user password for the PDF file.
docencrypt128 boolean Specify 0 - Use 40 bit strength encryption.
Specify 1 - Use 128 bit strength of encryption.
docallowprint boolean Specify 0 - Do not allow users to print the PDF file.
Specify 1 - Allow users to print the PDF file.
docallowchange boolean Specify 0 - Do not allow users to change the PDF file.
Specify 1 - Allow users to change the PDF file.
docallowcopy boolean Specify 0 - Do not allow users to copy the contents of the PDF file.
Specify 1 - Allow users to copy the contents of the PDF file.
docallownotes boolean Specify 0 - Do not allow users to add notes to the PDF file.
Specify 1 - Allow users to add notes to the PDF file.
docsignature number Specify 0 - Do not "digitally-sign" the PDF file.
Specify greater than 0 - Specifies the number of a valid signing-certificate.
mailsubject string Specifies the subject text of the email.
mailbody string Specifies the body text of the email. Each line of text must be separated by CRLF pair. If you specify a single asterisk "*", then the body text is set to NULL.
maildestination string Specifies the destination of the converted spooled-file. If this value is an email address or addresses then an email with attachments will be sent to these addresses. Each recipient should be separated by a semi-colon. If you specify a single asterisk "*" this sets the destination to all blanks.
maildestlist string Specifies the name of the mail-list. An email with attached files will be sent to every address in this list.
mailnotify string Specifies the recipient(s) of a "notification" email. Each recipient should be separated by a semi-colon. If you specify a single asterisk "*" this sets the notification recipient to all blanks.
mailnotifylist string Specifies the name of the mail-list. A "notification" email will be sent to every address in this list.
mailnotifyattach boolean Specify 0 - Do not attach files to notification email.
Specify 1 - Attach files to notification email.
mailfrom string Specifies the reply-to email address of the email.
mailreceipt boolean Specify 0 - Do not ask mail recipients for receipt message
Specify 1 - Ask mail-recipients for receipt message.
mailhold boolean Specify 0 - Do not HOLD emails before sending.
Specify 1 - HOLD emails before sending.
printername string Specifies the name of the printer.
printcopies number Specifies the number of copies to print.
printcolor number Specifies whether printing is to be in color or in monochrome.
Specify 0 to use the default setting of the printer.
Specify 1 to force monochrome printing.
Specify 2 to force color printing.
printtray string Specifies the tray for paper input, either by name or number.
printbin string Specifies the bin for printed paper output, either by name or number.
printduplex number Specifies whether printing is to be double-sided.
Specify 0 to use the default setting of the printer.
Specify 1 to force vertical duplex.
Specify 2 to force horizontal duplex.
Specify 3 to switch double-sided printing off.
printrange string Specifies the range of pages to be printed. This can be a single page ("2") or a range ("2-9") or a starting page ("2-"). The page-numbers must be valid or printing will fail.
By default, all pages are printed.
printquality number Specifies printing quality in dots-per-inch.
Specify 0 to use the default setting of the printer.
holdnoaddr boolean Specifies the action PDFing should take if the address-code is not found.
Specify 0 (false) if PDFing should send the message to the default destination.
Specify 1 (true) if PDFing should hold the message before sending to the default destination.
skipafterburst boolean Specifies the action PDFing should take after bursting a spooled-file.
Specify 0 (false) if PDFing should continue to process this spooled-file.
Specify 1 (true) if PDFing should not process this spoooled-file after it has been burst.
macro number Specify -9 to ignore any previously saved PCL macro-file.
Specify -2 to apply any previously saved PCL macro-file to this spooled-file. This is the default value.
Specify -1 to delete any previously saved temporary PCL macro-file, after applying it to this spooled-file.
Specify 0 to delete any previously saved temporary PCL macro-file, before processing this spooled-file.
Specify 1 to temporarily save this spooled-file as PCL macro-file which will then be added to the start of any *AFPDS or *USERASCII spooled-files subsequently received by PDFing
Specify 2 to add this spooled-file to a previously saved temporary PCL macro-file which will be then added to the start of any later AFPDS or *USERASCII spooled-files subsequently received by PDFing.
macroname string Specifies the name of a PCL macro-file previously saved in the \Markup directory. This macro-file is added to the start of this *AFPDS or *USERASCII spooled-file before it is processed by PDFing.
pclparameters string Specifies a series of parameters, each separated by CRLF pair. These parameters control how PCL is converted to PDF.
pclspecial boolean Specifies the which component PDFing should use to convert *AFPDS and *USERASCII spooled-files.
Specify 0 (false) if PDFing should use the latest version of the component.
Specify 1 (true) if PDFing should use an older version of the component.
luaburst boolean Specify 1 (true) if you want your lua script to handle "bursting". Your script must also include an implementation for function Event.OnBurstPage
addrbook string Specifies the name (without extension) of the address-book which will be searched by address-code when looking up email addresses. If you specify a single asterisk "*" then any value specified for field addrcode will be processed as an email address.
addrcode string Specifies the code that will be used to look up the address(es) of email recipient(s). Replaces "special characters" &C at run-time.
bursttext string Specifies the text that determined where a spooled-file was "burst" into a series of documents. Replaces "special characters" &B at run-time.
copyuserattachment string Specifies the full path name of the user supplied file that should be copied and attached to emails.
moveuserattachment string Specifies the full path name of the user supplied file that should be moved and attached to emails.
attachextensions string Specifies any non-standard file-extension(s) necessary to process any user-supplied-files that may be attached to emails. For example:
Message.attachextensions = ".csv"
clonetags string Specify one or more text-lines (delimited by \r\n) containing one or more processing "tags". A new copy of the current job will be created for each text-line. The "tag" strings in the text-line specify how this new job should be be processed by PDFing.
userlogname string Specify the name of a file, which will contain a copy of the control-file for this job. The control-file(LP*.con) will be copied once the job is complete or encounters an error.


Input LUA Table: Job
This table provides information about the attributes of the spooled-file which is being processed by PDFing.
Fields of table: Job
Field Name Type Comments
jobpdf string Sequential job-number (supplied by PDFing)
host string Host name of the system that wrote the spooled-file.
queue string Name of the "remote" output-queue that wrote the spooled-file.
user string Name of the user that created the spooled-file.
spooledfile string Name of the spooled-file.
receiveddate string Date and time (YYYMMDDHHNNSS) when spooled-file recived by PDFing.
inpdatafile string Name of the work-file containing the spooled-file text.
If the file-extension is .lpr then this the "raw" spooled-file text.
If the file-extension is .inx then this the "translated" spooled-file text.
os4attributes boolean 1 = true - Spooled-file data includes OS400 attributes such as form-type, user-date, etc.
0 = false - Spooled-file data does not include OS400 attributes.
The spooled--file will include OS400 attributes only when the remote output-queue is specified as DESTTYPE(*OS400) TRANSFORM(*NO) or our "transform exit program" for PDFing is used.
os4job string Name of the job that created the spooled-file.
Only valid when os4attributes equals 1.
os4jobnumber string Number of the job that created the spooled-file.
Only valid when os4attributes equals 1.
os4filenumber string Number of the spooled-file.
Only valid when os4attributes equals 1.
os4formtype string Form-type of the spooled-file.
Only valid when os4attributes equals 1.
os4userdata string User-data of the spooled-file.
Only valid when os4attributes equals 1.
os4dvcname string Name of the device-file that created the spooled-file.
Only valid when os4attributes equals 1.
os4pgmname string Name of the program that created the spooled-file.
Only valid when os4attributes equals 1.
os4createdate string Date and time (YYYMMDDHHNNSS) when spooled-file created.
Only valid when os4attributes equals 1.
istransformed boolean 1 = true - Spooled-file has been transformed by OS400.
0 = false - Spooled-file has not been transformed by OS400.
pagecount number Number of pages in spooled-file
markup string Name of the markup file used to process the spooled-file
destination string Destination of the spooled-file.
notifyaddress string Notify address of the spooled-file.
holdmail boolean 1 = true - Email will be held, and must be released before it will be sent.
0 = false - Email will be sent automatically.
specialtext string Special free-form text sent with spooled-file
language string Language code sent with the spooled-file.
wasburst boolean 1 = true - This spooled-file is the result of "Burst" of another spooled-file.
0 = false - This spooled-file is NOT the result of "Burst" of another spooled-file.
addresscode string Addressing Code (extracted from spooled-file text).
Only valid after conversion.
burstbytext string Bursting text (extracted from spooled-file text).
Only valid after conversion.
cloned boolean 1 = true - Spooled-file is a "clone" of an original spooled-file.
0 = false - Spooled-file is not a "clone" of an original spooled-file.
clonenumber number Sequence number of "cloned" spooled-file
macro number Macro processing-type specified by the EHP= "tag". Default value is -2.
macroname string Macro name specified by the EHN= "tag".
printername string Name of selected printer.
printcopies number Number of copies to print.
pathpdf string Full file path of the PDF file created by this job.
Only valid after conversion.
pathasc string Full file path of the ASCII file created by this job.
Only valid after conversion.
pathrtf string Full file path of the RTF file created by this job.
Only valid after conversion.
pathexl string Full file path of the Excel file created by this job.
Only valid after conversion.
pathall string Base path to files created by this job.
loadfromdir string Name of the Windows directory from which PDFingScript.lua is loaded.
Always valid.
tempdir string Name of the temporary Windows directory \Temp used by PDFing.
A different sub-directory will be used when debugging.


Lua Functions.
Your script can use any of the functions defined in Lua 4.0 or in its standard libraries. The following functions from the Lua string manipulation library are documented here, for convenience.
A script may, of course, define new functions:
function printhello() -- start function definition of "printhello"
    print("hello")
end                   -- end function definition
-- call function
printhello() -- >> "hello"


Lua Operators.
Scripts can use any of the operators defined in Lua 4.0.
The assignment operator is:
=
The arithmetic operators are:
+ - / * ^
The string concatenation operator is:
..
The relational operators (including inequality ~=) are:
== ~= < > <= >=
These operators return nil as false and a none nil value as true.
The logical operators are:
and or not
Like Lua control structures, all logical operators consider nil as false and anything else as true. The conjunction operator and returns nil if its first argument is nil; otherwise, it returns its second argument. The disjunction operator or returns its first argument if it is different from nil; otherwise, it returns its second argument. Both and and or use short-cut evaluation, that is, the second operand is evaluated only if necessary.
The constructor operator for tables and arrays is:
{}
The index operator for tables and arrays is:
[i]
The index value i may be a number or a string. An array is a Lua table without field names, so the expression a[1] refers to the first element in array a , a[2] refers to the second element, and so on.


Lua Control Structures.
Scripts can use any of the control structures defined in Lua 4.0. For convenience, if is defined below as:
if logical-expression then block-of-statements end

if logical-expression then block-of-statements else block-of-statements end
Lua also provides iterative control structures while and for. LuateX scripts do not usually require iteration and these control structures should be used with caution.


Example scripts using Lua for PDFing.
-- begin Lua script ------------------------------------
-- This script is not for spreadsheet creation !
-- Example (1) of PDFingScript.lua
-- Author: David Fowle (dfowle@pdfing.com)
-- Date: 5th July 2003
--------------------------------------------------------------
-- Event Function (before conversion begins)
function Event.OnBeginConvert(Page, Message, Job)

-- Set mail-subject and body from spooled-file text, depending on spooled-file name
if  (Job.spooledfile == "MailBody") then
    Message.createpdf   = 0 -- do not want any attachments
    Message.creatertf   = 0
    Message.createasc   = 0
    Message.createexl   = 0
    Message.createzip   = 0
    Message.mailsubject = Page.texts[1]
    Message.mailbody    = ""
    for	i = 2, 9, 1 do        -- gets lines 2 thru 9 of the spooled-file text
        Message.mailbody  = Message.mailbody .. Page.texts[i]
        Message.mailbody  = Message.mailbody .. "\r\n"
        end
    return
    end

end
--  end Lua script -------------------------------------


-- begin Lua script ------------------------------------
-- This script is not for spreadsheet creation !
-- Example (2) of PDFingScript.lua
-- Author: David Fowle (dfowle@pdfing.com)
-- Date: 5th July 2003
--------------------------------------------------------------
-- Event Function (before conversion begins)
function Event.OnBeginConvert(Page, Message, Job)

if  (Job.spooledfile == "ReplacePdf") then -- Depending on spooled-file
     Message.docname       = "TestCopy" -- set attached file name
     Message.usercopyfile  = "C:\\Temp\\Copied.pdf" -- add new field
     Message.createpdf     = 1 -- make sure that pdf is sent by email
     Message.creatertf     = 0
     Message.createasc     = 0
     Message.createexl     = 0
     Message.createzip     = 0
     return
     end

end
--------------------------------------------------------------
-- Event Function (after conversion ends)
function Event.OnEndConvert(Page, Message, Job)

-- if new field not nil - replace PDF generated from spooled-file
if (Message.usercopyfile) then
    Message.copyuserattachment = Message.usercopyfile
    end

end
--  end Lua script
--------------------------------------------------------------

This document ©Jane Hearn 2004-2007.