Distinguishing the Xi-Text offline State From error

Xi-TextXi-Textprinter-statesprinterstroubleshootingsplistspstart

A printer that has stopped by itself is in one of two states, offline or error. This article says what puts a printer into each, how to read which one you have, and how to clear an offline. The third stopped state, halted, is the one a printer is put into deliberately.

What separates the two

offline
The device stopped responding within the time the setup file allows, or the network transport reported a code the setup file maps to offline

Set when the printer loses the line, times out opening or writing to the device, or its network transport dies on a signal or with an exit code that maps to offline

error
Something failed outright and the printer could not proceed

Set by a setup file that is missing or will not parse, a device that cannot be opened or is not a device at all, a failed write, a banner program that will not run, a network transport that crashed or hung, and internal failures

What separates them is whether the fault was a timeout or a mapped exit code (offline) or an outright failure (error). The split is not hardware against software: a device file with the wrong permissions is a hardware-shaped problem that gives error, and a perfectly configured printer that someone switched off gives offline.

Both are cleared the same way. Xi-Text treats halted, offline and error identically when a printer is started: spstart clears all three, with nothing to reset and no need to halt the printer first.

Aspect	offline	error
What it means	The device stopped responding in time, or the transport exited with a mapped code	Something failed outright and could not be worked round
Typical trigger	Printer off, out of paper, cable pulled, print server not answering	Setup file missing or unparseable, device path wrong, device not writable, transport crashed
Report file	Nothing, except a network transport's own output where logerror is set	Almost always a message naming the fault and the file being read
Message after the state	Only on a network printer with fberror set	Always for the four transport failures; otherwise only with fberror
Recovery	Fix the device, then spstart	Fix the cause, then spstart - the same command

To read the state:

# View printer status
splist ptr1

# Output shows the state, with any message after a colon:
ptr1 /dev/lp0 a4.ps offline
ptr1 /dev/lp0 a4.ps error

Three format letters are useful here: %s gives the state with its message, %t gives the bare state name and is the one to use in a script, and %m gives the message alone.

splist -F "%t" ptr1

In spq, switch to the printer screen with 'o' from the jobs screen, or start spq with -p. The state column shows the current state, with any message after it.

See Managing Xi-Text Printer States and Operations for the full eight-state list, and Diagnosing and Clearing the Xi-Text Printer error State for diagnosing and clearing error.

The four things that put a printer offline

All four are a running printer losing touch with its device.

The line dropped. The printer process is told the connection has gone - on a serial device, loss of carrier. At the printer end that covers:

• Printer powered off, or in a standby mode that drops the line
• Cable disconnected or failing
• Terminal server or print server restarted

A timeout expired. Each printer has four timeout settings in its setup files, and two of them lead to offline:

• open - how long to wait for the device to open. Default 30 seconds. Exceeding it puts the printer offline.
• offline - how long a single write may take before the device is regarded as offline. Default 30 seconds for a local device, and 300 in the shipped network device settings. Exceeding it puts the printer offline.
• close - how long to wait for the device or the transport to close. Default 100 seconds for a local device, 10000 in the shipped network device settings. Exceeding it makes the printer kill the transport rather than go offline, and if that fails the printer ends in error with the message "Term serv hung".
• postclose - a pause after closing. A delay rather than a limit.

A write timeout is what an out-of-paper or paper-jam condition usually looks like on a printer that uses flow control: the printer stops accepting data, the write blocks, and the timeout elapses.

A network transport failed to start. The printer could not wait on the process it had just launched.

The transport exited or died on a signal that maps to offline. Every network printer has four such maps, and they have defaults, so this applies whether or not the setup file mentions them:

• By default: exit code 0 is a normal finish; exit codes 1 to 255 give error; the signals SIGHUP (1) and SIGPIPE (13) give offline; every other signal gives error.
• The setup file can replace any of the four maps:

# In the setup file, for a network printer:
exit setoffline 1,10-50
exit seterror 51-255
signal setoffline 1,13
signal seterror 2-12,14-31

