PDComm.GemEquipment

Class

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

public sealed class GemEquipment : GemEndpoint

The equipment answers standard host requests automatically: S1F1 (Are You There) with its model and software revision, S1F3 and S1F11 from the registered status variables, S1F13 (Establish Communications), and S1F15 and S1F17 (Off-line and On-line requests) according to its control state. Feature areas such as reports, alarms, remote commands, constants, data variables and process programs are configured with the other members of this class.

The application drives the endpoint with GemEndpoint.Poll, GemEndpoint.NextEvent and GemEndpoint.HandleEvent. Calls are serialized by an internal lock. Most GEM operations fail with PdcommStatus.Backpressure while a transport event that GemEndpoint.NextEvent kept after an allocation failure is still waiting to be read. To run the endpoint on a polling thread, use GemEquipmentWorker.

using GemEquipment equipment = GemEquipment.Create("127.0.0.1:5000", transportOptions, new GemEquipmentOptions
{
    Model = "PDComm", SoftwareRevision = "0.1.0", InitialControl = GemControlState.HostOffline,
    OnlineMode = GemOnlineMode.Remote, MaxVariables = 8, MaxMetadataBytes = 1024, MaxValueBytes = 8192,
    ItemLimits = limits,
});
using (SecsItem temperature = SecsItem.FromF4([21.5f], limits))
    equipment.RegisterStatus(1, "Temperature", "C", temperature);
equipment.Start();
while (running)
{
    equipment.Poll();
    HsmsEvent? current;
    while ((current = equipment.NextEvent()) is not null)
    {
        using (current)
        using (GemResult result = equipment.HandleEvent(current))
        {
            GemResultInfo info = result.GetInfo();
            if (info.Kind != GemResultKind.Ignored)
                Console.WriteLine($"{info.Kind} {info.RequestKind} {info.Outcome}");
        }
    }
    Thread.Sleep(2);
}
equipment.Stop();

Members

