Initializes a copy of Printer Attribute database variables for a printer formatter.
None (linked with the pioformat formatter driver)
#include <piostruct.h> int piogetvals (attrtable, NULL) struct attrparms attrtable [];
The piogetvals subroutine provides a way for a printer formatter's setup routine to define a list of printer attribute variables (and their characteristics) to the formatter driver. This routine, which is supplied by the formatter driver, allocates storage for the requested variables and uses the Printer Attribute database colon file to arrive at initial values.
The variables defined by the piogetvals subroutine are copies of variables in the database; they are used to hold current values of the variables. After the piogetvals subroutine returns pointers to each of the variables, the characteristics and memory location of each variable is known to both the formatter and the formatter driver. Subsequent changes to printer attribute values (made by the formatter while formatting an input data stream) are made to the newly defined variables, not to the database values. As a result of this scheme, the formatter driver always has access to the current value of each variable, but does not itself ever modify them.
The caller requests variables by filling in entries (an attribute name, its data type, and other characteristics) in the table pointed to by the attrtable parameter. For each entry, the piogetvals subroutine retrieves the requested attribute string in the Printer Attribute database and converts it, if necessary, into an actual value. The piogetvals subroutine then allocates memory for each of the variables, places the initial values there, and stores information about the variable (its name, data type, and memory location) in storage accessible to the piogetopt, piocmdout, and piogetstr subroutines.
A Printer Attribute database is a colon file containing printer attribute values, which can be overridden at the time a print job is requested. These attributes can be constants or may be expressions with unresolved references to other attributes in them. These references are resolved before a database attribute is used to fill in the value of a requested variable.
Database attribute values, which are stored in the database as ASCII strings, have possible data types of string constant (the default), integer variable, or string variable. The requested variables should be either integers or strings. String variables are used primarily for strings that the formatter may need to modify during its processing. NULL characters have no special significance and are permissible within variable strings.
Data types for the requested variables are specified in the array of the attrparms structures pointed to by the attrtable parameter and are not specified at all in the Printer Attribute database. This means that for database values used exclusively by the formatter, only the formatter knows the actual data type of each value. The formatter uses the piogetvals routine in part to inform the formatter driver of the actual data type for database values that are not the default data type.
Converting a database attribute string to an actual value involves two aspects. First, the piogetvals routine resolves any logic and any embedded references to other attribute strings, which yields a resolved string variable. Secondly, the data type of the requested variable must be checked. If this data type specifies a character string, then the resolved string is the final value, and it is stored in the memory allocated for it.
However, if the specified data type is integer variable, then the resolved string is converted to an integer. In this case, the attrtable entry for the attribute string is checked to determine how this conversion is to be performed. Either use the atoi subroutine for this purpose, or provide a pointer to a lookup table. After being converted to an integer, the value is stored in the memory allocated for it.
Using the piogetvals subroutine to convert database strings to integers as specified by the attrtable entries provides a table-driven procedure for the conversions. It also informs the formatter driver which values are integers and how strings that represent the integers can be converted into integer values. The piogetopt, piocmdout, and piogetstr subroutines assume that the formatter has used the piogetvals subroutine to provide this information about the variables to the formatter driver.
When a formatter subsequently calls either the piocmdout subroutine or the piogetstr subroutine to access a string from the database, a global list of variables defined by the piogetvals subroutine is checked by the subroutine to see if the desired string has been defined. If so, then the value of the variable is taken from the memory location specified in the global list. If not, then the Printer Attribute database is consulted for the correct attribute string. Either the piocmdout or piogetstr subroutine scans the string to resolve any logic and any references to other strings or integers. The characteristics and memory locations of the variables, as remembered by the piogetvals subroutine, are used to obtain the current values of the variables.
| attrtable | Points to a table of variables and their characteristics. The table is an array of attrparms structures, as defined in the piostruct.h file. |
Note: The second parameter is reserved for future use. This parameter should be a NULL pointer.
A return value of 0 indicates a successful operation. If the piogetvals subroutine detects an error, it issues an error message and terminates the print job.
The atoi subroutine, piocmdout subroutine, piogetopt subroutine, piogetstr subroutine, the setup subroutine.
Understanding Embedded References in Printer Attribute Strings in AIX Kernel Extensions and Device Support Programming Concepts.
Adding a New Printer Type to Your System in AIX Kernel Extensions and Device Support Programming Concepts.
Example of Print Formatter in AIX General Programming Concepts: Writing and Debugging Programs.