Back to Knowledege base

Xi-Text Printer Setup Files: What They Contain and When They Are Read

The files in a printer's directory, the order in which Xi-Text reads them, and how to tell whether one parsed
V1.x.x Xi-Text configuration printers setup-files troubleshooting

How Printer Setup Files Work

Xi-Text uses text-based setup files to define how each printer operates. These files control everything from hardware communication parameters to page formatting and post-processing filters.

Each printer has its own directory containing one or more setup files. The setup file system enables the same form type (like "a4.ps") to work correctly on different printer models without users needing to know which physical printer they're using.

Directory Structure

Setup files are located in printer-specific subdirectories under the printers directory (default: /var/spool/xi/printers). The default can be moved by setting SPOOLPT in /etc/xi/textconfig.

For a printer named ptr1, setup files are in:

/var/spool/xi/printers/ptr1/

File Types in Printer Directories

Setup Files (Paper Types)

Files without leading . or - characters are setup files representing paper types:

/var/spool/xi/printers/ptr1/a4
/var/spool/xi/printers/ptr1/letter
/var/spool/xi/printers/ptr1/default

A file is offered as a paper type only when it is a plain file owned by the system user spooler. A file owned by anyone else is still read if a job asks for it by name, but it will not appear in the list of paper types that Xi-Text offers an operator loading the printer.

The .device File

The .device file holds the settings that describe the connection to the printer, and that therefore stay the same whatever paper is loaded:

/var/spool/xi/printers/ptr1/.device

This file is where the printer installation script Ptrinstall puts:

  • Serial line settings - baud, ixon, ixany, parenb, parodd, cs7, cs8, twostop, clocal
  • The network command for a printer reached over the network (network=)
  • Timeouts - open, offline, close, postclose
  • Output buffering and device handling - outbuffer, reopen, canhang

The .device file is read before the paper-type setup file, every time the setup files are read. The two files are parsed as one continuous stream, so a symbolic name defined in .device can be used in the paper-type file that follows it.

Having a .device file does not remove the need for a paper-type file or a default file - if neither can be opened the printer fails to start. It is also the only place the network command belongs: a printer whose device is a network address must have a network= command, and a printer on a local device must not have one. Either mismatch stops the printer with "does not have network command specified or non-network printer does".

The physical device or network address itself is a property of the printer, set with spadd or spchange. It is not a setup file setting, and there is no port or device keyword.

Helper Files

Files beginning with . or - are never treated as paper types, so a printer directory is also the natural place for the files a setup file refers to:

/var/spool/xi/printers/ptr1/-Help       # Online help text
/var/spool/xi/printers/ptr1/.setpage    # Named by an align= line
/var/spool/xi/printers/ptr1/.acct       # Named by a record or logfile line

Only -Help is a fixed name: Xi-Text opens it by that name to give an operator help when they are choosing a form type to load onto the printer. The others are ordinary names chosen by whoever wrote the setup file. A file name in an align, record or logfile line that does not begin with / is taken relative to the printer's own directory, which is why the short names above work.

How Xi-Text Selects Setup Files

When a printer needs its setup, Xi-Text:

  1. Splits the form type into a paper type (everything before the first . or -) and a suffix (the rest)
  2. Changes to the printer's directory under the printers directory - if that directory is missing, the printer goes to Error
  3. Reads .device first, if it exists
  4. Reads the file whose name is exactly the paper type
  5. Falls back to default if there is no file of that name
  6. Fails, and puts the printer into Error, if neither can be opened

Steps 4 and 5 happen whether or not there is a .device file. The file name is matched by the operating system, so it is case sensitive - a job submitted as A4.ps is accepted by a printer loaded with a4, but the setup file looked for is A4, and if there is no such file the printer silently uses default instead.

The suffix never selects a file. It selects material within the files that are read, through the conditional construct described below.

Example Selection

For printer ptr1 with these files:

.device
a4
letter
default

Form type selections:

  • a4.ps → reads .device, then a4 (suffix: ps)
  • letter.p10 → reads .device, then letter (suffix: p10)
  • legal → reads .device, then default (no suffix)
  • A4.ps → reads .device, then default, because there is no file called A4

