On Web Connection Database Method

version 2004 (Modified)

The On Web Connection database method can be called in three different cases:

• the Web server receives a request beginning with the 4DCGI URL.

• the Web server receives an invalid request.

• it is also called by 4th Dimension or 4D Server each time a Web browser initiates a connection to the database in contextual mode, or each time the Web server receives a request requiring the creation of a context (this case is not handled by 4D Client, which does not support the contextual mode).

For more information, refer to the paragraph "On Web Connection Database Method calls" below.

The request should have been previously accepted by the On Web Authentication Database Method (if it exists) and the database should be published as a Web server.

The On Web Connection database method receives six text parameters that are passed by 4D. The contents of these parameters are as follows:

You must declare these parameters as follows:

      ` On Web Connection Database Method

   C_TEXT($1;$2;$3;$4;$5;$6)

      ` Code for the method

• URL extra data

The first parameter ($1) is the URL entered by the user in the location area of his or her Web browser, from which the host address has been removed.

Let's take the example of an Intranet connection. Suppose that the IP address of your 4D Web Server machine is 123.4.567.89. The following table shows the values of $1 depending on the URL entered in the Web browser:

Note that you are free to use this parameter at your convenience. 4D simply ignores the value passed beyond the host part of the URL.

For example, you can establish a convention where the value "/Customers/Add" means "go directly to add a new record in the [Customers] table." By supplying the Web users of your database with a list of possible values and/or default bookmarks, you can provide shortcuts to the different parts of your application. This way, Web users can quickly access resources of your Web site without going through the whole navigation path each time they make a new connection to your database.

WARNING: In order to prevent a user from reentering a database with a bookmark created during a previous session, 4D intercepts any URL that corresponds to one of the standard 4D URLs.

• Header of the HTTP request followed by the HTTP body

The second parameter ($2) is the header and the body of the HTTP request sent by the Web browser. Note that this information is passed to your On Web Connection Database Method as it is. Its contents will vary depending on the nature of the Web browser which is attempting the connection.

With Netscape 4.5 running on Mac OS, you may receive a header similar to this:

With Microsoft Internet Explorer 6 running on Windows, you may receive a header similar to this:

If your application deals with this information, it is up to you to parse the header and the body.

• IP address of the Web client

The $3 parameter receives the IP address of the browser's machine. This information can allow you to distinguish between Intranet and Internet connections.

• IP address of the server

The $4 parameter receives the IP address to which the HTTP request was sent. 4D allows for multi-homing, which allows you to exploit machines with more than one IP address. For more information, please refer to the section Web Server Settings.

• User Name and Password

The $5 and $6 parameters receive the user name and password entered by the user in the standard identification dialog box displayed by the browser. This dialog box appears for each connection, if the Use Passwords option has been selected in the Preferences dialog box (see section Connection Security).

