PDComm.GemHost

Class

A synchronous GEM (SEMI E30) host endpoint over one HSMS TCP connection.

public sealed class GemHost : GemEndpoint

The host sends GEM requests and receives their replies as GemResult objects from GemEndpoint.HandleEvent; match a reply to its request with GemResultInfo.Token. It answers S1F1 (Are You There) and S1F13 (Establish Communications) from the equipment automatically. Request methods return when the transport accepts the message, not when the reply arrives. At most 32 GEM requests can be pending at once, and requested IDs share GemHostOptions.MaxPendingIds.

The application drives the endpoint with GemEndpoint.Poll, GemEndpoint.NextEvent and GemEndpoint.HandleEvent. Calls are serialized by an internal lock. To run the endpoint on a polling thread, use GemHostWorker.

using GemHost host = GemHost.Create("127.0.0.1:5000", transportOptions,
    new GemHostOptions { MaxPendingIds = 64, ItemLimits = limits });
host.Start();
bool began = false;
while (running)
{
    host.Poll();
    if (!began && host.GetTransportState().State == HsmsConnectionState.Selected)
    {
        host.BeginCommunication();
        began = true;
    }
    HsmsEvent? current;
    while ((current = host.NextEvent()) is not null)
    {
        using (current)
        using (GemResult result = host.HandleEvent(current))
        {
            GemResultInfo info = result.GetInfo();
            if (info.Kind != GemResultKind.Response) continue;
            if (info.Outcome == GemOutcome.CommunicationEstablished) host.AreYouOnline();
            else if (info.Outcome == GemOutcome.EquipmentIdentity) host.RequestStatusValues([1, 2]);
        }
    }
    Thread.Sleep(2);
}
host.Stop();

Members

`AcknowledgeAlarm`

Method

Sends the S5F2 (Alarm Report Acknowledge) reply to a received S5F1 alarm report.

public void AcknowledgeAlarm(GemResult result, byte acknowledgement)

The host never acknowledges alarm reports automatically. The result owns the report, so the original HsmsEvent may already be disposed. The result is marked acknowledged only after the reply is accepted for sending; after a backpressure or allocation failure the call can be retried. Calls are serialized with the getters of result.

Parameters

Name	Description
`result`	The result of the received alarm report (`GemOutcome.AlarmReceived`) whose W-bit is set.
`acknowledgement`	The acknowledge code (ACKC5), 0 through 63. 0 means accepted.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when acknowledgement is greater than 63 or result is not an alarm result; PdcommStatus.InvalidState when the result is a list reply or a report sent without the W-bit, or GEM communication is not established; PdcommStatus.StaleToken when the report was already acknowledged or belongs to another endpoint, connection or selection; PdcommStatus.Backpressure when the transport cannot accept the reply; or another native failure status.

`AcknowledgeEvent`

Method

Sends S6F12 (Event Report Acknowledge) for an event report received from the equipment.

public void AcknowledgeEvent(GemResult result, byte acknowledgement)

The host never acknowledges S6F11 automatically; call this method after the application accepted or rejected the report. On success the result is marked acknowledged (GemEventInfo.Acknowledged) and its GemResultInfo.Acknowledgement and GemResultInfo.ReplySent are updated. After an allocation or backpressure failure the result is unchanged, so the acknowledgement can be retried. The call holds the host's lock and the result's lock, so it does not race with the result's getters.

Parameters

Name	Description
`result`	The result of the received S6F11, whose outcome is `GemOutcome.EventReceived`.
`acknowledgement`	The acknowledge code (ACKC6), 0 to 63; 0 means accepted.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The host or result was disposed.
Throws PdcommException: The native call failed: PdcommStatus.InvalidArgument when acknowledgement is greater than 63 or the result is not a received event report, PdcommStatus.StaleToken when the event was already acknowledged or was received on another endpoint, connection or selection, or another status when the reply cannot be sent.

`AreYouOnline`

Method

Sends S1F1 (Are You There) to the equipment.

public HsmsToken AreYouOnline()

Requires GemCommunicationState.Communicating. A valid S1F2 reply produces GemOutcome.EquipmentIdentity; its body is the list of the model (MDLN) and software revision (SOFTREV).

Returns

The token of the request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when communication is not established; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`CancelProgramGrant`

Method

Withdraws the grant that an answered S7F1 request activated.

public void CancelProgramGrant(GemResult result)

The released grant no longer reserves store capacity, and a later S7F3 for it is not granted.

Parameters

Name	Description
`result`	The original S7F1 request result whose reply granted the program; a result for the same PPID is not enough.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.StaleToken when the result is not an answered S7F1 request with an outstanding grant, or belongs to another endpoint or an earlier connection or selection; PdcommStatus.InvalidState when the result is not a program result or communication is not established; PdcommStatus.Backpressure when a retained transport event must be read first.

`ChangeConstants`

Method

Sends S2F15 (New Equipment Constant Send) with new equipment constant values.

public HsmsToken ChangeConstants(ReadOnlySpan<GemConstantChange> changes)

Requires GemCommunicationState.Communicating. A valid S2F16 reply produces GemOutcome.ConstantChangeAck with the EAC in GemResultInfo.Acknowledgement. The host does not know the equipment's constant definitions; the equipment checks formats, counts and ranges, and an EAC of 0 does not prove that a physical setting changed.

