pdcomm::GemEquipment

Class

GEM equipment role (SEMI E30) on one HSMS endpoint (SEMI E37).

class GemEquipment final : public GemEndpoint

Declared in: #include <pdcomm_gem.hpp>

The constructor configures the equipment identity (MDLN, SOFTREV), the initial control state and the status variable registry on a stopped TcpEndpoint. Configure the optional stores before start(), while the endpoint is stopped:

• reports and collection events (configureReports(), configureFixedCatalog()), used by S2F33 to S2F38 and S6F11;
• alarms (configureAlarms(), S5F1 to S5F8);
• remote commands (configureCommands(), S2F41/F42) and enhanced remote commands (configureEnhancedCommands(), S2F49/F50);
• equipment constants (configureConstants(), S2F13 to S2F16, S2F29/F30);
• data variables, report bindings and the event directory (configureDataVariables(), configureReportBindings(), configureEventDirectory(); S1F21 to S1F24, S6F15 to S6F22);
• process programs (GemEndpoint::configurePrograms()) and spooling (configureSpooling()).

Configure the report catalog before alarms, commands and constants, because their completion and alarm CEIDs must already exist in it.

At run time the library answers stream 1 requests, report and event definitions, alarm queries, constant queries and namelists itself. Remote commands, constant changes, report queries, program requests and spool requests produce Primary results that wait for your respond call. Nothing is executed on the physical tool by the library.

const auto limits = pdcomm::secsLimits(4096, 4096, 128, 8);
pdcomm::TcpEndpoint transport(address, tcpOptions(PDCOMM_TCP_PASSIVE));
pdcomm::GemEquipment equipment(std::move(transport), limits,
    pdcomm::GemControl::HostOffline, pdcomm::GemOnlineMode::Remote,
    "PDComm", "0.1.0", 8, 1024, 4096);
const std::vector<uint8_t> temperature = {0x41, 0xac, 0, 0};
auto value = pdcomm::SecsItem::primitive(PDCOMM_SECS_F4, temperature, limits);
equipment.registerStatus(1, "Temperature", "C", value);
equipment.start();

Notes

• Move-only. Serialize all calls on one endpoint (see GemEndpoint).

Members

GemEquipment

Constructor

Takes ownership of endpoint and configures it as GEM equipment from an options struct.

GemEquipment(TcpEndpoint &&endpoint, const PdcommGemEquipmentOptions &options)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
endpoint	Stopped HSMS endpoint without a GEM role. It is moved into this object and destroyed if the constructor throws.
options	Equipment options with struct_size, version 1 and reserved 0. Model and software revision are copied as length-delimited ASCII.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped or already has a GEM role; PDCOMM_INVALID_ARGUMENT for invalid options, non-ASCII identity or an initial GemControl::AttemptOnline; PDCOMM_LIMIT_EXCEEDED when the identity does not fit the item limits.

GemEquipment

Constructor

Takes ownership of endpoint and configures it as GEM equipment.

GemEquipment(TcpEndpoint &&endpoint, const PdcommSecsLimits &limits, GemControl initialControl, GemOnlineMode onlineMode, const std::string &model, const std::string &softwareRevision, size_t maxVariables, size_t maxMetadataBytes, size_t maxValueBytes)

Declared in: #include <pdcomm_gem.hpp>

Builds the options structure from the parameters.

Parameters

Name	Description
endpoint	Stopped HSMS endpoint without a GEM role. It is moved into this object and destroyed if the constructor throws.
limits	SECS-II limits for every message of this endpoint.
initialControl	Initial control state; GemControl::AttemptOnline is rejected.
onlineMode	Online substate entered when going online.
model	Equipment model (MDLN), ASCII.
softwareRevision	Software revision (SOFTREV), ASCII.
maxVariables	Maximum registered status variables.
maxMetadataBytes	Maximum bytes of status variable names and units.
maxValueBytes	Maximum bytes of status variable values.

Notes

• Throws pdcomm::Error: Same statuses as the options constructor.

alarmAt

Method

Returns one alarm in registration order.

GemAlarmInfo alarmAt(size_t index)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
index	Zero-based position, less than GemAlarmState::alarmCount.

Returns

Definition, set state and reporting state.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index.

alarmState

Method

Returns counters of the alarm store.

GemAlarmState alarmState()

Declared in: #include <pdcomm_gem.hpp>

Returns

Alarm, active, enabled and text byte counts.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when no alarm store is configured.