`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.

`CaptureSpool`

Method

Stores a primary message in the spool if spooling is active and the message is selected.

public GemSpoolWriteResult CaptureSpool(byte stream, byte function, bool wait, SecsItem? body, ulong now)

Capturing sends nothing. A stored entry is sent later with GemEquipment.SendNextSpool after the host requests transmission with S6F23.

Parameters

Name	Description
`stream`	The stream, 2 to 127.
`function`	The function of a primary message, an odd number.
`wait`	`true` to deliver the message later with the W-bit set; not allowed with function 255.
`body`	The message body, or `null` for a header-only message. It is copied.
`now`	An application timestamp stored as the capture time of the entry.

Returns

GemSpoolMutation.Captured with the new GemSpoolWriteResult.EntryId; GemSpoolMutation.Discarded when the spool is full and the message was dropped; or GemSpoolWriteResult.Selected false when spooling is inactive or disabled or the message is not cataloged and selected.

Notes

Throws ObjectDisposedException: The equipment or body was disposed.
Throws PdcommException: PdcommStatus.InvalidState when spooling is not configured or not synchronized; PdcommStatus.InvalidArgument when stream and function do not form a spoolable primary message; PdcommStatus.LimitExceeded when the body exceeds GemSpoolOptions.MaxBodyBytes, GemSpoolOptions.MaxTotalBodyBytes or the item limits; PdcommStatus.Backpressure when GemSpoolOverflow.OverwriteOldest could make room only by removing the entry being delivered, or a retained transport event is waiting to be read; or the status of a failed snapshot write, such as PdcommStatus.IoError.

`CaptureSpoolAlarm`

Method

Builds an S5F1 (Alarm Report Send) as GemEquipment.PublishAlarm does and stores it in the spool instead of sending it.

public GemSpoolWriteResult CaptureSpoolAlarm(uint alarmId, bool wait, ulong now)

The report carries the current alarm state; capturing does not change it.

Parameters

Name	Description
`alarmId`	The alarm ID (ALID) of a configured alarm with reporting enabled.
`wait`	`true` to deliver the report later with the W-bit set.
`now`	An application timestamp stored as the capture time of the entry.

Returns

The capture outcome, as for GemEquipment.CaptureSpool.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when spooling is not configured or not synchronized, alarms are not configured, or the alarm is unknown or its reporting is disabled; or the statuses of GemEquipment.CaptureSpool.

`CaptureSpoolEvent`

Method

Builds an S6F11 (Event Report Send) as GemEquipment.PublishEventWithData does and stores it in the spool instead of sending it.

public GemSpoolWriteResult CaptureSpoolEvent(uint dataId, uint eventId, ReadOnlySpan<GemDataSample> samples, ulong now)

The report is stored with the W-bit set.

Parameters

Name	Description
`dataId`	The data ID (DATAID) placed in the message.
`eventId`	The collection event ID (CEID) of an enabled event, linked or not.
`samples`	Data variable values for this report only; the items are copied.
`now`	An application timestamp stored as the capture time of the entry.

Returns

The capture outcome, as for GemEquipment.CaptureSpool.

Notes

Throws ArgumentNullException: A sample or its value is null.
Throws ObjectDisposedException: The equipment or a sample value was disposed.
Throws PdcommException: PdcommStatus.InvalidState when spooling is not configured or not synchronized, reports are not configured, or the event is unknown or disabled; PdcommStatus.LimitExceeded, PdcommStatus.InvalidArgument or PdcommStatus.InvalidState when the samples are rejected; or the statuses of GemEquipment.CaptureSpool.

`ClearDataVariable`

Method

Removes the cached value of a data variable.

public void ClearDataVariable(uint id)

Afterwards, an event report that needs the variable fails with PdcommStatus.InvalidState unless a sample supplies the value.

Parameters

Name	Description
`id`	The data variable ID.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed: PdcommStatus.OutOfRange for an unknown ID, or PdcommStatus.InvalidState when no data variable store is configured.

`ClearReportBindings`

Method

Removes the explicit report variable bindings.

public void ClearReportBindings()

Call while the endpoint is stopped. Afterwards each VID resolves to the status variable with the same ID.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed: PdcommStatus.InvalidState when the endpoint is not stopped, or PdcommStatus.InvalidArgument when a defined report uses a VID that is not a status variable ID or the event directory lists variables, which need data bindings.

`CompleteSpoolDelivery`

Method

Reports the application's verdict on a delivery and, on success, removes the delivered entry from the spool.

public GemSpoolWriteResult CompleteSpoolDelivery(GemResult result, bool success)

Inspect the reply body and apply the policy of the message, for example ACKC6 0 for S6F11; a matching function alone does not prove success. For an entry without the W-bit, success means only that the frame was written.

When the success is accepted but the removal fails, the method throws the persistence status while GemResult.GetSpoolInfo reports GemSpoolInfo.SuccessAccepted and GemSpoolInfo.DequeuePending; finish with GemEquipment.RetrySpoolDequeue instead of sending the entry again. Delivery is not exactly once: after an uncertain outcome, recovery may send an entry twice.

Parameters

Name	Description
`result`	The `GemOutcome.SpoolDeliveryResponse` or `GemOutcome.SpoolDeliveryWritten` result of the current delivery.
`success`	`true` to accept the delivery; `false` to keep the entry and end the transmission run.

Returns

On success, GemSpoolMutation.Removed with the removed GemSpoolWriteResult.EntryId; otherwise a result with no change.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The equipment or result was disposed.
Throws PdcommException: PdcommStatus.StaleToken when the result belongs to another endpoint, connection or selection, is not the current delivery, or was already completed; PdcommStatus.InvalidState when the result carries no delivery proof, GEM communication is not established, or the spool is not synchronized; PdcommStatus.Backpressure when a retained transport event is waiting to be read; or the status of a failed snapshot write when the entry could not be removed.

`ConfigureAlarms`

Method

Installs the alarm store that backs S5F1 alarm reports and the automatic replies to S5F3, S5F5 and S5F7.

public void ConfigureAlarms(GemAlarmOptions options, ReadOnlySpan<GemAlarmDefinition> definitions)

Call this method once while the endpoint is stopped, for example before GemEndpoint.Start. Configure reports first when definitions use set or clear events. The complete store is validated before it is installed, so a failure leaves the endpoint without alarms. All alarms start inactive and disabled.

After installation the endpoint handles S5F3 (Enable/Disable Alarm Send) automatically: it updates the enabled state of a configured alarm and, when a reply is expected, answers with ACKC5 0 for a configured alarm and 1 for an unknown one. It also answers S5F5 (List Alarms Request) and S5F7 (List Enabled Alarms Request) from the store.

Parameters

Name	Description
`options`	The alarm store limits.
`definitions`	The alarm definitions in registration order. The span is copied before the call returns.

Notes

Throws ArgumentNullException: options is null.
Throws ArgumentException: A definition has a null text or a text with non-ASCII characters.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when the definition count, one text or the combined text size exceeds options or the 120-byte text limit; PdcommStatus.InvalidArgument when a category is outside 1 through 63, an alarm ID is duplicated, GemAlarmOptions.MaxAlarms is zero, or a set or clear event is not a configured report event; PdcommStatus.InvalidState when the endpoint is not stopped or alarms are already configured; or another native failure status.

`ConfigureCommands`

Method

Installs the remote command store used to validate received S2F41 (Host Command Send) requests.

public void ConfigureCommands(GemCommandOptions options, ReadOnlySpan<GemCommandDefinition> definitions)

Call this method once while the endpoint is stopped, for example before GemEndpoint.Start. Configure reports first when definitions use completion events. The complete store is validated before it is installed, so a failure leaves the endpoint without commands.

After installation a received S2F41 is validated against the store and delivered as a GemResult with GemOutcome.CommandReceived. Nothing is executed or acknowledged automatically; reply with GemEquipment.RespondCommand.

Parameters

Name	Description
`options`	The command store limits.
`definitions`	The command definitions in registration order. The definitions and their name items are read only during the call.

Notes

Throws ArgumentNullException: options, a definition, a parameter definition, or one of their names is null.
Throws ObjectDisposedException: The endpoint or a name item was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when a count or name size exceeds options; PdcommStatus.InvalidArgument when a name is invalid or duplicated, a format or count range is invalid, numeric bounds lack an integer format or are reversed, GemCommandOptions.MaxCommands is zero, or a completion event is not a configured report event; PdcommStatus.InvalidState when the endpoint is not stopped or commands are already configured; or another native failure status.

`ConfigureConstants`

Method

Installs the equipment constant store that answers S2F13, S2F29 and S2F15.

public void ConfigureConstants(GemConstantOptions options, ReadOnlySpan<GemConstantDefinition> definitions)

Call once while the endpoint is stopped. The complete store is validated before it is installed; a failure changes nothing. See GemConstantDefinition for the rules for IDs, formats, counts and bounds.

Once configured, the equipment answers S2F13 (Equipment Constant Request) with S2F14 and S2F29 (Equipment Constant Namelist Request) with S2F30 automatically. An S2F15 (New Equipment Constant Send) request is reported as GemOutcome.ConstantChangesReceived and waits for GemEquipment.RespondConstants.

Parameters

Name	Description
`options`	The store limits.
`definitions`	The constants in registration order. The items and strings are read only during the call; the caller keeps ownership.

Notes

Throws ArgumentNullException: options, a definition, or its GemConstantDefinition.Id, GemConstantDefinition.Current, GemConstantDefinition.Name or GemConstantDefinition.Units is null.
Throws ArgumentException: A name or units string contains a non-ASCII character.
Throws ObjectDisposedException: The endpoint or a definition item was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when the definitions exceed GemConstantOptions.MaxConstants, GemConstantOptions.MaxIdentifierBytes, GemConstantOptions.MaxMetadataBytes, GemConstantOptions.MaxValueBytes or GemConstantOptions.ItemLimits; PdcommStatus.InvalidState when the endpoint is not stopped, a retained transport event is pending or constants are already configured; PdcommStatus.InvalidArgument for invalid options or an invalid definition, such as a duplicate or malformed ID, a format mismatch, a count outside the range, invalid bounds, list metadata, a JIS-8 item or a NaN value.

`ConfigureDataVariables`

Method

Configures or replaces the equipment's data variable store.

public void ConfigureDataVariables(GemDataOptions options, ReadOnlySpan<GemDataDefinition> definitions)

Call while the endpoint is stopped. A failed call keeps the previous store and counters. The equipment never samples, updates or persists values on its own: update cached values with GemEquipment.UpdateDataVariable or supply samples with GemEquipment.PublishEventWithData. After a successful call, those methods check values against GemDataOptions.ItemLimits before calling the native library.

Parameters

Name	Description
`options`	The capacity limits of the store.
`definitions`	The data variable definitions in stored order. Names, units and cached values are copied.

Notes

Throws ArgumentNullException: options, a definition, or its name or units is null.
Throws ArgumentException: A name or units string contains non-ASCII characters.
Throws ObjectDisposedException: The equipment or a cached value item was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when GemDataOptions.MaxVariables or an item limit is zero, an ID is duplicated, a format is not a SECS-II data format, the minimum count exceeds the maximum count, or a cached value does not match its format and count range; PdcommStatus.LimitExceeded when the definitions exceed a limit in options; PdcommStatus.InvalidState when the endpoint is not stopped; or another native status, for example PdcommStatus.InvalidArgument when existing report bindings or the event directory refer to a data variable that the new store lacks.

`ConfigureEnhancedCommands`

Method

Installs the enhanced remote command store used to validate received S2F49 (Enhanced Remote Command) requests.

public void ConfigureEnhancedCommands(GemEnhancedCommandOptions options, ReadOnlySpan<GemEnhancedObjectDefinition> definitions)

After installation a received S2F49 is validated against this store only, never against the store of GemEquipment.ConfigureCommands, and is delivered as a GemResult with GemOutcome.EnhancedCommandReceived. Nothing is executed or acknowledged automatically; reply with GemEquipment.RespondEnhancedCommand.

Parameters

Name	Description
`options`	The enhanced command store limits.
`definitions`	The object definitions in registration order. The definitions and their name items are read only during the call.

Notes

Throws ArgumentNullException: options, an object, command or parameter definition, or one of their names is null.
Throws ObjectDisposedException: The endpoint or a name item was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when a count or name size exceeds options; PdcommStatus.InvalidArgument when an object name is not an ASCII item, a name is invalid or duplicated, a format, count range or numeric bound is invalid, a limit of GemEnhancedCommandOptions.ItemLimits is zero, or a completion event is not a configured report event; PdcommStatus.InvalidState when the endpoint is not stopped or enhanced commands are already configured; or another native failure status.

`ConfigureEventDirectory`

Method

Configures or replaces the equipment's collection event directory, which answers S1F23 (Collection Event Namelist Request).

public void ConfigureEventDirectory(GemDirectoryOptions options, ReadOnlySpan<GemEventDirectoryDefinition> definitions)

Call while the endpoint is stopped, after configuring the report store, the data variables and the report bindings. The call replaces the whole directory; a failed call keeps the previous directory. An empty directory differs from no directory. Later cache updates and host report definitions (S2F33, S2F35) do not change the directory.

Parameters

Name	Description
`options`	The capacity limits of the directory.
`definitions`	The event entries in stored order. Names and variable IDs are copied.

Notes

Throws ArgumentNullException: options, a definition, or its name is null.
Throws ArgumentException: An event name contains non-ASCII characters.
Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when the entries exceed a limit in options; PdcommStatus.InvalidArgument when an event ID is duplicated or an entry lists a VID twice; PdcommStatus.InvalidState when the endpoint is not stopped; or another native status, for example PdcommStatus.InvalidArgument when the event IDs do not exactly match the events of the report store or a VID is not bound to an existing data variable.

`ConfigureFixedCatalog`

Method

Installs a complete fixed report catalog and its explicit report variable bindings in one atomic step.

public void ConfigureFixedCatalog(GemReportOptions reportOptions, IReadOnlyList<GemReportDefinition> reports, IReadOnlyList<GemFixedEventDefinition> events, GemBindingOptions bindingOptions, IReadOnlyList<GemReportBinding> bindings)

Call it while the endpoint is stopped, before GemEndpoint.Start. The inputs are copied during the call. On failure the previous report graph and binding store are kept, so the catalog is installed completely or not at all, and only once.

Parameters

Name	Description
`reportOptions`	The report store limits.
`reports`	The report definitions: each report ID (RPTID) with its variable IDs (VID).
`events`	The collection events with their linked reports and initial enable states.
`bindingOptions`	The binding store limits.
`bindings`	The explicit VID bindings. Each must use `GemDataSourceKind.Status` or `GemDataSourceKind.Data` with no constant ID.

Notes

Throws ArgumentNullException: reports, events or bindings is null.
Throws NotSupportedException: The loaded native library does not export this function.
Throws ObjectDisposedException: The endpoint or a binding's constant ID item was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint is not stopped or reports or bindings are already configured; PdcommStatus.InvalidArgument when a definition, link or binding is invalid, a binding uses a constant source, or a report refers to a variable that cannot be resolved; PdcommStatus.LimitExceeded when the catalog exceeds reportOptions or bindingOptions.

`ConfigureLocalSpooling`

Method

Sets the local spooling policy and the streams and functions selected for spooling.

public GemSpoolWriteResult ConfigureLocalSpooling(GemSpoolPolicy policy, ReadOnlySpan<GemSpoolSelection> selections)

The endpoint must be stopped. The change applies to future captures only; stored entries are kept. It also invalidates the synchronization, so call GemEquipment.SyncSpool before capturing.

Parameters

Name	Description
`policy`	The overflow policy, transmission limit and global enable switch.
`selections`	The stream selections; an empty span selects no stream. Each stream and function must be in the catalog.

Returns

The installation of the new configuration (GemSpoolMutation.Configured); its GemSpoolWriteResult.Status is PdcommStatus.SpoolUnconfirmed when persistence could not be confirmed.

Notes

Throws ArgumentNullException: policy is null.
Throws ArgumentOutOfRangeException: GemSpoolPolicy.Overflow is not a defined GemSpoolOverflow value.
Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint was started or spooling is not configured; PdcommStatus.InvalidArgument when a selection repeats a stream or function or names one that is not in the catalog; PdcommStatus.LimitExceeded when the selections exceed GemSpoolOptions.MaxStreams or GemSpoolOptions.MaxFunctionsPerStream; PdcommStatus.Backpressure when a transmission or delivery is pending or a retained transport event is waiting to be read; or the status of a failed snapshot write, such as PdcommStatus.IoError.

`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 GemEquipment.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.

