PMDF popstore & MessageStore Manager's Guide

After processing an HTTP request from a client, the result of processing the command is sent back as an HTTP response to the client. The format of the response is governed by formatting files specified in the command from the client. That is, the request from the client includes the names of formatting files on the CGI server system that are to be used to format the response sent back to the client. On OpenVMS systems, these files must reside in the PMDF_ROOT:[WWW.POPSTORE] directory; on UNIX and NT systems, these files must reside in the /pmdf/www/popstore/ directory tree.

The formatting files can contain text to be copied verbatim into the HTTP response as well as directives to substitute in values associated with the results of a particular command. There are three basic types of formatting files: success, error, and command-specific files.

After the CGI parses a request and executes it, the results of the operation are sent back to the HTTP client using the following formatting steps:

1. The command-specific formatting files are used to format the data collected by the command. The files can be consulted multiple times such as when generating a list or table of information (e.g., account listings).
2. If the preceeding step is successful, the content of the success formatting file is used as the response to the client. Each line of the file is copied to the content of the HTTP response. Any line beginning with %s is replaced with the formatted data generated in the first step. The HTTP response sent back to the client will have an HTTP 200 status code.
3. If the first step failed, the content of the error formatting file is sent as the response to the client. Each line of the file is copied to the content of the HTTP response. Any line beginning with %s is replaced with the output, if any, of the first step as well as any error messages. The HTTP response sent back to the client will have an HTTP 200 status code.

In the command-specific formatting files, command-specific substitution strings can appear. These strings all begin with the percent character, %. When such a string is encountered, the value it references is substituted into the HTTP response. For instance, the formatting file

%none{No users found matching your search criterion} %first{<TABLE><TR><TH>Username<TH>Messages} <TR><TD>%username<TD>%message_count %last{</TABLE>}

might be used in conjunction with the list_users command to produce an HTML table of the popstore users and how many messages each have stored; e.g.,

<TABLE><TR><TH>Username<TH>Messages <TR><TD>asmith<TD>11 <TR><TD>jdoe<TD>7 <TR><TD>mfreed<TD>8 <TR><TD>wrobinson<TD>12 <TR><TD>zsmith<TD>0 </TABLE>

In the tables describing each substitution string, the type of data associated with the substitution string is stated. These types are:

Type	Description
int	Signed integer
float	Single precision floating point number
string	ASCII text string
uint	Unsigned integer

In addition, the default formatting string used to format the data is also shown in the tables. The formatting strings follow the C programming language convention for formatting strings passed to the sprintf() C run-time library subroutine. Alternate formatting strings can be used by enclosing them in braces, {}, and appending them to the substitution string. For instance,

%quota_used{%.1f} Kbyte%s

might be used to limit the %quota_used to a single digit of precision after the decimal point.

Five substitution strings, %first, %last, %!first, %!last, and %none, deserve special attention. These first four strings substitute into the output specific text when formatting, respectively, the first, the last, not the first, or not the last instance of the data to be formatted. The text to be substituted in must be enclosed in braces, {}, following the substitution string.³ For example, suppose that a list of popstore users is to be formatted using the following formatting file:

%first{<TABLE>} <TD>%username %last{</TABLE>}

In the above, when information for the first popstore account is formatted, the text <TABLE> will be output followed by the username (%username). When information for the last account is formatted, the text </TABLE> will be output following the username.

The %none substitution string supplies text to output when there are no instances of the collected data to display. For example, when there are no messages to list for a given user account.