bindingAt

Method

Returns one binding in stored order.

GemBindingInfo bindingAt(size_t index)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
index	Zero-based position, less than GemBindingState::bindingCount.

Returns

VID, source and, for constants, an owned ECID item.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index.

bindingState

Method

Returns the state of the binding store.

GemBindingState bindingState()

Declared in: #include <pdcomm_gem.hpp>

Without configured bindings it reports explicit mode off and zero counts.

Returns

Binding count, identifier bytes and mode.

Notes

• Throws pdcomm::Error: with the native status on failure.

captureSpool

Method

Offers a generic primary message to the spool.

GemSpoolWriteResult captureSpool(uint8_t stream, uint8_t function, bool replyExpected, const SecsItem *body, uint64_t now)

Declared in: #include <pdcomm_gem.hpp>

The message is stored only while spooling is active and the (stream, function) is selected; otherwise the call succeeds with GemSpoolWriteInfo::selected false. A full spool applies the overflow policy, which is a statistics change, not an error. Capture does not send the message.

Parameters

Name	Description
stream	Stream of a registered spoolable primary.
function	Function of a registered spoolable primary.
replyExpected	W-bit to use when the message is delivered later.
body	Message body, or nullptr for a header-only message. Borrowed for the call.
now	Application timestamp stored as the capture time.

Returns

PDCOMM_OK or PDCOMM_SPOOL_UNCONFIRMED with the mutation details.

Notes

• Throws pdcomm::Error: for other statuses, for example PDCOMM_INVALID_STATE when the spool is not synchronized or PDCOMM_INVALID_ARGUMENT for an unregistered key.

captureSpoolAlarm

Method

Builds the S5F1 report for an alarm's current state and offers it to the spool.

GemSpoolWriteResult captureSpoolAlarm(uint32_t alarmId, bool replyExpected, uint64_t now)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
alarmId	ALID of a configured alarm.
replyExpected	W-bit to use when the report is delivered later.
now	Application timestamp stored as the capture time.

Returns

PDCOMM_OK or PDCOMM_SPOOL_UNCONFIRMED with the mutation details.

Notes

• Throws pdcomm::Error: for other statuses, as for captureSpool().

captureSpoolEvent

Method

Builds the S6F11 report for a collection event and offers it to the spool.

GemSpoolWriteResult captureSpoolEvent(uint32_t dataId, uint32_t eventId, const std::vector<GemDataSample> &samples, uint64_t now)

Declared in: #include <pdcomm_gem.hpp>

The report is built from the same sources as publishEventWithData(), at capture time.

Parameters

Name	Description
dataId	DATAID of the report.
eventId	CEID of a linked event.
samples	Data variable samples; borrowed for the call.
now	Application timestamp stored as the capture time.

Returns

PDCOMM_OK or PDCOMM_SPOOL_UNCONFIRMED with the mutation details.

Notes

• Throws pdcomm::Error: for other statuses, as for captureSpool() and publishEventWithData().

clearDataVariable

Method

Removes the cached value of a data variable.

void clearDataVariable(uint32_t id)

Declared in: #include <pdcomm_gem.hpp>

Reports that need the value then fail with PDCOMM_INVALID_STATE unless a sample is supplied.

Parameters

Name	Description
id	DVID.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an unknown ID.

clearReportBindings

Method

Removes all bindings and restores the default VID-equals-SVID resolution.

void clearReportBindings()

Declared in: #include <pdcomm_gem.hpp>

Allowed only while the endpoint is stopped, and only when the existing reports stay valid.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped or the existing reports would become invalid.

commandAt

Method

Returns one command definition in stored order.

GemCommandInfo commandAt(size_t index)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
index	Zero-based position, less than GemCommandState::commandCount.

Returns

Owned name and command metadata.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index.

commandParameterAt

Method

Returns one parameter definition of one command.

GemCommandParameterInfo commandParameterAt(size_t commandIndex, size_t parameterIndex)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
commandIndex	Zero-based command position.
parameterIndex	Zero-based parameter position.

Returns

Owned name and parameter rules.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index.

commandState

Method

Returns counters of the remote command store.

GemCommandState commandState()

Declared in: #include <pdcomm_gem.hpp>

Returns

Command, parameter and identifier byte counts.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when no command store is configured.

configureAlarms

Method

Creates the alarm store.