`ConfigureReportBindings`

Method

Configures or replaces the explicit bindings from report variable IDs (VIDs) to value sources.

public void ConfigureReportBindings(GemBindingOptions options, ReadOnlySpan<GemReportBinding> bindings)

Call while the endpoint is stopped. A failed call keeps the previous bindings. Without explicit bindings, each VID resolves to the status variable with the same ID.

Parameters

Name	Description
`options`	The capacity limits of the bindings.
`bindings`	The bindings in stored order. Constant identifier items are copied. An empty span installs explicit mode with no bindings, so no VID falls back to a status variable.

Notes

Throws ArgumentNullException: options or a binding is null.
Throws ObjectDisposedException: The equipment or a constant identifier item was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when a VID is duplicated, the source kind is not defined, a status or data binding has a constant identifier, a constant binding has a nonzero source ID or no identifier, or an identifier is neither ASCII nor a single integer; PdcommStatus.LimitExceeded when the bindings exceed a limit in options; PdcommStatus.InvalidState when the endpoint is not stopped; or another native status, for example PdcommStatus.InvalidArgument when a source does not exist or a defined report or the event directory uses a VID that the new bindings do not cover.

`ConfigureReports`

Method

Creates the equipment's event report store and registers its collection events.

public void ConfigureReports(GemReportOptions options, ReadOnlySpan<uint> eventIds)

Call once while the endpoint is stopped. No reports or links are predefined, and every registered event starts unlinked and disabled. While communicating, the equipment answers the host's S2F33 (Define Report, DRACK), S2F35 (Link Event Report, LRACK) and S2F37 (Enable/Disable Event Report, ERACK) requests from this store. Links and the enable state are independent, as in SEMI E30: S2F37 accepts every existing CEID, and an enabled event without linked reports is reported with an empty report list. A failed call leaves the equipment unchanged. Calls are serialized with the endpoint's internal lock.

Parameters

Name	Description
`options`	The capacity limits of the report store.
`eventIds`	The collection event IDs (CEIDs) that the host can link reports to. The IDs are copied.

Notes

Throws ArgumentNullException: options is null.
Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed: PdcommStatus.InvalidState when the endpoint is not stopped or a report store is already configured, PdcommStatus.LimitExceeded when eventIds has more than GemReportOptions.MaxEvents entries, or PdcommStatus.InvalidArgument when an event ID is duplicated.

`ConfigureSpooling`

Method

Attaches a spool to the equipment, kept in memory or in a snapshot file.

public GemSpoolWriteResult ConfigureSpooling(GemSpoolOptions options, ReadOnlySpan<GemSpoolMessageKey> catalog, string? path = null)

Call once before GemEndpoint.Start, then set the policy and selection with GemEquipment.ConfigureLocalSpooling. A loaded file keeps its persisted catalog, policy, selection, entries and counters; it is never replaced or migrated silently.

A file-backed spool holds an exclusive lock on a lock file next to path while the endpoint exists. Every change writes a complete snapshot to a temporary file next to path, flushes it, renames it over path and synchronizes the parent directory, all on the calling thread. When the result's GemSpoolWriteResult.Status is PdcommStatus.SpoolUnconfirmed, the new spool is attached but the directory synchronization failed; do not configure it again.

Parameters

Name	Description
`options`	The spool limits.
`catalog`	The primary messages that can be spooled, in order. A new spool requires a nonempty catalog. For an existing snapshot file, pass an empty span to accept the persisted catalog or exactly the persisted catalog in the same order.
`path`	`null` or empty for an in-memory spool; otherwise the path of the snapshot file, whose parent directory must exist.

Returns

For a new spool, the installation of its initial configuration (GemSpoolMutation.Configured, disabled, no stream selected). Loading an existing snapshot file writes nothing and reports no change.

Notes

Throws ArgumentNullException: options is null.
Throws ArgumentException: path contains a NUL character or cannot be encoded as UTF-8.
Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint was started or spooling is already configured; PdcommStatus.InvalidArgument when a new spool has an empty catalog, a catalog entry is invalid or repeated, path has no file name, or GemSpoolOptions.MaxSerializedBytes is below 144 with a path; PdcommStatus.LimitExceeded when the catalog exceeds GemSpoolOptions.MaxCatalogEntries, the snapshot file exceeds GemSpoolOptions.MaxSerializedBytes or its contents exceed options; PdcommStatus.InvalidData when the snapshot file is corrupt or its catalog differs from catalog; PdcommStatus.Backpressure when another spool holds the file lock or a retained transport event is waiting to be read; PdcommStatus.IoError when a file operation fails.

