PDComm.GemEquipmentWorker

Class

A GEM equipment endpoint that runs on a dedicated polling thread and exposes asynchronous commands.

public sealed class GemEquipmentWorker : GemWorker

The worker creates a GemEquipment on its thread, registers the initial status variables and configured features, starts the transport, and delivers every processed event through GemWorker.ReadEventsAsync. Standard requests such as S1F1, S1F3, S1F11, S1F13, S1F15 and S1F17 are answered automatically; primaries that need an application decision are answered with the feature commands of this class, such as GemEquipmentWorker.RespondReportQueryAsync.

Each *Async command queues the synchronous GemEquipment method of the same name on the worker thread; see GemWorker for queueing, backpressure and shutdown rules.

using SecsItem temperature = SecsItem.FromF4([21.5f], limits);
await using GemEquipmentWorker equipment = await GemEquipmentWorker.StartAsync(
    "127.0.0.1:0", transportOptions, equipmentOptions, workerOptions,
    [new GemStatusVariable(1, "Temperature", "C", temperature)], cancellationToken);
Console.WriteLine($"LISTEN {equipment.LocalAddress}");
await using IAsyncEnumerator<GemEvent> events =
    equipment.ReadEventsAsync(cancellationToken).GetAsyncEnumerator();
bool communicated = false;
while (await events.MoveNextAsync())
{
    using GemEvent current = events.Current;
    if (current.ProcessingStatus != PdcommStatus.Ok)
        throw new PdcommException(current.ProcessingStatus);
    GemResultInfo? info = current.Result?.GetInfo();
    if (info?.Kind == GemResultKind.Primary) Console.WriteLine(info.Value.Outcome);
    if (info?.State.Communication == GemCommunicationState.Communicating) communicated = true;
    if (communicated &&
        (await equipment.GetTransportStateAsync(cancellationToken)).State != HsmsConnectionState.Selected)
        break;
}
await equipment.StopAsync(cancellationToken);
while (await events.MoveNextAsync()) events.Current.Dispose();
await equipment.Completion;

Members

`CancelProgramGrantAsync`

Method

Queues GemEquipment.CancelProgramGrant on the worker thread.

public Task CancelProgramGrantAsync(GemResult result, CancellationToken cancellationToken = default)

result stays valid until the command finishes, even if you dispose it meanwhile. The command reserves SecsLimits.MessageBytes of the GEM item limits of the command byte budget.

Parameters

Name	Description
`result`	The original S7F1 request result whose reply granted the program.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the grant was withdrawn. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.CancelProgramGrant.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: result was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`CaptureSpoolAlarmAsync`

Method

Queues GemEquipment.CaptureSpoolAlarm on the worker thread.

public Task<GemSpoolWriteResult> CaptureSpoolAlarmAsync(uint alarmId, bool replyExpected, ulong now, CancellationToken cancellationToken = default)

Parameters

Name	Description
`alarmId`	The alarm ID (ALID) of a configured alarm with reporting enabled.
`replyExpected`	`true` to deliver the report later with the W-bit set.
`now`	An application timestamp stored as the capture time of the entry.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the capture outcome. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.CaptureSpoolAlarm.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`CaptureSpoolAsync`

Method

Queues GemEquipment.CaptureSpool on the worker thread.

public Task<GemSpoolWriteResult> CaptureSpoolAsync(byte stream, byte function, bool replyExpected, SecsItem? body, ulong now, CancellationToken cancellationToken = default)

Parameters

Name	Description
`stream`	The stream, 2 to 127.
`function`	The function of a primary message, an odd number.
`replyExpected`	`true` to deliver the message later with the W-bit set.
`body`	The message body, or `null` for a header-only message. It is encoded before this method returns, so the caller may dispose it afterward; its encoded length counts against the command byte budget.
`now`	An application timestamp stored as the capture time of the entry.
`cancellationToken`	The token that cancels the command before it runs.

Returns

Notes

Throws ObjectDisposedException: body was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync; PdcommStatus.LimitExceeded when the encoded body exceeds GemSpoolOptions.MaxBodyBytes or the SecsLimits.MessageBytes of the GEM item limits.

`CaptureSpoolEventAsync`

Method

Queues GemEquipment.CaptureSpoolEvent on the worker thread.

public Task<GemSpoolWriteResult> CaptureSpoolEventAsync(uint dataId, uint eventId, ReadOnlyMemory<GemDataSample> samples, ulong now, CancellationToken cancellationToken = default)

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. They are encoded before this method returns, so the caller may dispose them afterward; their encoded lengths count against the command byte budget.
`now`	An application timestamp stored as the capture time of the entry.
`cancellationToken`	The token that cancels the command before it runs.

Returns

Notes

Throws ArgumentNullException: A sample or its value is null.
Throws ObjectDisposedException: A sample value was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync; PdcommStatus.LimitExceeded when an encoded sample exceeds the SecsLimits.MessageBytes of the GEM item limits.

`ClearDataVariableAsync`

Method

Queues GemEquipment.ClearDataVariable on the worker thread.

public Task ClearDataVariableAsync(uint id, CancellationToken cancellationToken = default)

Parameters

Name	Description
`id`	The data variable ID.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the cached value was removed.

`CompleteSpoolDeliveryAsync`

Method

Queues GemEquipment.CompleteSpoolDelivery on the worker thread.

public Task<GemSpoolWriteResult> CompleteSpoolDeliveryAsync(GemResult result, bool success, CancellationToken cancellationToken = default)

The command reserves the SecsLimits.MessageBytes of the GEM item limits in the command byte budget. result stays valid until the command finishes, even if you dispose it meanwhile.

Parameters

Name	Description
`result`	The `GemOutcome.SpoolDeliveryResponse` or `GemOutcome.SpoolDeliveryWritten` result of the current delivery.
`success`	`true` to accept the delivery and remove the entry; `false` to keep the entry and end the transmission run.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the write result. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.CompleteSpoolDelivery.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: result was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`ConfirmProgramReplyAsync`

Method

Queues GemEquipment.ConfirmProgramReply on the worker thread.

public Task ConfirmProgramReplyAsync(GemResult result, CancellationToken cancellationToken = default)

result stays valid until the command finishes, even if you dispose it meanwhile. The command reserves SecsLimits.MessageBytes of the GEM item limits of the command byte budget.

Parameters

Name	Description
`result`	The received S7F3 or S7F17 request whose installation is unconfirmed.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the saved reply is ready to be sent with GemEquipmentWorker.RespondProgramAsync. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.ConfirmProgramReply.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: result was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`ConfirmSpoolReplyAsync`

Method

Queues GemEquipment.ConfirmSpoolReply on the worker thread.

public Task ConfirmSpoolReplyAsync(GemResult result, CancellationToken cancellationToken = default)

The command reserves the SecsLimits.MessageBytes of the GEM item limits in the command byte budget. result stays valid until the command finishes, even if you dispose it meanwhile.

