DataStore
A Datastore is the interface object provided by ORDA to reference and access a database. Datastore
objects are returned by the following commands:
- ds: a shortcut to the main datastore
- Open datastore: to open any remote datastore
Summary
.cancelTransaction() cancels the transaction |
.clearAllRemoteContexts() clears all the attributes for all the active contexts in the datastore |
.dataclassName : 4D.DataClass contains a description of the dataclass |
.encryptionStatus(): Object returns an object providing the encryption status for the current data file |
.flushAndLock() flushes the cache of the local datastore and prevents other processes from performing write operations on the database |
.getAllRemoteContexts() : Collection returns a collection of objects containing information on all the active optimization contexts in the datastore |
.getInfo(): Object returns an object providing information about the datastore |
.getRemoteContextInfo(contextName : Text) : Object returns an object that holds information on the contextName optimization context in the datastore. |
.getRequestLog() : Collection returns the ORDA requests logged in memory on the client side |
.locked() : Boolean returns True if the local datastore is currently locked |
.makeSelectionsAlterable() sets all entity selections as alterable by default in the current application datastores |
.provideDataKey( curPassPhrase : Text ) : Object .provideDataKey( curDataKey : Object ) : Object allows providing a data encryption key for the current data file of the datastore and detects if the key matches the encrypted data |
.setAdminProtection( status : Boolean ) allows disabling any data access on the web admin port, including for the Data Explorer in WebAdmin sessions |
.setRemoteContextInfo( contextName : Text ; dataClassName : Text ; attributes : Text {; contextType : Text { ; pageLength : Integer}}) .setRemoteContextInfo( contextName : Text ; dataClassName : Text; attributesColl : Collection {; contextType : Text { ; pageLength : Integer }} ) .setRemoteContextInfo( contextName : Text ; dataClassObject : 4D.DataClass ; attributes : Text {; contextType : Text { ; pageLength : Integer }}) .setRemoteContextInfo( contextName : Text ; dataClassObject : 4D.DataClass ; attributesColl : Collection {; contextType : Text { ; pageLength : Integer }} ) links the specified dataclass attributes to the contextName optimization context |
.startRequestLog() .startRequestLog( file : 4D.File ) .startRequestLog( file : 4D.File ; options : Integer ) .startRequestLog( reqNum : Integer ) starts the logging of ORDA requests on the client side or on the server side |
.startTransaction() starts a transaction in the current process on the database matching the datastore to which it applies |
.stopRequestLog() stops any logging of ORDA requests on the machine it is called (client or server) |
.unlock() removes the current lock on write operations in the datastore, if it has been set in the same process |
.validateTransaction() accepts the transaction |
ds
History
Release | Changes |
---|---|
18 | Support of localID parameter |
17 | Added |
ds { ( localID : Text ) } : cs.DataStore
Parameter | Type | Description | |
---|---|---|---|
localID | Text | -> | Local ID of the remote datastore to return |
Result | cs.DataStore | <- | Reference to the datastore |
Description
The ds
command returns a reference to the datastore matching the current 4D database or the database designated by localID.
If you omit the localID parameter (or pass an empty string ""), the command returns a reference to the datastore matching the local 4D database (or the 4D Server database in case of opening a remote database on 4D Server). The datastore is opened automatically and available directly through ds
.
You can also get a reference on an open remote datastore by passing its local id in the localID parameter. The datastore must have been previously opened with the Open datastore
command by the current database (host or component). The local id is defined when using this command.
The scope of the local id is the database where the datastore has been opened.
If no localID datastore is found, the command returns Null.
Objects available in the cs.Datastore
are mapped from the target database with respect to the ORDA general rules.
Example 1
Using the main datastore on the 4D database:
$result:=ds.Employee.query("firstName = :1";"S@")
Example 2
var $connectTo; $firstFrench; $firstForeign : Object
var $frenchStudents; $foreignStudents : cs.DataStore
$connectTo:=New object("type";"4D Server";"hostname";"192.168.18.11:8044")
$frenchStudents:=Open datastore($connectTo;"french")
$connectTo.hostname:="192.168.18.11:8050"
$foreignStudents:=Open datastore($connectTo;"foreign")
//...
//...
$firstFrench:=getFirst("french";"Students")
$firstForeign:=getFirst("foreign";"Students")
//getFirst method
//getFirst(localID;dataclass) -> entity
#DECLARE( $localId : Text; $dataClassName : Text ) -> $entity : 4D.Entity
$0:=ds($localId)[$dataClassName].all().first()
Open datastore
History
Release | Changes |
---|---|
20.3 | New passwordAlgorithm property |
18 | Added |
Open datastore( connectionInfo : Object ; localID : Text ) : cs.DataStore
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) |
Result | cs.DataStore | <- | Datastore object |
Description
The Open datastore
command connects the application to the 4D database identified by the connectionInfo parameter and returns a matching cs.DataStore
object associated with the localID local alias.
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,
- 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.
Objects available in the cs.Datastore
are mapped from the target database with respect to the ORDA general rules.
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. By default, the password is sent in clear form, therefore it is strongly recommended to use encrypted communications by passing true in the tls property. |
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. |
passwordAlgorithm | Text | Pass "4d-rest-digest" if the server validates the password using the Validate password command with the digest parameter set to true . |
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. Otherwise, error "1610 - A remote request to host xxx has failed" is raised
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")
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
.
.dataclassName
History
Release | Changes |
---|---|
17 | Added |
.dataclassName : 4D.DataClass
Description
Each dataclass in a datastore is available as a property of the DataStore objectdata. The returned object contains a description of the dataclass.
Example
var $emp : cs.Employee
var $sel : cs.EmployeeSelection
$emp:=ds.Employee //$emp contains the Employee dataclass
$sel:=$emp.all() //gets an entity selection of all employees
//you could also write directly:
$sel:=ds.Employee.all()
.cancelTransaction()
History
Release | Changes |
---|---|
18 | Added |
.cancelTransaction()
Parameter | Type | Description | |
---|---|---|---|
Does not require any parameters |
Description
The .cancelTransaction()
function cancels the transaction opened by the .startTransaction()
function at the corresponding level in the current process for the specified datastore.
The .cancelTransaction()
function cancels any changes made to the data during the transaction.
You can nest several transactions (sub-transactions). If the main transaction is cancelled, all of its sub-transactions are also cancelled, even if they were validated individually using the .validateTransaction()
function.
Example
See example for the .startTransaction()
function.
.clearAllRemoteContexts()
History
Release | Changes |
---|---|
19 R5 | Added |
.clearAllRemoteContexts()
Parameter | Type | Description | |
---|---|---|---|
Does not require any parameters |
Description
The .clearAllRemoteContexts()
function clears all the attributes for all the active contexts in the datastore.
This function is mainly used in the context of debugging. One thing to keep in mind is that when you open the debugger, it sends requests to the server and queries all the dataclass attributes to display them. This can overload your contexts with unnecessary data.
In such cases, you can use .clearAllRemoteContexts()
to clear your contexts and keep them clean.
See also
.getRemoteContextInfo()
.getAllRemoteContexts()
.setRemoteContextInfo()
.encryptionStatus()
History
Release | Changes |
---|---|
17 R5 | Added |
.encryptionStatus(): Object
Parameter | Type | Description | |
---|---|---|---|
Result | Object | <- | Information about the encryption of the current datastore and of each table |
Description
The .encryptionStatus()
function returns an object providing the encryption status for the current data file (i.e., the data file of the ds
datastore). The status for each table is also provided.
Use the
Data file encryption status
command to determine the encryption status of any other data file.
Returned value
The returned object contains the following properties:
Property | Type | Description | ||
---|---|---|---|---|
isEncrypted | Boolean | True if the data file is encrypted | ||
keyProvided | Boolean | True if the encryption key matching the encrypted data file is provided(*). | ||
tables | Object | Object containing as many properties as there are encryptable or encrypted tables. | ||
tableName | Object | Encryptable or Encrypted table | ||
name | Text | Name of the table | ||
num | Number | Table number | ||
isEncryptable | Boolean | True if the table is declared encryptable in the structure file | ||
isEncrypted | Boolean | True if the records of the table are encrypted in the data file |
(*) The encryption key can be provided:
- with the
.provideDataKey()
command, - at the root of a connected device before opening the datastore,
- with the
Discover data key
command.
Example
You want to know the number of encrypted tables in the current data file:
var $status : Object
$status:=ds.encryptionStatus()
If($status.isEncrypted) //the database is encrypted
C_LONGINT($vcount)
C_TEXT($tabName)
For each($tabName;$status.tables)
If($status.tables[$tabName].isEncrypted)
$vcount:=$vcount+1
End if
End for each
ALERT(String($vcount)+" encrypted table(s) in this datastore.")
Else
ALERT("This database is not encrypted.")
End if
.flushAndLock()
History
Release | Changes |
---|---|
20 | Added |
.flushAndLock()
Parameter | Type | Description | |
---|---|---|---|
Does not require any parameters |
Description
The .flushAndLock()
function flushes the cache of the local datastore and prevents other processes from performing write operations on the database. The datastore is set to a consistent, frozen state. Calling this function is necessary before executing an application snapshot, for example.
This function can only be called:
- on the local datastore (
ds
). - in client/server environment, on the server machine.
Once this function is executed, write operations such as .save()
or other .flushAndLock()
calls are frozen in all other processes until the datastore is unlocked.
When multiple calls to .flushAndLock()
have been done in the same process, the same number of .unlock()
calls must be executed to actually unlock the datastore.
The datastore is unlocked when:
- the
.unlock()
function is called in the same process, or - the process that called the
.flushAndLock()
function is killed.
If the datastore is already locked from another process, the .flushAndLock()
call is frozen and will be executed when the datastore will be unlocked.
An error is triggered if the .flushAndLock()
function cannot be executed (e.g. it is run on a remote 4D), .
Example
You want to create a copy of the data folder along with its current journal file:
$destination:=Folder(fk documents folder).folder("Archive")
$destination.create()
ds.flushAndLock() //Block write operations from other processes
$dataFolder:=Folder(fk data folder)
$dataFolder.copyTo($destination) //Copy the data folder
$oldJournalPath:=New log file //Close the journal and create a new one
$oldJournal:=File($oldJournalPath; fk platform path)
$oldJournal.moveTo($destination) //Save the old journal with data
ds.unlock() //Our copy is over, we can now unlock the datastore
See also
.getAllRemoteContexts()
History
Release | Changes |
---|---|
19 R5 | Added |
.getAllRemoteContexts() : Collection
Parameter | Type | Description | |
---|---|---|---|
Result | Collection | <- | Collection of optimization context objects |
Advanced mode: This function is intended for developers who need to customize ORDA default features for specific configurations. In most cases, you will not need to use it.
Description
The .getAllRemoteContexts()
function returns a collection of objects containing information on all the active optimization contexts in the datastore.
For more information on how contexts can be created, see client/server optimization.
Each object in the returned collection has the properties listed in the .getRemoteContextInfo()
section.
Example
The following code sets up two contexts and retrieves them using .getAllRemoteContexts()
:
var $ds : 4D.DataStoreImplementation
var $persons : cs.PersonsSelection
var $addresses : cs.AddressSelection
var $p : cs.PersonsEntity
var $a : cs.AddressEntity
var $contextA; $contextB : Object
var $info : Collection
var $text : Text
// Open remote datastore
$ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")
// Set context A
$contextA:=New object("context"; "contextA")
$persons:=$ds.Persons.all($contextA)
$text:=""
For each ($p; $persons)
$text:=$p.firstname+" lives in "+$p.address.city+" / "
End for each
// Set context B
$contextB:=New object("context"; "contextB")
$addresses:=$ds.Address.all($contextB)
$text:=""
For each ($a; $addresses)
$text:=$a.zipCode
End for each
// Get all remote contexts (in this case, contextA and contextB)
$info:=$ds.getAllRemoteContexts()
//$info = [{name:"contextB"; dataclass:"Address"; main:"zipCode"},
{name:"contextA";dataclass:"Persons";main:"firstname,address.city"}]
This example serves as a demonstration, it is not meant for real implementation.
See also
.getRemoteContextInfo()
.setRemoteContextInfo()
.clearAllRemoteContexts()
.getInfo()
History
Release | Changes |
---|---|
17 | Added |
.getInfo(): Object
Parameter | Type | Description | |
---|---|---|---|
Result | Object | <- | Datastore properties |
Description
The .getInfo()
function returns an object providing information about the datastore. This function is useful for setting up generic code.
Returned object
Property | Type | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
type | string | ||||||||||||||||
networked | boolean | ||||||||||||||||
localID | text | ID of the datastore on the machine. Corresponds to the localId string given with the Open datastore command. Empty string ("") for main datastore. | |||||||||||||||
connection | object | Object describing the remote datastore connection (not returned for main datastore). Available properties:
|
- If the
.getInfo()
function is executed on a 4D Server or 4D single-user,networked
is False. - If the
.getInfo()
function is executed on a remote 4D,networked
is True
Example 1
var $info : Object
$info:=ds.getInfo() //Executed on 4D Server or 4D
//{"type":"4D","networked":false,"localID":""}
$info:=ds.getInfo() // Executed on 4D remote
//{"type":"4D","networked":true,"localID":""}
Example 2
On a remote datastore:
var $remoteDS : cs.DataStore
var $info; $connectTo : Object
$connectTo:=New object("hostname";"111.222.33.44:8044";"user";"marie";"password";"aaaa")
$remoteDS:=Open datastore($connectTo;"students")
$info:=$remoteDS.getInfo()
//{"type":"4D Server",
//"localID":"students",
//"networked":true,
//"connection":{hostname:"111.222.33.44:8044","tls":false,"idleTimeout":2880,"user":"marie"}}
.getRemoteContextInfo()
History
Release | Changes |
---|---|
19 R5 | Added |
.getRemoteContextInfo(contextName : Text) : Object
Parameter | Type | Description | |
---|---|---|---|
contextName | Text | -> | Name of the context |
Result | Object | <- | Description of the optimization context |
Advanced mode: This function is intended for developers who need to customize ORDA default features for specific configurations. In most cases, you will not need to use it.
Description
The .getRemoteContextInfo()
function returns an object that holds information on the contextName optimization context in the datastore..
For more information on how optimization contexts can be created, see client/server optimization.
Returned object
The returned object has the following properties:
Property | Type | Description |
---|---|---|
name | Text | Name of the context |
main | Text | Attribute(s) associated to the context (attribute names are separated by a comma) |
dataclass | Text | Dataclass name |
currentItem (optional) | Text | The attributes of the page mode if the context is linked to a list box. Returned as Null or empty text element if the context name is not used for a list box, or if there is no context for the currentItem |
Since contexts behave as filters for attributes, if main is returned empty, it means that no filter is applied, and that the server returns all the dataclass attributes.
Example
See the example from the .setRemoteContextInfo() section.
See also
.setRemoteContextInfo()
.getAllRemoteContexts()
.clearAllRemoteContexts()
.getRequestLog()
History
Release | Changes |
---|---|
17 R6 | Added |
.getRequestLog() : Collection
Parameter | Type | Description | |
---|---|---|---|
Result | Collection | <- | Collection of objects, where each object describes a request |
Description
The .getRequestLog()
function returns the ORDA requests logged in memory on the client side. The ORDA request logging must have previously been enabled using the .startRequestLog()
function.
This function must be called on a remote 4D, otherwise it returns an empty collection. It is designed for debugging purposes in client/server configurations.
Returned value
Collection of stacked request objects. The most recent request has index 0.
For a description of the ORDA request log format, please refer to the ORDA client requests section.
Example
See Example 2 of .startRequestLog()
.
.isAdminProtected()
History
Release | Changes |
---|---|
18 R6 | Added |
.isAdminProtected() : Boolean
Parameter | Type | Description | |
---|---|---|---|
Result | Boolean | <- | True if the Data Explorer access is disabled, False if it is enabled (default) |
Description
The .isAdminProtected()
function returns True
if Data Explorer access has been disabled for the working session.
By default, the Data Explorer access is granted for webAdmin
sessions, but it can be disabled to prevent any data access from administrators (see the .setAdminProtection()
function).
See also
.locked()
History
Release | Changes |
---|---|
20 | Added |
.locked() : Boolean
Parameter | Type | Description | |
---|---|---|---|
Result | Boolean | <- | True if locked |
Description
The .locked()
function returns True if the local datastore is currently locked.
You can lock the datastore using the .flushAndLock() function before executing a snapshot of the data file, for example.
The function will also return True
if the datastore was locked by another administration feature such as backup or vss (see .flushAndLock()).
See also
.makeSelectionsAlterable()
History
Release | Changes |
---|---|
18 R5 | Added |
.makeSelectionsAlterable()
Parameter | Type | Description | |
---|---|---|---|
Does not require any parameters |
Description
The .makeSelectionsAlterable()
function sets all entity selections as alterable by default in the current application datastores (including remote datastores). It is intended to be used once, for example in the On Startup
database method.
When this function is not called, new entity selections can be shareable, depending on the nature of their "parent", or how they are created.
This function does not modify entity selections created by
.copy()
orOB Copy
when the explicitck shared
option is used.
Compatibility: This function must only be used in projects converted from 4D versions prior to 4D v18 R5 and containing .add() calls. In this context, using
.makeSelectionsAlterable()
can save time by restoring instantaneously the previous 4D behavior in existing projects. On the other hand, using this method in new projects created in 4D v18 R5 and higher is not recommended, since it prevents entity selections to be shared, which provides greater performance and scalabitlity.
.provideDataKey()
History
Release | Changes |
---|---|
17 R5 | Added |
.provideDataKey( curPassPhrase : Text ) : Object
.provideDataKey( curDataKey : Object ) : Object
Parameter | Type | Description | |
---|---|---|---|
curPassPhrase | Text | -> | Current encryption passphrase |
curDataKey | Object | -> | Current data encryption key |
Result | Object | <- | Result of the encryption key matching |
Description
The .provideDataKey()
function allows providing a data encryption key for the current data file of the datastore and detects if the key matches the encrypted data. This function can be used when opening an encrypted database, or when executing any encryption operation that requires the encryption key, such as re-encrypting the data file.
- The
.provideDataKey()
function must be called in an encrypted database. If it is called in a non-encrypted database, the error 2003 (the encryption key does not match the data.) is returned. Use theData file encryption status
command to determine if the database is encrypted.- The
.provideDataKey()
function cannot be called from a remote 4D or an encrypted remote datastore.
If you use the curPassPhrase parameter, pass the string used to generate the data encryption key. When you use this parameter, an encryption key is generated.
If you use the curDataKey parameter, pass an object (with encodedKey property) that contains the data encryption key. This key may have been generated with the New data key
command.
If a valid data encryption key is provided, it is added to the keyChain in memory and the encryption mode is enabled:
- all data modifications in encryptable tables are encrypted on disk (.4DD, .journal. 4Dindx files)
- all data loaded from encryptable tables is decrypted in memory
Result
The result of the command is described in the returned object:
Property | Type | Description | |
---|---|---|---|
success | Boolean | True if the provided encryption key matches the encrypted data, False otherwise | |
Properties below are returned only if success is FALSE | |||
status | Number | Error code (4 if the provided encryption key is wrong) | |
statusText | Text | Error message | |
errors | Collection | Stack of errors. The first error has the highest index | |
[ ].componentSignature | Text | Internal component name | |
[ ].errCode | Number | Error number | |
[ ].message | Text | Error message |
If no curPassphrase or curDataKey is given, .provideDataKey()
returns null (no error is generated).
Example
var $keyStatus : Object
var $passphrase : Text
$passphrase:=Request("Enter the passphrase")
If(OK=1)
$keyStatus:=ds.provideDataKey($passphrase)
If($keyStatus.success)
ALERT("You have provided a valid encryption key")
Else
ALERT("You have provided an invalid encryption key, you will not be able to work with encrypted data")
End if
End if
.setAdminProtection()
History
Release | Changes |
---|---|
18 R6 | Added |
.setAdminProtection( status : Boolean )
Parameter | Type | Description | |
---|---|---|---|
status | Boolean | -> | True to disable Data Explorer access to data on the webAdmin port, False (default) to grant access |
Description
The .setAdminProtection()
function allows disabling any data access on the web admin port, including for the Data Explorer in WebAdmin
sessions.
By default when the function is not called, access to data is always granted on the web administration port for a session with WebAdmin
privilege using the Data Explorer. In some configurations, for example when the application server is hosted on a third-party machine, you might not want the administrator to be able to view your data, although they can edit the server configuration, including the access key settings.
In this case, you can call this function to disable the data access from Data Explorer on the web admin port of the machine, even if the user session has the WebAdmin
privilege. When this function is executed, the data file is immediately protected and the status is stored on disk: the data file will be protected even if the application is restarted.
Example
You create a protectDataFile project method to call before deployments for example:
ds.setAdminProtection(True) //Disables the Data Explorer data access
See also
.setRemoteContextInfo()
History
Release | Changes |
---|---|
19 R5 | Added |
.setRemoteContextInfo( contextName : Text ; dataClassName : Text ; attributes : Text {; contextType : Text { ; pageLength : Integer}})
.setRemoteContextInfo( contextName : Text ; dataClassName : Text; attributesColl : Collection {; contextType : Text { ; pageLength : Integer }} )
.setRemoteContextInfo( contextName : Text ; dataClassObject : 4D.DataClass ; attributes : Text {; contextType : Text { ; pageLength : Integer }})
.setRemoteContextInfo( contextName : Text ; dataClassObject : 4D.DataClass ; attributesColl : Collection {; contextType : Text { ; pageLength : Integer }} )
Parameter | Type | Description | |
---|---|---|---|
contextName | Text | -> | Name of the context |
dataClassName | Text | -> | Name of the dataclass |
dataClassObject | 4D.DataClass | -> | dataclass object (e.g datastore.Employee) |
attributes | Text | -> | Attribute list separated by a comma |
attributesColl | Collection | -> | Collection of attribute names (text) |
contextType | Text | -> | If provided, value must be "main" or "currentItem" |
pageLength | Integer | -> | Page length of the entity selection linked to the context (default is 80) |
Advanced mode: This function is intended for developers who need to customize ORDA default features for specific configurations. In most cases, you will not need to use it.
Description
The .setRemoteContextInfo()
function links the specified dataclass attributes to the contextName optimization context. If an optimization context already exists for the specified attributes, this command replaces it.
When you pass a context to the ORDA class functions, the REST request optimization is triggered immediately:
- the first entity is not fully loaded as done in automatic mode
- pages of 80 entities (or
pageLength
entities) are immediately asked to the server with only the attributes in the context
For more information on how optimization contexts are built, refer to the client/server optimization paragraph
In contextName, pass the name of the optimization context to link to the dataclass attributes.
To designate the dataclass that will receive the context, you can pass a dataClassName or a dataClassObject.
To designate the attributes to link to the context, pass either a list of attributes separated by a comma in attributes (Text), or a collection of attribute names in attributesColl (collection of text).
If attributes is an empty Text, or attributesColl is an empty collection, all the scalar attributes of the dataclass are put in the optimization context. If you pass an attribute that does not exist in the dataclass, the function ignores it and an error is thrown.
You can pass a contextType to specify if the context is a standard context or the context of the current entity selection item displayed in a list box:
- If set to "main" (default), the contextName designates a standard context.
- If set to "currentItem", the attributes passed are put in the context of the current item. See Entity selection-based list box.
In pageLength, specify the number of dataclass entities to request from the server.
You can pass a pageLength for a relation attribute which is an entity selection (one to many). The syntax is relationAttributeName:pageLength
(e.g employees:20).
Example 1
var $ds : 4D.DataStoreImplementation
var $persons : cs.PersonsSelection
var $p : cs.PersonsEntity
var $contextA : Object
var $info : Object
var $text : Text
// Open remote datastore
$ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")
// Set context info
$contextA:=New object("context"; "contextA")
$ds.setRemoteContextInfo("contextA"; $ds.Persons; "firstname, lastname")
// Send requests to the server using a loop
$persons:=$ds.Persons.all($contextA)
$text:=""
For each ($p; $persons)
$text:=$p.firstname + " " + $p.lastname
End for each
// Check contents of the context
$info:=$ds.getRemoteContextInfo("contextA")
// $info = {name:"contextA";dataclass:"Persons";main:"firstname, lastname"}
This example serves as a demonstration, it is not meant for real implementation.
Example 2
The following piece of code requests pages of 30 entities of the Address
dataclass from the server. The returned entities only contain the zipCode
attribute.
For each Address
entity, 20 Persons entities are returned, and they only contain the lastname
and firstname
attributes:
var $ds : 4D.DataStoreImplementation
$ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")
$ds.setRemoteContextInfo("contextA"; $ds.Address; "zipCode, persons:20,\
persons.lastname, persons.firstname"; "main"; 30)
Example 3 - Listbox
// When the form loads
Case of
: (Form event code=On Load)
Form.ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")
// Set the attributes of the page context
Form.ds.setRemoteContextInfo("LB"; Form.ds.Persons; "age, gender,\
children"; "currentItem")
Form.settings:=New object("context"; "LB")
Form.persons:=Form.ds.Persons.all(Form.settings)
// Form.persons is displayed in a list box
End case
// When you get the attributes in the context of the current item:
Form.currentItemLearntAttributes:=Form.selectedPerson.getRemoteContextAttributes()
// Form.currentItemLearntAttributes = "age, gender, children"
See also
.getRemoteContextInfo()
.getAllRemoteContexts()
.clearAllRemoteContexts()
.startRequestLog()
History
Release | Changes |
---|---|
20 | Server side support, new options parameter |
17 R6 | Added |
.startRequestLog()
.startRequestLog( file : 4D.File )
.startRequestLog( file : 4D.File ; options : Integer )
.startRequestLog( reqNum : Integer )
Parameter | Type | Description | |
---|---|---|---|
file | 4D.File | -> | File object |
options | Integer | -> | Log response option (server only) |
reqNum | Integer | -> | Number of requests to keep in memory (client only) |
Description
The .startRequestLog()
function starts the logging of ORDA requests on the client side or on the server side. It is designed for debugging purposes in client/server configurations.
For a description of the ORDA request log format, please refer to the ORDA requests section.
Client-side
To create a client-side ORDA request log, call this function on a remote machine. The log can be sent to a file or to memory, depending on the parameter type:
- If you passed a file object created with the
File
command, the log data is written in this file as a collection of objects (JSON format). Each object represents a request.
If the file does not already exist, it is created. Otherwise if the file already exists, the new log data is appended to it. If.startRequestLog()
is called with a file while a logging was previously started in memory, the memory log is stopped and emptied.
A ] character must be manually appended at the end of the file to perform a JSON validation
-
If you passed a reqNum integer, the log in memory is emptied (if any) and a new log is initialized. It will keep reqNum requests in memory until the number is reached, in which case the oldest entries are emptied (FIFO stack).
If.startRequestLog()
is called with a reqNum while a logging was previously started in a file, the file logging is stopped. -
If you did not pass any parameter, the log is started in memory. If
.startRequestLog()
was previously called with a reqNum (before a.stopRequestLog()
), the log data is stacked in memory until the next time the log is emptied or.stopRequestLog()
is called.
Server-side
To create a server-side ORDA request log, call this function on the server machine. The log data is written in a file in .jsonl
format. Each object represents a request. If the file does not already exist, it is created. Otherwise if the file already exists, the new log data is appended to it.
- If you passed the file parameter, the log data is written in this file, at the requested location. - If you omit the file parameter or if it is null, the log data is written in a file named ordaRequests.jsonl and stored in the "/LOGS" folder.
- The options parameter can be used to specify if the server response has to be logged, and if it should include the body. By default when the parameter is omitted, the full response is logged. The following constants can be used in this parameter:
Constant | Description |
---|---|
srl log all | Log the response entirely (default value) |
srl log no response | Disable the logging of the response |
srl log response without body | Log the response without the body |
Example 1
You want to log ORDA client requests in a file and use the log sequence number:
var $file : 4D.File
var $e : cs.PersonsEntity
$file:=File("/LOGS/ORDARequests.txt") //logs folder
SET DATABASE PARAMETER(Client Log Recording;1) //to trigger the global log sequence number
ds.startRequestLog($file)
$e:=ds.Persons.get(30001) //send a request
ds.stopRequestLog()
SET DATABASE PARAMETER(Client Log Recording;0)
Example 2
You want to log ORDA client requests in memory:
var $es : cs.PersonsSelection
var $log : Collection
ds.startRequestLog(3) //keep 3 requests in memory
$es:=ds.Persons.query("name=:1";"Marie")
$es:=ds.Persons.query("name IN :1";New collection("Marie"))
$es:=ds.Persons.query("name=:1";"So@")
$log:=ds.getRequestLog()
ALERT("The longest request lasted: "+String($log.max("duration"))+" ms")
Example 3
You want to log ORDA server requests in a specific file and enable the log sequence number and duration:
SET DATABASE PARAMETER(4D Server Log Recording;1)
$file:=Folder(fk logs folder).file("myOrdaLog.jsonl")
ds.startRequestLog($file)
...
ds.stopRequestLog()
SET DATABASE PARAMETER(4D Server Log Recording;0)
.startTransaction()
History
Release | Changes |
---|---|
18 | Added |
.startTransaction()
Parameter | Type | Description | |
---|---|---|---|
Does not require any parameters |
Description
The .startTransaction()
function starts a transaction in the current process on the database matching the datastore to which it applies. Any changes made to the datastore's entities in the transaction's process are temporarily stored until the transaction is either validated or cancelled.
If this method is called on the main datastore (i.e. the datastore returned by the
ds
command), the transaction is applied to all operations performed on the main datastore and on the underlying database, thus including ORDA and classic languages.
You can nest several transactions (sub-transactions). Each transaction or sub-transaction must eventually be cancelled or validated. Note that if the main transaction is cancelled, all of its sub-transactions are also cancelled even if they were validated individually using the .validateTransaction()
function.
Example
var $connect; $status : Object
var $person : cs.PersonsEntity
var $ds : cs.DataStore
var $choice : Text
var $error : Boolean
Case of
:($choice="local")
$ds:=ds
:($choice="remote")
$connect:=New object("hostname";"111.222.3.4:8044")
$ds:=Open datastore($connect;"myRemoteDS")
End case
$ds.startTransaction()
$person:=$ds.Persons.query("lastname=:1";"Peters").first()
If($person#Null)
$person.lastname:="Smith"
$status:=$person.save()
End if
...
...
If($error)
$ds.cancelTransaction()
Else
$ds.validateTransaction()
End if
.stopRequestLog()
History
Release | Changes |
---|---|
20 | Server side support |
17 R6 | Added |
.stopRequestLog()
Parameter | Type | Description | |
---|---|---|---|
Does not require any parameters |
Description
The .stopRequestLog()
function stops any logging of ORDA requests on the machine it is called (client or server).
It actually closes the opened document on disk. On the client side, if the log was started in memory, it is stopped.
This function does nothing if logging of ORDA requests was not started on the machine.
Example
See examples for .startRequestLog()
.
.unlock()
History
Release | Changes |
---|---|
20 | Added |
.unlock()
Parameter | Type | Description | |
---|---|---|---|
Does not require any parameters |
Description
The .unlock()
function removes the current lock on write operations in the datastore, if it has been set in the same process. Write operations can be locked in the local datastore using the .flushAndLock()
function.
If the current lock was the only lock on the datastore, write operations are immediately enabled. If the .flushAndLock()
function was called several times in the process, the same number of .unlock()
must be called to actually unlock the datastore.
The .unlock()
function must be called from the process that called the corresponding .flushAndLock()
, otherwise the function does nothing and the lock is not removed.
If the .unlock()
function is called in an unlocked datastore, it does nothing.
See also
.validateTransaction()
History
Release | Changes |
---|---|
18 | Added |
.validateTransaction()
Parameter | Type | Description | |
---|---|---|---|
Does not require any parameters |
Description
The .validateTransaction()
function accepts the transaction that was started with .startTransaction()
at the corresponding level on the specified datastore.
The function saves the changes to the data on the datastore that occurred during the transaction.
You can nest several transactions (sub-transactions). If the main transaction is cancelled, all of its sub-transactions are also cancelled, even if they were validated individually using this function.
Example
See example for .startTransaction()
.