Understanding and Resolving Printer Error States

Understanding Printer States

Xi-Text printers can be in one of eight states:

Startup : Printer initialising with setup string

Idle : Ready to print jobs with current form type

Printing : Actively printing a job

Shutdown : Processing shutdown sequence after halt command

Halted : Stopped, no jobs printing (initial state)

a/w oper : Awaiting operator confirmation (alignment or single-job mode)

Offline : Detected as offline (variation of Halted state)

Error : Unrecoverable error detected

The Error state indicates something has prevented the printer from operating correctly.

Common Causes of Error State

Syntax errors in setup files : Malformed commands in .device or form type setup files

Inaccessible device files : Device special file doesn't exist or lacks permissions

I/O errors : Communication problems with printer hardware

Network connection failures : Terminal server or network printer unreachable

Filter command problems : External filter commands fail or produce errors

Exit code issues : Network subprocess returns error exit code

Diagnostic Approach

Step 1: Check System Log

Xi-Text records error details in the system log file:

bash

# View system log
tail -50 /var/spool/spd/spshed_reps

# Or from spq (X command)
# In spq, switch to printer view, press X

Look for messages related to the printer name. Common patterns:

Printer ptr1: Cannot open device /dev/lp0: Permission denied
Printer ptr1: Parse error in /usr/spool/printers/ptr1/a4.ps line 12
Printer ptr1: Network connection failed: Connection refused
Printer ptr1: Filter command exited with code 1

Step 2: Check Printer Configuration

View printer details:

bash

# List printer with full details
splist ptr1

# Check device assignment
splist -F "%D" ptr1

Verify:

• Device path exists and is accessible
• Form type setup files exist
• Device ownership and permissions correct

Step 3: Examine Setup Files

Setup files define how Xi-Text communicates with the printer.

Device file location:

bash

# Main device configuration
ls -l /usr/spool/printers/ptr1/.device

# Form type setup files
ls -l /usr/spool/printers/ptr1/

Check for syntax errors:

bash

# View device file
cat /usr/spool/printers/ptr1/.device

# View default setup
cat /usr/spool/printers/ptr1/default

# View form-specific setup
cat /usr/spool/printers/ptr1/a4.ps

Common syntax errors:

• Missing quotes around strings
• Invalid keyword names
• Malformed escape sequences
• Incorrect file paths in setup commands

Step 4: Test Device Access

Verify the device file is accessible:

bash

# Check device exists
ls -l /dev/lp0

# Test write access (as spooler user)
sudo -u spooler echo "test" > /dev/lp0

Expected: Command succeeds without error

If fails: Check device permissions and ownership

Resolving Common Error Scenarios

Scenario 1: Permission Denied on Device

Symptom:

Printer ptr1: Cannot open device /dev/lp0: Permission denied

Cause: Device file not accessible by spooler user

Solution:

Check device permissions:

bash

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

Ensure spooler user has access:

bash

# Add spooler to lp group
usermod -a -G lp spooler

# Or change device permissions
chmod 666 /dev/lp0  # Less secure but works

# Or change device group
chgrp spooler /dev/lp0
chmod 660 /dev/lp0

Restart printer:

bash

# In spq: halt printer (H), then start (G)
# Or via command line:
sphalt ptr1
spstart ptr1

Scenario 2: Device File Doesn't Exist

Symptom:

Printer ptr1: Cannot open device /dev/lp0: No such file or directory

Cause: Device path incorrect or device not created

Solution:

For parallel printers:

bash

# Check available parallel ports
ls -l /dev/lp*

# If missing, may need to load driver
modprobe lp

For serial printers:

bash

# Check serial devices
ls -l /dev/ttyS*

# Device might be USB serial
ls -l /dev/ttyUSB*

Update device path in printer definition:

bash

# Change device assignment
sqchange -d /dev/ttyS0 ptr1

# Or edit .device file directly
vi /usr/spool/printers/ptr1/.device
# Change: device=...

Scenario 3: Syntax Error in Setup File

Symptom:

Printer ptr1: Parse error in /usr/spool/printers/ptr1/a4.ps line 12: 
   Unexpected keyword 'netwrk'