Parameters

Name	Description
`result`	The result for which `GemEquipmentWorker.RespondSpoolingAsync` returned `PdcommStatus.SpoolUnconfirmed`.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the held reply was accepted for sending. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.ConfirmSpoolReply.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: result was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`GetAlarmAtAsync`

Method

Queues GemEquipment.GetAlarmAt on the worker thread.

public Task<GemAlarmEntry> GetAlarmAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position of the alarm in registration order.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the alarm state, metadata and text. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetAlarmAt.

`GetAlarmStateAsync`

Method

Queues GemEquipment.GetAlarmState on the worker thread.

public Task<GemAlarmState> GetAlarmStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the alarm store counters. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetAlarmState.

`GetBindingAtAsync`

Method

Queues GemEquipment.GetBindingAt on the worker thread.

public Task<GemReportBindingEntry> GetBindingAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position in stored order.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with a new entry that the caller owns and must dispose.

`GetBindingStateAsync`

Method

Queues GemEquipment.GetBindingState on the worker thread.

public Task<GemBindingState> GetBindingStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the state of the report variable bindings.

`GetCommandAtAsync`

Method

Queues GemEquipment.GetCommandAt on the worker thread.

public Task<GemCommandEntry> GetCommandAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position of the command in registration order.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the command metadata and name; the caller must dispose the entry. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetCommandAt.

`GetCommandParameterAtAsync`

Method

Queues GemEquipment.GetCommandParameterAt on the worker thread.

public Task<GemCommandParameterEntry> GetCommandParameterAtAsync(nuint commandIndex, nuint parameterIndex, CancellationToken cancellationToken = default)

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.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the parameter rules and name; the caller must dispose the entry. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetCommandParameterAt.

`GetCommandStateAsync`

Method

Queues GemEquipment.GetCommandState on the worker thread.

public Task<GemCommandState> GetCommandStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the command store counters. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetCommandState.

`GetConstantAsync`

Method

Queues GemEquipment.GetConstant on the worker thread.

public Task<SecsItem?> GetConstantAsync(SecsItem id, GemConstantField field, CancellationToken cancellationToken = default)

The encoded length of id counts against the command byte budget.

Parameters

Name	Description
`id`	The equipment constant ID (ECID): an ASCII item or a scalar integer item. It is encoded before the method returns, so the caller may dispose it afterward.
`field`	The field to read.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with a new item that the caller owns and must dispose, or null when the constant has no such optional field. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetConstant.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: id was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidArgument when id is neither an ASCII item nor a scalar integer item; PdcommStatus.LimitExceeded when its encoded length exceeds Int32.MaxValue.

`GetConstantAtAsync`

Method

Queues GemEquipment.GetConstantAt on the worker thread.

public Task<GemConstantEntry> GetConstantAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position in registration order.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with a new entry that the caller owns and must dispose. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetConstantAt.

`GetConstantStateAsync`

Method

Queues GemEquipment.GetConstantState on the worker thread.

public Task<GemConstantState> GetConstantStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the constant store counters. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetConstantState.

`GetDataAsync`

Method

Queues GemEquipment.GetData on the worker thread.

public Task<SecsItem?> GetDataAsync(uint id, GemDataField field, CancellationToken cancellationToken = default)

Parameters

Name	Description
`id`	The data variable ID.
`field`	The field to read.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with a new item that the caller owns and must dispose, or with null when field is GemDataField.Cached and no value is cached.

`GetDataAtAsync`

Method

Queues GemEquipment.GetDataAt on the worker thread.

public Task<GemDataInfo> GetDataAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position in stored order.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the shape and cache state of the data variable.

`GetDataStateAsync`

Method

Queues GemEquipment.GetDataState on the worker thread.

public Task<GemDataState> GetDataStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the data variable store counters.

`GetDirectoryAsync`

Method

Queues GemEquipment.GetDirectory on the worker thread.

public Task<SecsItem> GetDirectoryAsync(uint id, GemDirectoryField field, CancellationToken cancellationToken = default)

Parameters

Name	Description
`id`	The collection event ID (CEID).
`field`	`GemDirectoryField.Name` or `GemDirectoryField.VariableIds`.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with a new item that the caller owns and must dispose.

`GetDirectoryAtAsync`

Method

Queues GemEquipment.GetDirectoryAt on the worker thread.

public Task<GemDirectoryEntryInfo> GetDirectoryAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position in stored order.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the event ID and variable count of the entry.

`GetDirectoryStateAsync`

Method

Queues GemEquipment.GetDirectoryState on the worker thread.

public Task<GemDirectoryState> GetDirectoryStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the event directory counters.

`GetEnhancedCommandAtAsync`

Method

Queues GemEquipment.GetEnhancedCommandAt on the worker thread.

public Task<GemCommandEntry> GetEnhancedCommandAtAsync(nuint objectIndex, nuint commandIndex, CancellationToken cancellationToken = default)

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.
`cancellationToken`	The token that cancels the command before it runs.

Returns

`GetEnhancedCommandParameterAtAsync`

Method

Queues GemEquipment.GetEnhancedCommandParameterAt on the worker thread.

public Task<GemCommandParameterEntry> GetEnhancedCommandParameterAtAsync(nuint objectIndex, nuint commandIndex, nuint parameterIndex, CancellationToken cancellationToken = default)

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.
`cancellationToken`	The token that cancels the command before it runs.

Returns

`GetEnhancedCommandStateAsync`

Method

Queues GemEquipment.GetEnhancedCommandState on the worker thread.

public Task<GemEnhancedCommandState> GetEnhancedCommandStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the enhanced command store counters. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetEnhancedCommandState.

`GetEnhancedObjectAtAsync`

Method

Queues GemEquipment.GetEnhancedObjectAt on the worker thread.

public Task<GemEnhancedObjectEntry> GetEnhancedObjectAtAsync(nuint objectIndex, CancellationToken cancellationToken = default)

Parameters

Name	Description
`objectIndex`	The zero-based position of the object in registration order.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the object metadata and name; the caller must dispose the entry. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetEnhancedObjectAt.

`GetEventAtAsync`

Method

Queues GemEquipment.GetEventAt on the worker thread.

public Task<GemEventDefinition> GetEventAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position in registration order.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the event ID, its enable state and a copy of its linked report IDs.

`GetProgramAsync`

Method

Queues GemEquipment.GetProgram on the worker thread.

public Task<SecsItem> GetProgramAsync(SecsItem id, CancellationToken cancellationToken = default)

The encoded PPID counts against the command byte budget.

Parameters

Name	Description
`id`	The process program ID (PPID): a nonempty ASCII or binary item. It is encoded before the method returns, so the caller may dispose it afterward.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with a new body item that the caller owns and must dispose. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetProgram.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: id was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store; PdcommStatus.InvalidArgument when the PPID is empty or not an ASCII or binary item; PdcommStatus.LimitExceeded when an item exceeds the GEM item limits, the PPID is longer than GemProgramOptions.MaxIdentifierBytes or 120 bytes.

