Open datastore
History
| Release | Changes |
|---|---|
| 21 | Qodly cloud discontinued |
| 20 R6 | Support access to Qodly cloud instances |
| 20 R4 | New passwordAlgorithm property |
| 18 | Added |
Open datastore( connectionInfo : Object ; localID : Text ) : 4D.DataStoreImplementation
| 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 | 4D.DataStoreImplementation | ← | Datastore object |
Description
The Open datastore command connects the application to the remote datastore identified by the connectionInfo parameter and returns a matching 4D.DataStoreImplementation object associated with the localID local alias.
Exchanges with the remote datastore are automatically managed via REST requests. The connectionInfo 4D datastore must be available as a remote datastore, i.e.:
- its Web Server must be launched with http and/or https enabled,
- its datastore is exposed to REST (Expose as REST server option checked),
- a client license must be available if required (see 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):
| Property | Type | Remote 4D application |
|---|---|---|
| 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 | Integer | 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 | True to use secured connection(1). If omitted, false by default. Using a secured connection is recommended whenever possible. |
| type | Text | 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 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 4D.DataStoreImplementation 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 : 4D.DataStoreImplementation
$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 : 4D.DataStoreImplementation
$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 : 4D.DataStoreImplementation
$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.
See also
Properties
| Command number | 1452 |
| Thread safe | ✓ |
| Modifies variables | error |