SET DATABASE PARAMETER

version 2004.5 (Modified)

SET DATABASE PARAMETER ({table; }selector; value)

The SET DATABASE PARAMETER command allows you to modify various internal parameters of the 4D database.

selector designates the database parameter to modify. 4th Dimension offers predefined constants, which are located in the "Database Parameters" theme. The following table lists each constant and describes its scope:

(*) The table parameter is ignored in this case.

(**) This selector can only be read (see Get database parameter command).

(***) If the value parameter is negative, the setting is local to the current process and is reset for the next request.

value designates the value of the parameter. The value passed depends on the parameter that you want to modify. Here are the possible values for each selector:

Selector = 1 (Seq Order Ratio)

• Values: 0 -> 100,000

• Description: Ratio (between the number of selected records and the total number of records) below which the sorts are executed in sequential mode. This ratio must be multiplied by one hundred thousand. The default value is 9,000 (= 9 %).

Selector = 2 (Seq Access Optimization)

• Values: 0 or 1 (0 = not optimized, 1 = optimized)

• Description: Optimization mode for sequential accesses (sorts, searches or selection to array). In optimized mode, 4D will read numerous records at a time from the disk but will not place them in the cache. This mode is especially useful if the size of the cache is low. By default, the value is 1 (optimized mode).

Selector = 3 (Seq Distinct Values Ratio)

• Values: 0 -> 100,000

• Description: Ratio (between the number of selected records and the total number of records) below which the DISTINCT VALUES command will be executed in sequential mode. This ratio must be multiplied by one hundred thousand.

Selector = 4 (Index Compacting)

• Values: 0 or 1 (0 = no compacting, 1 = compacting)

• Description: This selector allows you to enable or disable the compacting of the index pages. By default, the value is 1 (indexes are compacted when necessary).

Index pages can, in databases containing a lot of indexes and records, use a lot of space in the memory cache of 4D. When the cache is full and 4D needs additional space, the data in the cache is not directly unloaded. Before unloading data to gain space, the program is going to check if it can gain space by compacting the index pages. This alternative allows you to avoid reloading the data later.

Selector = 5 (Seq Query Select Ratio)

• Values: 0 -> 100,000

• Description: Ratio (between the number of selected records and the total number of records) below which the QUERY SELECTION command will be executed in sequential mode. This ratio must be multiplied by one hundred thousand.

Selector = 6 (Minimum Web Process)

• Values: 0 -> 32,767

• Description: Minimum number of Web processes to maintain in non-contextual mode with 4th Dimension and 4D Server. By default, the value is 0 (see below).

Selector = 7 (Maximum Web Process)

• Values: 0 -> 32,767

• Description: Maximum number of Web processes to maintain in non-contextual mode with 4th Dimension and 4D Server. By default, the value is 10.

In non-contextual mode, for the Web server to be reactive, 4D delays the Web processes for 5 seconds and reuses them to execute any possible future HTTP queries. In terms of performance, this is actually more advantageous than creating a new process for each query. Once a Web process is reused, it is delayed again for 5 seconds. When the maximum number of Web processes has been reached, the web process is then aborted. If no query has been attributed to a Web process within the 5 second delay, the process is aborted, except if the minimum number of Web processes has been reached (in which case the process is delayed again).

These parameters allow you to adjust how your Web server operates in relation to the number of requests and the memory available as well as other parameters.

Selector = 8 (Web conversion mode)

• Values: 0, 1, 2 or 3

0= (Default mode) Conversion to the HTML 4.0 format if it is allowed by the browser. Otherwise, HTML 3.2 format + array use.

1= 6.0.x conversion mode

2= 6.5 conversion mode

3= Conversion to the HTML 4.0 format + CSS-P (since version 6.5.2)

• Description: Conversion mode of 4D forms for the Web with 4th Dimension and 4D Server. By default, the 4D Web Server uses the cascading style sheets (CSS1) to generate HTML pages similar to the 4D forms displayed in 4th Dimension. With this feature, the forms might not convert correctly for databases created with versions of 4D prior to 6.7. Consequently, you have the possibility of setting the form conversion mode.

This mode is set only for the process (Web context) within which the SET DATABASE PARAMETER was called. It can be called from within the On Web Connection Database Method to ensure the compatibility of all the forms of a database, or just before a single form is displayed. If the command is called outside either the contextual mode or a Web process, it has no effect.

Note: An additional selector can be used with the Get database parameter command: Database Cache Size (9). This selector cannot be used with the SET DATABASE PARAMETER command. For more information, please refer to the description of the Get database parameter command.

