[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Guide to Printers and Printing

Printer Colon File Escape Sequences

Embedded references and logic for attribute values in the printer backend's database colon files are defined with escape sequences placed at appropriate locations in the attribute string. These escape sequences are not to be confused with printer escape sequences. The first character of each escape sequence is always the % (percent sign) character, which indicates the beginning of an escape sequence. The second character (and sometimes subsequent characters) define the operation to be performed. The remainder of the characters (if any) in the escape sequence are operands used to perform the specified operation.

Calculations performed by the escape sequences can use a stack to hold integers or pointers to strings to be operated on and can use internal variables a through z to save integer values for later use.

Since the % character is used to define the beginning of an escape sequence, a % character that is part of the data must be represented in the database as two adjoining % characters (%%). Only one % character appears in the constructed string.

The escape sequences that can be specified in an attribute string are listed and described in the following table. They are based on the terminfo file escape sequences for terminals, which have been modified and extended for printers.

Esc. Seq. Description
%% Generates a % (percent sign) character.
ASCII Output From Stack:
%d Pops an integer value from the stack and converts it to ASCII, without leading zeros. Produces a field width large enough to hold the ASCII numeric digits. Similar to %d with the printf subroutine.
%[1-9]d Pops an integer value from the stack and converts it to ASCII. The result is 1 to 9 characters long, depending on the digit specified before the d. If the value does not fill the specified field width, it is padded on the left with zeros. If the value will not fit in the field, excess high-order digits are discarded. For example, with a value of 243 from the stack, %4d produces 0243 and %2d produces 43. A stack value of -243 would cause %5d to produce -0243.
Binary Output From Stack:
%c Pops an integer value from the stack and discards all but the low-order byte.
%h Pops an integer value from the stack and discards all but the two low-order bytes.
%a Similar to %h, except that the two bytes from the stack are in an alternate order: low-order byte, then high-order byte.
Input String:
%Ixx Includes the string attribute whose name is xx. %I and can be used recursively; that is, the included string can also contain a %I. Note that the included string does not inherit the current stack. Instead, it is assigned a new stack.
%I[ . . . ] If multiple, contiguous includes are to be done, the attribute names can be separated by commas and enclosed with brackets. For example, the string %Icp%Icc%IeW can be specified as %I[cp,cc,eW].
%Dxx Downloads to the printer the contents of the file whose full path name is specified by the xx attribute. The print job must have read access to the file. The primary use of this operator is to download fonts to a printer.
%"sss" Pushes a pointer to the sss string constant onto the stack. The only operation that can be performed on the string pointer is to use %= to compare the string with another string whose pointer is also on the stack.
%`xx Inserts the standard output produced when the command string specified by the xx attribute is passed to a shell. Note that ` is the grave accent character.
%' "String " Passes the quoted string as a command to a sub shell. Any double quotes within the quoted string must be back-quoted to prevent the internal quotes from being read as delimiters for the string. Note that ` is the grave accent character.
Input Integer To Stack:
%#xx"..@.." Extracts a selected portion of the string attribute named xx. The selection criteria is defined by the pattern "...@...". The selection pattern consists of three parts:
  1. The string immediately preceding the string to be extracted. If the prefix regular expression is missing, the extracted string consists of the entire string preceding the pattern specified by the suffix regular expression.
  2. The extracted string replaces the %#xx"..@.." operation sequence in the attribute currently being processed.
  3. The string immediately following the string to be extracted. If the suffix regular expression is missing, the extracted string consists of the entire string following the pattern specified by the prefix regular expression.

No string is extracted if the value of the string attribute is null. No string is extracted if the prefix or suffix regular expression is nonnull and does not have a corresponding match in the attribute value string.

Note: The ampersand (@) and quote ( " ) characters need to be surrounded with a separate pair of quotes if their meaning is to be taken literally. Otherwise, the program reads these symbols as delimiters.

When embedding a %# operator within a regular expression portion of another %# operator, the ampersand ( @ ) and quote ( " ) characters cannot be used for their literal meaning. To avoid this situation, place the embedded %# operator in a separate attribute value and include the new attribute within the regular expression of the outer %# operator.

%Gxx Gets the integer attribute whose name is xx and pushes it onto the stack. If the attribute is a string instead of an integer, the string is assumed to be an ASCII integer. It is converted to a binary integer using the atoi subroutine and pushed onto the stack.
%'c' Pushes character constant c onto the stack, where it becomes the low-order byte of an integer value. The high-order bytes are set to 0 (zero).
%{nn} Pushes integer constant nn onto the stack. The constant is a decimal value and can be either positive or negative.
Internal Variables:

Internal variables a through z are integer variables for use by %P, %Z, and %g. They are initialized to zero and their values change only if a %P or %Z changes them. There are two independent sets of these variables: one set is used by the piobe command for building pipelines, while the other set is used exclusively by a formatter. The values for a formatter's set are maintained for the duration of the formatter's processing.

%P[a-z] Pops an integer value from the stack and stores it in the specified internal variable. For example, %Pf moves an integer value from the stack to variable f.
%Z[a-z] Zeroes the specified internal variable. For example, %Zg stores a value of 0 in variable g.
%g[a-z] Pushes the value of the specified internal variable onto the stack. The value of the internal variable is not changed. For example, %gb reads the integer value in variable b and pushes it onto the stack.
Arithmetic Operators:
%+ %- %* %/ %m Pushes the result onto the stack.
%+ Adds the first two values popped off the stack. For example, %{5}%{6}%+ pushes a value of 11 onto the stack.
%- Subtracts the first value popped off the stack from the second value popped off the stack. For example, %{12}%{3}%- pushes a value of 9 onto the stack.
%* Multiplies the first two values popped off the stack. For example, %{2}%{3}%* pushes a value of 6 onto the stack.
%/ Divides the first value popped off the stack into the second value popped off the stack. For example, %{6}%{2}%/ pushes a value of 3 onto the stack.
%m (modulus) Similar to %/, except that the remainder, instead of the quotient, is pushed onto the stack. For example, %{17}%{9}%m pushes a value of 8 onto the stack.
Note: The first value to be popped off the stack is the last one to be pushed onto the stack, and the second value to be popped off the stack is the one that was pushed onto the stack first.
Relational and Logical Operators:
%= %> %< %! Pushes a value of 1 if true, or 0 if false, onto the stack.
%= Are the first two values that are popped off the stack equal? For example, %{2}%{2}%= pushes a value of 1 (true) onto the stack, and %{2}%{3}%= pushes a value of 0 (false) onto the stack.
%> Is the second value popped off the stack greater than the first value popped off the stack? For example, %{2}%{3}%> pushes a value of 0 (false) onto the stack.
%< Is the second value popped off the stack less than the first value popped off the stack? For example, %{2}%{3}%< pushes a value of 1 (true) onto the stack.
%! Negate
the value popped off the stack and push the result onto the stack:
                         
nonzero value to 0; 0 value to 1. For example, %{0}%! pushes
                         
a value of 1
(true) onto the stack, %{1}%! pushes a value of 0 (false)
                         
onto the stack,
and %{2}%! pushes a value of 0 (false) onto the stack.
                         
Note: The first value to be popped off the stack is the last one to be pushed onto the stack, and the second value to be popped off the stack is the one that was pushed onto the stack first.
Bitwise Logical Operators:
%& %| %^ %~ Pushes the result onto the stack.
%& ANDs the first two values popped off the stack. For example, %{6}%{3}%& pushes a value of 2 onto the stack.
%| ORs the first two values popped off the stack. For example, %{6}%{3}%| pushes a value of 7 onto the stack.
%^ EXCLUSIVE ORs the first two values popped off the stack. For example, %{6}%{3}%^ pushes a value of 5 onto the stack.
%~ ONE'S COMPLEMENTs the first value popped off the stack and inverts the value of each bit. For example, %{-1}%~ pushes a value of 0 (all bits off) onto the stack (assumes two's complement notation for -1).
Conditional (if-then-else) Operators:
%? expr %t thenpart %e elsepart %; %t pops a value off the stack and tests it. If the value is TRUE (nonzero), thenpart is run. Otherwise, elsepart (if present) is run.

else-if construct

%? c1 %t b1 %e c2 %t b2 %e c3 %t b3 %e b4 %;

where c1, c2, c3 denote conditions and b1, b2, b3, b4 denote bodies. For example, %?%{1}%t%{2}%e%{3}%; pushes a value of 2 onto the stack, and %gx%{6}%?%=%t%{2}%e%{3}%;%d outputs a value of 2 if the value of the internal variable x is 6. If value of x is not 6, a value of 3 is output.

When developing complex logic, it is sometimes useful to show it in structured form. The preceding example, in structured form, might look like this:

%gx Pushes the value of x onto the stack
%{6} Pushes a value of 6 onto the stack
%?%=%t If the stack values are equal then
%{2} pushes a value of 2 onto the stack
%e else
%{3} pushes a value of 3 onto the stack
%; endif
%d Outputs
the value in ASCII format
Pass-through:
%x (The piocmdout subroutine call only.) Pass through from input to output the number of bytes specified by the passthru argument to the piocmdout subroutine.
Loops
%wx While loop. Whenever a matching %; is reached, the value of the internal variable x (x can be a through z) is decremented by one. If the result is greater than 0, execution is transferred to the character following %wx.
Mode:
%o Starts using only original default values from the database instead of values that may have been updated from the command line (or during formatter processing).
%r Returns to using the values that were being used before %o.
Pipeline Overrides:
%p Indicates where to embed the prefix-filter pipeline in the main pipeline. If not present, it is assumed to be at the beginning of the main pipeline. Ignored if the first character of the attribute name is not i (that is it is not a main pipeline)
%z Indicates where to embed the pioout string (device-driver interface routine) in the main pipeline. If not present, it is assumed to be at the end of the main pipeline. If the first character of the attribute name is not i (that is, it is not a main pipeline), it is ignored.
%ix Can be specified only in a prefix filter string (that is, the first character of the attribute's two-character name is f). The x variable represents a pipeline identifier character. The %ix variable specifies that the attribute name for the main pipeline should be ix instead of iy, where y is the parameter specified (or defaulted) for the -d flag. As a special case %i! specifies that a null string should be used as the main pipeline.
Command Line Flags:

These operators are usually used in pipeline definitions, where they apply to flags specified by the print job submitter. If specified in attribute strings used by a formatter, they apply to the flags passed to the formatter. Valid flag letters are a through z, A through Z, and 0 through 9.

%Cy Pushes a value of 1 (true) onto the stack if flag y was specified on the command line. Otherwise, pushes a value of 0 (false) onto the stack.
%Fxy or %F[...] Shorthand for %?%Cy%t-x %I_y%;. If the y flag was specified on the command line, generates -x yarg, where yarg is the argument specified for the y flag. If ! is specified for x, -x will not be generated. If yarg contains an unprotected (not immediately preceded by an odd number of back slashes) single or double quote, an error message will be issued and the print job terminated.

If multiple flags are to be specified using %Fxy, and each flag's x and y values are identical, a list of flag letters can be specified in brackets. For example, %Faa%Fbb%Fcc can be specified as %F[abc].

The values referenced by y or [ . . . ] have attribute names whose first character is _ (underscore) and whose second character is y or a character in the string [ . . . ].

%fxy or %f[ . . . ]
                          Similar to %Fxy and %F[ . . . ], except that no space is placed between the flag name and the argument, unless the argument is a null string.
%vxy or %v[...] Similar to %fxy and %f[ . . . ], but used only in the command string for the pioout command, the Device Driver Interface Program, to generate flags and arguments for override values specified by the piobe command, the Print Job Manager. Flags are not generated when their arguments are equal to predefined default values.

With %v, the values referenced by y or [ . . . ] have attribute names whose first character is @ (at sign) and whose second character is y or a character in the string [ . . . ].

%Ux
or %U[ . . . ]
                          Indicates to the
piobe command that the x flag (or each flag in the string [ . . .]) is actually referenced even though it is not referenced by a pipeline; for example, the x flag may be referenced by a printer command instead of by a filter in a pipeline. This prevents the piobe command from rejecting the flag when specified on the command line.
                         
[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]