PROTOCOL.md: extend doc for record lock API

doc/PROTOCOL.md

@@ -318,7 +318,7 @@ Server Response
 :	The response contains a [Minimal Response].
 
 
-### Record(s) delete
+### Record delete
 
 Request the deletion of the record identified by the SIP. The SIP might contain a SIP_TABLE and/or a SIP_FORM.
 If both are specified, SIP_FORM will be taken. With SIP_FORM, the tableName is derived from the form. 
@@ -353,6 +353,43 @@ URL Parameters
 Server Response
 :   The response contains at least a [Minimal Response]. In addition, a [Typeahead dict],
 
+### Record lock
+
+Request, extend or release a lock for a record, identified by the SIP. The SIP contain a SIP_FORM and a SIP_R (record id).
+To detect record change at time of 'record lock' or 'record save', a MD5 hash is provided from the server
+and needs to pass back to dirty.php as well.
+
+Request
+:	api/dirty.php
+
+Request Method
+:	GET
+
+URL Parameters
+:	`s=<SIP>`   (form, r)
+:  `action=lock`, `action=extend`, `action=release>`
+:  `recordHashMd5=<value of hidden form element 'recordHashMd5'>`
+
+Server Response
+:	The response contains an [Lock Response].
+
+### Lock Response
+
+Asynchronous request (read AJAX) initiated by the Client receive a
+JSON Response from the server (extended [Minimal Response]) containing:
+
+	{
+		"status": "success"|"error"|"conflict"|"conflict_allow_force",
+		"message": "<message>"
+    }
+   
+`status` indicates how the request has been fullfiled by the server. 
+On`"success"`, the Client display nothing to the user. 
+On one of`"error"|"conflict"|"conflict_allow_force"` the Client must display `"<message>"` to the user.
+On `"conflict"` the Client opens the alert as modal dialog (user can't change anything on the form) with a 'reload current
+form' button.
+On `"conflict_allow_force"` the Client opens the alert non-modal (default).
+
 ## Glossary
 
 SIP