Execute on server

The Execute on server command starts a new process on the Server machine (if it is called in Client/Server) or on the same machine (if it is called in single-user) and returns the process number for that process.

You use this function to start a stored procedure. For more information about stored procedures, see the section Stored Procedures in the 4D Server Reference manual.

If you call Execute on server on a Client machine, the command returns a negative process number. If you call it on the Server machine, it returns a positive process number. Note that calling New process on the Server machine does the same thing as calling Execute on server.

If the process could not be created (for example, if there is not enough memory), Execute on server returns zero (0) and an error is generated. You can catch this error using an error-handling method installed using ON ERR CALL.

In procedure, you pass the name of the process method for the new process. After 4D has set up the context for the new process, it starts executing this method, which therefore becomes the process method.

The stack parameter allows you indicate the amount of memory allocated for the stack of the process. It is the space in memory used to “pile up” method calls, local variables, parameters in subroutines, and stacked records.

• Pass 0 in stack to use a default stack size, suitable for most applications (recommended setting).
• In certain particular cases, you may want to use a custom value. It must be expressed in bytes. It is recommended to pass a minimum of 64 KB (around 64,000 bytes) and you case use values above 512 KB in particular if the process can perform large chain calls (subroutines calling subroutines in cascade.

Note: The stack is NOT the total memory for the process. Processes share memory for records, interprocess variables, and so on. A process also uses extra memory for storing its process variables. The stack contains various items of 4D internal information; the amount of information kept on the stack depends on the number of nested method calls the process will employ, the number of forms that it will open before closing them and the number and size of local variables used in each nested method call.

Note for 64-bit 4D Server: The stack for a process executed on a 64-bit 4D Server usually requires more memory than on a 32-bit 4D Server (about twice as much). Make sure that you check this parameter when your code is intended for execution on a 64-bit 4D Server.

You pass the name of the new process in name. In single-user, this name will appear in the list of processes of the Runtime Explorer and will be returned by the PROCESS PROPERTIES command when applied to this new process. In Client/Server, this name will appear in blue in the Stored Procedure list of the 4D Server main window.

You can omit this parameter; if you do so, the name of the process will be the empty string.

Warning: Contrary to New process, do not attempt to make a process local in scope by prefixing its name with the dollar sign ($) while using Execute on server. This will work in single-user, because Execute on server acts as New process in this environment. On the other hand, in Client/Server, this will generate an error.

You can pass parameters to the process method. You can pass parameters in the same way as you would pass them to a subroutine. However, there is a restriction—you cannot pass pointer expressions. Also, remember that arrays cannot be passed as parameters to a method. Upon starting execution in the context of the new process, the process method receives the parameters values in $1, $2, etc.

Note: If you pass parameters to the process method, you must pass the name parameter; it cannot be omitted in this case.

If you pass a 4D object (C_OBJECT) as param or return value, the JSON form is used in UTF-8 for the server. If the C_OBJECT object contains pointers, their dereferenced values are sent, and not the pointers themselves.

Specifying this last parameter tells 4D to first check whether or not a process with the name you passed in name is already running. If it is, 4D does not start a new process and returns the process number of the process with that name.

The following example shows how importing data can be dramatically accelerated in Client/Server. The Regular Import method listed below allows you to test how long it takes to import records using the IMPORT TEXT command on the Client side:

With the regular import data, 4D Client performs the parsing of the text file, then, for each record, create a new record, fills out the fields with the imported data and sends the record to the Server machine so it can be added to the database. There are consequently many requests going over the network. A way to optimize the operation is to use a stored procedure to do the job locally on the Server machine. The Client machine loads the document into a BLOB, start a stored procedure passing the BLOB as parameter. The stored procedure stores the BLOB into a document on the server machine disk, then imports the document locally. The import data is therefore performed locally at a single-user version-like speed because most the network requests have been eliminated. Here is the CLIENT IMPORT project method. Executed on the Client machine, it starts the SERVER IMPORT stored procedure listed just below:

Here is the SERVER IMPORT project method executed as a stored procedure:

Once these two project methods have been implemented in a database, you can perform a “Stored Procedure-based” import data by, for instance, writing:

With some benchmarks you will discover that using this method you can import records up to 60 times faster than the regular import.