Debugging Print Problems

How many times have you gotten this call: “I need APPX to print me a list . . .”. You throw together an output and route it to the user’s printer, and . . . Argg, the report didn’t print! In this issue we will talk about where to start troubleshooting a printing problem. We will cover printing text outputs only. We will cover PDF printing at a later time.

First and foremost, it is important to understand that APPX does not print anything. That is the most fundamental part of APPX outputs, and a big part of where to start trouble shooting. When an output process ends, APPX creates two files, a text file of the report and a configuration file that contains the print and printer options. All printing is handled by the operating system. In order to find where the problem exists, you must first figure out if the problem is in APPX or at the operating system level.

Let’s go back to the statement about APPX creating the two files. When an output is completed APPX creates the two files, a text file containing the output and a text file containing the configuration information from the disposition. These files are not closed until the process ends (after the End of Process event point). All APPX print files are created with an eight character file name. The default names are PRTFI000, and PRTFI000.cfg. The 000 is a sequence number that is incremented if the file already exists in order to create a unique file name. The prefix can be overridden by entering a value in the Report File Name field of the output process. For example, if you enter REPT in the file name field, the first output created would be named REPT0000.

Now that the output has completed, we have our print file and configuration file, but where are they? The path to the print file location varies, depending on the operating system, release of APPX, and your environment variable settings. Release 4.2.x of APPX treats all operating systems the same now, and print files are stored by default in the $APPXPATH/PRINT/<appx usr id> directory. The default print file location can be overridden by setting the APPX_PRT_FI_DIR environment variable. If this variable is set, all print files will be placed in the indicated directory and will not be separated by user ID. Earlier releases of APPX for Unix and Linux placed print files in the /tmp directory by default unless, of course, APPX_PRT_FI_DIR was set.

To make sure print files can be created, you should check the file permissions for the PRINT directory and the user subdirectories. On Unix and Linux installations the directories should have permissions set to 777. On Windows make sure the user has full rights to the directories. On Linux/Unix systems, if APPX does not have permission to write to the PRINT directory, it will go into a loop trying to create the file. If your output appears to be hung, open a terminal connection to the server and change the PRINT directory permisssions. If permissions were the problem, your output will then run.

You can start your search in the middle, and then work towards an end. Very simply, if the print and configuration files exist in the print directory, then the problem is not in APPX and you can concentrate on the operating system. If they don’t, then the problem is probably in APPX and/or your application.

If the problem is in APPX, you can try printing the output to the screen to make sure the process is actually running to completion. In order for the print-on-screen utility to work, the print file must first be created on the server. If the output does not create the file, then go through your normal debugging steps. Set traps in various event points to see that the process is flowing as expected. Check the selection criteria to make sure records are being selected. Check the Use Query value to make sure there are no typos and the right query is being executed. Check the print disposition or defaults to make sure Print Hard Copy is set to yes. You could also run the utility to check for duplicate ANOs and EMs if everything looks correct but the process just seem to run wrong.

If the print-on-screen displays the report and you have the option to print hardcopy set to yes, then APPX is working just fine and your problem is at the operating system level. The actual printing is handled by the operating system spooler, or a third party spooler if one has been installed. APPX passes the print file to the operating system to handle the printing. How that hand-off occurs depends on the operating system and whether the printing is to be done from the server or from the client.

Sometimes it is as simple as making sure the printer is defined on the operating system or in your spooler. The .cfg file contains the name of the printer defined in APPX. Check to make sure the printer name matches your OS name. Remember, case is important.

Unix/Linux Server Printing

When APPX has created the print and configuration files, the appx_print script is executed to get the data to the operating system. The default script that is installed with APPX on Unix and Linux servers supports three commands for printing, lp (Unix), lpr (Linux), and ulp (UniQue, now named Axiar). When the script is executed it determines which command should be used, then formats the command with the file name and appends the arguments based on the values found in the configuration file. The arguments are the values found on the printer and form definitions, plus values entered in the disposition screen. Errors encountered by the appx_print script are directed to the /tmp/appx_print.last text file.