Cause: Typo or invalid syntax in setup file

Solution:

Edit the setup file:

bash

vi /usr/spool/printers/ptr1/a4.ps

Check line 12 for errors. Common issues:

bash

# Incorrect (typo):
netwrk=<server:9100>

# Correct:
network=<server:9100>

After fixing:

bash

# Test syntax by restarting printer
sphalt ptr1
spstart ptr1

# Check log for errors
tail /var/spool/spd/spshed_reps

Scenario 4: Network Connection Failed

Symptom:

Printer ptr1: Network connection to server:9100 failed: Connection refused

Cause: Network printer or terminal server not responding

Solution:

Test network connectivity:

bash

# Ping print server
ping server

# Test port connectivity
telnet server 9100

If network reachable but port closed:

• Verify printer is powered on
• Check printer IP address correct
• Verify port number (9100 is common for JetDirect, but may vary)
• Check firewall rules on print server

Update network address if changed:

bash

# Edit .device file
vi /usr/spool/printers/ptr1/.device

# Update network= line:
network=<new-server-ip:9100>

Scenario 5: Filter Command Failed

Symptom:

Printer ptr1: Filter command '/usr/local/bin/pdf-filter' exited with code 1

Cause: External filter program encountered error

Solution:

Test filter command manually:

bash

# Test with sample job
echo "test" | /usr/local/bin/pdf-filter

# Check exit code
echo $?
# 0 = success, non-zero = error

Check filter logs/output:

bash

# Run filter with verbose output
echo "test" | /usr/local/bin/pdf-filter -v 2>&1

# Look for error messages

Common filter issues:

• Missing dependencies
• Incorrect permissions
• Invalid arguments in setup file
• Input data format unexpected

Fix or remove filter:

bash

# Edit setup file
vi /usr/spool/printers/ptr1/a4.ps

# Comment out or fix filter line:
# filter='/usr/local/bin/pdf-filter -options'

Recovery Procedures

Basic Recovery Steps

1. Check system log for specific error
2. Fix underlying cause (permissions, syntax, network)
3. Halt printer to clear error state
4. Start printer to reinitialise

bash

# Command line recovery
sphalt ptr1
# Fix issue
spstart ptr1

If Error Persists

Verify spooler daemon running:

bash

ps aux | grep spshed

If not running:

bash

spstart  # Start Xi-Text scheduler

Check IPC resources:

bash

ipcs -a | grep "0x5869"

If stale resources exist, clean up and restart:

bash

sstop -y
# Clean IPC (see IPC Resource Management article)
spstart

Test with minimal configuration:

Create simple test printer:

bash

# Create test directory
mkdir /usr/spool/printers/testptr

# Create minimal .device file
cat > /usr/spool/printers/testptr/.device << 'EOF'
device=/dev/null
EOF

# Create minimal default setup
cat > /usr/spool/printers/testptr/default << 'EOF'
# Minimal setup - no commands
EOF

# Add printer
spadd -p testptr

# Start printer
spstart testptr

If test printer works, compare with problematic printer configuration to identify issue.

Preventing Error States

Validate setup files before deployment:

Test syntax by starting printer after each change.

Monitor system log regularly:

bash

# Check for warnings
grep -i "warning\|error" /var/spool/spd/spshed_reps

Use version control for setup files:

Track changes to printer configurations:

bash

# Initialize git in printers directory
cd /usr/spool/printers
git init
git add .
git commit -m "Initial printer configurations"

Test network connectivity:

Regular checks for network printers:

bash

#!/bin/bash
# check-printers.sh

for printer in ptr1 ptr2 ptr3; do
    HOST=$(grep "network=" /usr/spool/printers/$printer/.device | \
           sed 's/.*<\(.*\):.*/\1/')
    
    if ! ping -c 1 -W 2 "$HOST" >/dev/null 2>&1; then
        echo "WARNING: $printer host $HOST not responding"
    fi
done

Document printer configurations:

Maintain notes on each printer:

• Device type and model
• Network address (if applicable)
• Special configuration requirements
• Common issues and solutions