The text says:

7.3 XML Examples
Examples of the GEMS XML messages are available on the OMG website at http://www.omg.org/space. Navigate to
the GEMS specific page and look for GEMS Examples.

I can't find any such examples! (humble apologies if they are there but I have looked)

GEMS examples are available

The GEMS 1.5 Revision Task Force met today (June 24, 2020) and we agreed to close this ticket since the examples are available per the 07/May/20 comment in the original Jira ticket as follows:

“The examples can be found by browsing to that same OMG page at https://www.omg.org/space then click on the link "GEMS™ (Ground Equipment Monitoring Service™)" which takes you to http://www.omgwiki.org/space/doku.php?id=gems that has a link to the examples at http://www.omgwiki.org/space/doku.php?id=gems_examples”

The spec currently allows arrays, parameters sets, and arrays of parameter sets. These compound types can make for an API that's difficult to use. Specifically, if you want to modify a single member of a parameter set, you have to read it, deserialize it, modify part of it, re-serialize it, and write it back. This isn't wildly difficult, but I believe it's enough for a customer to complain about usability. This operation is particularly annoying in the case of arrays of parameter sets. Furthermore, the read/modify/write operation isn't atomic, and could result in race conditions that revert a simultaneous change.

I'd like to suggest that we extend the PIM to allow "leaf" values of compound types to be referenced directly. E.g., array elements and parameter set members could be referenced under the ASCII PSM using the following parameter names:

Array element: myArray/3
Set member: myParamSet/memberName
Array of sets: myArrayOfSets/5/memberName

...with a corresponding scheme for the XML PSM. This would require adding the forward slash as a reserved word that should not be used in parameter names, along with "|GEMS" and "|END".

Defer to GEMS 2.0 RFP

The GEMS 1.5 Revision Task Force met today (June 24, 2020) and we agreed to defer this ticket to the GEMS 2.0 RFP where we can discuss it in the context of an additional PSM, i.e. JSON over REST.

The spec currently allows arrays, parameters sets, and arrays of parameter sets. These compound types can make for an API that's difficult to use. Specifically, if you want to modify a single member of a parameter set, you have to read it, deserialize it, modify part of it, re-serialize it, and write it back. This isn't wildly difficult, but I believe it's enough for a customer to complain about usability. This operation is particularly annoying in the case of arrays of parameter sets. Furthermore, the read/modify/write operation isn't atomic, and could result in race conditions that revert a simultaneous change.

I'd like to suggest that we extend the PIM to allow "leaf" values of compound types to be referenced directly. E.g., array elements and parameter set members could be referenced under the ASCII PSM using the following parameter names:

Array element: myArray/3
Set member: myParamSet/memberName
Array of sets: myArrayOfSets/5/memberName

...with a corresponding scheme for the XML PSM. This would require adding the forward slash as a reserved word that should not be used in parameter names, along with "|GEMS" and "|END".

Extend PIM to allow leaf node access

I propose we defer this one. There are details that should be considered.

Some GEMS target parameters are not writable. It would be useful to know which ones are read-only when using GEMS to construct a GUI.

Add readonly to the parameter definitions

Add this as an optional attribute with a default of false for backwards compatibility.

In Table 8.2
"Message Length" has a "Range of Values" specified as "000074-999999". We took this as the minimum possible message length to the maximum possible message length. Which, given our experience, is not true. We have encountered several instances with production hardware (Amergint & RTLogic) where the message length was fewer than 74 bytes.

I personally don’t care if OMG decides to list a minimum length; I just want the documented "Range of Values" to reflect reality. In the case OMG doesn’t want to specify a minimum length I would suggest the range value would be listed as "000000-999999" in the spec. Listing a range of "000000" could be problematic/confusing as well, "000000" would never be a valid either... So... I will let you standards people work this one out.

Range of values in the message length

Change the range of values. Since the standard header may change, it makes sense to not specify the minimum length. That will make maintenance of the specification easier.

