Managing Xi-Text Printer States and Operations

The Eight Printer States

Every Xi-Text printer exists in one of eight states. Understanding these states is essential for effective printer management.

The state names below are the words the product itself prints, in lower case, in the state column of splist and in the printer section of spq:

halted   startup   idle   printing   a/w oper   shutdown   offline   error

To see the current state of every printer:

splist

ptr1  <lp0>     a4.ps  idle
ptr2  <srv:910> letter printing  15033 jsmith
ptr3  <lp1>     a4     halted
ptr4  <lp2>     labels offline

The default listing is printer name, device, form type, state, job number and job owner; the last two columns are filled only while the printer is printing.

Halted

Initial state when printer is added or explicitly stopped.

Characteristics:

• No jobs will be sent to this printer
• Required state for changing form type
• Required state for most configuration changes

How to enter: Press h (halt at the end of the current job) or H (halt at once) in spq, or run sphalt [printer] or spstop [printer]

Purpose: Safe state for maintenance, configuration, or paper changes

Also: every printer is halted whenever the spooler itself starts. The scheduler reads the saved printer list and sets every entry to halted regardless of the state it was in when the spooler was stopped, so printers have to be started again after a restart.

Startup

Transitional state during printer initialisation.

Characteristics:

• Setup files are being read, by a separate spdinit process
• The device is opened
• The setup string and the suffix start string are sent to the device

How to enter: Automatically when starting a halted printer, and again mid-run whenever a selected job needs a different form type from the one loaded

If it stays here: a fault in the setup files or the device moves the printer to error rather than leaving it in startup. A printer that sits in startup is blocked writing the setup string to the device - commonly flow control, where the printer has sent XOFF and never sends XON. Press H a second time to force it out.

Idle

Printer is ready and waiting for jobs.

Characteristics:

• Printer initialised successfully
• Waiting for job with matching form type
• Will print next suitable job immediately

How to enter: Automatically after successful startup, and after each job finishes

Indicators:

• Form type displayed
• (N/A) marker if alignment is required for the next job

Printing

Actively printing a job.

Characteristics:

• Job number and owner displayed
• Job data being sent to printer
• Can be interrupted or aborted

How to enter: Automatically when job selected

Duration: Depends on job size and printer speed

a/w oper (Awaiting Operator)

Printer paused, waiting for operator approval.

Characteristics:

• Two scenarios trigger this:
  1. An alignment page has just been printed, because the form type in use has an alignment file and the (N/A) marker was set
  2. Single-job mode (operator must approve each job)

Both are reached from printing, never directly from startup: the printer takes a job first, and pauses part-way through starting it.

Actions available:

• Press y to approve and continue, or run spok [printer]
• Press n to reject, or run spnok [printer]. For an alignment page this prints another alignment page; in single-job mode it continues, the same as y
• Press A to abort the job, which discards it and returns the printer to idle

How to exit: Operator approval, aborting the job, or halting the printer

Privilege: y and n, and spok and spnok, need the Select printer list permission, which is part of the default user privilege set. This is a different permission from the one that starts and stops printers.

Shutdown

Transitional state during printer stop.

Characteristics:

• Printer sending the suffix end string and then the halt string
• Any filter process is closed down
• The device is closed

How to enter: Automatically when halting printer

Purpose: Allows graceful printer reset before halting

If it stays here: a long docend, sufend or halt string takes as long as the device accepts it, and a printer taken off line mid-string may hold the port with XOFF. Press H again to force the shutdown through; the filter process group is then killed with SIGTERM.

Offline

Printer detected as not ready.

Characteristics:

• The printer stops, as a halt does, but the state records why
• Triggered by the device signalling hangup, or by the device open or write timing out
• A network or terminal-server filter can also report it, by exiting with a status listed in the setup file's offline directive
• Where the filter supplies a reason, it is shown after the state, as offline:Out of paper

How to enter: Automatically when the device or the filter reports an offline condition

Recovery:

1. Fix hardware issue (power, cable, paper)
2. Start the printer again - spstart [printer], or G in spq

Error