Selector = 10 (4th Dimension Scheduler)

Selector = 11 (4D Server Scheduler)

Selector = 12 (4D Client Scheduler)

• Values: For these three selectors, the value parameter is expressed in hexadecimal 0x00aabbcc detailed as follows:

aa = minimum number of ticks per call to the system (0 to 100 included).

bb = maximum number of ticks per call to the system (0 to 100 included).

cc = number of ticks between calls to the system (0 to 20 included).

If one of the values is out of range, 4D sets it to its maximum. You can pass one of the following preset standard values in the value parameter:

value = -1: maximum priority allocated to 4D,

value = -2: average priority allocated to 4D,

value = -3: minimum priority allocated to 4D.

• Description: This parameter allows you to dynamically set the 4D system internal calls. Depending on the selector, the scheduler value will be set for:

- 4th Dimension (single user) and 4D Tools, when the command is called from 4th Dimension (selector=10).

- 4D Server when the command is called from 4D Server (selector=11).

- 4D Client when the command is called from 4D Client (selector=12).

(See example 1).

Note: The operation of selector 12 (4D Client Scheduler) differs according to whether the SET DATABASE PARAMETER command is executed on the server machine or on the client machine:

- If the command is executed on the server machine, the new value will be applied to all the client machines that connect to it subsequently.

- If the command is executed on the client machine, the new value is applied to the client machine immediately as well as to all the client machines that connect to the server subsequently.

You can use this operation to implement a dynamic and individualized management of priority for each client machine. This consists in executing the command initially on the client machine to be configured, then a second time on the server machine using the default value, which will then be used for the client machines that connect to it subsequently.

This operation is in effect in 4th Dimension starting with versions 6.8.6, 2003.3 and 2004.

Selector = 13 (4D Server Timeout)

• Description: This parameter allows changing the value of the 4D Server timeout. The default 4D Server timeout value is defined on the "Client-Server/Configuration" page of the Preferences dialog box on the server side.

The 4D Server Timeout selector allows you to set in the corresponding value parameter a new timeout, expressed in minutes. This feature is particularly useful to increase the timeout before executing a blocking and time-consuming operation on the client, such as printing a large number of pages, which can cause an unexpected timeout.

You also have two options:

- If you pass a positive value in the value parameter, you set a global and permanent timeout: the new value is applied to all process and is stored in the preferences of the 4D application (equivalent to change in the Preferences dialog box).

- If you pass a negative value in the value parameter, you set a local and temporary timeout: The new value is applied to the calling process only (the other processes keep the default values) and is reset to default as soon as the server receives any signal of activity from the client — for example, when the operation is finished. This option is useful for managing long operations initiated by 4D plug-ins.

To set the "No timeout" option, pass 0 in value.

(See example 2).

Selector = 14 (4D Client Timeout)

• Description: This parameter allows changing the value of the 4D Client timeout. The default 4D Client timeout value is defined on the "Client-Server/Configuration" page of the Preferences dialog box on the client side.

For more information about this selector, refer to 4D Server Timeout selector description (13).

The 4D Client Timeout selector can be used in very specific cases.

Selector = 15 (Port ID)

• Description: This parameter allows changing on the fly the TCP port ID used by the 4D Web server with 4th Dimension and 4D Server. The default value, which can be set on the "Web/Configuration" page of the Preferences dialog box, is 80. You can use the constants of the "TCP Port Numbers" theme for the value parameter.

The Port ID selector is useful for 4D Web Servers compiled and merged with 4D Runtime (in which there is no access to the Design mode). For more information about the TCP port ID, refer to the Web Services, Configuration section.

Selector = 16 (IP Address to listen)

• Description: This parameter allows the user to change on the fly the IP address on which the 4D Web server will receive HTTP requests with 4th Dimension and 4D Server. By default, no specific address is defined (value = 0). This parameter can be set in the Preferences of the database.

The IP Address to listen selector is useful for 4D Web Servers compiled and merged with 4D Runtime (in which there is no access to the Design mode).

You will pass in the value parameter a hexadecimal IP address. That is, to designate a IP address such as "a.b.c.d", you should write:

   C_LONGINT($addr)
   $addr:=($a<<24)|($b<<16)|($c<<8)|$d
   SET DATABASE PARAMETER(IP Address to listen;$addr)

See also example 3. For more information on how to designate the IP address, refer to the Web Services, Web Server Settings section.

Selector = 17 (Character set)