Add 'units' as a parameter constraint (not really a constraint bu that's the section in the doc).
Units are a string containing the unit of measurement such as mm, inch, bps

Add Units to the device definition of parameters

Add a units attribute

Currently all of the GEMS examples are in the main specification document. Since the version number is in the message header, this creates a lot of changes to the document with every update, whether the examples changed or not. To avoid this, I recommend removing the examples from the specification and references the already-existing online examples. These are non-normative, but intended to provide a robust example set.

Remove the examples from the main specification

The problem is the examples have become difficult to maintain and must be updated every revision because the version number is in the message header. We have also found minor syntax errors in the examples. To correct these, we must issue a new version of the specification, which in turn requires the examples to be updated and the message header to change.

All of the examples will be removed from the main specification document (Sections 7.3, 7.5.1, and 8.3). The new text will provide a link to the online, non-normative examples. These examples will be maintained and updated separate from the specification.

It seems that over the years the original images have degraded. Many of the figures and diagrams are now low-resolution and difficult to read. The diagrams should be recreated (no technical content change) to make them more readable.

Replace old low-res diagrams

This doesn't change the content of the diagrams unless part of another issue.

There is no definition for arrays of parameter sets in the ASCII PSM. Section 7.1.1.3 suggests that these are supported by the PIM, and we need a mapping for all PSMs. Currently, a single parameter set (not an array of sets) is defined with commas as the delimiter between members of the set. The comma is also used as the delimiter between array elements. This makes it very difficult to deserialize an array of parameter sets, since the same delimiter character is used for two purposes. It became even more difficult after Issue 18814 was resolved by redefining the multiplicity to be a maximum array size (with -1 as a valid value), instead of the actual array size in the message. Suggest we use semicolons as the delimiter between parameter set members, and continue using commas as the delimiter between array elements.

Define the delimiter in a parameter set to be a semi-colon

The contents of section 8.2.1.2 have been confusing and incorrect. Specifying an array of parameter sets is undefined (clearly). We will define the delimiter to be a semi-colon with the last member of the parameter set requiring a semi-colon as well.

The HTTP header for GEMS XML in section 7.4 has the following issues:

1. First line contains "HTTP 1.0", which should be "HTTP/1.0"

2. There should be an additional endline between the header and the body

The example HTTP header is malformed

The intent is to use the standard HTTP header for all GEMS XML messages transferred across a plain TCP socket. However, the example in the specification does not correctly show this.

Received a request for either an asynchronous push or a new message
type that provides changes only. This was an optional requirement in
the original RFP

Add AsyncStatusMessage

This message is used for Asynchronous status messages. The transport mechanism or how it is set up are left for later versions of GEMS. At this point it was determined that the message definition would be sufficient for forward progress.

Section 7.2.6.1 only provides a simple example of a GetConfigResponse with no parameters. A better example would provide parameters possibly with multiplicity so implementers have a clearer understanding of how it should be done. Replace current example with:

<?xml version="1.0" encoding="UTF-8"?><GetConfigResponse gems_version="1.1" target="device1" timestamp="1234.98765" token="ABCD" transaction_id="1" xmlns="http://www.omg.org/gems"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.omg.org/gems GEMS_base_types.xsd">

<Result>SUCCESS</Result> <description>Get config was successful</description> <Parameter name="name"> <string>Device One</string> </Parameter>

<Parameter name="hex"> <hex_value bit_length="16">DEADBEEF</hex_value> </Parameter></GetConfigResponse>

GetConfigResponse Example

The existing example in the specification is insufficient. The online example provides what is needed.

The ASCII PSM defines the standard message trailer as "|END", but every single message type also ends with a "|" followed by "standard trailer". Strictly speaking, this results in every single message having a pair of pipes at the end with nothing between. We should remove the pipe from the standard trailer table (8.4).

Remove the extra pipe character in the message trailer

Combining the definition of the standard message trailer with the definition of the standard messages results in an extra and unintended pipe character.

The .xsd file requires parameters of a directive be with in <arguments> </arguments> but the example of page 37 doesn't do that.

Directive Example

The example in the specification was wrong and did not show the directive parameters in a containing <arguments></arguments> element.

This issue is OBE with the removal of the examples from the specification. The online example already shows this correctly.

The GEMS XML schema for a directive message has an extra, optional, attribute that should not be there. This was never caught until code generation was used and the attribute showed up.

Incorrect:

<!--

GEMS Directive

-->

<xsd:complexType name="ArgumentsType">

<xsd:sequence>

<xsd:element maxOccurs="unbounded" minOccurs="0" name="Parameter" type="Parameter"/>

</xsd:sequence>

<xsd:attribute name="directive_name" type="xsd:string" use="optional"/>

</xsd:complexType>

Correct:

<!--

GEMS Directive

-->

<xsd:complexType name="ArgumentsType">

<xsd:sequence>

<xsd:element maxOccurs="unbounded" minOccurs="0" name="Parameter" type="Parameter"/>

</xsd:sequence>

</xsd:complexType>

Remove the extra directive_name attribute in the Directive schema

The directive name is specified in the DirectiveMessageType:

<xsd:complexType name="DirectiveMessageType">
<xsd:complexContent>
<xsd:extension base="MessageType">
<xsd:sequence>
<xsd:element minOccurs="1" maxOccurs="1" name="directive_name" type="xsd:string"/>
<xsd:element minOccurs="0" maxOccurs="1" name="arguments" type="ArgumentsType"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>

But there is also an extra attribute in the ArgumentsType:

<xsd:complexType name="ArgumentsType">
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0" name="Parameter" type="Parameter"/>
</xsd:sequence>
<xsd:attribute name="directive_name" type="xsd:string" use="optional"/>
</xsd:complexType>

The extra attribute should be removed

The example HTTP POST header is incorrectly listed in section 7.4. The first line of the header should be:

POST /target HTTP/1.1

GEMS HTTP POST example is incorrect (Duplicate)

This is a duplicate

The ParameterSetDefType needs a multiplicity attribute similar to ParameterDefType. This allows for lists of Parameter Sets.

GEMS Device Definition needs multiplicity setting

This was already fixed in GEMS 1.3

<xsd:complexType name="ParameterSetDefType">
<xsd:sequence>
<xsd:element name="Description" minOccurs="0" maxOccurs="1"
type="xsd:string" />
<xsd:element name="ParameterDef" maxOccurs="unbounded" minOccurs="1"
type="ParameterDefType" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="multiplicity" type="xsd:int" use="optional" />
</xsd:complexType>

It would be very useful for the DisconnectMessage to have a response of success or failure.

DisconnectMessage Response

The original intent of the DisconnectMessage was to allow for "good behavior". It can be sent by either the GEMS user or the GEMS device and is typically immediately followed by a socket disconnect. Therefore, the may not be an available mechanism to send the reponse (the socket is closed).

The mixed parameter set example in 8.2.1.2 has an extra delimiter at the end of the message body:

mixed_param_set:set_type=param_1:int=1,param_2:boolean=true,param_3:string=a short string,

Delimiters should only be between the members of the set. This keeps them consistent with arrays (which, by the way, must NOT have delimiters at the end, since they have to be able to represent string arrays that end with an empty string element).

The ASCII parameter set definition is incorrect

The descriptive text in section 8.2.1.2 first shows an array (instead of a parameter set) and then incorrectly uses a comma as the delimiter.

The message examples for the ASCII PSM have the following issues. This is in addition to a handful of issue reported under Issue 19597.

1. The hex value examples have type "hexvalue". This should be "hex_value" (with underscore).

2. All examples have an extra space after the first pipe, e.g. "| GEMS|01|...". We should be able to use the examples literally.

3. The SetConfigMessage example still contains the long-removed "valid state" field. The "2" should be removed from the example, i.e.
SET-R|SUCCESS| The SET request was successful.||TRUE
instead of
SET-R|SUCCESS| The SET request was successful.|2|TRUE

4. The GEMS version in all examples should be updated to the latest ("14"). Right now it's using "01".

5. There is no ASCII example for the PING message. It should be:
Message: |GEMS|14|000122|123|CS123|111111111.222000000|FrameSync1|PING|END
Response: |GEMS|14|000122|123|CS123|111111111.222000000|FrameSync1|PING-R|SUCCESS|The PING request was successful.|END

Multiple issues with the GEMS-ASCII Examples

This issue captures a number of minor syntax errors within the example provided in the specification. Almost all are a result of document formatting or our inability to keep the examples up to date. Now that the examples are removed from the specification this issue is OBE. The existing online examples correct these errors and include an example of the PING message.

6.3.1.13 hex_value - Add: The length in bits is specified by following the hex data with a forward slash and the number of bits. E.g. /22.6.3.1.13 hex_value - Add: The length in bits is specified by following the hex data with a forward slash and the number of bits. E.g. /22.

Many of the XML examples: The gems_version attribute type should be xsd:decimal not xsd:int

Many of the XML examples: The XML examples shoudl all include the standard xml version segment like:
<?xml version="1.0" encoding="UTF-8"?>
This is missing from most of the examples

Many of the examples: The gems_version is shown as an integer value like: "1". It should be shown as a decimal value like: "1.3"

7.3.4.1 SetConfigMessage Example - this has a superfluous line: </SetConfigMessage> about half way down that needs to be deleted.

7.3.7.1 PingMessage Example - The version number should be changed from 1.1 to 1.3

7.3.7.2 PingResponse Example - The version number should be changed from 1.1 to 1.3

7.3.8.1 ConnectionRequestMessage without Authentication - The version number should be changed from 1.2 to 1.3

7.3.8.3 ConnectionRequestMessage with Authentication - The version number should be changed from 1.2 to 1.3

7.3.8.4 Failed ConnectionRequestResponse - add the version number as 1.3

7.3.8.5 Successful ConnectionRequestResponse - add the version number as 1.3

7.3.8.3 ConnectionRequestMessage with Authentication - The token filed text should be: "up:john:secret"

7.5.1 Example Device Definition File - replace 'bool' with 'boolean' 4 places

Table 8.1 boolean type: example should be: param:boolean=true

8.3.3 GetConfigMessage Example - change example sync_pattern to be: sync_pattern:hex_value=FAF320/22

8.3.4 SetConfigMessage Example - change example sync_pattern to be: sync_pattern:hex_value=FAF320/22

8.3.7 DirectiveMessage Example (response) - change accepted:bool=true to accepted:boolean=true

Clarify the bit_length field in a hex_value within the PIM

The request was to add the /bit-length notation to the description. Since this is actually the GEMS-ASCII format (XML is different), we will add a comment about the bit_length instead.

Issue GEMS14-7 lists many corrections in the documented examples. Since these are being removed from the document the issues are OBE. The generated examples online already correct these issues.

The link on page iv for reporting bugs is an invalid page. The link should be http://www.omg.org/report_issue.htm

The link to report issues is incorrect

The URL for the OMG issue reporting page is incorrect. This is in a boilerplate section.

Representation of arrays in the ASCII PSM is ambiguous. In 8.2.1 it says that arrays look like this:

parameter_name[3]:type=value1,value2,value3

The multiplicity is appended to the parameter name, there is a single type, and the values are comma separated. But in 8.2.1.2, it says arrays look like this:

param:int[3]:int=1,int=2,int=3

There are two colons, the multiplicity is appended to the type, and the type is repeated for each value within the comma separated list. Presumably there is a goal of unifying the way arrays and parameter sets are represented, where an array of scalars is just a homogeneous parameter set. Suggest we abandon this goal, as it will make representation of arrays of parameter sets very difficult. Suggest we represent arrays as follows:

name:type[multiplicity]=val1,val2,val3

Arrays defined ambiguously for ASCII PSM

This issue is basically a duplicate of GEMS14-40 and GEMS14-16. It highlights the error in array syntax and the need for a clarification on the parameter set delimiter.

Under "SetConfigResponse", it says "the message has 2 parameters", but only one parameter is described ("parameters_set"). This is probably a holdover from when the "valid state" parameter was removed back in v1.1. This should simply be changed to "the message has 1 parameter".

SetConfigResponse descriptive text specifies the wrong # parameters

The text indicates that here are 2 parameters, but there is only one.

All XML examples need to update the embedded URL. The "http://www.omg.org/gems" link is broken, it should be "http://www.omg.org/spec/GEMS" or "http://www.omg.org/spec/GEMS/current".

Links in the XML examples are broken

Now that the examples are removed from the specification this issue is OBE. The existing online examples are generated and all include the correct link.

<Parameter name=”telemetry_ports”>

should be

<Parameter name="telemetry_ports">

I copy and pasted that example into a file and it took me a couple of hours to realize there was invalid quotes.

Wrong type of quote used

The text could not be copied directly from the document because a fancy MS-Word quote had been pasted in.

The SCPI acronym definition in section 4 should read "Standard Commands", not "General Command".

SCPI Acronym not defined correctly

The definition is wrong

There are six figures in the specification that do not have figure numbers. These occur in sections 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.3.2.2, 8.2.3.

Add figure captions to all diagrams

Not all diagrams in the specification have figure captions

Section 9.2.6 and 9.2.7: Example response has an extra (typo) parameter. Need to remove the |0| field before the END.

These serve no purpose and are probably just typos. The typos will be fixed.

The header of the GEMS_base_types.xsd file does not match with section 7.1.1 of the GEMS Specification Beta 1 document. A. The new issue was mentioned in the AB review of the GEMS FTF report
B. Reported by Hugues Vincent

The GEMS XSD file contains the correct header information. Update section 7.1.1 of the document with the correct header found in this XSD file.

VALID_RANGE description contains extra copy of message UML image

a. This was found during our document review

b. Section 6.3.2.2

c. Reported by RT Logic

Remove the offending duplicate diagram from the INVALID_RANGE description.

There are two questions regarding hex_value types in the GEMS-ASCII PSM.

1. Hex value arrays are not well defined and the concept is complicated.
2. Can we use a 0xFFFF notation?
   Suggestions:
   Yes, the 0xFFFF notation can be used but it should be optional. ''(e.g. FAFA is the same as 0xFAFA)''
   As for arrays, this is a little complicated. Suggestions are as follows:

• Restrict arrays of hex_values to be the same bit length
• Move the bit length to the parameter value: e.g. hex_value[2]=22.FAF320,15.EB90 would specify an array with a 22 bit field and a 15 bit field
  RT Logic's recommendation is to use the 2nd option.

The GEMS PIM hex_value definition will be updated to make clear that all hex_values contained in arrays of hex_values must be of the same bit length.
The ASCII PSM definition will be updated to make clear what formats are allowable for hex_values.

Dave noted that the examples in the document do not clearly show the result description text. A simple ''Desc'' can be hidden. Better examples will help clear this up

Replace all 'Desc' text with wordier descriptions that are obviously visible.

There is no type defined for ConfigResult in either the PSM or the PIM. This is meant to be the result_description

The 'ConfigResult' type is really meant to be the 'result_description' defined in the base 'ResponseMessageType' in section 7.1.1.19.

The client_version is not defined in the PIM but offers the potential for client/server negotiations. This though might be too complex of a notion. Need to either delete it from the schema or update the PIM.
Recommend deleting it.

It is recommended that this notion of client_version be left out of the first version and reviewed for possible consideration at a later date.

Add XML and ASCII as normative references

Fill in section 3 with normative references for XML and ASCII.

Need an example of how to represent a parameter array in the GEMS-XML PSM

a. This missing example was found during our document review

b. Reported by RT Logic

This type of example is not suited to stand alone. Instead one of the existing examples will be modified to include an array of parameters for the purposes of demonstrating this concept.

The examples would be enhanced by providing an example of a directive with parameters and one with return values. Maybe these can be combined.

It seems appropriate to modify the example of a directive message in section 7.2.1 to include at least one parameter in the directive message and one return value in the directive message response. This would provide one comprehensive example of a directive message in the XML PIM.

Incorrect: ''Users connecting to a GEMS device are provide a token...''
Should be: ''.. are provided a token''

Simple correct the spelling error.

The standard device definitions are not defined yet. The original thought was that this section is populated by later revisions.
Suggest this be left for future versions/FTF.

Suggest this section be left empty with a short description regarding the notion of consistency across common devices. Future versions/FTF will expand this section with specific examples.

GEMS-ASCII messages do not specify a starting or trailing pipe character in either the table or in the examples. Dave's recommendation is to put this at the beginning of each message.

A beginning pipe will be added to the definition of the ASCII PSM message header. No ending pipe will be specified as one or the other is sufficient for parsing purposes.

The example only shows one parameter. Need to update one or the other.

The example is sufficient so it was decided to update the description to indicate only parameter would be requested.

The section provides a disconnect example, but the example has a connect message

The example will be changed to demonstrate a disconnect message in the GEMS-ASCII PSM.

The figure shows RTL instead of GEMS. Need to correct the figure.

Replace the figure with a correct version.

There is no description of ParameterSets in the GEMS-ASCII PSM. This needs to be added.

Discuss and flush out appropriately.

Need to define a standard way to escape and/or quote characters in string types

A new section (8.1.2 Reserved Words and Special Characters) will be added to discuss the requirements regarding any special characters and reserved words in the ASCII PSM.

1) The time format is closer to POSIX than UTC and does not allow for unambiguous leap second resolution.
A. This new issue was raised during the FTF.
B. Reported by David Overeem at Boeing