The printer stopped because Xi-Text could not carry on.

Characteristics:

• Printer cannot operate
• Detailed message in the system log
• Recovered by fixing the cause and starting the printer again, in the same way as offline. The state records that something needs attention rather than that the printer is beyond recovery

Common causes:

• Syntax error in the setup files, which makes spdinit exit non-zero
• No setup directory or no setup file for the form type
• The device cannot be opened
• The device is neither a character device nor a FIFO - pointing a printer at an ordinary file gives "Invalid device name"
• A network device with no network filter defined in the setup file, or a network filter defined for a device that is not a network device
• The network filter crashed, dumped core, or was lost

Recovery:

1. Check the system log: tail -20 /var/spool/xi/spd/spshed_reps
2. Fix underlying issue
3. Start the printer again

State Transitions

halted --spstart / G--> startup --setup ok--> idle
                            |
                            +--setup or device fault--> error
                            +--setup string interrupted--> halted

idle --job selected--> printing
printing --form type differs--> startup --> printing
printing --alignment required--> a/w oper --y--> printing
                                          --n--> a/w oper (page reprinted)
printing --single-job mode--> a/w oper --y or n--> printing
printing --job done, aborted or interrupted--> idle

idle, printing or a/w oper --sphalt / h--> shutdown --> halted
any running state --spstop / H--> shutdown --> halted
any running state --device hangup or timeout--> offline
any running state --setup, device or filter fault--> error

any state --spooler restarted--> halted

halted, offline and error are the three states in which the printer holds no process and takes no jobs; spstart treats all three alike and starts the printer from any of them.

Starting Printers

From spq

1. Press o to switch to printer section
2. Navigate to printer with cursor keys
3. Press G (Go/start)

Start spq with -p to open on the printer section, and with -P n to give that section n lines so every printer is visible at once. The printer section appears only for a user who holds the Select printer list permission; without it, o does nothing and the printer keys below are unavailable.

From Command Line

The printer name is a shell-style pattern. When it matches more than one printer you must add -f, or the command refuses with "Printers match … ".

# Start specific printer
spstart ptr1

# Start all printers
spstart -f '*'

# Start printer, loading a different form type first
spstart ptr1 a4.ps

The form type is the second argument, with no option letter. If the printer is already running with a different paper type - the form type up to its suffix - spstart halts it at the end of the current job, waits, changes the form type and starts it again, so the halt-change-start sequence does not have to be typed out.

Give spstart a first argument that begins with a digit, or no argument at all, and it starts the spooler instead of a printer. That is what the packaged service does, as spstart 2000 50.

Privilege: spstart, sphalt, spstop and spinter need the Halt/restart printers permission, which is part of the default user privilege set - starting and stopping printers is an ordinary user action unless the permission has been withdrawn.

What Happens at Startup

1. Printer enters startup state
2. A spdinit process is run for the printer and the current form type. It changes to the printers directory, then to the directory named after the printer, and reads the first of these that it finds: .device, then the file named after the form type, then the configured default form file
3. The device is opened, and checked to be a character device or a FIFO
4. The port setup string is sent, if one is defined
5. The setup string and the suffix start string are sent to the printer
6. If the form type has an alignment file, the printer is marked as needing alignment and the (N/A) marker appears
7. Printer enters idle state

Any failure in steps 2 to 4 moves the printer to error. A failure in step 5 returns it to halted. Neither prints anything on the terminal that issued spstart, because the printer is started by the spooler rather than by that command - the reason is written to spshed_reps in the spool directory, and that is the only place it appears. Start a printer and it goes idle, and read the log if it does anything else.

Alignment Page Handling

If an alignment file is configured for the form type:

When the printer takes its first job:

1. The (N/A) (not aligned) marker is set at startup
2. The printer takes the job and enters printing
3. The alignment page prints
4. Printer enters a/w oper state

Operator actions:

• Press y, or run spok - Approve alignment, clear the marker, print the job
• Press n, or run spnok - Reject alignment, print another alignment page
• Halt printer - Abandon alignment, return to halted state