Exit codes run 0 to 255 and signal numbers 1 to 31. Two rules matter more than the syntax:

• Each line replaces its own map entirely, and leaves the other three alone. A file that carries only an exit setoffline line still has the default error map covering 1 to 255, so the codes it nominated are in both.
• A code in both maps is taken as offline. Offline is tested first, and it stops the printer before the error test is reached. Write both lines.

These lines apply only to the network transport named by the network keyword. They have no effect on a job filter or on a local device.

Nothing is written to the log when a printer goes offline

The report file is /var/spool/xi/spd/spshed_reps, and it can also be read from spq with the X key.

tail -50 /var/spool/xi/spd/spshed_reps

None of the four causes produces a log entry, so searching the report file for the word "offline", or for the printer's name, finds nothing and proves nothing. The error state is the opposite: it almost always leaves a message naming the fault.

There is one exception, and it applies to network printers only. Where the setup file carries logerror - which the shipped network device settings do - whatever the transport writes to its standard error is copied into the report file:

Error report from printer ptr1 on device srv:9100
Report was: connection timed out

So on a network printer the log may explain the offline; on a local one there is nothing to find, and the printer's own panel is the diagnostic.

Finding the cause

Step 1: Read the printer's line

List the printer, or open spq on the printer screen:

splist ptr1

# Or start spq on the printer screen
spq -p

The state appears with any message the printer has after a colon:

ptr1  <srv:9100>  a4.ps  offline:Out of paper
ptr2  /dev/lp0    a4.ps  offline

A device shown in angle brackets is a network address; anything else is a file. That distinction decides most of what follows, because a message after the state name is only ever available to a network printer - see Messages after the state name below.

Step 2: Check the printer itself

On a local printer, check the power, the paper, the panel lights, any paper jam, the covers and the cable connections. On a network printer, use the printer's own web interface, control panel or manufacturer tools, and test that the network reaches it.

Step 3: Test the device

For serial and parallel printers, check that the device is what Xi-Text needs - a character device or a FIFO, writable by the spooler account:

ls -l /dev/lp0
# crw-rw----   1 root     lp         6,  0 Feb  6 10:00 /dev/lp0

For a serial device, read the line settings and the state of the modem-control signals - some printers use hardware flow control on DTR/DSR or RTS/CTS. The portable form takes the device on standard input:

stty -a < /dev/ttyS0

Device names differ between platforms, so use the name the system in front of you actually uses. If the printer is not asserting the signals the port expects - DSR, CTS or DCD, depending on how the port is configured - the line looks dropped whatever the printer's own panel says. The clocal keyword in the setup file tells Xi-Text to ignore the modem-control lines, which is how a printer wired without them is driven.

Do not read from or write to the device while the printer is running: its own process holds the device open, and anything a shell sends interleaves with the print stream. If a write test is needed, halt the printer first - Diagnosing and Clearing the Xi-Text Printer error State, Step 4, gives the safe form.

For a cable that has been disturbed:

# For serial printers, check cable at both ends
# Verify proper serial cable (not null-modem if direct)

# For parallel printers, ensure cable firmly seated
# Try different cable if available

For network printers, test the address the printer is actually set to:

splist -F "%p %d" ptr1

# Then, against the address it reports
telnet srv 9100

Leave that connection open no longer than it takes to see whether it is accepted. Many print servers accept one connection at a time, and holding it keeps the printer's own transport out.

# Test connectivity
ping printserver

# Check whether the port is accepting connections
telnet printserver 9100

Where the network reaches the printer, it may be rebooting, in power save mode, or its print server software may have crashed; wait a minute and start the printer again. Where it does not, check the cables, the switch, whether the printer's IP address has changed, and whether a firewall is in the way.

Clearing an offline

Fix the device - power, paper, cables - confirm connectivity for a network printer, and start the printer:

spstart ptr1

The printer initialises and enters idle. There is no need to halt it first: halting a printer that is already offline does nothing.

Starting a printer says nothing about failure - the spooler starts it in the background, so spstart reports success whether or not the printer reached idle. Check the state:

splist ptr1

If it goes offline again immediately, the device has not recovered. The printer's own panel is more use than repeating the command, and for a network printer the report file may carry the transport's own explanation.

If it goes offline repeatedly over time:

#!/bin/sh
# Watch one printer's state, for a pattern rather than a single event

while true
do
    date
    splist -F "%p %s" ptr1
    sleep 5
done

A repeated offline suggests an intermittent cable connection, a printer power cycling, network instability, print server crashes, or a timeout set too short for the printer's real speed.

Timeouts set too short

A printer that goes offline repeatedly on a busy or slow device may be outrunning its timeouts. The values are set in the printer's setup files:

grep -E 'open|offline|close' /var/spool/xi/printers/ptr1/.device

Raising the offline value gives a slow printer longer to accept a write before it is given up on; raising open helps a printer that takes time to come ready after a power cycle. Both take effect the next time the printer starts.

An exit code mapped to offline

Where the setup file maps the network transport's exit codes, an exit in the mapped range is a deliberate offline:

# View the setup files
cat /var/spool/xi/printers/ptr1/.device
cat /var/spool/xi/printers/ptr1/default

# Look for:
exit setoffline 1,10-50

To find out what the transport is returning, read the network line and run the same command by hand as the spooler account:

grep network /var/spool/xi/printers/ptr1/.device
# network=/usr/libexec/xi/xtelnet -p 9100 -h srv

su spooler -c '/usr/libexec/xi/xtelnet -p 9100 -h srv < /dev/null'
echo $?

If the exit code falls in the setoffline range, offline is the configured behaviour and the printer is reporting exactly what it was told to. With no exit line at all the default applies, and the default sends every non-zero exit to error, so an offline on a network printer whose setup file mentions neither keyword came from a signal or a timeout.

Messages after the state name

Only a state below halted - that is, offline or error - shows a message, and it appears after the state name separated by a colon. There are two sources for it, and most printers have neither.

Xi-Text's own messages, four of them, all concerning a network transport and all producing the error state:

ptr1 <srv:9100> a4.ps error:Net filt pid lost
ptr1 <srv:9100> a4.ps error:Term serv crashed
ptr1 <srv:9100> a4.ps error:Core dump term serv
ptr1 <srv:9100> a4.ps error:Term serv hung

The transport's own output, where the setup file carries fberror. The last line the transport wrote to its standard error is kept and displayed with whatever state the printer ends in:

splist ptr1
ptr1 <srv:9100> a4.ps offline:Out of paper
ptr2 <srv:9101> a4.ps offline:Paper Jam

A local printer shows a bare state name on offline. The mechanism reads a network transport's standard error, and a parallel or serial printer has no transport, so a printer on /dev/lp0 shows offline alone however informative its front panel is.

To enable the messages on a network printer:

# Edit the setup file
vi /var/spool/xi/printers/ptr1/.device

# Add:
fberror

The companion keyword logerror sends the same lines to the report file. The shipped settings for a network device set both, so a printer installed with the supplied defaults already has them.

Noticing an offline, and having somewhere for the work to go

Because nothing is logged when a printer goes offline, polling the state is the only way to notice:

#!/bin/sh
# monitor-printers.sh

while true
do
    splist -F "%p %t" | while read ptr state
    do
        if [ "$state" = "offline" ]
        then
            echo "ALERT: $ptr offline" | \
                mail -s "Printer Alert" admin@example.com
        fi
    done

    sleep 300   # Check every 5 minutes
done

mail -s is the Linux and AIX spelling; on Solaris and HP-UX the subject option belongs to mailx.

A second printer loaded with the same form type takes the jobs the first one cannot, because jobs are matched to printers by form type rather than tied to one printer:

# Add a backup printer and start it on the same form type
spadd -l /dev/lp1 backup-ptr
spstart backup-ptr a4.ps

spadd takes the device with -l and the printer name as its argument, and needs the add and delete printers privilege. The form type is the second argument to spstart, after the printer name.

Related articles

All articles · Release notes · Contact support