void configureAlarms(const PdcommGemAlarmOptions &options, const std::vector<GemAlarmDefinition> &definitions)

Declared in: #include <pdcomm_gem.hpp>

Call once while the endpoint is stopped, after configureReports() when alarms use set or clear CEIDs. The complete store is validated before installation. All alarms start inactive and with reporting disabled.

Parameters

Name	Description
options	Limits built with gemAlarmOptions().
definitions	Alarm definitions; borrowed for the call.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped or an alarm store exists; PDCOMM_INVALID_ARGUMENT for duplicate IDs, a category outside 1 to 63, non-ASCII text or unknown CEIDs; PDCOMM_LIMIT_EXCEEDED for limits.

configureCommands

Method

Creates the remote command (S2F41) store.

void configureCommands(const PdcommGemCommandOptions &options, const std::vector<GemCommandDefinition> &definitions)

Declared in: #include <pdcomm_gem.hpp>

Call once while the endpoint is stopped. The complete store is validated before installation; on failure nothing changes. Positive signed and unsigned names compare equal.

Parameters

Name	Description
options	Limits built with gemCommandOptions().
definitions	Command definitions; the items are borrowed for the call.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped or a command store exists; PDCOMM_INVALID_ARGUMENT for invalid or duplicate names, bounds without an integer format, or unknown completion CEIDs; PDCOMM_LIMIT_EXCEEDED for limits.

configureConstants

Method

Creates the equipment constant (ECID) store.

void configureConstants(const PdcommGemConstantOptions &options, const std::vector<GemConstantDefinition> &definitions)

Declared in: #include <pdcomm_gem.hpp>

Call once while the endpoint is stopped. The complete store is validated before installation. IDs are case-sensitive ASCII or scalar integers; positive signed and unsigned IDs compare equal.

Parameters

Name	Description
options	Limits built with gemConstantOptions().
definitions	Constant definitions; borrowed for the call.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped or a constant store exists; PDCOMM_INVALID_ARGUMENT for invalid or duplicate definitions; PDCOMM_LIMIT_EXCEEDED for limits.

configureDataVariables

Method

Installs or replaces the complete data variable (DVID) store.

void configureDataVariables(const PdcommGemDataOptions &options, const std::vector<GemDataDefinition> &definitions)

Declared in: #include <pdcomm_gem.hpp>

Allowed only while the endpoint is stopped. All definitions and the existing binding and directory targets are validated first; on failure the previous store stays. The library never samples, updates caches, or persists data variables by itself.

Parameters

Name	Description
options	Limits built with gemDataOptions().
definitions	Data variable definitions; borrowed for the call.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped; PDCOMM_INVALID_ARGUMENT for duplicate IDs, non-ASCII metadata or a cached value that does not match its format or count; PDCOMM_LIMIT_EXCEEDED for limits.

configureEnhancedCommands

Method

Creates the enhanced remote command (S2F49) store.

void configureEnhancedCommands(const PdcommGemEnhancedCommandOptions &options, const std::vector<GemEnhancedObjectDefinition> &objects)

Declared in: #include <pdcomm_gem.hpp>

Call once while the endpoint is stopped. The complete store is validated first; on failure the previous store stays. Object specifiers are exact, case-sensitive ASCII. There is no fallback between basic and enhanced commands.

Parameters

Name	Description
options	Limits built with gemEnhancedCommandOptions().
objects	Objects with their commands; the items are borrowed for the call.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped; PDCOMM_INVALID_ARGUMENT for invalid definitions; PDCOMM_LIMIT_EXCEEDED for limits.

configureEventDirectory

Method

Installs or replaces the collection event namelist answered for S1F23.

void configureEventDirectory(const PdcommGemDirectoryOptions &options, const std::vector<GemDirectoryDefinition> &definitions)

Declared in: #include <pdcomm_gem.hpp>

Allowed only while the endpoint is stopped. Event IDs must exactly match the report store, and every VID must be bound to an existing data variable. On failure the previous directory stays. Later cache or report changes do not alter the directory.

Parameters

Name	Description
options	Limits built with gemDirectoryOptions().
definitions	Directory rows; borrowed for the call.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped; PDCOMM_INVALID_ARGUMENT for duplicate IDs or unknown events or variables; PDCOMM_LIMIT_EXCEEDED for limits.

configureFixedCatalog

Method

Atomically installs a fixed report graph and its STATUS or DATA bindings.

