Distinguishing the Xi-Text offline State From error

Offline vs Error States

A printer that is stopped is in one of three states - halted, offline or error. Halted is the state a printer is put into deliberately. The other two are states a running printer falls into by itself, and they are the two that need explaining.

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

Two things about the pair are often assumed and are not true.

• Neither is less recoverable than the other. Xi-Text treats halted, offline and error identically when a printer is started: spstart clears all three. There is nothing to reset and no need to halt the printer first.
• The split is not hardware against software. A device file with the wrong permissions is a hardware-shaped problem that gives error; a perfectly configured printer that someone switched off gives offline. What separates them is whether the fault was a timeout or a mapped exit code (offline) or an outright failure (error).

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.

What Causes Offline State

A printer is put into offline in exactly four situations, and 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. What that means at the printer end covers most of the ordinary cases:

• 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 rather than relying on that.

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.

Diagnostic Approach

Step 1: Check the Printer Display

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 Error Messages on Offline State below.

Step 2: Check the Physical Printer

For local printers:

• Verify power on
• Check paper loaded
• Look for error lights/messages on printer panel
• Clear any paper jams
• Ensure covers closed
• Check cable connections

For network printers:

• Access printer web interface (if available)
• Check printer control panel via terminal server
• Verify printer status via manufacturer tools
• Test network connectivity

Step 3: Test Device Accessibility

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, the line settings and the state of the modem-control signals are worth reading. 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.

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 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.

Step 4: Review the System Log - and Know What Is Not There

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

Xi-Text writes nothing when a printer goes offline. 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. This is the opposite of the error state, which 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.

Resolving Offline Conditions

Hardware Issues

Printer powered off:

• Power on printer
• Wait for ready state
• Start printer in Xi-Text:

spstart ptr1

Out of paper:

• Load paper
• Clear any paper-out sensor errors
• Start printer:

spstart ptr1

Paper jam:

• Clear jam following printer manual
• Ensure no torn paper remains
• Close covers fully
• Start printer:

spstart ptr1

Printer error condition:

• Check printer display/lights for specific error
• Resolve indicated problem (toner, drum, maintenance)
• Clear error on printer
• Start printer in Xi-Text

Connectivity Issues

Cable disconnected:

# 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

After reconnecting:

spstart ptr1

Serial port signals:

Some printers use hardware flow control signals (DTR/DSR, RTS/CTS):

# Check serial port settings and signals
stty -a < /dev/ttyS0

If the signals indicate offline, the printer hardware may not be asserting the ready signals correctly, or the port may be configured to require signals this printer does not send. 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 normally driven.

Network printer unreachable:

# Test connectivity
ping printserver

# Check whether the port is accepting connections
telnet printserver 9100

If network reachable:

• Printer may be rebooting
• Printer in power save mode
• Print server software crashed

Wait a minute and retry:

spstart ptr1

If network unreachable:

• Check network cables
• Verify switch/router operation
• Check printer IP address hasn't changed
• Verify no firewall blocking

Timeouts

A printer that goes offline repeatedly on a busy or slow device may simply 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.

Exit Code Configuration

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

# 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. Remember that with no exit line at all the default applies, and the default sends every non-zero exit to error rather than offline - so an offline on a network printer whose setup file mentions neither keyword came from a signal or a timeout rather than from an exit code.

Offline vs Error Differentiation

How to tell which 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

Or check in spq:

• Switch to the printer screen (press 'o' from the jobs screen, or start spq with -p)
• The state column shows the current state
• Any message appears after it

Key differences:

Recovery Procedure

For offline state:

1. Fix physical issue (power, paper, cables)
2. Verify connectivity (ping for network printers)
3. Start printer:

spstart ptr1

Printer should initialise and enter idle state. There is no need to halt it first: halting a printer that is already offline does nothing.

Starting a printer is silent about failure - the spooler starts it in the background, so spstart reports success whether or not the printer reached idle. Check the state rather than the command:

splist ptr1

If it goes offline again immediately, the device has not recovered. Reading 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 pattern of repeatedly going offline suggests:

• Intermittent cable connection
• Printer power cycling
• Network instability
• Print server crashes
• A timeout set too short for the printer's real speed

Error Messages on Offline State

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 both are worth knowing because most printers have neither.

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

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 never shows a message 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 a bare offline however informative its front panel is. For a local printer a bare state name is the expected display.

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.

Preventing Offline Conditions

Regular maintenance:

• Keep printers stocked with paper
• Replace consumables before depletion
• Clean printers regularly
• Check cables periodically

Monitoring. 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.

Redundancy. 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.