Note: If the user name sent by the browser exists in 4D, the $6 parameter (the user's password) is not returned for security reasons.

The On Web Connection Database Method can be used as the entry point for the 4D Web server, either using the special 4DCGI URL, or using customized command URLs. It also plays a role as the entry point in contextual mode (with 4th Dimension and 4D Server).

Warning: Calling a 4D command that displays an interface element (ALERT, DIALOG...) ends the method processing.

The On Web connection database method is therefore called in the following cases:

• When connecting a browser to a 4D Web server operating in contextual mode. The database method is called with the /<action>... URL.

• When 4D receives the /4DMETHOD URL. The Web server switches to contextual mode and the database method is called with the /4DMETHOD/MethodName URL in $1.

• When 4D receives the /4DCGI URL. The database method is called with the /4DCGI/<action> URL in $1.

• When a Web page is called with a URL of type <path>/<file> is not found. The database method is called with the URL (*).

• When a Web page is called with a URL of type <file>/ and no home page has been defined by default. The database method is called with the URL (*).

(*) In this particular cases, the URL received in $1 does NOT start with the "/" character.

To know whether the On Web Connection Database Method was called from a contextual or from a non-contextual connection, you can use the Web Context function, that returns True if it is called from contextual mode, and False otherwise.

Consequently, we suggest that you structure the On Web Connection database method in the following manner:

      `On Web connection database method
   C_TEXT($1;$2;$3;$4;$5;$6)
   If (Web Context) `If in contextual mode
      WithContext ($1;$2;$3;$4;$5;$6)
         `The WithContext contains everything that was in the 
         `On Web connection database method in 4D 6.0.x
   Else
      NoContext ($1;$2;$3;$4;$5;$6)
         `The NoContext method executes the non-contextual
         `processing of requests (generally short)
   End if

In the following example, the parameter $1, sent to the On Web Connection database method, is used to implement Client Home Pages within an organization. The Intranet server operates in contextual mode.

The database has two tables: [Customers] and [Tables]. The On Startup database method shown here initializes interprocess arrays used later by the On Web Connection database method.

      ` On Startup Database Method

      ` Table List
   ARRAY STRING(31;<>asTables;Count tables)
   For ($vlTable;1;Size of array(<>asTables))
      <>asTables{$vlTable}:=Table name($vlTable)
   End for 

      ` Standard Web Actions at Login
   ARRAY STRING(31;<>asActions;2)
   <>asActions{1}:="Add"
   <>asActions{2}:="List"

The main job of the On Web Connection database method is to decipher the extra data passed in the URL after the host part of the address and to act accordingly. The method is as follows:

      ` On Web Connection Database Method

   C_TEXT($1;$2;$3;$4;$5;$6)
   C_TEXT($vtURL)

   If (Web context) `If we are in contextual mode
         ` Just in case, check that $1 is equal to "/" or "/..."
      If ($1="/@")
            ` Copy the URL into a local variable minus the first "/"  
         $vtURL:=Substring($1;2)
            ` Parse the URL and populate a local array with the tokens of the URL
            ` For example, if the URL extra data is "aaa/bbb/ccc", the resulting array
            ` will be of the three elements "aaa", "bbb" and "ccc" in that order
         $vlElem:=0
         ARRAY TEXT($atTokens;$vlElem)
         While ($vtURL # "")
            $vlElem:=$vlElem+1
            INSERT ELEMENT($atTokens;$vlElem)
            $vlPos:=Position("/";$vtURL)
            If ($vlPos>0)
               $atTokens{$vlElem}:=Substring($vtURL;1;$vlPos-1)
               $vtURL:=Substring($vtURL;$vlPos+1)
            Else 
               $atTokens{$vlElem}:=$vtURL
               $vtURL:=""
            End if 
           End while 
            ` If extra data was passed after the HOST part of the URL  
         If ($vlElem>0)
               ` Using the interprocess array initialized in the On Startup DB method
               ` Check whether the 1st token is a name of a table
            $vlTableNumber:=Find in array(<>asTables;$atTokens{1})
            If ($vlTableNumber>0)
                  ` If so, get pointer to this table
               $vpTable:=Table($vlTableNumber)
                  ` Set the Input and Output forms
               INPUT FORM($vpTable->;"Input Web")
               OUTPUT FORM($vpTable->;"Output Web")
                  ` Using an interprocess array initialized in the On Startup DB Method
                  ` Check whether the 2nd token is a known standard action
               $vlAction:=Find in array(<>asActions;$atTokens{2})
               Case of 
                     ` Adding records
                  : ($vlAction=1)
                     Repeat 
                        ADD RECORD($vpTable->;*)
                     Until (OK=0)
                     ` Listing records          
                  : ($vlAction=2)
                     READ ONLY($vpTable->)
                     ALL RECORDS($vpTable->)
                     DISPLAY SELECTION($vpTable->;*)
                     READ WRITE($vpTable->)
                  Else 
                     ` Here could additional standard table actions be implemented
               End case 
            Else 
               ` Here could other standard actions be implemented
            End if 
         End if 
      End if 
         ` Whatever happened above, pursue with the normal Log On process
      WWW NORMAL LOG ON 
   Else
      ...  ` Here could the code managing the non-contextual mode 
         `would be implemented
   End if

At this point, people within the organization can connect to the database and enter a URL according to the convention set by the methods listed. Users can also create bookmarks if they do not want to re-enter the URL each time. In fact, the ultimate solution is to provide each member of the organization with an HTML page that they will use locally to access the database. This HTML page is shown:

In other words, the HTML page ACME_IS.HTM is the Client Local Home Page for the 4D-based information system of the organization. If a user clicks on the Add New Products link, the Web browser will connect to the host having the URL http://123.4.567.89/Products/Add. Provided that the IP address of the database computer is 123.4.567.89, the On Web Connection Database Method receives the extra URL data "/Products/Add" in $1, and therefore proceeds to add records in the [Products] table.

Finally, users can drag and drop links from that page onto the desktop to create Internet Shortcut icons, such as the Add New Customers icon shown here. Simply double-clicking these icons will bring them directly into any part of your 4D Web database.

The source code of this HTML page is listed here:

Database Methods, On Web Authentication Database Method, URLs and Form Actions, Using the Contextual Mode.