pdcomm::GemHost

Class

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

class GemHost final : public GemEndpoint

Declared in: #include <pdcomm_gem.hpp>

The constructor configures the host role on a stopped TcpEndpoint. After start(), drive the endpoint with poll() and handleEvent(). Establish communication with beginCommunication() once the HSMS session is selected, then send requests. Every request method returns a PdcommTcpToken as soon as the message is queued; the reply, failure or timeout arrives later as a GemResult with the same token.

Requests share the endpoint's 32 native pending slots (PDCOMM_BACKPRESSURE when all are used) and the max_pending_ids budget for copied IDs (PDCOMM_LIMIT_EXCEEDED). Most requests need GemCommunication::Communicating and fail with PDCOMM_INVALID_STATE otherwise. Inputs are copied before the call returns.

Incoming S6F11 event reports and S5F1 alarm reports are never acknowledged automatically: call acknowledgeEvent() or acknowledgeAlarm() after your application has processed them.

const auto limits = pdcomm::secsLimits(4096, 4096, 128, 8);
pdcomm::TcpEndpoint transport(address, tcpOptions(PDCOMM_TCP_ACTIVE));
pdcomm::GemHost host(std::move(transport), pdcomm::gemHostOptions(limits, 64));
host.start();
// When host.tcp().state().state == PDCOMM_TCP_SELECTED:
host.beginCommunication();
// After a result with GemOutcome::CommunicationEstablished:
host.request(pdcomm::GemRequest::AreYouOnline);
host.request(pdcomm::GemRequest::StatusValues, {1, 2});

Notes

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

Members

GemHost

Constructor

Takes ownership of endpoint and configures it as a GEM host.

