v18.0 release develop into master

docs/REST/$asArray.md

@@ -0,0 +1,124 @@
+---
+id: asArray
+title: $asArray 
+---
+
+
+Returns the result of a query in an array (i.e. a collection) instead of a JSON object.
+
+
+## Description   
+
+If you want to receive the response in an array, you just have to add `$asArray` to your REST request (*e.g.*, `$asArray=true`).
+
+## Example  
+Here is an example or how to receive the response in an array.
+
+ `GET  /rest/Company/?$filter="name begin a"&$top=3&$asArray=true`
+
+**Response**:
+
+````
+[
+	{
+		"__KEY": 15,
+		"__STAMP": 0,
+		"ID": 15,
+		"name": "Alpha North Yellow",
+		"creationDate": "!!0000-00-00!!",
+		"revenues": 82000000,
+		"extra": null,
+		"comments": "",
+		"__GlobalStamp": 0
+	},
+	{
+		"__KEY": 34,
+		"__STAMP": 0,
+		"ID": 34,
+		"name": "Astral Partner November",
+		"creationDate": "!!0000-00-00!!",
+		"revenues": 90000000,
+		"extra": null,
+		"comments": "",
+		"__GlobalStamp": 0
+	},
+	{
+		"__KEY": 47,
+		"__STAMP": 0,
+		"ID": 47,
+		"name": "Audio Production Uniform",
+		"creationDate": "!!0000-00-00!!",
+		"revenues": 28000000,
+		"extra": null,
+		"comments": "",
+		"__GlobalStamp": 0
+	}
+]
+````
+
+The same data in its default JSON format:
+
+````
+{
+	"__entityModel": "Company",
+	"__GlobalStamp": 50,
+	"__COUNT": 52,
+	"__FIRST": 0,
+	"__ENTITIES": [
+		{
+			"__KEY": "15",
+			"__TIMESTAMP": "2018-03-28T14:38:07.434Z",
+			"__STAMP": 0,
+			"ID": 15,
+			"name": "Alpha North Yellow",
+			"creationDate": "0!0!0",
+			"revenues": 82000000,
+			"extra": null,
+			"comments": "",
+			"__GlobalStamp": 0,
+			"employees": {
+				"__deferred": {
+					"uri": "/rest/Company(15)/employees?$expand=employees"
+				}
+			}
+		},
+		{
+			"__KEY": "34",
+			"__TIMESTAMP": "2018-03-28T14:38:07.439Z",
+			"__STAMP": 0,
+			"ID": 34,
+			"name": "Astral Partner November",
+			"creationDate": "0!0!0",
+			"revenues": 90000000,
+			"extra": null,
+			"comments": "",
+			"__GlobalStamp": 0,
+			"employees": {
+				"__deferred": {
+					"uri": "/rest/Company(34)/employees?$expand=employees"
+				}
+			}
+		},
+		{
+			"__KEY": "47",
+			"__TIMESTAMP": "2018-03-28T14:38:07.443Z",
+			"__STAMP": 0,
+			"ID": 47,
+			"name": "Audio Production Uniform",
+			"creationDate": "0!0!0",
+			"revenues": 28000000,
+			"extra": null,
+			"comments": "",
+			"__GlobalStamp": 0,
+			"employees": {
+				"__deferred": {
+					"uri": "/rest/Company(47)/employees?$expand=employees"
+				}
+			}
+		}
+	],
+"__SENT": 3
+}
+````
+
+

docs/REST/$atomic_$atonce.md

@@ -0,0 +1,99 @@
+---
+id: atomic_$atonce
+title: $atomic/$atonce 
+---
+
+
+Allows the actions in the REST request to be in a transaction. If there are no errors, the transaction is validated. Otherwise, the transaction is cancelled.
+
+
+## Description   
+When you have multiple actions together, you can use `$atomic/$atonce` to make sure that none of the actions are completed if one of them fails. You can use either `$atomic` or `$atonce`.
+
+
+## Example  
+We call the following REST request in a transaction.
+
+ `POST  /rest/Employee?$method=update&$atomic=true`
+
+**POST data**:
+
+````
+[
+{
+    "__KEY": "1",
+    "__STAMP": 5,
+    "salary": 45000
+},
+{
+    "__KEY": "2",
+    "__STAMP": 10,
+    "salary": 99000
+}
+]
+````
+
+We get the following error in the second entity and therefore the first entity is not saved either:
+
+````
+{
+    "__ENTITIES": [
+        {
+            "__KEY": "1", 
+            "__STAMP": 5, 
+            "uri": "http://127.0.0.1:8081/rest/Employee(1)", 
+            "ID": 1, 
+            "firstName": "John", 
+            "lastName": "Smith", 
+            "fullName": "John Smith", 
+            "gender": false, 
+            "telephone": "4085551111", 
+            "salary": 45000, 
+            "employerName": "Adobe", 
+            "employer": {
+                "__deferred": {
+                    "uri": "http://127.0.0.1:8081/rest/Company(1)", 
+                    "__KEY": "1"
+                }
+            }
+        }, 
+        {
+            "__KEY": "2", 
+            "__STAMP": 2, 
+            "ID": 2, 
+            "firstName": "Paula", 
+            "lastName": "Miller", 
+            "fullName": "Paula Miller", 
+            "telephone": "4085559999", 
+            "salary": 36000, 
+            "employerName": "Adobe", 
+            "employer": {
+                "__deferred": {
+                    "uri": "http://127.0.0.1:8081/rest/Company(1)", 
+                    "__KEY": "1"
+                }
+            }, 
+            "__ERROR": [
+                {
+                    "message": "Value cannot be greater than 60000", 
+                    "componentSignature": "dbmg", 
+                    "errCode": 1569
+                }, 
+                {
+                    "message": "Entity fails validation", 
+                    "componentSignature": "dbmg", 
+                    "errCode": 1570
+                }, 
+                {
+                    "message": "The entity# 1 of the datastore class \"Employee\" cannot be saved", 
+                    "componentSignature": "dbmg", 
+                    "errCode": 1517
+                }
+            ]
+        }
+    ]
+}
+````
+
+
+>Even though the salary for the first entity has a value of 45000, this value was not saved to the server and the *timestamp (__STAMP)* was not modified either. If we reload the entity, we will see the previous value.

