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

From Serious Documentation
Jump to: navigation, search
(→‎Node: Variable)
 
(2 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
=== Node: [[SHIP:Node|Variable]] ===
 
=== Node: [[SHIP:Node|Variable]] ===
 
{{PropTableStart|}}
 
{{PropTableStart|}}
−
|<onlyinclude>{{Prop|variable|varid}}||{{DataType|Short}}|| Unique in-{{Prop|variable|context}} Variable ID for a {{Prop|variable|persistent}} registry variable.</onlyinclude>
+
|<onlyinclude>{{Prop|variable|varid}}**||{{DataType|Short}}|| Unique in-{{Prop|variable|context}} Variable ID for a {{Prop|variable|persistent}} registry variable.</onlyinclude>
 
|}
 
|}
 
Variables marked {{Prop|variable|persistent}} must be stored in the registry in a specific name space, or {{Prop|variable|context}}.  Within that context, each variable must be assigned a unique ID, or {{Prop|variable|varid}}.
 
Variables marked {{Prop|variable|persistent}} must be stored in the registry in a specific name space, or {{Prop|variable|context}}.  Within that context, each variable must be assigned a unique ID, or {{Prop|variable|varid}}.
Line 10: Line 10:
  
 
See the related properties {{Prop|variable|persistent}}, {{Prop|variable|context}}, 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|context}}, and {{Prop|variable|varversion}}. In order to make a variable {{Prop|variable|persistent}}, you must set these 3 related properties as well.
 +
 +
<nowiki>**</nowiki>The {{Prop|variable|varid}} property can only be set in [[SHIPTide]].
 +
=== Examples ===
 +
 +
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.
 +
 +
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" 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
 +
|}
 +
 +
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
varid** Short Unique in-context Variable ID for a persistent registry variable.

Variables marked persistent must be stored in the registry in a specific name space, or context. Within that context, each variable must be assigned a unique ID, or varid.

A varid is a 16 bit number, with 0x0000 and 0xFFFF reserved for Serious use. Make sure all your variable IDs are unique.

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, context, and varversion. In order to make a variable persistent, you must set these 3 related properties as well.

**The varid 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:varid&oldid=4312"