Disposition: See issue 14112 for disposition

Need a message to retrieve the list of saved/available configuration files. There is no current way to obtain the list of available configurations.

In the PIM the new messages are called GetConfigListMessage and GetConfigListResponse. The GetConfigListResponse includes a list of strings. Each string provides the name of a configuration.

The time stamp in the message header is loosely defined in the document. Need to clarify this. Suggest UTC following the time parameter type.

Update all related time stamp fields to specify UTC. Also changed the examples in the GEMS-ASCII PSM section to us ASCII time parameter format for the time stamp.
NOTE: There is an associated issue with this that was identified during the voting process. The time format is closer to POSIX than UTC and does not allow for unambiguous leap second resolution. Because the format of the message will likely not change, this should not impact GEMS 1.0 implementations. There are however several considerations that need to be taken in to account before a final decision can be made on using UTC vs POSIX. Therefore, the FTF is accepting the 3/4 yes vote as resolution of issue 12757. A new issue has been created (13132) and will be handled under a subsequent RTF to specifically address the UTC vs POSIX time concerns.

Should 64 bit integer values be added to the PIM?

Define the long type to be 64 bits in length. Originally the long type was redundant with the integer type. This approach matches the types used in XML.

The invalid_state field in the SetConfigResponse and LoadConfigResponse is confusing and might not apply to all cases (e.g. software only implementation). The original idea behind this was to provide a way to
indicate whether or not the hardware was left in a valid state in the event of an error.
Suggest moving this to a HARDWARE_ERROR ResultCode