If no jobs are waiting: the printer stays idle with the (N/A) marker showing, and the alignment page prints when a job arrives.

Mid-run: changing form type re-arms alignment. When a selected job needs a different form type, the printer goes back through startup, the marker is set again from the new form type's setup file, and the alignment page prints before that job. A printer that stops for the operator in the middle of the working day has usually just changed form type.

Stopping Printers

Graceful Stop (End of Current Job)

# In spq
Press 'h' on printer

# Command line
sphalt ptr1

Behaviour:

• If printing: finishes current job, then halts
• If idle or awaiting the operator: halts immediately
• Printer enters shutdown state
• The suffix end string and then the halt string are sent to the printer
• Printer enters halted state

Marker: while the printer is waiting for the job to finish, its line is marked (heoj). Pressing G, or running spstart, before it stops cancels the halt and leaves the printer running.

Immediate Stop

# In spq
Press 'H' on printer

# Command line
spstop ptr1

Behaviour:

• Stops immediately, even mid-job
• The abort string is sent, or the message ***ABORTED*** is printed if no abort string is defined
• Current job remains in queue, and the page it reached is recorded so it resumes there
• Use when printer needs immediate attention

Marker: the printer's line is marked AB!! while the stop is in progress.

Managing Running Jobs

Interrupt Current Job

# In spq
Press '!' on printer

# Command line
spinter ptr1

What happens:

• Current job stops, as an immediate halt does, and the printer starts again at once - the interrupt is a stop and a start in one command
• The page reached is recorded, less any windback pages set in the setup file
• The job returns to the queue and keeps its place in priority order. If a higher priority job is now waiting, that job prints and the interrupted one waits its turn
• When the interrupted job is selected again it resumes from the recorded page rather than from the beginning
• Useful for pushing a short urgent job past a long one

Note: Limited effectiveness if printer has large buffer - buffered data may still print. The recorded page is where Xi-Text stopped sending, which is ahead of what the printer has put on paper.

Abort Current Job

# In spq
Press 'A' on printer

# Command line
sqdel [job-number]

What happens:

• Current job stopped
• Job deleted from queue permanently
• abort string sent to printer
• Next job selected

A in spq aborts whatever the printer is currently printing; sqdel names a job and works whether or not it is printing.

Restart Current Job

# In spq
Press 'r' on printer

What happens:

• Current job stopped
• Job restarted from beginning
• restart string sent to printer, or the message ***RESTARTED*** and a page throw if none is configured

Note: Limited effectiveness if printer has large buffer. There is no command-line equivalent of r.

Changing Printer Configuration

Every change in this section, apart from the form type, needs the Add/delete printers permission, which is outside the default user privilege set. The form type needs no special permission.

Change Form Type

⚠️ In spq the printer must be halted

# In spq
1. Halt printer (H)
2. Press 'f' on halted printer
3. Enter new form type
4. Press '?' to see the form types set up for this printer

# Command line - halts, changes and restarts in one operation
spstart ptr1 letter.ps

Steps:

1. Halt printer
2. Physically change paper (if needed)
3. Update form type in Xi-Text
4. Start printer

From the command line spstart does the halting and restarting itself, so only the paper change is manual. spchange sets the form type on a printer that is already halted and leaves it halted.

Change Printer Name

⚠️ Printer must be halted

# In spq
Press 'P' on halted printer

Changes which setup file directory is used:

• Old name: /var/spool/xi/printers/old-name/
• New name: /var/spool/xi/printers/new-name/

The printers directory is a compiled-in default and a custom build may put it elsewhere; the setting is sprindir in /etc/xi/textconfig.

Change Device/Port

⚠️ Printer must be halted

# In spq
Press 'V' on halted printer

# Command line
spchange -v /dev/ttyS1 ptr1

Changes device file or network address:

• Local: /dev/lp0, /dev/ttyS0 - must be a character device
• Network: <printer01> (angle brackets). The angle brackets are how spq shows and accepts a network device, and a network device requires a network filter in the setup file
• FIFO: /tmp/printfifo - a named pipe is accepted as well as a character device

Change Description

⚠️ Printer must be halted