void configureFixedCatalog(const PdcommGemReportOptions &reportOptions, const std::vector<GemReportSpec> &reports, const std::vector<GemFixedEventSpec> &events, const PdcommGemBindingOptions &bindingOptions, const std::vector<GemReportBinding> &bindings)

Declared in: #include <pdcomm_gem.hpp>

Allowed only while the endpoint is stopped. Use it when the equipment, not the host, defines reports and links. On failure both the previous report graph and the binding store stay.

Parameters

Name	Description
reportOptions	Report store limits built with gemReportOptions().
reports	Report definitions.
events	Collection events with their linked reports and enabled state.
bindingOptions	Binding limits built with gemBindingOptions().
bindings	VID bindings for the report variables.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped; PDCOMM_INVALID_ARGUMENT for inconsistent definitions; PDCOMM_LIMIT_EXCEEDED for limits.

configureLocalSpooling

Method

Sets the local spooling policy and stream selection.

GemSpoolWriteResult configureLocalSpooling(const GemSpoolPolicy &policy, const std::vector<GemSpoolSelection> &selections)

Declared in: #include <pdcomm_gem.hpp>

Requires a stopped endpoint with no transmission or dequeue pending. Changes apply to future captures only; stored entries are kept. The change invalidates the current synchronization, so call syncSpool() again before capturing.

Parameters

Name	Description
policy	Overflow behaviour, transmit limit and global switch.
selections	Selected streams; an empty function list selects every registered primary of the stream, and an empty vector disables all streams.

Returns

PDCOMM_OK or PDCOMM_SPOOL_UNCONFIRMED with the mutation details.

Notes

• Throws pdcomm::Error: for other statuses, for example PDCOMM_INVALID_STATE or PDCOMM_INVALID_ARGUMENT for a selection outside the catalog.

configureReportBindings

Method

Installs or replaces the VID-to-source bindings used to build reports.

void configureReportBindings(const PdcommGemBindingOptions &options, const std::vector<GemReportBinding> &bindings)

Declared in: #include <pdcomm_gem.hpp>

Allowed only while the endpoint is stopped. All sources and existing reports are validated before the store changes. Different VIDs may share a source; duplicate VIDs fail. An empty vector installs explicit mode with no bindings and no fallback.

Parameters

Name	Description
options	Limits built with gemBindingOptions().
bindings	Bindings; the constant ID items are borrowed for the call.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped; PDCOMM_INVALID_ARGUMENT for duplicate VIDs or invalid sources; PDCOMM_OUT_OF_RANGE for unknown sources; PDCOMM_LIMIT_EXCEEDED for limits.

configureReports

Method

Creates the report store and declares the collection events (CEIDs).

void configureReports(const PdcommGemReportOptions &options, const std::vector<uint32_t> &eventIds)

Declared in: #include <pdcomm_gem.hpp>

Call once while the endpoint is stopped. No reports or links are predefined; the host defines them at run time with S2F33 and S2F35. The event IDs are copied.

Parameters

Name	Description
options	Limits built with gemReportOptions().
eventIds	CEIDs the equipment can report; duplicates are rejected.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped or a report store exists; PDCOMM_INVALID_ARGUMENT for duplicate IDs or invalid limits.

configureSpooling

Method

Attaches the equipment spool.

GemSpoolWriteResult configureSpooling(const GemSpoolOptions &options, const std::vector<GemSpoolMessageKey> &catalog, const std::string &path = {})

Declared in: #include <pdcomm_gem.hpp>

Call once while the endpoint is stopped. With an empty path the spool lives in memory. Otherwise a bounded snapshot file is opened under an exclusive lock: an existing file is loaded with its catalog, options, selection, queue and statistics and is never replaced or migrated; a new file is installed with an initial disabled snapshot. File I/O runs synchronously on the calling thread.

Parameters

Name	Description
options	Limits built with gemSpoolOptions().
catalog	Spoolable (stream, function) primaries. Required for a new store; for a loaded store it must be empty or match the persisted catalog exactly.
path	UTF-8 file path without NUL bytes, or empty for memory only. The parent directory must exist.

Returns

PDCOMM_OK, or PDCOMM_SPOOL_UNCONFIRMED when a new file was installed but its parent directory synchronization is unconfirmed. The spool is attached in both cases; do not configure again.

Notes

