SAS/IntrNet 9.2: htmSQL

The htmSQL Configuration File

The htmSQL configuration file contains the values for the htmSQL run-time configuration options.

Specifying and Naming the Configuration File

htmSQL can run both with and without a configuration file. If you want it to run with a configuration file, htmSQL can automatically locate your file if you follow our rules for naming and locating the file. Or if you need to name or locate the file in a manner different from what is required, you can explicitly specify the file's pathname in either the -rc parameter or the HTMSQL_CFG Web server environment variable.

If you want htmSQL to automatically locate your file, you must do both of the following:

Name the configuration file
```
    executable_name.cfg
```
where executable_name is the name of the htmSQL executable file. For example, if the name of your htmSQL executable file is htmSQL, then name the configuration file htmSQL.cfg. If the name of your htmSQL executable file is htmSQL.exe, then you still name the configuration file htmSQL.cfg.

If you rename the executable file, then you must also rename the configuration file to match.

Note for UNIX users who are upgrading:

If you are upgrading from a previous release of htmSQL and your configuration file is named .htmSQLrc, then you can keep that name (that is, you do not need to follow the above rule for naming the file).
Put the configuration file in a location that htmSQL knows about. htmSQL looks for the configuration file
1. first in the current directory
2. then in the directory where the htmSQL executable file is located
3. and if it still cannot find the file, htmSQL looks in
  - /usr/local/lib/IntrNet/htmSQL (for UNIX and z/OS)
  - C:\Program Files\SAS Software (for Windows)

Note: If htmSQL does not find a configuration file, then it will run without a configuration file. If htmSQL finds a configuration file but cannot open it, then htmSQL will not run.

If you want to give an explicit name and location ...

If you want to explicitly specify the name and location of your configuration file, then provide either a relative or absolute pathname for one of the following:

the -rc parameter when you run htmSQL from the command line
the HTMSQL_CFG Web server environment variable.

You can name your configuration file whatever you want and locate the file in whichever path you choose.

Both of the values are optional, but if you specify both values, then the value of the -rc parameter takes precedence over the value of the HTMSQL_CFG environment variable.

Note: If htmSQL cannot open the file, then htmSQL will not run.

Customizing the Configuration File

A default configuration file is downloaded with the htmSQL package. Modify the preset options to match your needs.

The syntax rules for the file are as follows:

all options must be specified as option = value on a single line unless a continuation character is specified
option names are not case sensitive
whitespace around the option names and values is not significant
blank lines are ignored
any line that begins with !, #, or * is ignored.

The following configuration options are available:

Options

CONTENT-TYPE

The CONTENT-TYPE option specifies the string to be included in the Content-type HTTP header that is output by htmSQL. If this option is not specified, the header defaults to text/html. If the option is specified with no value, then no Content-type header is generated. For example

CONTENT-TYPE =

CONTINUATION

The CONTINUATION option specifies the list of continuation characters that can be used in your configuration file. If the last non-blank character of the line is a continuation character, then at run time, the continuation character (and all blank spaces that immediately precede and follow the continuation character) is replaced with the contents of the next line (minus leading white space).

If you continue an option value to the next line and the first character of the continued text is an !, #, or *, do not place the character in column 1 because htmSQL will interpret it as a comment character and ignore the rest of that line.
The CONTINUATION option itself cannot be continued from one line to the next (that is, the CONTINUATION option must be specified on a single line).

If the CONTINUATION option is not specified, then the continuation character defaults to the backward slash (\).

For example:

     CONTINUATION = +\,
     DATASRCFILE = /local/disk1/htmSQL/htmSQL.datasrc: \
                   /local/disk1/htmSQL/alt.datasrc:    +
     #             /local/disk2/hr/apps/per.dsf:       \     
                   /local/disk2/hr/apps/per2.dsf:      ,
                   /local/disk2/fac/apps/fac.datasrc