# In spq
Press 'c' on halted printer

# Command line
spchange -D "Accounts department LaserJet" ptr1

Updates human-readable description, does not affect operation.

Adding and Removing Printers

Both need the Add/delete printers permission.

Add Printer

# In spq
Press 'N' in printer section

# Prompts for:
# - Printer name (cycles through available directories)
# - Device/port (cycles through unused /dev entries)
# - Form type (cycles through setup files)
# - Description

# Command line
spadd -l ttyS0 ptr1 a4.ps

# Interactive script, which also creates the setup files
Ptrinstall

spadd requires -l to name the device; without it the command refuses with "When adding a printer you must specify the device name". Adding a printer through spq or spadd registers it with the spooler and leaves the setup files to be created separately, which is what Ptrinstall is for.

Delete Printer

⚠️ Printer must be halted

# In spq
Press 'D' on halted printer

# Command line
spdel ptr1

Removes printer from Xi-Text list. Does not delete setup files. spdel deletes one printer at a time and refuses a pattern that matches several.

Single-Job Mode

For manual feed or special handling:

# In setup file
single

Behaviour:

• Take a job and print its banner
• Enter a/w oper state
• Wait for operator approval
• Print the job
• Repeat for the next job

In single-job mode both y and n release the job; only the alignment case treats them differently.

Use cases:

• Manual feed envelopes
• Special forms requiring verification
• Testing new configurations

Alignment Page Management

When Alignment is Required

Alignment pages are configured in setup files:

# In setup file
align=.setpage    # File containing alignment pattern

Use execalign in place of align to run the named file as a program rather than copy its contents to the printer. Either way, spdinit checks the file when the printer starts - align needs it readable, execalign needs it executable, by the system user - and a file it cannot use puts the printer into error rather than skipping the alignment.

Managing Alignment State

Approve alignment (when N/A showing):

# In spq
Press 'y' on printer in a/w oper state

# Asks for confirmation if idle

Reject alignment and reprint:

# In spq
Press 'n' on printer in a/w oper state

Clear alignment requirement:

# When printer is Idle
Press 'y' (confirms, clears N/A marker)

Reinstate alignment requirement:

# When printer is Idle
Press 'n' (confirms, adds N/A marker back)

spok and spnok do all four of these - approve, reject, clear and reinstate - according to the printer's state, and without asking for confirmation. On a halted printer they do nothing at all.

Load Limits

Control which printers can handle large jobs:

⚠️ Printer must be halted

# In spq
Press 'L'    # Set lower limit (minimum job size)
Press 'U'    # Set upper limit (maximum job size)

Both limits are in bytes, and are the size of the whole job, disregarding any page range or odd/even selection. Zero means no limit. A printer with a lower limit shows < after its state, and one with an upper limit shows >. Setting them needs the Halt/restart printers permission, and there is no command-line equivalent.

Use cases:

• Reserve fast printers for large jobs
• Route small jobs to slower printers
• Prevent huge jobs tying up certain printers

Class Codes

Control printer access by user groups:

⚠️ Printer must be halted

# In spq
Press 'C' to change class code

# Command line
spchange -S 000f ptr1

A job is only selected for a printer where:

job_class_code & printer_class_code != 0

The job's class code comes from the class code of the user who submitted it, so in practice this routes users to printers. Changing a printer's class code needs the Add/delete printers permission.

Monitoring Printer Activity

View System Log

# In spq
Press 'X'

# Command line
tail -50 /var/spool/xi/spd/spshed_reps

Shows:

• Printer start/stop events
• Errors and warnings
• File access issues
• Setup file problems

This is the only place a startup failure is reported. The spool directory is a compiled-in default; the setting is spooldir in /etc/xi/textconfig.

Printer Status Display

# In spq, printer section shows:
# - Current state
# - Form type
# - Device/port
# - Description
# - Current job (if printing)
# - Status messages

For a listing rather than a screen, use splist. Its state field carries any message the printer reported, as offline:Out of paper, and the (heoj), AB!!, (N/A), < and > markers appear in their own fields.