• Throws pdcomm::Error: for other statuses, for example PDCOMM_INVALID_STATE when the endpoint is not stopped or spooling is already configured, PDCOMM_INVALID_ARGUMENT for an invalid catalog or path, PDCOMM_IO_ERROR, or PDCOMM_INVALID_DATA for a corrupt file.

constant

Method

Returns one field of a local constant definition.

SecsItem constant(const SecsItem &id, GemConstantField field)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
id	ECID item.
field	Field to read; GemConstantField::Current returns the current value.

Returns

An independently owned item, or an empty item when an optional default, minimum or maximum is absent (which differs from an empty ASCII value).

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an unknown ID.

constantAt

Method

Returns one constant definition in stored order.

GemConstantInfo constantAt(size_t index)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
index	Zero-based position, less than GemConstantState::constantCount.

Returns

Owned ECID and value rules.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index.

constantState

Method

Returns counters of the constant store.

GemConstantState constantState()

Declared in: #include <pdcomm_gem.hpp>

Returns

Constant, metadata and value byte counts.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when no constant store is configured.

data

Method

Returns the name, units or cached value of a data variable.

SecsItem data(uint32_t id, GemDataField field)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
id	DVID.
field	Field to read.

Returns

An independently owned item; for GemDataField::Cached an empty item when no value is cached.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an unknown ID; PDCOMM_INVALID_STATE when no data store is configured.

dataAt

Method

Returns one data variable definition in stored order.

GemDataInfo dataAt(size_t index)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
index	Zero-based position, less than GemDataState::variableCount.

Returns

DVID, format, cache flag and count range.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index; PDCOMM_INVALID_STATE when no data store is configured.

dataState

Method

Returns counters of the data variable store.

GemDataState dataState()

Declared in: #include <pdcomm_gem.hpp>

Returns

Variable, metadata and value byte counts.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when no data store is configured.

directory

Method

Alias of directoryGet().

SecsItem directory(uint32_t id, GemDirectoryField field)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
id	CEID of the row.
field	Field to read.

Returns

An independently owned item.

Notes

• Throws pdcomm::Error: Same statuses as directoryGet().

directoryAt

Method

Returns one event directory row in stored order.

GemDirectoryEntryInfo directoryAt(size_t index)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
index	Zero-based position, less than GemDirectoryState::eventCount.

Returns

CEID and VID count.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index; PDCOMM_INVALID_STATE when no directory is configured.

directoryGet

Method

Returns the name or VID list of one event directory row.

SecsItem directoryGet(uint32_t id, GemDirectoryField field)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
id	CEID of the row.
field	GemDirectoryField::Name (ASCII) or GemDirectoryField::VariableIds (U4 array).

Returns

An independently owned item that survives reconfiguration.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT for GemDirectoryField::Units; PDCOMM_OUT_OF_RANGE for an unknown ID; PDCOMM_INVALID_STATE when no directory is configured.

directoryState

Method

Returns the state of the event directory.

GemDirectoryState directoryState()

Declared in: #include <pdcomm_gem.hpp>

Returns

Row and byte counts and whether a directory is configured.

Notes

• Throws pdcomm::Error: with the native status on failure.

enhancedCommandAt

Method

Returns one command of one enhanced object.

GemCommandInfo enhancedCommandAt(size_t objectIndex, size_t commandIndex)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
objectIndex	Zero-based object position.
commandIndex	Zero-based command position inside the object.

Returns

Owned name and command metadata.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index.

enhancedCommandParameterAt

Method

Returns one parameter definition of one enhanced command.

GemCommandParameterInfo enhancedCommandParameterAt(size_t objectIndex, size_t commandIndex, size_t parameterIndex)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
objectIndex	Zero-based object position.
commandIndex	Zero-based command position.
parameterIndex	Zero-based parameter position.

Returns

Owned name and parameter rules.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index.

enhancedCommandState

Method

Returns counters of the enhanced remote command store.

GemEnhancedCommandState enhancedCommandState()

Declared in: #include <pdcomm_gem.hpp>

Returns

Object, command, parameter and byte counts.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when no enhanced store is configured.

enhancedObjectAt

Method

Returns one object of the enhanced command store.

GemEnhancedObjectInfo enhancedObjectAt(size_t objectIndex)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
objectIndex	Zero-based object position.

Returns

Owned object specifier and command count.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index.

eventAt

Method

Returns one collection event in stored order.

GemEventDefinition eventAt(size_t index)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
index	Zero-based position, less than GemReportState::eventCount.

Returns