GemHost(TcpEndpoint &&endpoint, const PdcommGemHostOptions &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	Host options built with gemHostOptions().

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped or already has a GEM role; PDCOMM_INVALID_ARGUMENT for a wrong struct_size, version or item limits.

acknowledgeAlarm

Method

Sends S5F2 for a received S5F1 alarm report that expects a reply.

void acknowledgeAlarm(GemResult &result, uint8_t acknowledgement)

Declared in: #include <pdcomm_gem.hpp>

The result is marked acknowledged only after the reply is accepted for sending; after PDCOMM_ALLOCATION_FAILED or PDCOMM_BACKPRESSURE you may retry.

Parameters

Name	Description
result	Result with GemOutcome::AlarmReceived from this endpoint.
acknowledgement	ACKC5, 0 to 63 (0 means accepted).

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE for a report without W-bit; PDCOMM_STALE_TOKEN for a duplicate acknowledgement, another endpoint, an older connection or selection, or a consumed slot.
• This call changes result; do not run it concurrently with getters on it.

acknowledgeEvent

Method

Sends S6F12 for a received S6F11 event report.

void acknowledgeEvent(GemResult &result, uint8_t acknowledgement)

Declared in: #include <pdcomm_gem.hpp>

Acknowledge only after your application has accepted or rejected the report. On success the result is marked acknowledged. After PDCOMM_ALLOCATION_FAILED or PDCOMM_BACKPRESSURE you may retry the acknowledgement alone.

Parameters

Name	Description
result	Result with GemOutcome::EventReceived from this endpoint.
acknowledgement	ACKC6, 0 to 63 (0 means accepted).

Notes

• Throws pdcomm::Error: PDCOMM_STALE_TOKEN for a duplicate acknowledgement, another endpoint, an older connection or selection, or a consumed slot; PDCOMM_INVALID_ARGUMENT for a code above 63.
• This call changes result; do not run it concurrently with getters on it.

annotatedQuery

Method

Sends S6F21 Annotated Individual Report Request.

PdcommTcpToken annotatedQuery(uint32_t reportId)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
reportId	RPTID to report.

Returns

Token of the submitted request.

Notes

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

beginCommunication

Method

Sends S1F13 Establish Communications Request.

PdcommTcpToken beginCommunication()

Declared in: #include <pdcomm_gem.hpp>

Requires an HSMS-selected session in GemCommunication::NotCommunicating. The state becomes GemCommunication::WaitingAck; the S1F14 reply yields GemOutcome::CommunicationEstablished or GemOutcome::CommunicationRejected.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not connected or not in NotCommunicating; PDCOMM_BACKPRESSURE when no pending slot is free.

changeConstants

Method

Sends S2F15 New Equipment Constant Send.

PdcommTcpToken changeConstants(const std::vector<GemConstantChange> &changes)

Declared in: #include <pdcomm_gem.hpp>

The S2F16 reply yields GemOutcome::ConstantChangeAck with EAC. An EAC 0 does not tell the host whether a physical change took place.

Parameters

Name	Description
changes	(ECID, ECV) pairs; the items are borrowed for the call.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_INVALID_ARGUMENT for a nullptr item; PDCOMM_LIMIT_EXCEEDED when the message exceeds the item limits.

configureRemoteSpooling

Method

Sends S2F43 Reset Spooling Streams and Functions.

PdcommTcpToken configureRemoteSpooling(const std::vector<GemSpoolSelection> &selections)

Declared in: #include <pdcomm_gem.hpp>

Each stream with its functions counts against max_pending_items and the shared max_pending_ids while the request is pending. The S2F44 reply yields GemOutcome::SpoolConfigurationAck.

Parameters

Name	Description
selections	Streams to spool; an empty function list selects every primary of that stream. An empty vector turns spooling off for all streams.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when spool limits are not configured or the host is not communicating; PDCOMM_LIMIT_EXCEEDED when request limits are exceeded.

configureSpoolHost

Method

Enables the host spool requests (S2F43, S2F59, S6F23) with the given limits.

void configureSpoolHost(const GemSpoolHostOptions &options)

Declared in: #include <pdcomm_gem.hpp>

Call once while the endpoint is stopped. The host stores only request limits.

Parameters

Name	Description
options	Limits built with gemSpoolHostOptions().

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when the endpoint is not stopped or the limits are already set; PDCOMM_INVALID_ARGUMENT for invalid options.

constantMetadata

Method

Sends S2F29 Equipment Constant Namelist Request.

PdcommTcpToken constantMetadata(const std::vector<const SecsItem *> &ids = {})

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
ids	ECID items; empty asks for all constants.

Returns

Token of the submitted request.

Notes

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

constantRequest

Method

Sends S2F13 (values) or S2F29 (namelist) for equipment constants.

PdcommTcpToken constantRequest(GemConstantRequest kind, const std::vector<const SecsItem *> &ids = {})

Declared in: #include <pdcomm_gem.hpp>

Explicit IDs keep their order, duplicates and item format, and share max_pending_ids with status requests. The equipment, not the host, enforces ranges and formats.

Parameters

Name	Description
kind	GemConstantRequest::Values or GemConstantRequest::Metadata.
ids	ECID items, copied before sending; empty asks for all constants.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_LIMIT_EXCEEDED when the IDs exceed max_pending_ids or item limits; PDCOMM_INVALID_ARGUMENT for a nullptr ID.

constantValues

Method

Sends S2F13 Equipment Constant Request.

PdcommTcpToken constantValues(const std::vector<const SecsItem *> &ids = {})

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
ids	ECID items; empty asks for all constants.

Returns

Token of the submitted request.

Notes

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

dataDirectory

Method

Sends S1F21 Data Variable Namelist Request.

PdcommTcpToken dataDirectory(const std::vector<uint32_t> &ids = {})

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
ids	DVIDs; empty asks for all.

Returns

Token of the submitted request.

Notes

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

defineReports

Method

Sends S2F33 Define Report.

PdcommTcpToken defineReports(uint32_t dataId, const std::vector<GemReportSpec> &specs)

Declared in: #include <pdcomm_gem.hpp>

The S2F34 reply yields GemOutcome::DefineReportsAck with DRACK in GemResultInfo::acknowledgement.

Parameters

Name	Description
dataId	DATAID of the message.
specs	Reports to define. An empty vector deletes all reports and links; a spec with no VIDs deletes that report.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_LIMIT_EXCEEDED when the message exceeds the item limits.

directoryRequest

Method

Sends S1F21 (data variables) or S1F23 (collection events) namelist request.

PdcommTcpToken directoryRequest(GemDirectoryKind kind, const std::vector<uint32_t> &ids = {})

Declared in: #include <pdcomm_gem.hpp>

Explicit IDs keep their order, duplicates and unknown markers; a selected reply must return exactly those IDs in that order.

Parameters

Name	Description
kind	GemDirectoryKind::Data or GemDirectoryKind::Event.
ids	DVIDs or CEIDs, copied before sending; empty asks for all rows.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_LIMIT_EXCEEDED when the IDs exceed max_pending_ids or item limits.

enableAlarm

Method

Sends S5F3 Enable/Disable Alarm Send.

PdcommTcpToken enableAlarm(uint32_t id, bool enabled, bool replyExpected = true)

Declared in: #include <pdcomm_gem.hpp>

With replyExpected the S5F4 reply yields GemOutcome::AlarmEnableAck.

Parameters

Name	Description
id	ALID to change.
enabled	ALED: true to enable reporting, false to disable.
replyExpected	Sets the W-bit; without it no reply is expected.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_BACKPRESSURE when no pending slot is free.

enableEvents

Method

Sends S2F37 Enable/Disable Event Report.

PdcommTcpToken enableEvents(bool enabled, const std::vector<uint32_t> &eventIds = {})

Declared in: #include <pdcomm_gem.hpp>

The S2F38 reply yields GemOutcome::EnableEventsAck with ERACK.

Parameters

Name	Description
enabled	CEED: true to enable, false to disable.
eventIds	CEIDs to change; empty selects all events, linked or not. Only an unknown CEID is denied (ERACK 1).

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_LIMIT_EXCEEDED when the message exceeds the item limits.

enhancedRemoteCommand

Method

Sends S2F49 Enhanced Remote Command.

PdcommTcpToken enhancedRemoteCommand(uint32_t dataId, const SecsItem &object, const SecsItem &name, const std::vector<GemCommandParameter> &parameters = {})

Declared in: #include <pdcomm_gem.hpp>

The S2F50 reply yields GemOutcome::EnhancedCommandAck.

Parameters

Name	Description
dataId	DATAID of the message.
object	OBJSPEC; must be an ASCII item.
name	RCMD item.
parameters	(CPNAME, CEPVAL) pairs; values may be lists of any format except JIS-8. Borrowed for the call.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_INVALID_ARGUMENT for a non-ASCII object, a nullptr item, or a JIS-8 value; PDCOMM_LIMIT_EXCEEDED when the message exceeds the item limits.

eventDirectory

Method

Sends S1F23 Collection Event Namelist Request.

PdcommTcpToken eventDirectory(const std::vector<uint32_t> &ids = {})

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
ids	CEIDs; empty asks for all.

Returns

Token of the submitted request.

Notes

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

eventQuery

Method

Sends S6F15 Event Report Request.

PdcommTcpToken eventQuery(uint32_t eventId)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
eventId	CEID to report.

Returns

Token of the submitted request.

Notes

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

individualQuery

Method

Sends S6F19 Individual Report Request.

PdcommTcpToken individualQuery(uint32_t reportId)

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
reportId	RPTID to report.

Returns

Token of the submitted request.

Notes

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

linkReports

Method

Sends S2F35 Link Event Report.

PdcommTcpToken linkReports(uint32_t dataId, const std::vector<GemLinkSpec> &specs)

Declared in: #include <pdcomm_gem.hpp>

The S2F36 reply yields GemOutcome::LinkReportsAck with LRACK.

Parameters

Name	Description
dataId	DATAID of the message.
specs	Event links; an empty report list unlinks that event.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_LIMIT_EXCEEDED when the message exceeds the item limits.

programDelete

Method

Sends S7F17 Delete Process Program Send.

PdcommTcpToken programDelete(const std::vector<const SecsItem *> &ids = {})

Declared in: #include <pdcomm_gem.hpp>

Requires a program store (GemEndpoint::configurePrograms()). The S7F18 reply yields GemOutcome::ProgramAckReceived.

Parameters

Name	Description
ids	Program IDs to delete; an empty vector asks to delete all programs. The items are copied before the call returns.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating or no program store is configured; PDCOMM_LIMIT_EXCEEDED when ID budgets are exceeded.

programDirectory

Method

Sends S7F19 Current Process Program Directory Request (header only).

PdcommTcpToken programDirectory()

Declared in: #include <pdcomm_gem.hpp>

The S7F20 reply yields GemOutcome::ProgramDirectoryReceived; read the IDs with GemResult::programItem().

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating or no program store is configured.

queryRemoteSpooling

Method

Sends S2F59 to query the equipment's current spooling selection.

PdcommTcpToken queryRemoteSpooling()

Declared in: #include <pdcomm_gem.hpp>

The S2F60 reply yields GemOutcome::SpoolConfigurationData; read it with GemResult::spoolSelection().

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when spool limits are not configured or the host is not communicating.

remoteCommand

Method

Sends S2F41 Host Command Send.

PdcommTcpToken remoteCommand(const SecsItem &name, const std::vector<GemCommandParameter> &parameters = {})

Declared in: #include <pdcomm_gem.hpp>

The items are copied into a bounded message before the call returns. Success means the request was queued, not executed; the S2F42 reply yields GemOutcome::CommandAck.

Parameters

Name	Description
name	RCMD item (ASCII or integer).
parameters	(CPNAME, CPVAL) pairs; the pointed-to items are borrowed for the call.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_INVALID_ARGUMENT for a nullptr item; PDCOMM_LIMIT_EXCEEDED when the message exceeds the item limits.

reportQuery

Method

Sends one report query: S6F15, S6F19 or S6F21.

PdcommTcpToken reportQuery(GemRequest kind, uint32_t id)

Declared in: #include <pdcomm_gem.hpp>

The ID uses one max_pending_ids entry. An S6F16 reply must echo the requested CEID; S6F20 and S6F22 replies carry no RPTID.

Parameters

Name	Description
kind	GemRequest::EventQuery, GemRequest::IndividualQuery or GemRequest::AnnotatedQuery.
id	CEID for an event query, otherwise RPTID.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT for another kind; PDCOMM_INVALID_STATE when not communicating; PDCOMM_LIMIT_EXCEEDED when max_pending_ids is exhausted.

request

Method

Sends a basic stream 1 request.

PdcommTcpToken request(GemRequest requestKind, const std::vector<uint32_t> &ids = {})

Declared in: #include <pdcomm_gem.hpp>

Supported kinds: GemRequest::AreYouOnline (S1F1), GemRequest::StatusValues (S1F3), GemRequest::StatusNames (S1F11), GemRequest::Offline (S1F15) and GemRequest::Online (S1F17). Only the two status requests accept IDs.

Parameters

Name	Description
requestKind	Request to send.
ids	SVIDs for status requests, copied before sending; empty asks for all.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT for another kind or IDs on a non-status request; PDCOMM_INVALID_STATE when not communicating; PDCOMM_BACKPRESSURE when all pending slots are used; PDCOMM_LIMIT_EXCEEDED when the IDs exceed max_pending_ids.

requestAlarmList

Method

Sends S5F5 List Alarms Request.

PdcommTcpToken requestAlarmList(const std::vector<uint32_t> &ids = {})

Declared in: #include <pdcomm_gem.hpp>

Explicit IDs keep their order and duplicates; a successful S5F6 must return them in the same order. The reply yields GemOutcome::AlarmListReceived.

Parameters

Name	Description
ids	ALIDs, copied before sending; empty asks for all alarms.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating; PDCOMM_LIMIT_EXCEEDED when the IDs exceed max_pending_ids or item limits.

requestEnabledAlarmList

Method

Sends S5F7 List Enabled Alarm Request.

PdcommTcpToken requestEnabledAlarmList()

Declared in: #include <pdcomm_gem.hpp>

The S5F8 reply yields GemOutcome::EnabledAlarmListReceived.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when not communicating.

requestSpooledData

Method

Sends S6F23 Request Spooled Data.

PdcommTcpToken requestSpooledData(GemSpoolCommand command)

Declared in: #include <pdcomm_gem.hpp>

The S6F24 reply yields GemOutcome::SpoolControlAck with RSDA in GemResultInfo::acknowledgement. Spooled messages then arrive as normal primaries.

Parameters

Name	Description
command	Transmit or purge the spooled messages.

Returns

Token of the submitted request.

Notes

• Throws pdcomm::Error: PDCOMM_INVALID_STATE when spool limits are not configured or the host is not communicating.