5 How to use WDB

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 ' form', ' query' or ' default'. See below for details ....

keys

is only used in the ' query' mode. See 'Query Mode' below for details.

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

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.

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