`GetProgramAtAsync`

Method

Queues GemEquipment.GetProgramAt on the worker thread.

public Task<GemProgramEntry> GetProgramAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position in the store.
`cancellationToken`	The token that cancels the command before it runs.

Returns

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`GetProgramStateAsync`

Method

Queues GemEquipment.GetProgramState on the worker thread.

public Task<GemProgramState> GetProgramStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the process program store counters. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetProgramState.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`GetReportAtAsync`

Method

Queues GemEquipment.GetReportAt on the worker thread.

public Task<GemReportDefinition> GetReportAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position in stored order.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the report ID and a copy of its variable IDs.

`GetReportStateAsync`

Method

Queues GemEquipment.GetReportState on the worker thread.

public Task<GemReportState> GetReportStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the report store counters.

`GetReportValueAsync`

Method

Queues GemEquipment.GetReportValue on the worker thread.

public Task<SecsItem> GetReportValueAsync(uint vid, CancellationToken cancellationToken = default)

Parameters

Name	Description
`vid`	The variable ID (VID).
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with a new item that the caller owns and must dispose.

`GetSpoolCatalogAtAsync`

Method

Queues GemEquipment.GetSpoolCatalogAt on the worker thread.

public Task<GemSpoolMessageKey> GetSpoolCatalogAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position in the catalog.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the catalog entry. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetSpoolCatalogAt.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`GetSpoolEntryAtAsync`

Method

Queues GemEquipment.GetSpoolEntryAt on the worker thread.

public Task<GemSpoolEntry> GetSpoolEntryAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position in the spool; 0 is the oldest entry.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with a copy of the entry, which the caller owns and must dispose. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetSpoolEntryAt.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`GetSpoolEntryCapturedAtAsync`

Method

Queues GemEquipment.GetSpoolEntryCapturedAt on the worker thread.

public Task<ulong?> GetSpoolEntryCapturedAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position of the entry in the spool.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the capture time of the entry, or null when the entry has none.

`GetSpoolSelectionAtAsync`

Method

Queues GemEquipment.GetSpoolSelectionAt on the worker thread.

public Task<GemSpoolSelection> GetSpoolSelectionAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based position in the selection.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the stream selection. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetSpoolSelectionAt.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`GetSpoolStateAsync`

Method

Queues GemEquipment.GetSpoolState on the worker thread.

public Task<GemSpoolState> GetSpoolStateAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the spool state. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GetSpoolState.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`GetStatusAsync`

Method

Queues GemEquipment.GetStatus on the worker thread.

public Task<SecsItem> GetStatusAsync(uint id, CancellationToken cancellationToken = default)

The command runs on the worker thread, which owns the endpoint. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or its byte budget is full, faults with ObjectDisposedException after the worker stopped accepting commands, and is canceled when cancellationToken is canceled before the command runs. Otherwise it carries any exception of GemEquipment.GetStatus.

Parameters

Name	Description
`id`	The status variable ID (SVID).
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with a copy of the value; the caller owns the item and must dispose it.

`GetStatusIdAtAsync`

Method

Queues GemEquipment.GetStatusIdAt on the worker thread.

public Task<uint> GetStatusIdAtAsync(nuint index, CancellationToken cancellationToken = default)

Parameters

Name	Description
`index`	The zero-based registration position.
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the status variable ID (SVID).

`GetStatusMetadataAsync`

Method

Queues GemEquipment.GetStatusMetadata on the worker thread.

public Task<GemStatusName> GetStatusMetadataAsync(uint id, CancellationToken cancellationToken = default)

Parameters

Name	Description
`id`	The status variable ID (SVID).
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the status variable name and units.

`GrantProgramAsync`

Method

Queues GemEquipment.GrantProgram on the worker thread.

public Task<HsmsToken> GrantProgramAsync(SecsItem id, uint length, CancellationToken cancellationToken = default)

The encoded PPID counts against the command byte budget.

Parameters

Name	Description
`id`	The process program ID (PPID): a nonempty ASCII or binary item. It is encoded before the method returns, so the caller may dispose it afterward.
`length`	The length in bytes of the body payload that will be sent (LENGTH).
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the S7F1 request. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.GrantProgram.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: id was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store; PdcommStatus.InvalidArgument when the PPID is empty or not an ASCII or binary item; PdcommStatus.LimitExceeded when an item exceeds the GEM item limits, the PPID is longer than GemProgramOptions.MaxIdentifierBytes or 120 bytes or, because the request stays pending, when GemProgramOptions.MaxPendingIds is 0 or the PPID is longer than GemProgramOptions.MaxPendingIdentifierBytes.

`ObserveAlarmAsync`

Method

Queues GemEquipment.ObserveAlarm on the worker thread.

public Task<GemAlarmChange> ObserveAlarmAsync(uint id, bool active, CancellationToken cancellationToken = default)

The observation sends nothing. Queue GemEquipmentWorker.PublishAlarmAsync to send the S5F1 report.

Parameters

Name	Description
`id`	The alarm ID (ALID).
`active`	`true` when the alarm condition is set; `false` when it is cleared.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the observed change. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.ObserveAlarm.

`OperatorOfflineAsync`

Method

Queues GemEquipment.OperatorOffline on the worker thread.

public Task OperatorOfflineAsync(CancellationToken cancellationToken = default)

The command runs on the worker thread, which owns the endpoint. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or its byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, and is canceled when cancellationToken is canceled before the command runs. Otherwise it carries any exception of GemEquipment.OperatorOffline.

Parameters

Name	Description
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes when the equipment is off-line.

`OperatorOnlineAsync`

Method

Queues GemEquipment.OperatorOnline on the worker thread to send S1F1 and attempt to go on-line.

public Task<HsmsToken> OperatorOnlineAsync(CancellationToken cancellationToken = default)

The command runs on the worker thread, which owns the endpoint. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or its byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, and is canceled when cancellationToken is canceled before the command runs. Otherwise it carries any exception of GemEquipment.OperatorOnline.

Parameters

Name	Description
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes with the token of the S1F1 request.

`PublishAlarmAsync`

Method

Queues GemEquipment.PublishAlarm on the worker thread.

public Task<HsmsToken> PublishAlarmAsync(uint id, bool replyExpected, CancellationToken cancellationToken = default)

The S5F2 reply, if requested, arrives through GemWorker.ReadEventsAsync.

Parameters

Name	Description
`id`	The alarm ID (ALID).
`replyExpected`	`true` to set the W-bit and expect an S5F2 (Alarm Report Acknowledge) reply.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the transport token of the S5F1 request. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.PublishAlarm.

`PublishEventAsync`

Method

Queues GemEquipment.PublishEvent on the worker thread.