CEID, enabled flag and linked RPTIDs.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index.

observeAlarm

Method

Records the current set or clear state of an alarm without sending anything.

GemAlarmChange observeAlarm(uint32_t id, bool active)

Declared in: #include <pdcomm_gem.hpp>

Works without a connection. A transition returns the configured set or clear CEID; publish the S5F1 alarm report (publishAlarm()) and any S6F11 event separately. A later send failure never rolls the observed state back.

Parameters

Name	Description
id	ALID.
active	true when the alarm condition is present.

Returns

Whether the state changed, the reporting state and the transition CEID.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an unknown ALID.

operatorOffline

Method

Moves the equipment offline at the operator's request (the OFF-LINE switch).

void operatorOffline()

Declared in: #include <pdcomm_gem.hpp>

Allowed in GemControl::OnlineLocal, GemControl::OnlineRemote, and GemControl::HostOffline, as in the SEMI E30 control state model. The control state becomes GemControl::EquipmentOffline. No message is sent and no connection is required.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE in GemControl::EquipmentOffline or GemControl::AttemptOnline.

operatorOnline

Method

Starts an operator-initiated transition to online by sending S1F1.

PdcommTcpToken operatorOnline()

Declared in: #include <pdcomm_gem.hpp>

Requires a connected session and GemControl::EquipmentOffline. The control state becomes GemControl::AttemptOnline. The host's S1F2 yields GemOutcome::OnlineAccepted and the online substate from setOnlineMode(); a failure or disconnect moves to GemControl::HostOffline. The result reports GemRequest::OperatorOnline.

Returns

Token of the submitted S1F1.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not connected or not in EquipmentOffline.

publishAlarm

Method

Sends S5F1 Alarm Report Send with the alarm's current state.

PdcommTcpToken publishAlarm(uint32_t id, bool replyExpected)

Declared in: #include <pdcomm_gem.hpp>

Requires GemCommunication::Communicating and reporting enabled by the host. With replyExpected the report uses a pending slot and the S5F2 reply yields GemOutcome::AlarmAck; without it, PDCOMM_TCP_W0_WRITTEN only means a local write.

Parameters

Name	Description
id	ALID.
replyExpected	Sets the W-bit.

Returns

Token of the submitted report.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating or reporting is disabled; PDCOMM_OUT_OF_RANGE for an unknown ALID.

publishEvent

Method

Sends S6F11 Event Report Send for an enabled collection event.

PdcommTcpToken publishEvent(uint32_t dataId, uint32_t eventId)

Declared in: #include <pdcomm_gem.hpp>

Values come from the configured sources (status variables, or bindings and caches). The message body is an independent snapshot. The S6F12 reply yields GemOutcome::EventAck with ACKC6. An event without linked reports is sent with an empty report list. Same as publishEventWithData() without samples.

Parameters

Name	Description
dataId	DATAID of the report.
eventId	CEID to report.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_INVALID_DATA when no report store exists or the event is unknown or disabled; PDCOMM_OUT_OF_RANGE when a report variable has no source.

publishEventWithData

Method

Sends S6F11 using supplied samples first, then caches, for an enabled event.

PdcommTcpToken publishEventWithData(uint32_t dataId, uint32_t eventId, const std::vector<GemDataSample> &samples = {})

Declared in: #include <pdcomm_gem.hpp>

Every sample, including unused ones, is validated. Samples never change caches. The whole report is built before submission, so the input items can change afterwards. The S6F12 reply yields GemOutcome::EventAck.

Parameters

Name	Description
dataId	DATAID of the report.
eventId	CEID to report.
samples	Data variable samples; borrowed for the call.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT for unknown or duplicate samples or a shape mismatch; PDCOMM_LIMIT_EXCEEDED for limits; PDCOMM_OUT_OF_RANGE when a report variable has no source; PDCOMM_INVALID_STATE for missing data or when not communicating; PDCOMM_INVALID_DATA for an unknown or disabled event. Caches, bindings and queued messages are unchanged on failure.

purgeSpool

Method

Deletes all stored spool entries locally.

GemSpoolWriteResult purgeSpool()

Declared in: #include <pdcomm_gem.hpp>

Requires a stopped endpoint with no transmission or dequeue pending.

Returns

PDCOMM_OK or PDCOMM_SPOOL_UNCONFIRMED with the number of removed entries.

Notes

• Throws pdcomm::Error: for other statuses, for example PDCOMM_INVALID_STATE.

