next up previous external
Next: Porting WDB to other Up: WDB Installation and Users Previous: Form Definition File Syntax

How to use WDB


TOC:

To use wdb to access a specific form you start your WWW-browser with a URL of the form :

http://server/cgi-bin/wdb/database/form-name/mode/keys

Where ...

http://server
is the base URL to the HTTP server where you have installed WDB.

/cgi-bin/wdb/
is the path on the HTTP server to where you installed WDB. This example assumes that you have a special directory where you keep your CGI scripts called /cgi-bin. If your server are configured to run scripts depending on a file extension (say .cgi) then you'd have to rename the cgi script (say to wdb.cgi) and change the above path accordingly.

database
is the name of the subdirectory where you have stored the FDF files you are trying to access - typically you would name this directory after the database the FDF files are accessing. (This would be a subdirectory to the directory you defined in $formdir in the configuration file.) - If you only have one database and one or two FDF's this might seem ridiculous, but wdb was designed to handle a large number of FDF's in many different databases.

form-name
is the name of the FDF file you want to use - without the '.fdf' extension.

mode
is the mode in which you want to start WDB. This can be one of


See below for details ....

keys
is used in the following modes:

See below for details.

Using Simple Queries

Three modes: form, query, and default are used to select data from a database and display it to the user. Database queries are 90% of the capability needed from the WWW. The following three sections detail how to query a database using WDB.

Form Mode

In form mode WDB reads the form definition file and creates an HTML form in which the user can enter qualifiers. This is the normal use of WDB. For an example you can try the ESO Telescope Schedule Report located at

http://arch-http.hq.eso.org/cgi-bin/wdb/eso/sched_rep/form

Form mode is invoked with the form or query_form action.

Query Mode

This mode is used by WDB internally as the action script to activate when the user presses Search in the query form. However you can also use this mode to ask WDB to search for something in the database an present it according to the FDF specified. If one row is returned it will be displayed in full-screen output mode, otherwise the tabular output mode is used.

Query mode is invoked with the query action.

There are are two methods you can use to specify what to search for. The first and most used is to specify the key(s) for the table(s) in the FDF. Which fields in the FDF that are the keys is specified with the field attribute 'key' on one or more fields. To access a specific row via these keys you have to add the key values to the URL. If there are more than one key you have to specify the values in the same order as the key fields in the FDF, separated with a double colon ( :: ). Please note that this is the raw database values ( i.e. the to_db function is not used ).

The normal use of this is from an FDF file to provide hypertext links from one database row to another using the 'url' attribute. In fact you will need to use this in every FDF you write to provide access from the tabular output to the full-screen output. For example :

    FIELD  = more
   label  = More
   type   = char
   length = 4
   from_db= "MORE"
   url    = "$WDB/mydb/$form{'NAME'}/query/$val{'key1'}::$val{'key2'}"
   computed
   forcetab
   no_query
   no_full

This will create a hypertext link labeled 'MORE' in the tabular output which when activated will start WDB again using the same form, but this time searching on the two columns key1 and key2. Assuming these two columns together form the unique key on this form, this will lead to the full-screen output of the current row in the tabular output.

mkfdf will automatically add a field like the one above to your FDF files but you might want to modify it, or add url tags to other fields to create links from one form to another.

You can also create URL's to search on something different than the key values. To do this you have to use the HTTP GET method. The general syntax is :

http://server/cgi-bin/wdb/database/ form-name/query?fieldname=query& fieldname=query ...

Where fieldname is the name of a field in the form, and query is a query on that field as if the user had typed it in. This means you can use operators (like > and < ) and the values will be passed through the functions in the to_db attributes.

Default Mode

The default mode can be used to execute a default query. This is normally used in conjunction with the default field attribute in the FDF. The values in the 'default' field attributes are used as query constraints and the result shown in tabular output format. This is especially useful when the default attributes are expression that depends on the current time, or other external factors.

For example, lets say you have a table with schedule information. The table has a field called start_time with a default attribute like this

    default = ">= `date +'%Y.%m.%d'`"

Now you can create a link like 'click here to see schedule starting from today' using the default method.

