Open datastore

Home

4D v19.8

Open datastore


Open datastore ( connectionInfo ; localID ) -> Function result

Parameter	Type	Description
connectionInfo	Object	Connection properties used to reach the remote datastore
localID	Text	Id to assign to the opened datastore on the local application (mandatory)
Function result	Object	Datastore object

Description

The Open datastore command connects the application to the 4D database identified by the connectionInfo parameter and returns a matching datastore object associated with the localID local alias.

Exchanges with the remote datastore are automatically managed via REST requests.

The connectionInfo 4D database must be available as a remote datastore, i.e.:

its Web Server must be launched with http and/or https enabled,
its Expose as REST server option must be checked (see Web/REST Resource),
at least one client license is available.

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

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

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

Property	Type	Description
hostname	Text	Name or IP address of the remote database + ":" + port number (port number is mandatory)
user	Text	User name
password	Text	User password
idleTimeout	Longint	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.
tls	Boolean	Use secured connection(*). If omitted, false by default. Using a secured connection is recommended whenever possible.
type	Text	Must be "4D Server"

(*) 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 database (see ).
Otherwise, error "1610 - A remote request to host xxx has failed" is raised

Example 1

Connection to a remote datastore without user / password:

 C_OBJECT($connectTo;$remoteDS)

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

 C_OBJECT($connectTo;$remoteDS)

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

 C_OBJECT($connectTo;$frenchStudents;$foreignStudents)

 $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")

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.