|
Tech Tip
UnForm -- Advanced code block Techniques
Copy control example:
Mixed Copy and Page Collation Techniques ...
Background
The copies and pcopies
commands are used to generate multiple copies of document pages from a single
copy in a text print stream.
Copies produces a copy of the entire print
stream, after printing or processing the entire print stream the first time
through, and works with the laser and postscript drivers, but not with the PDF
driver.
Pcopies produces and inserts a copy page by
page. This works with all drivers, including PDF.
The Challenge
Batch print streams that include multi-page documents are a
collating challenge not handled well in a generic copies or pcopies environment,
specifically when the second or following copies need to be inserted or printed
after the printing the first copy of all pages of a multi-page document.
There are various ways to solve this problem with code-block
logic, two of which are presented below.
Overview of the Two Methods
Example 1 - UnForm Sub Job
Logic
Example 1 uses the following page control functions and
internal variables:
- jobstore(), jobexec(), jobclose()
- get()
- skip, uf.subjob
- if copy / endif
This method spawns a new UnForm job for each discrete
document in the print stream.
It has the disadvantage that since each document
becomes a separate job, other reports and documents can be printed in between
the documents which used to comprise a single print stream. If a
dedicated printer is used for a certain type of form, this may not present a
problem.
Example 2 - UnForm Page
Insertion Logic
Example 2 uses the following page control functions and
internal variables:
- get(), getpage(), inspage()
- arrtostr(), strtoarr()
- uf.maxpage
This method retains the job as a single print stream,
inserting the new copies in the proper location in the print stream during the
prejob codeblock execution.
It has the disadvantage that on very large batch
jobs, ones that involve thousands or tens of thousands of documents, system
performance may be affected during the page insertion process.
An integrator will have to weigh the advantages and
disadvantages of each method based on the particular environment at the
installation.
NOTE: A zip file download link is included at the bottom
of the article which includes these sample files, if you would like to copy them
into your UnForm samples directory for testing.
Example 1 - UnForm Sub Job Logic
Here is a snapshot from the UnForm design tool of the rule-set that employs
subjob logic to tackle the problem, followed by some comments describing the
details.
[Mixed Collation 1] RULE-SET DETAILS
page 51
cols 80
rows 51
portrait
... page geometry settings
copies 2
... process 2 copies from a single instance of the job stream,
... print the second copy after all original pages of the job
... have been printed
... note that since this example will spawn separate sub-jobs
... for each customer's document, and print pages will be
... suppressed (skipped) in the main job, this specification
... of the number of copies will apply to the sub-job
prepage {
}
... establish a prepage code-block, the code here will be
... executed BEFORE printing a page of output
if not(uf.subjob) then:
endif
... do not execute the enclosed logic if the process being run
... is the spawned sub-job, only do it in the main launching job
... a sub-job uses the same rule-file and rule-set as the main
... job by default, unless a command line argument specifying
... a different rule-file or rule-set is included in the jobexec
... arguments
skip=1
... in the main job, skip printing each page altogether,
... the printing is going to happen from the sub-job
Customer$=get(50,10,6,1)
... get the customer number off the page, it's going to be
... used as the document ID to distinguish when the document
... changes
noMoreCustPages=(customer$<>get(50,10,6,1,pagenum+1))
... set a boolean flag variable to 1 if the customer ID on the
... current page does NOT match the customer ID on the next page
jobstore(Customer$)
... store the text of this page in a temp file named with the
... current customer, along with previous pages, if any
if noMoreCustPages then:
endif
... if there are no more pages for this customer then
... process the enclosed commands
jobexec(customer$,">lp -dhp","laser","-c")
... execute the subjob to print this document using the
... jobexec() command, using the temp file created by
... the jobstore(), sending the output to the lp spooler,
... using the laser driver, and pass the "-c" command line
... argument to force use of the copies feature, which
... will cause the extra copy to print after all pages of
... the first copy are printed
jobclose(customer$)
... close the job and clean up variables and workfiles
<end of prepage code-block logic>
<regular UnForm command mode>
if copy 1
text 15,1,"Customer Copy",univers,18,bold
endif
if copy 2
text 15,1,"File Copy",univers,18,bold
endif
... print the unique copy title depending on which
... copy is currently being output
# formatting on all copies
cfont 50,1,60,1,univers,18,left,bold
cfont 50,10,55,1,univers,18,bold
text 40,1,"Page: ",univers,18,bold
... formatting that applies the
same to all copies
Example 2 - UnForm Page Insertion Logic
Here is a snapshot from the UnForm design tool of the rule-set that employs page
duplication and insertion logic to tackle the problem, followed by some comments
describing the details.
[Mixed Collation 2] RULE-SET DETAILS
page 51
cols 80
rows 51
portrait
... page geometry settings
prejob {
}
... establish a prepjob
code-block, the code here will be
... executed BEFORE processing or printing any page of output
pg=1,sav=0
... initialize the new job page counter at page 1,
... set the stored document page variable to zero
dim mypgstr$[0]
... dimension a string array variable to a single empty
... element zero, this is a variable that will store document
... pages to be duplicated as the code progresses
while pg<=uf.maxpage
wend
... process the enclosed logic only while the page
... counter variable pg is within the range of pages
... for the current job stream
... the internal global variable uf.maxpage is set and maintianed
... by UnForm automatically
Customer$=get(50,10,6,1,pg)
... get the customer number off page pg, it's going to
be
... used as the document ID to distinguish when the document
... changes
noMoreCustPages=(customer$<>get(50,10,6,1,pg+1))
... set a boolean flag variable to 1 if the customer ID on the
... current page does NOT match the customer ID on the next page
getpage(pg,mypg$[all])
... get the entire contents of page pg, and put it in an
... array called mypg$[] -- each array element represents
... an individual sequential line from the page
sav+=1
... the sav variable will track the number of pages for each
... customer's documents, here it is incremented by one
redim mypgstr$[sav]
... a string array is dimensioned or re-dimensioned for the
... new number of pages for a customer's document
arrtostr(mypg$[all],x$,$0a$)
... take the page array created with the getpage function
... and convert the entire array to a simple text string x$,
... with the line-feed character hex 0A as the line
... separator; this is so we can store the entire page
... contents in a single array element
mypgstr$[sav]=x$
... store the x$ contents from above in an array called
... mypgstr$[], using the value of the sav variable from above
... for the array element number, which corresponds with each
... sequential page
if noMoreCustPages then:
endif
... process the following only if there are no more pages
... in the current customer's document, this uses the boolean
... variable determined earlier
for i=1 to sav
next i
... for each page stored in the working array, based
... on the page counter tracked in the variable sav,
... do the following
x$=mypgstr$[i]
... extract the page stored in the mypgstr$[] array
... into the variable x$
strtoarr(x$,myNewPg$[all],$0a$)
... convert the line-feed delimited page string in x$
... into the array myNewPg$[], where each page line
... is now stored back in individual array elements
pg+=1
... increment a counter for the page count of the
... new duplicate to be inserted into the job stream
myNewPg$[1]=pad(myNewPg$[1],132)
myNewPg$[1](1,10)="CopyNo 2"
... pad the first line of the duplicated page with spaces
... out to a length of 132,
... and place the text "CopyNo 2" in the first ten bytes
... of the first row, as an identifier that it as a duplicate
... copy of a page
inspage(pg,myNewPg$[all])
... insert the new page array into the job text stream
... as page pg; the subsequent pages will be automatically
... renumbered by UnForm
sav=0
dim mypgstr$[0]
... reset the individual document page counter to zero,
... reset the individual document page string array to an
... array with only an empty element zero
pg+=1
... increment the new job stream page counter by one,
... so that the next page in the job stream, which is the first
... page of a new document from the original print stream,
... will be the active page that the process continues with
... when it returns up to the top of the loop
<end of prejob codeblock logic>
prepage {
}
... establish a prepage code-block, the code here will be
... executed BEFORE printing a page of output
extraCopy$=get(1,1,8,"y")
... from the top line of each page, get the first 8 characters --
... remember, this is the location where we put the copy "CopyNo 2"
... text on the first line of each duplicate page we inserted
if extraCopy$="" then:
copyTitle$="Customer Copy"
else
copyTitle$="File Copy"
endif
... set the copyTitle$ variable to be printed on each page based
... on whether there is text in the value extraCopy$, which means
... it is the duplicate "file" copy, or whether it is empty, which
means
... it is an original "customer" copy of the page
<end of prepage codeblock logic>
<regular UnForm command mode>
cfont 50,1,60,1,univers,18,left,bold
cfont 50,10,55,1,univers,18,bold
text 40,1,"Page: ",univers,18,bold
... enhance certain areas of each page
text 1,1,{copyTitle$},univers,18,bold
erase 1,1,10,1
... place the copy title on the page by referencing the value
... of the code-block variable copyTitle$ in a text command,
... and erase the duplicate copy text string placed each
... duplicate page during the prejob process
----------------------------------------------------------------------------------------
Automating the processing of multiple copies of a single form-text print-stream
is a very common and widespread application of UnForm's advanced forms
technology. Understanding the various ways it can be accomplished is useful and
sometimes critical information when the need arises.
By familiarizing yourself with these methods, it is also possible you might
discover some creative new ways to build smarter functionality into your forms
processing applications.
"Smart Form" code-blocks: one of UnForm's important features
for developers and integrators who need to take total control of the forms
and document processing environment.
|