`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 GemEquipment.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.

`ConfirmSpoolReply`

Method

Accepts the unconfirmed persistence of a held spooling reply so that GemEquipment.RespondSpool can send it.

public void ConfirmSpoolReply(GemResult result)

It neither synchronizes nor sends. Afterward GemResult.GetSpoolInfo reports GemSpoolDurability.Confirmed and still shows the original persistence status.

Parameters

Name	Description
`result`	The result for which `GemEquipment.RespondSpool` returned `PdcommStatus.SpoolUnconfirmed`.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The equipment or result was disposed.
Throws PdcommException: PdcommStatus.StaleToken when the result belongs to another endpoint, connection or selection, or was already answered; PdcommStatus.InvalidState when the result holds no unconfirmed reply; PdcommStatus.Backpressure when a retained transport event is waiting to be read.

`Create`

Method

Creates an HSMS endpoint and configures it as GEM equipment.

public static GemEquipment Create(string numericAddress, HsmsOptions options, GemEquipmentOptions 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 equipment options.

Returns

A stopped endpoint; register status variables and configure features, then call GemEndpoint.Start.

Notes

Throws ArgumentNullException: numericAddress, options, gemOptions, or its GemEquipmentOptions.Model or GemEquipmentOptions.SoftwareRevision is null.
Throws ArgumentException: The model or software revision contains a non-ASCII character.
Throws PdcommException: The endpoint could not be created or configured: PdcommStatus.InvalidArgument for a non-numeric address, invalid transport options, an initial control state of GemControlState.AttemptOnline, an undefined enum value, or zero GemEquipmentOptions.MaxVariables, GemEquipmentOptions.MaxValueBytes or item limits; PdcommStatus.LimitExceeded when the identity messages do not fit the item limits.

`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.

`GetAlarmAt`

Method

Gets the configured alarm at a position in registration order.

public GemAlarmEntry GetAlarmAt(nuint index)

The query is local. Use GemEquipment.TryCopyAlarmAt to copy the text into a caller-supplied buffer without allocating.

Parameters

Name	Description
`index`	The zero-based position of the alarm in registration order.

Returns

The alarm state, metadata and text.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when index is not less than the alarm count, PdcommStatus.InvalidState when alarms are not configured, or another native failure status.
Throws InvalidOperationException: The native text size changed between the size query and the copy.

`GetAlarmState`

Method

Gets the counters of the configured alarm store.

public GemAlarmState GetAlarmState()

The query is local; it needs neither a connection nor GEM communication.

Returns

The number of alarms, active alarms and enabled alarms, and the combined text size.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when alarms are not configured, or another native failure status.

`GetBindingAt`

Method

Gets the report variable binding at a position in stored order.

public GemReportBindingEntry GetBindingAt(nuint index)

Parameters

Name	Description
`index`	The zero-based position.

Returns

A new entry that the caller owns and must dispose to release its constant identifier item.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed, for example with PdcommStatus.OutOfRange when no bindings are configured or index is not less than the binding count.

`GetBindingState`

Method

Gets the current state of the report variable bindings.

public GemBindingState GetBindingState()

Returns

The binding count, the ASCII identifier size and whether explicit mode is active. All values are zero or false when no bindings are configured.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed.

`GetCommandAt`

Method

Gets the configured remote command at a position in registration order.

public GemCommandEntry GetCommandAt(nuint index)

Parameters

Name	Description
`index`	The zero-based position of the command in registration order.

Returns

The command metadata and name. The caller must dispose the returned entry.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when index is not less than the command count, PdcommStatus.InvalidState when commands are not configured, or another native failure status.

`GetCommandParameterAt`

Method

Gets one parameter definition of a configured remote command.

public GemCommandParameterEntry GetCommandParameterAt(nuint commandIndex, nuint parameterIndex)

Parameters

Name	Description
`commandIndex`	The zero-based position of the command in registration order.
`parameterIndex`	The zero-based position of the parameter in the command definition.

Returns

The parameter validation rules and name. The caller must dispose the returned entry.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when either index is out of range, PdcommStatus.InvalidState when commands are not configured, or another native failure status.

`GetCommandState`

Method

Gets the counters of the configured remote command store.

public GemCommandState GetCommandState()

Returns

The number of commands and parameter definitions, and the combined ASCII name size.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when commands are not configured, or another native failure status.

`GetConstant`

Method

Gets one field of a registered equipment constant.

public SecsItem? GetConstant(SecsItem id, GemConstantField field)

Parameters

Name	Description
`id`	The equipment constant ID (ECID): an ASCII item or a scalar integer item.
`field`	The field to read; `GemConstantField.Current` reads the current value (ECV).

Returns

A new item that the caller owns and must dispose, or null when the constant has no default, minimum or maximum. The name and units are returned as ASCII items; an empty ASCII item is a present but empty value, not an absent one.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: The endpoint or id was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when field is undefined or id is neither an ASCII item nor a scalar integer item; PdcommStatus.OutOfRange when the ID is not registered; PdcommStatus.InvalidState when constants are not configured.

`GetConstantAt`

Method

Gets the ID and declared shape of the constant at a position in registration order.

public GemConstantEntry GetConstantAt(nuint index)

Parameters

Name	Description
`index`	The zero-based position, less than `GemConstantState.ConstantCount`.

Returns

A new entry 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 constants are not configured.

`GetConstantState`

Method

Gets the counters of the equipment constant store.

public GemConstantState GetConstantState()

Returns

The number of constants and the metadata and value bytes in use.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when constants are not configured.

`GetData`

Method

Gets one field of a data variable as a new item.

public SecsItem? GetData(uint id, GemDataField field)

The returned item stays valid after later store or endpoint changes.

Parameters

Name	Description
`id`	The data variable ID.
`field`	The field to read.

Returns

A new item that the caller owns and must dispose: an ASCII item for GemDataField.Name and GemDataField.Units, or a copy of the cached value for GemDataField.Cached. null when field is GemDataField.Cached and no value is cached.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when field is not a defined value; otherwise the native status, for example PdcommStatus.OutOfRange for an unknown ID or PdcommStatus.InvalidState when no data variable store is configured.
Throws InvalidOperationException: The native library returned no item for a name or units.

`GetDataAt`

Method

Gets the shape and cache state of the data variable at a position in the store.

public GemDataInfo GetDataAt(nuint index)

Parameters

Name	Description
`index`	The zero-based position in stored order.

Returns

The ID, format, count range and whether a value is cached.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed: PdcommStatus.OutOfRange when index is not less than the variable count, or PdcommStatus.InvalidState when no data variable store is configured.

`GetDataState`

Method

Gets the current counters of the equipment's data variable store.

public GemDataState GetDataState()

Returns

The variable count and the metadata and cached value sizes.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed, for example with PdcommStatus.InvalidState when no data variable store is configured.

`GetDirectory`

Method

Gets one field of an event directory entry as a new item.

public SecsItem GetDirectory(uint id, GemDirectoryField field)

The returned item stays valid after the directory is reconfigured.

Parameters

Name	Description
`id`	The collection event ID (CEID).
`field`	`GemDirectoryField.Name` for an ASCII item or `GemDirectoryField.VariableIds` for a U4 array item.

Returns

A new item that the caller owns and must dispose.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when field is GemDirectoryField.Units or not a defined value; otherwise the native status, for example PdcommStatus.OutOfRange for an unknown ID or PdcommStatus.InvalidState when no directory is configured.
Throws InvalidOperationException: The native library returned no item.

`GetDirectoryAt`

Method

Gets the event ID and variable count of the directory entry at a position in stored order.

public GemDirectoryEntryInfo GetDirectoryAt(nuint index)

Parameters

Name	Description
`index`	The zero-based position.

Returns

The collection event ID (CEID) and the number of its variable IDs.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed: PdcommStatus.OutOfRange when index is not less than the entry count, or PdcommStatus.InvalidState when no directory is configured.

`GetDirectoryState`

Method

Gets the current counters of the equipment's event directory.

public GemDirectoryState GetDirectoryState()