public Task<HsmsToken> PublishEventAsync(uint dataId, uint eventId, CancellationToken cancellationToken = default)

The command runs on the worker's polling thread, which owns the endpoint. The task is canceled when cancellationToken is canceled before the command runs. It faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when event output is blocked as the command runs, with ObjectDisposedException after the worker stopped accepting commands, and otherwise with the exception of GemEquipment.PublishEvent. The host's S6F12 arrives later as a GemEvent from GemWorker.ReadEventsAsync.

Parameters

Name	Description
`dataId`	The data ID (DATAID) placed in the S6F11 message.
`eventId`	The collection event ID (CEID).
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the pending S6F11/S6F12 transaction.

`PublishEventWithDataAsync`

Method

Queues GemEquipment.PublishEventWithData on the worker thread.

public Task<HsmsToken> PublishEventWithDataAsync(uint dataId, uint eventId, ReadOnlyMemory<GemDataSample> samples, CancellationToken cancellationToken = default)

The command runs on the worker's polling thread, which owns the endpoint. The task is canceled when cancellationToken is canceled before the command runs. It faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when event output is blocked as the command runs, with ObjectDisposedException after the worker stopped accepting commands, and otherwise with the exception of GemEquipment.PublishEventWithData. The command reserves the encoded sample sizes plus a per-sample overhead from the worker's command byte budget. Without samples it is equivalent to GemEquipmentWorker.PublishEventAsync and needs no data configuration, like the synchronous method.

Parameters

Name	Description
`dataId`	The data ID (DATAID) placed in the S6F11 message.
`eventId`	The collection event ID (CEID) of an enabled event, linked or not.
`samples`	Data variable values for this report only. The worker encodes copies before this method returns, so the caller can dispose the items afterwards.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the pending S6F11/S6F12 transaction.

Notes

Throws OperationCanceledException: cancellationToken is already canceled.
Throws ArgumentNullException: A sample or its value is null.
Throws ObjectDisposedException: A sample value was disposed.
Throws PdcommException: PdcommStatus.InvalidState when samples is not empty and the worker was started without a data configuration, or PdcommStatus.LimitExceeded when the samples exceed the configured count, byte or item limits.

`RequestProgramAsync`

Method

Queues GemEquipment.RequestProgram on the worker thread.

public Task<HsmsToken> RequestProgramAsync(SecsItem id, CancellationToken cancellationToken = default)

The encoded PPID counts against the command byte budget.

Parameters

Name	Description
`id`	The process program ID (PPID): a nonempty ASCII or binary item. It is encoded before the method returns, so the caller may dispose it afterward.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the S7F5 request. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.RequestProgram.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: id was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store; PdcommStatus.InvalidArgument when the PPID is empty or not an ASCII or binary item; PdcommStatus.LimitExceeded when an item exceeds the GEM item limits, the PPID is longer than GemProgramOptions.MaxIdentifierBytes or 120 bytes or, because the request stays pending, when GemProgramOptions.MaxPendingIds is 0 or the PPID is longer than GemProgramOptions.MaxPendingIdentifierBytes.

`RespondCommandAsync`

Method

Queues GemEquipment.RespondCommand on the worker thread.

public Task<GemCommandReply> RespondCommandAsync(GemResult result, GemCommandDecision decision, ReadOnlyMemory<GemCommandIssue> issues, CancellationToken cancellationToken = default)

The worker keeps the native result alive until the command finishes. The command reserves the encoded size of the issue names plus one message of GemEquipmentOptions.ItemLimits in the command byte budget.

Parameters

Name	Description
`result`	The result of the received S2F41 request (`GemOutcome.CommandReceived`).
`decision`	The application decision, sent as HCACK when validation accepted the request.
`issues`	The parameter acknowledgements to send with `GemCommandDecision.ParameterErrors`. The issue names are encoded into a snapshot before the method returns.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the HCACK that was sent and the completion event, if any. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.RespondCommand.

Notes

Throws ArgumentNullException: result, an issue, or an issue name is null.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws ObjectDisposedException: result or an issue name was disposed.
Throws PdcommException: PdcommStatus.LimitExceeded when the number of issues, one issue name, or the combined encoded size of the names exceeds the item limits of GemEquipmentOptions.ItemLimits.

`RespondConstantsAsync`

Method

Queues GemEquipment.RespondConstants on the worker thread.

public Task<GemConstantReply> RespondConstantsAsync(GemResult result, GemConstantDecision decision, CancellationToken cancellationToken = default)

result stays valid until the command finishes, even if you dispose it meanwhile. The command reserves SecsLimits.MessageBytes of the GEM item limits plus the constant receipt reservation of the command byte budget.

Parameters

Name	Description
`result`	The result with outcome `GemOutcome.ConstantChangesReceived`.
`decision`	The EAC to send when the receipt validation accepted the request.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the EAC that was sent and whether the store was changed. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.RespondConstants.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: result was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.

`RespondEnhancedCommandAsync`

Method

Queues GemEquipment.RespondEnhancedCommand on the worker thread.

public Task<GemCommandReply> RespondEnhancedCommandAsync(GemResult result, GemCommandDecision decision, SecsItem? acknowledgements, CancellationToken cancellationToken = default)

The worker keeps the native result alive until the command finishes. The command reserves the encoded size of the acknowledgement snapshot plus one message of GemEquipmentOptions.ItemLimits in the command byte budget.

Parameters

Name	Description
`result`	The result of the received S2F49 request (`GemOutcome.EnhancedCommandReceived`).
`decision`	The application decision, sent as HCACK when validation accepted the request.
`acknowledgements`	The parameter acknowledgement list for `GemCommandDecision.ParameterErrors`, or `null`. When validation accepted the request, the item is encoded into a snapshot before the method returns; otherwise it is ignored.
`cancellationToken`	The token that cancels the command before it runs.

Returns

Notes

Throws ArgumentNullException: result is null.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws ObjectDisposedException: result or acknowledgements was disposed.
Throws PdcommException: PdcommStatus.InvalidState when result is not an enhanced command result, or PdcommStatus.LimitExceeded when acknowledgements exceeds GemEquipmentOptions.ItemLimits.

`RespondProgramAsync`

Method

Queues GemEquipment.RespondProgram on the worker thread.

public Task RespondProgramAsync(GemResult result, GemProgramPutMode mode, byte decision, CancellationToken cancellationToken = default)

result stays valid until the command finishes, even if you dispose it meanwhile. The command reserves SecsLimits.MessageBytes of the GEM item limits of the command byte budget.

Parameters

Name	Description
`result`	The result with outcome `GemOutcome.ProgramReceived`.
`mode`	How a granted or received program is stored when its PPID exists.
`decision`	The application decision; 0 accepts. See the synchronous method for the codes.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the reply was sent. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.RespondProgram. It faults with PdcommException (PdcommStatus.ProgramUnconfirmed) when the change was installed but its persistence could not be confirmed.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: result was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`RespondReportQueryAsync`

