On Server Open Connection Database Method

version 6.8 (Modified)

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

With 4D Client, the On Server Open Connection Database Method is called each time:

• 4D Client connects (because the User environment process starts)

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

• 4D Client starts a non-local process, using the New Process command

• A non-local process is started by a menu or using the Execute Method dialog box

In each case with 4D Client, two processes are started—One on the Client machine, one on the Server machine. On the Client machine, the process executes code and send requests to 4D Server. On the Server machine, the process maintains the database environment for the client process (i.e., current selections for user processes) and replies to requests sent by the process running on the Client machine. This is why the process running on the server is said to be a connection process—on the Server machine, over the network, via a connection, it does what the process running on the Client machine would also do if you were running as single-user rather than Client/Server.

When you connect to 4D Server from 4D Insider, a connection process is started on the Server machine in order to maintain a working environment for 4D Insider. This process replies to the requests sent by 4D Insider.

Each time a 4D Open-based application initiates a connection to 4D Server, a connection process is started on the Server machine. This process replies to the requests sent via 4D Open and maintains the database context of the connection (i.e., current selections).

Important: Web 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. For more information, see the description of this database method in the 4th Dimension 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 connection processes. They execute code on the Server machine, but do not reply to requests exchanged by 4D Client (or other Clients) and 4D Server.

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

For example, if a 4D Client connects to a 4D Server interpreted database, the User Environment, 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 User Environment connection process, the second time within the client registration process, and the third time within the Design connection 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 connection 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 connection process has not yet been named (PROCESS PROPERTIES will not at this point return the name of the connection 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.

With an interpreted database, 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 connection process. Because the On Server Close Connection Database Method will eventually be invoked within the same connection process, you may think that you can maintain information between the two methods using process variables. This will not work in compiled mode.

With a compiled database, the On Server Open Connection Database Method shares, with other database methods as well as triggers, a common process variable table maintained on the Server machine. This architecture has two purposes: to allow compiled code to run and to reduce memory consumption. First, you can access any process variable from within a database method or a trigger. The process variables need to be there. Second, creating one process table for each database method or trigger phase would consume memory and initialization time. Conclusion: Do NOT rely on process variables when executing On Server Open Connection Database Method and On Server Close Connection Database Method. Use data stored in interprocess variables or in table.

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:

Note: Since 4D Server version 6.8, the $3 parameter always returns 2 or 29.

These three 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 connection 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 three 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
   [Server Log]NC ID:=$3
   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]NC ID=$3;*)
   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 4D Client connections as well as a 4D Insider connection:

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.