Returns

The entry count, name bytes, variable count and whether a directory is configured. The counts are zero and GemDirectoryState.Configured is false when no directory is configured.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed.

`GetEnhancedCommandAt`

Method

Gets one command definition of a configured enhanced command object.

public GemCommandEntry GetEnhancedCommandAt(nuint objectIndex, nuint commandIndex)

Parameters

Name	Description
`objectIndex`	The zero-based position of the object in registration order.
`commandIndex`	The zero-based position of the command in the object definition.

Returns

The command metadata and name. The caller must dispose the returned entry.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when either index is out of range, PdcommStatus.InvalidState when enhanced commands are not configured, or another native failure status.

`GetEnhancedCommandParameterAt`

Method

Gets one parameter definition of a command of a configured enhanced command object.

public GemCommandParameterEntry GetEnhancedCommandParameterAt(nuint objectIndex, nuint commandIndex, nuint parameterIndex)

Parameters

Name	Description
`objectIndex`	The zero-based position of the object in registration order.
`commandIndex`	The zero-based position of the command in the object definition.
`parameterIndex`	The zero-based position of the parameter in the command definition.

Returns

The parameter validation rules and name. The caller must dispose the returned entry.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when an index is out of range, PdcommStatus.InvalidState when enhanced commands are not configured, or another native failure status.

`GetEnhancedCommandState`

Method

Gets the counters of the configured enhanced remote command store.

public GemEnhancedCommandState GetEnhancedCommandState()

Returns

The object, command and parameter counts and the combined name sizes.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when enhanced commands are not configured, or another native failure status.

`GetEnhancedObjectAt`

Method

Gets the configured enhanced command object at a position in registration order.

public GemEnhancedObjectEntry GetEnhancedObjectAt(nuint objectIndex)

Parameters

Name	Description
`objectIndex`	The zero-based position of the object in registration order.

Returns

The object metadata and name. The caller must dispose the returned entry.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when objectIndex is not less than the object count, PdcommStatus.InvalidState when enhanced commands are not configured, or another native failure status.

`GetEventAt`

Method

Gets the collection event at a position in the equipment's report store.

public GemEventDefinition GetEventAt(nuint index)

The host changes links with S2F35 (Link Event Report) and the enable state with S2F37 (Enable/Disable Event Report). Use GemEquipment.TryCopyEventAt to copy into a caller buffer instead.

Parameters

Name	Description
`index`	The zero-based position in registration order.

Returns

The event ID, its enable state and a copy of its linked report IDs.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed: PdcommStatus.OutOfRange when index is not less than the event count, or PdcommStatus.InvalidState when no report store is configured.
Throws InvalidOperationException: The native link count changed between the size query and the copy.

`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.

`GetReportAt`

Method

Gets the report definition at a position in the equipment's report store.

public GemReportDefinition GetReportAt(nuint index)

The host changes the reports with S2F33 (Define Report). Use GemEquipment.TryCopyReportAt to copy into a caller buffer instead.

Parameters

Name	Description
`index`	The zero-based position in stored order.

Returns

The report ID and a copy of its variable IDs.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed: PdcommStatus.OutOfRange when index is not less than the report count, or PdcommStatus.InvalidState when no report store is configured.
Throws InvalidOperationException: The native report size changed between the size query and the copy.

`GetReportState`

Method

Gets the current counters of the equipment's event report store.

public GemReportState GetReportState()

Returns

The event, report, variable and link counts.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed, for example with PdcommStatus.InvalidState when no report store is configured.

`GetReportValue`

Method

Gets a copy of the current value that a report variable ID resolves to.

public SecsItem GetReportValue(uint vid)

The value is resolved locally from the bindings and caches; no message is sent and the size of a whole report is not checked. The returned item is independent of the equipment.

Parameters

Name	Description
`vid`	The variable ID (VID).

Returns

A new item that the caller owns and must dispose.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed: PdcommStatus.OutOfRange when the VID or its source is unknown, or PdcommStatus.InvalidState when the bound data variable has no cached value or no data variable store is configured.

`GetSpoolCatalogAt`

Method

Gets one entry of the spool catalog.

public GemSpoolMessageKey GetSpoolCatalogAt(nuint index)

Parameters

Name	Description
`index`	The zero-based position in the catalog.

Returns

The stream and function of the catalog entry.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when index is not less than GemSpoolState.CatalogCount or spooling is not configured.

`GetSpoolEntryAt`

Method

Gets a copy of one stored spool entry.

public GemSpoolEntry GetSpoolEntryAt(nuint index)

Parameters

Name	Description
`index`	The zero-based position in the spool; 0 is the oldest entry, which is delivered next.

Returns

A new entry that the caller owns and must dispose.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when spooling is not configured; PdcommStatus.OutOfRange when index is not less than GemSpoolState.MessageCount; PdcommStatus.InvalidData when the stored body cannot be decoded; or another native failure such as PdcommStatus.AllocationFailed.

`GetSpoolEntryCapturedAt`

Method

Gets the capture time recorded for a spool entry.

public ulong? GetSpoolEntryCapturedAt(nuint index)

The time uses the clock of the application's capture calls, such as GemEquipment.CaptureSpool; the binding does not interpret it.

Parameters

Name	Description
`index`	The zero-based position of the entry in the spool.

Returns

The now value that was passed when the entry was captured, or null when the entry has no recorded capture time, such as an entry from an older spool snapshot.

Notes

Throws NotSupportedException: The loaded native library does not export this function.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when no entry exists at index; PdcommStatus.InvalidState when spooling is not configured.

`GetSpoolSelectionAt`

Method

Gets one stream selection of the current spooling configuration.

public GemSpoolSelection GetSpoolSelectionAt(nuint index)

Parameters

Name	Description
`index`	The zero-based position in the selection.

Returns

The stream and a new array of its selected functions; an empty array selects every cataloged function of the stream.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when spooling is not configured; PdcommStatus.OutOfRange when index is not less than GemSpoolState.SelectionCount; or another native failure such as PdcommStatus.AllocationFailed.
Throws InvalidOperationException: The native library returned no function list.

`GetSpoolState`

Method

Gets the counters, policy and flags of the spool.

public GemSpoolState GetSpoolState()

Returns

The current spool state.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when spooling is not configured.

`GetStatus`

Method

Gets a copy of the current value of a registered status variable.

public SecsItem GetStatus(uint id)

Parameters

Name	Description
`id`	The status variable ID (SVID).

Returns

A new item that the caller owns and must dispose; it stays valid after the endpoint is disposed.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange for an unknown ID.

`GetStatusIdAt`

Method

Gets the ID of the status variable at a position in registration order.

public uint GetStatusIdAt(nuint index)

Parameters

Name	Description
`index`	The zero-based registration position.

Returns

The status variable ID (SVID).

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when index is not less than GemState.VariableCount.

`GetStatusMetadata`

Method

Gets the name and units of a registered status variable.

public GemStatusName GetStatusMetadata(uint id)

Parameters

Name	Description
`id`	The status variable ID (SVID).

Returns

The status variable name and units.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange for an unknown ID.
Throws InvalidOperationException: The native metadata size changed during the read.

`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 and GemProgramOptions.MaxPendingIdentifierBytes 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 GemEquipment.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 or GemProgramOptions.MaxPendingIdentifierBytes; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`ObserveAlarm`

Method

Records the current active state of a configured alarm without sending a message.

public GemAlarmChange ObserveAlarm(uint id, bool active)

The state changes immediately and is not rolled back if a later send fails. To report the transition, call GemEquipment.PublishAlarm for S5F1 and, when GemAlarmChange.EventId is present, GemEquipment.PublishEvent for the S6F11 event report.

Parameters

Name	Description
`id`	The alarm ID (ALID).
`active`	`true` when the alarm condition is set; `false` when it is cleared.

Returns

