Message Format

Edit online

Each message sent by the printer backend consists of a message header frame, zero or more parameter header frames, a fully expanded message, and text consisting of zero or more parameters.

The message header specifies the message type, message catalog information, length of expanded message text, and the number of variable message parameters. The variable message parameters are used to build the expanded message text from the basic message text that is extracted from the message catalog. The structure formats for the message header and the message parameter header frames are defined in the /usr/include/piostruct.h file.

When extracting messages from the pipe, the print supervisor reads the message header frame, then reads the message parameter header frames (0-9, as specified by the number of parameters specified in the message header frame). The print supervisor reads the expanded message text, the length of which is specified in the message header frame, followed by the parameters (if any). The type and length of any parameters are specified in the individual message parameter header frames.

The type of message is specified in the message header frame. The message types are as follows:

  • ID_VAL_EVENT_ABORTED_BY_SERVER
  • ID_VAL_EVENT_WARNING_RESOURCE_NEEDS_ATTENTION

The actual message text is in expanded format. The parameters are placed in the message text after the parameters are extracted from the message catalog file in the server's locale. The print supervisor can use the message text or build its own message text from the supplied message catalog information and the message parameters. However, the printer backend cannot provide message catalog information (message number, set number, and catalog name) and variable message parameters in all cases. Therefore, the print supervisor must check for the catalog name field (pm_catnm field) to determine if the catalog name is a null string. If the catalog name is a null string, the print supervisor must use the supplied expanded message text.

If a catalog name is provided, the print supervisor can extract the message from the catalog and place any supplied message parameters in the message. The message parameters can be integer or string type. However, message parameters are passed from the printer backend as strings concatenated to the expanded message text. If the print supervisor extracts the message from the specified catalog and places the parameters in the message, the following conventions apply:

  • Parameters can be integer or string type, but are always passed in the pipe as strings with a trailing NUL character. The length of each parameter in string format is supplied in the parameter's associated header frame.
  • Extracted messages can contain escape sequences recognized by the printf subroutine. Therefore, while populating the message, the print supervisor checks for escape sequences such as %s, %d, and %c, and converts the parameters accordingly. Positional parameters are sometimes specified by using %n$s or %n$d. In such cases, the print supervisor fills in the parameters in the specified order.
  • A maximum of nine parameters can be specified. Therefore, the print supervisor can use nine variables of *char type and assign the variables to the appropriate supplied parameter strings. After replacing all positional specifiers and integer specifiers, the parameters can be passed to the printf subroutine. For example, the extracted message text might contain the following: 
    Error %8$d in opening %6$s file
    The print supervisor converts the message to the following: 
    Error %s in opening %s file
    The print supervisor assigns the first variable parameter pointer to the eighth parameter, the second variable parameter pointer to the sixth parameter, and the remaining variable parameter pointers to null strings. The print supervisor then calls the sprintf subroutine or a similar subroutine and passes the nine variable parameter pointers as parameters to the function.
  • The printer backend specifies the correct type (integer or string) for each parameter, even though all parameters are passed in the pipe as strings. The appropriate type must be used for handling field width and precision when placing a parameter in an extracted message.
  • The printer backend may or may not pass message catalog information and parameters for a message. Therefore, the print supervisor must be able to accept the expanded message itself, or accept the catalog information and parameters and then build the message accordingly.