piogetattrs Subroutine

Purpose

Retrieves printer attribute values, descriptions, and limits from a printer attribute database.

Library

libqb.a

Syntax

#include <piostruct.h> int piogetattrs(QueueName, QueueDeviceName, NumAttrElems, AttrElemTable) const char * QueueName, * QueueDeviceName; unsigned short NumAttrElems; struct pioattr * AttrElemTable;

Description

The piogetattrs subroutine retrieves printer attribute values and their associated descriptions and limits from a printer attribute database. Any logic (using the % escape sequence character) within the attribute description will be returned as a text string obtained from a message catalog, and will be in the language determined by the NLSPATH and LANG environment variables.

Information can be retrieved for any number of attributes defined in the printer attribute database, and for any combination of attribute value, attribute description, and attribute limit for each of the attributes with one piogetattrs subroutine call.

The combination of the QueueName and QueueDeviceName parameters identify a specific printer attribute database. Therefore, the QueueName and QueueDeviceName parameters must be unique for a particular host.

Parameters

Item Description
QueueName Specifies the print queue name. The print queue does not have to exist.
QueueDeviceName Specifies the queue device name for the print queue name specified by the QueueName parameter. The queue device does not have to exist.
NumAttrElems Specifies the number of attribute elements in the table specified by the AttrElemTable parameter.
AttrElemTable Points to a table of attribute element structures. Each structure element in the table specifies an attribute name, the type of value to be returned for the attribute, fields where the location and length of the returned value are to be stored, and a field for the return code of the retrieval operation. Memory is allocated for each resolved value that is returned, and the memory location and length are returned in the structure element. The format of each structure element is defined by the pioattr structure definition in the /usr/include/piostruct.h file.

Return Values

Item Description
NumAttrElems Specifies the number of attribute elements for which the piogetattrs subroutine has successfully retrieved the requested information.
-1 Indicates that an error occurred.

Examples

/* Array of elements to be passed to 
piogetattrs() */
#define ATTR_ARRAY_NO (sizeof(attr_table)/sizeof(attr_table[0]))
   
struct pioattr attr_table[] = {
        {"_b", PA_AVALT, NULL, 0, 0}, /* attribute record      */
                                      /* for _b (bottom margin)*/
        {"_i", PA_AVALT, NULL, 0, 0}, /* attribute record for  */
                                      /* _i (left indentation) */
        {"_t", PA_AVALT, NULL, 0, 0}, /* attribute record for  */
                                      /* _t (top margin)       */
}
   
...
const char                       *qnm = "ps";
const char                       *qdnm = "lp0";
int                              retno;
register const pioattr_t         *pap;
   
...
if((retno = piogetattrs(qnm,qdnm,ATTR_ARRAY_NO,attr_table)) ==-1)          {(void) 
fprintf(stderr,"Fatal error in piogetattrs()\n");
...
}
else if (retno != ATTR_ARRAY_NO) _{
        (void) printf("Warning! Infor was not retrieved for all \
        the attributes.\n");
}
for(pap = attr_table; pap<attr_table+ATTR_ARRAY_NO;pap++)
        if(pap->pa_retcode) /* If info was successfully */
                            /* retrieved for this attr  */
...