at run time is

     DATASRCFILE = /local/disk1/htmSQL/htmSQL.datasrc:/local/disk1/htmSQL/alt.datasrc:
        /local/disk2/hr/apps/per2.dsf:/local/disk2/fac/apps/fac.datasrc

DATASRCFILE

The DATASRCFILE option specifies the pathnames of one or more data source definition files to use. If this option is not specified, then the pathname defaults to

/usr/local/lib/IntrNet/htmSQL/htmSQL.datasrc (for UNIX and z/OS)
C:\Program Files\SAS Software\htmSQL.dsf (for Windows).

If you specify more than one data source definition file, then specify a path separator character between the pathnames. (Path separator characters are listed in the PATHSEPARATOR option.) htmSQL loads the definitions from the files in the order they are specified; if the same data source or SAS/SHARE server is specified in two files, then the later definition overrides the earlier one.

Some examples:

For UNIX and z/OS:

     DATASRCFILE = /usr/local/SAS/htmSQL/data_sources
     DATASRCFILE = /local/htmSQL/htmSQL.datasrc:/local/htmSQL/alt.datasrc

For Windows:

     PATHSEPARATOR = ;
     DATASRCFILE = c:\htmSQL\mydata.src
     DATASRCFILE = c:\htmSQL\mydata.src;c:\htmSQL\yourdata.src

EXPORT

The EXPORT option enables the Webmaster to make Web server environment variables available as htmSQL variables. The default htmSQL configuration file that comes with the htmSQL package exports the following environment variables. The Webmaster can add to or delete from this list:

EXPORT = HTTP_USER_AGENT, REMOTE_ADDR, REMOTE_HOST, REMOTE_USER

Although htmSQL variable names are not case sensitive, environment variable names are case sensitive. The Webmaster must specify the proper case when referring to a variable in the EXPORT option, but anyone creating an htmSQL input file can use uppercase, lowercase, or a combination of the two cases.

Note: Because htmSQL does not distinguish between upper- and lowercase, the Webmaster can export only one environment variable whose case-normalized name is a given sequence of characters (for example, you cannot export both the HOME and the home environment variables).

FULLHEADER

The FULLHEADER option specifies whether htmSQL generates a complete set of HTTP headers. This option is intended for Web servers that require CGI programs to generate a full set of HTTP headers (typically, the Web server generates these header lines).

The values for this option are YES, Y, TRUE, T, NO, N, FALSE, and F (case is not significant).

When the value of FULLHEADER is YES, Y, TRUE, or T or if no value is specified, then htmSQL generates a complete set of HTTP headers, which consists of the following lines:

    HTTP/1.0 200 OK
    MIME-Version: 1.0

plus the Content-type HTTP header, as indicated by the CONTENT-TYPE option. If the CONTENT-TYPE option is specified with no value, then the FULLHEADER option is ignored.

When the value of FULLHEADER is NO, N, FALSE, or F or if the option is not specified, then the complete set of headers is not generated.

INCLUDE

The INCLUDE option specifies a list of filename patterns. The patterns are specified with path separator characters in between them. Any input filename must match at least one of the patterns in the list. If this option is not specified, input filenames are not required to match any pattern. If both this option and the NOINCLUDE option are specified, any input file must match at least one pattern in the INCLUDE list and must not match any pattern in the NOINCLUDE list. The following example allows only files whose names end in .hsql or .hsq:

INCLUDE = *.hsql:*.hsq

LAST-MODIFIED

The LAST-MODIFIED option specifies whether htmSQL generates a Last-Modified HTTP header, which shows the date and time at which htmSQL executes.

The values for this option are YES, Y, TRUE, T, NO, N, FALSE, and F (case is not significant).

When the value of LAST-MODIFIED is YES, Y, TRUE, or T or if the option is not specified or is specified without a value, then a Last-Modified header is generated.

If the value is NO, N, FALSE, or F, the header is not generated.

