# CHAPTER 3: Variables in Toolkit Applications

## 3.1 Introduction

Empress Web HTML Toolkit Applications are written as collections of HTML pages and calls to a CGI program (`ehsql.cgi` or `ehlink.cgi`). HTML Forms are used to input data, and special markup tags are used to connect to the database. Information is referenced by several methods. Most of these take the form of the name of the attribute, variable or parameter in question surrounded by double or triple delimiting characters. This is similar to a UNIX operating system shell like `csh`, where environment variable values are obtained by the name of the variable preceded by a dollar sign, as in: `$PATH`.

Different kinds of information have different kinds of delimiters:

- Query results (attribute values) are surrounded by double percent around the attribute names.
- The values of fields of posted forms are surrounded by double ampersands when used for display purposes, or double question marks when used in SQL statements.
- System environment variables are surrounded by double dollar signs.
- Language specific messages are surrounded by double underscores.
- URL line parameters are referenced with the keyword `eh-dbase-key` followed by a number indicating the ordinality of the parameter.

Any character can be escaped with a backslash to print out the actual character instead of the results of the evaluation. For example:

       $$MSHYPERPATH$$          :  displays the value of environment
                                   variable MSHYPERPATH

       \$\$MSHYPERPATHPATH\$\$  :  prints the string $$MSHYPERPATH$$

The backslash itself can be printed with a double backslash.

## 3.2 Query Results

There are a few ways to phrase a database query in the Toolkit. But when a returned data value is referenced in an HTML document, it is always referenced as the name of the attribute surrounded by double percent signs. We will sometimes call these items percent variables. For example:

       <h1>The employee's first name is %%first%% </h1>

Often, queries can return many records, and usually the HTML page handling the display will organize such query results into tabular form. In this situation, a triple percent preceding the attribute name will suppress display of duplicate values of that particular attribute, so it will appear somewhat like the display of an SQL query with a `GROUP By` clause. For instance,

       %%department%% %%employee_num%% <p>

inside a query in an HTML form might access a database table and display the following information on the browser:

       sales     1526
       sales     0607
       sales     0984
       tech      0345
       tech      0645

whereas the same line with a triple percent in front of the department attribute:

       %%%department%%, %%employee_num%% <p>

would display as:

       sales     1526
                 0607
                 0894
       tech      0345
                 0645

Of course it wouldn't line up nice like that on the browser unless it was inside HTML `TABLE` tags.

The tools `ehsql:writer` and `ehsql:select` both provide methods for querying the database, and make the results available in percent variables.

## 3.3 User Input - Form Variables

Whenever an application requires user input, an HTML form is necessary. Several tools are provided for editing database records, as well as for other database administration functions.

Within HTML forms, form fields are declared. These are objects which consist of a variable name, and a means by which to set the value. The means can be user input such as text boxes, pull down lists, and radio buttons, or default values can be set without user interaction. When the submit button of a form is pushed, the information is packaged up and sent to a CGI program, declared in the `ACTION` of the form, and this CGI program uses the variables and their values. `ehsql:update` and `ehsql:writer` are two such programs. They take the information and edit the specified database tables. As well as taking the form as input, they take an HTML file as input. This file becomes the next page displayed on the browser after they finish operating. The values of the form variables are available on that page as the name of the variable surrounded by double ampersands. In this way a bunch of HTML pages become connected into an application, connected to each other by ampersand variables, (and URL parameters, described later) and connected to the database by percent variables. For instance, imagine two simple HTML files:

       file1.html

          <html>
          <form method=post
          action="/bin/ehsql.cgi/file2.ehtml">
            Type the value of X <input type=text name="x"> <p>
            <input type=hidden name="y" value = "2.5">
            <input type=submit
            value="push to submit these variables to file2.ehtml">
          </form>
          </html>

       file2.ehtml

          <html>
          <hr>
            the value of X is &&x&&
          <hr>
            the value of Y is &&y&&
          </html>