Parameters

Name	Description
`changes`	The ECID/ECV pairs in request order. IDs must be ASCII items or scalar integer items. The items are copied.

Returns

The token of the request.

Notes

Throws ArgumentNullException: A change, or its ID or value, is null.
Throws ObjectDisposedException: The endpoint or an item of a change was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when an item or the message exceeds GemHostOptions.ItemLimits or a value contains a JIS-8 item; PdcommStatus.InvalidArgument when an ID is neither an ASCII item nor a scalar integer item; PdcommStatus.InvalidState when communication is not established; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`ConfigurePrograms`

Method

Installs the process program store and enables the stream 7 process program transactions.

public void ConfigurePrograms(GemProgramOptions options, string? path = null)

Call once while the endpoint is stopped. With a path, the store takes an exclusive writer lock through a lock file next to the storage file and loads and validates the stored programs; a missing file starts an empty store. When opening or loading fails, no store is installed and an existing file is left as it is. Every later change writes a complete new file, replaces the old one and synchronizes the parent directory; this file I/O runs synchronously on the calling thread. PPIDs are never used as file names.

Afterwards received S7F1, S7F3, S7F5, S7F17 and S7F19 primaries are reported as GemOutcome.ProgramReceived and wait for GemHost.RespondProgram; nothing is answered or stored automatically.

Parameters

Name	Description
`options`	The store limits, request budgets and grant policy.
`path`	The storage file path, or `null` or empty to keep the store in memory. The parent directory must exist.

Notes

Throws ArgumentNullException: options is null.
Throws ArgumentOutOfRangeException: GemProgramOptions.GrantPolicy is not a defined value.
Throws ArgumentException: path contains a NUL character or cannot be encoded as UTF-8.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint is not stopped or programs are already configured; PdcommStatus.Backpressure when a retained transport event is pending or another writer holds the storage lock; PdcommStatus.IoError when the file cannot be opened or read; PdcommStatus.InvalidArgument when path has no file name; PdcommStatus.InvalidData when the file is not a valid program store; PdcommStatus.LimitExceeded when the file is larger than GemProgramOptions.MaxSerializedBytes or its contents exceed the store limits.

`ConfigureSpoolHost`

Method

Enables the host spooling requests and sets their limits.

public void ConfigureSpoolHost(GemSpoolHostOptions options)

Call once before GemEndpoint.Start. The host keeps no spool of its own.

Parameters

Name	Description
`options`	The limits of the requests and of the replies the host accepts.

Notes

Throws ArgumentNullException: options is null.
Throws ObjectDisposedException: The host was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint was started or the spooling limits are already configured; PdcommStatus.Backpressure when a retained transport event is waiting to be read.

`ConfirmProgramReply`

Method

Accepts an unconfirmed installation so that its saved reply can be sent.

public void ConfirmProgramReply(GemResult result)

The call sends no reply and performs no synchronization; it sets the durability to GemProgramDurability.Confirmed and makes the saved reply ready. Send it by calling GemHost.RespondProgram again with the same mode and decision.

Parameters

Name	Description
`result`	The received S7F3 or S7F17 request whose `GemProgramInfo.ConfirmationRequired` is `true`.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the result holds no unconfirmed reply, is not a program result, or communication is not established; PdcommStatus.StaleToken when the request was already answered or belongs to another endpoint or an earlier connection or selection; PdcommStatus.Backpressure when a retained transport event must be read first.

`Create`

Method

Creates an HSMS endpoint and configures it as a GEM host.

public static GemHost Create(string numericAddress, HsmsOptions options, GemHostOptions gemOptions)

Parameters

Name	Description
`numericAddress`	The numeric IPv4 or IPv6 socket address, such as `127.0.0.1:5000`; no DNS lookup is done. A passive endpoint binds to it immediately (port 0 selects a free port); an active endpoint connects to it.
`options`	The HSMS transport options.
`gemOptions`	The GEM host options.

Returns

A stopped endpoint; call GemEndpoint.Start to start it.

Notes

Throws ArgumentNullException: numericAddress, options or gemOptions is null.
Throws PdcommException: The endpoint could not be created or configured, for example PdcommStatus.InvalidArgument for a non-numeric address or invalid transport options.

`DefineReports`

Method

Sends S2F33 (Define Report) to the equipment.

public HsmsToken DefineReports(uint dataId, ReadOnlySpan<GemReportSpec> reports)

Submission is not acknowledgement: the equipment's S2F34 later produces a result with GemOutcome.DefineReportsAck and the DRACK code (0 to 4) in GemResultInfo.Acknowledgement: 0 accepted, 1 insufficient space, 2 invalid format, 3 at least one RPTID already defined, and 4 at least one VID does not exist (SEMI E5). Calls are serialized with the endpoint's internal lock.

Parameters

Name	Description
`dataId`	The data ID (DATAID) of the request.
`reports`	The reports to define. An empty span asks the equipment to delete all reports and their links; a report with no variable IDs asks it to delete that report. The specifications are copied before the call returns.

Returns

The token that identifies the pending S2F33/S2F34 transaction.

Notes

Throws ObjectDisposedException: The host was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when the encoded request would exceed the host's item limits; otherwise the native status, for example PdcommStatus.InvalidState when the host is not communicating or PdcommStatus.Backpressure when no pending request slot is free.

