Version: Next

Execute on server

Execute on server ( procedure ; stack {; name {; param {; param2 ; ... ; paramN}}}{; *} ) : Integer

Parameter	Type		Description
procedure	Text	→	Procedure to be executed within the process
stack	Integer	→	Stack size in bytes
name	Text	→	Name of the process created
param	Expression	→	Parameter(s) to the procedure
*	Operator	→	Unique process
Function result	Integer	←	Process number for newly created process or already executing process

Description

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.

Process Method

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.

Process Stack

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 set a custom value. It must be expressed in bytes. This setting should be used with precaution, it depends on the process chain call and the platform.

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.

Process Name

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 info 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.

Parameter to Process Method

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 an object or a collection as param, a copy is sent (and not a reference) and the JSON form is used in UTF-8 for the server. If the object or collection contains pointers, their dereferenced values are sent, and not the pointers themselves.

Optional * Parameter

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.

Example 1

You want to log some information from the remote side in a text file on the server machine.

You execute the method with local information as parameters on a remote machine:

 $process:=Execute on server("WriteLog";0;"WriteLogFile";Current user;String(Current date);String(Current time))

The WriteLog method will be executed on the server. It contains, for example:

 var $1;$2;$3 : Text
 TEXT TO DOCUMENT(Get 4D folder(Logs folder)+"Log"+$1+".txt";$2+" "+$3)

Example 2

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:

  // Regular Import Project Method
 $vhDocRef:=Open document("")
 If(OK=1)
    CLOSE DOCUMENT($vhDocRef)
    FORM SET INPUT([Table1];"Import")
    $vhStartTime:=Current time
    IMPORT TEXT([Table1];Document)
    $vhEndTime:=Current time
    ALERT("It took "+String(0+($vhEndTime-$vhStartTime))+" seconds.")
 End if

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:

  // CLIENT IMPORT Project Method
  // CLIENT IMPORT ( Pointer ; String )
  // CLIENT IMPORT ( -> [Table] ; Input form )
 
 var $1 : Pointer
 var $2 : Text
 var $vhDocRef : Time
 var $vxData : Blob
 var spErrCode : Integer
 
  // Select the document do be imported
 $vhDocRef:=Open document("")
 If(OK=1)
  // If a document was selected, do not keep it open
    CLOSE DOCUMENT($vhDocRef)
    $vhStartTime:=Current time
  // Try to load it in memory
    DOCUMENT TO BLOB(Document;$vxData)
    If(OK=1)
  // If the document could be loaded in the BLOB,
  // Start the stored procedure that will import the data on the server machine
       $spProcessID:=Execute on server("SERVER IMPORT";0;
       "Server Import Services";Table($1);$2;$vxData)
  // At this point, we no longer need the BLOB in this process
       CLEAR VARIABLE($vxData)
  // Wait for the completion of the operation performed by the stored procedure
       Repeat
          DELAY PROCESS(Current process;300)
          GET PROCESS VARIABLE($spProcessID;spErrCode;spErrCode)
          If(Undefined(spErrCode))
  // Note: if the stored procedure has not initialized its own instance
  // of the variable spErrCode, we may be returned an undefined variable
             spErrCode:=1
          End if
       Until(spErrCode<=0)
  // Tell the stored procedure that we acknowledge
       spErrCode:=1
       SET PROCESS VARIABLE($spProcessID;spErrCode;spErrCode)
       $vhEndTime:=Current time
       ALERT("It took "+String(0+($vhEndTime-$vhStartTime))+" seconds.")
    Else
       ALERT("There is not enough memory to load the document.")
    End if
 End if

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

  // SERVER IMPORT Project Method
  // SERVER IMPORT ( Long ; String ; BLOB )
  // SERVER IMPORT ( Table Number ; Input form ; Import Data )
 
 var $1 : Integer
 var $2 : Text
 var $3 : Blob
 var spErrCode : Integer
 
  // Operation is not finished yet, set spErrCode to 1
 spErrCode:=1
 $vpTable:=Table($1)
 FORM SET INPUT($vpTable->;$2)
 $vsDocName:="Import File "+String(1+Random)
 DELETE DOCUMENT($vsDocName)
 BLOB TO DOCUMENT($vsDocName;$3)
 IMPORT TEXT($vpTable->;$vsDocName)
 DELETE DOCUMENT($vsDocName)
  // Operation is finished, set spErrCode to 0
 spErrCode:=0
  // Wait until the requester Client got the result back
 Repeat
    DELAY PROCESS(Current process;1)
 Until(spErrCode>0)

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

 CLIENT IMPORT(->[Table1];"Import")

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

Example 3

Refer to the SP-Based Services (Example) section in the 4D Server Reference manual.

Properties


Command number	373
Thread safe	✗

Description​

Process Method​

Process Stack​

Process Name​

Parameter to Process Method​

Optional * Parameter​

Example 1​

Example 2​

Example 3​

See also​

Properties​