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