When Setup Files Are Read

Setup files are processed:

  1. At printer startup - .device and the setup file are read before the device is opened and the setup string sent
  2. When the form type changes - if the next job's form type differs from the printer's current one in any character, including the suffix alone, the printer sends its sufend string, adopts the new form type, re-reads both files and sends the new sufstart string

They are not read once per job. A job whose form type matches what the printer is already showing reuses the settings already in memory.

This has two consequences for editing. An edit is picked up at the next printer start, and also at the next form type change, so a file that has been edited into a broken state can drop a running printer into Error part-way through a queue rather than at the moment you saved it. Restarting the printer after an edit is therefore the way to find out immediately whether the file is good.

What Setup Files Control

Setup files can specify:

Hardware Parameters (typically in .device)

  • Serial line settings - baud, cs7 / cs8, twostop, parenb, parodd, clocal
  • Flow control - ixon, ixany
  • Output translation - onlcr, ocrnl, olcuc, onocr, onlret, extabs, addcr
  • Timeouts - open, offline, close, postclose
  • Device handling - outbuffer, reopen, canhang, closekill
  • A command to run against the port before use - portsetup
  • An stty command line to run against the port - stty

Print Job Handling

  • Banner page control - banner, nohdr, forcehdr, stdhdr, hdrpercopy, and bannprog to name a program that produces the banner
  • Single-sheet mode - single, which puts the printer into the a/w oper state before each job so paper can be fed by hand
  • Page delimiter - delimiter, which defines what counts as a page boundary
  • Page range handling - noranges, where the printer itself understands page ranges
  • Copies and retention - onecopy, retain, inclpage1, windback
  • Accounting and logging - charge, record, logfile, logerror, fberror
  • Banner page width - width

Strings Sent to Printer

  • setup - sent once when the printer starts
  • halt - sent when the printer stops
  • docstart - before each document
  • docend - after each document
  • pagestart - before each page
  • pageend - after each page
  • sufstart - after a new form type has been adopted
  • sufend - before the old form type is given up
  • abort - on job cancellation
  • restart - when a job is restarted

Each of these takes its value as a quoted string, or as one or more symbolic names defined earlier in the file. Writing the keyword with an = sign and nothing else clears the string; it does not assign to it.

Processing Options

  • filter - command that all output is piped through
  • network - command that carries the data to a network interface
  • align - file holding an alignment page
  • execalign - command that generates an alignment page
  • bannprog - program that produces banner pages
  • portsetup - command run against the port before the device is opened
  • exec - written before a string keyword's value to run it as a command rather than send it

Conditional Handling

  • Suffix-specific settings using a { (pattern) ... (pattern) ... } block, where the patterns are matched against the suffix and the first one that matches is used
  • @ matches the empty suffix, and *, ? and [...] are the wildcards
  • Suffix patterns are matched case sensitively, and carry no leading dot

Common Setup File Patterns

Serial Printer

# .device file - values are written after the keyword, with no = sign
# Porttype: Serial

baud 9600
ixon
open 30
offline 300
outbuffer 1024

# default setup file
# Symbolic names first - defining one sends nothing by itself

RESET=\eE

setup   RESET
halt    RESET

PCL Printer with Multiple Paper Types

# a4 setup file

RESET=\eE
A4SIZE=\e&l26A

setup   RESET A4SIZE

# letter setup file

RESET=\eE
LETTERSIZE=\e&l2A

setup   RESET LETTERSIZE

Suffix Handling Within One Setup File