Example:

LAST-MODIFIED = TRUE

NOINCLUDE

The NOINCLUDE option specifies a list of filename patterns. The patterns are specified with path separator characters in between them. Any input filename must not match any of the patterns in the list. If this option is not specified, then the value defaults to an empty list. If both this option and the INCLUDE option are specified, any input file must match at least one pattern in the INCLUDE list and must not match any pattern in the NOINCLUDE list. The following example disallows any input file whose name begins with local or etc or includes a subdirectory named "private":

PATHSEPARATOR = ;
NOINCLUDE = c:\local\*;c:\etc\*;c:\*\private\*

PATHSEPARATOR

The PATHSEPARATOR option specifies the list of characters that can be used to separate pathnames or path patterns in the values of the INCLUDE, NOINCLUDE, and DATASRCFILE options.

Specifying one separator character between pathnames and patterns is sufficient, although you are allowed to specify more than one character. For example,

PATHSEPARATOR = ;
INCLUDE = *.hsq;*.hsql;;*.html

If this option is not specified, then the path separator character defaults to the colon (:).

PRAGMA

The PRAGMA option specifies the string to be included in the Pragma HTTP header that is output by htmSQL. If the PRAGMA option is not specified or is specified without a value, then the Pragma header is not generated.

Example:

PRAGMA = no-cache

READONLY

The READONLY option specifies whether the SQL UPDATE, INSERT, DELETE, CREATE, DROP, and ALTER statements are allowed in htmSQL input files.

The values for this option are YES, Y, TRUE, T, NO, N, FALSE, and F (case is not significant). Specify YES, Y, TRUE, or T to prevent users from using these SQL statements. If the READONLY option is not specified, then the statements are allowed.

Example:

READONLY = YES

REFRESH

The REFRESH option specifies the string to be included in the Refresh HTTP header that is output by htmSQL. When the Web browser receives the Refresh header, it automatically reloads the document after a delay of a specified number of seconds. When you specify the REFRESH option, you must specify the number of seconds that the Web browser delays. You can optionally specify a URL that designates an alternate Web page to load at time of refresh.

If the REFRESH option is not specified or is specified without a value, then the Refresh header is not generated.

Some examples:

REFRESH = 3
REFRESH = 3,URL=http://support.sas.com

Note that you can achieve the same refresh effect (on Web browsers that support them) on a per-page basis by including an HTML META element in the htmSQL input file.

For example:

<META HTTP-EQUIV="Refresh" CONTENT="3;URL=http://support.sas.com"&gt

RELATIVE

The RELATIVE option specifies whether the relative pathnames of included input files are specified with respect to the location of the calling input file or with respect to the working directory. By default, htmSQL treats relative pathnames of included input files as being relative to that of the calling input file (a value of CALLING). If you want to change the default so that htmSQL regards the pathname as being relative to the working directory, then specify a value of WORKING. For example,

RELATIVE = WORKING

SET

The SET option enables you to specify default values for variables. You can specify one or more variable name and value pairs. The pairs are separated by ampersands (&) and are specified using the following format:

SET var1=value1&var2=value2&...varN=valueN

The values can contain URL-encoded data.

You can specify multiple instances of the SET option in a configuration file. For example

SET var1=value1&var2=value2
SET var3=value3

YEARDIGITS

The YEARDIGITS option specifies the number of digits that htmSQL uses in the year portion of its date and datetime formats. You can specify a value of either 2 or 4. For example,

YEARDIGITS = 4

If this option is not specified, then the value of YEARDIGITS defaults to 2. Note that this option also affects certain automatic variables.

Note: z/OS is the successor to the OS/390 and MVS operating systems. SAS/IntrNet 9.1 for z/OS is supported on the MVS, OS/390, and z/OS operating systems and, throughout this document, any reference to z/OS also applies to OS/390 and MVS, unless otherwise stated.

Top of Page