Skip to main content
Version: Next

openDatastore

openDatastore( connectionInfo : object , localID : text ) : cs.DataStore

ParameterTypeDescription
connectionInfoobject→Connection properties used to reach the remote datastore
localIDtext→Id to assign to the opened datastore on the current Cloud instance (mandatory)
Resultcs.DataStore←Datastore object

Description​

The openDatastore command connects the application to a remote datastore identified by the connectionInfo parameter and returns a matching cs.DataStore object associated with the localID alias on the Qodly Cloud instance. All objects exposed in the remote datastore are available as properties of the cs.DataStore returned object.

The following remote datastores are supported by the command:

datastore kindDescription
Qodly applicationAnother Qodly Server application that provided you with an api endpoint and a valid api key associated with a defined role. You must pass the api key in the api-key property of the connectionInfo object. You can then work with the returned datastore object, with all privileges granted to the associated role.
Remote 4D Server applicationA 4D Server application (version 20 or more) available as a remote datastore, i.e.:
  • its web server is launched with http and/or https enabled,
  • its datastore is exposed to REST (Expose as REST server option checked).
    • A license can be required.

    Pass in connectionInfo an object describing the remote datastore you want to connect to. It can contain the following properties (all properties are optional except hostname):

    PropertyTypeQodly applicationRemote 4D application
    hostnameTextAPI Endpoint of the Qodly cloud instanceName or IP address of the remote database + ":" + port number (port number is mandatory)
    api-keyTextAPI Key of the Qodly cloud instance- (ignored)
    idleTimeoutLongint- (ignored)Inactivity session timeout (in minutes), after which the session is automatically closed by 4D. If omitted, default value is 60 (1h). The value cannot be < 60 (if a lower value is passed, the timeout is set to 60). For more information, see Closing sessions.
    tlsBooleanTrue to use secured connection. If omitted, false by defaultTrue to use secured connection(1). If omitted, false by default. Using a secured connection is recommended whenever possible.
    typeText- (ignored)must be "4D Server"

    (1) If tls is true, the HTTPS protocol is used if:

    • HTTPS is enabled on the remote datastore
    • the given port is the right HTTPS port configured in the remote datastore settings
    • a valid certificate and private encryption key are installed in the project. Otherwise, an error "1610 - A remote request to host xxx has failed" is raised.
    info

    See the 4D documentation to know how to authenticate REST connection requests.

    If no matching connectionInfo remote datastore is found, openDatastore returns null.

    localID is a local alias on the current Cloud instance for the session opened on the remote datastore, i.e. either a Qodly session or a 4D Server session. If localID already exists on the instance, it is used. Otherwise, a new localID session is created when the datastore object is used.

    Once the session is opened on the remote 4D datastore, the following statements become equivalent and return a reference on the same datastore object:

     var mysd, myds2 : cs.DataStore
     myds = openDatastore(connectionInfo,"myLocalId")
     myds2 = ds("myLocalId")
      //myds and myds2 are equivalent

    Example 1​

    Connection to another Qodly application:

    var connectTo : object = {hostname: "https://xxx-x54xxx-xx-xxxxx-8xx5-xxxxxx.xx-api.cloud.com", tls: true}

    var remoteDS : 4D.DataStoreImplementation
    var data : 4D.EntitySelection

    connectTo["api-key"]="fxxxx-xxxx-4xxx-txxx-xxxxxxxx0" //only for example purpose  
      //it is recommended to store the API key in a secured place (i.e a file)
      //and to load in the code

    remoteDS = openDatastore(connectTo,"remoteId") 
    data = remoteDS.item.all()

    Example 2​

    Connection to a 4D Server remote datastore implementing an authentify() function (see the 4D documentation for more information):

    var remoteDS : 4D.DataStoreImplementation
    var customers : 4D.EntitySelection
    var result : variant

    remoteDS = openDatastore({hostname: "127.0.0.1:8044" , tls : true}, "id")
    customers = remoteDS.Customers.all() 
    // Error "You need to be logged in to perform this request."
    result = remoteDS.authentify({identifier: "msmith@acme.com", password: "a"}) 

    //Successful authentication
    customers = remoteDS.Customers.all()
    // No error - The customers are read

    Error management​

    In case of error, the command returns null. If the remote datastore cannot be reached (wrong address, web server not started, http and https not enabled...), error 1610 "A remote request to host XXX has failed" is raised. You can intercept this error with a method installed by onErrCall.

    See also​

    Using a remote datastore section on developer.4d.com.