`DeleteLocalPrograms`

Method

Deletes process programs from the local store.

public GemProgramWriteInfo DeleteLocalPrograms(ReadOnlySpan<SecsItem> ids)

Local changes require a stopped endpoint and involve no message. The change is validated and written to the storage file before it is committed in memory; a failure before installation leaves the store unchanged.

When the persistence cannot be confirmed, the method still returns: the change is installed and GemProgramWriteInfo.Durability is GemProgramDurability.Unconfirmed. Do not repeat the change as if it had been rolled back.

Parameters

Name	Description
`ids`	The distinct, stored PPIDs to delete, at most `GemProgramOptions.MaxRequestIds`; empty deletes every program.

Returns

Whether and how durably the change was installed.

Notes

Throws ArgumentNullException: An ID is null.
Throws ObjectDisposedException: The endpoint or an ID was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint is not stopped or programs are not configured; PdcommStatus.LimitExceeded when ids has more entries than GemProgramOptions.MaxRequestIds; PdcommStatus.InvalidArgument for an invalid or duplicate PPID; PdcommStatus.OutOfRange when a PPID is not stored; PdcommStatus.IoError when the storage file cannot be written; PdcommStatus.Backpressure when a retained transport event must be read first.

`DeletePrograms`

Method

Sends S7F17 (Delete Process Program Send) to delete process programs on the equipment.

public HsmsToken DeletePrograms(ReadOnlySpan<SecsItem> ids)

Requires GemCommunicationState.Communicating. The PPIDs count against GemProgramOptions.MaxPendingIds, GemProgramOptions.MaxPendingIdentifierBytes and GemHostOptions.MaxPendingIds until the request completes. A valid S7F18 reply produces GemOutcome.ProgramAckReceived with the ACKC7 in GemResultInfo.Acknowledgement.

Parameters

Name	Description
`ids`	The PPIDs to delete, each an ASCII or binary item, or empty to delete every program. The items are copied.

Returns

The token of the request.

Notes

Throws ArgumentNullException: An ID is null.
Throws ObjectDisposedException: The endpoint or an ID was disposed.
Throws PdcommException: PdcommStatus.InvalidState when programs are not configured or communication is not established; PdcommStatus.InvalidArgument when a PPID is empty or not an ASCII or binary item; PdcommStatus.LimitExceeded when ids has more entries than GemProgramOptions.MaxRequestIds or the remaining pending budgets, a PPID is longer than 120 bytes, or the message exceeds the item limits; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`EnableAlarm`

Method

Sends an S5F3 (Enable/Disable Alarm Send) request for one alarm.

public HsmsToken EnableAlarm(uint id, bool enabled, bool replyExpected)

With replyExpected the S5F4 reply arrives as a GemResult with GemOutcome.AlarmEnableAck and the received ACKC5 in GemResultInfo.Acknowledgement.

Parameters

Name	Description
`id`	The alarm ID (ALID).
`enabled`	`true` to enable reporting of the alarm (ALED 0x80); `false` to disable it (ALED 0).
`replyExpected`	`true` to set the W-bit and expect an S5F4 (Enable/Disable Alarm Acknowledge) reply.

Returns

The transport token of the accepted request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when GEM communication is not established, PdcommStatus.Backpressure when the transport or, with replyExpected, the pending request table is full, or another native failure status.

`EnableEvents`

Method

Sends S2F37 (Enable/Disable Event Report) to the equipment.

public HsmsToken EnableEvents(bool enabled, ReadOnlySpan<uint> eventIds)

Submission is not acknowledgement: the equipment's S2F38 later produces a result with GemOutcome.EnableEventsAck and the ERACK code (0 or 1) in GemResultInfo.Acknowledgement, where 0 means accepted. Calls are serialized with the endpoint's internal lock.

Parameters

Name	Description
`enabled`	The collection event enable/disable flag (CEED): `true` to enable, `false` to disable.
`eventIds`	The collection event IDs (CEIDs) to change. An empty span selects all events, linked or not. The IDs are copied before the call returns.

Returns

The token that identifies the pending S2F37/S2F38 transaction.

Notes

Throws ObjectDisposedException: The host was disposed.
Throws PdcommException: The native call failed, for example with PdcommStatus.InvalidState when the host is not communicating, PdcommStatus.LimitExceeded when the request would exceed the host's item limits, or PdcommStatus.Backpressure when no pending request slot is free.

`EnhancedRemoteCommand`

Method

Sends an S2F49 (Enhanced Remote Command) request.

public HsmsToken EnhancedRemoteCommand(uint dataId, SecsItem objectName, SecsItem name, ReadOnlySpan<GemCommandParameter> parameters)

The request always sets the W-bit. The items are copied into the outgoing message before the method returns. A returned token means the request was submitted, not that the command was executed. The S2F50 reply arrives as a GemResult with GemOutcome.EnhancedCommandAck; the received HCACK is in GemResultInfo.Acknowledgement and the parameter acknowledgements are read with GemResult.GetEnhancedCommandAcknowledgements.

Parameters

Name	Description
`dataId`	The data ID (DATAID), sent as U4.
`objectName`	The object specifier (OBJSPEC): an ASCII item.
`name`	The remote command name (RCMD): a nonempty ASCII item, or a scalar integer item from -128 through 255 (sent as I1 or U1).
`parameters`	The command parameters (CPNAME and CEPVAL) in wire order. Values may be nested lists and any format except JIS-8.

