Execute on server

version 2004.3 (Modified)

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

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 Execute on server 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 Execute on server on the Server machine, Execute on server 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 method, 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: In stack, you pass 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. It is expressed in bytes; it is recommended to pass at least 64K (around 64,000 bytes), but you can pass more if the process can perform large chain calls (subroutines calling subroutines in cascade). For example, you can pass 200K (around 200000 bytes), if necessary.

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 only holds local variables, method calls, parameters in subroutines and stacked records.

Process Name: You pass the name of the new process in name. In single-user, this name will appear in the Process List window of the Design environment, and will be returned by the command PROCESS PROPERTIES 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.

A process name can be up to 31 characters long. 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: Starting with version 6, 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.

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

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)
      INPUT FORM([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_STRING(31;$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";32*1024;
                              "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_STRING(31;$2)
   C_BLOB($3)
   C_LONGINT(spErrCode)

      ` Operation is not finished yet, set spErrCode to 1
   spErrCode:=1
   $vpTable:=Table($1)
   INPUT FORM($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.

New process, Stored Procedures.