Difference between revisions of "SHIP:Property:variable:context"

From Serious Documentation
Jump to: navigation, search
(→‎Node: Variable)
 
(One intermediate revision by one other user not shown)
Line 9: Line 9:
 
See the related properties {{Prop|variable|persistent}}, {{Prop|variable|varid}}, and {{Prop|variable|varversion}}. In order to make a variable {{Prop|variable|persistent}}, you must set these 3 related properties as well.
 
See the related properties {{Prop|variable|persistent}}, {{Prop|variable|varid}}, and {{Prop|variable|varversion}}. In order to make a variable {{Prop|variable|persistent}}, you must set these 3 related properties as well.
  
−
Here's how to make a variable persistent:
+
<nowiki>**</nowiki>The {{Prop|variable|context}} property can only be set in [[SHIPTide]].
−
* go into the property sheet for the variable in SHIPTide
+
=== Examples ===
−
* turn the persistent property to true
 
−
* set the context to 0x02...0xFD (your choice) - this is the name space for your application. This way you can have 2 different apps on the unit or more and each has its own set of persistent variables that do not conflict as long as they use different context IDs
 
−
* assign the variable a unique variable id (varid) (e.g. 0x0001, 0x0002, ...) within your context
 
−
* assign a variable version (varversion) to the variable (eg. 0x01) -- this is used if you ever need to upgrade a variable to a different version)
 
  
−
Now, whenever you change the variable it will write-thru automatically to the registry in serial flash. Whenever you boot, it will retrieve the value from serial flash.
+
The following example shows three global [[SHIP:Node|Variable]] from a GUI, all defined directly under the display node d0, each with a different name and data type.  Note how the {{Prop|variable|context}} is the same across them (<code>0x02</code>. The {{Prop|variable|varversion}} is all <code>0x01</code>, which is the normal case.
  
−
Here's an example in the attached screen shot:
+
What distinguishes them is the unique ID ({{Prop|variable|varid}}) assigned to each within the {{Prop|variable|context}} <code>0x02</code>.  The <nowiki>[</nowiki>{{Prop|variable|context}}+{{Prop|variable|varversion}}+{{Prop|variable|varid}}<nowiki>]</nowiki> values form a unique 32-bit value that is the lookup key in the SIM's persistent storage registry, so it is critical that there is no overlapping combinations of <nowiki>[</nowiki>{{Prop|variable|context}}+{{Prop|variable|varversion}}+{{Prop|variable|varid}}<nowiki>]</nowiki> in your GUI.
  
−
{| class="wikitable" style="margin: 1em auto 1em auto;"  
+
{| class="wikitable" margin: 1em auto 1em auto;"
−
|[[Image:SHIPPersistentVariable.png|200px|center|SHIP Persistent Variable Example]]
+
! Name
 +
! Type
 +
! Value
 +
! Context
 +
! Version
 +
! ID
 +
|-
 +
|d0.myStringVar1||{{DataType|String}}||Hello||0x02||0x01||0x0001
 +
|-
 +
|d0.myByteVar1||{{DataType|Byte}}||12||0x02||0x01||0x0002
 +
|-
 +
|d0.myIntVar1||{{DataType|Integer}}||-456||0x02||0x01||0x0003
 
|}
 
|}
  
−
<nowiki>**</nowiki>The {{Prop|variable|context}} property can only be set in [[SHIPTide]].
+
The following example adds a fourth global [[SHIP:Node|Variable]], <code>d0.myCrossGUIIntVar1</code> with a different context (<code>0x80</code>).  Even though it has {{Prop|variable|varid}} <code>0x0001</code> that does not conflict with <code>d0.myStringVar1</code> because they are in a different {{Prop|variable|context}} (i.e. namespace). 
 +
 
 +
This is very useful if you have several different GUIs that may be installed on the hardware depending on the customer or machine.  You can declare a set of common {{Prop|variable|persistent}} variables that exist and are available across all your different GUIs in one {{Prop|variable|context}} (e.g. the <code>myCrossGUIIntVar1</code> below in {{Prop|variable|context}} <code>0x80</code>).  Then you can assign a set of different specific GUI-locals contexts for each of your GUIs.  For example, GUI#1 could have local GUI {{Prop|variable|context}} variables in context <code>0x02</code> such as the three shown below, and then a different GUI#2 could use {{Prop|variable|context}} <code>0x03</code> for its local specific persistent variables, and so on.
 +
{| class="wikitable" margin: 1em auto 1em auto;"
 +
! Name
 +
! Type
 +
! Value
 +
! Context
 +
! Version
 +
! ID
 +
|-
 +
|d0.myStringVar1||{{DataType|String}}||Hello||0x02||0x01||0x0001
 +
|-
 +
|d0.myByteVar1||{{DataType|Byte}}||12||0x02||0x01||0x0002
 +
|-
 +
|d0.myIntVar1||{{DataType|Integer}}||-456||0x02||0x01||0x0003
 +
|-
 +
|d0.myCrossGUIIntVar1||{{DataType|Integer}}||7||0x80||0x01||0x0001
 +
|}

Latest revision as of 08:56, 23 July 2014

Node: Variable

Property Data Type Description
context** Byte The name space for this persistent variable on this SIM.

Variables marked persistent must be stored in the registry in a specific name space, or context. A context is a simple 8 bit number, with 0x00 and 0xFF reserved for Serious use. Typically, you'll use context 0x01. If you have multiple GUIs loading on the same physical SIM, you may assign each GUI's variables a different context -- or you can share persistent variables selectively by having some variables share the same context.

Variables are stored by a combined unique value of context + varid + varversion. A persistent variable in one GUI with context 0x01, varid 0x0001, varversion 0x01 is a completely different stored variable than one with a different (say, 0x02) context.

See the related properties persistent, varid, and varversion. In order to make a variable persistent, you must set these 3 related properties as well.

**The context property can only be set in SHIPTide.

Examples

The following example shows three global Variable from a GUI, all defined directly under the display node d0, each with a different name and data type. Note how the context is the same across them (0x02. The varversion is all 0x01, which is the normal case.

What distinguishes them is the unique ID (varid) assigned to each within the context 0x02. The [context+varversion+varid] values form a unique 32-bit value that is the lookup key in the SIM's persistent storage registry, so it is critical that there is no overlapping combinations of [context+varversion+varid] in your GUI.

Name Type Value Context Version ID
d0.myStringVar1 String Hello 0x02 0x01 0x0001
d0.myByteVar1 Byte 12 0x02 0x01 0x0002
d0.myIntVar1 Integer -456 0x02 0x01 0x0003

The following example adds a fourth global Variable, d0.myCrossGUIIntVar1 with a different context (0x80). Even though it has varid 0x0001 that does not conflict with d0.myStringVar1 because they are in a different context (i.e. namespace).

This is very useful if you have several different GUIs that may be installed on the hardware depending on the customer or machine. You can declare a set of common persistent variables that exist and are available across all your different GUIs in one context (e.g. the myCrossGUIIntVar1 below in context 0x80). Then you can assign a set of different specific GUI-locals contexts for each of your GUIs. For example, GUI#1 could have local GUI context variables in context 0x02 such as the three shown below, and then a different GUI#2 could use context 0x03 for its local specific persistent variables, and so on.

Name Type Value Context Version ID
d0.myStringVar1 String Hello 0x02 0x01 0x0001
d0.myByteVar1 Byte 12 0x02 0x01 0x0002
d0.myIntVar1 Integer -456 0x02 0x01 0x0003
d0.myCrossGUIIntVar1 Integer 7 0x80 0x01 0x0001
Retrieved from "https://techref.myserious.com/index.php?title=SHIP:Property:variable:context&oldid=4311"