Returns

The transport token of the accepted request.

Notes

Throws ArgumentNullException: objectName, name, a parameter, or a parameter name or value is null.
Throws ObjectDisposedException: The endpoint or one of the items was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when objectName is not an ASCII item, name or a parameter name is not a valid identifier item, or a value contains a JIS-8 item; PdcommStatus.LimitExceeded when the parameter count or the message exceeds GemHostOptions.ItemLimits; PdcommStatus.InvalidState when GEM communication is not established; PdcommStatus.Backpressure when the transport or the pending request table is full; or another native failure status.

`GetProgram`

Method

Gets a copy of the body of a stored process program.

public SecsItem GetProgram(SecsItem id)

Parameters

Name	Description
`id`	The process program ID (PPID): an ASCII or binary item; the format is part of the identity.

Returns

A new item with the PPBODY that the caller owns and must dispose.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: The endpoint or id was disposed.
Throws InvalidOperationException: The native library returned no body.
Throws PdcommException: PdcommStatus.InvalidArgument when id is not an ASCII or binary item; PdcommStatus.OutOfRange when the PPID is not stored; PdcommStatus.InvalidState when programs are not configured; PdcommStatus.Backpressure when a retained transport event must be read first.

`GetProgramAt`

Method

Gets a copy of the stored process program at a position in the store.

public GemProgramEntry GetProgramAt(nuint index)

Parameters

Name	Description
`index`	The zero-based position, less than `GemProgramState.ProgramCount`.

Returns

A new entry with the PPID and PPBODY that the caller owns and must dispose.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when index is too large; PdcommStatus.InvalidState when programs are not configured; PdcommStatus.Backpressure when a retained transport event must be read first.

`GetProgramState`

Method

Gets the counters of the process program store.

public GemProgramState GetProgramState()

Returns

The program, byte and grant counts and whether the store has a storage file.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when programs are not configured; PdcommStatus.Backpressure when a retained transport event must be read first.

`GrantProgram`

Method

Sends S7F1 (Process Program Load Inquire) to ask the peer to accept a process program.

public HsmsToken GrantProgram(SecsItem id, uint length)

Requires GemCommunicationState.Communicating. The PPID counts against GemProgramOptions.MaxPendingIds, GemProgramOptions.MaxPendingIdentifierBytes and GemHostOptions.MaxPendingIds until the request completes. A valid S7F2 reply produces GemOutcome.ProgramGrantReceived with the PPGNT in GemResultInfo.Acknowledgement. Submission is not a grant; send the program with GemHost.SendProgram after a grant.

Parameters

Name	Description
`id`	The process program ID (PPID): an ASCII or binary item.
`length`	The length in bytes of the body payload that will be sent (LENGTH).

Returns

The token of the request.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: The endpoint or id was disposed.
Throws PdcommException: PdcommStatus.InvalidState when programs are not configured or communication is not established; PdcommStatus.InvalidArgument when the PPID is empty or not an ASCII or binary item; PdcommStatus.LimitExceeded when the PPID is longer than 120 bytes, the message exceeds the item limits, or the request would exceed GemProgramOptions.MaxPendingIds, GemProgramOptions.MaxPendingIdentifierBytes or GemHostOptions.MaxPendingIds; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`LinkReports`

Method

Sends S2F35 (Link Event Report) to the equipment.

public HsmsToken LinkReports(uint dataId, ReadOnlySpan<GemLinkSpec> links)

Submission is not acknowledgement: the equipment's S2F36 later produces a result with GemOutcome.LinkReportsAck and the LRACK code (0 to 5) in GemResultInfo.Acknowledgement, where 0 means accepted. Calls are serialized with the endpoint's internal lock.

Parameters

Name	Description
`dataId`	The data ID (DATAID) of the request.
`links`	The event links to add. An event with no report IDs asks the equipment to unlink all reports from that event. The specifications are copied before the call returns.

Returns

The token that identifies the pending S2F35/S2F36 transaction.

Notes

Throws ObjectDisposedException: The host was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when the encoded request would exceed the host's item limits; otherwise the native status, for example PdcommStatus.InvalidState when the host is not communicating or PdcommStatus.Backpressure when no pending request slot is free.

`PutProgram`

Method

Stores a process program in the local store.

public GemProgramWriteInfo PutProgram(SecsItem id, SecsItem body, GemProgramPutMode mode)

Parameters

Name	Description
`id`	The process program ID (PPID): a nonempty ASCII or binary item of at most `GemProgramOptions.MaxIdentifierBytes` and 120 bytes. The format is part of the identity.
`body`	The process program body (PPBODY): an ASCII, binary, `I1` to `I8` or `U1` to `U8` item, which may be empty. Its format and raw bytes are preserved.
`mode`	How to store the program when its PPID already exists.

Returns

Whether and how durably the change was installed.

Notes

Throws ArgumentOutOfRangeException: mode is not a defined value.
Throws ArgumentNullException: id or body is null.
Throws ObjectDisposedException: The endpoint, id or body was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint is not stopped or programs are not configured; PdcommStatus.InvalidArgument for an invalid PPID or body, for GemProgramPutMode.Create with a stored PPID, or for GemProgramPutMode.Replace with an unknown PPID; PdcommStatus.LimitExceeded when the program exceeds a store limit or GemProgramOptions.MaxSerializedBytes; PdcommStatus.IoError when the storage file cannot be written; PdcommStatus.Backpressure when a retained transport event must be read first.