Method

Queues GemEquipment.RespondReportQuery on the worker thread to answer a received S6F15, S6F19 or S6F21 report query.

public Task RespondReportQueryAsync(GemResult result, ReadOnlyMemory<GemDataSample> samples, CancellationToken cancellationToken = default)

The worker keeps result alive until the command completes. The samples are validated and encoded before the method returns; their size and the item limit SecsLimits.MessageBytes count against the command byte budget. The command runs on the worker thread, which owns the endpoint. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or its byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, and is canceled when cancellationToken is canceled before the command runs. Otherwise it carries any exception of GemEquipment.RespondReportQuery.

Parameters

Name	Description
`result`	The `GemOutcome.ReportQueryReceived` result from a `GemEvent`.
`samples`	Current data variable samples to use in the reply; empty to use only cached and registered values.
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes when the reply is sent.

Notes

Throws ArgumentNullException: result, a sample or a sample value is null.
Throws ObjectDisposedException: result or a sample value was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when samples are given but the worker was started without a data variable configuration; PdcommStatus.LimitExceeded when the samples exceed the data variable limits.

`RespondSpoolingAsync`

Method

Queues GemEquipment.RespondSpool on the worker thread.

public Task<PdcommStatus> RespondSpoolingAsync(GemResult result, CancellationToken cancellationToken = default)

The command reserves the SecsLimits.MessageBytes of the GEM item limits in the command byte budget. result stays valid until the command finishes, even if you dispose it meanwhile.

Parameters

Name	Description
`result`	The `GemOutcome.SpoolReceived` result of the request.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with PdcommStatus.Ok when the reply was sent, or with PdcommStatus.SpoolUnconfirmed when the reply is held until GemEquipmentWorker.ConfirmSpoolReplyAsync. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.RespondSpool.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: result was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`ResyncProgramsAsync`

Method

Queues GemEquipment.ResyncPrograms on the worker thread.

public Task ResyncProgramsAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the parent directory was synchronized. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.ResyncPrograms.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store.

`ResyncSpoolingAsync`

Method

Queues GemEquipment.ResyncSpool on the worker thread.

public Task ResyncSpoolingAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the parent directory of the snapshot file was synchronized. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.ResyncSpool.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`RetrySpoolDequeueAsync`

Method

Queues GemEquipment.RetrySpoolDequeue on the worker thread.

public Task<GemSpoolWriteResult> RetrySpoolDequeueAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the write result of the removal. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.RetrySpoolDequeue.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`SendNextSpoolAsync`

Method

Queues GemEquipment.SendNextSpool on the worker thread.

public Task<HsmsToken> SendNextSpoolAsync(CancellationToken cancellationToken = default)

The delivery outcome arrives through GemWorker.ReadEventsAsync; pass it to GemEquipmentWorker.CompleteSpoolDeliveryAsync.

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the transport token of the sent entry. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.SendNextSpool.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`SendProgramAsync`

Method

Queues GemEquipment.SendProgram on the worker thread.

public Task<HsmsToken> SendProgramAsync(SecsItem id, SecsItem body, CancellationToken cancellationToken = default)

The encoded PPID and body count against the command byte budget.

Parameters

Name	Description
`id`	The process program ID (PPID): a nonempty ASCII or binary item. It is encoded before the method returns.
`body`	The process program body (PPBODY): an ASCII, binary, `I1` to `I8` or `U1` to `U8` item. It is encoded before the method returns, so the caller may dispose both items afterward.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the token of the S7F3 request. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.SendProgram.

Notes

Throws ArgumentNullException: id or body is null.
Throws ObjectDisposedException: id or body was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a process program store; PdcommStatus.InvalidArgument when the PPID is empty or not an ASCII or binary item, or the body has an unsupported format; PdcommStatus.LimitExceeded when an item exceeds the GEM item limits, the PPID is longer than GemProgramOptions.MaxIdentifierBytes or 120 bytes, or the body payload is longer than GemProgramOptions.MaxBodyBytes or 16,777,215 bytes or, because the request stays pending, when GemProgramOptions.MaxPendingIds is 0 or the PPID is longer than GemProgramOptions.MaxPendingIdentifierBytes.

`SetOnlineModeAsync`

Method

Queues GemEquipment.SetOnlineMode on the worker thread.

public Task SetOnlineModeAsync(GemOnlineMode mode, CancellationToken cancellationToken = default)

The command runs on the worker thread, which owns the endpoint. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or its byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, and is canceled when cancellationToken is canceled before the command runs. Otherwise it carries any exception of GemEquipment.SetOnlineMode.

Parameters

Name	Description
`mode`	The on-line mode.
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes when the mode is set.

`StartAsync`

Method

Starts an equipment worker whose endpoint is configured with status variables, reports, alarms, remote commands, enhanced remote commands and equipment constants.

public static Task<GemEquipmentWorker> StartAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, IReadOnlyList<GemStatusVariable>? initialStatus, GemReportConfiguration? reports, GemAlarmConfiguration? alarms, GemCommandConfiguration? commands, GemEnhancedCommandConfiguration? enhancedCommands, GemConstantConfiguration constants, CancellationToken cancellationToken = default)

The configuration is validated and copied before the worker thread starts. The worker thread then creates the endpoint, registers the status variables, installs the constants and the other stores, and starts the transport. Afterwards S2F13 and S2F29 are answered automatically, and S2F15 requests arrive as events that wait for GemEquipmentWorker.RespondConstantsAsync.

Because a received S2F15 result holds a copy of the constant store, every buffered event reserves an additional twice the sum of GemConstantOptions.MaxMetadataBytes and GemConstantOptions.MaxValueBytes of HsmsWorkerOptions.MaxEventBytes.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address passed to `GemEquipment.Create`.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The command queue, event queue and polling options of the worker.
`initialStatus`	The status variables to register, or `null` for none.
`reports`	The report catalog to configure, or `null` for none.
`alarms`	The alarm store to install, or `null` for none.
`commands`	The remote command store to install, or `null` for none.
`enhancedCommands`	The enhanced remote command store to install, or `null` for none.
`constants`	The equipment constant store to install.
`cancellationToken`	The token that cancels the startup.

Returns

A task that completes with the started worker. The task faults with the argument and option validation errors, the validation errors of GemEquipment.ConfigureConstants and the other configuration steps, or the endpoint creation or start failure, and is canceled when cancellationToken is canceled during startup. It faults with ArgumentOutOfRangeException when HsmsWorkerOptions.MaxEventBytes cannot hold one frame body, one GEM result reservation and the constant receipt reservation.

Notes

Throws ArgumentNullException: constants is null.

`StartAsync`

Method

Starts an equipment worker whose endpoint is configured with a collection event directory and optional status variables, report store, alarms, remote commands, enhanced remote commands, data variables and equipment constants.

