Internet

Beginning CGI Programming with Perl

Using the SSI config Command

The config command stands for configuration. You will never see this command appear anywhere on your Web page. But you will find it a very useful command for changing the look of other SSI commands on your Web page. The config command modifies the standard text output from an SSI error command. You should use the config command if you want to perform actions such as these:

  • Sending back a friendlier message than
    ["an error occurred while processing this directive"]
  • Using a different date format than
    Sunday, Oct 8 09:13:00 CDT 1995
  • Changing the way the file size is displayed on your Web page

By now, you should be able to deduce that the config command modifies the output of other SSI commands. In particular, the config command modifies how the following are displayed on your Web page:

  • The error message when an SSI command doesn’t work
  • The output of any command that includes a date or time
  • The format of the file size returned from the fsize command

Table 3.2 summarizes the command options for the SSI config command. The syntax of the command is similar to that of all other SSI commands:

<!--#Command Command-Argument="Argument-Value" -->

Table 3.2. Command options for the config command.

Command Command-Argument Argument-Value
config errmsg Any ASCII text
config sizefmt Bytes or abbrev
config timefmt Any of the date codes listed in Table 3.3

Why would you want to use this command? The most common use is to change the date printed when using the flastmod SSI command. The flastmod SSI command prints the last modified date of a file. If you use your SSI commands to perform more complex tasks, however, like executing a CGI or system command, you might find it useful to return a polite error message.

Perhaps the requested CGI program is available only to registered users, for example. You could change the error message to return a polite

I'm sorry, this function is available only to registered users

instead of the rather cryptic default error message of

["an error occurred while processing this directive"]

If you are changing the error message to try to debug your scripting errors, however, the error log is a better tool than the config errmsg command. The error log is covered in Tutorial 13, “Debugging CGI Programs.”

The syntax of the config errmsg command follows:

<!--#config errmsg="You can put any message here" -->

The second valid command-argument affects mainly the fsize command. It changes whether the size returned by the fsize is returned in bytes or in a rounded-up kilobyte format. The command-argument is sizefmt, which accepts the argument values of bytes or abbrev.

The syntax of the config sizefmt command follows:

<!--#config sizefmt="bytes" --> or  <!--#config sizefmt="abbrev" -->

Finally, the timefmt command argument is quite useful. You can use this inside regular text to return a date or time formatted to your preference. Whether you want only the day of the week, the current hour, or a full GMT date stamp, timefmt enables you to format the current date to fit all your needs.

Table 3.3 shows all the possible variations for the date format. It’s amazing how many varieties of time are available to you.

The format for configuring the time follows:

<!--#config timefmt="Any valid grouping of format codes" -->

If you want to print the day of the week, followed by the month, day of the month, and then the year, use this SSI command:

<!--#config timefmt="%A, %B %d, %Y" -->

Table 3.3. Date codes for displaying the time on your Web page.

Command Specifies
%a Abbreviated weekday name, according to the current locale
%A Full weekday name, according to the current locale
%b Abbreviated month name, according to the current locale
%B Full month name, according to the current locale
%c Preferred date and time representation for the current locale
%d Day of the month as a decimal number (ranging from 0 to 31)
%m Month as a decimal number (ranging from 10 to 12)
%U Week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week
%W Week number of the current year as a decimal number, starting with the first Monday as the first day of the first week
%w Day of the week as a decimal, with Sunday being 0
%x Preferred date representation for the current locale without the time
%y Year as a decimal number without a century (ranging from 00 to 99)
%Y Year as a decimal number, including the century
%H Hour as a decimal number using a 24-hour clock (ranging from 00 to 23)
%I Hour as a decimal number, using a 12-hour clock (ranging from 01 to 12)
%j Day of the year as a decimal number (ranging from 001 to 366)
%M Minute as a decimal number
%p Either a.m. or p.m., according to the given time value or the corresponding strings for the current locale
%S Second as a decimal number
%X Preferred time representation for the current locale without the date
%Z Time zone, name, or abbreviation

Figure 3.2 shows several uses of the config command: changing the error message, the appearance of the date, and the size of a file. Listing 3.3 shows the HTML and SSI commands used to generate this Web page.

Figure 3.2 : Using the config command.

Listing 3.3. The config command in HTML.

01: <html>02: <head>03: <title>Config command examples </title>04: </head>05: <body>06: <h3>First lets demonstrate modifying the error message. </h3>07: <!--#config errmsg="This command won't work because the relative path starts  at the directory above the current path." -->08:09: <!--#flastmod file="../../signatures/pi_sig.html" -->10:11: <h3>Next we output the standard date. </h3>12: The signature file was last modified on13: <!--#flastmod virtual="/signatures/pi_sig.html" -->.14: and is <!--#fsize virtual="/signatures/pi_sig.html" --> in size.15: <h3> If you don't like that date format try outputting something more  common. </h3>16: <!--#config timefmt="%x" -->17: The signature file was last modified on18: <!--#flastmod virtual="/signatures/pi_sig.html" -->19: <!--#config sizefmt="bytes" -->20: and is <!--#fsize virtual="/signatures/pi_sig.html" --> bytes in size.21: <br><hr>22: Today is <!--#config timefmt="%A" --> <!--#echo var="DATE_LOCAL" -->,23: it is day <!--#config timefmt="%d" --> <!--#echo var="DATE_LOCAL" -->24: of the month of25: <!--#config timefmt="%B" --> <!--#echo var="DATE_LOCAL" -->26: in the year <!--#config timefmt="%Y" --> <!--#echo var="DATE_LOCAL" -->.27: </body>28: </html>