The htmSQL Configuration File

Specifying and Naming the Configuration File

The htmSQL configuration file contains the values for the htmSQL run-time configuration options. 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 these 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: If you are a UNIX user and you are upgrading from a previous release of htmSQL, if your configuration file is named .htmSQLrc, then you can keep that name (that is, you do not need to follow the 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, then 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 runs without a configuration file. If htmSQL finds a configuration file but cannot open it, then htmSQL does not run.
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 does 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
  • white space characters around the option names and values are not significant
  • blank lines are ignored
  • any line that begins with !, #, or * is ignored.
The following configuration options are available:
CONTENT-TYPE
The CONTENT-TYPE option specifies the string to include 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 interprets it as a comment character and ignores 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 in which 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.
For 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 include 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.
For 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.
For example: 
READONLY = YES
REFRESH
The REFRESH option specifies the string to include 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 specify a URL that designates an alternate Web page to load at the refresh time.
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: 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">
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. This option also affects certain automatic variables.
Copyright © SAS Institute Inc. All rights reserved.