Remove the valid_state Boolean members of the SetConfigResponse and LoadConfigResponse classes in the PIM. This change also needs propagating throughout the document. All references and sections to valid_state must be removed.

There are a number of places where internal table references are incorrect. This includes a few places where XXX is used.

All table references have been updated to reference existing tables with correct table numbers.

The GEMS PIM & PSMs do not define a generic message for a response to an unreadable or completely malformed message. This can occur if the server receives a message that is either not a GEMS message (i.e. junk) or a GEMS message with a malformed header. Currently the only response messages are tied to specific message types and it is unclear what a server should return in this more general case.
Proposed Resolution: Utilize the base response message class for this. The specific type in ASCII could be UNK-R and in XML UnknownResponse.

Utilize the base response message class for this. Define the specific type in ASCII to be UNK-R and in XML UnknownResponse. This are simple mappings to the base response message. The response code for this message indicates the specific error and is most commonly MALFORMED_MESSAGE.

The example for the GEMS-ASCII SaveConfigResponse in section 8.2.5 contains an extra field
Proposed Resolution: Fix

Remove the second numerical field (the zero).

The XML PSM sections and attached schema do not define a ping response message
Proposed Resolution: Potential XML Ping & PingResponse messages

<?xml version="1.0" encoding="UTF-8"?><PingMessage gems_version="1.1" target="testDevice1" timestamp="1234.98765"