LANDSCAPE=\e&l1O
PORTRAIT=\e&l0O
P12=\e(s12H

{
        (l*)
                docstart LANDSCAPE
        (*)
                docstart PORTRAIT
}

{
        (*12)
                sufstart P12
}

Network Terminal Server

# .device file

open 30
offline 300
close 10000
postclose 1
reopen

network=/usr/libexec/xi/xtelnet -p 9100 -h $SPOOLDEV

Syntax Errors and Diagnostics

Setup file syntax errors prevent printer startup. When a printer enters Error state:

  1. Check the system log file: 
    tail -20 /var/spool/xi/spd/spshed_reps
  2. Each entry names the printers directory, the printer and the file that was being read, then gives the reason. The messages come from the setup file reader and read like:
    • "Error near line 12 - probable undefined name `csize'." - a name Xi-Text does not recognise, used without an = sign
    • "Error near line 4 - Number expected" - a keyword such as baud or open followed by something other than a number, most often an = sign
    • "Error near line 9 - Expected a `}'" - an unclosed conditional block
    • "Error near line 7 - Invalid baud rate 12000"
    • "There does not appear to be a setup file (even a possible default one of `default') in the printer directory for printer name ptr1"
    • "There does not appear to be a directory for the printer name ptr1 in the printers directory /var/spool/xi/printers"
  3. The same file can be read from within spq with the X command.

Nothing is written to the log when a setup file is read successfully, so an empty log after a printer start means the files parsed.

Common mistakes, and what each one actually does:

  • A keyword name Xi-Text does not have. Any unrecognised word is taken as a symbolic name, so it needs an = sign and a value. Without one you get "probable undefined name". With one - ptr_type=ps, for example - it is accepted in silence and does nothing at all.
  • Writing setup=, docstart= and so on with a value. The = sign on these keywords only clears the string. The value must follow as a quoted string or as a symbolic name.
  • A backslash or other punctuation where a keyword is expected. This is the dangerous one. Writing setup=\e&l26A stops the parse dead at the backslash: the rest of the file is discarded, nothing is logged, the printer starts, and it starts with an empty setup string. Escape sequences belong on the right-hand side of a symbolic name definition, as in the examples above.
  • An unclosed quote. The string simply ends at the end of the line; no error is raised.

File Permissions

Setup files should be:

  • Owner: spooler - required for a file to be offered as a paper type
  • Permissions: 644 (read for all, write for owner)
  • Directory: 755 (readable and executable for all)

Xi-Text does not test the group, and the group the packages give these files differs between distributions, so leave it alone.

Check permissions:

ls -la /var/spool/xi/printers/ptr1/

Fix if needed:

chown -R spooler: /var/spool/xi/printers/ptr1/
chmod 755 /var/spool/xi/printers/ptr1/
find /var/spool/xi/printers/ptr1/ -type f -exec chmod 644 {} \;

Use find rather than a shell wildcard here. A wildcard does not match a leading dot, so it silently skips .device - the first file Xi-Text tries to open.

Template Directories with Symbolic Links

For identical printers, create a master template directory and link to it:

# Master template
/var/spool/xi/printers/hp-laserjet-template/

# Symbolic links
/var/spool/xi/printers/office1 -> hp-laserjet-template
/var/spool/xi/printers/office2 -> hp-laserjet-template

Individual files can also be linked:

cd /var/spool/xi/printers/office1
ln -s ../template-printer/a4 a4

Xi-Text follows the link when it checks a file, so it is the file at the far end of the link that must be a plain file owned by spooler.

Testing Setup Files

After creating or modifying setup files:

  1. Stop and restart the printer - this is what forces the files to be read
  2. Check that the printer reaches a running or waiting state rather than Error
  3. Read the system log if it does not, remembering that a clean start writes nothing there
  4. Send a test job, and a second one with a different suffix, to exercise the conditional blocks
  5. Verify strings are sent correctly (use printer self-test or network capture)

Related Articles

  • Configuring Xi-Text Form Types, Paper Types and Suffixes - Understanding form type structure
  • Managing Xi-Text Printer States and Operations - Starting and stopping printers
  • Diagnosing and Clearing the Xi-Text Printer error State - Troubleshooting setup file problems
  • Reading the Xi-Text System Log (spshed_reps) - Reading the messages described above
  • Setting Up and Working With Xi-Text Alignment Pages - The align and execalign keywords

Documentation Reference

For complete setup file syntax and all available keywords, see the Xi-Text System Reference Manual, Chapter: Printer Definitions.

Labels
V1.x.x Xi-Text configuration printers setup-files troubleshooting
Configuring Xi-Text Form Types, Paper Types and Suffixes
What a form type is, the exact rule matching a job to a printer, and how a suffix changes without stopping the printer