If the print file exists and does not print you can add echo statements to the appx_print script to see that it is executing properly, or executing at all. The script is executed in a shell, which may not always be installed on your system. Look at the very first line of the script to see what shell is being invoked (like ksh) and type that shell name at the command prompt. If that causes an error, modify the appx_print script to execute a shell you do have installed. Make sure standard error is directed to a text file so that you can review the results; otherwise the statements will appear on the console. Look for the text >/dev/null in the script and change /dev/null to a file name in a writeable directory, such as /tmp/appx_script_errors.

You can also review the appx_print.last file. It is located in the /tmp directory and contains all the information from the execution of the appx_print script, including the values from the configuration file, the first 10 lines of the report, and the command executed to invoke the spooler. Look for errors from the script and try typing the command at the console. If the command works from the command line, it will work from the script. If the command line fails, so will the script.

Printing on Unix and Linux servers may also use filters. Filters are scripts that are used to interpret commands and format them into the escape sequences recognizable to a printer or type of printer. An example of a filter is MPAGE (see the print format field on the disposition screen). You can add echo statements and redirect errors from the filter scripts in the same manner as the appx_print script.

Remember, the scripts supplied by APPX are simply general scripts that should work in most default installations. If your installation requires a different shell, or if you have a different spooler that the script is not set up to handle, you can change the script or filters in any way you need. If you do modify the appx_print script you may want to give the new script a different name and set the APPX_PRT_SCRIPT environment variable so you won’t break printing the next time you upgrade APPX.

Windows Server Printing

Print files created on a Windows server are processed by winprint.exe. The winprint.exe program does about the same thing on Windows as the appx_print script does on Unix, except it is not a script and it does not format a command line in quite the same manner. Arguments received by winprint.exe are checked against a list of commands within winprint.exe and formatted accordingly. All other arguments are passed through in the same format they are received. It is up to the printer and/or driver to handle those commands. You can see the list of arguments winprint.exe recognizes by typing "winprint.exe" at a command prompt.

While there is no appx_print.last on Windows, winprint.exe can be run from the command prompt with the print file name, and optionally other arguments, to manually test printing. Executing winprint.exe with no arguments will print a list of the options supported by winprint. You can also set the WINPRINT_DEBUG environment variable to a writeable file name in order to help with debugging printing problems.

Many printer drivers have two versions, one for interactive printing and one for non-interactive printing. In some cases the non-interactive drivers may not fully support all the features the interactive drivers support. If winprint.exe appears to be working properly but the report prints incorrectly, or not at all, there may be a driver issue. You can check the printer manufacturer’s web site for an updated driver, or check FAQs for more information.

Check the printer name on the server against the OS ID in APPX. The name in APPX must match exactly the server name, not the name on the user’s desktop. Remember, printing is done from the server, not the desktop. You can also try the full UNC path to the printer if the name is giving you problems.

If you are formatting printer commands in your output and they seem to be getting ignored, try adding the –raw option to your form control options. The –raw option tells winprint.exe to pass the commands through to the printer as received, without trying to reformat them.

Windows Client Side Printing

Client side printing is pretty much the same as server side printing on Windows. Instead of winprint.exe, though, client side printing is handled by nativeWindows.dll (formerly known as winprintdll.dll). While the two are not identical, nativeWindows.dll supports and recognizes all the options available in winprint.exe. With a few exceptions, troubleshooting printing problems is about the same.

With client side printing, APPX copies the print and configuration files from the server to the desktop. The first thing to check when printing from the client is the permissions of the directory the files are copied into. Usually that would be under the user’s Documents and Settings directory. Find the print directory under the \.appx\cache\<server>\<port>\Print path and make sure the user has permission to write to the directory, and that the print file is actually there.

An option available with client printing is –interactive. By placing –interactive in the printer options in APPX, the operating system will be instructed to open the print dialog box. This is a handy way to see if there is a difference with the interactive and non-interactive versions of the driver.

This article does not cover every aspect of troubleshooting a printing problem. Each installation and each situation presents its own set of circumstances. Hopefully this article will help you get started on the right track to solve your problem quickly. As always, APPX Software’s technical support staff is ready to help you in those situations when you need us.

Comments:

Read what other users have said about this page or add your own comments.