This little example application asks the user to type in the value of one variable, then sets the value of a second variable in a hidden (undisplayed) field. Both are posted through the tool `ehsql:writer`, which is given a second file `file2.ehtml` as input as well. The form variables from `file1.html` are referenced as ampersand variables in `file2.ehtml` and displayed. No database is accessed in this application, it just demonstrates the passing around of form variables. The real trick is in the URL specified in the `ACTION` of the form. All paths are from the HTTP server DocumentRoot. The first path is the path to the `ehsql.cgi` program. This is `/My-bin/ehsql.cgi`. The second path is to the document `file2.ehtml`. The question mark specifies the first parameter of the URL, which always should contain the name of the specific tool desired. In this case it is `ehsql:writer`, a general purpose tool used for entering direct SQL statements. These tools are explained in their own sections.

Normally, referencing an ampersand variable with no value will generate an error. This can happen for instance if the user doesn't fill out the relevant field. Depending on the application, this can be a valuable check, or it can be annoying. If it is desired that the variable needn't have a value, place a third ampersand in front. Then, if it has no value, it will simply not display. For instance:

       <hr>
         the value of X is &&&x&&

It looks funny, but it works.

## 3.4 Form values in SQL

Form variables are often passed from HTML forms in order to form an SQL command. You can use the ampersand notation to add the form values to the SQL:

       SELECT lastname FROM employee WHERE firstname = "&&Bob&&"

However, there are two problems with this:

1. If the form value is not filled out the system will generate an error
2. Some types of text in this value can be misinterpreted by the SQL parser

It is better if you use the question marker notation.

       SELECT lastname FROM employee WHERE firstname = "??Bob??"

For those who are interested, this binds the form data to the SQL statement. If you don't know what this means, it doesn't really matter. What's important is the effect. Basically this allows any data to be placed in the SQL.

If the form value is not filled out the Toolkit will still transmit an error back to the client. However if you use three question marks in front of the variable:

       SELECT lastname FROM employee WHERE firstname = "???Bob??"

The variable will be replaced by `NULL`.

Note that:

1. The question mark notation even allows binary data to be added to the SQL statement providing that the `eh-binary` keyword is used in the HTML form. And you can't use binary data in a where clause

2. This depreciates the `<EMPQUOTE>` option used in HTML Toolkit V3.00. This method is still available, but it is no longer documented, and it is recommended to replace it with the newer syntax.

## 3.5 URL Line Parameters

Addresses, whether on the URL line of a browser, or in the `ACTION` clause of a form, can take parameters. The format is a question mark at the end of the actual address, and then a list of parameters separated by plus signs (`+`). If posted through `ehsql.cgi` to another file these parameters will be available with the keyword `eh-dbase-key` followed by the number of the parameter in question. `eh-dbase-key` gets its name from the pages of history, it has nothing to do with keys or databases anymore.

One could rewrite the ampersand variable example as follows:

       file1.html

          <html>
          <form method=post
          action="/bin/ehsql.cgi/file2.ehtml?bruce+2.5">
            <input type=submit
            value="push to submit the URL parameters to file2.ehtml">
          </form>
          </html>

       file2.ehtml

          <html>
          <hr>
            the value of parameter 1 is eh-dbase-key1
          <hr>
            the value of parameter 2 is eh-dbase-key2
          </html>

## 3.6 Environment and Resource Variables

Any of the system environment variables of the HTTP server, and the Common Gateway Interface, can be displayed on a HTML page, along with any resource variables set in the Toolkits resource file. These variables are referenced by adding the name of the variable to the HTML template in between pairs of double dollar signs:

       <html>

       the value of the environment variable MSHYPERPATH is $$MSHYPERPATH$$

       </html>

For these to be available, the page they appear in must be called from an `ehsql.cgi` tool.

The most significant environment variables used by the Toolkit is defined in Resource Variables chapter of this manual and the most significant Common Gateway Environment Variables is defined in Appendix A of this manual.

## 3.7 Language-Specific Applications

Any text appearing between double underscores is assumed to be a string found in the directories pointed to by `MSUSERPATH`, and will be replaced by its corresponding language-specific string. For instance, it is possible to write a completely generic application which will change its display language simply by specifying a variable.

       <html>

       __greeting__

       </html>