docs/REST/$attributes.md

@@ -0,0 +1,106 @@
+---
+id: attributes
+title: $attributes 
+---
+
+Allows selecting the related attribute(s) to get from the dataclass (*e.g.*, `Company(1)?$attributes=employees.lastname` or `Employee?$attributes=employer.name`).
+
+
+## Description   
+
+When you have relation attributes in a dataclass, use `$attributes` to define the path of attributes whose values you want to get for the related entity or entities.
+
+You can apply `$attributes` to an entity (*e.g.*, People(1)) or an entity selection (*e.g.*, People/$entityset/0AF4679A5C394746BFEB68D2162A19FF) .
+
+
+- If `$attributes` is not specified in a query, or if the "*" value is passed, all available attributes are extracted. **Related entity** attributes are extracted with the simple form: an object with property `__KEY` (primary key). **Related entities** attributes are not extracted.
+
+- If `$attributes` is specified for **related entity** attributes:
+	- `$attributes=relatedEntity`: the related entity is returned with simple form (deferred __KEY property (primary key)).
+	- `$attributes=relatedEntity.*`: all the attributes of the related entity are returned
+	- `$attributes=relatedEntity.attributePath1, relatedEntity.attributePath2, ...`: only those attributes of the related entity are returned.
+
+
+- If `$attributes` is specified for **related entities** attributes:
+	- `$attributes=relatedEntities.*`: all the properties of all the related entities are returned
+	- `$attributes=relatedEntities.attributePath1, relatedEntities.attributePath2, ...`: only those attributes of the related entities are returned.
+
+
+
+## Example with related entities
+
+If we pass the following REST request for our Company datastore class (which has a relation attribute "employees"):
+
+ `GET  /rest/Company(1)/?$attributes=employees.lastname`
+
+**Response**:
+
+```
+{
+    "__entityModel": "Company",
+    "__KEY": "1",  
+    "__TIMESTAMP": "2018-04-25T14:41:16.237Z",
+    "__STAMP": 2,
+    "employees": {
+		"__ENTITYSET": "/rest/Company(1)/employees?$expand=employees",
+		"__GlobalStamp": 50,
+		"__COUNT": 135,
+		"__FIRST": 0,
+		"__ENTITIES": [
+			{
+				"__KEY": "1",
+				"__TIMESTAMP": "2019-12-01T20:18:26.046Z",
+				"__STAMP": 5,
+				"lastname": "ESSEAL"
+			},
+			{
+				"__KEY": "2",
+				"__TIMESTAMP": "2019-12-04T10:58:42.542Z",
+				"__STAMP": 6,
+				"lastname": "JONES"
+			},
+			...
+    }
+}
+```
+
+If you want to get all attributes from employees:
+
+ `GET  /rest/Company(1)/?$attributes=employees.*`
+
+If you want to get last name and job name attributes from employees:
+
+ `GET  /rest/Company(1)/?$attributes=employees.lastname,employees.jobname`
+
+
+## Example with related entity
+
+If we pass the following REST request for our Employee datastore class (which has several relation attributes, including "employer"):
+
+
+ `GET  /rest/Employee(1)?$attributes=employer.name`
+
+**Response**:
+
+```
+{
+	"__entityModel": "Employee",
+	"__KEY": "1",
+	"__TIMESTAMP": "2019-12-01T20:18:26.046Z",
+	"__STAMP": 5,
+	"employer": {
+		"__KEY": "1",
+		"__TIMESTAMP": "2018-04-25T14:41:16.237Z",
+		"__STAMP": 0,
+		"name": "Adobe"
+	}
+}
+```
+
+If you want to get all attributes of the employer:
+
+ `GET  /rest/Employee(1)?$attributes=employer.*`
+
+If you want to get the last names of all employees of the employer:
+
+ `GET  /rest/Employee(1)?$attributes=employer.employees.lastname`

docs/REST/$binary.md

@@ -0,0 +1,21 @@
+---
+id: binary
+title: $binary 
+---
+
+Pass "true" to save the BLOB as a document (must also pass `$expand={blobAttributeName}`)
+
+## Description   
+
+`$binary` allows you to save the BLOB as a document.  You must also use the [`$expand`]($expand.md) command in conjunction with it.
+
+When you make the following request:
+
+```
+GET  /rest/Company(11)/blobAtt?$binary=true&$expand=blobAtt
+```
+
+You will be asked where to save the BLOB to disk:
+
+![](assets/en/REST/binary.png)
+