Whether the state changed, the current reporting policy, and the set or clear collection event ID (CEID) mapped to the transition.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when id is not a configured alarm, or PdcommStatus.InvalidState when the endpoint is not an equipment with configured alarms.

`OperatorOffline`

Method

Switches the equipment to GemControlState.EquipmentOffline, as the operator's OFF-LINE switch does.

public void OperatorOffline()

Allowed from GemControlState.OnlineLocal, GemControlState.OnlineRemote and GemControlState.HostOffline, as in the SEMI E30 control state model. No message is sent to the host and no connection is required.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the control state is GemControlState.EquipmentOffline or GemControlState.AttemptOnline.

`OperatorOnline`

Method

Starts an operator request to go on-line by sending S1F1 (Are You There) to the host.

public HsmsToken OperatorOnline()

Allowed only in GemControlState.EquipmentOffline while the session is selected. The control state becomes GemControlState.AttemptOnline. When the host answers with an empty S1F2 list, the result has the outcome GemOutcome.OnlineAccepted and the state becomes the on-line state selected by the on-line mode; when the transaction fails, the state becomes GemControlState.HostOffline. The result reports GemRequestKind.OperatorOnline.

Returns

The token of the S1F1 request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState in another control state or without a selected session; PdcommStatus.Backpressure when all 32 pending request slots are in use.

`PublishAlarm`

Method

Sends an S5F1 (Alarm Report Send) message with the current state of a configured alarm.

public HsmsToken PublishAlarm(uint id, bool replyExpected)

The message carries ALCD (category, with bit 8 set when the alarm is active), ALID and ALTX. With replyExpected the request occupies a pending slot and the S5F2 reply arrives as a GemResult with GemOutcome.AlarmAck. Without it the token only tracks the local write and does not mean the host received the report.

Parameters

Name	Description
`id`	The alarm ID (ALID).
`replyExpected`	`true` to set the W-bit and expect an S5F2 (Alarm Report Acknowledge) reply.

Returns

The transport token of the accepted request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when id is not a configured alarm; PdcommStatus.InvalidState when alarms are not configured, reporting is not enabled for the alarm, or GEM communication is not established; PdcommStatus.Backpressure when the transport or, with replyExpected, the pending request table is full; or another native failure status.

`PublishEvent`

Method

Sends an event report (S6F11) for an enabled collection event; an event without linked reports is sent with an empty report list.

public HsmsToken PublishEvent(uint dataId, uint eventId)

The message body is built from the current report values before the method returns and is sent with the reply bit set. Values come from the report bindings when they are configured, otherwise from the status variables whose IDs equal the VIDs. Submission is not acknowledgement: the host's S6F12 later produces a result with GemOutcome.EventAck and the ACKC6 code (0 to 63) in GemResultInfo.Acknowledgement. Use GemEquipment.PublishEventWithData to supply data samples.

Parameters

Name	Description
`dataId`	The data ID (DATAID) placed in the message.
`eventId`	The collection event ID (CEID).

Returns

The token that identifies the pending S6F11/S6F12 transaction.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed: PdcommStatus.InvalidState when the equipment is not communicating or a bound data variable has no cached value, PdcommStatus.InvalidData when no report store is configured or the event is unknown or disabled, PdcommStatus.OutOfRange when a report variable has no value source, PdcommStatus.LimitExceeded when the message exceeds the item limits, or PdcommStatus.Backpressure when no pending request slot is free.

`PublishEventWithData`

Method

Sends an event report (S6F11) whose data variable values come from the supplied samples first and from the cached values second.

public HsmsToken PublishEventWithData(uint dataId, uint eventId, ReadOnlySpan<GemDataSample> samples)

The whole report is built before submission, so a failed call sends nothing and keeps caches, bindings and earlier queued reports unchanged. Submission is not acknowledgement: the host's S6F12 later produces a result with GemOutcome.EventAck and the ACKC6 code in GemResultInfo.Acknowledgement.

Parameters

Name	Description
`dataId`	The data ID (DATAID) placed in the message.
`eventId`	The collection event ID (CEID) of an enabled event, linked or not.
`samples`	Data variable values for this report only, at most one per data variable ID. Every sample is validated even when no linked report uses it. Samples never change the cached values, and the items are copied before the call returns.

Returns

The token that identifies the pending S6F11/S6F12 transaction.

Notes

Throws ArgumentNullException: A sample or its value is null.
Throws ObjectDisposedException: The equipment or a sample value was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when the samples exceed the count, byte or item limits of the data variable store; PdcommStatus.InvalidArgument when a sample ID is unknown or duplicated or a sample does not match its variable's format and count range; or the same native statuses as GemEquipment.PublishEvent, including PdcommStatus.InvalidState when samples are supplied but no data variable store is configured.

`PurgeSpool`

Method

Removes every stored entry from the spool.

public GemSpoolWriteResult PurgeSpool()

The endpoint must be stopped. Spooling becomes inactive and the start and full times are cleared. A host purges the spool of a running endpoint with S6F23 instead.

Returns

GemSpoolMutation.Purged with the number of removed entries in GemSpoolWriteResult.AffectedCount.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint was started or spooling is not configured; PdcommStatus.Backpressure when a transmission or delivery is pending or a retained transport event is waiting to be read; or the status of a failed snapshot write, such as PdcommStatus.IoError.

`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.

`RegisterStatus`

Method

Registers a status variable that the equipment reports in S1F4 and S1F12.

public void RegisterStatus(uint id, string name, string units, SecsItem value)

Registration is allowed only while the endpoint is stopped. value is copied; the caller keeps ownership of it. On failure the registry is unchanged. GemEquipment.GetStatusIdAt uses registration order.

Parameters

Name	Description
`id`	The status variable ID (SVID).
`name`	The status variable name (SVNAME); ASCII only, embedded NUL characters are kept.
`units`	The units (UNITS); ASCII only, may be empty.
`value`	The initial value; its top-level format is fixed for later updates.

Notes

Throws ArgumentNullException: name, units or value is null.
Throws ArgumentException: name or units contains a non-ASCII character.
Throws ObjectDisposedException: The endpoint or value was disposed.
Throws PdcommException: PdcommStatus.InvalidState after the endpoint started; PdcommStatus.InvalidArgument for a duplicate ID; PdcommStatus.LimitExceeded when GemEquipmentOptions.MaxVariables, GemEquipmentOptions.MaxMetadataBytes, GemEquipmentOptions.MaxValueBytes or the item limits would be exceeded.

`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 and GemProgramOptions.MaxPendingIdentifierBytes 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 or GemProgramOptions.MaxPendingIdentifierBytes; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`RespondCommand`

Method

Sends the S2F42 (Host Command Acknowledge) reply to a received S2F41 remote command.

public GemCommandReply RespondCommand(GemResult result, GemCommandDecision decision, ReadOnlySpan<GemCommandIssue> issues)

When validation rejected the request on receipt, the reply carries the original HCACK and parameter issues and decision and issues are ignored. Validation and the completion event are fixed when the request is received, even if the control state changes later. Application interlocks remain the caller's responsibility.

The reply is prepared completely before it is sent, and the result is marked as responded only after the send succeeds. After a failure, retry with the same decision instead of performing the work again. Start deferred work only after an HCACK 4 reply was sent, and publish the completion event separately. Calls are serialized with the getters of result.

Parameters

Name	Description
`result`	The result of the received request (`GemOutcome.CommandReceived`).
`decision`	The application decision, sent as HCACK when validation accepted the request on receipt.
`issues`	The parameter acknowledgements (CPNAME and CPACK 1 through 3) to send. Only `GemCommandDecision.ParameterErrors` may carry issues, and at most `GemCommandOptions.MaxErrors`.

Returns

The HCACK that was sent and, for HCACK 0 or 4, the completion collection event ID (CEID).

Notes

