Invoking htmSQL

Creating an HTML Form

From your Web browser, you can use an HTML form to invoke htmSQL. The HTML form must use the URL for your Web page as the value of the ACTION attribute of the HTML FORM element. You can also use the optional METHOD attribute to specify the CGI method to use for sending form data:

<form action="http://yourserver/dir/executable_file/input-file" [method=get|post]>

yourserver is your Web server host name (and port, if required).
dir is the path of the Web server CGI program directory that contains htmSQL.
executable_file is the htmSQL program name. For UNIX and z/OS, the program name is htmSQL. For Windows, the program name is htmSQL.exe.
input-file is your input file as a relative pathname under the Web server's root directory (which can include a Web server alias).
GET and POST are the two CGI methods for sending form data.

method=get

Your Web browser sends the form data to the Web server as part of the URL. The Web server passes the form data to htmSQL through the environment variable QUERY_STRING.

method=post

Your Web browser sends the form data to the Web server as part of the body of the HTTP request. htmSQL reads the form data from stdin.

On the form, use HTML INPUT elements to collect variable values. For the NAME attribute of the INPUT element, use the same variable names that you use for your variable references. When the form is submitted, the Web browser automatically generates the following query string from the form input and appends it to the URL that is specified by the ACTION attribute (for the GET method) or sends it in the body of the HTTP request (for the POST method):

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

Note: Some Web servers can be configured to recognize an input file by its file extension and to automatically call the appropriate CGI program to process the file. If your Web server can be configured this way, you can omit the path to htmSQL when you specify the URL (that is, you can omit the dir and executable_file values). Consult your Web server documentation for details about whether and how your server can be so configured.

Specifying a URL for Your Web Page

From your Web browser, you can specify a URL to invoke htmSQL. Specify the URL either on an existing Web page or on your Web browser command line. A URL for htmSQL must include the pathname for an input file and must be of the form:

http://yourserver/dir/executable_file/input-file[?query-string]

yourserver is your Web server host name (and port, if required).
dir is the path of the Web server CGI program directory that contains htmSQL.
executable_file is the htmSQL program name. For UNIX and z/OS, the program name is htmSQL. For Windows, the program name is htmSQL.exe.
input-file is your input file as a relative pathname under the Web server's root directory (which can include a Web server alias).
query-string specifies values for one or more of the variables that are referenced in the input file. This parameter is optional. The variable name and value pairs are separated by ampersands (&) and are specified using the following format:
```
var1=value1&var2=value2&...varN=valueN
```
Be sure to properly encode any nonalphabetic characters that are in the query string: spaces become plus signs (+) and other characters are replaced by a percent sign (%) and the two-digit ASCII representation.

The following example shows a URL that invokes htmSQL: http://support.sas.com/cgi_bin/htmSQL/empdata.hsql?first=fname&last=lname&middle=mi

Note: Some Web servers can be configured to recognize an input file by its file extension and to automatically call the appropriate CGI program to process the file. If your Web server can be configured this way, you can omit the path to htmSQL when you specify the URL (that is, you can omit the dir and executable_file values). Consult your Web server documentation for details about whether and how your server can be so configured.

From the Command-Line Prompt

The output that htmSQL generates is sent to stdout (usually your terminal display). You can capture the generated output by redirecting stdout to a file. Use this method of invocation to test an htmSQL input file or to produce a static page that contains SAS data.

The following is the syntax for the htmSQL command (parameters that are within square brackets ([]) are optional):

htmSQL input-file ["query-string"] [-rc config-file] [-dsf datasrc-file]

input-file specifies the pathname for your input file.
query_string specifies values for one or more of the variables that are referenced in the input file. The variable name and value pairs are separated by ampersands (&) and are specified using the following format:
```
var1=value1&var2=value2&...varN=valueN
```
You do not need to encode nonalphabetic characters that are in the query string.
-rc config-file specifies the pathname of the configuration file to use. You can name the file whatever you want and locate the file in whichever path you choose. htmSQL does not run if the specified file cannot be opened.

This parameter is optional. For more information about running htmSQL without explicitly specifying a configuration pathname, see Specifying and Naming the Configuration File.
-dsf datasrc-file specifies the pathname of the data source definition file. If you specify a simple filename, htmSQL looks in the current directory for the file. This option overrides any data source definition file that is specified in the configuration file. The file does not have to be named htmSQL.datasrc, htmSQL.dsf, or HTMSQL DATASRC.
the -rc and -dsf parameters can be placed anywhere after the htmSQL command name.