• Values:

0: Western European

1: Japanese

2: Chinese

3: Korean

4: User-defined

5: Reserved

6: Central European

7: Cyrillic

8: Arabic

9: Greek

10: Hebrew

11: Turkish

12: Baltic

• Description: This parameter allows the user to change on the fly the character set that the 4D Web Server (with 4th Dimension and 4D Server) should use to communicate with browsers connecting to the database. The default value actually depends on the language of the operating system.

This parameter can be set in Preferences of the database. The Character set selector is useful for 4D Web Servers compiled and merged with 4D Runtime (in which there is no access to the Design mode).

Selector = 18 (Max Concurrent Web Processes)

• Values: You can pass any value between 10 and 32 000. The default value is 32 000.

• Description: This parameter allows setting the strictly high limit of concurrent Web processes of any type (contextual, non-contextual or belonging to the "pool of processes"— see selector 7, Maximum Web Process) supported by the 4D Web Server with 4th Dimension and 4D Server. When this number (minus one) is reached, 4D will not create any other processes and returns the HTTP status 503 - Service Unavailable to all new requests.

This parameter can prevent the 4D Web Server from saturation, which can occur when an exceedingly large number of concurrent requests are sent, or when too many context creations are requested. This parameter can also be set in the Preferences dialog box (see the Web Services, Web Server Settings section).

In theory, the maximum number of Web processes is the result of the following formula: Available memory/Web process stack size. Another solution is to visualize the information on Web processes displayed in the Runtime Explorer: the current number of Web processes and the maximum number reached since the Web server boot are indicated.

Note: If you pass a value inferior to the high limit of the "pool of processes," this limit is reduced in order to match the value of the selector 18. If necessary, the low limit of the pool (see selector 6, Minimum Web Process) is also modified.

Selector = 19 (Client Minimum process Web)

Selector = 20 (Client Maximum process Web)

Selector = 21 (Client Max Web requests size)

Selector = 22 (Client Port ID)

Selector = 23 (Client IP Address to listen)

Selector = 24 (Client Character set)

Selector = 25 (Client Max Concurrent Web Proc)

• Values: Identical to those of the corresponding 4th Dimension or 4D Server selectors (see selectors 6 to 8, 15 to 18 and 27).

• Description: These selectors are used to specify the operating parameters of 4D Client machines used as Web servers.

The values defined using these selectors are applied to all the 4D Client machines used as Web servers. If you want to define values only for certain 4D Client machines, use the 4D Client Preferences dialog box.

Selector = 26 (Cache writing mode)

• Values: 0 or 1 (0 = disable, 1 = enable).

• Description: Enabling or disabling of the optimized cache writing mode. By default, the value is 1 (enabled).

The optimized cache writing mode, enabled by default in 4th Dimension starting with version 2003, considerably accelerates 4D applications, in particular under Mac OS.

Selector = 27 (Maximum Web requests size)

• Values: 500 000 to 2 147 483 648.

• Description: Maximum size (in bytes) of incoming HTTP requests (POST) that the Web server is authorized to process. By default, the value is 2 000 000, i.e. a little less than 2 MB. Passing the maximum value (2 147 483 648) means that, in practice, no limit is set.

This limit is used to avoid Web server saturation due to incoming requests that are too large. When a request reaches this limit, the 4D Web server refuses it.

Selector = 28 (4D Server Log Recording)

• Values: 0 or from 1 to X (0 = do not record, 1 to X = sequential number, added to the file name).

• Description: Starts or stops the recording of standard requests received by 4D Server (excluding Web requests). By default, the value is 0 (requests not recorded).

4D Server lets you record each request received by the server machine in a log file. When this mechanism is enabled, the log file is created next to the database structure file. Its name is "4DRequestsLogX," where X is the sequential number of the log. Once the file reaches a size of 10 MB, it is closed and a new file is generated, with an incremented sequential number. If a file of the same name already exists, it is replaced directly. You can set the starting number of the sequence using the value parameter.

This text file stores various information concerning each request in a simple tabulated format: time, process number, user, size of request, processing duration, etc. This information can be particularly useful when fine tuning the application or for statistical purposes. It can be imported, for example, into a spreadsheet software in order to be processed.

Note: It is possible to manually enable or disable the recording of requests using the Ctrl+Alt+L shortcut under Windows or the Command+Option+L shortcut under Mac OS.

Selector = 29 (Web Log Recording)

• Values: 0 or 1 (0 = do not record, 1 = record).