public static Task<GemEquipmentWorker> StartAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, IReadOnlyList<GemStatusVariable>? initialStatus, GemReportConfiguration? reports, GemAlarmConfiguration? alarms, GemCommandConfiguration? commands, GemEnhancedCommandConfiguration? enhancedCommands, GemDataConfiguration? data, GemConstantConfiguration? constants, GemDirectoryConfiguration directories, CancellationToken cancellationToken = default)

The worker thread creates and owns the endpoint and configures it before starting it.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address to connect to or listen on, depending on the transport mode.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The worker queue, budget and timing options.
`initialStatus`	The status variables to register before the endpoint starts, or `null` for none.
`reports`	The event report store to configure, or `null` for none.
`alarms`	The alarms to configure, or `null` for none.
`commands`	The remote commands to configure, or `null` for none.
`enhancedCommands`	The enhanced remote commands to configure, or `null` for none.
`data`	The data variables and report bindings to configure, or `null` for none.
`constants`	The equipment constants to configure, or `null` for none.
`directories`	The collection event directory to configure.
`cancellationToken`	The token that cancels the startup.

Returns

A task that completes with the started worker. The task faults when an argument is null or invalid, when a configuration exceeds its limits or contains duplicate IDs (PdcommException), or when the endpoint cannot be created, configured or started, for example because the directory does not match the report store or data bindings. It is canceled when cancellationToken is canceled before startup completes.

Notes

Throws ArgumentNullException: directories is null.

`StartAsync`

Method

Starts an equipment worker whose endpoint is configured with data variables and optional status variables, report store, alarms, remote commands, enhanced remote commands and equipment constants.

public static Task<GemEquipmentWorker> StartAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, IReadOnlyList<GemStatusVariable>? initialStatus, GemReportConfiguration? reports, GemAlarmConfiguration? alarms, GemCommandConfiguration? commands, GemEnhancedCommandConfiguration? enhancedCommands, GemDataConfiguration data, GemConstantConfiguration? constants = null, CancellationToken cancellationToken = default)

The worker thread creates and owns the endpoint and configures it before starting it. The data options are kept so that GemEquipmentWorker.UpdateDataVariableAsync and GemEquipmentWorker.PublishEventWithDataAsync can validate values before queueing them.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address to connect to or listen on, depending on the transport mode.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The worker queue, budget and timing options.
`initialStatus`	The status variables to register before the endpoint starts, or `null` for none.
`reports`	The event report store to configure, or `null` for none.
`alarms`	The alarms to configure, or `null` for none.
`commands`	The remote commands to configure, or `null` for none.
`enhancedCommands`	The enhanced remote commands to configure, or `null` for none.
`data`	The data variables and optional report bindings to configure.
`constants`	The equipment constants to configure, or `null` for none.
`cancellationToken`	The token that cancels the startup.

Returns

A task that completes with the started worker. The task faults when an argument is null or invalid (for example, ArgumentException when only one of GemDataConfiguration.BindingOptions and GemDataConfiguration.Bindings is set), when a configuration exceeds its limits, or when the endpoint cannot be created, configured or started. It is canceled when cancellationToken is canceled before startup completes.

Notes

Throws ArgumentNullException: data is null.

`StartAsync`

Method

Starts an equipment worker whose endpoint is configured with status variables, reports, alarms, remote commands and enhanced remote commands.

public static Task<GemEquipmentWorker> StartAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, IReadOnlyList<GemStatusVariable>? initialStatus, GemReportConfiguration? reports, GemAlarmConfiguration? alarms, GemCommandConfiguration? commands, GemEnhancedCommandConfiguration enhancedCommands, CancellationToken cancellationToken = default)

The configuration is validated and copied before the worker thread starts. The worker thread then creates the endpoint, applies the configuration in the order status variables, reports, alarms, commands and enhanced commands, and starts the transport.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address passed to `GemEquipment.Create`.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The command queue, event queue and polling options of the worker.
`initialStatus`	The status variables to register, or `null` for none.
`reports`	The report catalog to configure, or `null` for none. Completion events must be event IDs of this catalog.
`alarms`	The alarm store to install, or `null` for none.
`commands`	The remote command store to install, or `null` for none.
`enhancedCommands`	The enhanced remote command store to install.
`cancellationToken`	The token that cancels the startup.

Returns

A task that completes with the started worker. The task faults with the argument and option validation errors, the validation errors of GemEquipment.ConfigureEnhancedCommands and the other configuration steps, or the endpoint creation or start failure, and is canceled when cancellationToken is canceled during startup.

Notes

Throws ArgumentNullException: enhancedCommands is null.

`StartAsync`

Method

Starts an equipment worker whose endpoint is configured with status variables, reports, alarms and remote commands.

public static Task<GemEquipmentWorker> StartAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, IReadOnlyList<GemStatusVariable>? initialStatus, GemReportConfiguration? reports, GemAlarmConfiguration? alarms, GemCommandConfiguration commands, CancellationToken cancellationToken = default)

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address passed to `GemEquipment.Create`.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The command queue, event queue and polling options of the worker.
`initialStatus`	The status variables to register, or `null` for none.
`reports`	The report catalog to configure, or `null` for none. Completion events must be event IDs of this catalog.
`alarms`	The alarm store to install, or `null` for none.
`commands`	The remote command store to install.
`cancellationToken`	The token that cancels the startup.

Returns

A task that completes with the started worker. The task faults with the argument and option validation errors, the validation errors of GemEquipment.ConfigureCommands and the other configuration steps, or the endpoint creation or start failure, and is canceled when cancellationToken is canceled during startup.

Notes

Throws ArgumentNullException: commands is null.

`StartAsync`

Method

Starts an equipment worker whose endpoint is configured with status variables, reports and alarms.

public static Task<GemEquipmentWorker> StartAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, IReadOnlyList<GemStatusVariable>? initialStatus, GemReportConfiguration? reports, GemAlarmConfiguration alarms, CancellationToken cancellationToken = default)

The configuration is validated and copied before the worker thread starts. The worker thread then creates the endpoint, registers the status variables, configures the reports and installs the alarms before it starts the transport.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address passed to `GemEquipment.Create`.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The command queue, event queue and polling options of the worker.
`initialStatus`	The status variables to register, or `null` for none.
`reports`	The report catalog to configure, or `null` for none. Alarm set and clear events must be event IDs of this catalog.
`alarms`	The alarm store to install.
`cancellationToken`	The token that cancels the startup.

Returns

A task that completes with the started worker. The task faults with the argument and option validation errors, the validation errors of GemEquipment.ConfigureAlarms and the other configuration steps, or the endpoint creation or start failure, and is canceled when cancellationToken is canceled during startup.

Notes

Throws ArgumentNullException: alarms is null.

`StartAsync`

Method

Starts an equipment worker whose endpoint is configured with initial status variables and an event report store.

