4D v16.3

Execute on server

Home

 
4D v16.3
Execute on server

Execute on server 


 

Execute on server ( procedure ; stack {; name {; param {; param2 ; ... ; paramN}}}{; *} ) -> Function result 
Parameter Type   Description
procedure  String in Procedure to be executed within the process
stack  Longint in Stack size in bytes
name  String in Name of the process created
param  Expression in Parameter(s) to the procedure
Operator in Unique process
Function result  Longint in Process number for newly created process or already executing process

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.

Example  

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 )
 
 C_POINTER($1)
 C_TEXT($2)
 C_TIME($vhDocRef)
 C_BLOB($vxData)
 C_LONGINT(spErrCode)
 
  ` 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 )
 
 C_LONGINT($1)
 C_TEXT($2)
 C_BLOB($3)
 C_LONGINT(spErrCode)
 
  ` 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.



See also 

New process

 
PROPERTIES 

Product: 4D
Theme: Processes
Number: 373

 
HISTORY 

Modified: 4D 2004.3

 
ARTICLE USAGE

4D Language Reference ( 4D v16)
4D Language Reference ( 4D v16.1)
4D Language Reference ( 4D v16.2)
4D Language Reference ( 4D v16.3)