`QueryRemoteSpooling`

Method

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

public HsmsToken QueryRemoteSpooling()

The S2F60 reply arrives as a GemResult with GemOutcome.SpoolConfigurationData; read each stream with GemResult.GetSpoolSelection.

Returns

The transport token of the request.

Notes

Throws ObjectDisposedException: The host was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the spooling limits are not configured or GEM communication is not established; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event is waiting to be read; or a transport failure.

`RemoteCommand`

Method

Sends an S2F41 (Host Command Send) remote command request.

public HsmsToken RemoteCommand(SecsItem name, ReadOnlySpan<GemCommandParameter> parameters)

The request always sets the W-bit. The items are copied into the outgoing message before the method returns. A returned token means the request was submitted, not that the command was executed. The S2F42 reply arrives as a GemResult with GemOutcome.CommandAck; the received HCACK is in GemResultInfo.Acknowledgement and the CPACK entries are read with GemResult.GetCommandIssue. The CPACK names are not matched against the request.

Parameters

Name	Description
`name`	The remote command name (RCMD): a nonempty ASCII item, or a scalar integer item from -128 through 255 (sent as I1 or U1).
`parameters`	The command parameters (CPNAME and CPVAL) in wire order.

Returns

The transport token of the accepted request.

Notes

Throws ArgumentNullException: name, a parameter, or a parameter name or value is null.
Throws ObjectDisposedException: The endpoint or one of the items was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when name or a parameter name is not a valid identifier item; PdcommStatus.LimitExceeded when the parameter count or the message exceeds GemHostOptions.ItemLimits; PdcommStatus.InvalidState when GEM communication is not established; PdcommStatus.Backpressure when the transport or the pending request table is full; or another native failure status.

`RequestAlarmList`

Method

Sends an S5F5 (List Alarms Request) for selected alarms or for all alarms.

public HsmsToken RequestAlarmList(ReadOnlySpan<uint> ids)

The request always expects a reply. The S5F6 reply arrives as a GemResult with GemOutcome.AlarmListReceived; read it with GemResult.GetAlarmInfo and GemResult.GetAlarmAt. For an explicit ID list, a successful reply must match the requested count and ID order.

Parameters

Name	Description
`ids`	The alarm IDs (ALID) to list, or an empty span to list every alarm. Order and duplicates are preserved.

Returns

The transport token of the accepted request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when the IDs, together with the IDs of other pending requests, exceed GemHostOptions.MaxPendingIds or the message exceeds GemHostOptions.ItemLimits; PdcommStatus.InvalidState when GEM communication is not established; PdcommStatus.Backpressure when the transport or the pending request table is full; or another native failure status.

`RequestAnnotatedQuery`

Method

Sends S6F21 (Annotated Individual Report Request) for a report.

public HsmsToken RequestAnnotatedQuery(uint id)

See GemHost.RequestReportQuery.

Parameters

Name	Description
`id`	The report ID (RPTID).

Returns

The token of the request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The request was not sent; see GemHost.RequestReportQuery.

`RequestConstantMetadata`

Method

Sends S2F29 (Equipment Constant Namelist Request) for equipment constant metadata.

public HsmsToken RequestConstantMetadata(ReadOnlySpan<SecsItem> ids)

Requires GemCommunicationState.Communicating. The IDs count against GemHostOptions.MaxPendingIds until the request completes. A valid S2F30 reply produces GemOutcome.ConstantMetadataReceived; read its fields (ECID, ECNAME, ECMIN, ECMAX, ECDEF, UNITS) with GemResult.GetConstantMetadata.

Parameters

Name	Description
`ids`	The equipment constant IDs (ECIDs), each an ASCII item or a scalar integer item, or empty to request every constant. Order and duplicates are kept. The items are copied.

Returns

The token of the request.

Notes

Throws ArgumentNullException: An ID is null.
Throws ObjectDisposedException: The endpoint or an ID was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when ids has more entries than GemHostOptions.MaxPendingIds allows together with the IDs of other pending requests, or an ID or the message exceeds GemHostOptions.ItemLimits; PdcommStatus.InvalidArgument when an ID is neither an ASCII item nor a scalar integer item; PdcommStatus.InvalidState when communication is not established; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`RequestConstantValues`

Method

Sends S2F13 (Equipment Constant Request) for equipment constant values.

public HsmsToken RequestConstantValues(ReadOnlySpan<SecsItem> ids)

Requires GemCommunicationState.Communicating. The IDs count against GemHostOptions.MaxPendingIds until the request completes. A valid S2F14 reply produces GemOutcome.ConstantValuesReceived; read its entries with GemResult.GetConstantValue. Submission is not a response; the equipment enforces its own formats and ranges.

Parameters

Name	Description
`ids`	The equipment constant IDs (ECIDs), each an ASCII item or a scalar integer item, or empty to request every constant. Order and duplicates are kept. The items are copied.

Returns

The token of the request.

Notes

