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
.getGlobalStamp() : Real    returns the current value of the global modification stamp of 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
.setGlobalStamp( newStamp : Real)    sets newStamp as new value for the current global modification stamp for the datastore
.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

Version	Changes
v18	Support of localID parameter
v17	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

Version	Changes
v18	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
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. 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

Version	Changes
v17	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

Version	Changes
v18	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

Version	Changes
v19 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

Version	Changes
v17 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

Version	Changes
v20	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.

info

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), .

caution

Other 4D features and services including backup, vss, and MSC can also lock the datastore. Before calling .flushAndLock(), make sure no other locking action is being used, in order to avoid any unexpected interaction.

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

.locked()
.unlock()

.getAllRemoteContexts()

History

Version	Changes
v19 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()

.getGlobalStamp()

History

Version	Changes
v20 R3	Added

.getGlobalStamp() : Real

Parameter	Type		Description
Result	Real	<-	Current value of the global modification stamp

Description

The .getGlobalStamp() function returns the current value of the global modification stamp of the datastore.

info

This function can only be called:

• on the local datastore (ds).
• in client/server environment, on the server machine.

For more information on global stamp and data change tracking, please refer to the Using the Global Stamp page.

Example

var $currentStamp : Real
var $hasModifications : Boolean

$currentStamp:=ds.getGlobalStamp()
methodWhichCouldModifyEmployees //call some code 
$hasModifications:=($currentStamp # ds.getGlobalStamp())

See also

.setGlobalStamp()

.getInfo()

History

Version	Changes
v17	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	"4D": main datastore, available through ds "4D Server": remote datastore, open with Open datastore
networked	boolean	True: the datastore is reached through a network connection. False: the datastore is not reached through a network connection (local database)
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: Property Type Description hostname text IP address or name of the remote datastore + ":" + port number tls boolean True if secured connection is used with the remote datastore idleTimeout number Session inactivity timeout (in minutes) user text User authenticated on the remote datastore

• 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

Version	Changes
v19 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

Version	Changes
v17 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

Version	Changes
v18 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

.setAdminProtection()

.locked()

History

Version	Changes
v20	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.

caution

The function will also return True if the datastore was locked by another administration feature such as backup or vss (see .flushAndLock()).

See also

.flushAndLock()
.unlock()

.makeSelectionsAlterable()

History

Version	Changes
v18 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() or OB Copy when the explicit ck 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

Version	Changes
v17 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 the Data 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

Version	Changes
v18 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

.isAdminProtected()

.setGlobalStamp()

History

Version	Changes
v20 R3	Added

.setGlobalStamp( newStamp : Real)

Parameter	Type		Description
newStamp	Real	->	New value of global modification stamp

Advanced mode

This function is intended for developers who need to modify the current global stamp value. It should be used with care.

Description

The .setGlobalStamp() function sets newStamp as new value for the current global modification stamp for the datastore.

info

This function can only be called:

• on the local datastore (ds).
• in client/server environment, on the server machine.

For more information on global stamp and data change tracking, please refer to the Using the Global Stamp page.

Example

The following code sets the modification global stamp:

var $newValue: Real
$newValue:=ReadValueFrom //get a new value to assign
ds.setGlobalStamp($newValue)

See also

.getGlobalStamp()

.setRemoteContextInfo()

History

Version	Changes
v19 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

Version	Changes
v20	Server side support, new options parameter
v17 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.

info

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

Version	Changes
v18	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

Version	Changes
v20	Server side support
v17 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

Version	Changes
v20	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

.flushAndLock()
.locked()

.validateTransaction()

History

Version	Changes
v18	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().