Adding Support for Configuring a Network-Attached Printer

Guide to Printers and Printing

Adding Support for Configuring a Network-Attached Printer

Note: The information in this article is provided for backward compatibility only. The preferred method for adding new printer attachment definitions is through attachment files. For more information, see "Printer Attachment Files" .

The following article discusses the information you need to add support for configuring a network-attached printer. This information is not necessary to configure a network-attached printer. It shows how support can be added to allow users to configure a non-supported device that is to be attached to a network and drive one or more printers.

Overview of Adding Support for Configuring Network-Attached Printers

Network-attached printers are printer devices that are not directly attached to the host computer, but are driven by the host over the network. For example, a printer attached to an Xstation is a network-attached printer. To configure a network-attached printer with the mkvirprt command, you need a device configuration file.

A device configuration file extends the capability of the mkvirprt command for network-attached printers. Specifically, a device configuration file can support six different types of statements to create a dialog of menus and prompts. This dialog starts when you use the mkvirprt command; you respond to the menus and prompts. The mkvirprt command uses the information you enter to create a stanza in the /etc/qconfig file that is customized for the device being configured. The device configuration file controls the queue device name, backend = statement, and the file = statement in the /etc/qconfig stanza.

Naming a Device Configuration File

The device configuration file must have the filename extension .config and must be located in the /usr/lib/lpd/pio/etc directory.

Statement Types Available in a Device Configuration File

Six different types of statements provide various capabilities for the dialog created in the device configuration file:

M	Menu header for list of menu choices
m	Menu choice
l	Menu choice list
V	Prompt user for value
v	Validation pipeline for entered value and error message
T	Text to be placed in a variable or in a backend = statement.

Each statement consists of the following 10 fields: type, label, gotolabel, reserved1, text, variable, reserved2, pipeline, msgid, and defmsg. The following matrix shows the statement types, and the fields they support. An x (ex) indicates that the statement supports the field. A - (minus sign) indicates that the statement does not support the field.

Device Configuration File Statement Types
Stmt	type	label	gotolabel	text	variable	pipeline	msgid	defmsg
M	X	X	X	X	X	-	X	X
m	X	-	X	X	-	-	X	X
l	X	-	-	-	-	X	-	-
V	X	X	X	X	X	-	X	X
v	X	-	-	-	-	X	X	X
T	X	X	X	X	X	-	-	-

Note: The reserved1 and reserved2 fields are for future use, but are not currently active and are not shown in table above (see "Description of Statement Fields" ).

Statement Format for a Device Configuration File

Statements are constructed by separating each field with a colon, as in the following format:

type:
label:
gotolabel:
reserved1:
text:
variable:
reserved2:
pipeline:
msgid:
defmsg

The specific statement formats are as follows:

Statement	Format
M	`M:label:gotolabel::text:variable:::msgid:defmsg`
m	`m::gotolabel::text::::msgid:defmsg`
l	`l:::::::pipeline::`
V	`V:label:gotolabel::text:variable:::msgid:defmsg`
v	`v:::::::pipeline:msgid:defmsg`
T	`T:label:gotolabel::text:variable::::`

Description of Statement Fields

type

Identifies the type of statement.

label

Specifies the label that identifies this statement.

gotolabel

Specifies the label of the statement to branch to after executing this statement.

For M statements, specifies the label of the statement to go to for m statements that do not have a gotolabel. If the gotolabel field is null, fall through.
For m statements, if the gotolabel field is null, branch to the gotolabel field of the M statement.
For V statements, if the gotolabel field is null, fall through.
For T statements, if the gotolabel field is null, fall through.

reserved1

Reserved for future use.

text

Specifies a string of text. How the text is used depends on the statement type.

For M statements, specifies that the text be placed in the backend = statement.
For m statements, specifies the text to be placed in the backend = statement if the corresponding M statement contains a null string in the variable field.
For V statements, specifies that the text be placed in the backend = statement.
For T statements, specifies the text to be used by the variable field.

The text field has the special capability to execute shell commands and insert the resulting standard output (stdout) into the text string. Any text between a pair of back quote characters is executed as a shell command. The stdout resulting from the shell is inserted where the back-quoted text was.

For example, suppose the environment variable HOME were equal to /home/guest. If the text field was /tmp`echo $HOME`/file, the resulting text would be /tmp/home/guest/file.

Note: Inside the back-quoted text \` (backslash, single back-quote) represents the back-quote character and \ \ (backslash, backslash) represents the backslash character.

Variable

Indicates the name of the variable in which to store data. This field can have multiple variables separated by commas. If null, place the data in the backend = statement. The data to be stored depends on the statement type:

For M statements, the data stored is the selection value.
For V statements, the data stored is the entered value.
For T statements, the data stored is the text field.

The environment variable used to store the data consists of the string PIO prepended to the variable name. For example, if the variable field was: var1, The environment variable name would be PIOvar1.

There are two special cases of variable names:

dname	In addition to the data being stored in the PIOdname environment variable, it is also used as the queue device name in the /etc/qconfig file.
fname	In addition to the data being stored in the PIOfname environment variable, it is also used as the value for the file= statement in the /etc/qconfig file.

reserved2

Reserved for future use.

pipeline

Specifies a shell command to execute. Specifically:

For l statements, specifies the shell command to run. The output of the command is constructed into a menu.
For v statements, specifies the shell command executed to validate the values entered. A 0 (zero) return code indicates that the entered value is valid.

msgid

Specifies the message to be used by this statement. The field consists of the message catalog name (CatalogName), set number (SetNumber), and message number (MessageNumber), separated by commas. The message catalog name and set number only need to be specified on the first statement; null strings can be used for subsequent statements.

defmsg

Specifies the default message text to be used if a message cannot be found in the message catalog.

Comments in a Device Configuration File

A line with a # (pound sign) character in the first column will be ignored, allowing comment lines in the config line.

First Statement in a Device Configuration File

The first statement in the device configuration file must be the m (menu choice) statement type. This statement specifies the menu choice displayed by the mkvirprt command when prompting the user for the device they wish to configure.

If the message catalog name and set number are specified in this statement, null strings can be used for the catalog name and catalog set in subsequent statements.

Setting Up Menus and Prompts in a Device Configuration File

When configuring network-attached printers, you may want to customize specific types of information. To handle this, you can set up menus and prompts in the device configuration file.

Menus

Menus can be constructed in two ways:

Using one M statement in combination with one or more m statements.
Using one M statement in combination with one l statement.

The M statement identifies the beginning of a menu and specifies text for the menu header, which is displayed above the menu choices.

Each m statement specifies a different item under the menu.

The l statement specifies a shell command to be executed. The stdout from the shell command is constructed into a menu. In the construction of the menu the \n (newline) character is the delimiter for menu items. For example, the shell command:

echo Choice1\\nChoice2\\nChoice3

is constructed into the menu as:

1	Choice1
2	Choice2
3	Choice3

Prompts

Prompts can be constructed using the V statement plus one or more v statements to validate the response. After the V statement is executed, the user's response is stored in an environment variable. The v statement can then be used to execute a shell command to validate the response. A 0 (zero) return code from the shell indicates no errors. A non-zero return code means an error was found; the specified message is displayed, and the user is prompted again for the input value.

Example of a Device Configuration File

Refer to the /usr/lib/lpd/pio/etc/xsta.config file as an example of a device configuration file. This is the file used to support Xstation configuration.