Sun Java System Web Server 6.1 SP11 Programmer's Guide

Chapter 2 Server-parsed HTML Tags


HTML files can contain tags that are executed on the server. In addition to supporting the standard server-side tags, Sun Java System Web Server 6.1 allows you to embed servlets and define your own server-side tags.

This chapter has the following sections:

Enabling Server-side HTML

The server parses server-side tags only if server-side parsing is enabled.

ProcedureTo enable server-side parsing using the Administration interface

  1. Access the Class Manager, and then click on the Content Management tab.

  2. Click the Parse HTML link.

  3. Use the drop-down list to specify a resource for which the server will parse HTML.

    Choose the virtual server or a specific directory within the virtual server. If you choose a directory, the server will parse HTML only when the server receives a URL for that directory or any file in that directory.

  4. Choose whether to activate server-parsed HTML. The choices are:

    • No. The server does not parse HTML.

      • Yes, with exec tag. The server parses HTML and allows HTML files to execute arbitrary programs on the server.

      • Yes, without exec tag. The server parses HTML but does not allow HTML files to execute arbitrary programs on the server. You might not want to allow the exec tag for security or performance reasons.

  5. Choose which files to parse. The choices are:

    • Files with the extension .shtml. The server parses only files with the extension .shtml. In this case, all files you want to parse must have the .shtml extension. This is the most common (and default) choice.

      • Files with the execute bit and the extension .shtml. (Unix/Linux only) The server parses files whose UNIX/Linux permissions specify that the execute bit is on. Using the execute permissions can be unreliable because in some cases the bit is set on files that are not executable.

      • All HTML files. The server parses all HTML files. Choosing this option can slow down server performance.

  6. Click OK, and then apply your changes.

    When you activate parsing, ensure that the following directives are added to the magnus.conf file :

    Note –

    native threads are turned off

    Init funcs="shtml_init,shtml_send" 
    shlib="install_dir/bin/https/bin/Shtml.dll" NativeThreads="no"

    Note that you must set NativeThread="no" for Sun Java System Web Server version 6.1 and above. In addition, these functions now originate from Shtml.dll (or on UNIX), which is located in install_dir/bin/https/bin for Windows, and install_dir/bin/https/lib for UNIX.

    In addition, make sure the following directive is added to the obj.conf file:

    <Object name="default">
    Service fn="shtml_send" type="magnus-internal/parsed-html" 

    To enable parsing of server-side tags for files with extensions other than .shtml, add the extension to the appropriate line in the mime.types file. For example, the following line in mime.types indicates that files with either an .shtml or .jbhtml extension are parsed for server-side tags:

    type=magnus-internal/parsed-html exts=shtml,jbhtml

Using Server-side HTML Commands

This section describes the HTML commands for including server-parsed tags in HTML files. These commands are embedded into HTML files, which are processed by the built-in SAF parse-html.

The server replaces each command with data determined by the command and its attributes.

The format for a command is:

<!--#command attribute1 attribute2 <Body>... -->

The format for each attribute is a name-value pair such as:


Commands and attribute names should be in lower case.

The commands are hidden within HTML comments so they are ignored if not parsed by the server. The standard server-side commands are listed below, and described in this section:


The config command initializes the format for other commands.


<!--#config timefmt="%r %a %b %e, %Y" sizefmt="abbrev"-->

This sets the date format to a value such as 08:23:15 AM Wed Apr 15, 1996, and the file size format to the number of KB or MB of characters used by the file.


The include command inserts a file into the parsed file. You can nest files by including another parsed file, which then includes another file, and so on. The client requesting the parsed document must also have access to the included file if your server uses access control for the directories in which they reside.

In Sun Java System Web Server 6.1, you can use the include command with the virtual attribute to include a CGI program file. You must also use an exec command to execute the CGI program.


<!--#include file="bottle.gif"-->


The echo command inserts the value of an environment variable. The var attribute specifies the environment variable to insert. If the variable is not found, “(none)” is inserted. For a list of environment variables, see Environment Variables in Server-side HTML Commands.


<!--#echo var="DATE_GMT"-->


The fsize command sends the size of a file. The attributes are the same as those for the include command (virtual and file). The file size format is determined by the sizefmt attribute in the config command.


<!--#fsize file="bottle.gif"-->


The flastmod command prints the date a file was last modified. The attributes are the same as those for the include command (virtual and file). The date format is determined by the timefmt attribute in the config command.


<!--#flastmod file="bottle.gif"-->


The exec command runs a shell command or CGI program.


<!--#exec cgi=""-->

Environment Variables in Server-side HTML Commands

In addition to the standard set of environment variables used in CGI, you can include the following variables in your parsed commands:

Embedding Servlets

Sun Java System Web Server 6.1 supports the <SERVLET> tag as introduced by Java Web Server. This tag allows you to embed servlet output in an SHTML file. No configuration changes are necessary to enable this behavior. If SSI and servlets are both enabled, the <SERVLET> tag is enabled.

The <SERVLET> tag syntax is slightly different from that of other SSI commands in that it resembles the <APPLET> tag syntax:

<servlet name=name code=code codebase=path iParam1=v1 iParam2=v2>
<param name=param1 value=v3>
<param name=param2 value=v4>

If the servlet is part of a web application, the code parameter is required and other parameters are ignored. The code parameter must include:

Defining Customized Server-parsed HTML Tags

In Sun Java System Web Server 6.1, users can define their own server-side tags. For example, you could define the tag HELLO to invoke a function that prints “Hello World!” You could have the following code in your hello.shtml file:

<title>shtml custom tag example</title>

When the browser displays this code, each occurrence of the HELLO tag calls the function.