can be defined to display as any of:

       Hi
       Bonjour
       G'Day

depending on the setting of the `MSUSERLANG` variable. The mechanism works as follows:

- `MSUSERPATH` is set in the `ehtml.ini` file to point to a directory. This directory must be called `nls`. For example, if you create your application's `nls` directory in `/usr/joe/ehtml/apps/nls` then set `MSUSERPATH` to `/usr/joe/ehtml/apps`.

  Note also that the `nls` directory you create is for your application, it should not be the standard `nls` directory `$MSHYPERPATH/nls` which holds the Toolkit's runtime messages in various languages.

- In your own `nls` you should create other directories, one for each language desired. For instance, to create US English language support, create a directory with a name like `en_US`. Within this directory create a file called `html.rtm`.

  Within the file, use a format as follows:

         labels

         {

            Corn_Meal:   "Grits";

            Football:    "Soccer";

         }

         msg

         {

            CCwarning:   "Warning:  This application does not encrypt form
                          information.  Users providing credit-card numbers
                          do so at own risk"

         }

  The `labels` section contains the symbols which will be referenced with the underscore variables. Each line must give a symbol ending in a colon, followed by a quoted string ending in a semi-colon. The symbol is the text which will be written between double underscores in the `.html` and `.ehtml` files, and the string is what displays.

  If an underscored symbol appears in an application but isn't defined in a developer's `.rtm` file, the Toolkit will search for the symbol in the `ehtml.rtm` file, which should not be altered.

  The `msg` section is set up and used exactly the same way, except you must use `__symbol__MSG` to reference them. Maybe longer strings should go in there.

- Before it can be used, `html.rtm` must be compiled with the utility `emprtmc`. The syntax is:

         $MSHYPERPATH/ehtml/bin/emprtmc -o html.nls html.rtm

  This tells the utility to compile the contents of `html.rtm` into the language file `html.nls`. `emprtmc` is found in the `bin` directory of the Toolkit installation.

  Back up your `html.rtm` file, and don't get the syntax backwards, because the `emprtmc` utility can easily overwrite your source file.

- To use a new language properly, you will also need a directory with that language name in the `$MSHYPERPATH/nls` directory, with a corresponding `ehtml.rtm` file written and compiled. If English Toolkit messages are fine, simply creating the directory and softlinking the `ehtml.nls` file from `en_US` will do fine.

- Once the above files are in place, and an application is written with underscored strings anywhere language support is needed, a language can be turned on by including the parameter `MSLANG:name_of_language_directory` as the last parameter of a URL calling a Toolkit program. In the US English example, one might have an `ACTION` of a form read:

         action="/My-bin/ehsql.cgi/helpform.ehtml?MSLANG:en_US"

  When `ehsql.cgi` processes the `helpform.ehtml` file, it will look up any underscored language references in the `html.rtm` file it finds in the `$MSUSERPATH/en_US` directory.

It is only necessary to specify the language on the URL line once, say at the starting page of an application. After this, simply including the parameter `MSLANG:eh-language` as the last parameter in the calls to subsequent pages will keep the application displaying in the language initially set. That is to say, if it is desired that the user select a language from a pull-down list at the start of a Toolkit application, and this is used to set `MSLANG` on the URL line, it is not necessary for you as a developer to keep track of that language and set it every page.

If a certain language is to be used throughout an entire application, then the value of `MSUSERLANG` can be set in the `ehtml.ini` file, and the `MSUSERLANG` parameter can be left out of the URL line. If `MSUSERLANG` is included as a URL parameter, it will override the setting in the `ehtml.ini` file for that call only.

If error logging is desired in a different language than the displayed one, the variable `MSLANG` can be set in the `ehtml.ini` file to the name of a directory under `MSUSERPATH`. This will cause messages to write into the HTTP server log file in the language specified by `MSLANG`, not `MSUSERLANG`. It will not affect the browser output of the application at all.

Note that when written into the `ehtml.ini` file, `MSLANG` controls the message-logging language, and `MSUSERLANG` controls the application display language. When specified as the last parameter of a URL, `MSLANG` controls the application display language. There is no way to set the message logging language from the URL line.