Throws ArgumentNullException: An ID is null.
Throws ObjectDisposedException: The endpoint or an ID was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when ids has more entries than GemHostOptions.MaxPendingIds allows together with the IDs of other pending requests, or an ID or the message exceeds GemHostOptions.ItemLimits; PdcommStatus.InvalidArgument when an ID is neither an ASCII item nor a scalar integer item; PdcommStatus.InvalidState when communication is not established; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`RequestDataDirectory`

Method

Sends S1F21 (Data Variable Namelist Request) to the equipment.

public HsmsToken RequestDataDirectory(ReadOnlySpan<uint> ids)

Equivalent to GemHost.RequestDirectory with GemDirectoryKind.Data.

Parameters

Name	Description
`ids`	The variable IDs (VIDs) to request, or empty for all entries.

Returns

The token that identifies the pending S1F21/S1F22 transaction.

Notes

Throws ObjectDisposedException: The host was disposed.
Throws PdcommException: The request failed; see GemHost.RequestDirectory.

`RequestDirectory`

Method

Sends S1F21 (Data Variable Namelist Request) or S1F23 (Collection Event Namelist Request) to the equipment.

public HsmsToken RequestDirectory(GemDirectoryKind kind, ReadOnlySpan<uint> ids)

Submission is not a response. The equipment's S1F22 or S1F24 later produces a result with GemOutcome.DataDirectoryReceived or GemOutcome.EventDirectoryReceived; read the rows with GemResult.GetDirectoryAt and GemResult.GetDirectory. A reply to explicit IDs must list exactly the requested IDs in the same order. Empty names cannot show whether the equipment knows an ID.

Parameters

Name	Description
`kind`	The directory to request.
`ids`	The VIDs (for `GemDirectoryKind.Data`) or CEIDs (for `GemDirectoryKind.Event`) to request, or empty for all entries in the equipment's stored order. Order and duplicates are preserved, and the IDs are copied before the call returns.

Returns

The token that identifies the pending S1F21/S1F22 or S1F23/S1F24 transaction.

Notes

Throws ObjectDisposedException: The host was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when kind is not a defined value; PdcommStatus.LimitExceeded when ids has more entries than GemHostOptions.MaxPendingIds, the IDs of all pending requests would exceed that limit, or the request would exceed the item limits; or another native status, for example PdcommStatus.InvalidState when the host is not communicating or PdcommStatus.Backpressure when no pending request slot is free.

`RequestEnabledAlarmList`

Method

Sends an S5F7 (List Enabled Alarm Request) for the alarms whose reporting is enabled.

public HsmsToken RequestEnabledAlarmList()

The S5F8 reply arrives as a GemResult with GemOutcome.EnabledAlarmListReceived.

Returns

The transport token of the accepted request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when GEM communication is not established, PdcommStatus.Backpressure when the transport or the pending request table is full, or another native failure status.

`RequestEventDirectory`

Method

Sends S1F23 (Collection Event Namelist Request) to the equipment.

public HsmsToken RequestEventDirectory(ReadOnlySpan<uint> ids)

Equivalent to GemHost.RequestDirectory with GemDirectoryKind.Event.

Parameters

Name	Description
`ids`	The collection event IDs (CEIDs) to request, or empty for all entries.

Returns

The token that identifies the pending S1F23/S1F24 transaction.

Notes

Throws ObjectDisposedException: The host was disposed.
Throws PdcommException: The request failed; see GemHost.RequestDirectory.

`RequestEventQuery`

Method

Sends S6F15 (Event Report Request) for a collection event.

public HsmsToken RequestEventQuery(uint id)

See GemHost.RequestReportQuery.

Parameters

Name	Description
`id`	The collection event ID (CEID).

Returns

The token of the request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The request was not sent; see GemHost.RequestReportQuery.

`RequestIndividualQuery`

Method

Sends S6F19 (Individual Report Request) for a report.

public HsmsToken RequestIndividualQuery(uint id)

See GemHost.RequestReportQuery.

Parameters

Name	Description
`id`	The report ID (RPTID).

Returns

The token of the request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The request was not sent; see GemHost.RequestReportQuery.

`RequestOffline`

Method

Sends S1F15 (Request Off-line) to the equipment.

public HsmsToken RequestOffline()

A valid S1F16 reply produces GemOutcome.OfflineAck with OFLACK in GemResultInfo.Acknowledgement. Requires GemCommunicationState.Communicating.

Returns

The token of the request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when communication is not established; PdcommStatus.Backpressure when all 32 pending request slots are in use.

`RequestOnline`

Method

Sends S1F17 (Request On-line) to the equipment.

public HsmsToken RequestOnline()

A valid S1F18 reply produces GemOutcome.OnlineAck with ONLACK in GemResultInfo.Acknowledgement: 0 accepted, 1 not allowed, 2 already on-line. Requires GemCommunicationState.Communicating.

Returns

The token of the request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when communication is not established; PdcommStatus.Backpressure when all 32 pending request slots are in use.

`RequestProgram`

Method

Sends S7F5 (Process Program Request) for a process program of the peer.

public HsmsToken RequestProgram(SecsItem id)

Requires GemCommunicationState.Communicating. The PPID counts against GemProgramOptions.MaxPendingIds, GemProgramOptions.MaxPendingIdentifierBytes and GemHostOptions.MaxPendingIds until the request completes. A valid S7F6 reply produces GemOutcome.ProgramDataReceived; GemResult.GetProgramBody returns the body, or null when the peer does not have the program. The received program is not stored.