• Description: Starts or stops the recording of Web requests received by the Web server of 4th Dimension or 4D Server. By default, the value is 0 (requests not recorded).

The log of Web requests is stored as a text file named "logweb.txt" that is automatically placed next to the database structure file. This file is in CLF (Common LogFile Format) or NCSA format, which is recognized by most Web site analysis tools.

This file can also be activated on the "Web/Advanced" page of the 4th Dimension Preferences.

Selector = 30 (Client Web Log Recording)

• Values: 0 or 1 (0 = do not record, 1 = record).

• Description: Starts or stops the recording of Web requests received by the Web servers of all the client machines. By default, the value is 0 (requests not recorded).

The operation of this selector is identical to that of selector 29; however, it applies to all the 4D Client machines used as Web servers. If you only want to set values for certain client machines, use the Preferences dialog box of 4D Client.

Selector = 31 (Table Sequence Number)

• Values: Any longint value.

Description: This selector is used to modify or get the current unique number for records of the table passed as parameter. "Current number" means "last number used": if you modify this value using SET DATABASE PARAMETER, the next record will be created with a number that consists of the value passed + 1 (this new number is the one returned by the Sequence number command).

By default, this unique number is set by 4th Dimension and corresponds to the order of record creation. For additional information, refer to the documentation of the Sequence number command.

Selector = 32 (Real Display Precision)

• Values: Any positive longint value.

• Description: This selector lets you modify or get the number of non-significant digits truncated from the right by the real screen display algorithm. This value is set for the current application and session.

By default, the value of this option is 4. The value 0 indicates that the default value is used and that the parameter has not been modified during the session.

For historical reasons, 4th Dimension works with real numbers stored on 10 bytes and converts them to 8 bytes during processing (see the Display of Real Numbers section). This is entirely transparent and does not affect calculations; however certain results may not be displayed as anticipated. For example, the operation 4,1-4,09 displays the result 0.009999999999999780000, but searching for 0.01 finds the correct value.

Here is how 4D goes about displaying a real number: let's take the value 8.97499999999996158 obtained by a calculation as an example (the expected result would normally be 8.975). The algorithm which rounds off most accurately removes the last four digits (6158) by default and then checks whether the last remaining digit is a 0 or a 9. If it is 0, the algorithm goes back to the first 0 and removes all the others. If the value is 9, the algorithm goes back to the first 9 and rounds the decimal up to the next value. In our example, the value 8.974999999999996158 is thus transformed into 8.975.

It may happen that certain results end with 5 non-significant digits, like 8.9749999999999986158 for instance. In this case, the algorithm cannot round the value off correctly because the last remaining digit (after removing the last four) is neither 0 nor 9 and it will thus do nothing.

You may want for the precision algorithm to truncate more or less digits according to the specific characteristics of your database. In this case, pass a custom value. Except for zero (4D internal value choice), this value will indicate the number of digits truncated by the precision algorithm.

Keep in mind that this setting does not affect the display of numbers, nor their internal processing.

• Selector = 33 (TCP_NODELAY)

• Possible values: 0 or 1 (0 = disable, 1 = enable)

• Description: Enabling or disabling of the TCP_NODELAY network option. This option, which is internal to the TCP/IP protocol, controls a network communications optimization mechanism. It can be set separately for the server machine and the client machines. By default, the value is 1 (option enabled) on all the machines (server and clients).

In specific cases, in particular in the case of client/server connections by DSL or by VPN (Virtual Private Network), disabling this option can noticeably improve application performance. This operation should be carried out with caution and must be accompanied by load testing in the different client/server configurations.

If you modify this value, it will be necessary to restart the application in order for the new value to be taken into account.

• Selector = 34 (Debug Log Recording)

• Possible values: 0, 1 or 2 (0 = do not record, 1 = record, 2 = record in detailed mode)

• Description: Starts or stops the sequential recording of events occurring at the 4D programming level, intended for debugging the application. By default, the value is 0 (events are not saved).

When this mode is enabled, various types of information can be recorded, more particularly:

- For each event, the number of milliseconds since the creation of the file and the process number ([n]),

- The execution of each 4D command (cmd) and each calling of a plug-in (plugInName); in this case, the stack level is indicated (n),

- Each calling of project methods (meth), object methods (obj) and form methods (form),

- When the detailed mode is activated (value = 2), additional information concerning the plug-ins are recorded: events in the plug-in areas (EventCode) and calls to 4D by the plug-ins (externCall).