Throws ArgumentNullException: result, an issue, or an issue name is null.
Throws ObjectDisposedException: The endpoint, result or an issue name was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when decision is not defined, the result is not a remote command result, issues accompany another decision, or an issue code or name is invalid; PdcommStatus.LimitExceeded when the issues exceed the command limits or the reply exceeds the message limits; PdcommStatus.InvalidState when the result is a host-side reply or GEM communication is not established; PdcommStatus.StaleToken when the request was already answered or belongs to another endpoint, connection or selection; PdcommStatus.Backpressure when the transport cannot accept the reply; or another native failure status.

`RespondConstants`

Method

Sends the S2F16 (New Equipment Constant Acknowledge) reply to a received S2F15 request.

public GemConstantReply RespondConstants(GemResult result, GemConstantDecision decision)

When the receipt validation rejected the request, its EAC (1 or 3) is sent whatever the decision. Otherwise GemConstantDecision.Apply replaces the stored values only after the reply was handed to the transport; the method performs no physical operation, persistence or event report. A request that became stale because the store changed or was reconfigured after receipt cannot be applied, but can still be rejected.

Requires GemCommunicationState.Communicating. If building or sending the reply fails, the store and the result are unchanged and the call can be retried. The result can be answered only once.

Parameters

Name	Description
`result`	The result with outcome `GemOutcome.ConstantChangesReceived`; inspect it with `GemResult.GetConstantChangeInfo` and `GemResult.GetConstantChange`.
`decision`	The EAC to send when the receipt validation accepted the request: `GemConstantDecision.Apply`, `GemConstantDecision.CannotPerform`, `GemConstantDecision.OutOfRange` or an equipment-specific code from 4 to 63.

Returns

The EAC that was sent and whether the store was changed.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when decision is 1 or above 63, or result is not a received S2F15 request; PdcommStatus.StaleToken when the result was already answered, belongs to another endpoint or an earlier connection or selection, or applies a stale request; PdcommStatus.InvalidState when communication is not established; PdcommStatus.Backpressure when a retained transport event must be read first or the transport cannot accept the reply.

`RespondEnhancedCommand`

Method

Sends the S2F50 (Enhanced Remote Command Acknowledge) reply to a received S2F49 request.

public GemCommandReply RespondEnhancedCommand(GemResult result, GemCommandDecision decision, SecsItem? acknowledgements)

When validation rejected the request on receipt, the reply carries the original HCACK and the frozen validation errors, and decision is ignored. Names, order and zero codes of acknowledgements are sent as supplied and are not matched against the request.

The result is marked as responded only after the send succeeds. After a failure, retry with the same decision instead of performing the work again. Start deferred work only after an HCACK 4 reply was sent, and publish the completion event separately. Calls are serialized with the getters of result.

Parameters

Name	Description
`result`	The result of the received request (`GemOutcome.EnhancedCommandReceived`).
`decision`	The application decision, sent as HCACK when validation accepted the request on receipt.
`acknowledgements`	The parameter acknowledgement list sent as the second field of S2F50, or `null`. With `GemCommandDecision.ParameterErrors` it must be a List item whose entries are `L[CPNAME, CEPACK]`, where CEPACK is a U1 scalar 0 through 4, a List of U1 scalars, or a list of nested named entries. Every outer entry must contain at least one nonzero code; an empty list is valid. With any other decision it must be `null`. It is ignored when validation rejected the request.

Returns

The HCACK that was sent and, for HCACK 0 or 4, the completion collection event ID (CEID).

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint, result or acknowledgements was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when decision is not defined, the result is not an enhanced command result, or acknowledgements does not match the decision or the acknowledgement structure; PdcommStatus.LimitExceeded when the nonzero codes exceed GemEnhancedCommandOptions.MaxErrors or the reply exceeds the message limits; PdcommStatus.InvalidState when the result is a host-side reply or GEM communication is not established; PdcommStatus.StaleToken when the request was already answered or belongs to another endpoint, connection or selection; PdcommStatus.Backpressure when the transport cannot accept the reply; or another native failure status.

`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 GemEquipment.ResyncPrograms, then GemEquipment.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 GemEquipment.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.

`RespondReportQuery`

Method

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

public void RespondReportQuery(GemResult result, ReadOnlySpan<GemDataSample> samples)

Report queries are never answered automatically. The reply is built from the report definitions and values at the time of this call, not when the query was received. The result keeps the request, so the original HsmsEvent may already be disposed. Sample items are borrowed only for the call.

A failure leaves the request unanswered, so the call can be retried. Only a successful call sets GemQueryInfo.Responded and GemResultInfo.ReplySent.

Parameters

Name	Description
`result`	The `GemOutcome.ReportQueryReceived` result returned by `GemEndpoint.HandleEvent`.
`samples`	Current data variable samples to use in the reply; empty to use only cached and registered values. Every sample is validated, even when the reply does not use it, and samples do not change the cached values.

Notes

Throws ArgumentNullException: result, a sample, or a sample value is null.
Throws ObjectDisposedException: The endpoint, result or a sample value was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when result is not a received report query or a sample is invalid; PdcommStatus.InvalidState when communication is not established or samples are given without configured data variables; PdcommStatus.StaleToken when the query was already answered or belongs to another endpoint, connection or selection; PdcommStatus.LimitExceeded when the samples or the reply exceed the configured limits.

`RespondSpool`

Method

Applies a spooling request received by the equipment and sends its reply: S2F44 for S2F43, S2F60 for S2F59 or S6F24 for S6F23.

public PdcommStatus RespondSpool(GemResult result)

An S2F43 whose streams and functions are all in the catalog replaces the selection and is answered with RSPACK 0; otherwise the reply carries RSPACK 1 with one STRACK error per rejected stream and nothing changes. S2F59 is answered with the current selection, not the catalog. S6F23 is answered with RSDA 1 while a transmission or delivery is pending, 2 when the spool is empty, and otherwise 0; then Purge empties the spool and Transmit starts a transmission run once the reply is sent. Configuration and purge are installed before the reply is sent.

If sending fails, the prepared reply is retained; call again with the same result to retry only that reply.

Parameters

Name	Description
`result`	The `GemOutcome.SpoolReceived` result of the request, or the same result again to send a retained reply.

Returns

PdcommStatus.Ok when the reply was sent; PdcommStatus.SpoolUnconfirmed when the change was installed but its persistence could not be confirmed, so the reply is held unsent until GemEquipment.ConfirmSpoolReply.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The equipment or result was disposed.
Throws PdcommException: PdcommStatus.StaleToken when the result belongs to another endpoint, connection or selection, or was already answered; PdcommStatus.InvalidState when the result is not a received spooling request, GEM communication is not established, or the spool is not synchronized; PdcommStatus.Backpressure when an accepted transmission can no longer start or a retained transport event is waiting to be read; the status of a failed snapshot write; or a transport failure.

`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 GemEquipment.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.

`ResyncSpool`

Method

Retries synchronizing the parent directory of the spool snapshot file.

public void ResyncSpool()

Use it after a PdcommStatus.SpoolUnconfirmed outcome. It never rewrites the snapshot, sends or confirms a reply, or removes an entry, and it does not update earlier results.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when spooling is not configured or the spool is in memory; PdcommStatus.Backpressure when a retained transport event is waiting to be read; or PdcommStatus.IoError when the synchronization fails.

`RetrySpoolDequeue`

Method

Retries removing a delivered entry whose success was accepted but whose removal failed.

public GemSpoolWriteResult RetrySpoolDequeue()

It sends nothing and works after a reconnection without the original result. GemSpoolState.DequeuePending reports whether a removal is pending.

Returns

GemSpoolMutation.Removed with the removed GemSpoolWriteResult.EntryId.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when spooling is not configured; PdcommStatus.StaleToken when no removal is pending; PdcommStatus.Backpressure when a retained transport event is waiting to be read; or the status of a failed snapshot write.