token="ABCD" transaction_id="1" xmlns="http://www.omg.org/gems" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://www.omg.org/gems GEMS_base_types.xsd" />
<?xml version="1.0" encoding="UTF-8"?><PingResponse gems_version="1.1" target="testDevice1"

timestamp="1234.98765" token="ABCD" transaction_id="1" xmlns="http://www.omg.org/gems" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://www.omg.org/gems GEMS_base_types.xsd"> <Result>SUCCESS</Result> <description>I'm Here!</description></PingResponse>

Add a section to the PIM describing the Ping message and response. Correct the XSD and add a section to the XML PSM describing the message format.

Unlike a normal Parameter with multiplicity greater than 1, a ParameterSet array contains ParameterSet elements. These each have a name and multiplicity with then that need to be ignored.
Proposed Resolution: Add the following comment to the XSD for a ParameterSet:
NOTE: If the multiplicity is set, then the contained ParameterSet's are entries in the
array and the name & multiplicity (if specified) are ignored.

The issue here is that normally an element of an array parameter does not itself have a name or multiplicity. When translating between GEMS-XML and GEMS-ASCII there is no mapping for these. However, in GEMS-XML the XML schema allows for their existence.
For example, a normal parameter array is defined as follows in GEMS-XML:

<Parameter name="myarray" multiplicity="2">
<long>1</long>
<long>2</long>
</Parameter>