Testing a Printer's State From a Script

# True (exit 0) if the printer is running at all
spstat ptr1

# True if the printer is in the named state
spstat ptr1 idle
spstat ptr1 'a/w oper'

spstat reports through its exit status - 0 for true, 1 for false - and prints nothing. "Running" means any of startup, idle, printing, a/w oper or shutdown. It names exactly one printer and refuses a pattern that matches more than one. Spaces are removed from both the state name and the argument before they are compared, so a/w oper and a/woper both match, and the state name may itself be a pattern.

A script that has to wait for a printer to finish what it is doing polls that exit status:

#!/bin/sh
# wait-for-idle.sh

PRINTER=$1

while ! spstat $PRINTER idle
do
    echo "Waiting for $PRINTER to become idle..."
    sleep 5
done

echo "$PRINTER is now idle"

A printer that has gone offline or into error is never idle, so a loop like this waits for ever on a fault. Test for the stopped states as well if it is to run unattended.

To watch every printer rather than test one, poll splist. watch is a Linux utility and is absent on the commercial Unix platforms the product also ships on, so a loop is the portable form; inside spq, -R sets the refresh interval instead.

while true
do
    splist
    sleep 2
    clear
done

Best Practices

Before Changing Configuration

1. Halt printer gracefully
2. Wait for current job to complete
3. Make changes
4. Test with small job
5. Monitor for errors

Regular Maintenance

1. Check system log periodically
2. Verify printers in expected states - an idle printer is working normally and needs no attention, so look for offline, error and unexpectedly halted
3. Start every printer again after the spooler has been restarted, since a restart halts them all
4. Test after any system changes

Emergency Procedures

1. Immediate halt if printer misbehaving
2. Check system log first
3. Fix issue
4. Test before returning to service

Troubleshooting

Printer Goes Straight to Error

spstart itself reports nothing, because the printer is started by the spooler. The reason is in spshed_reps.

Check:

1. A setup file exists for the form type - a directory named after the printer under the printers directory, holding .device or a file named after the form type or the default form file
2. The device exists, is a character device or a FIFO, and can be opened by the system user
3. A network device (angle brackets) has a network filter in its setup file, and a filter is defined only for a network device
4. Any align, execalign, record or log file named in the setup file is readable, or executable, by the system user
5. System log for the specific error

Printer Stays in Startup or Shutdown

Indicates:

• A write to the device is blocked - most often flow control, where the printer sent XOFF and has not sent XON
• A long setup, docend, sufend or halt string still going out

Action: Press H again, or run spstop, to force it. Take the printer off line after it has halted rather than before, so the port is not left holding an unfinished string.

Jobs Not Printing from Idle Printer

Check:

1. Form type matches job form type, comparing only the paper type - the form type up to its suffix
2. Alignment required ((N/A) marker) - the alignment page prints before the job
3. Class code compatibility - the job's class code and the printer's must share a bit
4. Job size within limits, in bytes, for the whole job
5. The job has a hold time still in the future
6. The job has already been assigned to another printer
7. Scheduling is suspended - ssuspend stops jobs being allocated to any printer until it expires or srelease is run

Related Articles

• Xi-Text Printer Setup Files: What They Contain and When They Are Read - Configuration details
• Configuring Xi-Text Form Types, Paper Types and Suffixes - Form type management
• Diagnosing and Clearing the Xi-Text Printer error State - Error recovery
• Distinguishing the Xi-Text offline State From error - Telling the two apart
• Stopping and Starting All Xi-Text Printers at Once - Bulk operations
• Xi-Text File Permissions and Ownership - Who must own the setup files and devices

Documentation Reference

For complete printer operation details, see:

• Xi-Text Reference Manual, Chapter: Text screen-based Programs (the spq section)
• Xi-Text Reference Manual, Chapter: Printer Definitions (setup file keywords)
• Xi-Text Reference Manual, User Programs: Spstart, Sphalt, Spok, Spinter, Spchange, Spadd, Spstat, Sstop, Ssuspend, Srelease
• Xi-Text Administration Guide, Chapter: Defining and Installing Printers