For example to see the ESO telescope allocation schedule, starting from today, you can use :

    http://arch-http.hq.eso.org/cgi-bin/wdb/eso/sched_rep/default

As you can see, default mode is invoked with the default action.

NEW Inserting New Database Records

WDB now allows you to insert information into a database via the WWW. Inserts are harder to do than simple queries, but WBD makes an effort to support most simple database structures. WDB can insert data across table joins, but only uder certain conditions.

If one table contains a key field that uniquely identifies a record, and that field is referred to by other tables, the key field must appear before any other key fields in the FDF. The value inserted into the first table can also inserted into the other tables as the value of the foreign key fields if the dependant fields are labeled in the FDF with the foreign_key tag.

Also, if the unique key is a serial field, which means a unique value is generated for the record before or after the value is inserted, the serial field must be designated in the FDF with the serial_key attribute. Some databases don't support serial fields natively and a simple method is suggested in the DBI file for your particular database. Others do, and WDB attempts to support these native methods as well.

Under default operations, inserts are not allowed. To enable inserts for a specified FDF, include the following line in the FDF:

    ALLOW_INSERT

Inserts across table joins currently only works under the following conditions:

  1. The serial key field is in the FDF before any foreign key,
  2. The table containing the serial key is first in the TABLE field,
  3. All foreign keys reference the serial key, and
  4. Only one serial key exists in the FDF.

Insert Form Mode

The insert_form mode generates a form based on the specified FDF for you to enter data into. You can specify required fields using the non_null attribute so WDB will not attempt to perform an insert if any required field is empty, and WDB will return a list of the fields that are required but empty so the user can quickly enter the required information.

In addition, a field can be designated as a serial key so the value generated by the database is inserted into the serial_key field instead of requiring the user to enter a value, plus all foreign keys get the same value.

Instructing WDB to generate an insert form is done with the insert_form action like so:

    http://www.some.where/cgi-bin/wdb.cgi/database/fdf/insert_form

Insert Mode

This mode is used to actually insert into the database the information entered in the insert_form mode.

Instructing WDB to insert data is done with the insert action like so:

    http://www.some.where/cgi-bin/wdb.cgi/database/fdf/insert

NEW Updating Database Records

WDB does updates in a very straight-forward manner. First, you run a query to find the data you might want to update. From the displayed results, you select a record and that takes you to a Web form that is filled in with the data you want to update. When done, you push a button and the data in the database is replaced with what you added or deleted from the Web form.

You'll notice there is a step missing from most normal database updates. WDB does nothing to lock the database record you are changing in case someone else comes along and wants to change the same record. WDB simply compares each field of data to what currently exists in the database just before it performs the update. If you get a copy of the data, then someone else gets a copy and saves changes, then you try to save changes, yours will fail because the data no longer matches. Why does WDB allow this?

The main reason is because that's how the Web forces things to happen. There is no easy way to lock a table or record for updates from the Web. What happens if the Web browser with the lock suddenly crashes, or the person using it gets called away before they can complete the update? What if they change their mind and decide not to make changes? The table or record will remain locked until manually unlocked or a timeout program unlocks it. The whole idea of using the Web to accomplish updates in a large multi-user environment is a non-starter to begin with.

However, there are times when data MUST be updated and WDB allows trusted users to do that. If you want to make the update function available to a large number of concurrent users, feel free to do so. Just don't come crying to me when your database is corrupted by four people pushing the Update button at the same time. The Web is not the ideal venue for updating a database, but with care, it works fine. Keep this in mind as you deploy the ability to update data from the Web using WDB.

Some fields, such as primary key fields, should not allow updates by the user. Fields such as these can be designated using the no_update attribute. However, those protected fields are included as hidden form fields so their value doesn't change during an update.

Under default operations, updates are not allowed. To enable updates for a specified FDF, include the following line in the FDF:

    ALLOW_UPDATE

The logical flow from one update mode to the next is like this:

    Update Query Form -> Update Query -> Update Form -> Update
This sequence is explained more fully in the following sections.

Update Query Form Mode