In contrast, a parameter set array is defined as follows in GEMS-XML:

<ParameterSet multiplicity="2" name="setlist">
<ParameterSet>
<Parameter name="param1">
<hex_value bit_length="2">0F</hex_value>
</Parameter>
<Parameter name="param2">
<string>text1</string>
</Parameter>
</ParameterSet>
<ParameterSet>
<Parameter name="param1">
<hex_value bit_length="2">1F</hex_value>
</Parameter>
<Parameter name="param2">
<string>text2</string>
</Parameter>
</ParameterSet>
</ParameterSet>

Per the XML schema, it is legal to add a multiplicity and name to the internal ParameterSet elements. This is effectively an extra layer of nesting that is not required in the GEMS-ASCII version and no mapping existing for the name and multiplicity.
To clarify the specification a comment shall be added to section 7.1.1.3 indicating that these values will be ignored.
To further help clarify this, an additional parameter set array will be added to the SetConfigMessage example in section 7.2.4.1.

The way hex_value arrays are handled in GEMS 1.1 solves this problem. The comment relates to the old way of doing hex_values
Proposed Resolution: Remove the comment

Remove the last sentence in section 6.3.1.13: “In cases where the multiplicity is greater than one the bit_length attribute of the hex_values must all be equal.”

There is no clear example of how to define a zero length hex_value in GEMS-ASCII. Possibilities include name:hex_value=/0 or name:hex_value=0/0
Proposed Resolution: name:hex_value=0/0 to make parsing simpler.