ProcedureTo define a customized server-parsed tag

  1. Define the Functions that Implement the Tag.

    You must define the tag execution function. You must also define other functions that are called on tag loading and unloading and on page loading and unloading.

  2. Write an Initialization Function to Register the New Tag.

    Write an initialization function that registers the tag using the shtml_add_tag function.

  3. Load the New Tag into the Server.

Define the Functions that Implement the Tag

Define the functions that implements the tag in C, using NSAPI.

The other functions you must define for your tag are:

The signatures for these functions are:

#define TagUserData void*
typedef TagUserData (*ShtmlTagInstanceLoad)(
    const char* tag, pblock*, const char*, size_t);
typedef void (*ShtmlTagInstanceUnload)(TagUserData);
typedef int (*ShtmlTagExecuteFunc)(
    pblock*, Session*, Request*, TagUserData, TagUserData);
typedef TagUserData (*ShtmlTagPageLoadFunc)(
    pblock* pb, Session*, Request*);
typedef void (*ShtmlTagPageUnLoadFunc)(TagUserData);


Here is the code that implements the HELLO tag:

 * mytag.c: NSAPI functions to implement #HELLO SSI calls

#include "nsapi.h"
#include "shtml/shtml_public.h"

/* FUNCTION : mytag_con
 * DESCRIPTION: ShtmlTagInstanceLoad function
#ifdef __cplusplus
extern "C"
mytag_con(const char* tag, pblock* pb, const char* c1, size_t t1)
    return NULL;

/* FUNCTION : mytag_des
 * DESCRIPTION: ShtmlTagInstanceUnload
#ifdef __cplusplus
extern "C"
mytag_des(TagUserData v1)


/* FUNCTION : mytag_load
 * DESCRIPTION: ShtmlTagPageLoadFunc
#ifdef __cplusplus
extern "C"
mytag_load(pblock *pb, Session *sn, Request *rq)
    return NULL;

/* FUNCTION : mytag_unload
 * DESCRIPTION: ShtmlTagPageUnloadFunc
#ifdef __cplusplus
extern "C"
mytag_unload(TagUserData v2)


/* FUNCTION : mytag
 * DESCRIPTION: ShtmlTagExecuteFunc
#ifdef __cplusplus
extern "C"
mytag(pblock* pb, Session* sn, Request* rq, TagUserData t1, 
TagUserData t2)
    char* buf;
    int length;
    char* client;
    buf = (char *) MALLOC(100*sizeof(char));
    length = util_sprintf(buf, "<h1>Hello World! </h1>", client);
    if (net_write(sn->csd, buf, length) == IO_ERROR)
        return REQ_ABORTED;
    return REQ_PROCEED;

/* FUNCTION : mytag_init
* DESCRIPTION: initialization function, calls shtml_add_tag() to
 * load new tag
#ifdef __cplusplus
extern "C"
mytag_init(pblock* pb, Session* sn, Request* rq)
    int retVal = 0;
// NOTE: ALL arguments are required in the shtml_add_tag() function
    retVal = shtml_add_tag("HELLO", mytag_con, mytag_des, mytag, 
mytag_load, mytag_unload);

    return retVal;
/* end mytag.c */

Write an Initialization Function to Register the New Tag

In the initialization function for the shared library that defines the new tag, register the tag using the function shtml_add_tag. The signature is:

NSAPI_PUBLIC int shtml_add_tag (
    const char* tag,
    ShtmlTagInstanceLoad ctor,
    ShtmlTagInstanceUnload dtor,
    ShtmlTagExecuteFunc execFn,
    ShtmlTagPageLoadFunc pageLoadFn,
    ShtmlTagPageUnLoadFunc pageUnLoadFn);


Any of these arguments can return NULL except for tag and execFn.

Load the New Tag into the Server

After creating the shared library that defines the new tag, you load the library into Sun Java System Web Server in the usual way for NSAPI plugins. That is, add the following directives to the configuration file magnus.conf

  1. Add an Init directive whose fn parameter is load-modules and whose shlib parameter is the shared library to load. For example, if you compiled your tag into the shared object install_dir /, it would be:

    Init funcs="mytag,mytag_init" shlib="install_dir/" fn="load-modules"

  2. Add another Init directive whose fn parameter is the initialization function in the shared library that uses shtml_add_tag to register the tag. For example:

    Init fn="mytag_init"

Time Formats

The following table describes the format strings for dates and times used by server-parsed HTML. The left column lists time format symbols, and the right column explains the meanings of the symbols.

Table 2–1 Time Formats




Abbreviated weekday name (3 chars)


Day of month as decimal number (01-31)


Second as decimal number (00-59) 


Minute as decimal number (00-59) 


Hour in 24-hour format (00-23) 


Year with century, as decimal number, up to 2099 


Abbreviated month name (3 chars)


Abbreviated month name (3 chars) 


Time "HH:MM:SS" 


Time "HH:MM:SS" 


Full weekday name 


Full month name 


"%a %b %e %H:%M:%S %Y" 


Date & time "%m/%d/%y %H:%M:%S" 


Date "%m/%d/%y" 


Day of month as decimal number (1-31) without leading zeros 


Hour in 12-hour format (01-12) 


Day of year as decimal number (001-366) 


Hour in 24-hour format (0-23) without leading zeros 


Hour in 12-hour format (1-12) without leading zeros 


Month as decimal number (01-12) 


Line feed 


A.M./P.M. indicator for 12-hour clock 


Time "%H:%M" 


Time "%I:%M:%S %p" 




Week of year as decimal number, with Sunday as first day of week (00-51) 


Weekday as decimal number (0-6; Sunday is 0) 


Week of year as decimal number, with Monday as first day of week (00-51) 


Date "%m/%d/%y" 


Year without century, as decimal number (00-99) 


Percent sign