diff --git a/.gitignore b/.gitignore
index 8d2f293d2098c8..566068abc766e0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,13 +1,17 @@
.DS_Store
-node_modules
-
+/node_modules
+docsPostProcessed/
lib/core/metadata.js
lib/core/MetadataBlog.js
-website/translated_docs
+docsPostProcessed
+
+website/siteConfig.js
+
website/build/
website/yarn.lock
website/node_modules
!website/node_modules/highlight.js/lib/index.js
!website/node_modules/highlight.js/lib/languages/code4d.js
+
diff --git a/crowdin.yml b/crowdin.yml
index 2f8898eda5573d..ebc1a79010dc79 100644
--- a/crowdin.yml
+++ b/crowdin.yml
@@ -1,7 +1,6 @@
files:
- source: /docs/**/*.md
translation: /website/translated_docs/%two_letters_code%/**/%original_file_name%
- type: fm_md7
- source: /docs/assets/en/**/*.png
translation: /docs/assets/%two_letters_code%/**/%original_file_name%
- source: /website/i18n/en.json
diff --git a/docs/API/BlobClass.md b/docs/API/BlobClass.md
new file mode 100644
index 00000000000000..f211fde7068ef2
--- /dev/null
+++ b/docs/API/BlobClass.md
@@ -0,0 +1,92 @@
+---
+id: BlobClass
+title: Blob
+---
+
+The Blob class lets you create and manipulate [blob objects](../Concepts/dt_blob.md#blob-types) (`4D.Blob`).
+
+### Summary
+
+||
+|---|
+|[](#4dblobnew) |
+|[](#size)
|
+|[](#slice)
|
+
+## 4D.Blob.new()
+
+History
+|Version|Changes|
+|---|---|
+|v19 R2|Added|
+
**4D.Blob.new**( *blobScal* : Blob ) : 4D.Blob
**4D.Blob.new**( *blobObj* : 4D.Blob ) : 4D.Blob
+
+
+
+| Parameter | Type | | Description |
+| --------- | --------------- | :-: | ------------ |
+| blob | Blob or 4D.Blob | -> | Blob to copy |
+| Result | 4D.Blob | <- | New 4D.Blob |
+
+
+#### Description
+
+`4D.Blob.new` creates a new `4D.Blob` object optionally encapsulating a copy of the data from another blob (scalar blob or `4D.Blob`).
+
+If the `blob` parameter is omitted, the method returns an empty 4D.Blob.
+
+## .size
+
+
+**.size** : Real
+
+#### Description
+The `.size` property returns the size of a `4D.Blob`, expressed in bytes.
+
+## .slice()
+
+History
+|Version|Changes|
+|---|---|
+|v19 R2|Added|
+
**.slice**( *start* : Real ) : 4D.Blob
**.slice**( *start* : Real; *end* : Real ) : 4D.Blob
+
+
+| Parameter | Type ||Description |
+| --------- | ------- | :-: | --- |
+| start| Real | -> | index of the first byte to include in the new `4D.Blob`. |
+| end| Real | -> | index of the first byte that will not be included in the new `4D.Blob` |
+| Result| 4D.Blob | <- | New `4D.Blob`|
+
+#### Description
+
+`.slice()` creates and returns a `4D.Blob ` that references data from a subset of the blob on which it's called. The original blob is not altered.
+
+The `start` parameter is an index into the blob indicating the first byte to include in the new `4D.Blob`. If you specify a negative value, 4D treats it as an offset from the end of the blob toward the beginning. For example, -10 would be the 10th from last byte in the blob. The default value is 0. If you specify a value for start that is larger than the size of the source blob, the returned `4D.Blob`'s size is 0, and it contains no data.
+
+The `end` parameter is an index into the blob indicating the first byte that will not be included in the new `4D.Blob` (i.e. the byte exactly at this index is not included). If you specify a negative value, 4D treats it as an offset from the end of the blob toward the beginning. For example, -10 would be the 10th from last byte in the blob. The default value is the size of the blob.
+
+#### Example
+
+```4d
+var $myBlob : 4D.Blob
+
+// Store text in a 4D.Blob
+CONVERT FROM TEXT("Hello, World!"; "UTF-8"; $myBlob)
+$is4DBlob:=OB Instance of($myBlob; 4D.Blob); //True
+
+$myString:=Convert to text($myBlob; "UTF-8")
+// $myString contains "Hello, World!"
+
+// Create a new 4D.Blob from $myBlob
+$myNewBlob:=$myBlob.slice(0; 5)
+
+$myString:=Convert to text($myNewBlob; "UTF-8")
+// $myString contains "Hello"
+```
diff --git a/docs/API/ClassClass.md b/docs/API/ClassClass.md
new file mode 100644
index 00000000000000..b4efe13478eb28
--- /dev/null
+++ b/docs/API/ClassClass.md
@@ -0,0 +1,146 @@
+---
+id: ClassClass
+title: Class
+---
+
+
+When a user class is [defined](Concepts/classes.md#class-definition) in the project, it is loaded in the 4D language environment. A class is an object itself, of "Class" class, which has properties and a function.
+
+
+
+### Summary
+
+
+||
+|---|
+|[](#name)
|
+|[](#new)
|
+|[](#superclass)
|
+
+
+
+
+## .name
+
+History
+|Version|Changes|
+|---|---|
+|v18 R3|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v18 R3|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R3|Added|
+
+ |
+|[](#new-shared-collection)
|
+
+
+### Example
+
+```4d
+ var $colVar : Collection //creation of collection type 4D variable
+ $colVar:=New collection //initialization of the collection and assignment to the 4D variable
+```
+
+
+### Summary
+
+
+||
+|---|
+|[](#average)
|
+|[](#clear)
|
+|[](#combine)
|
+|[](#concat)
|
+|[](#copy)
|
+|[](#count)
|
+|[](#countvalues)
|
+|[](#distinct)
|
+|[](#equal)
|
+|[](#every)
|
+|[](#extract)
|
+|[](#fill)
|
+|[](#filter)
|
+|[](#find)
|
+|[](#find)
|
+|[](#indexof)
|
+|[](#indices)
|
+|[](#insert)
|
+|[](#join)
|
+|[](#lastindexof)
|
+|[](#length)
|
+|[](#map)
|
+|[](#max)
|
+|[](#min)
|
+|[](#orderby)
|
+|[](#orderbymethod)
|
+|[](#pop)
|
+|[](#push)
|
+|[](#query)
|
+|[](#reduce)
|
+|[](#remove)
|
+|[](#resize)
|
+|[](#reverse)
|
+|[](#shift)
|
+|[](#slice)
|
+|[](#some)
|
+|[](#sort)
|
+|[](#sum)
|
+|[](#unshift)
|
+
+
+
+## `New collection`
+
+
+
+**New collection** {( *...value* : any )} : Collection
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|value|Number, Text, Date, Time, Boolean, Object, Collection, Picture, Pointer|->|Collection's value(s)|
+|Result|Collection|<-|New collection|
+
+
+
+#### Description
+
+The `New collection` command creates a new empty or prefilled collection and returns its reference.
+
+If you do not pass any parameters, `New collection` creates an empty collection and returns its reference.
+
+You must assign the returned reference to a 4D variable of the Collection type.
+
+>Keep in mind that `var : Collection` or `C_COLLECTION` statements declare a variable of the `Collection` type but does not create any collection.
+
+Optionally, you can prefill the new collection by passing one or several *value*(s) as parameter(s).
+
+Otherwise, you can add or modify elements subsequently through assignment. For example:
+
+```4d
+ myCol[10]:="My new element"
+```
+
+If the new element index is beyond the last existing element of the collection, the collection is automatically resized and all new intermediary elements are assigned a **null** value.
+
+You can pass any number of values of any supported type (number, text, date, picture, pointer, object, collection...). Unlike arrays, collections can mix data of different types.
+
+You must pay attention to the following conversion issues:
+
+* If you pass a pointer, it is kept "as is"; it is evaluated using the `JSON Stringify` command
+* Dates are stored as "yyyy-mm-dd" dates or strings with the "YYYY-MM-DDTHH:mm:ss.SSSZ" format, according to the current "dates inside objects" database setting. When converting 4D dates into text prior to storing them in the collection, by default the program takes the local time zone into account. You can modify this behavior using the `Dates inside objects` selector of the `SET DATABASE PARAMETER` command.
+* If you pass a time, it is stored as a number of milliseconds (Real).
+
+#### Example 1
+
+
+
+You want to create a new empty collection and assign it to a 4D collection variable:
+
+```4d
+ var $myCol : Collection
+ $myCol:=New collection
+ //$myCol=[]
+```
+
+#### Example 2
+
+You want to create a prefilled collection:
+
+```4d
+ var $filledColl : Collection
+ $filledColl:=New collection(33;"mike";"november";->myPtr;Current date)
+ //$filledColl=[33,"mike","november","->myPtr","2017-03-28T22:00:00.000Z"]
+```
+
+#### Example 3
+
+You create a new collection and then add a new element:
+
+```4d
+ var $coll : Collection
+ $coll:=New collection("a";"b";"c")
+ //$coll=["a","b","c"]
+ $coll[9]:="z" //add a 10th element with value "z"
+ $vcolSize:=$coll.length //10
+ //$coll=["a","b","c",null,null,null,null,null,null,"z"]
+```
+
+
+
+
+## `New shared collection`
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R3|New *ck shared* option. New *groupWith* parameters|
+|v16 R6|Added|
+
**.copy**( *option* : Integer ) : Collection
**.copy**( *option* : Integer ; *groupWithCol* : Collection ) : Collection
**.copy**( *option* : Integer ; *groupWithObj* : Object ) : Collection
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|option|Integer|->|`ck resolve pointers`: resolve pointers before copying,
`ck shared`: return a shared collection|
+|groupWithCol |Collection|->|Shared collection to be grouped with the resulting collection|
+|groupWithObj |Object|->|Shared object to be grouped with the resulting collection|
+|Result|Collection|<-|Deep copy of the original collection|
+
+
+
+#### Description
+
+The `.copy()` function returns a deep copy of the collection instance.***Deep copy*** means that objects or collections within the original collection are duplicated and do not share any reference with the returned collection.
+
+>This function does not modify the original collection.
+
+If passed, the *option* parameter can contain one of the following constants (or both):
+
+|option |Description|
+|---|---|
+|`ck resolve pointers`| If the original collection contains pointer type values, by default the copy also contains the pointers. However, you can resolve pointers when copying by passing the ck resolve pointers. In this case, each pointer present in the collection is evaluated when copying and its dereferenced value is used.|
+|`ck shared`| By default, copy() returns a regular (not shared) collection, even if the command is applied to a shared collection. Pass the ck shared constant to create a shared collection. In this case, you can use the groupWith parameter to associate the shared collection with another collection or object (see below).|
+
+The *groupWithCol* or *groupWithObj* parameters allow you to designate a collection or an object with which the resulting collection should be associated.
+
+
+#### Example 1
+
+We want to copy the *$lastnames* regular (non shared) collection into the *$sharedObject* shared object. To do this, we must create a shared copy of the collection (*$sharedLastnames*).
+
+```4d
+var $sharedObject : Object
+var $lastnames;$sharedLastnames : Collection
+var $text : Text
+
+$sharedObject:=New shared object
+
+$text:=Document to text(Get 4D folder(Current resources folder)+"lastnames.txt")
+$lastnames:=JSON Parse($text) //$lastnames is a regular collection
+
+$sharedLastnames:=$lastnames.copy(ck shared) //$sharedLastnames is a shared collection
+
+//Now we can put $sharedLastnames into $sharedObject
+Use($sharedObject)
+ $sharedObject.lastnames:=$sharedLastnames
+End use
+```
+
+
+#### Example 2
+
+We want to combine *$sharedColl1* and *$sharedColl2*. Since they belong to different shared groups, a direct combination would result in an error. Therefore, we must make a shared copy of *$sharedColl1* and designate *$sharedColl2* as a shared group for the copy.
+
+```4d
+var $sharedColl1;$sharedColl2;$copyColl : Collection
+
+$sharedColl1:=New shared collection(New shared object("lastname";"Smith"))
+$sharedColl2:=New shared collection(New shared object("lastname";"Brown"))
+
+//$copyColl belongs to the same shared group as $sharedColl2
+ $copyColl:=$sharedColl1.copy(ck shared;$sharedColl2)
+ Use($sharedColl2)
+ $sharedColl2.combine($copyColl)
+ End use
+```
+
+#### Example 3
+
+We have a regular collection (*$lastnames*) and we want to put it in the **Storage** of the application. To do this, we must create a shared copy beforehand (*$sharedLastnames*).
+
+```4d
+var $lastnames;$sharedLastnames : Collection
+var $text : Text
+
+$text:=Document to text(Get 4D folder(Current resources folder)+"lastnames.txt")
+$lastnames:=JSON Parse($text) //$lastnames is a regular collection
+
+$sharedLastnames:=$lastnames.copy(ck shared) // shared copy
+
+Use(Storage)
+ Storage.lastnames:=$sharedLastnames
+End use
+```
+
+#### Example 4
+
+This example illustrates the use of the `ck resolve pointers` option:
+
+```4d
+ var $col : Collection
+ var $p : Pointer
+ $p:=->$what
+
+ $col:=New collection
+ $col.push(New object("alpha";"Hello";"num";1))
+ $col.push(New object("beta";"You";"what";$p))
+
+ $col2:=$col.copy()
+ $col2[1].beta:="World!"
+ ALERT($col[0].alpha+" "+$col2[1].beta) //displays "Hello World!"
+
+ $what:="You!"
+ $col3:=$col2.copy(ck resolve pointers)
+ ALERT($col3[0].alpha+" "+$col3[1].what) //displays "Hello You!"
+```
+
+
+
+
+
+
+
+
+
+## .count()
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+
**.distinct**( *propertyPath* : Text {; *option* : Integer } ) : Collection
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|option|Integer|->|`ck diacritical`: diacritical evaluation ("A" # "a" for example)|
+|propertyPath|Text|->|Path of attribute whose distinct values you want to get|
+|Result|Collection|<-|New collection with only distinct values|
+
+
+
+#### Description
+
+The `.distinct()` function returns a collection containing only distinct (different) values from the original collection.
+
+>This function does not modify the original collection.
+
+The returned collection is automatically sorted. **Null** values are not returned.
+
+By default, a non-diacritical evaluation is performed. If you want the evaluation to be case sensitive or to differentiate accented characters, pass the `ck diacritical` constant in the *option* parameter.
+
+If the collection contains objects, you can pass the *propertyPath* parameter to indicate the object property whose distinct values you want to get.
+
+
+
+#### Example
+
+```4d
+ var $c; $c2 : Collection
+ $c:=New collection
+ $c.push("a";"b";"c";"A";"B";"c";"b";"b")
+ $c.push(New object("size";1))
+ $c.push(New object("size";3))
+ $c.push(New object("size";1))
+ $c2:=$c.distinct() //$c2=["a","b","c",{"size":1},{"size":3},{"size":1}]
+ $c2:=$c.distinct(ck diacritical) //$c2=["a","A","b","B","c",{"size":1},{"size":3},{"size":1}]
+ $c2:=$c.distinct("size") //$c2=[1,3]
+```
+
+
+
+
+
+
+
+
+## .equal()
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+
**.every**( *startFrom* : Integer ; *methodName* : Text { ;*...param* : any } ) : Boolean
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|startFrom|Integer|->|Index to start the test at|
+|methodName|Text|->|Name of the method to call for the test|
+|param|Mixed|->|Parameter(s) to pass to methodName|
+|Result|Boolean|<-|True if all elements successfully passed the test|
+
+
+
+#### Description
+
+The `.every()` function returns **true** if all elements in the collection successfully passed a test implemented in the provided *methodName* method.
+
+
+In *methodName*, pass the name of the method to use to evaluate collection elements, along with its parameter(s) in *param* (optional). *methodName* can perform any test, with or without the parameter(s). This method receives an `Object` in first parameter ($1) and must set *$1.result* to true for every element fulfilling the test.
+
+*methodName* receives the following parameters:
+
+* in *$1.value*: element value to be evaluated
+* in *$2*: param
+* in *$N...*: paramN...
+
+*methodName* sets the following parameter(s):
+
+* *$1.result* (Boolean): **true** if the element value evaluation is successful, **false** otherwise.
+* *$1.stop* (Boolean, optional): **true** to stop the method callback. The returned value is the last calculated.
+
+In all cases, at the point when the `.every()` function encounters the first collection element returning **false** in *$1.result*, it stops calling *methodName* and returns **false**.
+
+By default, `.every()` tests the whole collection. Optionally, you can pass in *startFrom* the index of the element from which to start the test.
+
+* If *startFrom* >= the collection's length, **false** is returned, which means the collection is not tested.
+* If *startFrom* < 0, it is considered as the offset from the end of the collection ( *startFrom:=startFrom+length*).
+* If *startFrom* = 0, the whole collection is searched (default).
+
+
+#### Example 1
+
+```4d
+var $c : Collection
+var $b : Boolean
+$c:=New collection
+$c.push(5;3;1;4;6;2)
+$b:=$c.every("NumberGreaterThan0") //returns true
+$c.push(-1)
+$b:=$c.every("NumberGreaterThan0") //returns false
+```
+
+With the following ***NumberGreaterThan0*** method:
+
+```4d
+$1.result:=$1.value>0
+```
+
+#### Example 2
+
+This example tests that all elements of a collection are of the real type:
+
+```4d
+var $c : Collection
+var $b : Boolean
+$c:=New collection
+$c.push(5;3;1;4;6;2)
+$b:=$c.every("TypeLookUp";Is real) //$b=true
+$c:=$c.push(New object("name";"Cleveland";"zc";35049))
+$c:=$c.push(New object("name";"Blountsville";"zc";35031))
+$b:=$c.every("TypeLookUp";Is real) //$b=false
+```
+
+With the following ***TypeLookUp*** method:
+
+```4d
+#DECLARE ($toEval : Object ; $param : Integer) //$1; $2
+If(Value type($toEval.value)=$param)
+ $toEval.result:=True
+End if
+```
+
+
+
+
+
+
+
+## .extract()
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+
**.extract**( *propertyPath* : Text ; *targetPath* : Text { ;...*propertyPathN* : Text ;... *targetPathN* : Text } ) : Collection
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|propertyPath|Text|->|Object property path whose values must be extracted to the new collection|
+|targetpath|Text|->|Target property path or property name|
+|option|Integer|->|`ck keep null`: include null properties in the returned collection (ignored by default). Parameter ignored if *targetPath* passed.|
+|Result|Collection|<-|New collection containing extracted values|
+
+
+
+#### Description
+
+The `.extract()` function creates and returns a new collection containing *propertyPath* values extracted from the original collection of objects.
+
+>This function does not modify the original collection.
+
+The contents of the returned collection depends on the *targetPath* parameter:
+
+* If the *targetPath* parameter is omitted, `.extract()` populates the new collection with the *propertyPath* values of the original collection.
+
+ By default, elements for which *propertyPath* is null or undefined are ignored in the resulting collection. You can pass the `ck keep null` constant in the *option* parameter to include these values as null elements in the returned collection.
+
+
+* If one or more *targetPath* parameter(s) are passed, `.extract()` populates the new collection with the *propertyPath* properties and each element of the new collection is an object with *targetPath* properties filled with the corresponding *propertyPath* properties. Null values are kept (*option* parameter is ignored with this syntax).
+
+
+#### Example 1
+
+```4d
+var $c : Collection
+$c:=New collection
+$c.push(New object("name";"Cleveland"))
+$c.push(New object("zip";5321))
+$c.push(New object("name";"Blountsville"))
+$c.push(42)
+$c2:=$c.extract("name") // $c2=[Cleveland,Blountsville]
+$c2:=$c.extract("name";ck keep null) //$c2=[Cleveland,null,Blountsville,null]
+```
+
+
+#### Example 2
+
+
+```4d
+var $c : Collection
+$c:=New collection
+$c.push(New object("zc";35060))
+$c.push(New object("name";Null;"zc";35049))
+$c.push(New object("name";"Cleveland";"zc";35049))
+$c.push(New object("name";"Blountsville";"zc";35031))
+$c.push(New object("name";"Adger";"zc";35006))
+$c.push(New object("name";"Clanton";"zc";35046))
+$c.push(New object("name";"Clanton";"zc";35045))
+$c2:=$c.extract("name";"City") //$c2=[{City:null},{City:Cleveland},{City:Blountsville},{City:Adger},{City:Clanton},{City:Clanton}]
+$c2:=$c.extract("name";"City";"zc";"Zip") //$c2=[{Zip:35060},{City:null,Zip:35049},{City:Cleveland,Zip:35049},{City:Blountsville,Zip:35031},{City:Adger,Zip:35006},{City:Clanton,Zip:35046},{City:Clanton,Zip:35045}]
+```
+
+
+
+
+
+
+
+
+## .fill()
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+
**.fill**( *value* : any ; *startFrom* : Integer { ; *end* : Integer } ) : Collection
+
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|value|number, Text, Collection, Object, Date, Boolean|->|Filling value|
+|startFrom|Integer|->|Start index (included)|
+|end|Integer|->|End index (not included)|
+|Result|collection|<-|Original collection with filled values|
+
+
+
+#### Description
+
+The `.fill()` function fills the collection with the specified *value*, optionally from *startFrom* index to *end* index, and returns the resulting collection.
+
+>This function modifies the original collection.
+
+* If the *startFrom* parameter is omitted, *value* is set to all collection elements (*startFrom*=0).
+* If the *startFrom* parameter is passed and *end* omitted, *value* is set to collection elements starting at *startFrom* to the last element of the collection (*end*=length).
+* If both the *startFrom* parameter and *end* are passed, *value* is set to collection elements starting at *startFrom* to the element *end*.
+
+In case of inconsistency, the following rules apply:
+
+* If *startFrom* < 0, it is recalculated as *startFrom:=startFrom+length* (it is considered as the offset from the end of the collection). If the calculated value is negative, *startFrom* is set to 0.
+* If *end* < 0 , it is recalculated as *end:=end+length*.
+* If *end* < *startFrom* (passed or calculated values), the method does nothing.
+
+
+#### Example
+
+```4d
+ var $c : Collection
+ $c:=New collection(1;2;3;"Lemon";Null;"";4;5)
+ $c.fill("2") // $c:=[2,2,2,2,2,2,2,2]
+ $c.fill("Hello";5) // $c=[2,2,2,2,2,Hello,Hello,Hello]
+ $c.fill(0;1;5) // $c=[2,0,0,0,0,Hello,Hello,Hello]
+ $c.fill("world";1;-5) //-5+8=3 -> $c=[2,"world","world",0,0,Hello,Hello,Hello]
+```
+
+
+
+
+
+
+
+
+## .filter()
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+
**.find**( *startFrom* : Integer ; *methodName* : Text { ; *...param* : any } ) : any
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|startFrom|Integer|->|Index to start the search at|
+|methodName|Text|->|Name of the function to call for the find|
+|param|any|->|Parameter(s) to pass to *methodName*|
+|Result|any |<-|First value found, or Undefined if not found|
+
+
+
+#### Description
+
+The `.find()` function returns the first value in the collection for which *methodName*, applied on each element, returns **true**.
+
+>This function does not modify the original collection.
+
+In *methodName*, pass the name of the method to use to evaluate collection elements, along with its parameter(s) in *param* (optional). *methodName* can perform any test, with or without the parameter(s). This method receives an `Object` in the first parameter ($1) and must set *$1.result* to **true** for the first element fulfilling the condition.
+
+*methodName* receives the following parameters:
+
+* in *$1.value:* element value to be evaluated
+* in *$2: param*
+* in *$N...*: param2...paramN
+
+*methodName* sets the following parameter(s):
+
+* *$1.result* (boolean): **true** if the element value matches the search condition.
+* *$1.stop* (boolean, optional): **true** to stop the method callback. The returned value is the last calculated.
+
+By default, `.find()` searches in the whole collection. Optionally, you can pass in *startFrom* the index of element from which to start the search.
+
+* If *startFrom* >= the collection's length, -1 is returned, which means the collection is not searched.
+* If *startFrom* < 0, it is considered as the offset from the end of the collection (*startFrom:=startFrom+length*).
+ **Note**: Even if *startFrom* is negative, the collection is still searched from left to right.
+* If *startFrom* = 0, the whole collection is searched (default).
+
+
+#### Example 1
+
+You want to get the first element with a length smaller than 5:
+
+```4d
+ var $col : Collection
+ $col:=New collection("hello";"world";4;"red horse";"tim";"san jose")
+ $value:=$col.find("LengthLessThan";5) //$value="tim"
+```
+
+The code for ***LengthLessThan*** method is:
+
+```4d
+ var $1 : Object
+ var $2 : Integer
+ If(Value type($1.value)=Is text)
+ $1.result:=(Length($1.value))<$2
+ End if
+```
+
+#### Example 2
+
+You want to find a city name within a collection:
+
+```4d
+ var $c; $c2 : Collection
+ $c:=New collection
+ $c.push(New object("name";"Cleveland";"zc";35049))
+ $c.push(New object("name";"Blountsville";"zc";35031))
+ $c.push(New object("name";"Adger";"zc";35006))
+ $c.push(New object("name";"Clanton";"zc";35046))
+ $c.push(New object("name";"Clanton";"zc";35045))
+ $c2:=$c.find("FindCity";"Clanton") //$c2={name:Clanton,zc:35046}
+```
+
+The code for ***FindCity*** is:
+
+```4d
+ var $1 : Object
+ var $2 : Text
+ $1.result:=$1.value.name=$2 //name is a property name of objects in the collection
+```
+
+
+
+
+
+
+
+
+## .findIndex()
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+
**.findIndex**( *startFrom* : Integer ; *methodName* : Text { ; *...param* : any } ) : Integer
+
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|startFrom|Integer|->|Index to start the search at|
+|methodName|Text|->|Name of the function to call for the find|
+|param|any|->|Parameter(s) to pass to *methodName*|
+|Result|Integer |<-|Index of first value found, or -1 if not found|
+
+
+
+#### Description
+
+The `.findIndex()` function returns the index, in the collection, of the first value for which *methodName*, applied on each element, returns **true**.
+
+>This function does not modify the original collection.
+
+In *methodName*, pass the name of the method to use to evaluate collection elements, along with its parameter(s) in *param* (optional). *methodName* can perform any test, using or not the parameter(s). This method receives an `Object` as first parameter ($1) and must set *$1.result* to **true** for the first element fulfilling the condition.
+
+*methodName* receives the following parameters:
+
+* in *$1.value*: element value to be evaluated
+* in *$2: param*
+* in *$N...*: param2...paramN
+
+*methodName* sets the following parameter(s):
+
+* *$1.result* (boolean): **true** if the element value matches the search condition.
+* *$1.stop* (boolean, optional): **true** to stop the method callback. The returned value is the last calculated.
+
+By default, `.findIndex()` searches in the whole collection. Optionally, you can pass in *startFrom* the index of element from which to start the search.
+
+* If *startFrom* >= the collection's length, -1 is returned, which means the collection is not searched.
+* If *startFrom* < 0, it is considered as the offset from the end of the collection (*startFrom:=startFrom+length*).
+ **Note**: Even if *startFrom* is negative, the collection is still searched from left to right.
+* If *startFrom* = 0, the whole collection is searched (default).
+
+#### Example
+
+You want to find the position of the first city name within a collection:
+
+```4d
+ var $c : Collection
+ var $val2;$val3 : Integer
+ $c:=New collection
+ $c.push(New object("name";"Cleveland";"zc";35049))
+ $c.push(New object("name";"Blountsville";"zc";35031))
+ $c.push(New object("name";"Adger";"zc";35006))
+ $c.push(New object("name";"Clanton";"zc";35046))
+ $c.push(New object("name";"Clanton";"zc";35045))
+ $val2:=$c.findIndex("FindCity";"Clanton") // $val2=3
+ $val3:=$c.findIndex($val2+1;"FindCity";"Clanton") //$val3=4
+```
+
+The code for ***FindCity*** method is:
+
+```4d
+ var $1 : Object
+ var $2 : Text
+ $1.result:=$1.value.name=$2
+```
+
+
+
+
+
+
+
+
+
+## .indexOf()
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+
**.orderBy**( *pathStrings* : Text ) : Collection
**.orderBy**( *pathObjects* : Collection ) : Collection
**.orderBy**( *ascOrDesc* : Integer ) : Collection
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+
+|pathStrings|Text|->|Property path(s) on which to order the collection|
+|pathObjects|Collection|->|Collection of criteria objects|
+|ascOrDesc|Integer|->|`ck ascending` or `ck descending` (scalar values)|
+|Result|Collection |<-|Ordered copy of the collection (shallow copy)|
+
+
+
+#### Description
+
+The `.orderBy()` function returns a new collection containing all elements of the collection in the specified order.
+
+This function returns a *shallow copy*, which means that objects or collections in both collections share the same reference. If the original collection is a shared collection, the returned collection is also a shared collection.
+
+>This function does not modify the original collection.
+
+If you pass no parameter, the function orders scalar values in the collection in ascending order (other element types such as objects or collections are returned unordered). You can modify this automatic order by passing the `ck ascending` or `ck descending` constants in the *ascOrDesc* parameter (see below).
+
+You can also pass a criteria parameter to define how the collection elements must be sorted. Three syntaxes are supported for this parameter:
+
+* *pathStrings* : Text (formula). **Syntax**: `propertyPath1 {desc or asc}, propertyPath2 {desc or asc},...` (default order: asc). *pathStrings* contains a formula made of 1 to x property paths and (optionally) sort orders, separated by commas. The order in which the properties are passed determines the sorting priority of the collection elements. By default, properties are sorted in ascending order. You can set the sort order of a property in the criteria string, separated from the property path by a single space: pass "asc" to sort in ascending order or "desc" in descending order.
+
+* *pathObjects* : Collection. You can add as many objects in the *pathObjects* collection as necessary. By default, properties are sorted in ascending order ("descending" is false). Each element of the collection contains an object structured in the following way:
+
+```4d
+{
+ "propertyPath": string,
+ "descending": boolean
+}
+```
+
+* *ascOrDesc* : Integer. You pass one of the following constants from the **Objects and collections** theme:
+
+ |Constant| Type|Value|Comment|
+ |---|---|---|---|
+ |ck ascending|Longint|0|Elements are ordered in ascending order (default)|
+ |ck descending|Longint|1|Elements are ordered in descending order
+
+ This syntax orders scalar values in the collection only (other element types such as objects or collections are returned unordered).
+
+If the collection contains elements of different types, they are first grouped by type and sorted afterwards. Types are returned in the following order:
+
+1. null
+2. booleans
+3. strings
+4. numbers
+5. objects
+6. collections
+7. dates
+
+#### Example 1
+
+Ordering a collection of numbers in ascending and descending order:
+
+```4d
+ var $c; $c2; $3 : Collection
+ $c:=New collection
+ For($vCounter;1;10)
+ $c.push(Random)
+ End for
+ $c2:=$c.orderBy(ck ascending)
+ $c3:=$c.orderBy(ck descending)
+```
+
+
+#### Example 2
+
+Ordering a collection of objects based on a text formula with property names:
+
+```4d
+ var $c; $c2 : Collection
+ $c:=New collection
+ For($vCounter;1;10)
+ $c.push(New object("id";$vCounter;"value";Random))
+ End for
+ $c2:=$c.orderBy("value desc")
+ $c2:=$c.orderBy("value desc, id")
+ $c2:=$c.orderBy("value desc, id asc")
+```
+
+Ordering a collection of objects with a property path:
+
+```4d
+ var $c; $c2 : Collection
+ $c:=New collection
+ $c.push(New object("name";"Cleveland";"phones";New object("p1";"01";"p2";"02")))
+ $c.push(New object("name";"Blountsville";"phones";New object("p1";"00";"p2";"03")))
+
+ $c2:=$c.orderBy("phones.p1 asc")
+```
+
+
+#### Example 3
+
+Ordering a collection of objects using a collection of criteria objects:
+
+```4d
+ var $crit; $c; $c2 : COllection
+ $crit:=New collection
+ $c:=New collection
+ For($vCounter;1;10)
+ $c.push(New object("id";$vCounter;"value";Random))
+ End for
+ $crit.push(New object("propertyPath";"value";"descending";True))
+ $crit.push(New object("propertyPath";"id";"descending";False))
+ $c2:=$c.orderBy($crit)
+```
+
+Ordering with a property path:
+
+```4d
+ var $crit; $c; $c2 : Collection
+ $c:=New collection
+ $c.push(New object("name";"Cleveland";"phones";New object("p1";"01";"p2";"02")))
+ $c.push(New object("name";"Blountsville";"phones";New object("p1";"00";"p2";"03")))
+ $crit:=New collection(New object("propertyPath";"phones.p2";"descending";True))
+ $c2:=$c.orderBy($crit)
+```
+
+
+
+
+
+
+
+
+
+## .orderByMethod()
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Support of querySettings|
+|v16 R6|Added|
+
**.query**( *queryString* : Text ; *querySettings* : Object ) : Collection
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|queryString|Text|->|Search criteria|
+|value|Mixed|->|Value(s) to compare when using placeholder(s)|
+|querySettings|Object|->|Query options: parameters, attributes|
+|Result|Collection |<-|Element(s) matching queryString in the collection|
+
+
+
+#### Description
+
+The `.query()` function returns all elements of a collection of objects that match the search conditions defined by *queryString* and (optionally) *value* or *querySettings*. If the original collection is a shared collection, the returned collection is also a shared collection.
+
+>This function does not modify the original collection.
+
+The *queryString* parameter uses the following syntax:
+
+```4d
+propertyPath comparator value {logicalOperator propertyPath comparator value}
+```
+
+For detailed information on how to build a query using *queryString*, *value* and *querySettings* parameters, please refer to the [`dataClass.query()`](DataClassClass.md#query) function description.
+
+> Formulas are not supported by the `collection.query()` function, neither in the *queryString* parameter nor as *formula* object parameter.
+
+#### Example 1
+
+```4d
+ var $c; $c2; $c3 : Collection
+ $c:=New collection
+ $c.push(New object("name";"Cleveland";"zc";35049))
+ $c.push(New object("name";"Blountsville";"zc";35031))
+ $c.push(New object("name";"Adger";"zc";35006))
+ $c.push(New object("name";"Clanton";"zc";35046))
+ $c.push(New object("name";"Clanton";"zc";35045))
+ $c2:=$c.query("name = :1";"Cleveland") //$c2=[{name:Cleveland,zc:35049}]
+ $c3:=$c.query("zc > 35040") //$c3=[{name:Cleveland,zc:35049},{name:Clanton,zc:35046},{name:Clanton,zc:35045}]
+```
+
+
+#### Example 2
+
+
+```4d
+ var $c : Collection
+ $c:=New collection
+ $c.push(New object("name";"Smith";"dateHired";!22-05-2002!;"age";45))
+ $c.push(New object("name";"Wesson";"dateHired";!30-11-2017!))
+ $c.push(New object("name";"Winch";"dateHired";!16-05-2018!;"age";36))
+
+ $c.push(New object("name";"Sterling";"dateHired";!10-5-1999!;"age";Null))
+ $c.push(New object("name";"Mark";"dateHired";!01-01-2002!))
+```
+
+This example returns persons whose name contains "in":
+
+```4d
+ $col:=$c.query("name = :1";"@in@")
+ //$col=[{name:Winch...},{name:Sterling...}]
+```
+
+This example returns persons whose name does not begin with a string from a variable (entered by the user, for example):
+
+```4d
+ $col:=$c.query("name # :1";$aString+"@")
+ //if $astring="W"
+ //$col=[{name:Smith...},{name:Sterling...},{name:Mark...}]
+```
+
+This example returns persons whose age is not known (property set to null or undefined):
+
+```4d
+ $col:=$c.query("age=null") //placeholders not allowed with "null"
+ //$col=[{name:Wesson...},{name:Sterling...},{name:Mark...}]
+```
+
+This example returns persons hired more than 90 days ago:
+
+```4d
+ $col:=$c.query("dateHired < :1";(Current date-90))
+ //$col=[{name:Smith...},{name:Sterling...},{name:Mark...}] if today is 01/10/2018
+```
+
+
+#### Example 3
+
+More examples of queries can be found in the `dataClass.query()` page.
+
+
+
+
+
+
+
+
+## .reduce()
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+
**.reduce**( *methodName* : Text ; *initValue* : any { ; *...param* : expression } ) : any
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|methodName |Text|->|Name of the function to call to process collection elements|
+|initValue |Text, Number, Object, Collection, Date, Boolean|->|Value to use as the first argument to the first call of *methodName*|
+|param |expression|->|Parameter(s) to pass to *methodName*|
+|Result|Text, Number, Object, Collection, Date, Boolean |<-|Result of the accumulator value|
+
+
+
+#### Description
+
+
+The `.reduce()` function applies the *methodName* callback method against an accumulator and each element in the collection (from left to right) to reduce it to a single value.
+
+>This function does not modify the original collection.
+
+In *methodName*, pass the name of the method to use to evaluate collection elements, along with its parameter(s) in param (optional). *methodName* takes each collection element and performs any desired operation to accumulate the result into *$1.accumulator*, which is returned in *$1.value*.
+
+You can pass the value to initialize the accumulator in *initValue*. If omitted, *$1.accumulator* starts with *Undefined*.
+
+*methodName* receives the following parameters:
+
+* in *$1.value*: element value to be processed
+* in *$2: param*
+* in *$N...*: *paramN...*
+
+*methodName* sets the following parameter(s):
+
+* *$1.accumulator*: value to be modified by the function and which is initialized by *initValue*.
+* *$1.stop* (boolean, optional): **true** to stop the method callback. The returned value is the last calculated.
+
+
+#### Example 1
+
+
+```4d
+ C_COLLECTION($c)
+ $c:=New collection(5;3;5;1;3;4;4;6;2;2)
+ $r:=$c.reduce("Multiply";1) //returns 86400
+```
+
+With the following ***Multiply*** method:
+
+```4d
+ If(Value type($1.value)=Is real)
+ $1.accumulator:=$1.accumulator*$1.value
+ End if
+```
+
+#### Example
+
+This example allows reducing several collection elements to a single one:
+
+```4d
+ var $c;$r : Collection
+ $c:=New collection
+ $c.push(New collection(0;1))
+ $c.push(New collection(2;3))
+ $c.push(New collection(4;5))
+ $c.push(New collection(6;7))
+ $r:=$c.reduce("Flatten") //$r=[0,1,2,3,4,5,6,7]
+```
+
+With the following ***Flatten*** method:
+
+```4d
+ If($1.accumulator=Null)
+ $1.accumulator:=New collection
+ End if
+ $1.accumulator.combine($1.value)
+```
+
+
+
+
+
+
+
+## .remove()
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+
**.some**( *startFrom* : Integer ; *methodName* : Text { ; *...param* : any } ) : Boolean
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|startFrom |Integer |->|Index to start the test at|
+|methodName |Text |->|Name of the method to call for the test|
+|param |Mixed |->|Parameter(s) to pass to *methodName*|
+|Result|Boolean|<-|True if at least one element successfully passed the test|
+
+
+
+#### Description
+
+The `.some()` function returns true if at least one element in the collection successfully passed a test implemented in the provided *methodName* method.
+
+
+In *methodName*, pass the name of the method to use to evaluate collection elements, along with its parameter(s) in *param* (optional). *methodName* can perform any test, with or without the parameter(s). This method receives an `Object` as first parameter ($1) and must set *$1.result* to **True** for every element fulfilling the test.
+
+*methodName* receives the following parameters:
+
+* in *$1.value*: element value to be evaluated
+* in *$2*: param
+* in *$N...*: param2...paramN
+
+*methodName* sets the following parameter(s):
+
+* *$1.result* (boolean): **true** if the element value evaluation is successful, **false** otherwise.
+* *$1.stop* (boolean, optional): **true** to stop the method callback. The returned value is the last calculated.
+
+In any case, at the point where `.some()` function encounters the first collection element returning true in *$1.result*, it stops calling *methodName* and returns **true**.
+
+By default, `.some()` tests the whole collection. Optionally, you can pass the index of an element from which to start the test in *startFrom*.
+
+* If *startFrom* >= the collection's length, **False** is returned, which means the collection is not tested.
+* If *startFrom* < 0, it is considered as the offset from the end of the collection.
+* If *startFrom* = 0, the whole collection is searched (default).
+
+
+#### Example
+
+
+```4d
+ var $c : Collection
+ var $b : Boolean
+ $c:=New collection
+ $c.push(-5;-3;-1;-4;-6;-2)
+ $b:=$c.some("NumberGreaterThan0") // returns false
+ $c.push(1)
+ $b:=$c.some("NumberGreaterThan0") // returns true
+
+ $c:=New collection
+ $c.push(1;-5;-3;-1;-4;-6;-2)
+ $b:=$c.some("NumberGreaterThan0") //$b=true
+ $b:=$c.some(1;"NumberGreaterThan0") //$b=false
+```
+
+With the following *NumberGreaterThan0* method:
+
+```4d
+ $1.result:=$1.value>0
+```
+
+
+
+
+
+
+
+
+
+## .sort()
+
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v16 R6|Added|
+
|
+|[](#curve)
|
+|[](#decrypt)
|
+|[](#encrypt)
|
+|[](#getprivatekey)
|
+|[](#getpublickey)
|
+|[](#sign)
|
+|[](#size)
|
+|[](#type)
|
+|[](#verify)
|
+
+
+
+
+
+
+
+
+## 4D.CryptoKey.new()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added
+ |
+|[](#exposed)
|
+|[](#fieldnumber)
|
+|[](#fieldtype)
|
+|[](#indexed)
|
+|[](#inversename)
|
+|[](#keywordindexed)
|
+|[](#kind)
|
+|[](#mandatory)
|
+|[](#name)
|
+|[](#readonly)
|
+|[](#relateddataclass)
|
+|[](#type)
|
+|[](#unique)
|
+
+
+
+
+## .autoFilled
+
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v19 R3|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v19 R3|Support of computed attributes|
+
scalar: corresponding 4D field type, see [`Value type`](https://doc.4d.com/4dv19/help/command/en/page1509.html)entity: 38 (`Is object`)entity selection: 42 (`Is collection)`|
+
+
+
+
+#### See also
+
+[`.type`](#type)
+
+
+## .indexed
+
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v19 R3|Added "calculated"|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v19 R3|Added|
+
+
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+
+
+History
+|Version|Changes|
+|---|---|
+|v19 R3|Support of computed attributes|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+ |
+|[](#all)
|
+|[](#exposed)
|
+|[](#fromcollection)
|
+|[](#get)
|
+|[](#getdatastore)
|
+|[](#getinfo)
|
+|[](#new)
|
+|[](#newselection)
|
+|[](#query)
|
+
+
+
+
+## .*attributeName*
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Support of the *settings* parameter|
+|v17|Added|
+History
+|Version|Changes|
+|---|---|
+|v19 R3|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Support of the *settings* parameter|
+|v17|Added|
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+
**.get**( *primaryKey* : Text { ; *settings* : Object } ) : 4D.Entity
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|primaryKey |Integer OR Text|->|Primary key value of the entity to retrieve|
+|settings |Object|->|Build option: context|
+|Result|4D.Entity|<-|Entity matching the designated primary key|
+
+
+#### Description
+
+The `.get()` function queries the dataclass to retrieve the entity matching the *primaryKey* parameter.
+
+In *primaryKey*, pass the primary key value of the entity to retrieve. The value type must match the primary key type set in the datastore (Integer or Text). You can also make sure that the primary key value is always returned as Text by using the [`.getKey()`](EntityClass.md#getkey) function with the `dk key as string` parameter.
+
+If no entity is found with *primaryKey*, a **Null** entity is returned.
+
+Lazy loading is applied, which means that related data is loaded from disk only when it is required.
+
+**settings**
+
+In the optional *settings* parameter, you can pass an object containing additional options. The following property is supported:
+
+|Property| Type| Description|
+|---|---|---|
+|context| Text| Label for the automatic optimization context applied to the entity. This context will be used by the subsequent code that loads the entity so that it can benefit from the optimization. This feature is [designed for ORDA client/server processing](ORDA/entities.md#client-server-optimization).|
+
+
+
+#### Example 1
+
+```4d
+ var $entity : cs.EmployeeEntity
+ var $entity2 : cs.InvoiceEntity
+ $entity:=ds.Employee.get(167) // return the entity whose primary key value is 167
+ $entity2:=ds.Invoice.get("DGGX20030") // return the entity whose primary key value is "DGGX20030"
+```
+
+#### Example 2
+
+This example illustrates the use of the *context* property:
+
+```4d
+ var $e1; $e2; $e3; $e4 : cs.EmployeeEntity
+ var $settings; $settings2 : Object
+
+ $settings:=New object("context";"detail")
+ $settings2:=New object("context";"summary")
+
+ $e1:=ds.Employee.get(1;$settings)
+ completeAllData($e1) // In completeAllData method, an optimization is triggered and associated to context "detail"
+
+ $e2:=ds.Employee.get(2;$settings)
+ completeAllData($e2) // In completeAllData method, the optimization associated to context "detail" is applied
+
+ $e3:=ds.Employee.get(3;$settings2)
+ completeSummary($e3) //In completeSummary method, an optimization is triggered and associated to context "summary"
+
+ $e4:=ds.Employee.get(4;$settings2)
+ completeSummary($e4) //In completeSummary method, the optimization associated to context "summary" is applied
+```
+
+
+
+
+
+
+## .getDataStore()
+
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
`dk non ordered`: creates an unordered entity selection (default if omitted) |
+|Result|4D.EntitySelection|<-|New blank entity selection related to the dataclass|
+
+
+
+#### Description
+
+The `.newSelection( )` function creates a new, blank, non-shareable entity selection, related to the dataclass, in memory.
+
+> For information on non-shareable entity selections, please refer to [this section](ORDA/entities.md#shareable-or-non-shareable-entity-selections).
+
+
+If you want to create an ordered entity selection, pass the `dk keep ordered` selector in the *keepOrder* parameter. By default if you omit this parameter, or if you pass the `dk non ordered` selector, the method creates an unordered entity selection. Unordered entity selections are faster but you cannot rely on entity positions. For more information, please see [Ordered vs Unordered entity selections](ORDA/dsMapping.md#ordered-or-unordered-entity-selection).
+
+When created, the entity selection does not contain any entities (`mySelection.length` returns 0). This method lets you build entity selections gradually by making subsequent calls to the [`add()`](EntitySelectionClass.md#add) function.
+
+
+#### Example
+
+
+```4d
+ var $USelection; $OSelection : cs.EmployeeSelection
+ $USelection:=ds.Employee.newSelection() //create an unordered empty entity selection
+ $OSelection:=ds.Employee.newSelection(dk keep ordered) //create an ordered empty entity selection
+```
+
+
+
+
+
+
+
+## .query()
+
+History
+|Version|Changes|
+|---|---|
+|v17 R6|Support of Formula parameters|
+|v17 R5|Support of placeholders for values|
+|v17|Added|
+
**.query**( *formula* : Object { ; *querySettings* : Object } ) : 4D.EntitySelection
+
+
+|Parameter|Type||Description|
+|---|---|---|---|
+|queryString |Text |-> |Search criteria as string|
+|formula |Object |-> |Search criteria as formula object|
+|value|any|->|Value(s) to use for indexed placeholder(s)|
+|querySettings|Object|->|Query options: parameters, attributes, args, allowFormulas, context, queryPath, queryPlan|
+|Result|4D.EntitySelection|<-|New entity selection made up of entities from dataclass meeting the search criteria specified in *queryString* or *formula*|
+
+
+
+#### Description
+
+The `.query( )` function searches for entities that meet the search criteria specified in *queryString* or *formula* and (optionally) *value*(s), for all the entities in the dataclass, and returns a new object of type `EntitySelection` containing all the entities that are found. Lazy loading is applied.
+
+If no matching entities are found, an empty `EntitySelection` is returned.
+
+**queryString parameter**
+
+The *queryString* parameter uses the following syntax:
+
+```4d
+attributePath|formula comparator value
+ {logicalOperator attributePath|formula comparator value}
+ {order by attributePath {desc | asc}}
+```
+
+where:
+
+* **attributePath**: path of attribute on which you want to execute the query. This parameter can be a simple name (for example "country") or any valid attribute path (for example "country.name".) In case of an attribute path whose type is `Collection`, \[ ] notation is used to handle all the occurences (for example "children\[ ].age"). You can also use a **placeholder** (see below).
+
+ >*You cannot use directly attributes whose name contains special characters such as ".", "\[ ]", or "=", ">", "#"..., because they will be incorrectly evaluated in the query string. If you need to query on such attributes, you must consider using placeholders, which allow an extended range of characters in attribute paths (see* **Using placeholders** *below).*
+
+* **formula**: a valid formula passed as `Text` or `Object`. The formula will be evaluated for each processed entity and must return a boolean value. Within the formula, the entity is available through the `This` object.
+
+ * **Text**: the formula string must be preceeded by the `eval( )` statement, so that the query parser evaluates the expression correctly. For example: *"eval(length(This.lastname) >=30)"*
+ * **Object**: the [formula object](FunctionClass.md) is passed as a **placeholder** (see below). The formula must have been created using the [`Formula`](FunctionClass.md#formula) or [`Formula from string`](FunctionClass.md#formula-from-string) command.
+
+ >* Keep in mind that 4D formulas only support `&` and `|` symbols as logical operators.
+ >* If the formula is not the only search criteria, the query engine optimizer could prior process other criteria (e.g. indexed attributes) and thus, the formula could be evaluated for only a subset of entities.
+
+ Formulas in queries can receive parameters through $1. This point is detailed in the **formula parameter** paragraph below.
+
+ >* You can also pass directy a `formula` parameter object instead of the `queryString` parameter (recommended when formulas are more complex). See **formula parameter** paragraph below.
+ >* For security reasons, formula calls within `query()` methods can be disallowed. See `querySettings` parameter description.
+
+* **comparator**: symbol that compares *attributePath* and *value*. The following symbols are supported:
+
+ |Comparison| Symbol(s)| Comment|
+ |---|---|---|
+ |Equal to |=, == |Gets matching data, supports the wildcard (@), neither case-sensitive nor diacritic.|
+ ||===, IS| Gets matching data, considers the @ as a standard character, neither case-sensitive nor diacritic|
+ |Not equal to| #, != |Supports the wildcard (@)|
+ ||!==, IS NOT| Considers the @ as a standard character|
+ |Less than| <| |
+ |Greater than| > ||
+ |Less than or equal to| <=||
+ |Greater than or equal to| >= ||
+ |Included in| IN |Gets data equal to at least one of the values in a collection or in a set of values, supports the wildcard (@)|
+ |Not condition applied on a statement| NOT| Parenthesis are mandatory when NOT is used before a statement containing several operators|
+ |Contains keyword| %| Keywords can be used in attributes of string or picture type|
+
+* **value**: the value to compare to the current value of the property of each entity in the entity selection or element in the collection. It can be a **placeholder** (see **Using placeholders** below) or any expression matching the data type property.
+When using a constant value, the following rules must be respected:
+ * **text** type constant can be passed with or without simple quotes (see **Using quotes** below). To query a string within a string (a "contains" query), use the wildcard symbol (@) in value to isolate the string to be searched for as shown in this example: "@Smith@". The following keywords are forbidden for text constants: true, false.
+ * **boolean** type constants: **true** or **false** (case sensitive).
+ * **numeric** type constants: decimals are separated by a '.' (period).
+date type constants: "YYYY-MM-DD" format
+ * **null** constant: using the "null" keyword will find **null** and **undefined** properties.
+ * in case of a query with an IN comparator, value must be a collection, or values matching the type of the attribute path between \[ ] separated by commas (for strings, " characters must be escaped with "\").
+* **logicalOperator**: used to join multiple conditions in the query (optional). You can use one of the following logical operators (either the name or the symbol can be used):
+
+ |Conjunction|Symbol(s)|
+ |---|---|
+ |AND|&, &&, and|
+ |OR | |,||, or|
+
+* **order by attributePath**: you can include an order by *attributePath* statement in the query so that the resulting data will be sorted according to that statement. You can use multiple order by statements, separated by commas (e.g., order by *attributePath1* desc, *attributePath2* asc). By default, the order is ascending. Pass 'desc' to define a descending order and 'asc' to define an ascending order.
+ >*If you use this statement, the returned entity selection is ordered (for more information, please refer to [Ordered vs Unordered entity selections](ORDA/dsMapping.md#ordered-or-unordered-entity-selection)).
+
+**Using quotes**
+
+When you use quotes within queries, you must use single quotes ' ' inside the query and double quotes " " to enclose the whole query, otherwise an error is returned. For example:
+
+```4d
+"employee.name = 'smith' AND employee.firstname = 'john'"
+```
+
+>Single quotes (') are not supported in searched values since they would break the query string. For example "comp.name = 'John's pizza' " will generate an error. If you need to search on values with single quotes, you may consider using placeholders (see below).
+
+**Using parenthesis**
+
+You can use parentheses in the query to give priority to the calculation. For example, you can organize a query as follows:
+
+```4d
+"(employee.age >= 30 OR employee.age <= 65) AND (employee.salary <= 10000 OR employee.status = 'Manager')"
+```
+
+
+**Using placeholders**
+
+4D allows you to use placeholders for *attributePath*, *formula* and *value* arguments within the *queryString* parameter. A placeholder is a parameter that you insert in query strings and that is replaced by another value when the query string is evaluated. The value of placeholders is evaluated once at the beginning of the query; it is not evaluated for each element.
+
+Two types of placeholders can be used: **indexed placeholders** and **named placeholders**:
+
+|- |Indexed placeholders| Named placeholders|
+|---|---|---|
+|Definition |Parameters are inserted as :paramIndex (for example :1, :2...) in queryString and their corresponding values are provided by the sequence of value parameter(s). You can use up to 128 value parameters| Parameters are inserted as :paramName (for example :myparam) and their values are provided in the attributes and/or parameters objects in the querySettings parameter|
+|Example|$r:=class.query(":1=:2";"city";"Chicago")| $o.attributes:=New object("att";"city")
$o.parameters:=New object("name";"Chicago")
$r:=class.query(":att=:name";$o)|
+
+You can mix all argument kinds in *queryString*. A *queryString* can contain, for *attributePath*, *formula* and *value* parameters:
+
+
+* direct values (no placeholders),
+* indexed placeholders and/or named placeholders.
+
+**Using placeholders in queries is recommended** for the following reasons:
+
+1. It prevents malicious code insertion: if you directly use user-filled variables within the query string, a user could modifiy the query conditions by entering additional query arguments. For example, imagine a query string like:
+
+ ```4d
+ $vquery:="status = 'public' & name = "+myname //user enters their name
+ $result:=$col.query($vquery)
+ ```
+
+ This query seems secured since non-public data are filtered. However, if the user enters in the *myname* area something like *"smith OR status='private'*, the query string would be modified at the interpretation step and could return private data.
+
+ When using placeholders, overriding security conditions is not possible:
+
+ ```4d
+ $result:=$col.query("status='public' & name=:1";myname)
+ ```
+
+ In this case if the user enters *smith OR status='private'* in the *myname* area, it will not be interpreted in the query string, but only passed as a value. Looking for a person named "smith OR status='private'" will just fail.
+
+2. It prevents having to worry about formatting or character issues, especially when handling *attributePath* or *value* parameters that might contain non-alphanumeric characters such as ".", "['...
+
+3. It allows the use of variables or expressions in query arguments. Examples:
+
+ ```4d
+ $result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@")
+ $result2:=$col.query("company.name = :1";"John's Pizzas")
+ ```
+
+**Looking for null values**
+
+When you look for null values, you cannot use the placeholder syntax because the query engine considers null as an unexpected comparison value. For example, if you execute the following query:
+
+```4d
+$vSingles:=ds.Person.query("spouse = :1";Null) // will NOT work
+```
+
+You will not get the expected result because the null value will be evaluated by 4D as an error resulting from the parameter evaluation (for example, an attribute coming from another query). For these kinds of queries, you must use the direct query syntax:
+
+```4d
+ $vSingles:=ds.Person.query("spouse = null") //correct syntax
+```
+
+
+**Linking collection attribute query arguments**
+
+When searching in collections within object attributes using multiple query arguments joined by the AND operator, you may want to make sure that only entities containing elements that match all arguments are returned, and not entities where arguments can be found in different elements. To do this, you need to link query arguments to collection elements, so that only single elements containing linked arguments are found.
+
+For example, with the following two entities:
+
+```
+Entity 1:
+ds.People.name: "martin"
+ds.People.places:
+ { "locations" : [ {
+ "kind":"home",
+ "city":"paris"
+ } ] }
+
+Entity 2:
+ds.People.name: "smith"
+ds.People.places:
+ { "locations" : [ {
+ "kind":"home",
+ "city":"lyon"
+ } , {
+ "kind":"office",
+ "city":"paris"
+ } ] }
+```
+
+You want to find people with a "home" location kind in the city "paris". If you write:
+
+```4d
+ds.People.query("places.locations[].kind= :1 and places.locations[].city= :2";"home";"paris")
+```
+
+... the query will return "martin" **and** "smith" because "smith" has a "locations" element whose "kind" is "home" and a "locations" element whose "city" is "paris", even though they are different elements.
+
+If you want to only get entities where matching arguments are in the same collection element, you need to **link arguments**. To link query arguments:
+
+- Add a letter between the \[] in the first path to link and repeat the same letter in all linked arguments. For example: `locations[a].city and locations[a].kind`. You can use any letter of the Latin alphabet (not case sensitive).
+- To add different linked criteria in the same query, use another letter. You can create up to 26 combinations of criteria in a single query.
+
+With the above entities, if you write:
+
+```4d
+ds.People.query("places.locations[a].kind= :1 and places.locations[a].city= :2";"home";"paris")
+```
+
+... the query will only return "martin" because it has a "locations" element whose "kind" is "home" and whose "city" is "paris". The query will not return "smith" because the values "home" and "paris" are not in the same collection element.
+
+
+
+**formula parameter**
+
+As an alternative to formula insertion within the *queryString* parameter (see above), you can pass directly a formula object as a boolean search criteria. Using a formula object for queries is **recommended** since you benefit from tokenization, and code is easier to search/read.
+
+The formula must have been created using the `Formula` or `Formula from string` command. In this case:
+
+* the *formula* is evaluated for each entity and must return true or false. During the execution of the query, if the formula's result is not a boolean, it is considered as false.
+* within the *formula*, the entity is available through the `This` object.
+* if the `Formula` object is **null**, the errror 1626 ("Expecting a text or formula") is generated, that you call intercept using a method installed with `ON ERR CALL`.
+
+ >For security reasons, formula calls within `query(`) member methods can be disallowed. See *querySettings* parameter description.
+
+**Passing parameters to formulas**
+
+Any *formula* called by the `query()` class function can receive parameters:
+
+* Parameters must be passed through the **args** property (object) of the *querySettings* parameter.
+* The formula receives this **args** object as a **$1** parameter.
+
+This small code shows the principles of how parameter are passed to methods:
+
+```4d
+ $settings:=New object("args";New object("exclude";"-")) //args object to pass parameters
+ $es:=ds.Students.query("eval(checkName($1.exclude))";$settings) //args is received in $1
+```
+
+Additional examples are provided in example 3.
+
+**4D Server**: In client/server, formulas are executed on the server. In this context, only the `querySettings.args` object is sent to the formulas.
+
+
+
+**querySettings parameter**
+
+In the *querySettings* parameter, you can pass an object containing additional options. The following properties are supported:
+
+|Property| Type| Description|
+|---|---|---|
+|parameters|Object|**Named placeholders for values** used in the *queryString* or *formula*. Values are expressed as property / value pairs, where property is the placeholder name inserted for a value in the *queryString* or *formula* (":placeholder") and value is the value to compare. You can mix indexed placeholders (values directly passed in value parameters) and named placeholder values in the same query.|
+|attributes|Object|**Named placeholders for attribute paths** used in the *queryString* or *formula*. Attributes are expressed as property / value pairs, where property is the placeholder name inserted for an attribute path in the *queryString* or *formula* (":placeholder"), and value can be a string or a collection of strings. Each value is a path that can designate either a scalar or a related attribute of the dataclass or a property in an object field of the dataclass
| Type | Description |
|---|
| String | attributePath expressed using the dot notation, e.g. "name" or "user.address.zipCode" |
| Collection of strings | Each string of the collection represents a level of attributePath, e.g. \["name"] or \["user","address","zipCode"]. Using a collection allows querying on attributes with names that are not compliant with dot notation, e.g. \["4Dv17.1","en/fr"] |
You can mix indexed placeholders (values directly passed in *value* parameters) and named placeholder values in the same query.|
+|args|Object|Parameter(s) to pass to formulas, if any. The **args** object will be received in $1 within formulas and thus its values will be available through *$1.property* (see example 3).|
+|allowFormulas| Boolean|True to allow the formula calls in the query (default). Pass false to disallow formula execution. If set to false and `query()` is given a formula, an error is sent (1278 - Formula not allowed in this member method).|
+|context|Text|Label for the automatic optimization context applied to the entity selection. This context will be used by the code that handles the entity selection so that it can benefit from the optimization. This feature is designed for client/server processing; for more information, please refer to the **Client/server optimization** section.|
+|queryPlan| Boolean |In the resulting entity selection, returns or does not return the detailed description of the query just before it is executed, i.e. the planned query. The returned property is an object that includes each planned query and subquery (in the case of a complex query). This option is useful during the development phase of an application. It is usually used in conjunction with queryPath. Default if omitted: false. **Note**: This property is supported only by the `entitySelection.query( )` and `dataClass.query( )` functions.|
+|queryPath|Boolean| In the resulting entity selection, returns or does not return the detailed description of the query as it is actually performed. The returned property is an object that contains the actual path used for the query (usually identical to that of the queryPlan, but may differ if the engine manages to optimize the query), as well as the processing time and the number of records found. This option is useful during the development phase of an application. Default if omitted: false. **Note**: This property is supported only by the `entitySelection.query( )` and `dataClass.query( )` functions.|
+
+**About queryPlan and queryPath**
+
+The information recorded in `queryPlan`/`queryPath` include the query type (indexed and sequential) and each necessary subquery along with conjunction operators. Query paths also contain the number of entities found and the time required to execute each search criterion. You may find it useful to analyze this information while developing your application(s). Generally, the description of the query plan and its path are identical but they can differ because 4D can implement dynamic optimizations when a query is executed in order to improve performance. For example, the 4D engine can dynamically convert an indexed query into a sequential one if it estimates that it is faster. This particular case can occur when the number of entities being searched for is low.
+
+For example, if you execute the following query:
+
+```4d
+ $sel:=ds.Employee.query("salary < :1 and employer.name = :2 or employer.revenues > :3";\
+ 50000;"Lima West Kilo";10000000;New object("queryPath";True;"queryPlan";True))
+```
+
+queryPlan:
+
+```4d
+{Or:[{And:[{item:[index : Employee.salary ] < 50000},
+ {item:Join on Table : Company : Employee.employerID = Company.ID,
+ subquery:[{item:[index : Company.name ] = Lima West Kilo}]}]},
+ {item:Join on Table : Company : Employee.employerID = Company.ID,
+ subquery:[{item:[index : Company.revenues ] > 10000000}]}]}
+```
+
+queryPath:
+
+```4d
+{steps:[{description:OR,time:63,recordsfounds:1388132,
+ steps:[{description:AND,time:32,recordsfounds:131,
+ steps:[{description:[index : Employee.salary ] < 50000,time:16,recordsfounds:728260},{description:Join on Table : Company : Employee.employerID = Company.ID,time:0,recordsfounds:131,
+ steps:[{steps:[{description:[index : Company.name ] = Lima West Kilo,time:0,recordsfounds:1}]}]}]},{description:Join on Table : Company : Employee.employerID = Company.ID,time:31,recordsfounds:1388132,
+ steps:[{steps:[{description:[index : Company.revenues ] > 10000000,time:0,recordsfounds:933}]}]}]}]}
+```
+
+#### Example 1
+
+This section provides various examples of queries.
+
+Query on a string:
+
+```4d
+$entitySelection:=ds.Customer.query("firstName = 'S@'")
+```
+
+Query with a NOT statement:
+
+```4d
+$entitySelection:=ds.Employee.query("not(firstName=Kim)")
+```
+
+Queries with dates:
+
+```4d
+$entitySelection:=ds.Employee.query("birthDate > :1";"1970-01-01")
+$entitySelection:=ds.Employee.query("birthDate <= :1";Current date-10950)
+```
+
+Query with indexed placeholders for values:
+
+```4d
+$entitySelection:=ds.Customer.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";"D@";"R@";"S@";"K@")
+```
+
+Query with indexed placeholders for values on a related dataclass:
+
+```4d
+$entitySelection:=ds.Employee.query("lastName = :1 and manager.lastName = :2";"M@";"S@")
+```
+
+Query with indexed placeholder including a descending order by statement:
+
+```4d
+$entitySelection:=ds.Student.query("nationality = :1 order by campus.name desc, lastname";"French")
+```
+
+Query with named placeholders for values:
+
+```4d
+var $querySettings : Object
+var $managedCustomers : cs.CustomerSelection
+$querySettings:=New object
+$querySettings.parameters:=New object("userId";1234;"extraInfo";New object("name";"Smith"))
+$managedCustomers:=ds.Customer.query("salesperson.userId = :userId and name = :extraInfo.name";$querySettings)
+```
+
+Query that uses both named and indexed placeholders for values:
+
+```4d
+var $querySettings : Object
+var $managedCustomers : cs.CustomerSelection
+$querySettings.parameters:=New object("userId";1234)
+$managedCustomers:=ds.Customer.query("salesperson.userId = :userId and name=:1";"Smith";$querySettings)
+```
+
+Query with queryPlan and queryPath objects:
+
+```4d
+$entitySelection:=ds.Employee.query("(firstName = :1 or firstName = :2) and (lastName = :3 or lastName = :4)";"D@";"R@";"S@";"K@";New object("queryPlan";True;"queryPath";True))
+
+ //you can then get these properties in the resulting entity selection
+var $queryPlan; $queryPath : Object
+$queryPlan:=$entitySelection.queryPlan
+$queryPath:=$entitySelection.queryPath
+```
+
+Query with an attribute path of Collection type:
+
+```4d
+$entitySelection:=ds.Employee.query("extraInfo.hobbies[].name = :1";"horsebackriding")
+```
+
+Query with an attribute path of Collection type and linked attributes:
+
+```4d
+$entitySelection:=ds.Employee.query("extraInfo.hobbies[a].name = :1 and extraInfo.hobbies[a].level=:2";"horsebackriding";2)
+```
+
+Query with an attribute path of Collection type and multiple linked attributes:
+
+```4d
+$entitySelection:=ds.Employee.query("extraInfo.hobbies[a].name = :1 and
+ extraInfo.hobbies[a].level = :2 and extraInfo.hobbies[b].name = :3 and
+ extraInfo.hobbies[b].level = :4";"horsebackriding";2;"Tennis";5)
+```
+
+Query with an attribute path of Object type:
+
+```4d
+$entitySelection:=ds.Employee.query("extra.eyeColor = :1";"blue")
+```
+
+Query with an IN statement:
+
+```4d
+$entitySelection:=ds.Employee.query("firstName in :1";New collection("Kim";"Dixie"))
+```
+
+Query with a NOT (IN) statement:
+
+```4d
+$entitySelection:=ds.Employee.query("not (firstName in :1)";New collection("John";"Jane"))
+```
+
+Query with indexed placeholders for attributes:
+
+```4d
+var $es : cs.EmployeeSelection
+$es:=ds.Employee.query(":1 = 1234 and :2 = 'Smith'";"salesperson.userId";"name")
+ //salesperson is a related entity
+```
+
+Query with indexed placeholders for attributes and named placeholders for values:
+
+```4d
+var $es : cs.EmployeeSelection
+var $querySettings : Object
+$querySettings:=New object
+$querySettings.parameters:=New object("customerName";"Smith")
+$es:=ds.Customer.query(":1 = 1234 and :2 = :customerName";"salesperson.userId";"name";$querySettings)
+ //salesperson is a related entity
+```
+
+Query with indexed placeholders for attributes and values:
+
+
+```4d
+var $es : cs.EmployeeSelection
+$es:=ds.Clients.query(":1 = 1234 and :2 = :3";"salesperson.userId";"name";"Smith")
+ //salesperson is a related entity
+```
+
+#### Example 2
+
+This section illustrates queries with named placeholders for attributes.
+
+Given an Employee dataclass with 2 entities:
+
+Entity 1:
+
+```4d
+name: "Marie"
+number: 46
+softwares:{
+"Word 10.2": "Installed",
+"Excel 11.3": "To be upgraded",
+"Powerpoint 12.4": "Not installed"
+}
+```
+
+Entity 2:
+
+```4d
+name: "Sophie"
+number: 47
+softwares:{
+"Word 10.2": "Not installed",
+"Excel 11.3": "To be upgraded",
+"Powerpoint 12.4": "Not installed"
+}
+```
+
+Query with named placeholders for attributes:
+
+```4d
+ var $querySettings : Object
+ var $es : cs.EmployeeSelection
+ $querySettings:=New object
+ $querySettings.attributes:=New object("attName";"name";"attWord";New collection("softwares";"Word 10.2"))
+ $es:=ds.Employee.query(":attName = 'Marie' and :attWord = 'Installed'";$querySettings)
+ //$es.length=1 (Employee Marie)
+```
+
+Query with named placeholders for attributes and values:
+
+```4d
+ var $querySettings : Object
+ var $es : cs.EmployeeSelection
+ var $name : Text
+ $querySettings:=New object
+ //Named placeholders for values
+ //The user is asked for a name
+ $name:=Request("Please enter the name to search:")
+ If(OK=1)
+ $querySettings.parameters:=New object("givenName";$name)
+ //Named placeholders for attribute paths
+ $querySettings.attributes:=New object("attName";"name")
+ $es:=ds.Employee.query(":attName= :givenName";$querySettings)
+ End if
+```
+
+#### Example 3
+
+These examples illustrate the various ways to use formulas with or without parameters in your queries.
+
+The formula is given as text with `eval()` in the *queryString* parameter:
+
+```4d
+ var $es : cs.StudentsSelection
+ $es:=ds.Students.query("eval(length(This.lastname) >=30) and nationality='French'")
+```
+
+The formula is given as a `Formula` object through a placeholder:
+
+```4d
+ var $es : cs.StudentsSelection
+ var $formula : Object
+ $formula:=Formula(Length(This.lastname)>=30)
+ $es:=ds.Students.query(":1 and nationality='French'";$formula)
+```
+
+Only a `Formula` object is given as criteria:
+
+```4d
+ var $es : cs.StudentsSelection
+ var $formula : Object
+ $formula:=Formula(Length(This.lastname)>=30)
+ $es:=ds.Students.query($formula)
+```
+
+Several formulas can be applied:
+
+```4d
+ var $formula1; $1; $formula2 ;$0 : Object
+ $formula1:=$1
+ $formula2:=Formula(Length(This.firstname)>=30)
+ $0:=ds.Students.query(":1 and :2 and nationality='French'";$formula1;$formula2)
+```
+
+
+A text formula in *queryString* receives a parameter:
+
+```4d
+ var $es : cs.StudentsSelection
+ var $settings : Object
+ $settings:=New object()
+ $settings.args:=New object("filter";"-")
+ $es:=ds.Students.query("eval(checkName($1.filter)) and nationality=:1";"French";$settings)
+```
+
+```4d
+ //checkName method
+ #DECLARE($exclude : Text) -> $result : Boolean
+ $result:=(Position($exclude;This.lastname)=0)
+```
+
+Using the same ***checkName*** method, a `Formula` object as placeholder receives a parameter:
+
+```4d
+ var $es : cs.StudentsSelection
+ var $settings; $formula : Object
+ $formula:=Formula(checkName($1.filter))
+ $settings:=New object()
+ $settings.args:=New object("filter";"-")
+ $es:=ds.Students.query(":1 and nationality=:2";$formula;"French";$settings)
+ $settings.args.filter:="*" // change the parameters without updating the $formula object
+ $es:=ds.Students.query(":1 and nationality=:2";$formula;"French";$settings)
+```
+
+We want to disallow formulas, for example when the user enters their query:
+
+```4d
+ var $es : cs.StudentsSelection
+ var $settings : Object
+ var $queryString : Text
+ $queryString:=Request("Enter your query:")
+ if(OK=1)
+ $settings:=New object("allowFormulas";False)
+ $es:=ds.Students.query($queryString;$settings) //An error is raised if $queryString contains a formula
+ End if
+```
+
+#### See also
+
+[`.query()`](EntitySelectionClass.md#query) for entity selections
+
+
+
diff --git a/docs/API/DataStoreClass.md b/docs/API/DataStoreClass.md
new file mode 100644
index 00000000000000..395532bb574ce5
--- /dev/null
+++ b/docs/API/DataStoreClass.md
@@ -0,0 +1,877 @@
+---
+id: DataStoreClass
+title: DataStore
+---
+
+A [Datastore](ORDA/dsMapping.md#datastore) is the interface object provided by ORDA to reference and access a database. `Datastore` objects are returned by the following commands:
+
+* [ds](#ds): a shortcut to the main datastore
+* [Open datastore](#open-datastore): to open any remote datastore
+
+### Summary
+
+||
+|---|
+|[](#canceltransaction) |
+|[](#dataclassname)
|
+|[](#encryptionstatus)
|
+|[](#getinfo)
|
+|[](#getrequestlog)
|
+|[](#makeselectionsalterable)
|
+|[](#providedatakey)
|
+|[](#setadminprotection)
|
+|[](#startrequestlog)
|
+|[](#starttransaction)
|
+|[](#stoprequestlog)
|
+|[](#validatetransaction)
|
+
+
+
+
+
+## ds
+
+History
+|Version|Changes|
+|---|---|
+|v18|Support of localID parameter|
+|v17|Added|
+History
+|Version|Changes|
+|---|---|
+|v18|Added|
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+History
+|Version|Changes|
+|---|---|
+|v18|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+
"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
+
+```4d
+ 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:
+
+```4d
+ 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"}}
+```
+
+
+
+
+
+
+
+## .getRequestLog()
+
+History
+|Version|Changes|
+|---|---|
+|v17 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+
**.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
+
+```4d
+ 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|
+History
+|Version|Changes|
+|---|---|
+|v17 R6|Added|
+
**.startRequestLog**( *file* : 4D.File )
**.startRequestLog**( *reqNum* : Integer )
+
+
+
+|Parameter|Type||Description|
+|---|---|---|---|
+|file |4D.File|->|File object|
+|reqNum |Integer|->|Number of requests to keep in memory|
+
+
+
+#### Description
+
+The `.startRequestLog()` function starts the logging of ORDA requests on the client side.
+
+This function must be called on a remote 4D, otherwise it does nothing. It is designed for debugging purposes in client/server configurations.
+
+The ORDA request 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.
+
+For a description of the ORDA request log format, please refer to the [**ORDA client requests**](https://doc.4d.com/4Dv18/4D/18/Description-of-log-files.300-4575486.en.html#4385373) section.
+
+#### Example 1
+
+You want to log ORDA client requests in a file and use the log sequence number:
+
+```4d
+ 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:
+
+```4d
+ 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")
+```
+
+
+
+
+
+
+
+## .startTransaction()
+
+History
+|Version|Changes|
+|---|---|
+|v18|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v18|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+
**.original** : 4D.Folder
+
+
+#### Description
+
+The `.original` property returns the target element for an alias, a shortcut, or a symbolic link file. The target element can be:
+
+* a file object
+* a folder object
+
+For non-alias files, the property returns the same file object as the file.
+
+This property is **read-only**.
+
+
+
+
+
+
+
+## .parent
+
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v19 R2|Returns 4D.Blob
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+
**.getText**( { *charSetNum* : integer } { ; } { *breakMode* : integer} ) : Text
+
+
+
+|Parameter|Type||Description|
+|---|---|---|---|
+|charSetName |Text |-> |Name of character set|
+|charSetNum |Integer |-> |Number of character set|
+|breakMode|Integer |-> |Processing mode for line breaks|
+|Result |Text |<- |Text from the document|
+
+
+
+#### Description
+The `.getText()` function returns the contents of the file as text .
+
+Optionally, you can designate the character set to be used for reading the contents. You can pass either:
+
+- in *charSetName*, a string containing the standard set name (for example "ISO-8859-1" or ""UTF-8"),
+- or in *charSetNum*, the MIBEnum ID (number) of the standard set name.
+
+> For the list of character sets supported by 4D, refer to the description of the `CONVERT FROM TEXT` command.
+
+If the document contains a Byte Order Mark (BOM), 4D uses the character set that it has set instead of the one specified in *charSetName* or *charSetNum* (this parameter is then ignored).
+If the document does not contain a BOM and if *charSetName* or *charSetNum* is omitted, by default 4D uses the "UTF-8" character set.
+
+In *breakMode*, you can pass a number indicating the processing to apply to end-of-line characters in the document. The following constants of the "System Documents" theme are available:
+
+|Constant | Value| Comment|
+|---|---|---|
+|`Document unchanged`|0|No processing|
+|`Document with native format`|1|(Default) Line breaks are converted to the native format of the operating system: CR (carriage return) under OS X, CRLF (carriage return + line feed) under Windows|
+|`Document with CRLF`|2|Line breaks are converted to Windows format: CRLF (carriage return + line feed)|
+|`Document with CR`|3|Line breaks are converted to OS X format: CR (carriage return)|
+|`Document with LF`|4|Line breaks are converted to Unix format: LF (line feed)|
+
+By default, when you omit the *breakMode* parameter, line breaks are processed in native mode (1).
+
+**Returned value**
+
+Text of the file.
+
+#### Example
+
+Given the following text document (fields are separated by tabs):
+
+```4d
+id name price vat
+3 thé 1.06€ 19.6
+2 café 1.05€ 19.6
+```
+
+When you execute this code:
+
+
+```4d
+ $myFile:=Folder(fk documents folder).file("Billing.txt") //UTF-8 by default
+ $txt:=$myFile.getText()
+```
+... you get:
+
+```4d
+ // $Text = "id name price vat\r\n3 thé 1.06€\t19.6\r\n2\tcafé\t1.05€\t19.6"
+ // \t = tab
+ // \r = CR
+```
+
+
+
+
+
+
+
+
diff --git a/docs/API/EmailObjectClass.md b/docs/API/EmailObjectClass.md
new file mode 100644
index 00000000000000..d8de339c65a4b2
--- /dev/null
+++ b/docs/API/EmailObjectClass.md
@@ -0,0 +1,665 @@
+---
+id: EmailObjectClass
+title: Email
+---
+
+Creating, sending or receiving emails in 4D is done by handling an `Email` object.
+
+`Email` objects are created when receiving mails through a *transporter* class function:
+
+- IMAP - [`.getMail()`](IMAPTransporterClass.md#getmail) and [`.getMails()`](IMAPTransporterClass.md#getmails) functions to get emails from an IMAP server
+- POP3 - [`.getMail()`](POP3TransporterClass.md#getmail) function to get an email from a POP3 server.
+
+> You can also create a new, blank `Email` object by calling the [`New object`](https://doc.4d.com/4dv18/help/command/en/page1471.html) 4D command, and then fill it with [Email object properties](#email-object).
+
+You send `Email` objects using the SMTP [`.send()`](SMTPTransporterClass.md#send) function.
+
+[`MAIL Convert from MIME`](#mail-convert-from-mime) and [`MAIL Convert to MIME`](#mail-convert-to-mime) commands can be used to convert `Email` objects to and from MIME contents.
+
+
+### Email Object
+
+Email objects provide the following properties:
+
+> 4D follows the [JMAP specification](https://jmap.io/spec-mail.html) to format the Email object.
+
+||
+|---|
+|[](#attachments) |
+|[](#bcc)
|
+|[](#bodystructure)
|
+|[](#bodyvalues)
|
+|[](#cc)
|
+|[](#comments)
|
+|[](#from)
|
+|[](#headers)
|
+|[](#htmlbody)
|
+|[](#id)
|
+|[](#inreplyto)
|
+|[](#keywords)
|
+|[](#messageid)
|
+|[](#receivedat)
|
+|[](#references)
|
+|[](#replyto)
|
+|[](#sendat)
|
+|[](#sender)
|
+|[](#size)
|
+|[](#subject)
|
+|[](#textbody)
|
+|[](#to)
|
+
+
+### Email Addresses
+
+All properties that contain email addresses ([`from`](#from), [`cc`](#cc), [`bcc`](#bcc), [`to`](#to), [`sender`](#sender), [`replyTo`](#replyto)) accept a value of text, object, or collection type.
+
+#### Text
+
+- single email: "somebody@domain.com"
+- single display name+email: "Somebody "
+- several emails: "Somebody ,me@home.org"
+
+#### Object
+
+An object with two properties:
+
+|Property|Type|Description|
+|---|---|---|
+|name|Text|Display name (can be null)|
+|email|Text|Email address|
+
+#### Collection
+
+A collection of address objects.
+
+### Handling body part
+
+The [`textBody`](#textbody) and [`htmlBody`](#htmlbody) properties are only used with the [SMTP.send()](SMTPTransporterClass.md#send) function to allow sending simple mails. When both property are filled, the MIME content-type multipart/alternative is used. The email client should then recognize the multipart/alternative part and display the text part or html part as necessary.
+
+[`bodyStructure`](#bodystructure) and [`bodyValues`](#bodyvalues) are used for [SMTP](SMTPTransporterClass.md) when the [Email object](email-object) is built from a MIME document, e.g. when generated by the `MAIL Convert from MIME` command. In this case, both `bodyStructure` and `bodyValues` properties must be passed together, and it is not recommended to use `textBody` and `htmlBody`.
+
+#### Example of bodyStructure and bodyValues objects
+
+```json
+"bodyStructure": {
+ "type": "multipart/mixed",
+ "subParts": [
+ {
+ "partId": "p0001",
+ "type": "text/plain"
+ },
+ {
+ "partId": "p0002",
+ "type": "text/html"
+ }
+ ]
+},
+"bodyValues": {
+ "p0001": {
+ "value": "I have the most brilliant plan. Let me tell you all about it."
+ },
+ "p0002": {
+ "value": "I have the most brilliant plan. Let me tell you all about it.
"
+ }
+}
+```
+
+
+
+
+
+
+## .attachments
+
+
+**.attachments** : Collection
+
+
+#### Description
+
+
+
+The `.attachments` property contains a collection of `4D.MailAttachment` object(s).
+
+Attachment objects are defined through the [`MAIL New attachment`](MailAttachmentClass.md#mail-new-attachment) command. Attachment objects have specific [properties and functions](MailAttachmentClass.md).
+
+
+
+
+## .bcc
+
+
+**.bcc** : Text
**.bcc** : Object
**.bcc** : Collection
+
+
+#### Description
+
+The `.bcc` property contains the Blind Carbon Copy (BCC) hidden email recipient [addresse(s)](#email-addresses) of the email.
+
+
+
+
+## .bodyStructure
+
+
+**.bodyStructure** : Object
+
+
+#### Description
+
+The `.bodyStructure` property contains the *EmailBodyPart* object, i.e. the full MIME structure of the message body (optional). See [Handling body part](#handling-body-part) section.
+
+The `.bodyStructure` object contains the following properties:
+
+|Property|Type|Value|
+|---|---|---|
+|partID|Text|Identifies the part uniquely within the email|
+|type|Text|(mandatory) Value of the Content-Type header field of the part|
+|charset|Text|Value of the charset parameter of the Content-Type header field|
+|encoding|Text|If `isEncodingProblem=true`, the Content-Transfer-Encoding value is added (by default undefined)|
+|disposition|Text|Value of the Content-Disposition header field of the part|
+|language|Collection of texts|List of language tags, as defined in [RFC3282](https://tools.ietf.org/html/rfc3282), in the Content-Language header field of the part, if present.|
+|location|Text|URI, as defined in [RFC2557](https://tools.ietf.org/html/rfc2557), in the Content-Location header field of the part, if present.|
+|subParts|Collection of objects|Body parts of each child (collection of *EmailBodyPart* objects)|
+|headers|Collection of objects|List of all header fields in the part, in the order they appear in the message (collection of *EmailHeader* objects, see [headers](#headers-) property)|
+
+
+
+
+## .bodyValues
+
+
+**.bodyValues** : Object
+
+
+#### Description
+
+The `.bodyValues` property contains the *EmailBodyValue* object, containing an object for each \ of `bodyStructure` (optional). See [Handling body part](#handling-body-part) section.
+
+The `.bodyValues` object contains the following properties:
+
+|Property|Type|Value|
+|---|---|---|
+|*partID*.value|text|Value of the body part|
+|*partID*.isEncodingProblem|boolean|True if malformed sections are found while decoding the charset, or unknown charset, or unknown content transfer-encoding. False by default|
+
+
+
+
+## .cc
+
+
+**.cc** : Text
**.cc** : Object
**.cc** : Collection
+
+
+#### Description
+
+The `.cc` property contains the Carbon Copy (CC) additional email recipient [addresse(s)](#email-addresses) of the email.
+
+
+
+
+
+
+## .comments
+
+
+**.comments** : Text
+
+
+#### Description
+
+The `.comments` property contains an additional comments header.
+
+Comments only appear within the header section of the message (keeping the message's body untouched).
+
+For specific formatting requirements, please consult the [RFC#5322](https://tools.ietf.org/html/rfc5322).
+
+
+
+
+## .from
+
+
+**.from** : Text
**.from** : Object
**.from** : Collection
+
+
+#### Description
+
+The `.from` property contains the Originating [address(es)](#email-addresses) of the email.
+
+
+Each email you send out has both the [sender](#sender) and **from** addresses:
+
+- the sender domain is what the receiving email server gets when opening the session,
+- the from address is what the recipient(s) will see.
+
+For better deliverability, it is recommended to use the same from and sender addresses.
+
+
+
+
+## .headers
+
+
+**.headers** : Collection
+
+
+#### Description
+
+The `.headers` property contains a collection of `EmailHeader` objects, in the order they appear in the message. This property allows users to add extended (registered) headers or user-defined (not registered, starting with "X") headers.
+
+> If an `EmailHeader` object property defines a header such as "from" or "cc" which is already set as a property at the mail level, the `EmailHeader` property is ignored.
+
+Every object of the headers collection can contain the following properties:
+
+|Property|Type|Value|
+|---|---|---|
+|[].name|text|(mandatory) Header field name as defined in [RFC#5322](https://tools.ietf.org/html/rfc5322). If null or undefined, the header field is not added to the MIME header.|
+|[].value|text|Header field values as defined in [RFC#5322](https://tools.ietf.org/html/rfc5322)|
+
+
+
+
+
+
+
+## .htmlBody
+
+
+**.htmlBody** : Text
+
+
+#### Description
+
+The `.htmlBody` property contains the HTML representation of the email message (default charset is UTF-8) (optional, SMTP only). See [Handling body part](#handling-body-part) section.
+
+
+
+
+
+
+
+## .id
+
+
+**.id** : Text
+
+
+#### Description
+
+[IMAP transporter](IMAPTransporterClass.md) only.
+
+The `.id` property contains the unique ID from the IMAP server.
+
+
+
+
+
+
+## .inReplyTo
+
+
+**.inReplyTo** : Text
+
+
+#### Description
+
+The `.inReplyTo` property contains the message identifier(s) of the original message(s) to which the current message is a reply.
+
+For specific formatting requirements, please consult the [RFC#5322](https://tools.ietf.org/html/rfc5322).
+
+
+
+
+
+
+## .keywords
+
+
+**.keywords** : Object
+
+
+#### Description
+
+The `.keywords` property contains a set of keywords as an object, where each property name is a keyword and each value is true.
+
+This property is the "keywords" header (see [RFC#4021](https://tools.ietf.org/html/rfc4021)).
+
+|Property|Type|Value|
+|---|---|---|
+|.\|boolean|Keyword to set (value must be true)|
+
+Reserved keywords:
+* $draft - Indicates a message is a draft
+* $seen - Indicates a message has been read
+* $flagged - Indicates a message needs special attention (e.g., Urgent)
+* $answered - Indicates a message has been replied to
+* $deleted - Indicates a message to delete
+
+#### Example
+
+```
+ $mail.keywords["$flagged"]:=True
+ $mail.keywords["4d"]:=True
+```
+
+
+
+
+## .messageId
+
+
+**.messageId** : Text
+
+
+#### Description
+
+The `.messageId` property contains a message identifier header ("message-id").
+
+This header is usually "lettersOrNumbers@domainname", e.g. "abcdef.123456@4d.com". This unique ID is used in particular on forums or public mailing lists. In general, mail servers automatically add this header to the messages they send.
+
+
+
+## .receivedAt
+
+
+**.receivedAt** : Text
+
+
+#### Description
+
+[IMAP transporter](IMAPTransporterClass.md) only.
+
+The `.receivedAt` property contains the timestamp of the email's arrival on the IMAP server in ISO 8601 UTC format (ex: 2020-09-13T16:11:53Z).
+
+
+
+
+
+
+## .references
+
+
+**.references** : Collection
+
+
+#### Description
+
+The `.references` property contains the Collection of all message-ids of messages in the preceding reply chain.
+
+For specific formatting requirements, please consult the [RFC#5322](https://tools.ietf.org/html/rfc5322).
+
+
+
+
+## .replyTo
+
+
+**.replyTo** : Text
**.replyTo** : Object
**.replyTo** : Collection
+
+
+#### Description
+
+The `.replyTo` property contains the [addresse(s)](#email-addresses) for responses.
+
+
+
+
+
+## .sendAt
+
+
+**.sendAt** : Text
+
+
+#### Description
+
+The `.sendAt` property contains the Email timestamp in ISO 8601 UTC format.
+
+
+
+
+## .sender
+
+
+**.sender** : Text
**.sender** : Object
**.sender** : Collection
+
+
+#### Description
+
+The `.sender` property contains the email source [addresse(s)](#email-addresses) of the email.
+
+
+Each email you send out has both the **sender** and **[from](#from)** addresses:
+
+- the sender domain is what the receiving email server gets when opening the session,
+- the from address is what the recipient(s) will see.
+
+For better deliverability, it is recommended to use the same from and sender addresses.
+
+
+
+
+## .size
+
+
+**.size** : Integer
+
+
+#### Description
+
+[IMAP transporter](IMAPTransporterClass.md) only.
+
+The `.size` property contains the size (expressed in bytes) of the Email object returned by the IMAP server.
+
+
+
+
+## .subject
+
+
+**.subject** : Text
+
+
+#### Description
+
+The `.subject` property contains the description of topic.
+
+
+
+
+
+## .textBody
+
+
+**.textBody** : Text
+
+
+#### Description
+
+The `.textBody` property contains the Plain text representation of the email message (default charset is UTF-8) (optional, SMTP only). See [Handling body part](#handling-body-part) section.
+
+
+
+## .to
+
+
+**.to** : Text
**.to** : Object
**.to** : Collection
+
+
+#### Description
+
+The `.to` property contains the primary recipient [addresse(s)](#email-addresses) of the email.
+
+
+## MAIL Convert from MIME
+
+History
+|Version|Changes|
+|---|---|
+|v18|Added|
+
**MAIL Convert from MIME**( *mime* : Text ) : Object
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|mime|Blob, Text|->|Email in MIME|
+|Result|Object|<-|Email object|
+
+
+#### Description
+
+The `MAIL Convert from MIME` command converts a MIME document into a valid email object.
+
+>4D follows the [JMAP specification](https://jmap.io/spec-mail.html) to format the returned email object.
+
+Pass in *mime* a valid MIME document to convert. It can be provided by any mail server or application. You can pass a BLOB or a text *mime* parameter. If the MIME comes from a file, it is recommended to use a BLOB parameter to avoid issues related to charset and line break conversions.
+
+#### Returned object
+
+Email object.
+
+#### Example 1
+
+You want to load a mail template saved as MIME in a text document and send an email:
+
+```4d
+C_BLOB($mime)
+C_OBJECT($mail;$server;$transporter;$status)
+
+$mime:=File("/PACKAGE/Mails/templateMail.txt").getContent())
+
+$mail:=[#current_title_incode]($mime)
+$mail.to:="smith@mail.com"
+$mail.subject:="Hello world"
+
+$server:=New object
+$server.host:="smtp.gmail.com"
+$server.port:=465
+$server.user:="test@gmail.com"
+$server.password:="XXXX"
+
+$transporter:=SMTP New transporter($server)
+$status:=$transporter.send($mail)
+```
+
+#### Example 2
+
+In this example, you send directly a 4D Write Pro document containing pictures:
+
+```4d
+C_TEXT($mime)
+C_OBJECT($email;$server;$transporter;$status)
+
+// Mime export of the 4D Write Pro document
+WP EXPORT VARIABLE(WParea;$mime;wk mime html)
+
+// convert 4D Write Pro Mime variable in mail object
+$email:=MAIL Convert from MIME($mime)
+
+// Fill your mail object headers
+$email.subject:="4D Write Pro HTML body"
+$email.from:="YourEmail@gmail.com"
+$email.to:="RecipientEmail@mail.com"
+
+$server:=New object
+$server.host:="smtp.gmail.com"
+$server.port:=465
+$server.user:="YourEmail@gmail.com"
+$server.password:="XXXX"
+
+$transporter:=SMTP New transporter($server)
+$status:=$transporter.send($email)
+```
+
+
+
+
+
+## MAIL Convert to MIME
+
+History
+|Version|Changes|
+|---|---|
+|v17 R4|Added|
+|v17 R5|Modified|
+| Constant | Value | Comment |
|---|
| mail mode ISO2022JP | US-ASCII_ISO-2022-JP_UTF8_QP | - headerCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & Quoted-printable if possible, otherwise UTF-8 & Quoted-printable
- bodyCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & 7-bit if possible, otherwise UTF-8 & Quoted-printable
|
| mail mode ISO88591 | ISO-8859-1 | - headerCharset: ISO-8859-1 & Quoted-printable
- bodyCharset: ISO-8859-1 & 8-bit
|
| mail mode UTF8 | US-ASCII_UTF8_QP | headerCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & Quoted-printable (**default value**) |
| mail mode UTF8 in base64 | US-ASCII_UTF8_B64 | headerCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & base64 |
|
+|bodyCharset| Text| Charset and encoding used for the html and text body contents of the email. Possible values: Same as for headerCharset (see above)|
+
+If the *options* parameter is omitted, the mail mode UTF8 configuration is used for header and body parts.
+
+
+#### Example
+
+```4d
+C_OBJECT($mail)
+C_TEXT($mime)
+$mail:=New object
+
+// Creation of a mail
+$mail.from:="tsales@massmarket.com"
+$mail.subject:="Terrific Sale! This week only!"
+$mail.textBody:="Text format email"
+$mail.htmlBody:="HTML format email"
+$mail.to:=New collection
+$mail.to.push(New object ("email";"noreply@4d.com"))
+$mail.to.push(New object ("email";"test@4d.com"))
+
+// transform the mail object in MIME
+$mime:=[#current_title_incode]($mail)
+
+// Contents of $mime:
+// MIME-Version: 1.0
+// Date: Thu, 11 Oct 2018 15:42:25 GMT
+// Message-ID: <7CA5D25B2B5E0047A36F2E8CB30362E2>
+// Sender: tsales@massmarket.com
+// From: tsales@massmarket.com
+// To: noreply@4d.com
+// To: test@4d.com
+// Content-Type: multipart/alternative; boundary="E0AE5773D5E95245BBBD80DD0687E218"
+// Subject: Terrific Sale! This week only!
+//
+// --E0AE5773D5E95245BBBD80DD0687E218
+// Content-Type: text/plain; charset="UTF-8"
+// Content-Transfer-Encoding: quoted-printable
+//
+// Text format email
+// --E0AE5773D5E95245BBBD80DD0687E218
+// Content-Type: text/html; charset="UTF-8"
+// Content-Transfer-Encoding: quoted-printable
+//
+// HTML format email
+// --E0AE5773D5E95245BBBD80DD0687E218--
+```
+
+
+
diff --git a/docs/API/EntityClass.md b/docs/API/EntityClass.md
new file mode 100644
index 00000000000000..5553bb4f7630f5
--- /dev/null
+++ b/docs/API/EntityClass.md
@@ -0,0 +1,1757 @@
+---
+id: EntityClass
+title: Entity
+---
+
+An [entity](ORDA/dsMapping.md#entity) is an instance of a [Dataclass](ORDA/dsMapping.md#dataclass), like a record of the table matching the dataclass in its associated datastore. It contains the same attributes as the dataclass as well as the data values and specific properties and functions.
+
+
+### Summary
+
+||
+|---|
+|[](#attributename) |
+|[](#clone)
|
+|[](#diff)
|
+|[](#drop)
|
+|[](#first)
|
+|[](#fromobject)
|
+|[](#getdataclass)
|
+|[](#getkey)
|
+|[](#getselection)
|
+|[](#getstamp)
|
+|[](#indexof)
|
+|[](#isnew)
|
+|[](#last)
|
+|[](#lock)
|
+|[](#next)
|
+|[](#previous)
|
+|[](#reload)
|
+|[](#save)
|
+|[](#toobject)
|
+|[](#touched)
|
+|[](#touchedattributes)
|
+|[](#unlock)
|
+
+
+
+
+
+
+
+## .*attributeName*
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+
the entity has been dropped (the stamp has changed and the memory space is now free)the entity has been dropped and replaced by another one with another primary key (the stamp has changed and a new entity now uses the memory space). When using entity.drop( ), this error can be returned when dk force drop if stamp changed option is used. When using entity.lock( ), this error can be returned when dk reload if stamp changed option is used**Associated statusText**: "Entity does not exist anymore"|
+|`dk status locked`|3|The entity is locked by a pessimistic lock.
**Associated statusText**: "Already locked"|
+|`dk status serious error`| 4| A serious error is a low-level database error (e.g. duplicated key), a hardware error, etc.
**Associated statusText**: "Other error"
+|`dk status stamp has changed`| 2|The internal stamp value of the entity does not match the one of the entity stored in the data (optimistic lock).
with `.save( )`: error only if the `dk auto merge` option is not usedwith `.drop( )`: error only if the `dk force drop if stamp changed` option is not usedwith `.lock( )`: error only if the `dk reload if stamp changed` option is not used**Associated statusText**: "Stamp has changed"|
+
+
+#### Example 1
+
+Example without `dk force drop if stamp changed` option:
+
+```4d
+ var $employees : cs.EmployeeSelection
+ var $employee : cs.EmployeeEntity
+ var $status : Object
+ $employees:=ds.Employee.query("lastName=:1";"Smith")
+ $employee:=$employees.first()
+ $status:=$employee.drop()
+ Case of
+ :($status.success)
+ ALERT("You have dropped "+$employee.firstName+" "+$employee.lastName) //The dropped entity remains in memory
+ :($status.status=dk status stamp has changed)
+ ALERT($status.statusText)
+ End case
+```
+
+#### Example 2
+
+Example with `dk force drop if stamp changed` option:
+
+```4d
+ var $employees : cs.EmployeeSelection
+ var $employee : cs.EmployeeEntity
+ var $status : Object
+ $employees:=ds.Employee.query("lastName=:1";"Smith")
+ $employee:=$employees.first()
+ $status:=$employee.drop(dk force drop if stamp changed)
+ Case of
+ :($status.success)
+ ALERT("You have dropped "+$employee.firstName+" "+$employee.lastName) //The dropped entity remains in memory
+ :($status.status=dk status entity does not exist anymore)
+ ALERT($status.statusText)
+ End case
+```
+
+
+
+
+
+
+
+## .first()
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+
**.getKey**( { *mode* : Integer } ) : Integer
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|mode|Integer|->|`dk key as string`: primary key is returned as a string, no matter the primary key type|
+|Result|Text|<-|Value of the text primary key of the entity|
+|Result|Integer|<-|Value of the numeric primary key of the entity|
+
+
+
+#### Description
+
+The `.getKey()` function returns the primary key value of the entity.
+
+Primary keys can be numbers (Integer) or strings. You can "force" the returned primary key value to be a string, no matter the actual primary key type, by passing the `dk key as string` option in the *mode* parameter.
+
+#### Example
+
+
+```4d
+ var $employees : cs.EmployeeSelection
+ var $employee : cs.EmployeeEntity
+ $employees:=ds.Employee.query("lastName=:1";"Smith")
+ $employee:=$employees[0]
+ ALERT("The primary key is "+$employee.getKey(dk key as string))
+```
+
+
+
+
+
+
+
+## .getSelection()
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+
**Associated statusText**: "Entity does not exist anymore"|
+|`dk status locked`| 3 |The entity is locked by a pessimistic lock.**Associated statusText**: "Already locked"
+|`dk status serious error`| 4 |A serious error is a low-level database error (e.g. duplicated key), a hardware error, etc.
**Associated statusText**: "Other error"|
+|`dk status stamp has changed`|2|The internal stamp value of the entity does not match the one of the entity stored in the data (optimistic lock).
with `.save( )`: error only if the `dk auto merge` option is not usedwith `.drop( )`: error only if the `dk force drop if stamp changed` option is not usedwith `.lock( )`: error only if the `dk reload if stamp changed` option is not used
**Associated statusText**: "Stamp has changed"|
+
+
+#### Example 1
+
+Example with error:
+
+```4d
+ var $employee : cs.EmployeeEntity
+ var $status : Object
+ $employee:=ds.Employee.get(716)
+ $status:=$employee.lock()
+ Case of
+ :($status.success)
+ ALERT("You have locked "+$employee.firstName+" "+$employee.lastName)
+ :($status.status=dk status stamp has changed)
+ ALERT($status.statusText)
+ End case
+```
+
+
+#### Example 2
+
+Example with `dk reload if stamp changed` option:
+
+```4d
+ var $employee : cs.EmployeeEntity
+ var $status : Object
+ $employee:=ds.Employee.get(717)
+ $status:=$employee.lock(dk reload if stamp changed)
+ Case of
+ :($status.success)
+ ALERT("You have locked "+$employee.firstName+" "+$employee.lastName)
+ :($status.status=dk status entity does not exist anymore)
+ ALERT($status.statusText)
+ End case
+```
+
+
+
+
+
+
+## .next()
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+***Available only in case of error***:|
+|status(\*)|number|Error code, see below|
+|statusText(\*)|text|Description of the error, see below|
+
+(\*) The following values can be returned in the *status* and *statusText* properties of *Result* object in case of error:
+
+|Constant| Value| Comment|
+|---|---|---|
+|`dk status entity does not exist anymore`|5|The entity no longer exists in the data. This error can occur in the following cases:
the entity has been dropped (the stamp has changed and the memory space is now free)the entity has been dropped and replaced by another one with another primary key (the stamp has changed and a new entity now uses the memory space). When using `.drop( )`, this error can be returned when `dk force drop if stamp changed` option is used. When using `.lock( )`, this error can be returned when `dk reload if stamp changed` option is used
***Associated statusText***: "Entity does not exist anymore"|
+|`dk status serious error`|4| A serious error is a low-level database error (e.g. duplicated key), a hardware error, etc.
***Associated statusText***: "Other error"|
+
+
+#### Example
+
+```4d
+ var $employee : cs.EmployeeEntity
+ var $employees : cs.EmployeeSelection
+ var $result : Object
+
+ $employees:=ds.Employee.query("lastName=:1";"Hollis")
+ $employee:=$employees[0]
+ $employee.firstName:="Mary"
+ $result:=$employee.reload()
+ Case of
+ :($result.success)
+ ALERT("Reload has been done")
+ :($result.status=dk status entity does not exist anymore)
+ ALERT("The entity has been dropped")
+ End case
+```
+
+
+
+
+
+## .save()
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+**Associated statusText**: "Auto merge failed"|
+|`dk status entity does not exist anymore`| 5| The entity no longer exists in the data. This error can occur in the following cases:
the entity has been dropped (the stamp has changed and the memory space is now free)the entity has been dropped and replaced by another one with another primary key (the stamp has changed and a new entity now uses the memory space). When using `.drop( )`, this error can be returned when `dk force drop if stamp changed` option is used. When using `.lock( )`, this error can be returned when `dk reload if stamp changed` option is used
**Associated statusText**: "Entity doesnot exist anymore"|
+|`dk status locked`| 3| The entity is locked by a pessimistic lock.**Associated statusText**: "Already locked"
+|`dk status serious error`|4|A serious error is a low-level database error (e.g. duplicated key), a hardware error, etc.
**Associated statusText**: "Other error"|
+|`dk status stamp has changed`|2|The internal stamp value of the entity does not match the one of the entity stored in the data (optimistic lock).
with `.save( )`: error only if the `dk auto merge` option is not usedwith `.drop( )`: error only if the `dk force drop if stamp changed` option is not usedwith `.lock( )`: error only if the `dk reload if stamp changed` option is not used
**Associated statusText**: "Stamp has changed"
+
+
+#### Example 1
+
+Creating a new entity:
+
+```4d
+ var $status : Object
+ var $employee : cs.EmployeeEntity
+ $employee:=ds.Employee.new()
+ $employee.firstName:="Mary"
+ $employee.lastName:="Smith"
+ $status:=$employee.save()
+ If($status.success)
+ ALERT("Employee created")
+ End if
+```
+
+#### Example 2
+
+Updating an entity without `dk auto merge` option:
+
+```4d
+ var $status : Object
+ var $employee : cs.EmployeeEntity
+ var $employees : cs.EmployeeSelection
+ $employees:=ds.Employee.query("lastName=:1";"Smith")
+ $employee:=$employees.first()
+ $employee.lastName:="Mac Arthur"
+ $status:=$employee.save()
+ Case of
+ :($status.success)
+ ALERT("Employee updated")
+ :($status.status=dk status stamp has changed)
+ ALERT($status.statusText)
+ End case
+```
+
+#### Example 3
+
+Updating an entity with `dk auto merge` option:
+
+```4d
+ var $status : Object
+
+ var $employee : cs.EmployeeEntity
+ var $employees : cs.EmployeeSelection
+
+ $employees:=ds.Employee.query("lastName=:1";"Smith")
+ $employee:=$employees.first()
+ $employee.lastName:="Mac Arthur"
+ $status:=$employee.save(dk auto merge)
+ Case of
+ :($status.success)
+ ALERT("Employee updated")
+ :($status.status=dk status automerge failed)
+ ALERT($status.statusText)
+ End case
+```
+
+
+
+
+
+
+## .toObject()
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+
**.toObject**( *filterString* : Text { ; *options* : Integer} ) : Object
**.toObject**( *filterCol* : Collection { ; *options* : Integer } ) : Object
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|filterString |Text |->|Attribute(s) to extract (comma-separated string)|
+|filterCol |Collection |->|Collection of attribute(s) to extract|
+|options|Integer|->|`dk with primary key`: adds the \_KEY property;
`dk with stamp`: adds the \_STAMP property|
+|Result|Object|<-|Object built from the entity|
+
+
+#### Description
+
+The `.toObject()` function returns an object which has been built from the entity. Property names in the object match attribute names of the entity.
+
+If no filter is specified, or if the *filterString* parameter contains an empty string or "*", the returned object will contain:
+
+* all storage entity attributes
+* attributes of the `relatedEntity` [kind](DataClassAttributeClass.md#kind): you get a property with the same name as the related entity (name of the many-to-one link). Attribute is extracted with the simple form.
+* attributes of the `relatedEntities` [kind](DataClassAttributeClass.md#kind): attribute is not returned.
+
+
+In the first parameter, you pass the entity attribute(s) to extract. You can pass:
+
+* *filterString*: a string with property paths separated with commas: "propertyPath1, propertyPath2, ...", or
+* *filterCol*: a collection of strings: \["propertyPath1","propertyPath2";...]
+
+If a filter is specified for attributes of the relatedEntity [kind](DataClassAttributeClass.md#kind):
+
+* propertyPath = "relatedEntity" -> it is extracted with simple form: an object with property \_\_KEY (primary key).
+* propertyPath = "relatedEntity.*" -> all the properties are extracted
+* propertyPath = "relatedEntity.propertyName1; relatedEntity.propertyName2; ..." -> only those properties are extracted
+
+If a filter is specified for attributes of the relatedEntities [kind](DataClassAttributeClass.md#kind):
+
+* propertyPath = "relatedEntities.*" -> all the properties are extracted
+* propertyPath = "relatedEntities.propertyName1; relatedEntities.propertyName2; ..." -> only those properties are extracted
+
+In the *options* parameter, you can pass the `dk with primary key` and/or` dk with stamp` selector(s) to add the entity's primary keys and/or stamps in extracted objects.
+
+
+#### Example 1
+
+The following structure will be used throughout all examples of this section:
+
+
+
+
+Without filter parameter:
+
+```4d
+employeeObject:=employeeSelected.toObject()
+```
+
+Returns:
+
+```4d
+{
+ "ID": 413,
+ "firstName": "Greg",
+ "lastName": "Wahl",
+ "salary": 0,
+ "birthDate": "1963-02-01T00:00:00.000Z",
+ "woman": false,
+ "managerID": 412,
+ "employerID": 20,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": { // relatedEntity extracted with simple form
+ "__KEY": 20
+ },
+ "manager": {
+ "__KEY": 412
+ }
+}
+```
+
+
+
+#### Example 2
+
+Extracting the primary key and the stamp:
+
+```4d
+employeeObject:=employeeSelected.toObject("";dk with primary key+dk with stamp)
+```
+
+Returns:
+
+```4d
+{
+ "__KEY": 413,
+ "__STAMP": 1,
+ "ID": 413,
+ "firstName": "Greg",
+ "lastName": "Wahl",
+ "salary": 0,
+ "birthDate": "1963-02-01T00:00:00.000Z",
+ "woman": false,
+ "managerID": 412,
+ "employerID": 20,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 20
+ },
+ "manager": {
+ "__KEY": 412
+ }
+}
+```
+
+#### Example 3
+
+Expanding all the properties of `relatedEntities`:
+
+```4d
+employeeObject:=employeeSelected.toObject("directReports.*")
+```
+
+```4d
+{
+ "directReports": [
+ {
+ "ID": 418,
+ "firstName": "Lorena",
+ "lastName": "Boothe",
+ "salary": 44800,
+ "birthDate": "1970-10-02T00:00:00.000Z",
+ "woman": true,
+ "managerID": 413,
+ "employerID": 20,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 20
+ },
+ "manager": {
+ "__KEY": 413
+ }
+ },
+ {
+ "ID": 419,
+ "firstName": "Drew",
+ "lastName": "Caudill",
+ "salary": 41000,
+ "birthDate": "2030-01-12T00:00:00.000Z",
+ "woman": false,
+ "managerID": 413,
+ "employerID": 20,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 20
+ },
+ "manager": {
+ "__KEY": 413
+ }
+ },
+ {
+ "ID": 420,
+ "firstName": "Nathan",
+ "lastName": "Gomes",
+ "salary": 46300,
+ "birthDate": "2010-05-29T00:00:00.000Z",
+ "woman": false,
+ "managerID": 413,
+ "employerID": 20,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 20
+ },
+ "manager": {
+ "__KEY": 413
+ }
+ }
+ ]
+}
+```
+
+#### Example 4
+
+Extracting some properties of `relatedEntities`:
+
+```4d
+ employeeObject:=employeeSelected.toObject("firstName, directReports.lastName")
+```
+
+Returns:
+
+```4d
+{
+ "firstName": "Greg",
+ "directReports": [
+ {
+ "lastName": "Boothe"
+ },
+ {
+ "lastName": "Caudill"
+ },
+ {
+ "lastName": "Gomes"
+ }
+ ]
+}
+```
+
+#### Example 5
+
+Extracting a `relatedEntity` with simple form:
+
+```4d
+ $coll:=New collection("firstName";"employer")
+ employeeObject:=employeeSelected.toObject($coll)
+```
+
+Returns:
+
+```4d
+{
+ "firstName": "Greg",
+ "employer": {
+ "__KEY": 20
+ }
+}
+```
+
+#### Example 6
+
+Extracting all the properties of a `relatedEntity`:
+
+```4d
+ employeeObject:=employeeSelected.toObject("employer.*")
+```
+
+Returns:
+
+```4d
+{
+ "employer": {
+ "ID": 20,
+ "name": "India Astral Secretary",
+ "creationDate": "1984-08-25T00:00:00.000Z",
+ "revenues": 12000000,
+ "extra": null
+ }
+}
+```
+
+#### Example 7
+
+Extracting some properties of a `relatedEntity`:
+
+```4d
+ $col:=New collection
+ $col.push("employer.name")
+ $col.push("employer.revenues")
+ employeeObject:=employeeSelected.toObject($col)
+```
+
+Returns:
+
+```4d
+{
+ "employer": {
+ "name": "India Astral Secretary",
+ "revenues": 12000000
+ }
+}
+```
+
+
+
+
+
+
+## .touched( )
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+ |
+|[](#attributename)
|
+|[](#add)
|
+|[](#and)
|
+|[](#average)
|
+|[](#contains)
|
+|[](#count)
|
+|[](#distinct)
|
+|[](#drop)
|
+|[](#extract)
|
+|[](#first)
|
+|[](#getdataclass)
|
+|[](#isalterable)
|
+|[](#isordered)
|
+|[](#last)
|
+|[](#length)
|
+|[](#max)
|
+|[](#min)
|
+|[](#minus)
|
+|[](#or)
|
+|[](#orderby)
|
+|[](#orderbyformula)
|
+|[](#query)
|
+|[](#querypath)
|
+|[](#queryplan)
|
+|[](#refresh)
|
+|[](#selected)
|
+|[](#slice)
|
+|[](#sum)
|
+|[](#tocollection)
|
+
+
+
+## Create entity selection
+
+
+**Create entity selection** ( *dsTable* : Table { ; *settings* : Object } ) : 4D.EntitySelection
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|dsTable|Table|->|Table in the 4D database whose current selection will be used to build the entity selection|
+|settings|Object|->|Build option: context |
+|Result|4D.EntitySelection|<-|Entity selection matching the dataclass related to the given table|
+
+
+
+#### Description
+
+The `Create entity selection` command builds and returns a new, [alterable](ORDA/entities.md#shareable-or-alterable-entity-selections) entity selection related to the dataclass matching the given *dsTable*, according to the current selection of this table.
+
+If the current selection is sorted, an [ordered](ORDA/dsMapping.md#ordered-or-unordered-entity-selection) entity selection is created (the order of the current selection is kept). If the current selection is unsorted, an unordered entity selection is created.
+
+If the *dsTable* is not exposed in [`ds`](API/DataStoreClass.md#ds), an error is returned. This command cannot be used with a Remote datastore.
+
+In the optional *settings* parameter, you can pass an object containing the following property:
+
+|Property|Type|Description|
+|---|---|---|
+|context|Text|Label for the [optimization context](ORDA/entities.md#clientserver-optimization) applied to the entity selection.|
+
+
+#### Example
+
+```4d
+var $employees : cs.EmployeeSelection
+ALL RECORDS([Employee])
+$employees:=Create entity selection([Employee])
+// The $employees entity selection now contains a set of reference
+// on all entities related to the Employee dataclass
+```
+
+#### See also
+
+[`dataClass.newSelection()`](DataClassClass.md#newselection)
+
+
+## [*index*]
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
***.attributeName*** : 4D.EntitySelection
+
+
+#### Description
+
+Any dataclass attribute can be used as a property of an entity selection to return a "projection" of values for the attribute in the entity selection. Projected values can be a collection or a new entity selection, depending on the [kind](DataClassAttributeClass.md#kind) (`storage` or `relation`) of the attribute.
+
+* If *attributeName* kind is `storage`:
+`.attributeName` returns a collection of values of the same type as *attributeName*.
+* If *attributeName* kind is `relatedEntity`:
+`.attributeName` returns a new entity selection of related values of the same type as *attributeName*. Duplications are removed (an unordered entity selection is returned).
+* If *attributeName* kind is `relatedEntities`:
+`.attributeName` returns a new entity selection of related values of the same type as *attributeName*. Duplications are removed (an unordered entity selection is returned).
+
+
+When a relation attribute is used as a property of an entity selection, the result is always another entity selection, even if only one entity is returned. In this case, if no entities are returned, the result is an empty entity selection.
+
+If the attribute does not exist in the entity selection, an error is returned.
+
+
+
+
+
+
+#### Example 1
+
+Projection of storage values:
+
+
+
+
+```4d
+ var $firstNames : Collection
+ $entitySelection:=ds.Employee.all()
+ $firstNames:=$entitySelection.firstName // firstName type is string
+```
+
+The resulting collection is a collection of strings, for example:
+
+```4d
+[
+ "Joanna",
+ "Alexandra",
+ "Rick"
+]
+```
+
+#### Example 2
+
+Projection of related entity:
+
+```4d
+ var $es; $entitySelection : cs.EmployeeSelection
+ $entitySelection:=ds.Employee.all()
+ $es:=$entitySelection.employer // employer is related to a Company dataClass
+```
+
+The resulting object is an entity selection of Company with duplications removed (if any).
+
+#### Example 3
+
+Projection of related entities:
+
+```4d
+ var $es : cs.EmployeeSelection
+ $es:=ds.Employee.all().directReports // directReports is related to Employee dataclass
+```
+
+The resulting object is an entity selection of Employee with duplications removed (if any).
+
+
+
+
+
+
+
+## .add()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R5|Only supports alterable entity selections|
+|v17|Added|
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
**.and**( *entitySelection* : 4D.EntitySelection ) : 4D.EntitySelection
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|entity |4D.Entity|->|Entity to intersect with|
+|entitySelection |4D.EntitySelection|->|Entity selection to intersect with|
+|Result|4D.EntitySelection|<-|New entity selection with the result of intersection with logical AND operator|
+
+
+
+#### Description
+
+The `.and()` function combines the entity selection with an *entity* or *entitySelection* parameter using the logical AND operator; it returns a new, unordered entity selection that contains only the entities that are referenced in both the entity selection and the parameter.
+
+* If you pass *entity* as parameter, you combine this entity with the entity selection. If the entity belongs to the entity selection, a new entity selection containing only the entity is returned. Otherwise, an empty entity selection is returned.
+* If you pass *entitySelection* as parameter, you combine both entity selections. A new entity selection that contains only the entities that are referenced in both selections is returned. If there is no intersecting entity, an empty entity selection is returned.
+
+>You can compare [ordered and/or unordered entity selections](ORDA/dsMapping.md#ordered-or-unordered-entity-selection). The resulting selection is always unordered.
+
+If the original entity selection or the *entitySelection* parameter is empty, or if the *entity* is Null, an empty entity selection is returned.
+
+If the original entity selection and the parameter are not related to the same dataclass, an error is raised.
+
+
+#### Example 1
+
+
+```4d
+ var $employees; $result : cs.EmployeeSelection
+ var $employee : cs.EmployeeEntity
+ $employees:=ds.Employee.query("lastName = :1";"H@")
+ //The $employees entity selection contains the entity
+ //with primary key 710 and other entities
+ //for ex. "Colin Hetrick" / "Grady Harness" / "Sherlock Holmes" (primary key 710)
+ $employee:=ds.Employee.get(710) // Returns "Sherlock Holmes"
+
+ $result:=$employees.and($employee) //$result is an entity selection containing
+ //only the entity with primary key 710 ("Sherlock Holmes")
+```
+
+
+#### Example 2
+
+We want to have a selection of employees named "Jones" who live in New York:
+
+```4d
+ var $sel1; $sel2; $sel3 : cs.EmployeeSelection
+ $sel1:=ds.Employee.query("name =:1";"Jones")
+ $sel2:=ds.Employee.query("city=:1";"New York")
+ $sel3:=$sel1.and($sel2)
+```
+
+
+
+
+
+## .average()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R6|Returns undefined if empty entity selection|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v18 R5|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v18 R3|Added|
+
+
**.extract**( *attributePath* { ; *targetPath* } { ; *...attributePathN* : Text ; *targetPathN* : Text } ) : Collection
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|attributePath |Text|->|Attribute path whose values must be extracted to the new collection |
+|targetPath|Text|->|Target attribute path or attribute name|
+|option|Integer|->|`ck keep null`: include null attributes in the returned collection (ignored by default)|
+|Result|Collection|<-|Collection containing extracted values|
+
+
+#### Description
+
+The `.extract()` function returns a collection containing *attributePath* values extracted from the entity selection.
+
+*attributePath* can refer to:
+
+* a scalar dataclass attribute,
+* related entity,
+* related entities.
+
+If *attributePath* is invalid, an empty collection is returned.
+
+This function accepts two syntaxes.
+
+**.extract( attributePath : Text { ; option : Integer } ) : Collection**
+
+With this syntax, `.extract()` populates the returned collection with the *attributePath* values of the entity selection.
+
+By default, entities for which *attributePath* is *null* or undefined are ignored in the resulting collection. You can pass the `ck keep null` constant in the *option* parameter to include these values as **null** elements in the returned collection.
+
+* Dataclass attributes with [.kind](DataClassAttributeClass.md#kind) = "relatedEntity" are extracted as a collection of entities (duplications are kept).
+* Dataclass attributes with [.kind](DataClassAttributeClass.md#kind) = "relatedEntities" are extracted as a collection of entity selections.
+
+
+**.extract ( attributePath ; targetPath { ; ...attributePathN ; ... targetPathN}) : Collection**
+
+With this syntax, `.extract()` populates the returned collection with the *attributePath* properties. Each element of the returned collection is an object with *targetPath* properties filled with the corresponding *attributePath* properties. Null values are kept (*option* parameter is ignored with this syntax).
+
+If several *attributePath* are given, a *targetPath* must be given for each. Only valid pairs \[*attributePath*, *targetPath*] are extracted.
+
+* Dataclass attributes with [.kind](DataClassAttributeClass.md#kind) = "relatedEntity" are extracted as an entity.
+* Dataclass attributes with [.kind](DataClassAttributeClass.md#kind) = "relatedEntities" are extracted as an entity selection.
+
+> Entities of a collection of entities accessed by \[ ] are not reloaded from the database.
+
+
+#### Example
+
+Given the following table and relation:
+
+
+
+```4d
+ var $firstnames; $addresses; $mailing; $teachers : Collection
+ //
+ //
+ //$firstnames is a collection of Strings
+
+
+ $firstnames:=ds.Teachers.all().extract("firstname")
+ //
+ //$addresses is a collection of entities related to dataclass Address
+ //Null values for address are extracted
+ $addresses:=ds.Teachers.all().extract("address";ck keep null)
+ //
+ //
+ //$mailing is a collection of objects with properties "who" and "to"
+ //"who" property content is String type
+ //"to" property content is entity type (Address dataclass)
+ $mailing:=ds.Teachers.all().extract("lastname";"who";"address";"to")
+ //
+ //
+ //$mailing is a collection of objects with properties "who" and "city"
+ //"who" property content is String type
+ //"city" property content is String type
+ $mailing:=ds.Teachers.all().extract("lastname";"who";"address.city";"city")
+ //
+ //$teachers is a collection of objects with properties "where" and "who"
+ //"where" property content is String
+ //"who" property content is an entity selection (Teachers dataclass)
+ $teachers:=ds.Address.all().extract("city";"where";"teachers";"who")
+ //
+ //$teachers is a collection of entity selections
+ $teachers:=ds.Address.all().extract("teachers")
+```
+
+
+
+
+
+
+## .first()
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+
+History
+
+|Version|Changes|
+|---|---|
+|v18 R5|Added|
+
+History
+
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+|v18 R6|Returns undefined if empty entity selection|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+|v18 R6|Returns undefined if empty entity selection|
+
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+
**.minus**( *entitySelection* : 4D.EntitySelection ) : 4D.EntitySelection
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|entity |4D.Entity|->|Entity to substract|
+|entitySelection|4D.EntitySelection|->|Entity selection to substract|
+|Result|4D.EntitySelection|<-|New entity selection or a new reference on the existing entity selection|
+
+
+#### Description
+
+The `.minus()` function excludes from the entity selection to which it is applied the *entity* or the entities of *entitySelection* and returns the resulting entity selection.
+
+* If you pass *entity* as parameter, the function creates a new entity selection without *entity* (if *entity* belongs to the entity selection). If *entity* was not included in the original entity selection, a new reference to the entity selection is returned.
+* If you pass *entitySelection* as parameter, the function returns an entity selection containing the entities belonging to the original entity selection without the entities belonging to *entitySelection*.
+
+>You can compare [ordered and/or unordered entity selections](ORDA/dsMapping.md#ordered-or-unordered-entity-selection). The resulting selection is always unordered.
+
+If the original entity selection or both the original entity selection and the *entitySelection* parameter are empty, an empty entity selection is returned.
+
+If *entitySelection* is empty or if *entity* is Null, a new reference to the original entity selection is returned.
+
+If the original entity selection and the parameter are not related to the same dataclass, an error is raised.
+
+
+#### Example 1
+
+```4d
+ var $employees; $result : cs.EmployeeSelection
+ var $employee : cs.EmployeeEntity
+
+ $employees:=ds.Employee.query("lastName = :1";"H@")
+ // The $employees entity selection contains the entity with primary key 710 and other entities
+ // for ex. "Colin Hetrick", "Grady Harness", "Sherlock Holmes" (primary key 710)
+
+ $employee:=ds.Employee.get(710) // Returns "Sherlock Holmes"
+
+ $result:=$employees.minus($employee) //$result contains "Colin Hetrick", "Grady Harness"
+```
+
+
+#### Example 2
+
+We want to have a selection of female employees named "Jones" who live in New York :
+
+```4d
+ var $sel1; $sel2; $sel3 : cs.EmployeeSelection
+ $sel1:=ds.Employee.query("name =:1";"Jones")
+ $sel2:=ds.Employee.query("city=:1";"New York")
+ $sel3:=$sel1.and($sel2).minus(ds.Employee.query("gender='male'"))
+```
+
+
+
+
+
+## .or()
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+
**.or**( *entitySelection* : 4D.EntitySelection ) : 4D.EntitySelection
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|entity|4D.Entity|->|Entity to intersect with|
+|entitySelection|4D.EntitySelection|->|Entity selection to intersect with|
+|Result|4D.EntitySelection|<-|New entity selection or new reference to the original entity selection|
+
+
+#### Description
+
+The `.or()` function combines the entity selection with the *entity* or *entitySelection* parameter using the logical (not exclusive) OR operator; it returns a new, unordered entity selection that contains all the entities from the entity selection and the parameter.
+
+* If you pass *entity* as parameter, you compare this entity with the entity selection. If the entity belongs to the entity selection, a new reference to the entity selection is returned. Otherwise, a new entity selection containing the original entity selection and the entity is returned.
+* If you pass *entitySelection* as parameter, you compare entity selections. A new entity selection containing the entities belonging to the original entity selection or *entitySelection* is returned (or is not exclusive, entities referenced in both selections are not duplicated in the resulting selection).
+
+>You can compare [ordered and/or unordered entity selections](ORDA/dsMapping.md#ordered-or-unordered-entity-selection). The resulting selection is always unordered.
+
+If the original entity selection and the *entitySelection* parameter are empty, an empty entity selection is returned. If the original entity selection is empty, a reference to *entitySelection* or an entity selection containing only *entity* is returned.
+
+If *entitySelection* is empty or if *entity* is Null, a new reference to the original entity selection is returned.
+
+If the original entity selection and the parameter are not related to the same dataclass, an error is raised.
+
+
+#### Example 1
+
+```4d
+ var $employees1; $employees2; $result : cs.EmployeeSelection
+ $employees1:=ds.Employee.query("lastName = :1";"H@") //Returns "Colin Hetrick","Grady Harness"
+ $employees2:=ds.Employee.query("firstName = :1";"C@") //Returns "Colin Hetrick", "Cath Kidston"
+ $result:=$employees1.or($employees2) //$result contains "Colin Hetrick", "Grady Harness","Cath Kidston"
+```
+
+#### Example 2
+
+```4d
+ var $employees; $result : cs.EmployeeSelection
+ var $employee : cs.EmployeeEntity
+ $employees:=ds.Employee.query("lastName = :1";"H@") // Returns "Colin Hetrick","Grady Harness", "Sherlock Holmes"
+ $employee:=ds.Employee.get(686) //the entity with primary key 686 does not belong to the $employees entity selection
+ //It matches the employee "Mary Smith"
+
+ $result:=$employees.or($employee) //$result contains "Colin Hetrick", "Grady Harness", "Sherlock Holmes", "Mary Smith"
+```
+
+
+
+
+
+## .orderBy()
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+
**.orderBy**( *pathObjects* : Collection ) : 4D.EntitySelection
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|pathString |Text |->|Attribute path(s) and sorting instruction(s) for the entity selection|
+|pathObjects |Collection |->|Collection of criteria objects|
+|Result|4D.EntitySelection|<-|New entity selection in the specified order|
+
+
+#### Description
+
+The `.orderBy()` function returns a new ordered entity selection containing all entities of the entity selection in the order specified by *pathString* or *pathObjects* criteria.
+
+>* This method does not modify the original entity selection.
+* For more information, please refer to the [Ordered or unordered entity selection](ORDA/dsMapping.md#ordered-or-unordered-entity-selection) section.
+
+You must use a criteria parameter to define how the entities must be sorted. Two different parameters are supported:
+
+* *pathString* (Text) : This parameter contains a formula made of 1 to x attribute paths and (optionally) sort orders, separated by commas. The syntax is:
+
+```4d
+"attributePath1 {desc or asc}, attributePath2 {desc or asc},..."
+```
+
+The order in which the attributes are passed determines the sorting priority of the entities. By default, attributes are sorted in ascending order. You can set the sort order of a property in the criteria string, separated from the property path by a single space: pass "asc" to sort in ascending order or "desc" in descending order.
+
+* *pathObjects* (collection): each element of the collection contains an object structured in the following way:
+
+```4d
+{
+ "propertyPath": string,
+ "descending": boolean
+}
+```
+
+By default, attributes are sorted in ascending order ("descending" is false).
+
+You can add as many objects in the criteria collection as necessary.
+
+>Null values are evaluated as less than other values.
+
+#### Example
+
+
+```4d
+// order by formula
+ $sortedEntitySelection:=$entitySelection.orderBy("firstName asc, salary desc")
+ $sortedEntitySelection:=$entitySelection.orderBy("firstName")
+
+ // order by collection with or without sort orders
+ $orderColl:=New collection
+ $orderColl.push(New object("propertyPath";"firstName";"descending";False))
+ $orderColl.push(New object("propertyPath";"salary";"descending";True))
+ $sortedEntitySelection:=$entitySelection.orderBy($orderColl)
+
+ $orderColl:=New collection
+ $orderColl.push(New object("propertyPath";"manager.lastName"))
+ $orderColl.push(New object("propertyPath";"salary"))
+ $sortedEntitySelection:=$entitySelection.orderBy($orderColl)
+```
+
+
+
+
+
+
+## .orderByFormula( )
+
+History
+|Version|Changes|
+|---|---|
+|v17 R6|Added|
+
+
**.orderByFormula**( *formulaObj* : Object { ; *sortOrder* : Integer } { ; *settings* : Object} ) : 4D.EntitySelection
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|formulaString|Text|->|Formula string|
+|formulaObj|Object|->|Formula object|
+|sortOrder |Integer|->|`dk ascending` (default) or `dk descending`|
+|settings|Object|->|Parameter(s) for the formula|
+|Result|4D.EntitySelection|<-|New ordered entity selection|
+
+
+#### Description
+
+The `.orderByFormula()` function returns a new, ordered entity selection containing all entities of the entity selection in the order defined through the *formulaString* or *formulaObj* and, optionally, *sortOrder* and *settings* parameters.
+
+>This function does not modify the original entity selection.
+
+You can use either a *formulaString* or a *formulaObj* parameter:
+
+- *formulaString*: you pass a 4D expression such as "Year of(this.birthDate)".
+- *formulaObj*: pass a valid formula object created using the `Formula` or `Formula from string` command.
+
+The *formulaString* or *formulaObj* is executed for each entity of the entity selection and its result is used to define the position of the entity in the returned entity selection. The result must be of a sortable type (boolean, date, number, text, time, null).
+
+>A null result is always the smallest value.
+
+By default if you omit the *sortOrder* parameter, the resulting entity selection is sorted in ascending order. Optionnally, you can pass one of the following values in the *sortOrder* parameter:
+
+|Constant| Value| Comment|
+|---|---|---|
+|dk ascending| 0 |Ascending sort order (default)|
+|dk descending| 1 |Descending sort order|
+
+Within the *formulaString* or *formulaObj*, the processed entity and thus its attributes are available through the `This` command (for example, `This.lastName`).
+
+You can pass parameter(s) to the formula using the `args` property (object) of the `settings` parameter: the formula receives the `settings.args` object in $1.
+
+#### Example 1
+
+Sorting students using a formula provided as text:
+
+```4d
+ var $es1; $es2 : cs.StudentsSelection
+ $es1:=ds.Students.query("nationality=:1";"French")
+ $es2:=$es1.orderByFormula("length(this.lastname)") //ascending by default
+ $es2:=$es1.orderByFormula("length(this.lastname)";dk descending)
+```
+
+Same sort order but using a formula object:
+
+```4d
+ var $es1; $es2 : cs.StudentsSelection
+ var $formula : Object
+ $es1:=ds.Students.query("nationality=:1";"French")
+ $formula:=Formula(Length(This.lastname))
+ $es2:=$es1.orderByFormula($formula) // ascending by default
+ $es2:=$es1.orderByFormula($formula;dk descending)
+```
+
+
+#### Example 2
+
+A formula is given as a formula object with parameters; `settings.args` object is received as $1 in the ***computeAverage*** method.
+
+In this example, the "marks" object field in the **Students** dataClass contains students' grades for each subject. A single formula object is used to compute a student's average grade with different coefficients for schoolA and schoolB.
+
+```4d
+ var $es1; $es2 : cs.StudentsSelection
+ var $formula; $schoolA; $schoolB : Object
+ $es1:=ds.Students.query("nationality=:1";"French")
+ $formula:=Formula(computeAverage($1))
+
+ $schoolA:=New object() //settings object
+ $schoolA.args:=New object("english";1;"math";1;"history";1) // Coefficients to compute an average
+
+ //Order students according to school A criteria
+ $es2:=$es1.entitySelection.orderByFormula($formula;$schoolA)
+
+ $schoolB:=New object() //settings object
+ $schoolB.args:=New object("english";1;"math";2;"history";3) // Coefficients to compute an average
+
+ //Order students according to school B criteria
+ $es2:=$es1.entitySelection.orderByFormula($formula;dk descending;$schoolB)
+```
+
+```4d
+ //
+ // computeAverage method
+ // -----------------------------
+ #DECLARE ($coefList : Object) -> $result : Integer
+ var $subject : Text
+ var $average; $sum : Integer
+
+ $average:=0
+ $sum:=0
+
+ For each($subject;$coefList)
+ $sum:=$sum+$coefList[$subject]
+ End for each
+
+ For each($subject;This.marks)
+ $average:=$average+(This.marks[$subject]*$coefList[$subject])
+ End for each
+
+ $result:=$average/$sum
+```
+
+
+
+
+
+
+## .query()
+
+History
+|Version|Changes|
+|---|---|
+|v17 R6|Support of Formula parameters|
+|v17 R5|Support of placeholders for values|
+|v17|Added|
+
+
**.query**( *formula* : Object { ; *querySettings* : Object } ) : 4D.EntitySelection
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|queryString |Text |-> |Search criteria as string|
+|formula |Object |-> |Search criteria as formula object|
+|value|any|->|Value(s) to use for indexed placeholder(s)|
+|querySettings|Object|->|Query options: parameters, attributes, args, allowFormulas, context, queryPath, queryPlan|
+|Result|4D.EntitySelection|<-|New entity selection made up of entities from entity selection meeting the search criteria specified in *queryString* or *formula*|
+
+#### Description
+
+The `.query()` function searches for entities that meet the search criteria specified in *queryString* or *formula* and (optionally) *value*(s) among all the entities in the entity selection, and returns a new object of type `EntitySelection` containing all the entities that are found. Lazy loading is applied.
+
+>This function does not modify the original entity selection.
+
+If no matching entities are found, an empty `EntitySelection` is returned.
+
+For detailed information on how to build a query using *queryString*, *value*, and *querySettings* parameters, please refer to the DataClass [`.query()`](DataClassClass.md#query) function description.
+
+>By default if you omit the **order by** statement in the *queryString*, the returned entity selection is [not ordered](ORDA/dsMapping.md#ordered-or-unordered-entity-selection). Note however that, in Client/Server mode, it behaves like an ordered entity selection (entities are added at the end of the selection).
+
+#### Example 1
+
+
+```4d
+ var $entitySelectionTemp : cs.EmployeeSelection
+ $entitySelectionTemp:=ds.Employee.query("lastName = :1";"M@")
+ Form.emps:=$entitySelectionTemp.query("manager.lastName = :1";"S@")
+```
+
+
+#### Example 2
+
+More examples of queries can be found in the DataClass [`.query()`](DataClassClass.md#query) page.
+
+#### See also
+
+[`.query()`](DataClassClass.md#query) for dataclass
+
+
+
+
+
+
+## .queryPath
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v18 R3|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v19 R3|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+
+History
+|Version|Changes|
+|---|---|
+|v17|Added|
+
+
**.toCollection**( *filterString* : Text {; *options* : Integer { ; *begin* : Integer { ; *howMany* : Integer }}} ) : *Collection*
**.toCollection**( *filterCol* : Collection {; *options* : Integer { ; *begin* : Integer { ; *howMany* : Integer }}} ) : *Collection*
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|filterString |Text|->|String with entity attribute path(s) to extract|
+|filterCol |Collection|->|Collection of entity attribute path(s) to extract|
+|options|Integer|->|`dk with primary key`: adds the primary key
`dk with stamp`: adds the stamp|
+|begin|Integer| ->|Designates the starting index|
+|howMany|Integer|->|Number of entities to extract|
+|Result|Collection|<-|Collection of objects containing attributes and values of entity selection|
+
+
+#### Description
+
+The `.toCollection()` function creates and returns a collection where each element is an object containing a set of properties and values corresponding to the attribute names and values for the entity selection.
+
+If no filter parameter is passed or the first parameter contains an empty string or "*", all the attributes are extracted. Attributes with [kind](DataClassAttributeClass.md#kind) property as "relatedEntity" are extracted with the simple form: an object with property \_\_KEY (primary key). Attributes with kind property as "relatedEntities" are not extracted.
+
+Or, you can designate the entity attributes to extract using a filter parameter. You can use one of these two filters:
+
+* *filterString* --a string with property paths separated with commas: "propertyPath1, propertyPath2, ...".
+* *filterCol* --a collection of strings containing property paths: \["propertyPath1","propertyPath2",...]
+
+
+If a filter is specified for an attribute of the `relatedEntity` kind:
+
+* propertyPath = "relatedEntity" -> it is extracted with simple form
+* propertyPath = "relatedEntity.*" -> all the properties are extracted
+* propertyPath = "relatedEntity.propertyName1, relatedEntity.propertyName2, ..." -> only those properties are extracted
+
+
+If a filter is specified for an attribute of the `relatedEntities` kind:
+
+* propertyPath = "relatedEntities.*" -> all the properties are extracted
+* propertyPath = "relatedEntities.propertyName1, relatedEntities.propertyName2, ..." -> only those properties are extracted
+
+
+
+In the *options* parameter, you can pass the `dk with primary key` and/or `dk with stamp` selector(s) to add the entity's primary keys and/or stamps in extracted objects.
+
+The *begin* parameter allows you to indicate the starting index of the entities to extract. You can pass any value between 0 and entity selection length-1.
+
+The *howMany* parameter lets you specify the number of entities to extract, starting with the one specified in *begin*. Dropped entities are not returned but are taken into account according to *howMany*. For example, if *howMany*= 3 and there is 1 dropped entity, only 2 entities are extracted.
+
+If *howMany* > length of the entity selection, the method returns (length - *begin*) objects.
+
+An empty collection is returned if:
+
+* the entity selection is empty, or
+* *begin* is greater than the length of the entity selection.
+
+
+#### Example 1
+
+The following structure will be used throughout all examples of this section:
+
+
+
+
+Example without filter or options parameter:
+
+```4d
+ var $employeesCollection : Collection
+ var $employees : cs.EmployeeSelection
+
+ $employeesCollection:=New collection
+ $employees:=ds.Employee.all()
+ $employeesCollection:=$employees.toCollection()
+```
+
+Returns:
+
+```4d
+[
+ {
+ "ID": 416,
+ "firstName": "Gregg",
+ "lastName": "Wahl",
+ "salary": 79100,
+ "birthDate": "1963-02-01T00:00:00.000Z",
+ "woman": false,
+ "managerID": 412,
+ "employerID": 20,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 20
+ },
+ "manager": {
+ "__KEY": 412
+
+ }
+ },
+ {
+ "ID": 417,
+ "firstName": "Irma",
+ "lastName": "Durham",
+ "salary": 47000,
+ "birthDate": "1992-06-16T00:00:00.000Z",
+ "woman": true,
+ "managerID": 412,
+ "employerID": 20,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 20
+ },
+ "manager": {
+ "__KEY": 412
+ }
+ }
+]
+```
+
+#### Example 2
+
+Example with options:
+
+```4d
+var $employeesCollection : Collection
+var $employees : cs.EmployeeSelection
+
+$employeesCollection:=New collection
+$employees:=ds.Employee.all()
+$employeesCollection:=$employees.toCollection("";dk with primary key+dk with stamp)
+```
+
+Returns:
+
+```4d
+[
+ {
+ "__KEY": 416,
+ "__STAMP": 1,
+ "ID": 416,
+ "firstName": "Gregg",
+ "lastName": "Wahl",
+ "salary": 79100,
+ "birthDate": "1963-02-01T00:00:00.000Z",
+ "woman": false,
+ "managerID": 412,
+ "employerID": 20,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 20
+ },
+ "manager": {
+ "__KEY": 412
+ }
+ },
+ {
+ "__KEY": 417,
+ "__STAMP": 1,
+ "ID": 417,
+ "firstName": "Irma",
+ "lastName": "Durham",
+ "salary": 47000,
+ "birthDate": "1992-06-16T00:00:00.000Z",
+ "woman": true,
+ "managerID": 412,
+ "employerID": 20,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 20
+ },
+ "manager": {
+ "__KEY": 412
+ }
+ }]
+```
+
+#### Example 3
+
+Example with slicing and filtering on properties:
+
+```4d
+var $employeesCollection; $filter : Collection
+var $employees : cs.EmployeeSelection
+
+$employeesCollection:=New collection
+$filter:=New collection
+$filter.push("firstName")
+$filter.push("lastName")
+
+$employees:=ds.Employee.all()
+$employeesCollection:=$employees.toCollection($filter;0;0;2)
+```
+
+Returns:
+
+```4d
+[
+ {
+ "firstName": "Gregg",
+ "lastName": "Wahl"
+ },
+ {
+ "firstName": "Irma",
+ "lastName": "Durham"
+ }
+]
+
+```
+
+
+#### Example 4
+
+Example with `relatedEntity` type with simple form:
+
+
+```4d
+var $employeesCollection : Collection
+$employeesCollection:=New collection
+$employeesCollection:=$employees.toCollection("firstName,lastName,employer")
+```
+
+returns:
+
+```4d
+[
+ {
+ "firstName": "Gregg",
+ "lastName": "Wahl",
+ "employer": {
+ "__KEY": 20
+ }
+ },
+ {
+ "firstName": "Irma",
+ "lastName": "Durham",
+ "employer": {
+ "__KEY": 20
+ }
+ },
+ {
+ "firstName": "Lorena",
+ "lastName": "Boothe",
+ "employer": {
+ "__KEY": 20
+ }
+ }
+ ]
+```
+
+#### Example 5
+
+Example with *filterCol* parameter:
+
+```4d
+var $employeesCollection; $coll : Collection
+$employeesCollection:=New collection
+$coll:=New collection("firstName";"lastName")
+$employeesCollection:=$employees.toCollection($coll)
+```
+
+Returns:
+
+```4d
+[
+ {
+ "firstName": "Joanna",
+ "lastName": "Cabrera"
+ },
+ {
+ "firstName": "Alexandra",
+ "lastName": "Coleman"
+ }
+]
+```
+
+#### Example 6
+
+Example with extraction of all properties of a relatedEntity:
+
+```4d
+var $employeesCollection; $coll : Collection
+$employeesCollection:=New collection
+$coll:=New collection
+$coll.push("firstName")
+$coll.push("lastName")
+$coll.push("employer.*")
+$employeesCollection:=$employees.toCollection($coll)
+```
+
+Returns:
+
+```4d
+[
+ {
+ "firstName": "Gregg",
+ "lastName": "Wahl",
+ "employer": {
+ "ID": 20,
+ "name": "India Astral Secretary",
+ "creationDate": "1984-08-25T00:00:00.000Z",
+ "revenues": 12000000,
+ "extra": null
+ }
+ },
+ {
+ "firstName": "Irma",
+ "lastName": "Durham",
+ "employer": {
+ "ID": 20,
+ "name": "India Astral Secretary",
+ "creationDate": "1984-08-25T00:00:00.000Z",
+ "revenues": 12000000,
+ "extra": null
+ }
+ },
+ {
+ "firstName": "Lorena",
+ "lastName": "Boothe",
+ "employer": {
+ "ID": 20,
+ "name": "India Astral Secretary",
+ "creationDate": "1984-08-25T00:00:00.000Z",
+ "revenues": 12000000,
+ "extra": null
+ }
+ }
+ ]
+```
+
+#### Example 7
+
+Example with extraction of some properties of a relatedEntity:
+
+```4d
+var $employeesCollection : Collection
+$employeesCollection:=New collection
+$employeesCollection:=$employees.toCollection("firstName, lastName, employer.name")
+```
+
+```4d
+[
+ {
+ "firstName": "Gregg",
+ "lastName": "Wahl",
+
+ "employer": {
+ "name": "India Astral Secretary"
+ }
+ },
+ {
+ "firstName": "Irma",
+ "lastName": "Durham",
+ "employer": {
+ "name": "India Astral Secretary"
+ }
+ },
+ {
+ "firstName": "Lorena",
+ "lastName": "Boothe",
+ "employer": {
+ "name": "India Astral Secretary"
+ }
+ }]
+```
+
+#### Example 8
+
+Example with extraction of some properties of `relatedEntities`:
+
+```4d
+ var $employeesCollection : Collection
+ $employeesCollection:=New collection
+ $employeesCollection:=$employees.toCollection("firstName, lastName, directReports.firstName")
+```
+
+Returns:
+
+```4d
+[
+ {
+ "firstName": "Gregg",
+ "lastName": "Wahl",
+ "directReports": []
+ },
+ {
+ "firstName": "Mike",
+ "lastName": "Phan",
+ "directReports": [
+ {
+ "firstName": "Gary"
+ },
+ {
+ "firstName": "Sadie"
+ },
+ {
+ "firstName": "Christie"
+ }
+ ]
+ },
+ {
+ "firstName": "Gary",
+
+ "lastName": "Reichert",
+ "directReports": [
+ {
+ "firstName": "Rex"
+ },
+ {
+ "firstName": "Jenny"
+ },
+ {
+ "firstName": "Lowell"
+ }
+ ]
+ }]
+```
+
+#### Example 9
+
+Example with extraction of all properties of `relatedEntities`:
+
+```4d
+var $employeesCollection : Collection
+$employeesCollection:=New collection
+$employeesCollection:=$employees.toCollection("firstName, lastName, directReports.*")
+
+```
+
+```4d
+[
+ {
+ "firstName": "Gregg",
+ "lastName": "Wahl",
+ "directReports": []
+ },
+ {
+ "firstName": "Mike",
+ "lastName": "Phan",
+ "directReports": [
+ {
+ "ID": 425,
+ "firstName": "Gary",
+ "lastName": "Reichert",
+ "salary": 65800,
+ "birthDate": "1957-12-23T00:00:00.000Z",
+ "woman": false,
+ "managerID": 424,
+ "employerID": 21,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 21
+ },
+ "manager": {
+ "__KEY": 424
+ }
+ },
+ {
+ "ID": 426,
+ "firstName": "Sadie",
+ "lastName": "Gallant",
+ "salary": 35200,
+ "birthDate": "2022-01-03T00:00:00.000Z",
+ "woman": true,
+ "managerID": 424,
+ "employerID": 21,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 21
+ },
+ "manager": {
+ "__KEY": 424
+ }
+ }
+ ]
+ },
+ {
+ "firstName": "Gary",
+ "lastName": "Reichert",
+ "directReports": [
+ {
+ "ID": 428,
+ "firstName": "Rex",
+ "lastName": "Chance",
+ "salary": 71600,
+ "birthDate": "1968-08-09T00:00:00.000Z",
+ "woman": false,
+
+ "managerID": 425,
+ "employerID": 21,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 21
+ },
+ "manager": {
+ "__KEY": 425
+ }
+ },
+ {
+ "ID": 429,
+ "firstName": "Jenny",
+ "lastName": "Parks",
+ "salary": 51300,
+ "birthDate": "1984-05-25T00:00:00.000Z",
+ "woman": true,
+ "managerID": 425,
+ "employerID": 21,
+ "photo": "[object Picture]",
+ "extra": null,
+ "employer": {
+ "__KEY": 21
+ },
+ "manager": {
+ "__KEY": 425
+ }
+ }
+ ]
+ }
+]
+```
+
+
+
+
+
+
+
+
diff --git a/docs/API/FileClass.md b/docs/API/FileClass.md
new file mode 100644
index 00000000000000..cfbb0c8c755a87
--- /dev/null
+++ b/docs/API/FileClass.md
@@ -0,0 +1,745 @@
+---
+id: FileClass
+title: File
+---
+
+`File` objects are created with the [`File`](#file) command. They contain references to disk files that may or may not actually exist on disk. For example, when you execute the `File` command to create a new file, a valid `File` object is created but nothing is actually stored on disk until you call the [`file.create( )`](#create) function.
+
+### Example
+
+The following example creates a preferences file in the project folder:
+
+```code4d
+var $created : Boolean
+$created:=File("/PACKAGE/SpecialPrefs/"+Current user+".myPrefs").create()
+```
+
+### File object
+
+||
+|---|
+|[](#copyto)
|
+|[](#create)
|
+|[](#createalias)
|
+|[](#creationdate)
|
+|[](#creationtime)
|
+|[](#delete)
|
+|[](#exists)
|
+|[](#extension)
|
+|[](#fullname)
|
+|[](#getappinfo)
|
+|[](#getcontent)
|
+|[](#geticon)
|
+|[](#gettext)
|
+|[](#hidden)
|
+|[](#isalias)
+|[](#isfile)
|
+|[](#isfolder)
|
+|[](#iswritable)
|
+|[](#modificationdate)
|
+|[](#modificationtime)
|
+|[](#moveto)
|
+|[](#name)
|
+|[](#original)
|
+|[](#parent)
|
+|[](#path)
|
+|[](#platformpath)
|
+|[](#rename)
|
+|[](#setappinfo)
|
+|[](#setcontent)
|
+|[](#settext)
|
+|[](#size)
|
+
+
+
+## File
+
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+
**File** ( *fileConstant* : Integer { ; *\** } ) : 4D.File
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|path|Text|->|File path|
+|fileConstant|Integer|->|4D file constant|
+|pathType|Integer|->|`fk posix path` (default) or `fk platform path`|
+|*||->|* to return file of host database|
+|Result|4D.File|<-|New file object|
+
+
+
+#### Description
+
+The `File` command creates and returns a new object of the `4D.File` type. The command accepts two syntaxes:
+
+**File ( path { ; pathType } { ; \* })**
+
+In the *path* parameter, pass a file path string. You can use a custom string or a filesystem (e.g., "/DATA/myfile.txt").
+
+> Only absolute pathnames are supported with the `File` command.
+
+By default, 4D expects a path expressed with the POSIX syntax. If you work with platform pathnames (Windows or macOS), you must declare it using the *pathType* parameter. The following constants are available:
+
+|Constant|Value|Comment|
+|---|---|---|
+|fk platform path|1|Path expressed with a platform-specific syntax (mandatory in case of platform pathname)|
+|fk posix path|0|Path expressed with POSIX syntax (default)
+
+**File ( fileConstant { ; \* } )**
+
+In the *fileConstant* parameter, pass a 4D built-in or system file, using one of the following constants:
+
+|Constant|Value|Comment|
+|---|---|---|
+|Backup history file|19|Backup history file (see Configuration and trace files). Stored in the backup destination folder. |
+|Backup log file|13|Current backup journal file. Stored in the application Logs folder.|
+|Backup settings file|1|Default backup.4DSettings file (xml format), stored in the Settings folder of the project|
+|Backup settings file for data|17|backup.4DSettings file (xml format) for the data file, stored in the Settings folder of the data folder|
+|Build application log file|14|Current log file in xml format of the application builder. Stored in the Logs folder. |
+|Build application settings file|20|Default settings file of the application builder ("buildApp.4DSettings"). Stored in the Settings folder of the project.|
+|Compacting log file|6|Log file of the most recent compacting done with the Compact data file command or the Maintenance and security center. Stored in the Logs folder.|
+|Current backup settings file|18|backup.4DSettings file currently used by the application. It can be the backup settings file (default) or a custom user backup settings file defined for the data file|
+|Debug log file|12|Log file created by the `SET DATABASE PARAMETER(Debug log recording)` command. Stored in the Logs folder. |
+|Diagnostic log file|11|Log file created by the `SET DATABASE PARAMETER(Diagnostic log recording)` command. Stored in the Logs folder. |
+|Directory file|16|directory.json file, containing the description of users and groups (if any) for the project application. It can be located either in the user settings folder (default, global to the project), or in the data settings folder (specific to a data file). |
+|HTTP debug log file|9|Log file created by the `WEB SET OPTION(Web debug log)` command. Stored in the Logs folder. |
+|HTTP log file|8|Log file created by the `WEB SET OPTION(Web log recording)` command. Stored in Logs folder.|
+|IMAP Log file|23|Log file created by the `SET DATABASE PARAMETER(IMAP Log)` command. Stored in the Logs folder.|
+|Last backup file|2|Last backup file, named \[bkpNum].4BK, stored at a custom location.|
+|Last journal integration log file|22|Full pathname of the last journal integration log file (stored in the Logs folder of the restored application), if any. This file is created, in auto-repair mode, as soon as a log file integration occurred|
+|Repair log file|7|Log file of database repairs made on the database in the Maintenance and Security Center (MSC). Stored in the Logs folder.|
+|Request log file|10|Standard client/server request log file (excluding Web requests) created by the `SET DATABASE PARAMETER(4D Server log recording)` or `SET DATABASE PARAMETER(Client log recording)` commands. If executed on the server, the server log file is returned (stored in the Logs folder on the server). If executed on the client, the client log file is returned (stored in the client local Logs folder). |
+|SMTP log file|15|Log file created by the `SET DATABASE PARAMETER(SMTP Log)` command. Stored in the Logs folder. |
+|User settings file|3|settings.4DSettings file for all data files, stored in Preferences folder next to structure file if enabled.|
+|User settings file for data|4|settings.4DSettings file for current data file, stored in Preferences folder next to the data file.|
+|Verification log file|5|Log files created by the `VERIFY CURRENT DATA FILE` and `VERIFY DATA FILE` commands or the Maintenance and Security Center (MSC). Stored in the Logs folder. |
+
+If the target *fileConstant* does not exist, a null object is returned. No errors are raised.
+
+If the command is called from a component, pass the optional * parameter to get the path of the host database. Otherwise, if you omit the * parameter, a null object is always returned.
+
+
+## 4D.File.new()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R6|Added
+
**4D.File.new** ( *fileConstant* : Integer { ; *\** } ) : 4D.File
+
+
+#### Description
+
+The `4D.File.new()` function creates and returns a new object of the `4D.File` type. It is identical to the [`File`](#file) command (shortcut).
+
+> It is recommended to use the [`File`](#file) shortcut command instead of `4D.File.new()`.
+
+
+
+
+
+
+
+## .create()
+
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v19|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v19|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+
**.setText** ( *text* : Text {; *charSetNum* : Integer { ; *breakMode* : Integer } } )
+
+
+
+|Parameter|Type||Description|
+|---------|----|---|--------|
+|text|Text|->|Text to store in the file|
+|charSetName|Text|->|Name of character set|
+|charSetNum|Integer|->|Number of character set|
+|breakMode|Integer|->|Processing mode for line breaks|
+
+#### Description
+
+The `.setText()` function writes *text* as the new contents of the file.
+
+If the file referenced in the `File` object does not exist on the disk, it is created by the function. When the file already exists on the disk, its prior contents are erased, except if it is already open, in which case, its contents are locked and an error is generated.
+
+In *text*, pass the text to write to the file. It can be a literal ("my text"), or a 4D text field or variable.
+
+Optionally, you can designate the character set to be used for writing the contents. You can pass either:
+
+- in *charSetName*, a string containing the standard set name (for example "ISO-8859-1" or ""UTF-8"),
+- or in *charSetNum*, the MIBEnum ID (number) of the standard set name.
+
+> For the list of character sets supported by 4D, refer to the description of the `CONVERT FROM TEXT` command.
+
+If a Byte Order Mark (BOM) exists for the character set, 4D inserts it into the file unless the character set used contains the suffix "-no-bom" (e.g. "UTF-8-no-bom"). If you do not specify a character set, by default 4D uses the "UTF-8" character set.
+
+In *breakMode*, you can pass a number indicating the processing to apply to end-of-line characters before saving them in the file. The following constants, found in the **System Documents** theme, are available:
+
+|Constant|Value|Comment|
+|--------|-----|-------|
+|`Document unchanged`|0|No processing|
+|`Document with native format`|1|(Default) Line breaks are converted to the native format of the operating system: LF (carriage return) on macOS, CRLF (carriage return + line feed) on Windows|
+|`Document with CRLF`|2|Line breaks are converted to CRLF (carriage return + line feed), the default Windows format|
+|`Document with CR`|3|Line breaks are converted to CR (carriage return), the default Classic Mac OS format|
+|`Document with LF`|4|Line breaks are converted to LF (line feed), the default Unix and macOS format|
+
+By default, when you omit the *breakMode* parameter, line breaks are processed in native mode (1).
+
+> **Compatibility Note**: compatibility options are available for EOL and BOM management. See [Compatibility page](https://doc.4d.com/4dv19R/help/title/en/page3239.html) on doc.4d.com.
+
+#### Example
+
+```4d
+$myFile:=File("C:\\Documents\\Hello.txt";fk platform path)
+$myFile.setText("Hello world")
+```
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/API/FolderClass.md b/docs/API/FolderClass.md
new file mode 100644
index 00000000000000..87e82bded1b0b6
--- /dev/null
+++ b/docs/API/FolderClass.md
@@ -0,0 +1,488 @@
+---
+id: FolderClass
+title: Folder
+---
+
+
+
+`Folder` objects are created with the [`Folder`](#folder) command. They contain references to folders that may or may not actually exist on disk. For example, when you execute the `Folder` command to create a new folder, a valid `Folder` object is created but nothing is actually stored on disk until you call the [`folder.create( )`](#create-) function.
+
+### Example
+
+The following example creates a "JohnSmith" folder:
+
+```code4d
+Form.curfolder:=Folder(fk database folder)
+Form.curfolder:=Folder("C:\\Users\\JohnSmith\\";fk platform path)
+```
+
+### Folder object
+
+||
+|---|
+|[](#copyto) |
+|[](#create)
|
+|[](#createalias)
|
+|[](#creationdate)
|
+|[](#creationtime)
|
+|[](#delete)
|
+|[](#exists)
|
+|[](#extension)
|
+|[](#fullname)
|
+|[](#geticon)
|
+|[](#hidden)
|
+|[](#isalias)
|
+|[](#isfile)
|
+|[](#isfolder)
|
+|[](#ispackage)
|
+|[](#modificationdate)
|
+|[](#modificationtime)
|
+|[](#name)
|
+|[](#original)
|
+|[](#parent)
|
+|[](#path)
|
+|[](#platformpath)
|
+|[](#moveto)
|
+|[](#rename)
|
+
+
+
+## Folder
+
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added|
+
**Folder** ( *folderConstant* : Integer { ; *\** } ) : 4D.Folder
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|path|Text|->|Folder path|
+|folderConstant|Integer|->|4D folder constant|
+|pathType|Integer|->|`fk posix path` (default) or `fk platform path`|
+|*||->|* to return folder of host database|
+|Result|4D.Folder|<-|New folder object|
+
+
+
+#### Description
+
+The `Folder` command creates and returns a new object of the `4D.Folder` type. The command accepts two syntaxes:
+
+**Folder ( path { ; pathType } { ; \* } )**
+
+In the *path* parameter, pass a folder path string. You can use a custom string or a filesystem (e.g., "/DATA").
+
+> Only absolute pathnames are supported with the `Folder` command.
+
+By default, 4D expects a path expressed with the POSIX syntax. If you work with platform pathnames (Windows or macOS), you must declare it using the *pathType* parameter. The following constants are available:
+
+|Constant|Value|Comment|
+|---|---|---|
+|fk platform path|1|Path expressed with a platform-specific syntax (mandatory in case of platform pathname)|
+|fk posix path|0|Path expressed with POSIX syntax (default)
+
+**Folder ( folderConstant { ; \* } )**
+
+In the *folderConstant* parameter, pass a 4D built-in or system folder, using one of the following constants:
+
+|Constant|Value|Comment|
+|---|---|---|
+|fk applications folder|116||
+|fk data folder|9|Associated filesystem: "/DATA"|
+|fk database folder|4|Associated filesystem: "/PACKAGE"|
+|fk desktop folder|115||
+|fk documents folder|117|Document folder of the user|
+|fk licenses folder|1|Folder containing the machine's 4D license files|
+|fk logs folder|7|Associated filesystem: "/LOGS"|
+|fk mobileApps folder|10|Associated filesystem: "/DATA"|
+|fk remote database folder|3|4D database folder created on each 4D remote machine|
+|fk resources folder|6|Associated filesystem: "/RESOURCES"|
+|fk system folder|100||
+|fk user preferences folder|0|4D folder that stores user preference files within the \ directory.|
+|fk web root folder|8|Current Web root folder of the database: if within the package "/PACKAGE/path", otherwise full path|
+
+If the command is called from a component, pass the optional * parameter to get the path of the host database. Otherwise, if you omit the * parameter, a null object is always returned.
+
+
+## 4D.Folder.new()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R6|Added
+
**4D.Folder.new** ( *folderConstant* : Integer { ; *\** } ) : 4D.Folder
+
+
+#### Description
+
+The `4D.Folder.new()` function creates and returns a new object of the `4D.Folder` type. It is identical to the [`Folder`](#folder) command (shortcut).
+
+> It is recommended to use the [`Folder`](#folder) shortcut command instead of `4D.Folder.new()`.
+
+
+
+
+
+
+
+## .create()
+
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+History
+|Version|Changes|
+|---|---|
+|v17 R5|Added
+ |
+|[](#call)
|
+|[](#source)
|
+
+
+
+
+## Formula
+
+History
+|Version|Changes|
+|---|---|
+|v17 R6|Renamed (New formula -> Formula)|
+|v17 R3|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R6|Renamed New formula from string -> Formula from string|
+|v17 R3|Added|
+History
+|Version|Changes|
+|---|---|
+|v17 R3|Added|
+
**.apply**( *thisObj* : Object { ; *formulaParams* : Collection } ) : any
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|thisObj|Object|->|Object to be returned by the This command in the formula|
+|formulaParams |Collection|->|Collection of values to be passed as $1...$n when `formula` is executed|
+|Result|any|<-|Value from formula execution|
+
+
+
+#### Description
+
+The `.apply()` function executes the `formula` object to which it is applied and returns the resulting value. The formula object can be created using the `Formula` or `Formula from string` commands.
+
+
+In the *thisObj* parameter, you can pass a reference to the object to be used as `This` within the formula.
+
+You can also pass a collection to be used as $1...$n parameters in the formula using the optional *formulaParams* parameter.
+
+Note that `.apply()` is similar to [`.call()`](#call) except that parameters are passed as a collection. This can be useful for passing calculated results.
+
+
+#### Example 1
+
+```4d
+ var $f : 4D.Function
+ $f:=Formula($1+$2+$3)
+
+ $c:=New collection(10;20;30)
+ $result:=$f.apply(Null;$c) // returns 60
+```
+
+
+#### Example 2
+
+```4d
+ var $calc : 4D.Function
+ var $feta; $robot : Object
+ $robot:=New object("name";"Robot";"price";543;"quantity";2)
+ $feta:=New object("name";"Feta";"price";12.5;"quantity";5)
+
+ $calc:=Formula(This.total:=This.price*This.quantity)
+
+ $calc.apply($feta) // $feta={name:Feta,price:12.5,quantity:5,total:62.5}
+ $calc.apply($robot) // $robot={name:Robot,price:543,quantity:2,total:1086}
+```
+
+
+
+
+
+## .call()
+
+History
+|Version|Changes|
+|---|---|
+|v17 R3|Added|
+
**.call**( *thisObj* : Object { ; ...*params* : any } ) : any
+
+
+|Parameter|Type||Description|
+|---|---|---|---|
+|thisObj|Object|->|Object to be returned by the This command in the formula|
+|params |any|->|Value(s) to be passed as $1...$n when formula is executed|
+|Result|any|<-|Value from formula execution|
+
+
+
+#### Description
+
+The `.call()` function executes the `formula` object to which it is applied and returns the resulting value. The formula object can be created using the `Formula` or `Formula from string` commands.
+
+In the *thisObj* parameter, you can pass a reference to the object to be used as `This` within the formula.
+
+You can also pass values to be used as *$1...$n* parameters in the formula using the optional *params* parameter(s).
+
+Note that `.call()` is similar to [`.apply()`](#apply) except that parameters are passed directly.
+
+#### Example 1
+
+```4d
+ var $f : 4D.Function
+ $f:=Formula(Uppercase($1))
+ $result:=$f.call(Null;"hello") // returns "HELLO"
+```
+
+#### Example 2
+
+```4d
+ $o:=New object("value";50)
+ $f:=Formula(This.value*2)
+ $result:=$f.call($o) // returns 100
+```
+
+
+
+
+
+
+## .source
+
+History
+|Version|Changes|
+|---|---|
+|v18 R2|Added|
+
|
+|[](#addflags)
|
+|[](#append)
|
+|[](#authenticationmode)
|
+|[](#checkconnection)
|
+|[](#checkconnectiondelay)
|
+|[](#connectiontimeout)
|
+|[](#copy)
|
+|[](#createbox)
|
+|[](#delete)
|
+|[](#deletebox)
|
+|[](#expunge)
|
+|[](#getboxinfo)
|
+|[](#getboxlist)
|
+|[](#getdelimiter)
|
+|[](#getmail)
|
+|[](#getmails)
|
+|[](#getmimeasblob)
|
+|[](#host)
|
+|[](#logfile)
|
+|[](#move)
|
+|[](#numtoid)
|
+|[](#removeflags)
|
+|[](#renamebox)
|
+|[](#port)
|
+|[](#searchmails)
|
+|[](#selectbox)
|
+|[](#subscribe)
|
+|[](#unsubscribe)
|
+|[](#user)
|
+
+
+
+## IMAP New transporter
+
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added|
+
|False|
+|.**accessTokenOAuth2**: Text
.**accessTokenOAuth2**: Object
Text string or token object representing OAuth2 authorization credentials. Used only with OAUTH2 `authenticationMode`. If `accessTokenOAuth2` is used but `authenticationMode` is omitted, the OAuth 2 protocol is used (if allowed by the server). Not returned in *[IMAP transporter](#imap-transporter-object)* object.|none|
+|[](#authenticationmode)
|the most secure authentication mode supported by the server is used|
+|[](#checkconnectiondelay)
|300|
+|[](#connectiontimeout)
|30|
+|[](#host)
|*mandatory*
+|[](#logfile)
|none|
+|.**password** : Text
User password for authentication on the server. Not returned in *[IMAP transporter](#imap-transporter-object)* object.|none|
+|[](#port)
|993|
+|[](#user)
|none|
+
+
+>**Warning**: Make sure the defined timeout is lower than the server timeout, otherwise the client timeout will be useless.
+
+
+#### Result
+
+The function returns an [**IMAP transporter object**](#imap-transporter-object). All returned properties are **read-only**.
+
+>The IMAP connection is automatically closed when the transporter object is destroyed.
+
+#### Example
+
+```4d
+$server:=New object
+$server.host:="imap.gmail.com" //Mandatory
+$server.port:=993
+$server.user:="4d@gmail.com"
+$server.password:="XXXXXXXX"
+$server.logFile:="LogTest.txt" //log to save in the Logs folder
+
+var $transporter : 4D.IMAPTransporter
+ $transporter:=IMAP New transporter($server)
+
+$status:=$transporter.checkConnection()
+If(Not($status.success))
+ ALERT("An error occurred: "+$status.statusText)
+End if
+```
+
+
+## 4D.IMAPTransporter.new()
+
+
+
+**4D.IMAPTransporter.new**( *server* : Object ) : 4D.IMAPTransporter
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|server|Object|->|Mail server information|
+|Result|4D.IMAPTransporter|<-|[IMAP transporter object](#imap-transporter-object)|
+
+
+#### Description
+
+The `4D.IMAPTransporter.new()` function creates and returns a new object of the `4D.IMAPTransporter` type. It is identical to the [`IMAP New transporter`](#imap-new-transporter) command (shortcut).
+
+
+
+
+
+## .addFlags()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R6|Added|
+
**.addFlags**( *msgIDs* : Text ; *keywords* : Object ) : Object
**.addFlags**( *msgIDs* : Longint ; *keywords* : Object ) : Object
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|msgIDs|Collection|->|Collection of strings: Message unique IDs (text)
Text: Unique ID of a message
Longint (IMAP all): All messages in the selected mailbox|
+|keywords|Object|->|Keyword flags to add|
+|Result|Object|<-|Status of the addFlags operation|
+
+
+
+#### Description
+
+The `.addFlags()` function adds flags to the `msgIDs` for the specified `keywords`.
+
+In the `msgIDs` parameter, you can pass either:
+
+* a *collection* containing the unique IDs of specific messages or
+* the unique ID (*text*) of a single message or
+* the following constant (*longint*) for all messages in the selected mailbox:
+
+ |Constant |Value |Comment|
+ |---|---|---|
+ |IMAP all |1 |Select all messages in the selected mailbox|
+
+The `keywords` parameter lets you pass an object with keyword values for specific flags to add to `msgIDs`. You can pass any of the following keywords:
+
+|Parameter|Type|Description|
+|---|---|---|
+|$draft |Boolean |True to add the "draft" flag to the message |
+|$seen |Boolean |True to add the "seen" flag to the message|
+|$flagged |Boolean |True to add the "flagged" flag to the message|
+|$answered |Boolean |True to add the "answered" flag to the message|
+|$deleted |Boolean | True to add the "deleted" flag to the message|
+
+>* False values are ignored.
+>* The interpretation of keyword flags may vary per mail client.
+
+
+**Returned object**
+
+The function returns an object describing the IMAP status:
+
+|Property|| Type| Description|
+|---|---|---|---|
+|success||Boolean|True if the operation is successful, False otherwise
+|statusText || Text|Status message returned by the IMAP server, or last error returned in the 4D error stack |
+|errors ||Collection|4D error stack (not returned if a IMAP server response is received)|
+| |\[].errcode|Number| 4D error code|
+| |\[].message|Text|Description of the 4D error |
+| |\[].componentSignature|Text|Signature of the internal component which returned the error|
+
+
+#### Example
+
+```4d
+var $options;$transporter;$boxInfo;$status : Object
+
+$options:=New object
+$options.host:="imap.gmail.com"
+$options.port:=993
+$options.user:="4d@gmail.com"
+$options.password:="xxxxx"
+
+// Create transporter
+$transporter:=IMAP New transporter($options)
+
+// Select mailbox
+$boxInfo:=$transporter.selectBox("INBOX")
+
+// Mark all messages from INBOX as read/seen
+$flags:=New object
+$flags["$seen"]:=True
+$status:=$transporter.addFlags(IMAP all;$flags)
+```
+
+
+
+
+
+## .append()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R6|Added|
+
- headerCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & Quoted-printable if possible, otherwise UTF-8 & Quoted-printable
- bodyCharset: US-ASCII if possible, Japanese (ISO-2022-JP) & 7-bit if possible, otherwise UTF-8 & Quoted-printable
|
+|mail mode ISO88591|ISO-8859-1|- headerCharset: ISO-8859-1 & Quoted-printable
- bodyCharset: ISO-8859-1 & 8-bit
|
+|mail mode UTF8|US-ASCII_UTF8_QP|headerCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & Quoted-printable (**default value**)|
+|mail mode UTF8 in base64|US-ASCII_UTF8_B64|headerCharset & bodyCharset: US-ASCII if possible, otherwise UTF-8 & base64|
+
+
+**Returned object**
+
+The function returns an object describing the IMAP status:
+
+|Property|| Type| Description|
+|---|---|---|---|
+|success||Boolean|True if the operation is successful, False otherwise
+|statusText || Text|Status message returned by the IMAP server, or last error returned in the 4D error stack |
+|errors ||Collection|4D error stack (not returned if a IMAP server response is received)|
+| |\[].errcode|Number| 4D error code|
+| |\[].message|Text|Description of the 4D error |
+| |\[].componentSignature|Text|Signature of the internal component which returned the error|
+
+
+#### Example
+
+To save an email in the Drafts mailbox:
+
+```4d
+var $settings; $status; $msg; $imap: Object
+
+$settings:=New object("host"; "domain.com"; "user"; "xxxx"; "password"; "xxxx"; "port"; 993)
+
+$imap:=IMAP New transporter($settings)
+
+$msg:=New object
+$msg.from:="xxxx@domain.com"
+$msg.subject:="Lorem Ipsum"
+$msg.textBody:="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+$msg.keywords:=New object
+$msg.keywords["$seen"]:=True//flag the message as read
+$msg.keywords["$draft"]:=True//flag the message as a draft
+
+$status:=$imap.append($msg; "Drafts")
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## .checkConnectionDelay
+
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R5|Added|
+
**.copy**( *allMsgs* : Integer ; *destinationBox* : Text ) : Object
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|msgsIDs|Collection|->|Collection of message unique IDs (strings)|
+|allMsgs|Integer|->|`IMAP all`: All messages in the selected mailbox|
+|destinationBox|Text|->|Mailbox to receive copied messages|
+|Result|Object|<-|Status of the copy operation|
+
+
+
+#### Description
+
+The `.copy()` function copies the messages defined by *msgsIDs* or *allMsgs* to the *destinationBox* on the IMAP server.
+
+You can pass:
+
+- in the *msgsIDs* parameter, a collection containing the unique IDs of the specific messages to copy, or
+- in the *allMsgs* parameter, the `IMAP all` constant (integer) to copy all messages in the selected mailbox.
+
+The *destinationBox* parameter allows you to pass a text value with the name of the mailbox where the copies of messages will be placed.
+
+
+**Returned object**
+
+The function returns an object describing the IMAP status:
+
+|Property|| Type| Description|
+|---|---|---|---|
+|success||Boolean|True if the operation is successful, False otherwise
+|statusText || Text|Status message returned by the IMAP server, or last error returned in the 4D error stack |
+|errors ||Collection|4D error stack (not returned if a IMAP server response is received)|
+| |\[].errcode|Number| 4D error code|
+| |\[].message|Text|Description of the 4D error |
+| |\[].componentSignature|Text|Signature of the internal component which returned the error|
+
+
+
+
+#### Example 1
+
+To copy a selection of messages:
+
+
+```4d
+ var $server;$boxInfo;$status : Object
+ var $mailIds : Collection
+ var $transporter : 4D.IMAPTransporter
+
+ $server:=New object
+ $server.host:="imap.gmail.com" //Mandatory
+ $server.port:=993
+ $server.user:="4d@gmail.com"
+ $server.password:="XXXXXXXX"
+
+ $transporter:=IMAP New transporter($server)
+
+ //select mailbox
+ $boxInfo:=$transporter.selectBox("inbox")
+
+ //get collection of message unique IDs
+ $mailIds:=$transporter.searchMails("subject \"4D new feature:\"")
+
+ // copy found messages to the "documents" mailbox
+ $status:=$transporter.copy($mailIds;"documents")
+```
+
+#### Example 2
+
+To copy all messages in the current mailbox:
+
+
+```4d
+ var $server;$boxInfo;$status : Object
+ var $transporter : 4D.IMAPTransporter
+
+ $server:=New object
+ $server.host:="imap.gmail.com" //Mandatory
+ $server.port:=993
+ $server.user:="4d@gmail.com"
+ $server.password:="XXXXXXXX"
+
+ $transporter:=IMAP New transporter($server)
+
+ //select mailbox
+
+ $boxInfo:=$transporter.selectBox("inbox")
+
+ // copy all messages to the "documents" mailbox
+ $status:=$transporter.copy(IMAP all;"documents")
+```
+
+
+
+
+
+## .createBox()
+
+History
+|Version|Changes|
+|---|---|
+|v19|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R5|Added|
+
**.delete**( *allMsgs* : Integer ) : Object
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|msgsIDs|Collection|->|Collection of message unique IDs (strings)|
+|allMsgs|Integer|->|`IMAP all`: All messages in the selected mailbox|
+|Result|Object|<-|Status of the delete operation|
+
+
+
+#### Description
+
+The `.delete()` function sets the "deleted" flag for the messages defined in `msgsIDs` or `allMsgs`.
+
+You can pass:
+
+- in the `msgsIDs` parameter, a collection containing the unique IDs of the specific messages to delete, or
+- in the `allMsgs` parameter, the `IMAP all` constant (integer) to delete all messages in the selected mailbox.
+
+Executing this function does not actually remove messages. Messages with the "delete" flag can still be found by the [.searchMails()](#searchmails) function. Flagged messages are deleted from the IMAP server with the [`.expunge()`](#expunge) function or by selecting another mailbox or when the [transporter object](#imap-transporter-object) (created with [IMAP New transporter](#imap-new-transporter)) is destroyed.
+
+
+
+**Returned object**
+
+The function returns an object describing the IMAP status:
+
+|Property|| Type| Description|
+|---|---|---|---|
+|success||Boolean|True if the operation is successful, False otherwise
+|statusText || Text|Status message returned by the IMAP server, or last error returned in the 4D error stack |
+|errors ||Collection|4D error stack (not returned if a IMAP server response is received)|
+| |\[].errcode|Number| 4D error code|
+| |\[].message|Text|Description of the 4D error |
+| |\[].componentSignature|Text|Signature of the internal component which returned the error|
+
+
+
+
+#### Example 1
+
+To delete a selection of messages:
+
+
+```4d
+ var $server;$boxInfo;$status : Object
+ var $mailIds : Collection
+ var $transporter : 4D.IMAPTransporter
+
+ $server:=New object
+ $server.host:="imap.gmail.com" //Mandatory
+ $server.port:=993
+ $server.user:="4d@gmail.com"
+ $server.password:="XXXXXXXX"
+
+ $transporter:=IMAP New transporter($server)
+
+ //select mailbox
+ $boxInfo:=$transporter.selectBox("Inbox")
+
+ //get collection of message unique IDs
+ $mailIds:=$transporter.searchMails("subject \"Reports\"")
+
+ // Delete selected messages
+ $status:=$transporter.delete($mailIds)
+```
+
+#### Example 2
+
+To delete all messages in the current mailbox:
+
+
+```4d
+ var $server;$boxInfo;$status : Object
+ var $transporter : 4D.IMAPTransporter
+
+ $server:=New object
+ $server.host:="imap.gmail.com" //Mandatory
+ $server.port:=993
+ $server.user:="4d@gmail.com"
+ $server.password:="XXXXXXXX"
+
+ $transporter:=IMAP New transporter($server)
+
+ //select mailbox
+ $boxInfo:=$transporter.selectBox("Junk Email")
+
+ // delete all messages in the current mailbox
+ $status:=$transporter.delete(IMAP all)
+```
+
+
+
+
+
+## .deleteBox()
+
+History
+|Version|Changes|
+|---|---|
+|v19|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R6|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R5|name is optional|
+|v18 R4|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added|
+|v19|Add `isSubscribed` parameter|
+- true - the mailbox can be selected
- false - the mailbox can not be selected
|
+|\[].inferior |boolean |Indicates whether or not the access rights allow creating a lower hierachy in the mailbox: - true - a lower level can be created
- false - a lower level can not be created
|
+|\[].interesting |boolean |Indicates if the mailbox has been marked "interesting" by the server: - true - The mailbox has been marked "interesting" by the server. For example, it may contain new messages.
- false - The mailbox has not been marked "interesting" by the server.
|
+
+
+If the account does not contain any mailboxes, an empty collection is returned.
+
+>* If there is no open connection, `.getBoxList()` will open a connection.
+>* If the connection has not been used since the designated connection delay (see `IMAP New transporter`), the `.checkConnection( )` function is automatically called.
+
+
+#### Example
+
+
+```4d
+ var $transporter : 4D.IMAPTransporter
+ $transporter:=IMAP New transporter($server)
+
+ $boxList:=$transporter.getBoxList()
+
+ For each($box;$boxList)
+ If($box.interesting)
+ $split:=Split string($box.name;$transporter.getDelimiter())
+ ALERT("New emails are available in the box: "+$split[$split.length-1])
+ End if
+ End for each
+```
+
+
+
+
+
+
+## .getDelimiter()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added|
+
**.getMail**( *msgID*: Text { ; *options* : Object } ) : Object
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|msgNumber|Integer|->|Sequence number of the message|
+|msgID|Text|->|Unique ID of the message|
+|options|Object|->|Message handling instructions|
+|Result|Object|<-|[Email object](EmailObjectClass.md#email-object)|
+
+
+
+#### Description
+
+The `.getMail()` function returns the `Email` object corresponding to the *msgNumber* or *msgID* in the mailbox designated by the `IMAP_transporter`. This function allows you to locally handle the email contents.
+
+In the first parameter, you can pass either:
+
+* *msgNumber*, an *integer* value indicating the sequence number of the message to retrieve or
+* *msgID*, a *text* value indicating the unique ID of the message to retrieve.
+
+The optional *options* parameter allows you pass an object defining additional instructions for handling the message. The following properties are available:
+
+|Property | Type | Description |
+|---|---|---|
+|updateSeen|boolean|If True, the message is marked as "seen" in the mailbox. If False, the message is not marked as "seen". Default value: True|
+|withBody|boolean | Pass True to return the body of the message. If False, only the message header is returned. Default value: True|
+
+>* The function generates an error and returns **Null** if *msgID* designates a non-existing message,
+>* If no mailbox is selected with the [`.selectBox()`](#selectbox) function, an error is generated,
+>* If there is no open connection, `.getMail()` will open a connection the last mailbox specified with [`.selectBox()`](#selectbox)`.
+
+
+
+#### Result
+
+`.getMail()` returns an [`Email` object](EmailObjectClass.md#email-object) with the following specific IMAP properties: *id*, *receivedAt*, and *size*.
+
+#### Example
+
+You want to get the message with ID = 1:
+
+```4d
+ var $server : Object
+ var $info; $mail; $boxInfo : Variant
+ var $transporter : 4D.IMAPTransporter
+
+ $server:=New object
+ $server.host:="imap.gmail.com" //Mandatory
+ $server.port:=993
+ $server.user:="4d@gmail.com"
+ $server.password:="XXXXXXXX"
+
+ //create transporter
+ $transporter:=IMAP New transporter($server)
+
+ //select mailbox
+ $boxInfo:=$transporter.selectBox("Inbox")
+
+ //get Email object with ID 1
+ $mail:=$transporter.getMail(1)
+```
+
+
+
+
+
+
+## .getMails()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R5|Added|
+
**.getMails**( *startMsg* : Integer ; *endMsg* : Integer { ; *options* : Object } ) : Object
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|ids |Collection|->|Collection of message ID|
+|startMsg|Integer|->|Sequence number of the first message|
+|endMsg |Integer|->|Sequence number of the last message|
+|options|Object|->|Message handling instructions|
+|Result|Object|<-|Object containing:
- a collection of [Email objects](EmailObjectClass.md#email-object) and
- a collection of IDs or numbers for missing messages, if any
|
+
+
+
+#### Description
+
+The `.getMails()` function returns an object containing a collection of `Email` objects.
+
+**First Syntax:**
+
+***.getMails( ids { ; options } ) -> result***
+
+The first syntax allows you to retrieve messages based on their IDs.
+
+In the *ids* parameter, pass a collection of IDs for the messages to return. You can get the IDs with [`.getMail()`](#getmail).
+
+The optional *options* parameter allows you to define the parts of the messages to be returned. See the **Options** table below for a description of the available properties.
+
+**Second syntax:**
+
+ ***.getMails( startMsg ; endMsg { ; options } ) -> result***
+
+The second syntax allows you to retrieve messages based on a sequential range. The values passed represent the position of the messages in the mailbox.
+
+In the *startMsg* parameter, pass an *integer* value corresponding to the number of the first message in a sequential range. If you pass a negative number (*startMsg* <= 0), the first message of the mailbox will be used as the beginning of the sequence.
+
+In the *endMsg* parameter, pass an *integer* value corresponding to the number of the last message to be included in a sequential range. If you pass a negative number (*endMsg* <= 0), the last message of the mailbox will be used as the end of the sequence.
+
+The optional *options* parameter allows you to define the parts of the messages to be returned.
+
+**Options**
+
+|Property | Type| Description |
+|---|---|---|
+|updateSeen | Boolean | If True, the specified messages are marked as "seen" in the mailbox. If False, the messages are not marked as "seen". Default value: True |
+|withBody | Boolean | Pass True to return the body of the specified messages. If False, only the message headers are returned. Default value: True|
+
+>* If no mailbox is selected with the [`.selectBox()`](#selectbox) command, an error is generated.
+>* If there is no open connection, `.getMails()` will open a connection the last mailbox specified with [`.selectBox()`](#selectbox).
+
+
+#### Result
+
+`.getMails()` returns an object containing the following collections:
+
+
+|Property | Type | Description |
+|---|---|---|
+|list |Collection |Collection of [`Email` objects](EmailObjectClass.md#email-object). If no Email objects are found, an empty collection is returned.|
+
+|notFound |Collection| Collection of:
- first syntax - previously passed message IDs that do not exist
- second syntax - sequence numbers of messages between startMsg and endMsg that do not exist
An empty collection is returned if all messages are found.|
+
+
+#### Example
+
+You want to retrieve the 20 most recent emails without changing their "seen" status:
+
+```4d
+ var $server,$boxInfo,$result : Object
+ var $transporter : 4D.IMAPTransporter
+
+ $server:=New object
+ $server.host:="imap.gmail.com" //Mandatory
+ $server.port:=993
+ $server.user:="4d@gmail.com"
+ $server.password:="XXXXXXXX"
+
+ //create transporter
+ $transporter:=IMAP New transporter($server)
+
+ //select mailbox
+ $boxInfo:=$transporter.selectBox("INBOX")
+
+ If($boxInfo.mailCount>0)
+ // retrieve the headers of the last 20 messages without marking them as read
+ $result:=$transporter.getMails($boxInfo.mailCount-20;$boxInfo.mailCount;\
+ New object("withBody";False;"updateSeen";False))
+ For each($mail;$result.list)
+ // ...
+ End for each
+ End if
+```
+
+
+
+
+
+
+## .getMIMEAsBlob()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added|
+
**.getMIMEAsBlob**( *msgID* : Text { ; *updateSeen* : Boolean } ) : Blob
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|msgNumber|Integer|-> |Sequence number of the message|
+|msgID|Text|-> |Unique ID of the message|
+|updateSeen|Boolean|->|If True, the message is marked "seen" in the mailbox. If False the message is left untouched.|
+|Result|BLOB|<-|Blob of the MIME string returned from the mail server|
+
+
+
+
+
+#### Description
+
+The `.getMIMEAsBlob()` function returns a BLOB containing the MIME contents for the message corresponding to the *msgNumber* or *msgID* in the mailbox designated by the `IMAP_transporter`.
+
+In the first parameter, you can pass either:
+
+* *msgNumber*, an *integer* value indicating the sequence number of the message to retrieve or
+* *msgID*, a *text* value indicating the unique ID of the message to retrieve.
+
+The optional *updateSeen* parameter allows you to specify if the message is marked as "seen" in the mailbox. You can pass:
+
+* **True** - to mark the message as "seen" (indicating the message has been read)
+* **False** - to leave the message's "seen" status untouched
+
+
+>* The function returns an empty BLOB if *msgNumber* or msgID* designates a non-existing message,
+>* If no mailbox is selected with the [`.selectBox()`](#selectbox) command, an error is generated,
+>* If there is no open connection, `.getMIMEAsBlob()` will open a connection the last mailbox specified with `.selectBox()`.
+
+
+#### Result
+
+`.getMIMEAsBlob()` returns a `BLOB` which can be archived in a database or converted to an [`Email` object](EmailObjectClass.md#email-object) with the `MAIL Convert from MIME` command.
+
+
+#### Example
+
+
+```4d
+ var $server : Object
+ var $boxInfo : Variant
+ var $blob : Blob
+ var $transporter : 4D.IMAPTransporter
+
+ $server:=New object
+ $server.host:="imap.gmail.com"
+ $server.port:=993
+ $server.user:="4d@gmail.com"
+ $server.password:="XXXXXXXX"
+
+ //create transporter
+ $transporter:=IMAP New transporter($server)
+
+ //select mailbox
+ $boxInfo:=$transporter.selectBox("Inbox")
+
+ //get BLOB
+ $blob:=$transporter.getMIMEAsBlob(1)
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## .move()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R5|Added|
+
**.move**( *allMsgs* : Integer ; *destinationBox* : Text ) : Object
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|msgsIDs|Collection|->|Collection of message unique IDs (strings)|
+|allMsgs|Integer|->|`IMAP all`: All messages in the selected mailbox|
+|destinationBox|Text|->|Mailbox to receive moved messages|
+|Result|Object|<-|Status of the move operation|
+
+
+
+#### Description
+
+The `.move()` function moves the messages defined by *msgsIDs* or *allMsgs* to the *destinationBox* on the IMAP server.
+
+You can pass:
+
+- in the *msgsIDs* parameter, a collection containing the unique IDs of the specific messages to move, or
+- in the *allMsgs* parameter, the `IMAP all` constant (integer) to move all messages in the selected mailbox.
+
+The *destinationBox* parameter allows you to pass a text value with the name of the mailbox where the messages will be moved.
+
+> This function is only supported by IMAP servers compliant with RFC [8474](https://tools.ietf.org/html/rfc8474).
+
+
+**Returned object**
+
+The function returns an object describing the IMAP status:
+
+|Property|| Type| Description|
+|---|---|---|---|
+|success||Boolean|True if the operation is successful, False otherwise
+|statusText || Text|Status message returned by the IMAP server, or last error returned in the 4D error stack |
+|errors ||Collection|4D error stack (not returned if a IMAP server response is received)|
+| |\[].errcode|Number| 4D error code|
+| |\[].message|Text|Description of the 4D error |
+| |\[].componentSignature|Text|Signature of the internal component which returned the error|
+
+
+
+
+#### Example 1
+
+To move a selection of messages:
+
+```4d
+ var $server;$boxInfo;$status : Object
+ var $mailIds : Collection
+ var $transporter : 4D.IMAPTransporter
+
+ $server:=New object
+ $server.host:="imap.gmail.com" //Mandatory
+ $server.port:=993
+ $server.user:="4d@gmail.com"
+ $server.password:="XXXXXXXX"
+
+ $transporter:=IMAP New transporter($server)
+
+ //select mailbox
+ $boxInfo:=$transporter.selectBox("inbox")
+
+ //get collection of message unique IDs
+ $mailIds:=$transporter.searchMails("subject \"4D new feature:\"")
+
+ // Move found messages from the current mailbox to the "documents" mailbox
+ $status:=$transporter.move($mailIds;"documents")
+```
+
+#### Example 2
+
+To move all messages in the current mailbox:
+
+
+```4d
+ var $server;$boxInfo;$status : Object
+ var $transporter : 4D.IMAPTransporter
+
+ $server:=New object
+ $server.host:="imap.gmail.com" //Mandatory
+ $server.port:=993
+ $server.user:="4d@gmail.com"
+ $server.password:="XXXXXXXX"
+
+ $transporter:=IMAP New transporter($server)
+
+ //select mailbox
+ $boxInfo:=$transporter.selectBox("inbox")
+
+ // move all messages in the current mailbox to the "documents" mailbox
+ $status:=$transporter.move(IMAP all;"documents")
+```
+
+
+
+
+
+
+## .numToID()
+
+History
+|Version|Changes|
+|---|---|
+|v18 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R6|Added|
+
**.removeFlags**( *msgIDs* : Text ; *keywords* : Object ) : Object
**.removeFlags**( *msgIDs* : Longint ; *keywords* : Object ) : Object
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|msgIDs|Collection|->|Collection of strings: Message unique IDs (text)
Text: Unique ID of a message
Longint (IMAP all): All messages in the selected mailbox|
+|keywords|Object|->|Keyword flags to remove|
+|Result|Object|<-|Status of the removeFlags operation|
+
+
+
+#### Description
+
+The `.removeFlags()` function removes flags from the `msgIDs` for the specified `keywords`.
+
+In the `msgIDs` parameter, you can pass either:
+
+* a *collection* containing the unique IDs of specific messages or
+* the unique ID (*text*) of a single message or
+* the following constant (*longint*) for all messages in the selected mailbox:
+
+ |Constant |Value |Comment|
+ |---|---|---|
+ |IMAP all |1 |Select all messages in the selected mailbox|
+
+The `keywords` parameter lets you pass an object with keyword values for specific flags to remove from `msgIDs`. You can pass any of the following keywords:
+
+|Parameter|Type|Description|
+|---|---|---|
+|$draft |Boolean |True to remove the "draft" flag from the message |
+|$seen |Boolean |True to remove the "seen" flag from the message|
+|$flagged |Boolean |True to remove the "flagged" flag from the message|
+|$answered |Boolean |True to remove the "answered" flag from the message|
+|$deleted |Boolean | True to remove the "deleted" flag from the message|
+
+Note that False values are ignored.
+
+
+**Returned object**
+
+The function returns an object describing the IMAP status:
+
+|Property|| Type| Description|
+|---|---|---|---|
+|success||Boolean|True if the operation is successful, False otherwise
+|statusText || Text|Status message returned by the IMAP server, or last error returned in the 4D error stack |
+|errors ||Collection|4D error stack (not returned if a IMAP server response is received)|
+| |\[].errcode|Number| 4D error code|
+| |\[].message|Text|Description of the 4D error |
+| |\[].componentSignature|Text|Signature of the internal component which returned the error|
+
+
+#### Example
+
+```4d
+var $options;$transporter;$boxInfo;$status : Object
+
+$options:=New object
+$options.host:="imap.gmail.com"
+$options.port:=993
+$options.user:="4d@gmail.com"
+$options.password:="xxxxx"
+
+// Create transporter
+$transporter:=IMAP New transporter($options)
+
+// Select mailbox
+$boxInfo:=$transporter.selectBox("INBOX")
+
+// Mark all messages from INBOX as unseen
+$flags:=New object
+$flags["$seen"]:=True
+$status:=$transporter.removeFlags(IMAP all;$flags)
+```
+
+
+
+
+
+## .renameBox()
+
+History
+|Version|Changes|
+|---|---|
+|v19|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R5|Added|
+History
+|Version|Changes|
+|---|---|
+|v18 R4|Added|
+History
+|Version|Changes|
+|---|---|
+|v19|Added|
+History
+|Version|Changes|
+|---|---|
+|v19|Added|
+ |
+|[](#disposition)
|
+|[](#getcontent)
|
+|[](#name)
|
+|[](#path)
|
+|[](#platformpath)
|
+|[](#type)
|
+
+
+## MAIL New attachment
+
+History
+|Version|Changes|
+|---|---|
+|v19 R2|Accepts 4D.File, 4D.ZipFile, 4D.Blob
+
**MAIL New attachment**( *zipFile* : 4D.ZipFile { ; *name* : Text {; *cid* : Text{ ; *type* : Text { ; *disposition* :Text } } } } ) : 4D.MailAttachment
**MAIL New attachment**( *blob* : 4D.Blob { ; *name* : Text {; *cid* : Text{ ; *type* : Text { ; *disposition* :Text } } } } ) : 4D.MailAttachment
**MAIL New attachment**( *path* : Text { ; *name* : Text {; *cid* : Text{ ; *type* : Text { ; *disposition* :Text } } } } ) : 4D.MailAttachment
+
+
+
+|Parameter|Type||Description|
+|---------|--- |:---:|------|
+|file|4D.File|->|Attachment file|
+|zipFile|4D.ZipFile|->|Attachment Zipfile|
+|blob|4D.Blob|->|BLOB containing the attachment|
+|path|Text|->|Path of the attachment file|
+|name|Text|->|Name + extension used by the mail client to designate the attachment|
+|cid|Text|->|ID of attachment (HTML messages only), or " " if no cid is required|
+|type|Text|->|Value of the content-type header|
+|disposition|Text|->|Value of the content-disposition header: "inline" or "attachment".|
+|Result|4D.MailAttachment|<-|Attachment object|
+
+
+
+#### Description
+
+The `MAIL New attachment` command allows you to create an attachment object that you can add to an [Email object](EmailObjectClass.md#email-object).
+
+To define the attachment, you can use:
+
+- a *file*, pass a `4D.File` object containing the attachment file.
+- a *zipfile*, pass a `4D.ZipFile` object containing the attachment file.
+- a *blob*, pass a `4D.Blob` object containing the attachment itself.
+- a *path*, pass a **text** value containing the path of the attachment file, expressed with the system syntax. You can pass a full path name or a simple file name (in which case 4D will search for the file in the same directory as the project file).
+
+The optional *name* parameter lets you pass the name and extension to be used by the mail client to designate the attachment. If *name* is omitted and:
+
+* you passed a file path, the name and extension of the file is used,
+* you passed a BLOB, a random name without extension is automatically generated.
+
+The optional *cid* parameter lets you pass an internal ID for the attachment. This ID is the value of the `Content-Id` header, it will be used in HTML messages only. The cid associates the attachment with a reference defined in the message body using an HTML tag such as `\
`. This means that the contents of the attachment (e.g., a picture) should be displayed within the message on the mail client. The final result may vary depending on the mail client. You can pass an empty string in *cid* if you do not want to use this parameter.
+
+You can use the optional *type* parameter to explicitly set the `content-type` of the attachment file. For example, you can pass a string defining a MIME type ("video/mpeg"). This content-type value will be set for the attachment, regardless of its extension. For more information about MIME types, please refer to the [MIME type page on Wikipedia](https://en.wikipedia.org/wiki/MIME).
+
+By default, if the *type* parameter is omitted or contains an empty string, the `content-type` of the attachment file is based on its extension. The following rules are applied for the main MIME types:
+
+|Extension| Content Type|
+|---|---|
+|jpg, jpeg| image/jpeg|
+|png| image/png|
+|gif| image/gif|
+|pdf| application/pdf|
+|doc| application/msword|
+|xls| application/vnd.ms-excel|
+|ppt| application/vnd.ms-powerpoint|
+|zip| application/zip|
+|gz| application/gzip|
+|json| application/json|
+|js| application/javascript|
+|ps| application/postscript|
+|xml| application/xml|
+|htm, html| text/html|
+|mp3| audio/mpeg|
+|*other*| application/octet-stream|
+
+The optional *disposition* parameter lets you pass the `content-disposition` header of the attachment. You can pass one of the following constants from the "Mail" constant theme:
+
+|Constant|Value|Comment|
+|---|---|---|
+|mail disposition attachment|"attachment"|Set the Content-disposition header value to "attachment", which means that the attachment file must be provided as a link in the message.|
+|mail disposition inline|"inline"|Set the Content-disposition header value to "inline", which means that the attachment must be rendered within the message contents, at the "cid" location. The rendering depends on the mail client.|
+
+By default, if the *disposition* parameter is omitted:
+
+* if the *cid* parameter is used, the `Content-disposition` header is set to "inline",
+* if the *cid* parameter is not passed or empty, the `Content-disposition` header is set to "attachment".
+
+#### Example 1
+
+You want to send an email with a user-selected file as an attachment and an image embedded in the HTML body:
+
+```4d
+$doc:=Select document("";"*";"Please select a file to attach";0)
+If (OK=1) //If a document was selected
+
+C_OBJECT($email;$server;$transporter)
+
+$server:=New object
+$server.host:="smtp.mail.com"
+$server.user:="test_user@mail.com"
+$server.password:="p@ssw@rd"
+$transporter:=SMTP New transporter($server)
+
+$email:=New object
+$email.from:="test_user@mail.com"
+$email.to:="test_user@mail.com"
+$email.subject:="This is a test message with attachments"
+
+//add a link to download file
+$email.attachments:=New collection(MAIL New attachment(Document))
+//insert an inline picture (use a cid)
+$email.attachments[1]:=MAIL New attachment("c:\\Pictures\\4D.jpg";"";"4D")
+
+$email.htmlBody:=""+\
+"
Hello World!"+\
+"
"+\
+""+\
+""+\
+"