Calling 4D Tables and Methods

The access mode for 4D tables referenced in the Wakanda application depends on how the external catalog is integrated, which is defined in Wakanda during its connection to the remote application (see Integrating with the active model or using a dedicated model):

• merged with active model (default option): in this case, remote tables are used exactly like local classes through the ds object.
• using a dedicated model: in this case, remote tables are properties of the dedicated model object.

When merged with the active model, 4D tables referenced in the Wakanda application can be used directly in the Server-side JavaScript code as properties of the ds object, just like local datastore classes. 

Note: The ds object contains the current datastore of the Wakanda application. 

For example, to perform a query in the records of the [Employees] 4D table, you can write:

var emp = ds.Employees.query("age > :1",30);
        //retrieve a collection of records from the Employees table
        //where age is greater than 30 in the emp variable

On the client side, you can also take advantage of automatic mechanisms of the datasources based on the datastore classes and associated with the widgets. For example, if you associate the ’employees’ datasource with a ’Grid’ type widget, you can display the list of employees automatically:

When the table is associated with a datasource, you can also access its data using this datasource. For example, to sort the collection of records of the ’employees’ datasource, you can write:

sources.employees.orderBy("age");
    //sorts the collection of employees by their age

For more information about working with datastore classes, refer to the Wakanda documentation.

The 4D tables referenced are used in the Server-side JavaScript code as properties of the catalog where they were placed when the link was created. The name of this catalog is the one that you passed in the Remote datastore name connection parameter (Wakanda Studio connection dialog box) or in localName (JavaScript methods).

For example, if you created a link called "my4Dstore" and want to perform a query among the records of the [Employees] table, you can write:

var emp2 = my4Dstore.Employees.query("age > :1", 30);
    // search in the records of the Employees table
    // in the link named "my4Dstore"

Implementation note: On the client side, using a dedicated model in the current version of 4D Mobile does not allow access to remote classes at the present time.

4D methods referenced in the Wakanda application can be used directly in the JavaScript code as properties of the datastore class, entity collection or entity objects, depending on their scope as defined on the 4D side (see the Parent table and Scope of project methods paragraph). Here is the correspondence between Wakanda objects and the scope of the project methods:

Note: 4D methods can also be called on the client side using datasources (see below); in this case all the methods are available, and the datasource applies them automatically to the current collection or the current entity depending on the context. 

For example, if you perform a query using the query method (see previous section), Wakanda returns an entity collection. You can execute any 4D project method whose scope is declared as "current selection" on this collection.

There are three ways for 4D methods to be called by JavaScript code:

• From the JavaScript code executed on the server (SSJS), using the SSJS Datastore API. In this case, 4D methods are called as properties of the datastore class, entity collection or entity objects, as described above.
  Examples:
  

  var vTot = ds.Emp.raiseSalary(param))
      //raiseSalary is a datastore class property
      //the catalog is merged with the active model
  var vTot2 = my4DStore.Company.first().capital(param)) 
      //capital is an entity property since first() returns an entity
      //using the my4DStore dedicated model

• From the JavaScript code executed on the client (i.e., the browser) using the Wakanda Ajax Framework (WAF). There are two possibilities:
  Implementation note: In the current version of Wakanda Enterprise, client access to 4D database methods is only avaialble when the remote database is connected and merged with the active model.
  
  • using WAF Datasource API: this high-level API provides many automatic functions for managing data. With this API, 4D methods are called as properties of datasources associated with datastore classes and will be applied automatically to the datastore class, the current entity collection, or the current entity depending on the context. You can manage return values of the methods or any errors using the asynchronous syntax (required for code executed on the client). Example:
    

    sources.employee.raiseSalary(param,
        {onSuccess: function(event)
        { ... //code to execute when method has finished}
    }))

    
    It is not mandatory to use a callback function because datasource objects have automatic functions that support, for example, updating data displayed in the current collection after a query.
  • using WAF Dataprovider API: this low-level client API lets you work with objects directly. As with the SSJS Datastore API, 4D methods are called as properties of the datastore class, entity collection or entity objects. However, you must manage the return values of the methods or any errors using the asynchronous syntax (required for code executed on the client). Example:
    

    ds.Employee.raiseSalary(param, // syntax resembles a SSJS call
        {onSuccess: function(event)    // but it’s client-side code so you must
        // manage the callback method of the asynchronous call
        { ... //code to execute when 4D method has finished}
    }))

  The choice of location (server or client) and API depends on the needs of the application and is described in the Wakanda documentation.

As with standard methods, you can pass parameters during the call, which are received in order in the parameters $1, $2, and so on. Similarly, the method can return a result in the $0 variable.

Example: You want to give a 5% raise to employees whose salary is less than 1500.

• On the 4D side, the IncreaseSalary method was exposed through 4D Mobile and its scope is the "Current selection". Its code is as follows:
  
   C_REAL($1)
 READ WRITE([Employees])
 FIRST RECORD([Employees])
 While(Not(End selection([Employees])))
    [Employees]salary:=[Employees]salary*$1
    SAVE RECORD([Employees])
    NEXT RECORD([Employees])
 End while
 UNLOAD RECORD([Employees])

• On the Wakanda side, you execute the following code on the server:
  

  var emp = ds.Employees.query("salary < :1",1500); 
          // emp contains the collection of employees whose salary is <1500
      emp.IncreaseSalary(1.05);
          //execute the IncreaseSalary method on the collection
          //You could also write: 
          //"ds.Employees.query("salary < :1",1500).IncreaseSalary(1.05);

You can also return a 4D selection directly as a Wakanda collection using the MOBILE Return selection command. For example:

When calling a 4D method by means of the Wakanda link:

• If the method applies to a selection (entity collection), it becomes the current selection and 4D is positioned on the first record of this selection without loading it or activating the links. If the selection is empty, the Selected record number command returns 0 instead of 1.

• If the method applies to a record (entity), it becomes the current record. The current selection is reduced to just this record and the Selected record number command returns 1.
  Note: For optimization reasons and to avoid unnecessary locking, the record is loaded in read only mode. However, the table is in read-write mode, so you can simply call the LOAD RECORD command to force the record to be loaded in read-write mode whenever necessary.

• If the method applies to a table (datastore class), neither the current selection nor the current record are affected.

Note that after executing a method through 4D Mobile, the 4D context is reset:

• selections are reduced to 0,
• records are unstacked and unloaded,
• local selections and sets for the process are destroyed,
• any transactions open during method execution are canceled,
• the configuration of automatic relations by fields, query destinations or queries on the server are reset,
• print jobs are canceled,
• windows are closed,
• any SQL, PHP or HTTP connections are closed.

You must make sure the scope of the 4D method corresponds to the type of Wakanda object that is calling it, otherwise a "TypeError: 'undefined' is not a function" error is returned by Wakanda.

For example, given the 4D "getcursel" method containing the following code:

Given the run method on the Wakanda side:

var tt = ds.Table_1.query("Field_2 = 'a*'").getcursel();

The query( ) method returns a collection. If the scope of the getcursel method was set as "Current record", Wakanda returns the following error:
TypeError: 'undefined' is not a function (evaluating 'ds.Table_1.query("Field_2 = 'a*'").getcursel()')".