# Appendix B: Toolkit Enhancements

## B.1 Toolkit Enhancements

Version 8.62 of Empress Web HTML Toolkit inherits all the enhancements of Version 8.20 of Empress Web HTML Toolkit, compared to the previous versions. These include:

- New Features

  - Added the `%%Index%%` attribute for `eh_info EXECUTE` tag. This allows the user to display a count of the databases as they are listed.

  - Pass output from select through `eh_writer` after 'select' processing. This allows `EXECUTE` and `QUERY` tags to be embedded into the select result page.
    Note: since select is done first attributes for query must use different names than those in the eh-attributes list of the select tool.

  - Make the writer tool the default if the user does not specify one.
    All other modes, except `get_bulk`, can be specified in the HTML form using the `eh-mode` option (select, update, create).

  - Add `eh-binary` option. Can indicate all form input fields that contain binary data (comma separated string). This depreciates `eh-datatype`.

  - Add in `<EXECUTE TYPE="INCLUDE">` for including library functions kept under `bin/include`.

    First items are JavaScripts `required.js` and `datatype.js`

  - Added `EH_TIMEOUT` resource variable. This will timeout queries if they take longer than the number of seconds in specified in the variable. Default is no timeout. Currently only available for `ehsql.cgi`

- General Improvement

  - Added white space into `DISPLAY INDEX` option.

  - Removed whitespace removal feature from `dbi_set_table ()`. This whitespace removal feature destroyed all whitespace in table names in the URL!

  - Added feature to allow URL value `MSLANG:xxx` to now be `MSLANGyxxx`, where `y` is any character.
    Added to allow for the fact that JavaScript didn't like the colon.

  - Added Internet Explorer recognition into `get_info`. Automatically translates from ShiftJIS to EUC encoding if IE detected.

  - Improved URL encoding of arguments.

    1. Detect in JavaScript and META headers.

    2. Scramble more characters to prevent Windows browser from detecting EUC characters and converting them to ShiftJIS.

  - Added `dbasename=none` option to avoid name loss with `ehlink.cgi` when `DBASE` note specified in `QUERY` and `EXECUTE` tags.

  - Increased Signal catching facilities to stop the `ehlink.cgi ehdbi` system being damaged by the HTTP server.

  - Add greater than and less than to `NUMRECORDS` option in `QUERY` tag. Also added `NOQUERY` option, `START` and `END` options. e.g:

           <QUERY DBASE="Corporate"
           SQL="SELECT * FROM Personnel WHERE LastName MATCH 's*'"
           START="<OL>"
           END="</OL>"
           COUNT=2
           TEXT="<HR>"
           >
           <LI>%%FirstName%% %%OtherNames%% %%LastName%%

           <NUMRECORDS=0>
           No Match Found

           <NUMRECORDS < 3 NOQUERY>
           Less Than 3 Found

           <NUMRECORDS > 10
           noquery
           START="<HR SIZE=5>"
           END="<HR SIZE=10>">
           More Than 10 Found

           </QUERY>

  - Change cookie dates from 4 digit year to 2 digit year so Internet Explorer could handle it. Look out year 2000!
    Also set cookie content to `EXPIRED` as extra precaution.

  - Made RTM (RunTime Message) system search application file before program files when looking for `CONTENT_TYPE` option (makes it application programmable).

  - Removed `FREEWARE` compile options.

  - Make the `eh-edit` option better so that it works the way people expect - i.e detach the URL arguments so that they are not needed.

    URL options for `eh-edit` should now be considered depreciated.

    `index-attribute` value should be set as an attribute in the form.

  - Add ODBC client information to `-version` option.

  - Change signal handler to handle signals below 15 only.

  - Correct for the fact that you cannot use the paired ampersands (and %, $, _) in scripts embedded in the writer tool.

  - Make `KEY_xxx` (e.g `KEY_INSERT`) case insensitive.

  - Add `PORT` option to `EXECUTE TYPE=eh_info/eh_info_edit`.

  - Made `TYPE=""` equivalent to `TYPE="NONE"` in the `EXECUTE` tag. Also unknown types are equivalent to `NONE`.

    System calls are now made by setting `TYPE="SYSTEM"` and specifying the desired call as the `NAME` argument.

  - Make `SELECT` count use `BYPASS` if the original `SELECT` statement did.

  - `mime_types` file can now only be located in `$MSHYPERPATH/resources` directory.

  - Messages directory now only available as `$MSHYPERPATH/resource/messages`.

  - Reverse the change that made `TEXT` and `COUNT` start at beginning of `QUERY`. Now first display of `TEXT` starts after first `COUNT` records are displayed. (If you want test at the start of the `QUERY` you should use `START` option). user.

  - Added `ESC_` option in markup (e.g `%%ESC_attrname%%`) to escape strings for JavaScript.

