The REST SET statement modified objects in the actual JSON document tree or adds new key / value pairs to the document. The statement starts with the REST SET keywords followed by one or more OBJECT ... VALUE or OBJECT ... QUOTED clauses:
Each object definition starts with the OBJECT keyword, followed by the object location definition. The object location definition may be concatenated from multiple quoted strings and sat-nms driver variables. Section object paths in chapter REST I/O functions describes object location definitions more detailed.
Within the REST SET statement, each object is newly created with all its parent objects if it does not yet exist in the document. This includes conditional definitions for array elements. If an object already exists in the document, its value will be overwritten by the value specified later in this OBJECT clause.
The object location definition is terminated by the VALUE keyword which starts the definition of the value which shall be assigned to this object. Alternatively, QUOTED may be used instead of VALUE, this is used for textual values which shall be enclosed in double quotes in the JSON text.
The value definition itself is much like writing a command using the PRINT command:
| "text" | Plain text, enclosed in double quotes, is added to the output buffer as it is. |
| ascii-code | A decimal number is interpreted as the ASCII code of a single character to output. You may use this to send special characters like carriage-return or line-feed to the device. |
| XLT table | The XLT keyword, followed by the name of an already defined table, tells the driver to translate the next variable value which shall be printed through this translation table. Chapter Using conversion tables gives more information about tables in general. |
| FMT "..." | The FMT keyword, followed by a format description in double quotes, tells the device driver to format the next variable following the format description given. FMT is used to format numeric variables into the representation the device expects in it's remote control command. |
A format description consists of the following elements:
| format character | description |
|---|---|
| d b x X f | The first letter of the format description defines the general number representation: d (decimal), b (binary), x (hex, lower case), X (hex, upper case) or f (floating point) |
| + | If the + option is given, the number is preceded by a +/- character even if it is positive. Together with the 0 option below, the sign appears as an additional character at the first column, hence the field width is increased by one on this case. |
| 0 | If the 0 option is given, the field is padded up with zeroes instead of spaces. |
| 1 .. 99 | Here follows a one or two digit field width. The field width is the total number of characters the formatted number occupies including the padding characters. If there are more digits needed to show a number correctly, the field with is enlarged automatically. Specifying a field width 1 disables the right orientation in a fixed width completely. This specially is useful for floating point numbers where only the number of fraction digits shall be fixed, not the complete field width. |
| . | For floating point formats the dot separates the precision from the field width. |
| 0 .. 9 | The dot is followed by a one digit specification of the number of fraction digits which shall be printed. The dot and fraction digits specification is valid only with the floating point format. |
INTEGER variables may be printed using a floating point format, and FLOAT variables may be printed with a d or x format likewise. With FLOAT variables you should format in any case as internal precision/rounding problems may cause unpredictable results when floating point values are printed unformatted.
| OFFSET o | The OFFSET keyword, followed by the (floating point) offset value, tells the driver to add the offset value to the next variable before it is printed. |
| SCALE s | The SCALE keyword, followed by the (floating point) scale factor, tells the driver to multiply the next variable with the scale factor before it is printed |
| FUNCTION "name" | The FUNCTION keyword, followed by the name of the function as a quoted string, tells the driver to apply this function to the next variable before it is printed. The function name is extended by appending .txt to achieve the file name to read for the function definition. Chapter Function tables in I/O functions gives an extensive description about functions an how they are used. |
| variable-name | A variable name tells the driver to print the value stored in this variable. Usually the commanded value is used rather than the value which has been read back from the device. If, however, there has been never a value commanded, or if this variable is a read only variable, the value recently read from the device is used. |
Before the variable is printed to the output buffer, any XLT, FMT, OFFSET or SCALE operations which have been specified are applied. This happens in a fixed order:
SCALE operation has been specified, this is done first.SCALE operation is followed by an OFFSET addition.XLT operation has been specified.This scheme applies to numeric (INTEGER, HEX, FLOAT) and to text type variables as well. As soon as a SCALE, OFFSET or FMT keyword is present in front of a variable, this gets converted to a floating point number. Strings which cannot be converted give a zero value.
Example
REST CLEAR
REST SET OBJECT "/settings/frequency" VALUE FMT "f1.3" tx.frequency
REST SET OBJECT "/settings/fec" QUOTED XLT "tFec" tx.fec
TRANSACT "PATCH /api/v1/modulators?slot=2"Value quoting
In JSON, textual values are enclosed in double quotes, numeric and boolean values are not. The sat-nms Software does this automatically by looking at the value to set if this is a boolean, a number or a text. This may fail, if the device expects a number enclosed in double quotes.
To cope with this, the REST SET statement lets you force the usage of quotes in several ways:
QUOTED keyword instead if VALUE. The value will be forced to be set in double quotes when added to the document. This way produces better readable code than putting the quote characters explicitly in the sequence of operands after VALUE.Conditional execution
By default a VALUE or QUOTED clause in the REST SET statement causes the JSON document only to be modified if
This behavior protects the JSON document content from unwanted changes if e.g. only one parameter shall be changed but the REST SET statement contains the OBJECT .. VALUE pairs of all parameters in this group.
You can force values to be written regardless of the conditions described above by introducing the keyword FORCE directly after the VALUE or QUOTED keywords.
Object deletion
When used with DELETE, REST SET deletes the JSON object specified in the OBJECT clause and all of it's child objects.
Parent objects are removed as well if they become empty after deletion of the specified object. Please note, that array elements may still not be empty - even if all known child elements of the array element have been deleted. In this case the array element is not automatically removed, must be deleted explicitly by another REST SET ... DELETE statement.