On Server Open Connection Database Method

version 11.2 (Modified)

The On Server Open Connection Database Method is called once on the Server machine each time a connection process is started by a 4D remote workstation. The On Server Open Connection Database Method is NOT invoked by any 4D environment other than 4D Server.

The On Server Open Connection Database Method is called each time:

• a remote 4D connects (because the Application process starts)

• a remote 4D opens the Design environment (because the Design process starts)

• a remote 4D starts a non-local process, using the New Process command, a menu command or using the Execute Method dialog box

In each case witha remote 4D, three processes are started—One on the client machine and two others on the server machine. On the client machine, the process executes code and send requests to 4D Server. On the server machine, the 4D Client Process maintains the database environment for the client process (i.e., current selections and locking of records for user processes) and replies to requests sent by the process running on the client machine. The 4D Client Database process is in charge of monitoring the corresponding 4D Client process.

Important: Web connections and SQL connections do not invoke the On Server Open Connection Database Method. When a Web browser connects to 4D Server, the On Web Authentication Database Method (if any) and/or the On Web Connection Database Method are invoked. When 4D Server receives an SQL query, the On SQL Authentication Database Method (if one exists) is called. For more information, see the description of this database method in the 4D Language Reference manual.

Important: When a Stored Procedure is started, the On Server Open Connection Database Method is NOT invoked. Stored Procedures are server processes, not 4D Client processes. They execute code on the Server machine, but do not reply to requests exchanged by a 4D client (or other clients) and 4D Server.

The On Server Open Connection Database Method is executed on the 4D Server machine within the 4D Client process that provoked the call to the method.

For example, if a remote 4D connects to a 4D Server interpreted database, the user process, the Design process and the client registration process (by default) for that client are started. The On Server Open Connection Database Method is therefore executed three times in a row—the first time within the Application process, the second time within the client registration process, and the third time within the Design process. If the three process are respectively the sixth, seventh and eighth process to be started on the Server machine, and if you call Current process from within the On Server Open Connection Database Method, the first time Current process returns 6, the second time 7 and the third time 8.

Note that On Server Open Connection Database Method executes on the Server machine. It executes within the 4D Client process running on the Server machine, independent of the process running on the client side. In addition, at the moment when the method is invoked, the 4D Client process has not yet been named (PROCESS PROPERTIES will not at this point return the name of the 4D Client process).

The On Server Open Connection Database Method has no access to the process variable table of the process running on the Client side. This table resides on the Client machine, not on the Server machine.

When the On Server Open Connection Database Method accesses a process variable, it works with a private and dynamically created process variable table for the 4D Client process.

4D Server passes three Long Integer parameters to the On Server Open Connection Database Method and expects a Long Integer result. The method must therefore be explicitly declared with three Long Integer parameters as well as a Long Integer function result:

   C_LONGINT($0;$1;$2;$3)

If you do not return a value in $0, thereby leaving the variable undefined or initialized to zero, 4D Server assumes that the database method accepts the connection. If you do not accept the connection, you return a non-null value in $0.

This table details the information provided by the three parameters passed to the database method:

These ID numbers are not directly usable as sources of information to be passed as, for example, parameters to a 4D command. However, they provide a way to uniquely identify a 4D Client process between the On Server Open Connection Database Method and the On Server Close Connection Database Method. At any moment of a 4D Server session, the combination of these values is unique. By storing this information in an interprocess array or a table, the two database methods can exchange information. In the example at the end of this section, the two database methods use this information to store the date and time of the beginning and end of a connection in the same record of a table.

1. The following example shows how to maintain a log of the connections to the database using the On Server Open Connection Database Method and the On Server Close Connection Database Method. The [Server Log] table (shown below) is used to keep track of the connection processes:

The information stored in this table is managed by the On Server Open Connection Database Method and the On Server Close Connection Database Method listed here:

      ` On Server Open Connection Database Method
   C_LONGINT($0;$1;$2;$3)
      ` Create a [Server Log] record
   CREATE RECORD([Server Log])
   [Server Log]Log ID:=Sequence number([Server Log])
      ` Save the Log Date and Time
   [Server Log]Log Date:=Current date
   [Server Log]Log Time:=Current time
      ` Save the connection information
   [Server Log]User ID:=$1
   [Server Log]Connection ID:=$2
   SAVE RECORD([Server Log])
        ` Returns no error so that the connection can continue
   $0:=0

      ` On Server Close Connection Database Method
   C_LONGINT($1;$2;$3)
      ` Retrieve the [Server Log] record
   QUERY([Server Log];[Server Log]User ID=$1;*)
   QUERY([Server Log]; & ;[Server Log]Connection ID=$2;*)
   QUERY([Server Log]; & ;[Server Log]Process ID=0)
      ` Save the Exit date and time
   [Server Log]Exit Date:=Current date
   [Server Log]Exit Time:=Current time
      ` Save the process information
   [Server Log]Process ID:=Current process
   PROCESS PROPERTIES([Server Log]Process ID;$vsProcName;$vlProcState;$vlProcTime)
   [Server Log]Process Name:=$vsProcName
   SAVE RECORD([Server Log])

Here are some entries in the [Server Log] showing several remote connections:

2. The following example prevents any new connection from 2 to 4 A.M.

      ` On Server Open Connection Database Method
   C_LONGINT($0;$1;$2;$3)

   If((?02:00:00?<=Current time)&(Current time<?04:00:00?))
      $0:=22000
   Else
      $0:=0
   End if

Database Methods, On Server Close Connection Database Method.