- XML and Other Text Format Support

  - Removed case switching of HTML tags and added `is_match` functions to compensates.

  - Added ODBC and RDBMS versioning information as option. Implemented as:

           <EXECUTE TYPE="empvers" DBASE="xxx"></EXECUTE>

  - Added `TYPE="Content-type"` to `EXECUTE` tag.

  - Added `mime_extensions` file to resource directory. Includes process levels.

    Process levels are:

    - PL_FULL: process full document
    - PL_TAGS: only process document parts inside QUERY or EXECUTE tags.
    - PL_NONE: don't process text documents.
    - PL_BINARY: don't process binary documents.

    Hard coded document types are:

    - mif frame/maker PL_TAGS
    - gif image/gif PL_BINARY
    - jpeg image/jpeg PL_BINARY
    - jpg image/jpeg PL_BINARY
    - txt text/plain PL_FULL

  - Changed backslash escapes to remove backslash in front of &, %, $, and ? only. This allows more document types (e.g RTF).

  - Option for `MSINSECURE` removed. Toolkit will now handle any file extension.

- Installation Modifications

  - Added resources directory in `MSHYPERMEDIA`. Can locate default `ehtml.ini`, `.html` and `mime_types` here.

  - Removed option for calling `ehtml.ini` file environment (backward compatibility removed).

    Also removed optional `.ehtml` directory under `cgi-bin`.

    Valid locations for `ehtml.ini` are now:

    - $MSHYPERPATH/resources
    - $DOCUMENT_ROOT/.ehtml/ehtml.ini
    - cgi-directory

  - Moved program level nls messages from `$MSHYPERMEDIA/ehtml/nls` to `$MSHYPERPATH/resources/nls`. Also removed alternative search in `$MSPATH/nls`.

- Compatibility

  Version 8.62 of the toolkit is compatible with Version 8.20 but not compatible with the previous releases. Incompatibilities are changes in the syntax that will require modifications to current applications if the items are used.

  There are two reasons why these incompatibilities have been allowed:

  - To improve security
  - To improve efficiency (support for some very old syntax has been removed).

  The changes are:

  - It was previously possible to execute any command in the `EXECUTE` tag by specifying the process in the `TYPE` argument of the tag. For example:

           <EXECUTE TYPE="date"></EXECUTE>

    This caused odd behavior in systems when application developers made errors in the application. Now only predefined types are allowed in the `TYPE` argument. To obtain the same behavior with v8.20 and v8.62 the `TYPE` must be set to `SYSTEM`, and the command to be executed should be specified in the `NAME` argument. For example,

           <EXECUTE TYPE="SYSTEM" NAME="date"></EXECUTE>

    Note: as with the previous version; this options should always be used with caution.

  - The `MSINSECURE` resource variable has been removed.

    When unset this option prevented the writer tool from reading files without the `.ehtml` extension. With the coming of XML this would have be difficult to use. It is now recommended that you use other options to ensure security of your documents - the simplest being to ensure that the Toolkit CGI is as secure as the documents.

  - A number of resources files have been moved:

    The `mime_types` file, used to work out mime types of binary objects in the database, has been moved in to a standard location - `$MSHYPERPATH/resources/init/mime_types`. Files in any other location will be ignored.

  - Resources files (`ehtml.ini`) located under the CGI directory; at:

           .ehtml/ehtml.ini

    will be ignored.

  - Resource files with the old name of environment will be ignored.

- Depreciated Syntax

  Depreciated syntax is application syntax that, although currently still supported, has been replaced by a newer syntax; and in general it is recommended that you switch to the newer syntax when possible.

  - The normal way of indicating whether you intended to update or insert data with the update tools was by the value of the first argument on the URL. The preferred mode is now to specify the update mode itself with a field in the HTML form. This field is named `eh-edit` and can contain one of three values - `insert`, `update`, or `delete`.

  - When inserting binary data into the database via a HTML form the field was flagged as binary data by naming the next field in the form `eh-datatype` and setting it to a value of `binary`. This has been superseded by the `eh-binary` option. This is generally much easier to use.

  - Although the databases can still be located using the odbc.ini file it is generally recommended that this file be renamed empress_config_exml.ini.

- Recommendations

  Recommendations are changes in the syntax where we intended to support the old syntax for the foreseeable future. But the new syntax is considered better, and is therefore recommended.

  The HTML tool that an application would use with `ehsql.cgi` (or `ehlink.cgi`) was always specified as the first argument on the URL. The tools being:

  - writer
  - update
  - select
  - get_bulk

  This is no longer necessary, except for the case of `get_bulk`. The tool will automatically default to `writer`, and if you wish to use `update`, or `select`, this can now be specified in the HTML form that they use by setting the hidden form variable `eh_mode`. For example:

         <INPUT TYPE="HIDDEN" NAME="eh-mode" VALUE="update">

  or

         <INPUT TYPE="HIDDEN" NAME="eh-mode" VALUE="select">

## B.2 Basic XML Support

Version 8.20 and 8.62 of Web HTML Toolkit relaxed the tie between the Toolkit and HTML in order to allow generation of any text based document system by embedding queries in the text. The toolkit can now be used to generate text based documents such as VCard and Rich Text Format (RTF), along with the upcoming XML markups such as Math, Chemical, and even Shakespeare Markup Language.