Skip to main content
Version: Next

Open datastore

History
ReleaseChanges
20 R6Support access to Qodly instances
20 R4New passwordAlgorithm property
18Added

Open datastore( 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 local application (mandatory)
Function resultcs.DataStore←Datastore object

Description​

The Open datastore command connects the application to the remote datastore identified by the connectionInfo parameter and returns a matching cs.DataStore object associated with the localID local alias.

The following remote datastores are supported by the command:

datastore kindDescription
Remote 4D applicationA 4D application 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 (see note)
    Qodly applicationA 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.
    note

    Open datastore requests rely on the 4D REST API and can require a 4D Client license to open the connection on a remote 4D Server. Refer to the user login mode section to know how to configure the authentication depending on the selected current user login mode.

    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):

    PropertyTypeRemote 4D applicationQodly application
    hostnameTextName or IP address of the remote database + ":" + port number (port number is mandatory)API Endpoint of the Qodly cloud instance
    userTextUser name- (ignored)
    passwordTextUser password- (ignored)
    idleTimeoutIntegerInactivity 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.- (ignored)
    tlsBooleanTrue to use secured connection(1). If omitted, false by default. Using a secured connection is recommended whenever possible.True to use secured connection. If omitted, false by default
    typeTextmust be "4D Server"- (ignored)
    api-keyText- (ignored)Api key of the Qodly cloud instance

    (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 database settings
    • a valid certificate and private encryption key are installed in the 4D application. Otherwise, error "1610 - A remote request to host xxx has failed" is raised

    localID is a local alias for the session opened on remote datastore. If localID already exists on the application, it is used. Otherwise, a new localID session is created when the datastore object is used.

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

     $myds:=Open datastore(connectionInfo;"myLocalId")
     $myds2:=ds("myLocalId")
      //$myds and $myds2 are equivalent

    Objects available in the cs.Datastore are mapped with respect to the ORDA general rules.

    If no matching datastore is found, Open datastore returns Null.

    Example 1​

    Connection to a remote datastore without user / password:

     var $connectTo : Object
     var $remoteDS : cs.DataStore
     $connectTo:=New object("type";"4D Server";"hostname";"192.168.18.11:8044")
     $remoteDS:=Open datastore($connectTo;"students")
     ALERT("This remote datastore contains "+String($remoteDS.Students.all().length)+" students")

    Example 2​

    Connection to a remote datastore with user / password / timeout / tls:

     var $connectTo : Object
     var $remoteDS : cs.DataStore
     $connectTo:=New object("type";"4D Server";"hostname";\"192.168.18.11:4443";\  
      "user";"marie";"password";$pwd;"idleTimeout";70;"tls";True)
     $remoteDS:=Open datastore($connectTo;"students")
     ALERT("This remote datastore contains "+String($remoteDS.Students.all().length)+" students")

    Example 3​

    Working with several remote datastores:

     var $connectTo : Object
     var $frenchStudents; $foreignStudents : cs.DataStore
     $connectTo:=New object("hostname";"192.168.18.11:8044")
     $frenchStudents:=Open datastore($connectTo;"french")
     $connectTo.hostname:="192.168.18.11:8050"
     $foreignStudents:=Open datastore($connectTo;"foreign")
     ALERT("They are "+String($frenchStudents.Students.all().length)+" French students")
     ALERT("They are "+String($foreignStudents.Students.all().length)+" foreign students")

    Example 4​

    Connection to a 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 (e.g. a file)
      //and to load it in the code

    $remoteDS:=Open datastore($connectTo; "remoteId")
    $data:=$remoteDS.item.all()

    ALERT(String($data.length)+" items have been 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 ON ERR CALL.

    See also​

    ds