Blue Prairie Forms allows for a wide array of configuration options.   To allow documents to be processes in parallel, additional phantom threads can be defined so that many job scan be sent to your printers simultaneously.  To understand how to properly configure threading, you should understand what it does.  The following diagram will be referenced below.

Document Creation Flow (from left to right)

1. Your program calls the BP Forms API to generate a document.
2. The document is written to a queue directory. 
3. The queue directory is normally a path on the MultiValue server such as /dbms/BPIFORMS/bpi_forms/queue/bpiform1
4. One or more phantoms may poll the queue directory and attempt to process the documents placed into it in first-in, first out order.  The first phantom to find and lock the document is the winner and will process the document.  The other phantoms will observe that the document has been locked by the winning phantom and will skip the locked document and move onto the next available document.
5. The winning phantom will communicate with the BP Forms server.
   1. It will check to see that the server is alive
   2. It will check to ensure that the printer name to which the document is to be directed exists on the BP Forms server (in CUPS)
   3. It will check to ensure that the mount that allows the BP Forms server to reach into the queue directory is working
   4. If all of these checks are successfuil, the phantom will send a command to the BP Forms server to start open office, load the document and print it to the targeted printer.
6. Open office loads the document and prints it to the specified printer
7. CUPS (Common Unix Printing System) communicates with the printing device (e.g., PDF printer, Physical printer, etc) and delivers the print job to the printer.  Note that in release 4.2 of BP Forms (2025), you can now render directly to PDF without going through the CUPS PDF printer driver. 
8. Open office closes and notifies the phantom thread that the print was successful
9. The phantom returns to polling the queue directory.

What can be done to improve print performance?

Some printing problems are at the printer hardware or network level.  It is best to run printing tests independent of BP Forms to ensure that the performance problem is not network, WAN or printer device related.

If these tests show that the printer is working well, then the problem could be the speed at which the system can deplete the queue directory.  BP Forms allows for one or more phantoms to process a single queue directory.  Remember that if you place most of your documents into the same queue directory and have only one phantom polling it, then the document printing time may be impacted because BP Forms must process the printing of the document serially in first-in, first out order.  If a large document is queued, it may take some time for open office to open , print and deliver it to CUPS. This can cause documents queued after the large document to 'back up' in the queue leading to the perception that the printing is 'slow'.

Threading to the Rescue

To speed up processing, you may run several phantom threads all polling the same queue directory.  In doing so, printing will be parallelized and documents will not become 'stuck' behind a large print job.  If a large print job is being processed, the other phantoms that process that queue will simply run ahead to the next available document and process it.

If your print jobs must be processed in the order that the print jobs are created by your application, then it is best to have a single phantom thread processing that queue.  But for most printing, the order of the print jobs appearing on the printer(s) is less important than the speed of the printing.

A thread requires a unique user

Blue Prairie Forms achieves threading by calling LibreOffice on the print server.  To run multiple simultaneous instances of LibreOffice on the print server at the same time, each instance of Libre Office must be run as a different user.  This is much like running Microsoft Word or Excel on Windows.  If you login to your PC as user 'bruce' and then launch Word, it will bring up word.  But if in the same session you bring up Word again, it does not launch a new instance of Word, but rather, simply brings the existing instance into the foreground.

Libre Office and Linux work the same way.  BP Forms is designed to launch many LibreOffice instance simultaneously.  To cause multiple instances of Libre Office to launch, each instance is launched using a different (unique user).   For parallelization/threading of tasks, BP Forms requires that a unique user name, for that thread be created on both the jBASE server and on the Print Server.  While BP Forms does not care which user names are used, it is common practice to name the user(s) based on the queue they will be servicing.  For example, if your queue is /db/accts/BPIFORMS/bpi_forms/queue/bpiform1, then your username is recommended to begin with bpiform1.  By following this practice, it makes it easy to instantly recognize a process, running as a specific user, is processing that queue. 

In our example above, we have a queue named bpiform1 with a user named bpiform1.  But, if we want to have the queue bpiform1 processed by three threads (phantoms) for parallel processing, then we would:

1) Create three threads named bpiform1.1, bpiform1.2, bpiform1.3 that all process the queue bpiform1.

2) Create linux/unix users called bpiform1.1, bpiform1.2, and bpiform1.3 on both the MultiValue server and on the print server(s)

3) Establish a passwordless ssh shared key between each username on the MultiValue server and the same username on the print server.

With this done, BP Forms can freely launch simultaneous instances of LibreOffice (each with a unique user name).  This allows for parallel processing and, because of the structured and uniform naming conventions used for these users, we can observe the libre office processes running on the print server and instantly understand for each instance:

1) Which queue it is processing; and

2) which thread/phantom launched it.

For more information about configuring phantom threads, see Administrative Interfaces.