This mode is used to generate the initial query form used to locate the data which is to be updated. This is the same form used in the form, query_form (same as form), or delete_query_form modes.

Instructing WDB to generate an update query form is done with the update_query_form action like so:

    http://www.some.where/cgi-bin/wdb.cgi/database/fdf/update_query_form

Update Query Mode

This mode is used to perform a database query based on parameters entered by the user in the update query form. The results of an update query are always displayed in tabular output format with an Update hyperlink for each record. You will select the specific record to update from the displayed results by clicking on the hyperlink.

Instructing WDB to perform an update query is done with the update_query action like so:

    http://www.some.where/cgi-bin/wdb.cgi/database/fdf/update_query

Update Form Mode

Once you have selected the specific record to update by clicking on the Update hyperlink, your Web browser will display a Web form on which the form elements are filled with the selected data. On this update form, you can add to, change, or delete individual fields. Pressing the Update button sends the changes to WDB for processing.

Note: if you don't like the word Update taking up space on your output page, you can always edit the FDF and choose a word or letter you like better.

Instructing WDB to generate an update form is done with the update_form action like so:

    http://www.some.where/cgi-bin/wdb.cgi/database/fdf/update_form

Update Mode

This mode actually performs the action of updating the information in the database. If the record does not exist (maybe it was deleted out from under you), you will get an error message.

Instructing WDB to perform an update is done with the update action like so:

    http://www.some.where/cgi-bin/wdb.cgi/database/fdf/update

NEW Deleting Database Records

WDB deletes records from a database using much the same process as updating database records. First, you run a query to find the data you might want to delete. From the displayed results, you select a record and that takes you to a Web form that is filled in with the data you want to delete. Once you have verified the selected record is the one you want to delete, you push a button and the data is removed from the database.

Note: WDB currently performs a delete based on the first key field it finds in the FDF. If your database structure requires more than one key field to uniquely identify a record, do not use WDB to delete records. If the single key field is not a unique key, the delete command will delete all records which contain the specified key value. This could ruin your whole day.

Under default operations, deletes are not allowed. To enable deletes for a specified FDF, include the following line in the FDF:

    ALLOW_DELETE

The logical flow from one update mode to the next is like this:

    Delete Query Form -> Delete Query -> Delete Form -> Delete
This sequence is explained more fully in the following sections.

Delete Query Form Mode

This mode is used to generate the initial query form used to locate the data which is to be deleted. This is the same form used in the form, query_form (same as form), or update_query_form modes.

Instructing WDB to generate a delete query form is done with the delete_query_form action like so:

    http://www.some.where/cgi-bin/wdb.cgi/database/fdf/delete_query_form

Delete Query Mode

This mode is used to perform a database query based on parameters entered by the user in the delete query form. The results of a delete query are always displayed in tabular output format with a Delete hyperlink for each record. You will select the specific record to delete from the displayed results by clicking on the hyperlink.

Instructing WDB to perform a delete query is done with the delete_query action like so:

    http://www.some.where/cgi-bin/wdb.cgi/database/fdf/delete_query

Delete Form Mode

Once you have selected the specific record to delete by clicking on the Delete hyperlink, your Web browser will display a Web form on which the form elements are filled with the selected data. On this delete form, you can verify that this is the data you want to delete. Pressing the Delete button sends the delete request to WDB for processing.

Note: if you don't like the word Delete taking up space on your output page, you can always edit the FDF and choose a word or letter you like better.

Instructing WDB to generate a delete form is done with the delete_form action like so:

    http://www.some.where/cgi-bin/wdb.cgi/database/fdf/delete_form

Delete Mode

This mode actually performs the action of deleting the information from the database. If the record does not exist (maybe it was deleted out from under you), this is not considered an error. (You wanted the record gone, right? Well, it's gone!)

Instructing WDB to perform a delete is done with the delete action like so:

    http://www.some.where/cgi-bin/wdb.cgi/database/fdf/delete


next up previous external
Next: Porting WDB to other Up: WDB Installation and Users Previous: Form Definition File Syntax

Copyright © 1996 Bo Frese Rasmussen