The events are stored in a file named "4DDebugLog.txt" that is automatically placed next to the database structure file. Each event is systematically recorded in the file before its execution, which guarantees its presence in the file even when the application quits unexpectedly. Be careful, this file is erased and rewritten each time the application is launched.

This option can be activated for any type of 4D application (4th Dimension single user, 4D Server, 4D Client, 4D Runtime), in interpreted or compiled mode).

Note: This option is provided solely for the purpose of debugging and must not be put into production since it may lead to deterioration of the application performance and saturation of the hard disk.

• Selector = 35 (Client Server Port ID)

• Possible values: 0 to 65535

• Description: This parameter can be used to change the TCP port number where the 4D Server publishes the database (bound for 4D Client machines) by programming. By default, the value is 19813.

Customizing this value means that several 4D client-server applications can be used on the same machine with the TCP protocol; in this case, you must indicate a different port number for each application.

The value is stored in the database structure file. It can be set with 4th Dimension single-user but is only taken into account in client-server configuration.

When you modify this value, it is necessary to restart the server machine in order for the new value to be taken into account.

• Selector = 36 (WEDD Signature)

• Possible values: String of 1 to 255 c haracters.

• Description: This parameter can be used to modify the WEDD signature of the open database (structure file and data file). By default, this signature is blank (the parameter is not defined). Keep in mind that the signature is case senstive.

The WEDD signature is used to associate a structure file with a specific data file. A structure file containing a WEDD signature can only be opened with the data file containing the same WEDD signature and vice versa. For more information about the WEDD signature, please refer to the Design Reference manual.

Setting this value by programming facilitates the distribution of upgrades for applications that have a custom signature.

Note: When you use this selector with the Get database parameter command, the string defined as the WEDD signature is returned in the optional stringValue parameter and the command returns 0.

• Selector = 37 (Invert Objects)

• Possible values: 0, 1 or 2 (0 = mode disabled, 1 = automatic mode, 2 = mode enabled)

• Description: Configuration of the "object inversion" mode which is used to invert forms, objects, menu bars, and so on, in Custom Menus mode when the database is displayed under Windows in a right-to-left language. This mode can also be configured on the Database/Script Manager page of the application Preferences.

- Value 0 indicates that the mode is never enabled, regardless of the system configuration (corresponds to the No value in the Preferences).

- Value 1 indicates that the mode is enabled or disabled depending on the system configuration (corresponds to the Automatic value in the Preferences).

- Value 2 indicates that the mode is enabled, regardless of the system configuration (corresponds to the Yes value in the Preferences).

For more information, refer to the Design Reference manual of 4D.

• Selector = 39 (HTTPS Port ID)

• Possible values: 0 to 65535

• Description: This selector can be used to modify by programming the TCP port number used by the 4th Dimension and 4D Server Web server for secure connections via SSL (HTTPS protocol). The HTTPS port number is set on the "Web/Configuration" page of the Preferences dialog box. For more information, please refer to the Web Server Settings section.

By default, the value is 443 (standard value). You can use the constants of the "TCP Port Numbers" theme for the value parameter.

• Selector = 40 (Client HTTPS Port ID)

• Possible values: 0 to 65535

• Description: This selector can be used to modify by programming the TCP port used by the Web servers of the client machines for secure connections via SSL (HTTPS protocol). By default, the value is 443 (standard value).

This selector operates exactly the same way as selector 39; however, it applies to all the 4D Client machines used as Web servers. If you only want to modify the value of certain specific client machines, use the Preferences dialog box of 4D Client.

1. The following method allows you to define the scheduler values if 4D single user is running:

   C_LONGINT($ticksbtwcalls;$maxticks;$minticks;$lparams)
   If(Application type=4th Dimension) ` if 4D single user is used
      $ticksbtwcalls:=12
      $maxticks:=20
      $minticks:=7
      $lparams:=($minticks<<16)|($maxticks<<8)|$ticksbtwcalls
      SET DATABASE PARAMETER (4th Dimension scheduler;$lparams)
   End if

2. The following statement will avoid any unexpected timeout:

      `Increasing the timeout to 3 hours for the current process
   SET DATABASE PARAMETER(4D Server Timeout;-60*3)
      `Executing a time-consuming operation with no control from 4D
   ...
   WR PRINT MERGE (Area;3;0)
   ...

3. The IP address 192.193.194.195 will be set with the following statement:

   SET DATABASE PARAMETER(IP Address to listen;0xC0C1C2C3)

DISTINCT VALUES, Get database parameter, QUERY SELECTION.