# CHAPTER 7: Bulk and Text Data

## 7.1 Insert Binary Files

Binary data can be uploaded by using either `ehsql:update` or `ehsql:writer`. Both require a HTML Form to be used.

In both cases the following items are required in the form.

1. The form tag itself must contain an parameter called `ENCTYPE`, and this must be set to `multipart/form-data`. For example:

          <FORM METHOD="POST" ENCTYPE="multipart/form-data" ACTION="...

   This allows the browser to transmit file based data to the HTTP Server.

2. Any attributes that will contain binary data must be listed using the `eh-binary` keyword. For example, if there where two binary attributes `b1` and `b2`, then they should be listed:

          <INPUT TYPE="HIDDEN" NAME="eh-binary" VALUE="b1">
          <INPUT TYPE="HIDDEN" NAME="eh-binary" VALUE="b2">

3. Any input binary or text attributes that will be loaded from a file on the browser must have a form input field of type `FILE`.

   Note that binary data can ONLY be uploaded from a file. For example, if you had a text field `t1` and a binary filed `b1` that were to be uploaded from file. Then you would need:

          <INPUT TYPE="FILE" NAME="t1">
          <INPUT TYPE="FILE" NAME="b1">

   `TYPE="FILE"`will cause the HTML form to generate a button which ican be used to starts a file system browser window allowing the user to pick the file to upload.

If this procedure is followed, then large text and binary files can be transmitted to the HTTP Server.

To use `ehsql:update` to insert this data, then the rest of the form should be configured as outlined in the chapter on ehsql:update.

An example is listed below:

       <html>
         <h1> Form to Input binary data from a file </h1>
         <form method=post enctype="multipart/form-data"
          action="/My-bin/ehsql.cgi/insert.html">

         <input type=hidden name=eh-dbase value="tours">
         <input type=hidden name=eh-mode  value="update">
         <input type=hidden name=eh-edit  value="insert">
         <input type=hidden name=eh-table value="pictures">
         <input type=hidden name=eh-binary value="GIFS">

         Choose a binary file:<input type=file name="GIFS"><p>

         Choose a text file:<input type=file name="Explanation"><p>

         Description:<input name="describe"><p>

         <input type=submit value="submit order">

       </form>
       </html>

To insert the same data using `ehsql:writer`, the following HTML form could be used.

       <html>
         <h1> Form to Input binary data from a file </h1>
         <form method=post enctype="multipart/form-data"
          action="/My-bin/ehsql.cgi/insert.html">

         <input type=hidden name=eh-binary value="GIFS">

         Choose a binary file:<input type=file name="GIFS"><p>

         Choose a text file:<input type=file name="Explanation"><p>

         Description:<input name="describe"><p>

         <input type=submit value="submit order">

       </form>
       </html>

As you can see the form is much shorter. However it would require the application developer to add the following commands to the destination HTML file (`insert.html`).

        <EXECUTE DBASE="tours">
        INSERT INTO pictures (describe, Explanation, GIFS)
    	VALUES (??describe??, ??Explanation??, ??GIFS??)
        </EXECUTE>

## 7.2 Display Binary Attributes

When `ehsql:select` displays the results of a query which contains a bulk attribute, it will generate a hyperlink in the single-record display. When clicked, this hyperlink will attempt to recognize the format of the bulk data and display or play the data. Players for various multimedia formats can be included in the setup of the browser. If it doesn't recognize it, a file system browser will appear asking for a filename to save the object in.

If a template document is to display bulk objects as multimedia, along with other markup, then the tool `ehsql:get_bulk` should be used to define a file to give to `<img src>` or other multimedia tags. The `get_bulk` tool is used exclusively for retrieving binary objects from database tables.

`ehsql:get_bulk` is called by `ehsql` with a predefined set of arguments on the URL. For example:

       ehsql.cgi?get_bulk+tours+pictures+GIFS+1+image/gif

These are, in order:

1. get_bulk

   The literal string. Instructing `ehsql` to use the `get_bulk` tool.

2. datasource name

3. table name

4. attribute name

5. Empress internal index for the required record

   This is an Empress hidden attribute present in every table. It can be included in the attribute list of an SQL `SELECT` statement, or and `ehsql.cgi?select` query.

   Note that when this index is to be used it must be retrieved explicitly from the database. For example, `SELECT * FROM pictures` would not retrieve it. You would need something like:

          SELECT eh-internal-index, describe, Explanation FROM pictures;

6. Mime type of the retrieved bulk item (optional)

   If this is not specified, `get_bulk` will attempt to decipher the file format based on information contained in `$MSHYPERPATH/resources/init/mime_types`.

The following example displays a list of `.gif` pictures obtained from a database query. The example file `draw.ehtml` would be called through `ehsql:writer`.

       <html>
       <QUERY DBASE="tours"
        SQL="SELECT eh_internal_index, desc FROM pictures">

       %%desc%%<p>
       <img src="/My-bin/ehsql.cgi?get_bulk+ tours+pictures
                 +GIFS+%%eh-internal-index%%">

       <p>
       </QUERY>
       <html>

This query obtains the internal index number and the description attribute from the pictures table in the `tours` data source. For each record obtained, it will display the description, then display and image retrieved from a call to `get_bulk` with the current internal index number. GIF files can be handled automatically, there is no need to specify the MIME-type.