Standardize on the following format:

name:hex_value=0/0

This makes parsing the message easier as all valid hex_value parameters will contain content on either side of the ‘/’.

The attribute should be multiplicity to match the PIM/PSM
Proposed Resolution: Fix

Correct the XML schema and the text in section 7.1.1.3

The GEMS-XML schema defines a default value for multiplicity (default of 1). The result is that parsers using the schema are unable to tell if a parameter is a scalar or an array of length one.
Proposed Resolution: Recommend removing the default multiplicity in the xml schema and the spec should state 'no multiplicity == scalar'

Remove the default multiplicity in the xml schema and the spec now states 'no multiplicity == scalar'.

The mapping of XML to ASCII versions is inconsistent in the PSMs. GEMS-ASCII uses an integer (01, 02, 03...), and GEMS XML uses decimal numbers (1.1, 1.2 and so forth)
Proposed Resolution: Need to discuss

Add a simple mapping in table 8.2 that maps the versions. This section will be kept up to date as new GEMS versions are created.

The valid_state was removed from the PIM however the message table in 8.1.8.2 still has a valid state field.
Proposed Resolution: Remove this from the table

Remove the row in table 8.10 starting with the valid_state field name from the table.

The GEMS-ASCII message types are not correct in section 8.1.10.1. Appears to be a copy-n-paste error in GetConfigListMessage, GetConfigListResponse.

Correct the comment cell in table 8.11 to use the correct message types.

The schema dtc/11-02-02 has 6 errors found by running an XML Schema validator.

Various types extending MessageType give the following error: derived by restriction complex type has content while base type is empty

Change the restriction to an extension

Parsing a GEMS-XML message as it arrives on a TCP socket is difficult since you must first parse the stream (i.e. with SAX) and then likely validate it with a DOM.
Proposed Resolution: Add a statement indicating that the if a transport protocol is used (e.g. smart sockets etc) that includes the length, then nothing needs to be done. Otherwise, if TCP sockets are used, a HTTP header is pre-pended.

Add a statement indicating that if a transport protocol is used (e.g. smart sockets etc) that includes the length, then nothing needs to be done. Otherwise, if TCP sockets are used, a HTTP header is pre-pended.

6.3.1.4: but – bit
6.3.2: update supported versions (1 becomes 1.0, 1.1 and 1.2)
6.5: 3rd sentence, change 'contents' to 'content' (there is only one token field, so I think this is the better fix)
7.1.1.1: in the Unsigned Short Integer, change fixed="time" to fixed="ushort". (the XML schema is correct.. just a typo in the document)
8.1.2: first sentence after the escape sequence table, change 'chosed' to 'chosen'

Fix errors (see revised text)

The device definition return that is specified in the original RFP at section 6.5.1.9 does not appear to be implemented in the released specification 1.0.

Add a GEMS Device Definition description to the PIM. This description is generic in nature and defers the specifics of the description to the PSMs.
Define the exact format of the GEMS Device Definition in the GEMS-XML PSM as an XML file. This file may be obtained manually (e.g. distributed directly by the GEMS vendor) or automatically by serving the file out through an HTTP GET using the following URL: http://hostname/omg/gems/DeviceDefinitions.xml

UTC Time as a new type Create a new time type that uses the UTC time format. This would allow for times that are human readable and that also support leap seconds. Unfortunately the current time type cannot be replaced because the XML schema for it wouldn't easily support this new format for time. We suggest leaving the old time type (based on POSIX) which we admit is useful under many circumstances.

Adopt utime as a new parameter type. Updates are to be made in the PIM and PSMs. This resolution allows for backward compatibility with GEMS 1.0 since existing implementations will not utilize utime parameter types.