registerStatus

Method

Registers a status variable (SVID) with its name, units and initial value.

void registerStatus(uint32_t id, const std::string &name, const std::string &units, const SecsItem &value)

Declared in: #include <pdcomm_gem.hpp>

Allowed only while the endpoint is stopped. The value is copied, and its top-level format becomes the declared format for later updates. On error the registry is unchanged.

Parameters

Name	Description
id	SVID; must be unique.
name	SVNAME, ASCII.
units	Units, ASCII; may be empty.
value	Initial value.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped; PDCOMM_INVALID_ARGUMENT for a duplicate ID or non-ASCII text; PDCOMM_LIMIT_EXCEEDED when registry limits are exceeded.

reportAt

Method

Returns one defined report in stored order.

GemReportDefinition reportAt(size_t index)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
index	Zero-based position, less than GemReportState::reportCount.

Returns

RPTID and VIDs.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index.

reportState

Method

Returns counters of the report store.

GemReportState reportState()

Declared in: #include <pdcomm_gem.hpp>

Returns

Event, report, variable and link counts.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when no report store is configured.

reportValue

Method

Resolves the current report value of a VID from its source.

SecsItem reportValue(uint32_t variableId)

Declared in: #include <pdcomm_gem.hpp>

Uses caches only; it does not check that a whole report would fit.

Parameters

Name	Description
variableId	VID to resolve.

Returns

An independently owned value item.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an unknown VID or source; PDCOMM_INVALID_STATE when a data variable has no cached value.

respondCommand

Method

Sends S2F42 for a received S2F41.

GemCommandReply respondCommand(GemResult &result, GemCommandAcknowledgement decision, const std::vector<GemCommandIssue> &issues = {})

Declared in: #include <pdcomm_gem.hpp>

Validation was frozen at receipt: a rejected request keeps its original HCACK and issues, whatever decision says. For an accepted request only GemCommandAcknowledgement::ParameterErrors may carry issues. The library executes nothing; start deferred work only after an HCACK 4 reply was submitted. If sending fails, retry with the same decision; never execute completed work again.

Parameters

Name	Description
result	Result with GemOutcome::CommandReceived from this endpoint.
decision	HCACK to send.
issues	CPACK entries (codes 1 to 3) for HCACK 3; borrowed for the call.

Returns

The HCACK actually sent and the completion CEID for HCACK 0 or 4; publish that event separately.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_STALE_TOKEN for a stale, consumed or already answered request; PDCOMM_INVALID_ARGUMENT for issues with another decision or invalid codes.
• This call changes result; do not run it concurrently with getters on it.

respondConstants

Method

Sends S2F16 for a received S2F15 using a named decision.

GemConstantReply respondConstants(GemResult &result, GemConstantDecision decision)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
result	Result with GemOutcome::ConstantChangesReceived from this endpoint.
decision	EAC to send.

Returns

The EAC sent and whether the store changed.

Notes

• Throws pdcomm::Error: Same statuses as the uint8_t overload.

respondConstants

Method

Sends S2F16 for a received S2F15.

GemConstantReply respondConstants(GemResult &result, uint8_t decision)

Declared in: #include <pdcomm_gem.hpp>

Only a successfully submitted EAC 0 swaps the new values into the SDK store; nothing is applied physically or persisted. A failed validation at receipt keeps its original EAC. If another change or reconfiguration happened since receipt, EAC 0 can no longer apply, but a rejection can still be sent. On send failure the stores stay unchanged and you can retry.

Parameters

Name	Description
result	Result with GemOutcome::ConstantChangesReceived from this endpoint.
decision	EAC: 0, 2, 3, or an application value from 4 to 63.

Returns

The EAC sent and whether the store changed.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_STALE_TOKEN for a stale, consumed or already answered request; PDCOMM_INVALID_ARGUMENT for an invalid decision.
• This call changes result; do not run it concurrently with getters on it.

respondEnhancedCommand

Method

Sends S2F50 for a received S2F49.

GemCommandReply respondEnhancedCommand(GemResult &result, GemCommandAcknowledgement decision, const SecsItem *acknowledgements = nullptr)

Declared in: #include <pdcomm_gem.hpp>

Admission and validation were frozen at receipt; a rejected request keeps its original reply and ignores acknowledgements. For an accepted request with GemCommandAcknowledgement::ParameterErrors, pass an outer list of L[name, ACK] entries; every other decision needs nullptr. Retry a failed send with the same arguments and never execute completed work again.