Parameters

Name	Description
`id`	The process program ID (PPID): an ASCII or binary item.

Returns

The token of the request.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: The endpoint or id was disposed.
Throws PdcommException: PdcommStatus.InvalidState when programs are not configured or communication is not established; PdcommStatus.InvalidArgument when the PPID is empty or not an ASCII or binary item; PdcommStatus.LimitExceeded when the PPID is longer than 120 bytes, the message exceeds the item limits, or the request would exceed GemProgramOptions.MaxPendingIds, GemProgramOptions.MaxPendingIdentifierBytes or GemHostOptions.MaxPendingIds; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`RequestProgramDirectory`

Method

Sends the header-only S7F19 (Current EPPD Request) for the equipment's process program list.

public HsmsToken RequestProgramDirectory()

Requires GemCommunicationState.Communicating. A valid S7F20 reply produces GemOutcome.ProgramDirectoryReceived; read the PPIDs with GemResult.GetProgramId up to GemProgramInfo.IdCount.

Returns

The token of the request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when programs are not configured or communication is not established; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`RequestReportQuery`

Method

Sends an S6 report query to the equipment.

public HsmsToken RequestReportQuery(GemReportQueryKind kind, uint id)

The ID consumes one entry of GemHostOptions.MaxPendingIds until the request completes. A valid reply produces GemOutcome.EventQueryReceived, GemOutcome.IndividualQueryReceived or GemOutcome.AnnotatedQueryReceived; read it with GemResult.GetQueryInfo, GemResult.GetQueryReport and GemResult.GetQueryValue. An S6F16 reply must echo the requested CEID. An empty reply alone does not show whether the ID is defined.

Parameters

Name	Description
`kind`	The query: `GemReportQueryKind.Event` sends S6F15, `GemReportQueryKind.Individual` sends S6F19, and `GemReportQueryKind.Annotated` sends S6F21.
`id`	The collection event ID (CEID) for an event query, otherwise the report ID (RPTID).

Returns

The token of the request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument for an undefined kind; PdcommStatus.InvalidState when communication is not established; PdcommStatus.LimitExceeded when no pending ID entry is left; PdcommStatus.Backpressure when all 32 pending request slots are in use.

`RequestSpoolConfiguration`

Method

Sends S2F43 (Reset Spooling Streams and Functions) to set the equipment's spooling selection.

public HsmsToken RequestSpoolConfiguration(ReadOnlySpan<GemSpoolSelection> selections)

The S2F44 reply arrives as a GemResult with GemOutcome.SpoolConfigurationAck. Read RSPACK from GemSpoolInfo.Acknowledgement of GemResult.GetSpoolInfo (0 accepted, 1 rejected) and each rejected stream with GemResult.GetSpoolError.

Parameters

Name	Description
`selections`	The streams to spool, without repetition. An empty function list requests every function of the stream, and an empty span requests that no stream be spooled. The values are copied.

Returns

The transport token of the request.

Notes

Throws ObjectDisposedException: The host was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the spooling limits are not configured or GEM communication is not established; PdcommStatus.LimitExceeded when the selections exceed GemSpoolHostOptions.MaxStreams, GemSpoolHostOptions.MaxFunctionsPerStream, GemSpoolHostOptions.MaxPendingItems, the remaining GemHostOptions.MaxPendingIds or the item limits, or repeat a stream or function; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event is waiting to be read; or a transport failure.

`RequestSpooledData`

Method

Sends S6F23 (Request Spooled Data) to make the equipment transmit or purge its spool.

public HsmsToken RequestSpooledData(GemSpoolCommand command)

The S6F24 reply arrives as a GemResult with GemOutcome.SpoolControlAck; read RSDA from GemSpoolInfo.Acknowledgement of GemResult.GetSpoolInfo. A PDComm equipment answers 0 when it accepts, 1 while a transmission or delivery is pending, and 2 when its spool is empty. After an accepted Transmit, it sends each spooled primary message with its original stream and function.

Parameters

Name	Description
`command`	The request spooled data code (RSDC).

Returns

The transport token of the request.

Notes

Throws ArgumentOutOfRangeException: command is not a defined GemSpoolCommand value.
Throws ObjectDisposedException: The host was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the spooling limits are not configured or GEM communication is not established; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event is waiting to be read; or a transport failure.

`RequestStatusNames`

Method

Sends S1F11 (Status Variable Namelist Request) for status variable names and units.

public HsmsToken RequestStatusNames(ReadOnlySpan<uint> ids)

The IDs are copied before the method returns and count against GemHostOptions.MaxPendingIds until the request completes. A valid S1F12 reply produces GemOutcome.NamesReceived; read the entries with GemResult.GetStatusName. Requires GemCommunicationState.Communicating.

Parameters

Name	Description
`ids`	The status variable IDs (SVIDs) to describe; an empty span requests all variables.

Returns

The token of the request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when communication is not established; PdcommStatus.LimitExceeded when the IDs exceed the remaining pending ID budget or the item limits; PdcommStatus.Backpressure when all 32 pending request slots are in use.

`RequestStatusValues`

Method

Sends S1F3 (Selected Equipment Status Request) for status variable values.

public HsmsToken RequestStatusValues(ReadOnlySpan<uint> ids)