Escape characters: To make parsing quite a bit easier (enabling the use of string tokenizer tools found in most modern programming languages) we suggest changing the current escape character implementation with a mechanism similar to the one used for HTML / XML. This would mean identifying all special characters ('|', ',', ';' . . .) and creating character sequences for them ('&p', '&c', . . .). Doing this would simplify parsing code significantly. The initial message could then be easily split using the '|' as the token. Array members could easily be split using a ',' etc...

Adopt a simple escape character sequence. There are numerous standard escape sequences available, but the most common do not provide for the specific four characters needed in the GEMS ASCII PSM: | , & ;
To keep the ASCII PSM simple the following table is to be used:
Character Escape Sequence
& &a

Other PSMs might need a different escape sequence and will define this table differently.

Need to describe what a GET message returns when targeted to a proxy. There is no description of what is returned when a GetMessage is sent to a proxy.
Options:

• Return information on the proxy such as an array of target names available ''behind'' the proxy.
• Return all parameters for all devices behind the proxy
• Defined standard parameters for the proxy which would then be returned

Return a parameter with the name 'targets' that provides an array of strings, each array value represents a single target.

Hex value arrays in ASCII This was already differed as an issue during the FTF to be fixed later. Some additional feedback received was to use a format like 'FAF320/20' instead of notation like 'FAF320.20'. The later matches the notation used for the current time type but might cause too much confusion with floats.

Adopt the FAF320/20 format.

GEMS VERSION 1.2

It is not obvious what happens to a client using either GEMS-ASCII or GEMS-XML across TCP when the TCP socket is closed. If the client has successfully connected to a GEMS Device, is that GEMS connection (and resulting token) still active or does it automatically disconnect? Section 6.5 indicates that it should be disconnected, but this is not an obvious place for this behavior to be described.

Also, GEMS-XML states that the HTTP header should be added. When using client-side HTTP libraries, the default behavior is to disconnect often. This is an internet-style approach. The GEMS specification should state that persistent socket connection are required

Clarify socket behavior for GEMS over a TCP connection by stating that once a TCP connection is lost, the GEMS device should disconnect

It is not clear how to define the multiplicity of a list of Parameters or ParameterSets when the list is unbounded or can vary in length. For example, if the multiplicity is set to 5, it is assumed this means the list must contain 5 parameters. How does one specify "up to 5" or "unbounded"?

Create standard method of declaring unbounded list sizes. Use a multiplicity of -1 to indicate an unbounded array, while a non-negative and non-zero multiplicity indicates that the array may contain up to the number. For example, a multiplicity of 5 indicates that the array may contain anywhere between 0 and 5 elements.

The comments about the GEMS Version field in Table 8.2 are confusing. Is the example trying to imply that starting with GEMS version 1.2 the GEMS Version field digits matches the actual GEMS version number, or what?

Clarify comment text to specify that starting after version 1.2, the GEMS version field will be the same as the GEMS version number, with the decimal point removed (1.2 is 12, 1.3 is 13, etc.)

GEMS-XML schema (GEMS 1.2) for MessageSequenceType does not support elements for DirectiveMessage, even though DirectiveMessageType shares the same base (MessageType) as the other supported elements defined in MessageSequenceType.

Add DirectiveMessages to the MessageSequenceType in the GEMS-XML schema. Upon analysis of this issue, it was discovered the several other message types were missing. These were not reported in the original issue, but are fixed as part of the resolution.

Currently the message length is limited to 999999 characters. This can
cause problems translating from GEMS-XML to GEMS-ASCII. It also limits
the utility of message sets

Extend message length to 10 characters

The current GEMS-XML schema requires that Parameters and ParameterSets are always listed in that order. (i.e. ParameterSets cannot precede Parameters). It seems that these should be order independent.

Reported to AMERGINT by Raytheon

Fix the schema to be order independent.

The GEMS-XML XSD bases the HexParameter on the xsd:hexBinary type. This type expects an even number of characters (two for each octet). The GEMS-XML specification should mention this and explain how it needs to be handled.

Recommend always providing an even number of hex characters and using the bit length to specify the actual length.

Example of an invalid 4 bit field: E/4

Example of a valid 4 bit field: E0/4

Pad the hex_value field to two full nibbles for the XML.

Authentication of a GEMS user is loosely defined in the specification.
This should be clarified and include a better definition of how
credentials are passed in, what is the roll (if any) of SSL and
similar transports, and how do proxies handle authentication. In
particular, how does a GEMS user grab control of a system without
creating a race condition.

Add a multiplicity attribute to the ParameterSetDefType declaration to the GEMS_Device file, where it was omitted.