Technical Reference: Kernel and Subsystems, Volume 2

setup Subroutine

Purpose

Performs setup processing for the print formatter.

Library

None (provided by the formatter).

Syntax

#include <piostruct.h>
struct shar_vars *setup (argc, argv, passthru)
unsigned argc;
char * argv [ ];
int passthru;

Description

The setup subroutine performs the following tasks:

Invokes the piogetvals subroutine to initialize the database variables that the formatter uses.
Processes the command line flags using the piogetopt subroutine.
Validates the input parameters from the database and the command line.

The setup subroutine should not send commands or data to the printer since the formatter driver performs additional error checking when the setup subroutine returns.

Parameters

argc	Specifies the number of formatting arguments from the command line (including the command name).
argv	Points to a list of pointers to the formatting arguments.
passthru	Indicates whether the input data stream should be formatted (the passthru value is 0) or passed through without modification (the passthru value is1). The value for this parameter is the argument value for the -# flag specified to the pioformat formatter driver. If the -# flag is not specified, the passthru value is 0.

Return Values

Upon successful completion, the setup subroutine returns one of the following pointers:

A pointer to a shar_vars structure that contains pointers to initialized vertical spacing variables. These variables are shared with the formatter driver, which provides vertical page movement.
A null pointer, which indicates that the formatter handles its own vertical page movement or that the input data stream is to be passed through without modification. Vertical page movement includes top and bottom margins, new pages, initial pages to be skipped, and progress reports to the qdaemon daemon.

Returning a pointer to a shar_vars structure causes the formatter driver to invoke the formatter's lineout function for each line to be printed. Returning a null pointer causes the formatter driver to invoke the formatter's passthru function once instead.

If the setup subroutine detects an error, it uses the piomsgout subroutine to issue an error message. The setup subroutine then invokes the pioexit subroutine with a value of PIOEXITBAD. Note that if the piogetvals, piogetopt, piocmdout, or piogetstr subroutine detects an error, it automatically issues its own error message and terminates the print job.

Related Information

The piocmdout subroutine, pioexit subroutine, piogetopt subroutine, piogetstr subroutine, piogetvals subroutine, piomsgout subroutine.

The qdaemon daemon.

Understanding Embedded References in Printer Attribute Strings in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

Adding a New Printer Type to Your System in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

Example of Print Formatter in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.