The IDs are copied before the method returns and count against GemHostOptions.MaxPendingIds until the request completes. A valid S1F4 reply produces GemOutcome.ValuesReceived; read the values with GemResult.GetStatusValue. A reply with a different number of values than requested IDs is reported as GemResultKind.InvalidResponse with GemError.Correlation. Requires GemCommunicationState.Communicating.

Parameters

Name	Description
`ids`	The status variable IDs (SVIDs) to read, in reply order; an empty span requests all values.

Returns

The token of the request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when communication is not established; PdcommStatus.LimitExceeded when the IDs exceed the remaining pending ID budget or the item limits; PdcommStatus.Backpressure when all 32 pending request slots are in use.

`RespondProgram`

Method

Answers a received stream 7 process program request.

public void RespondProgram(GemResult result, GemProgramPutMode mode, byte decision)

Sends S7F2, S7F4, S7F6, S7F18 or S7F20. The store's own checks take precedence over an accepting decision: the grant policy, the store and grant limits, the declared length, the mode and the existence of the PPID can still reject the request with the matching PPGNT or ACKC7. An S7F17 that names more PPIDs than GemProgramOptions.MaxRequestIds is answered with ACKC7 3 (matrix overflow) and one that names a PPID that is not stored with ACKC7 4 (PPID not found); a repeated PPID is deleted once. S7F6 carries the stored program, or an empty PPID and body for an unknown PPID, and S7F20 lists the stored PPIDs. Storing a program or acknowledging it does not select or run a process.

For an accepted S7F3 or S7F17, the change is written and committed before the acknowledgement is sent, and the result keeps the prepared reply. If sending fails, for example with PdcommStatus.Backpressure, the change may already be applied; call again with the same mode and decision to send only the saved reply. When the persistence cannot be confirmed, the change stays installed, no reply is sent and the method throws PdcommStatus.ProgramUnconfirmed; optionally call GemHost.ResyncPrograms, then GemHost.ConfirmProgramReply, and then call this method again with the same arguments.

A grant becomes active only after S7F2 was queued; it ends when the matching S7F3 is stored, when the connection ends, or with GemHost.CancelProgramGrant.

Parameters

Name	Description
`result`	The result with outcome `GemOutcome.ProgramReceived`.
`mode`	How a granted (S7F1) or received (S7F3) program is stored when its PPID exists. Must be a defined value for every request kind.
`decision`	The application decision. For S7F1, 0 grants and 1 to 5 reject with PPGNT 1 (already have), 2 (no space), 3 (invalid PPID), 4 (busy) or 5 (will not accept). For S7F3 and S7F17, 0 accepts and 1 to 5 reject with ACKC7 1 (permission not granted), 2 (length error), 3 (matrix overflow), 4 (PPID not found) or 5 (mode unsupported). S7F5 and S7F19 require 0.

Notes

Throws ArgumentNullException: result is null.
Throws ArgumentOutOfRangeException: mode is not a defined value.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.ProgramUnconfirmed when the change was installed but its persistence could not be confirmed; PdcommStatus.StaleToken when the request was already answered or belongs to another endpoint or an earlier connection or selection; PdcommStatus.InvalidArgument when decision is not valid for the request kind, or a retry uses another mode or decision; PdcommStatus.InvalidState when the result is not a received program request, programs are not configured or communication is not established; PdcommStatus.IoError or PdcommStatus.LimitExceeded when the change cannot be written, which leaves the store unchanged; PdcommStatus.Backpressure when a retained transport event must be read first or the transport cannot accept the reply.

`ResyncPrograms`

Method

Synchronizes the parent directory of the storage file again.

public void ResyncPrograms()

Use it after an unconfirmed change when the application needs a confirmed directory synchronization, for example before GemHost.ConfirmProgramReply. It never rewrites program data, never changes the reported durability of an earlier change, and never confirms a retained reply.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when programs are not configured or the store is kept in memory; PdcommStatus.IoError when the synchronization fails; PdcommStatus.Backpressure when a retained transport event must be read first.

`SendProgram`

Method

Sends S7F3 (Process Program Send) with a process program.

public HsmsToken SendProgram(SecsItem id, SecsItem body)

Requires GemCommunicationState.Communicating. The PPID counts against GemProgramOptions.MaxPendingIds, GemProgramOptions.MaxPendingIdentifierBytes and GemHostOptions.MaxPendingIds until the request completes. A valid S7F4 reply produces GemOutcome.ProgramAckReceived with the ACKC7 in GemResultInfo.Acknowledgement; the reply does not show how durably the peer stored the program.

Parameters

Name	Description
`id`	The process program ID (PPID): an ASCII or binary item.
`body`	The process program body (PPBODY): an ASCII, binary, `I1` to `I8` or `U1` to `U8` item.

Returns

The token of the request.

Notes

Throws ArgumentNullException: id or body is null.
Throws ObjectDisposedException: The endpoint, id or body was disposed.
Throws PdcommException: PdcommStatus.InvalidState when programs are not configured or communication is not established; PdcommStatus.InvalidArgument when the PPID is empty or not an ASCII or binary item, or body has an unsupported format; PdcommStatus.LimitExceeded when the PPID is longer than 120 bytes, the message exceeds the item limits, or the request would exceed GemProgramOptions.MaxPendingIds, GemProgramOptions.MaxPendingIdentifierBytes or GemHostOptions.MaxPendingIds; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.