5. Writing Data (Output)

5.1. Getting the Output

To write a data sample, first look up an output:

output = connector.getOutput('MyPublisher::MySquareWriter')

Connector.getOutput() returns an Output() object. This example obtains the output defined by the data_writer named MySquareWriter within the publisher named MyPublisher:

<publisher name="MyPublisher">
  <data_writer name="MySquareWriter" topic_ref="Square" />
</publisher>

This publisher is defined inside the domain_participant selected to create this Connector() (see Creating a new Connector).

5.2. Populating the data sample

The next step is to set the Instance() fields. You can set them member-by-member:

output.instance.setNumber('x', 1)
output.instance.setNumber('y', 2)
output.instance.setNumber('shapesize', 30)
output.instance.setString('color', 'BLUE')

Or using a JSON object:

output.instance.setFromJson({ x: 1, y: 2, shapesize: 30, color: 'BLUE' })

The name of each member corresponds to the type assigned to this output in XML. For example, the XML configuration corresponding to the above code snippets is:

<struct name="ShapeType">
  <member name="color" type="string" stringMaxLength="128" key="true" default="RED"/>
  <member name="x" type="long" />
  <member name="y" type="long" />
  <member name="shapesize" type="long" default="30"/>
 </struct>

See Instance() and Accessing the data for more information.

5.3. Writing the data sample

To write the values that have been set in Output.instance, call Output.write():

output.write()

If the datawriter_qos is reliable, you can use Output.wait() to block until all matching reliable subscribers acknowledge the reception of the data sample:

try {
  await output.wait()
} catch (err) {
  console.log('Error caught: ' + err)
}

The write method can also receive a JSON object specifing several options. For example, to write with a specific timestamp:

output.write({ source_timestamp: 100000 })

It is also possible to dispose or unregister an instance:

output.write({ action: 'dispose' })
output.write({ action: 'unregister' })

In these two cases, only the key fields in the Output.instance are relevant.

See Output.write() for more information on the supported parameters.

5.4. Matching with a subscription

Before writing, you can use the method Output.waitForSubscriptions() to detect when a compatible DDS subscription is matched or stops matching. It returns a Promise that will resolve to the change in the number of matched subscriptions since the last time it was called.

You can wait for the Promise using await in an async function:

let changeInMatches = await output.waitForSubscriptions()

Or using the then and catch methods:

output.waitForSubscriptions().then((res) => {
  // The Promise resolved successfully and the number of matches is stored in res
}).catch((err) => {
  // Handle the error (which is possibly a timeout)
}

For example, if a new compatible subscription is discovered within the specified timeout, the Promise will resolve to 1; if a previously matching subscription no longer matches (for example, due to the application being closed), it resolves to -1.

You can obtain information about the currently matched subscriptions with the Output.matchedSubscriptions property:

output.matchedSubscriptions.forEach((match) => {
 subName = match.name
}

5.5. Class reference: Output, Instance

5.5.1. Output class

class Output(connector, name)

Allows writing data for a DDS Topic.

This class is used to publish data for a DDS Topic.

To get an Output object, use Connector.getOutput().

Attributes:

instance (Instance()) - The data that is written when Output.write() is called.
connector (Connector()) - The Connector() object that created this object.
name (str) - The name of this Output (the name used in Connector.getOutput()).
native (pointer) - The native handle that allows accessing additional Connext DDS APIs in C.
matchedSubscriptions (JSON) - Information about matched subscriptions (see below).

Output.matchedSubscriptions

type: JSON

Provides information about matched subscriptions.

This property returns a JSON array, with each element of the array containing information about a matched subscription.

Currently the only information contained in this JSON object is the subscription name of the matched subscription. If the matched subscription doesn’t have a name, the name for that specific subscription will be null.

Note that Connector() Inputs are automatically assigned a name from the data_reader name element in the XML configuration.

Output.clearMembers()

Resets the values of the members of this Instance().

If the member is defined with a default attribute in the configuration file, it gets that value. Otherwise, numbers are set to 0 and strings are set to empty. Sequences are cleared and optional members are set to ‘null’. For example, if this Output’s type is ShapeType, then clearMembers() sets:

color = 'RED'
shapesize = 30
x = 0
y = 0

Output.wait(timeout)

Waits until all matching reliable subscriptions have acknowledged all the samples that have currently been written.

This method only waits if this Output is configured with a reliable QoS.

Note

This operation is asynchronous

Arguments:

timeout (timeout) – The maximum time to wait, in milliseconds. By default, infinite.

Throws:

TimeoutError – TimeoutError() will be thrown if the timeout expires before all matching reliable subscriptions acknowledge all the samples.

Returns:

Promise – Promise object which will be rejected if not all matching reliable subscriptions acknowledge all of the samples within the specified timeout.

Output.waitForSubscriptions(timeout)

Waits for this Output to match or unmatch a compatible DDS Publication.

This method waits for the specified timeout (or if no timeout is specified, it waits forever), for a match (or unmatch) to occur.

Note

This operation is asynchronous

Arguments:

timeout (number) – The maximum time to wait, in milliseconds. By default, infinite.

Throws:

TimeoutError – TimeoutError() will be thrown if the timeout expires before a subscription is matched.

Returns:

Promise – Promise object resolving with the change in the current number of matched inputs. If this is a positive number, the output has matched with new subscribers. If it is negative, the output has unmatched from a subscription. It is possible for multiple matches and/or unmatches to be returned (e.g., 0 could be returned, indicating that the output matched the same number of inputs as it unmatched).

Output.write(params)

Publishes the values of the current Instance.

Note that after writing it, the Instance’s values remain unchanged. If, for the next write, you need to start from scratch, you must first call Output.clearMembers().

This method accepts an optional JSON object as a parameter, which may specify the parameters to use in the write call. The supported parameters are a subset of those documented in the Writing Data section of the RTI Connext DDS Core Libraries User’s Manual. These are:

action – One of write (default), dispose or unregister
source_timestamp – An integer representing the total number of nanoseconds
identity – A JSON object containing the fields writer_guid and sequence_number
related_sample_identity – Used for request-reply communications. It has the same format as identity

Arguments:

params (JSON) – [Optional] The optional parameters described above

Throws:

TimeoutError – The write method can block under multiple circumstances (see ‘Blocking During a write()’ in the Writing Data section of the RTI Connext DDS Core Libraries User’s Manual.) If the blocking time exceeds the max_blocking_time, this method throws TimeoutError().

Examples:

output.write()

output.write({
    action: 'dispose',
    identity: { writer_guid: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16], sequence_number: 1 }
})

5.5.2. Instance class

class Instance(output)

A data sample.

Instance() is the type obtained through Output.instance and is the object that is published by Output.write().

An Instance has an associated DDS Type, specified in the XML configuration, and it allows setting the values for the fields of the DDS Type.

Attributes:

output (Output()) - The Output() that owns this Instance.
native (pointer) - Native handle to this Instance that allows for additional Connext DDS Pro C APIs to be called.

Instance.native

type: pointer

The native C object.

This property allows accessing additional Connext DDS APIs in C.

Instance.clearMember(fieldName)

Resets a member to its default value.

The effect is the same as that of Output.clearMembers(), except that only one member is cleared.

Arguments:

fieldName (string) – The name of the field. It can be a complex member or a primitive member.

Instance.getJson()

Retrives the value of this instance as a JSON object.

Note

This operation should not be used with values with an aboslute value larger than Number.MAX_SAFE_INTEGER. See Accessing 64-bit integers for more information.

Returns:: JSON – The value of this instance as a JSON object.

Instance.set(fieldName, value)

Sets the value of fieldName.

The type of the argument value must correspond with the type of the field with name fieldName (as defined in the configuration XML file).

This method is an alternative to Instance.setNumber(), Instance.setString() and Instance.setBoolean(). The main difference is that it is type-independent (in that the same method can be used for all fields).

Arguments:

fieldName (string) – The name of the field.
value (number|boolean|string|null) – The value to set. Note that null is used to unset an optional member.

Instance.setBoolean(fieldName, value)

Sets a boolean field.

Arguments:

fieldName (string) – The name of the field.
value (boolean) – A boolean value, or null, to unset an optional member.

Instance.setFromJson(jsonObj)

Sets the member values specified in a JSON object.

The keys in the JSON object are the member names of the DDS Type associated with the Output, and the values are the values to set for those members.

This method sets the values of those members that are explicitly specified in the JSON object. Any member that is not specified in the JSON object will retain its previous value.

To clear members that are not in the JSON object, call Output.clearMembers() before this method. You can also explicitly set any value in the JSON object to null to reset that field to its default value.

Arguments:

jsonObj (JSON) – The JSON object containing the keys (field names) and values (values for the fields).

Instance.setNumber(fieldName, value)

Sets a numeric field.

Note

This operation should not be used with values with an aboslute value larger than Number.MAX_SAFE_INTEGER. See Accessing 64-bit integers for more information.

Arguments:

fieldName (string) – The name of the field.
value (number) – A numeric value, or null, to unset an optional member.

Instance.setString(fieldName, value)

Sets a string field.

Arguments:

fieldName (string) – The name of the field.
value (string|null) – A string value, or null, to unset an optional member.