Appendix B: Toolkit Enhancements

B.1 Toolkit Enhancements

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

This 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 of v8.20 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

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.