public static Task<GemEquipmentWorker> StartAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, IReadOnlyList<GemStatusVariable>? initialStatus, GemReportConfiguration reports, CancellationToken cancellationToken = default)

The worker thread creates and owns the endpoint and applies the configuration with GemEquipment.ConfigureReports before starting it.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address to connect to or listen on, depending on the transport mode.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The worker queue, budget and timing options.
`initialStatus`	The status variables to register before the endpoint starts, or `null` for none.
`reports`	The event report store to configure.
`cancellationToken`	The token that cancels the startup.

Returns

A task that completes with the started worker. The task faults when an argument is null or invalid, when reports lists more events than GemReportOptions.MaxEvents (PdcommException with PdcommStatus.LimitExceeded), or when the endpoint cannot be created, configured or started. It is canceled when cancellationToken is canceled before startup completes.

Notes

Throws ArgumentNullException: reports is null.

`StartAsync`

Method

Starts a polling thread that creates, configures and starts a GEM equipment endpoint.

public static Task<GemEquipmentWorker> StartAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, IReadOnlyList<GemStatusVariable>? initialStatus = null, CancellationToken cancellationToken = default)

The task faults with ArgumentNullException when address, transportOptions, options or workerOptions is null; with ArgumentOutOfRangeException when workerOptions is invalid or HsmsWorkerOptions.MaxEventBytes cannot hold one frame body (HsmsOptions.MaxFrameBytes minus 14) plus one GEM result reservation (SecsLimits.MessageBytes of the GEM item limits); with OperationCanceledException when cancellationToken is canceled before the worker started; and with any exception of GemEquipment.Create or GemEquipment.RegisterStatus raised on the worker thread. A startup failure also stops the worker. It also faults with PdcommException (PdcommStatus.LimitExceeded) when initialStatus exceeds GemEquipmentOptions.MaxVariables, GemEquipmentOptions.MaxMetadataBytes, GemEquipmentOptions.MaxValueBytes or the item limits, and with ArgumentNullException when an entry has a null name, units or value.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address, such as `127.0.0.1:5000`; a passive endpoint binds to it (port 0 selects a free port) and an active endpoint connects to it.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The command queue, event buffer, polling and shutdown options.
`initialStatus`	The status variables to register before the transport starts, or `null` for none. Their values are encoded while this method runs, so the caller may dispose them after it returns.
`cancellationToken`	A token that cancels the startup.

Returns

A task that completes with the started worker after the equipment endpoint was created, configured and started on the worker thread; for a passive endpoint GemWorker.LocalAddress is then available.

`StartWithFormattedProgramsAsync`

Method

Starts a polling thread that creates and configures a GEM equipment endpoint, enables formatted process program services on it and starts it.

public static Task<GemEquipmentWorker> StartWithFormattedProgramsAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, GemFormattedProgramConfiguration configuration, IReadOnlyList<GemStatusVariable>? initialStatus = null, CancellationToken cancellationToken = default)

The worker thread registers initialStatus and then applies configuration with GemFormattedProgramConfiguration.Configure. Apart from the configuration check, failures are reported through the task as described for GemEquipmentWorker.StartAsync; the task also faults with any exception of GemFormattedProgramConfiguration.Configure raised on the worker thread. Use GemWorker.FormattedPrograms for the formatted program operations.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address, such as `127.0.0.1:5000`; a passive endpoint binds to it (port 0 selects a free port) and an active endpoint connects to it.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The command queue, event buffer, polling and shutdown options.
`configuration`	The formatted process program services to enable before the transport starts.
`initialStatus`	The status variables to register before the transport starts, or `null` for none. Their values are encoded while this method runs, so the caller may dispose them after it returns.
`cancellationToken`	A token that cancels the startup.

Returns

A task that completes with the started worker after the equipment endpoint was created, configured and started on the worker thread; for a passive endpoint GemWorker.LocalAddress is then available.

Notes

Throws ArgumentNullException: configuration is null.

`StartWithProgramsAsync`

Method

Starts an equipment worker whose process program store is loaded with initial programs.

public static Task<GemEquipmentWorker> StartWithProgramsAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, GemProgramConfiguration programs, IReadOnlyList<GemStatusVariable>? initialStatus = null, CancellationToken cancellationToken = default)

The program configuration is validated and copied before this method returns. The task faults with ArgumentNullException when address, transportOptions, options or workerOptions is null; with ArgumentOutOfRangeException when workerOptions is invalid or HsmsWorkerOptions.MaxEventBytes cannot hold one frame body (HsmsOptions.MaxFrameBytes minus 14) plus one GEM result reservation (SecsLimits.MessageBytes of the GEM item limits); with OperationCanceledException when cancellationToken is canceled before the worker started; and with any exception of GemEquipment.Create or GemEquipment.RegisterStatus raised on the worker thread. A startup failure also stops the worker. It also faults with PdcommException (PdcommStatus.LimitExceeded) when initialStatus exceeds GemEquipmentOptions.MaxVariables, GemEquipmentOptions.MaxMetadataBytes, GemEquipmentOptions.MaxValueBytes or the item limits, and with ArgumentNullException when an entry has a null name, units or value.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address, such as `127.0.0.1:5000`; a passive endpoint binds to it (port 0 selects a free port) and an active endpoint connects to it.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The command queue, event buffer, polling and shutdown options.
`programs`	The process program options, the initial programs, and an optional storage path; a `null` path keeps the store in memory.
`initialStatus`	The status variables to register before the transport starts, or `null` for none. Their values are encoded while this method runs, so the caller may dispose them after it returns.
`cancellationToken`	A token that cancels the startup.

Returns

A task that completes with the started worker after the equipment endpoint was created, configured and started on the worker thread; for a passive endpoint GemWorker.LocalAddress is then available.

Notes

Throws ArgumentNullException: options, programs or its options are null.
Throws ArgumentException: An initial program is null or the storage path contains a NUL character.
Throws ObjectDisposedException: An initial program item was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.InvalidArgument or PdcommStatus.LimitExceeded when the program options or initial programs are invalid or exceed the program limits.

`StartWithProgramsAsync`

Method

Starts an equipment worker with an empty process program store.

public static Task<GemEquipmentWorker> StartWithProgramsAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, GemProgramOptions programs, IReadOnlyList<GemStatusVariable>? initialStatus = null, CancellationToken cancellationToken = default)

