# Help

- Introduction
- Query Strings
- Basic Selection Page
- Query All Fields Page
- Query Form Build Page
- Information Providors
- Limitations

## Introduction

The Hypertext-dBASEIV interface provides query access to VMS-hosted `dBASEIV` database files (surprise!).

The user can, by radio button, select to generate a report in a fixed-font format (the default), or using native HTML tables (supported by Netscape v1.n, but not supported by Mosaic v2.4, the current VMS browser).

Another set of radio buttons allow selection of the report layout as a table (the default), where fields are columnated, or as a listing, where fields are presented sequentially.

Parameters for the query are presented using a combination of checkboxes and/or text entry boxes against one, more, or all of the fields in a database. The checkboxes allow the inclusion of that field in a report. The text entry boxes allow the specification of query strings, and provide the ability to selectively report on records of a database depending on the contents of the fields.

A Submit Query button allows the completed query form to be sent to the server, and the report generated and returned to the user.

A basic demonstration of the interface is available.

## Query Strings

A query string allows records to be selected based on whether a corresponding field's data matches on one of two methods:

1. pattern match
2. range check

To be selected a record must match each of all query fields supplied (i.e. it is a logical and of queried fields).

## Pattern Match

This allows records to be selected based on whether a corresponding field's data matches the pattern supplied. Query strings may be empty, contain a fixed sequence of characters that must be matched exactly, or include wildcards matching variable characters.

- An empty query string (i.e. no characters, not even spaces) results in that field being ignored - no pattern match, no report.
- A single asterisk causes all records to be selected for that field.
- Any other sequence of characters results in a pattern match being undertaken.
- A query string may not begin with any of the characters ``<'', ``>'' or ``='', which introduce a range check query. If the query string must begin with any of these characters then introduce the string with a leading ``\'' (backslash).

Wildcards available:

- The ``*'' matches zero, or any one or more characters in the field data.
- The ``%'' matches any single character in the field data.

The pattern matching algorithm used is fairly common. To match any given leading characters an asterisk must lead the query string, otherwise the match commences from the first character of the query string and the first character of the field. Trailing characters must be wildcarded if not to be explicitly matched. For example, to search for the string ```CPU`'' anywhere within a twenty character database field the query string ```*CPU*`'' would need to be entered. To locate all records with the field beginning with the characters ```Intel`'' the query string ```Intel*`'' would be needed.

The character matching is case-insensitive (i.e. lower-case and upper-case are not differentiated).

## Range Check

This allows records to be selected based on whether a corresponding field's data numerically falls within the range(s) specified. Of course the field must contain a valid number for this to be possible, but that number can be within either a numeric or character-string based field.

Note:

> The range-check function attempts to convert the first string in any field to a number. If the string is not a valid number no range-check is made! There may be multiple numbers within a character field, etc., but only the first is range-checked. It is up to the user to ensure the use of range-check against any particular field is valid.

> Numbers can be in integer or floating-point format, but are converted to a floating-point internal representation. All comparisons are done using floating-point operations.

The range-check syntax is elementary. The following relational operations are provided:

- ``<'' ... less than
- ``<='' ... less than or equal to
- ``='' ... equal to
- ``>='' ... greater than or equal to
- ``>'' ... greater than
- ``<>'' ... not equal to

These symbols must be immediately followed by a number (integer or floating-point representation) and operate directly on that number in comparison with the field value. Consecutive evaluations are implicitly ANDed allowing inclusive ranges. Consecutive evaluations separated by commas are implicitly ORed allowing exclusive ranges. Spaces are allowed but not required. For example:

> `<25`
>   Selects all records with a value less than 25.
> `>=10<=25`
>   Selects all records with a value greater than or equal to 10 and less than or equal to 25.
> `<10,>25`
>   Selects all records with a value less than 10, or greater than 25.
> `>=0<=10,>=90<=100`
>   Selects all records with a value between 0 and 10, or between 90 and 100.

## Basic Selection Page

This page provides a basic interface to all records in a database.

The user can, by radio button, select either to report all fields from all records, or to report specific fields from all records. Field specification is accomplished by selecting the checkbox against the required field name(s).

## Query All Fields Page

This page provides a basic query interface to records in a database.

The user can, by radio button, select either to report all fields from all records, or to report specific fields from all records.

Each field supporting queries has a corresponding text entry box allowing a query string to be entered. Those not supporting queries have a selection checkbox. Note:

> For this page the default for the query text entry boxes is an empty string. This means that the field will not, by default, be reported on (unless the All Fields box is checked). For this page a single asterisk must be inserted into a query box for a report to be generated against the corresponding field. To use it as a genuine query a query string must be input. Then, only those records with field(s) matching the corresponding entries will be returned in the results page.

## Query Form Build Page

This page allows a custom query form, based on the structure of a specific database, to be designed by the user and built by the Hypertext-dBASEIV server. When this form is returned to the user its functionality can be checked by direct use. Modifications may then be made by going back to the build page, with as many of these iterations as necessary. Although the build page can be used for ad hoc queries its real utility derives from the capacity to save the page for use as a permanent interface to the database (by employing the browser's save as `HTML` functionality) and using the file as required, either standalone in a hypertext area, or by including it in another hypertext document. Once saved the built form may be directly edited for further customization.

The build page comprises several sections:

- The page header, providing title and database information.

- A checkbox that when selected, causes the generated form to contain only the query interface. No page header or other information is generated. Use this when generating a query form for inclusion in another document.

- A text entry box containing the default database specification. This can be altered if necessary. Generally it will not require change ... in fact because the query interface is built specifically for a given database's structure substituting another may not produce the desired result!

  There are two legitimate uses for this field (which is why it is provided!), both depending on multiple databases sharing a common structure:

  1. The same build page may be used for generating multiple query forms for multiple databases.
  2. A database specification may be wildcarded to specify a query should search across multiple databases. Of course great care must be exercised to ensure the wildcarded specification only returns those database files containing the same structure (VMS file specification rules apply). The results will be indeterminate if a query designed for one structure is applied to another. In addition, if multiple, large databases are accessed the information returned may overwhelm the browser ... query carefully!

- A text entry box allows a specific title to be placed on the built form and any database query results it generates. If not supplied the title defaults to the name of the database file being accessed.

- Another text entry box allows text to be placed on the built form's page header. This can be used to provide a description of the form's purpose, specific usage instructions, etc. It is not propagated to any query results pages generated. It is added as HTML, so markup tags can be used. The quantity of text is limited to 255 characters.

- A radio button selector allowing control of field display:

  1. No facility to display all fields.
  2. Always display all fields.
  3. Provide a radio button selector allowing the user to specify either selected fields (the default) or all fields.

- All of the fields in the database. For each field a list selector allows specification of how the field will be presented in the built form and any query report generated from it. Four fields are generally available to choose from, by default it is displayed blank:

  NAME-OF-FIELD (type-of-field, size-of-field)

  1. Blank excludes the field from any built form and subsequent report.
  2. Always include the field in any generated report.
  3. Allow the user to Select it for inclusion.
  4. Provide a text entry box for the user to input a Query string against that particular field. By default the query string contains a single asterisk, resulting in a match for all records and the field always being included in any generated report. Query option is not available for all field types.

  Following this selector is the name of the field (the database variable name) and a short description of the type and size of the field.

When the appropriate selections have been made the Build Query Form button causes the server to return a page containing the custom-built form.

## Information Providors

This section is for document authors wishing to provide links to this facility. As the server interface is moderately complex, and varies on a per-database instance, database query documents are best generated using the query form build page.

For ad hoc access to any specific database (the `.DBF` extension is default) use the partial URL:

      /dbiv/vms-file-path

or if from a non-HFRD served document, a full URL:

      http://host/dbiv/vms-file-path

Similarly, to generate a listing of all `dBASEIV` databases (`.DBF`s) in a directory provide just the directory path:

      /dbiv/vms-directory-path

The help you are currently reading can be linked to separately using the partial URL:

      /dbiv?do=help

To link directly to the basic selection page use the partial URL:

      /dbiv/vms-file-path?do=select

To link directly to the query all fields page use the partial URL:

      /dbiv/vms-file-path?do=select:query

To link directly to the build page use the partial URL:

      /dbiv/vms-file-path?do=build

## Limitations

- Queries can be applied to `dBASEIV` character, date, logical and memo fields. Numeric fields (genuine `dBASEIV` float and numeric, not character fields containing digits) are not currently supported.

- Caveat Emptor! Hypertext-dBASEIV has not had an extensive development or debugging period, nor has it been tested on a wide number of databases. The developer would appreciate any feedback, problem reports, etc. PostMail or mailto: Mark Daniel.