Parameters

Name	Description
result	Result with GemOutcome::EnhancedCommandReceived from this endpoint.
decision	HCACK to send.
acknowledgements	Outer acknowledgement list for HCACK 3, or nullptr. Borrowed.

Returns

The HCACK actually sent and the completion CEID for HCACK 0 or 4.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_STALE_TOKEN for a stale, consumed or already answered request; PDCOMM_INVALID_ARGUMENT for an acknowledgement list that does not match the decision; PDCOMM_LIMIT_EXCEEDED when max_errors or wire limits are exceeded.
• This call changes result; do not run it concurrently with getters on it.

respondReportQuery

Method

Answers a received S6F15, S6F19 or S6F21 with S6F16, S6F20 or S6F22.

void respondReportQuery(GemResult &result, const std::vector<GemDataSample> &samples = {})

Declared in: #include <pdcomm_gem.hpp>

Values use the report graph and caches at response time, with samples taking precedence. The complete reply is checked before it is sent. On failure the request stays unanswered and you can retry. No event acknowledgement is involved.

Parameters

Name	Description
result	Result with GemOutcome::ReportQueryReceived from this endpoint.
samples	Data variable samples, or empty for cache values only. Borrowed.

Notes

• Throws pdcomm::Error: PDCOMM_STALE_TOKEN for a stale, consumed or already answered request; PDCOMM_INVALID_ARGUMENT for invalid samples; PDCOMM_INVALID_STATE when data is unavailable.
• This call changes result; do not run it concurrently with getters on it.

setOnlineMode

Method

Sets the operator's REMOTE/LOCAL switch.

void setOnlineMode(GemOnlineMode mode)

Declared in: #include <pdcomm_gem.hpp>

Allowed in every control state. As in the SEMI E30 control state model, an online equipment moves to GemControl::OnlineLocal or GemControl::OnlineRemote at once; an offline equipment uses the mode the next time it goes online. No message is sent.

Parameters

Name	Description
mode	GemOnlineMode::Local or GemOnlineMode::Remote.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT for GemOnlineMode::Unavailable.

status

Method

Returns a copy of the current value of a status variable.

SecsItem status(uint32_t id)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
id	Registered SVID.

Returns

An independently owned item; it survives endpoint destruction.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an unknown ID.

statusIdAt

Method

Returns the SVID at a position in registration order.

uint32_t statusIdAt(size_t index)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
index	Zero-based position, less than GemState::variableCount.

Returns

The SVID.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an invalid index.

statusMetadata

Method

Returns the registered name and units of a status variable.

GemStatusName statusMetadata(uint32_t id)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
id	Registered SVID.

Returns

SVID, name and units.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an unknown ID.

syncSpool

Method

Synchronizes the spool with the current communication state.

GemSpoolWriteResult syncSpool(uint64_t now)

Declared in: #include <pdcomm_gem.hpp>

Call it after handling TCP and GEM events. It observes the actual connection and selection, activates spooling when communication is lost, and retries a failed activation. It never starts a transmission. Capture, respond and send calls require a current successful synchronization.

Parameters

Name	Description
now	Application timestamp stored as the spooling start or full time.

Returns

PDCOMM_OK or PDCOMM_SPOOL_UNCONFIRMED with the mutation details.

Notes

• Throws pdcomm::Error: for other statuses, for example PDCOMM_INVALID_STATE when spooling is not configured.

updateDataVariable

Method

Replaces the cached value of a data variable.

void updateDataVariable(uint32_t id, const SecsItem &value)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
id	DVID.
value	New value; must match the declared format and count range. Copied.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an unknown ID; PDCOMM_INVALID_ARGUMENT for a format or count mismatch; PDCOMM_LIMIT_EXCEEDED when value limits are exceeded.

updateStatus

Method

Replaces the current value of a registered status variable.

void updateStatus(uint32_t id, const SecsItem &value)

Declared in: #include <pdcomm_gem.hpp>

Allowed during operation. The value is copied and must keep the declared top-level format.

Parameters

Name	Description
id	Registered SVID.
value	New value.

Notes

• Throws pdcomm::Error: PDCOMM_OUT_OF_RANGE for an unknown ID; PDCOMM_INVALID_ARGUMENT for a format change; PDCOMM_LIMIT_EXCEEDED when value limits are exceeded.