Process program transactions (stream 7) are handled by the configured store. The task faults with ArgumentNullException when address, transportOptions, options or workerOptions is null; with ArgumentOutOfRangeException when workerOptions is invalid or HsmsWorkerOptions.MaxEventBytes cannot hold one frame body (HsmsOptions.MaxFrameBytes minus 14) plus one GEM result reservation (SecsLimits.MessageBytes of the GEM item limits); with OperationCanceledException when cancellationToken is canceled before the worker started; and with any exception of GemEquipment.Create or GemEquipment.RegisterStatus raised on the worker thread. A startup failure also stops the worker. It also faults with PdcommException (PdcommStatus.LimitExceeded) when initialStatus exceeds GemEquipmentOptions.MaxVariables, GemEquipmentOptions.MaxMetadataBytes, GemEquipmentOptions.MaxValueBytes or the item limits, and with ArgumentNullException when an entry has a null name, units or value.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address, such as `127.0.0.1:5000`; a passive endpoint binds to it (port 0 selects a free port) and an active endpoint connects to it.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The command queue, event buffer, polling and shutdown options.
`programs`	The process program limits and grant policy; the store is kept in memory.
`initialStatus`	The status variables to register before the transport starts, or `null` for none. Their values are encoded while this method runs, so the caller may dispose them after it returns.
`cancellationToken`	A token that cancels the startup.

Returns

A task that completes with the started worker after the equipment endpoint was created, configured and started on the worker thread; for a passive endpoint GemWorker.LocalAddress is then available.

Notes

Throws ArgumentNullException: programs is null.
Throws PdcommException: PdcommStatus.InvalidArgument when the grant policy of programs is undefined.

`StartWithSpoolingAsync`

Method

Starts an equipment worker whose endpoint gets a spool before the transport starts.

public static Task<GemEquipmentWorker> StartWithSpoolingAsync(string address, HsmsOptions transportOptions, GemEquipmentOptions options, HsmsWorkerOptions workerOptions, GemEquipmentSpoolConfiguration spooling, IReadOnlyList<GemStatusVariable>? initialStatus = null, CancellationToken cancellationToken = default)

The task faults as for GemEquipmentWorker.StartAsync and also with any exception of GemEquipment.ConfigureSpooling or GemEquipment.ConfigureLocalSpooling raised on the worker thread. The write results of those calls are not returned. A PdcommStatus.SpoolUnconfirmed result means the spool was installed in memory and on disk but the parent directory synchronization failed; the worker still starts. When the application needs confirmed durability of a file-backed spool, call GemEquipmentWorker.ResyncSpoolingAsync once after this task completes: it succeeds only when the directory is synchronized, whether or not the startup write was confirmed, and it never rewrites the snapshot. Only a worker started this way accepts the spooling commands.

Parameters

Name	Description
`address`	The numeric IPv4 or IPv6 socket address, such as `127.0.0.1:5000`; a passive endpoint binds to it (port 0 selects a free port) and an active endpoint connects to it.
`transportOptions`	The HSMS transport options.
`options`	The GEM equipment options.
`workerOptions`	The command queue, event buffer, polling and shutdown options.
`spooling`	The spool to attach; it is copied before this method returns.
`initialStatus`	The status variables to register before the transport starts, or `null` for none. Their values are encoded while this method runs, so the caller may dispose them after it returns.
`cancellationToken`	A token that cancels the startup.

Returns

A task that completes with the started worker after the equipment endpoint was created, given its spool and started on the worker thread; for a passive endpoint GemWorker.LocalAddress is then available.

Notes

Throws ArgumentNullException: spooling or its GemEquipmentSpoolConfiguration.Options is null.
Throws ArgumentOutOfRangeException: The GemSpoolPolicy.Overflow of GemEquipmentSpoolConfiguration.LocalPolicy is not a defined value.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.LimitExceeded when the catalog exceeds GemSpoolOptions.MaxCatalogEntries or the selections exceed GemSpoolOptions.MaxStreams or GemSpoolOptions.MaxFunctionsPerStream.

`StopSpoolTransmitAsync`

Method

Queues GemEquipment.StopSpoolTransmit on the worker thread.

public Task StopSpoolTransmitAsync(CancellationToken cancellationToken = default)

Parameters

Name	Description
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the transmission run has ended. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full, or when the command runs while event output is blocked), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.StopSpoolTransmit.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`SyncSpoolingAsync`

Method

Queues GemEquipment.SyncSpool on the worker thread.

public Task<GemSpoolWriteResult> SyncSpoolingAsync(ulong now, CancellationToken cancellationToken = default)

Queue it after reading events so that captures, replies and deliveries see the current communication state.

Parameters

Name	Description
`now`	An application timestamp, stored as the start time when spooling activates.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes with the write result. The task faults with PdcommException (PdcommStatus.Backpressure when the command queue or byte budget is full), with ObjectDisposedException after the worker stopped accepting commands, is canceled when cancellationToken is canceled before the command runs, and otherwise carries the exception of GemEquipment.SyncSpool.

Notes

Throws PdcommException: PdcommStatus.InvalidState when the worker was not started with GemEquipmentWorker.StartWithSpoolingAsync.

`UpdateDataVariableAsync`

Method

Queues GemEquipment.UpdateDataVariable on the worker thread.

public Task UpdateDataVariableAsync(uint id, SecsItem value, CancellationToken cancellationToken = default)

The command runs on the worker's polling thread, which owns the endpoint. The task is canceled when cancellationToken is canceled before the command runs. It faults with PdcommException (PdcommStatus.Backpressure) when the command queue or byte budget is full or when event output is blocked as the command runs, with ObjectDisposedException after the worker stopped accepting commands, and otherwise with the exception of GemEquipment.UpdateDataVariable. The command reserves the value's encoded size from the worker's command byte budget.

Parameters

Name	Description
`id`	The data variable ID.
`value`	The new value. The worker encodes a copy before this method returns, so the caller can dispose the item afterwards.
`cancellationToken`	The token that cancels the command before it runs.

Returns

A task that completes when the cached value was replaced.

Notes

Throws ArgumentNullException: value is null.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws ObjectDisposedException: value was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the worker was started without a data configuration, or PdcommStatus.LimitExceeded when the value exceeds the configured item limits.

`UpdateStatusAsync`

Method

Queues GemEquipment.UpdateStatus on the worker thread.

public Task UpdateStatusAsync(uint id, SecsItem value, CancellationToken cancellationToken = default)

The value is encoded before the method returns, so the caller may dispose it afterward; its encoded length counts against the command byte budget. The command runs on the worker thread, which owns the endpoint. The task faults with PdcommException (PdcommStatus.Backpressure) when the command queue or its byte budget is full or when the command runs while event output is blocked because the event buffer is full, faults with ObjectDisposedException after the worker stopped accepting commands, and is canceled when cancellationToken is canceled before the command runs. Otherwise it carries any exception of GemEquipment.UpdateStatus.

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.
`cancellationToken`	A token that cancels the command if it has not run yet.

Returns

A task that completes when the value is stored.

Notes

Throws ArgumentNullException: value is null.
Throws ObjectDisposedException: value was disposed.
Throws OperationCanceledException: cancellationToken is already canceled.
Throws PdcommException: PdcommStatus.LimitExceeded when the encoded value is larger than GemEquipmentOptions.MaxValueBytes or the item limit SecsLimits.MessageBytes.