`SendNextSpool`

Method

Sends the oldest stored entry as the next delivery of the current transmission run.

public HsmsToken SendNextSpool()

A transmission run starts when GemEquipment.RespondSpool accepts an S6F23 Transmit request, and ends when the spool is empty or GemSpoolPolicy.MaxTransmit entries were removed. Nothing sends the next entry automatically; call this once per entry. A failure after the delivery was prepared, including a missing pending slot or a transport failure, keeps the entry and ends the run.

Submission is not delivery. The outcome arrives as a GemResult: GemOutcome.SpoolDeliveryResponse with the reply to an entry sent with the W-bit, GemOutcome.SpoolDeliveryWritten once an entry without the W-bit was written, or GemOutcome.SpoolDeliveryFailed, which keeps the entry and ends the run. Pass the first two to GemEquipment.CompleteSpoolDelivery.

Returns

The transport token of the sent message.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when spooling is not configured or not synchronized, GEM communication is not established, or no transmission run is in progress; PdcommStatus.OutOfRange when the spool is empty, which ends the run; PdcommStatus.Backpressure when a delivery is in flight or awaits removal, when the entry expects a reply and no pending request slot is free, or when a retained transport event is waiting to be read; or a transport failure.

`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 and GemProgramOptions.MaxPendingIdentifierBytes 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 or GemProgramOptions.MaxPendingIdentifierBytes; PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`SetOnlineMode`

Method

Sets the operator's REMOTE/LOCAL switch.

public void SetOnlineMode(GemOnlineMode mode)

Allowed in every control state, as in the SEMI E30 control state model: an on-line equipment moves to GemControlState.OnlineLocal or GemControlState.OnlineRemote at once, and an off-line equipment uses the mode the next time it goes on-line. No message is sent to the host.

Parameters

Name	Description
`mode`	The on-line mode.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument for an undefined mode.

`StopSpoolTransmit`

Method

Ends the current transmission run and keeps the stored entries.

public void StopSpoolTransmit()

A new run requires another accepted S6F23 Transmit request.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when spooling is not configured; PdcommStatus.Backpressure when a delivery is in flight or awaits removal, or a retained transport event is waiting to be read.

`SyncSpool`

Method

Records the current communication and selection state for spooling and activates spooling while communication is down.

public GemSpoolWriteResult SyncSpool(ulong now)

Call it after handling transport and GEM events. Captures, replies and deliveries require a synchronization that still matches the current state; GemSpoolState.Synchronized reports it. Communication is up when the transport is selected and GEM communication is GemCommunicationState.Communicating.

While communication is down and the policy is enabled, spooling activates; activating an empty spool resets the counters. A new connection or a lost one ends the transmission run and abandons a delivery in flight, but a delivery that awaits removal stays pending. Synchronization never starts a transmission.

Parameters

Name	Description
`now`	An application timestamp, stored as `GemSpoolState.StartTime` when spooling activates; PDComm does not interpret it.

Returns

GemSpoolMutation.Activated when spooling became active; otherwise a result with no change.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: PdcommStatus.InvalidState when spooling is not configured; PdcommStatus.Backpressure when a retained transport event is waiting to be read; or the status of a failed snapshot write, such as PdcommStatus.IoError.

`TryCopyAlarmAt`

Method

Copies the configured alarm at a position in registration order into a caller-supplied buffer.

public bool TryCopyAlarmAt(nuint index, out GemAlarmInfo info, Span<byte> text, out nuint required)

Parameters

Name	Description
`index`	The zero-based position of the alarm in registration order.
`info`	When this method returns, contains the alarm state and metadata.
`text`	The buffer that receives the alarm text as ASCII bytes. No terminating NUL is appended.
`required`	When this method returns, contains the text length in bytes.

Returns

true when the text was copied; false when text is shorter than required. In that case text is left unchanged, and info and required are still set.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange when index is not less than the alarm count, PdcommStatus.InvalidState when alarms are not configured, or another native failure status.

`TryCopyEventAt`

Method

Copies the collection event at a position in the equipment's report store into a caller buffer.

public bool TryCopyEventAt(nuint index, out uint eventId, out bool enabled, Span<uint> reportIds, out nuint required)

Parameters

Name	Description
`index`	The zero-based position in registration order.
`eventId`	When this method returns, the collection event ID (CEID).
`enabled`	When this method returns, `true` when reporting of the event is enabled.
`reportIds`	The buffer that receives the linked report IDs (RPTIDs).
`required`	When this method returns, the number of linked report IDs.

Returns

true when the report IDs were copied; false when reportIds is shorter than required. In that case the buffer is not modified, but eventId, enabled and required are still set.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed: PdcommStatus.OutOfRange when index is not less than the event count, or PdcommStatus.InvalidState when no report store is configured.

`TryCopyReportAt`

Method

Copies the report definition at a position in the equipment's report store into a caller buffer.

public bool TryCopyReportAt(nuint index, out uint id, Span<uint> variableIds, out nuint required)

Parameters

Name	Description
`index`	The zero-based position in stored order.
`id`	When this method returns, the report ID (RPTID).
`variableIds`	The buffer that receives the variable IDs (VIDs).
`required`	When this method returns, the number of variable IDs in the report.

Returns

true when the variable IDs were copied; false when variableIds is shorter than required. In that case the buffer is not modified, but id and required are still set.

Notes

Throws ObjectDisposedException: The equipment was disposed.
Throws PdcommException: The native call failed: PdcommStatus.OutOfRange when index is not less than the report count, or PdcommStatus.InvalidState when no report store is configured.

`TryCopyStatusMetadata`

Method

Copies the name and units of a registered status variable into caller buffers.

public bool TryCopyStatusMetadata(uint id, Span<byte> name, out nuint nameRequired, Span<byte> units, out nuint unitsRequired)

Parameters

Name	Description
`id`	The status variable ID (SVID).
`name`	The buffer that receives the ASCII name bytes; no terminator is added.
`nameRequired`	Receives the name length in bytes.
`units`	The buffer that receives the ASCII units bytes; no terminator is added.
`unitsRequired`	Receives the units length in bytes.

Returns

true when both values were copied; false when either buffer is too small, in which case neither buffer is changed and the required lengths are reported.

Notes

Throws ArgumentException: name and units overlap.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.OutOfRange for an unknown ID.

`UpdateDataVariable`

Method

Replaces the cached value of a data variable.

public void UpdateDataVariable(uint id, SecsItem value)

The method can be called in any communication state. Event reports and report queries use the cached value when no sample supplies the variable.

Parameters

Name	Description
`id`	The data variable ID.
`value`	The new value. It must match the variable's format and count range. The call copies it; the caller keeps ownership.

Notes

Throws ArgumentNullException: value is null.
Throws ObjectDisposedException: The equipment or value was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when the value exceeds the store's item limits or the cached values would exceed GemDataOptions.MaxValueBytes; PdcommStatus.InvalidArgument when the format or count does not match; PdcommStatus.OutOfRange for an unknown ID; or PdcommStatus.InvalidState when no data variable store is configured.

`UpdateStatus`

Method

Replaces the value of a registered status variable.

public void UpdateStatus(uint id, SecsItem value)

Updates are allowed while the endpoint runs. value is copied; the caller keeps ownership of it. On failure the stored value is unchanged.

Parameters

Name	Description
`id`	The status variable ID (SVID).
`value`	The new value; it must have the same top-level format as the registered value.

Notes

Throws ArgumentNullException: value is null.
Throws ObjectDisposedException: The endpoint or value was disposed.
Throws PdcommException: PdcommStatus.OutOfRange for an unknown ID; PdcommStatus.InvalidArgument when the format differs; PdcommStatus.LimitExceeded when GemEquipmentOptions.MaxValueBytes or the item limits would be exceeded.