PDComm.GemFormattedPrograms

Class

Provides the formatted process program services of a GEM endpoint: the S7F21 to S7F32 transactions, the equipment's local formatted program store and capability catalog, program selection, dry runs and execution tracking.

public sealed class GemFormattedPrograms

Get an instance from GemEndpoint.FormattedPrograms, or use GemWorker.FormattedPrograms to run the same operations on a worker's polling thread. Each service is configured once, while the endpoint is stopped, with its Configure method or with GemFormattedProgramConfiguration.

The host sends S7F21 (GemFormattedPrograms.SubmitCapabilityQuery), S7F23 (GemFormattedPrograms.SubmitTransfer), S7F25 (GemFormattedPrograms.SubmitQuery) and S7F31 (GemFormattedPrograms.SubmitVerificationRequest), and answers S7F27 and S7F29. The equipment sends S7F27 (GemFormattedPrograms.SubmitVerificationReport) and the S7F29/S7F27 negotiation (GemFormattedPrograms.PrepareVerification), answers S7F21, S7F23, S7F25 and S7F31, and owns the local store, capability catalog, selection, dry run and execution state. A call made in the wrong role fails with PdcommException and PdcommStatus.InvalidState.

Every method serializes on the endpoint's internal lock and throws ObjectDisposedException after the endpoint is disposed. Results, snapshots, reports and actions returned here own their native memory, stay valid after the endpoint is disposed, and must be disposed by the caller. The execution methods only track state that the application reports; they never drive the equipment.

Members

`CancelExecution`

Method

Requests the cancellation of a running execution as a cancel action.

public GemFormattedProgramExecutionAction CancelExecution(GemFormattedProgramExecutionToken token)

Equipment only. While a cancel is pending, calling again returns the same pending action. Report its result with GemFormattedPrograms.SubmitActionResult; a rejected cancel returns the execution to GemFormattedProgramExecutionState.Running.

Parameters

Name	Description
`token`	The execution token from `GemFormattedProgramExecutionStart.Token`.

Returns

The cancel action, which carries the index of the next command that would run. The caller owns it and must dispose it.

Notes

Throws ArgumentNullException: token is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.StaleToken when token does not identify the current execution; PdcommStatus.InvalidState on a host, when the query service is not configured or when the execution is not GemFormattedProgramExecutionState.Running.

`ClearCapabilities`

Method

Removes the equipment's process capabilities catalog.

public ulong ClearCapabilities()

Equipment only. While the catalog is empty, GemFormattedPrograms.RespondCapabilityQuery fails with PdcommStatus.InvalidState and a dry run reports the capability as missing.

Returns

The catalog revision after the call. It increases by one when a catalog was removed and is unchanged when the catalog was already empty.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host or when the service is not configured.

`ClearSelection`

Method

Clears the current program selection.

public bool ClearSelection(GemFormattedProgramSelectionToken token)

Equipment only.

Parameters

Name	Description
`token`	The token of the current selection, from `GemFormattedPrograms.SelectProgram`.

Returns

true when the selection was cleared; false when there was nothing to clear.

Notes

Throws ArgumentNullException: token is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.StaleToken when token does not identify the current selection; PdcommStatus.InvalidState on a host or when the query service is not configured.

`CompleteExecution`

Method

Reports the final outcome of a running execution and ends it.

public void CompleteExecution(GemFormattedProgramExecutionToken token, ulong reportId, GemFormattedProgramTerminalOutcome outcome, ReadOnlyMemory<byte> detail)

Equipment only. The detail bytes are copied. Repeating the same report ID, outcome and detail succeeds without a change.

Parameters

Name	Description
`token`	The execution token from `GemFormattedProgramExecutionStart.Token`.
`reportId`	An application-defined report ID that is recorded with the outcome.
`outcome`	The final outcome of the program.
`detail`	Application-defined detail bytes that are recorded with the outcome, at most `SecsLimits.MessageBytes` of the endpoint's GEM item limits; may be empty.

Notes

Throws ArgumentNullException: token is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when outcome is not a defined value; PdcommStatus.StaleToken when token does not identify the current execution or a different outcome was already recorded; PdcommStatus.InvalidState on a host, when the query service is not configured, when the execution is not GemFormattedProgramExecutionState.Running with no pending action, or when GemFormattedProgramTerminalOutcome.Complete is reported before every command was applied; PdcommStatus.LimitExceeded when detail is too long.

`ConfigureCapabilities`

Method

Enables the S7F21/S7F22 process capabilities service and, on equipment, its local capability catalog.

public void ConfigureCapabilities(GemFormattedProgramCapabilityOptions options)

Configure the service once, before GemEndpoint.Start. The catalog starts empty at revision 0.

Parameters

Name	Description
`options`	The catalog bounds and the request, received, result and history capacities of the service.

Notes

Throws ArgumentNullException: options is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint is not stopped or the service is already configured; PdcommStatus.InvalidArgument when the options are invalid.

`ConfigureQueries`

Method

Enables the S7F25/S7F26 formatted process program request service and, on equipment, the local formatted program store, selection and execution tracking.

public void ConfigureQueries(GemFormattedProgramQueryOptions options)

Configure the service once, before GemEndpoint.Start. The store, selection, dry run and execution methods require it on equipment.

Parameters

Name	Description
`options`	The command and parameter bounds, the store bounds, and the request, received, result and history capacities of the service.

Notes

Throws ArgumentNullException: options is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint is not stopped or the service is already configured; PdcommStatus.InvalidArgument when the options are invalid.

`ConfigureTransfers`

Method

Enables the S7F23/S7F24 formatted process program send service.

public void ConfigureTransfers(GemFormattedProgramTransferOptions options)

Configure the service once, before GemEndpoint.Start.

Parameters

Name	Description
`options`	The command and parameter bounds and the request, received, result and history capacities of the service.

Notes

Throws ArgumentNullException: options is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint is not stopped or the service is already configured; PdcommStatus.InvalidArgument when the options are invalid.

`ConfigureVerificationNegotiation`

Method

Enables the S7F29/S7F30 verification inquire and grant negotiation that precedes an S7F27 verification send.

public void ConfigureVerificationNegotiation(GemFormattedProgramVerificationNegotiationOptions options)

Configure the service once, before GemEndpoint.Start.

Parameters

Name	Description
`options`	The issue bounds, the prepared-negotiation capacity, and the request, received, result and history capacities of the service.

Notes

Throws ArgumentNullException: options is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint is not stopped or the service is already configured; PdcommStatus.InvalidArgument when the options are invalid.

`ConfigureVerificationReports`

Method

Enables the S7F27/S7F28 process program verification report service.

public void ConfigureVerificationReports(GemFormattedProgramOptions options)

Configure the service once, before GemEndpoint.Start.

Parameters

Name	Description
`options`	The issue bounds and the request, received, result and history capacities of the service.

Notes

Throws ArgumentNullException: options is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint is not stopped or the service is already configured; PdcommStatus.InvalidArgument when the options are invalid.

`ConfigureVerificationRequests`

Method

Enables the S7F31/S7F32 verification request service.

public void ConfigureVerificationRequests(GemFormattedProgramVerificationRequestOptions options)

Configure the service once, before GemEndpoint.Start.

Parameters

Name	Description
`options`	The command and parameter bounds and the request, received, result and history capacities of the service.

Notes

Throws ArgumentNullException: options is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState when the endpoint is not stopped or the service is already configured; PdcommStatus.InvalidArgument when the options are invalid.

`DryRun`

Method

Analyzes the selected program against the equipment's capability catalog without executing it.

public GemFormattedProgramDryRunReport DryRun(GemFormattedProgramSelectionToken token, GemFormattedProgramDryRunOptions options)

Equipment only. The analysis is read-only and structural; it does not perform or guarantee physical execution. Without a capability catalog the outcome is GemFormattedProgramDryRunOutcome.Indeterminate. Pass a report that is not rejected to GemFormattedPrograms.StartExecution.

Parameters

Name	Description
`token`	The token of the current selection, from `GemFormattedPrograms.SelectProgram`.
`options`	The analysis policy version, which must be `1`, and the bounds on the issue count and the encoded program size in bytes.

Returns

The dry run report with its outcome and issues. The caller owns it and must dispose it.

Notes

Throws ArgumentNullException: token or options is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.StaleToken when token no longer matches a valid selection; PdcommStatus.InvalidArgument when the policy version is not supported; PdcommStatus.LimitExceeded when the program or the issue list exceeds options; PdcommStatus.InvalidState on a host or when the query service is not configured.

`GetActionToken`

Method

Gets the token that identifies an execution action, for GemFormattedPrograms.SubmitActionResult.

public static GemFormattedProgramExecutionActionToken GetActionToken(GemFormattedProgramExecutionAction action)

The method reads only the action object; it does not use an endpoint.

Parameters

Name	Description
`action`	An action returned by `GemFormattedPrograms.StartExecution`, `GemFormattedPrograms.StepExecution` or `GemFormattedPrograms.CancelExecution`.

Returns

The action kind, endpoint, session, execution generation and action sequence of the action.

Notes

Throws ArgumentNullException: action is null.
Throws ObjectDisposedException: action was disposed.
Throws PdcommException: The native library failed to read the action.

`GetExecutionSnapshot`

Method

Gets a snapshot of the equipment's formatted program execution tracker.

public GemFormattedProgramExecutionSnapshot GetExecutionSnapshot()

Equipment only. The snapshot does not change when the execution state changes later.

Returns

A copy of the state, tokens, captured program, pending action and application report. The caller owns it and must dispose it.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host or when the query service is not configured.

`GetSelectionSnapshot`

Method

Gets a snapshot of the current program selection.

public GemFormattedProgramSelectionSnapshot GetSelectionSnapshot()

Equipment only. The snapshot owns its contents.

Returns

A snapshot with the selection state (empty, ready or stale), the stale reason and the selected program. The caller owns it and must dispose it.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host or when the query service is not configured.

`GetStoreInfo`

Method

Gets the revision, usage and limits of the equipment's local formatted program store.

public GemFormattedProgramStoreInfo GetStoreInfo()

Equipment only.

Returns

The store revision, entry count, identifier and encoded byte totals, and their limits.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host or when the query service is not configured.

`GetStoreSnapshot`

Method

Gets a copy of every program in the equipment's local formatted program store.

public GemFormattedProgramStoreSnapshot GetStoreSnapshot()

Equipment only. The snapshot owns a full copy and stays valid after later store changes and after the endpoint is disposed.

Returns

A snapshot of the store. The caller owns it and must dispose it.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host or when the query service is not configured.

`PrepareVerification`

Method

Prepares an S7F27 verification report for the S7F29/S7F30 negotiation without sending anything.

public GemResult PrepareVerification(SecsItem id, IReadOnlyList<GemFormattedProgramIssue> issues)

Equipment only. Pass the result to GemFormattedPrograms.SubmitPreparedVerification to send S7F29 with the body length (LENGTH). Read it with GemResult.GetFormattedProgramVerificationNegotiationInfo, GemResult.GetFormattedProgramId and GemResult.GetFormattedProgramIssueAt.

Parameters

Name	Description
`id`	The process program ID (PPID): a nonempty ASCII or Binary item of at most 120 bytes.
`issues`	The verification issues in wire order.

Returns

A prepared negotiation result that records the encoded S7F27 body length. The caller owns it and must dispose it.

Notes

Throws ArgumentNullException: id or issues, or an issue or its text, is null.
Throws ArgumentException: An issue text contains an invalid UTF-16 surrogate sequence.
Throws ObjectDisposedException: The endpoint or id was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host, when the negotiation service is not configured or when GEM communication is not established; PdcommStatus.InvalidArgument when the PPID or an issue is invalid or the issues exceed GemFormattedProgramVerificationNegotiationOptions; PdcommStatus.LimitExceeded when the S7F27 message would not fit in one HSMS frame or the prepared capacity is used up.

`PutProgram`

Method

Writes a program to the equipment's local formatted program store.

public void PutProgram(GemFormattedProgramPayload payload, GemFormattedProgramStoreAction action)

Equipment only. The inputs are copied and a failed call leaves the store unchanged. A successful write increases the store revision, and a selection of the replaced program becomes stale.

Parameters

Name	Description
`payload`	The program to store; `GemFormattedProgramPayload` describes the rules for each field.
`action`	How to write the program: `GemFormattedProgramStoreAction.CreateOnly`, `GemFormattedProgramStoreAction.ReplaceOnly` or `GemFormattedProgramStoreAction.Upsert`.

Notes

Throws ArgumentNullException: payload, its ID, model, software revision or command list, or a command, its code, its parameter list or one of its parameters is null.
Throws ArgumentException: A string contains an invalid UTF-16 surrogate sequence.
Throws ObjectDisposedException: The endpoint or an item of payload was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when a field of payload is invalid, or action is GemFormattedProgramStoreAction.RespondOnly or undefined; PdcommStatus.InvalidState on a host, when the query service is not configured, when GemFormattedProgramStoreAction.CreateOnly finds an existing program or GemFormattedProgramStoreAction.ReplaceOnly finds none, or when a pending transfer response locks the store; PdcommStatus.LimitExceeded when the program exceeds GemFormattedProgramQueryOptions, the store, or the item limits.

`RemoveProgram`

Method

Removes a program from the equipment's local formatted program store.

public bool RemoveProgram(SecsItem id)

Equipment only. A removal increases the store revision, and a selection of the removed program becomes stale.

Parameters

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

Returns

true when a program was removed; false when no program had the PPID.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: The endpoint or id was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host, when the query service is not configured or when a pending transfer response locks the store; PdcommStatus.InvalidArgument when id is not a valid PPID item.

`RemoveQuery`

Method

Removes a program from the equipment's local formatted program store.

public bool RemoveQuery(SecsItem id)

Equipment only. An alias of GemFormattedPrograms.RemoveProgram.

Parameters

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

Returns

true when a program was removed; false when no program had the PPID.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: The endpoint or id was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host or when the query service is not configured; PdcommStatus.InvalidArgument when id is not a valid PPID item; another status when the store is locked by a pending transfer response.

`ReplaceCapabilities`

Method

Replaces the equipment's process capabilities catalog that answers S7F21.

public ulong ReplaceCapabilities(string model, string softwareRevision, byte commandMaximum, uint byteMaximum, IReadOnlyList<GemFormattedProgramCapabilityCommand> commands)

Equipment only. The inputs are copied; a failed call leaves the current catalog unchanged. A received S7F21 is answered from the catalog when GemFormattedPrograms.RespondCapabilityQuery is called. The dry run compares programs with this catalog.

Parameters

Name	Description
`model`	The equipment model type (MDLN): ASCII text of at most 20 bytes.
`softwareRevision`	The software revision (SOFTREV): ASCII text of at most 20 bytes.
`commandMaximum`	The largest number of commands a program may contain (CMDMAX); it is sent as a U1 item.
`byteMaximum`	The largest encoded program size, in bytes (BYTMAX); it is sent as a U4 item.
`commands`	The command entries in wire order.

Returns

The catalog revision after the call. It is unchanged when the new catalog equals the current one and increases by one otherwise.

Notes

Throws ArgumentNullException: model, softwareRevision or commands, or a command, its code, name, dependency list, parameter list or one of its parameters is null.
Throws ArgumentException: A string contains an invalid UTF-16 surrogate sequence.
Throws ObjectDisposedException: The endpoint or a parameter item was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host or when the service is not configured; PdcommStatus.InvalidArgument when text is not ASCII or too long, a block definition is out of range or a parameter descriptor has the wrong shape; PdcommStatus.LimitExceeded when the catalog exceeds GemFormattedProgramCapabilityOptions.

`RespondCapabilityQuery`

Method

Answers a received S7F21 with an S7F22 (Process Capabilities Data) built from the local catalog.

public void RespondCapabilityQuery(GemResult result)

Equipment only. The first call captures the current catalog in the result, so a retry after a failure sends the same data. A call after the reply was sent returns without sending again.

Parameters

Name	Description
`result`	The `GemResult` of the received S7F21 request (`GemOutcome.FormattedCapabilityReceived`) from this endpoint and session.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host, when GEM communication is not established, when result is not a capabilities request or when the catalog is empty; PdcommStatus.StaleToken when result belongs to another endpoint or session; PdcommStatus.Backpressure when the transport cannot queue the reply.

`RespondQuery`

Method

Answers a received S7F25 with an S7F26 (Formatted Process Program Data) from the local store.

public void RespondQuery(GemResult result)

Equipment only. The reply carries the stored program with the requested PPID, or an empty list when there is none; the answer is then also readable from result. A call after the reply was sent returns without sending again.

Parameters

Name	Description
`result`	The `GemResult` of the received S7F25 (`GemOutcome.FormattedQueryReceived`) from this endpoint and session.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host, when GEM communication is not established or when result is not a program request; PdcommStatus.StaleToken when result belongs to another endpoint or session or is not a received request; PdcommStatus.Backpressure when the transport cannot queue the reply.

`RespondTransfer`

Method

Answers a received S7F23 with an S7F24 (Formatted Process Program Acknowledge).

public void RespondTransfer(GemResult result, byte acknowledgement)

Equipment only. The local store is not changed; use GemFormattedPrograms.RespondTransferAndStore to store the program. Repeating the same answer after the reply was sent succeeds without sending again.

Parameters

Name	Description
`result`	The `GemResult` of the received S7F23 (`GemOutcome.FormattedTransferReceived`) from this endpoint and session.
`acknowledgement`	The acknowledge code (ACKC7), from 0 through 7; 0 accepts the program.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when acknowledgement is greater than 7; PdcommStatus.InvalidState on a host, when GEM communication is not established or when result is not a transfer; PdcommStatus.StaleToken when result belongs to another endpoint or session, is not a received request, or was already answered differently; PdcommStatus.Backpressure when the transport cannot queue the reply.

`RespondTransferAndStore`

Method

Answers a received S7F23 with an S7F24 and, in the same step, writes the received program to the local store.

public void RespondTransferAndStore(GemResult result, byte acknowledgement, GemFormattedProgramStoreAction action)

Equipment only. The acknowledge code does not select the action: the program is written whenever a store action is given. The store write is reserved before the reply is queued and committed after it; while the reservation is pending, other store changes fail. After PdcommStatus.Backpressure, repeat the call with the same arguments. Repeating the same answer after the reply was sent succeeds without sending again.

Parameters

Name	Description
`result`	The `GemResult` of the received S7F23 (`GemOutcome.FormattedTransferReceived`) from this endpoint and session.
`acknowledgement`	The acknowledge code (ACKC7), from 0 through 7; 0 accepts the program.
`action`	How to write the program to the store; `GemFormattedProgramStoreAction.RespondOnly` replies without writing.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when acknowledgement is greater than 7 or action is undefined; PdcommStatus.InvalidState on a host, when GEM communication is not established, when result is not a transfer, when the query service that owns the store is not configured, or when the store rejects the action; PdcommStatus.StaleToken when result belongs to another endpoint or session, is not a received request, or was already answered with a different code or action; PdcommStatus.Backpressure when the transport cannot queue the reply; PdcommStatus.LimitExceeded when the program exceeds the store limits.

`RespondVerification`

Method

Answers a received S7F29 with an S7F30 (Process Program Verification Grant).

public void RespondVerification(GemResult result, byte grant)

Host only. Repeating the same answer after the reply was sent succeeds without sending again. The grant is kept when the reply cannot be queued; repeat the call with the same grant or call GemFormattedPrograms.RetryVerificationResponse. A granting reply lets the equipment send its S7F27 report, which the host receives through the service configured with GemFormattedPrograms.ConfigureVerificationReports.

Parameters

Name	Description
`result`	The `GemResult` of the received S7F29 (`GemOutcome.FormattedVerificationInquireReceived`) from this endpoint and session.
`grant`	The grant code (PPGNT), from 0 through 63; 0 grants the verification send.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when grant is greater than 63; PdcommStatus.InvalidState on equipment, when GEM communication is not established or when result is not a verification inquire; PdcommStatus.StaleToken when result belongs to another endpoint or session, is not a received request, or a different grant was already prepared or sent; PdcommStatus.Backpressure when the transport cannot queue the reply.

`RespondVerificationReport`

Method

Answers a received S7F27 verification report with S7F28 (Process Program Verification Acknowledge).

public void RespondVerificationReport(GemResult result)

Host only. S7F28 has no body. After PdcommStatus.Backpressure the prepared reply is kept and the call can be repeated; a call after the reply was sent returns without sending again.

Parameters

Name	Description
`result`	The `GemResult` of the received S7F27 (`GemOutcome.FormattedVerificationReportReceived`) from this endpoint and session.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidState on equipment, when GEM communication is not established or when result is not a verification report; PdcommStatus.StaleToken when result belongs to another endpoint or session or is not a received request; PdcommStatus.Backpressure when the transport cannot queue the reply.

`RespondVerificationRequest`

Method

Answers a received S7F31 with an S7F32 (Verification Request Acknowledge).

public void RespondVerificationRequest(GemResult result, byte acknowledgement)

Equipment only. Repeating the same answer after the reply was sent succeeds without sending again.

Parameters

Name	Description
`result`	The `GemResult` of the received S7F31 (`GemOutcome.FormattedVerificationRequestReceived`) from this endpoint and session.
`acknowledgement`	The acknowledge code (ACKC7), from 0 through 7; 0 accepts the request.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when acknowledgement is greater than 7; PdcommStatus.InvalidState on a host, when GEM communication is not established or when result is not a verification request; PdcommStatus.StaleToken when result belongs to another endpoint or session, is not a received request, or was already answered with a different code; PdcommStatus.Backpressure when the transport cannot queue the reply.

`RetryVerification`

Method

Sends the S7F27 of a granted verification negotiation when the automatic send after the grant failed.

public HsmsToken RetryVerification(GemResult result)

Equipment only. The S7F28 reply arrives as a GemResult with GemOutcome.FormattedVerificationNegotiationAck.

Parameters

Name	Description
`result`	The prepared negotiation `GemResult`, or the result that reported its S7F30 grant, on this endpoint and session.

Returns

The transport token of the accepted S7F27 request.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host, when GEM communication is not established or when result is not a negotiation result; PdcommStatus.StaleToken when result belongs to another endpoint or session or is a received request; PdcommStatus.Backpressure when the pending request table or the transport is full; another status such as PdcommStatus.LimitExceeded when the negotiation was not granted or its S7F27 was already sent.

`RetryVerificationResponse`

Method

Sends again the S7F30 reply that an earlier GemFormattedPrograms.RespondVerification could not queue.

public void RetryVerificationResponse(GemResult result)

Host only.

Parameters

Name	Description
`result`	The `GemResult` of the received S7F29 (`GemOutcome.FormattedVerificationInquireReceived`) whose reply is still unsent.

Notes

Throws ArgumentNullException: result is null.
Throws ObjectDisposedException: The endpoint or result was disposed.
Throws PdcommException: PdcommStatus.InvalidState on equipment, when GEM communication is not established or when result is not a verification inquire; PdcommStatus.StaleToken when result belongs to another endpoint or session, is not a received request or was already answered; PdcommStatus.Backpressure when the transport cannot queue the reply; another status when no grant was prepared.

`SeedQuery`

Method

Adds a program to the equipment's local formatted program store, or replaces the stored program with the same PPID.

public void SeedQuery(GemFormattedProgramPayload payload)

Equipment only. An alias of GemFormattedPrograms.PutProgram with GemFormattedProgramStoreAction.Upsert that also checks that the program fits in an S7F26 reply. The store answers S7F25 requests and feeds selection and execution. The inputs are copied during the call.

Parameters

Name	Description
`payload`	The program to store; `GemFormattedProgramPayload` describes the rules for each field.

Notes

Throws ArgumentNullException: payload, its ID, model, software revision or command list, or a command, its code, its parameter list or one of its parameters is null.
Throws ArgumentException: A string contains an invalid UTF-16 surrogate sequence.
Throws ObjectDisposedException: The endpoint or an item of payload was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host or when the query service is not configured; PdcommStatus.InvalidArgument when a field of payload is invalid; PdcommStatus.LimitExceeded when the program exceeds GemFormattedProgramQueryOptions, the store, or the item limits; another status when the store is locked by a pending transfer response.

`SelectProgram`

Method

Selects a stored program for a dry run and execution.

public GemFormattedProgramSelectionToken SelectProgram(SecsItem id)

Equipment only. Selection is local state and performs no physical execution. A new selection replaces the previous one; selecting the same unchanged program again returns the same token. The selection becomes stale when the program changes or is removed, the HSMS session changes or the connection is lost.

Parameters

Name	Description
`id`	The process program ID (PPID) of a program in the local store: an ASCII or Binary item.

Returns

The token that identifies this selection.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: The endpoint or id was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host, when the query service is not configured or when the store has no program with the PPID; PdcommStatus.InvalidArgument when id is not a valid PPID item; PdcommStatus.LimitExceeded when the program is too large to capture.

`StartExecution`

Method

Starts tracking the execution of the selected formatted program and returns its first action, a start action.

public GemFormattedProgramExecutionStart StartExecution(GemFormattedProgramSelectionToken selection, GemFormattedProgramDryRunReport report)

Equipment only. No message is sent and the equipment is not driven: the application performs the action and reports the result with GemFormattedPrograms.SubmitActionResult. While the execution has not reached a terminal state, calling again with the same selection and report returns the pending start action again. Starting after a terminal state replaces the previous execution.

Parameters

Name	Description
`selection`	The token returned by `GemFormattedPrograms.SelectProgram`; it must still match the current selection.
`report`	A dry run report of the same selection from `GemFormattedPrograms.DryRun`, made against the current capability catalog revision. A report with the outcome `GemFormattedProgramDryRunOutcome.Reject` is refused.

Returns

The execution token and the start action. The caller owns the returned object and must dispose it.

Notes

Throws ArgumentNullException: selection or report is null.
Throws ObjectDisposedException: The endpoint or report was disposed.
Throws PdcommException: PdcommStatus.StaleToken when selection no longer matches the current selection, or when report does not match the selection, the endpoint or the current capability catalog revision; PdcommStatus.InvalidState on a host, when the query service is not configured, when no HSMS session is selected, when the report outcome is GemFormattedProgramDryRunOutcome.Reject, or when a different execution has not reached a terminal state; PdcommStatus.LimitExceeded when the program exceeds the execution limits derived from the query options.

`StepExecution`

Method

Requests the next command of a running execution as a step action.

public GemFormattedProgramExecutionAction StepExecution(GemFormattedProgramExecutionToken token)

Equipment only. While a step is pending, calling again returns the same pending action. Report its result with GemFormattedPrograms.SubmitActionResult.

Parameters

Name	Description
`token`	The execution token from `GemFormattedProgramExecutionStart.Token`.

Returns

The step action, which carries the command index, code and parameters. The caller owns it and must dispose it.

Notes

Throws ArgumentNullException: token is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.StaleToken when token does not identify the current execution; PdcommStatus.InvalidState on a host, when the query service is not configured, when the execution is not GemFormattedProgramExecutionState.Running, or when every command has been applied.

`SubmitActionResult`

Method

Reports the application's result for the pending start, step or cancel action.

public void SubmitActionResult(GemFormattedProgramExecutionActionToken token, GemFormattedProgramActionResult result)

Equipment only. Submitting the same result again for an action that is already resolved succeeds without a change.

Parameters

Name	Description
`token`	The action token from `GemFormattedPrograms.GetActionToken` for the pending action.
`result`	The result; it must suit the action kind, as described for `GemFormattedProgramActionResult`.

Notes

Throws ArgumentNullException: token is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidArgument when result is not a defined value or does not suit the action kind; PdcommStatus.StaleToken when token does not identify the pending action of the current execution, or when the action was already resolved with a different result; PdcommStatus.InvalidState on a host or when the query service is not configured.

`SubmitCapabilityQuery`

Method

Sends an S7F21 (Process Capabilities Request) to the equipment.

public HsmsToken SubmitCapabilityQuery()

Host only. The S7F22 reply arrives as a GemResult with GemOutcome.FormattedCapabilityResult; read it with GemResult.GetFormattedProgramCapabilityInfo and the related accessors.

Returns

The transport token of the accepted request.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.InvalidState on equipment, when the service is not configured or when GEM communication is not established; PdcommStatus.Backpressure when the pending request table or the transport is full; PdcommStatus.LimitExceeded when the service's pending capacity is used up.

`SubmitPreparedVerification`

Method

Sends the S7F29 (Process Program Verification Inquire) of a prepared verification report.

public HsmsToken SubmitPreparedVerification(GemResult prepared)

Equipment only. The S7F30 reply arrives as a GemResult with GemOutcome.FormattedVerificationGrantReceived. When the PPGNT grants (0), the endpoint sends the prepared S7F27 by itself and its S7F28 reply arrives with GemOutcome.FormattedVerificationNegotiationAck; any other PPGNT ends the negotiation.

Parameters

Name	Description
`prepared`	The `GemResult` returned by `GemFormattedPrograms.PrepareVerification` on this endpoint and session.

Returns

The transport token of the accepted S7F29 request.

Notes

Throws ArgumentNullException: prepared is null.
Throws ObjectDisposedException: The endpoint or prepared was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host, when GEM communication is not established or when prepared is not a negotiation result; PdcommStatus.StaleToken when prepared belongs to another endpoint or session or is a received request; PdcommStatus.Backpressure when the pending request table or the transport is full; another status such as PdcommStatus.LimitExceeded when the pending capacity is used up or the report was already submitted.

`SubmitQuery`

Method

Sends an S7F25 (Formatted Process Program Request) to the equipment.

public HsmsToken SubmitQuery(SecsItem id)

Host only. The S7F26 reply arrives as a GemResult with GemOutcome.FormattedQueryResult; GemResult.GetFormattedProgramQueryInfo tells whether the equipment returned a program or an empty reply.

Parameters

Name	Description
`id`	The process program ID (PPID) to request: a nonempty ASCII or Binary item of at most 120 bytes.

Returns

The transport token of the accepted request.

Notes

Throws ArgumentNullException: id is null.
Throws ObjectDisposedException: The endpoint or id was disposed.
Throws PdcommException: PdcommStatus.InvalidState on equipment, when the service is not configured or when GEM communication is not established; PdcommStatus.InvalidArgument when id is not an ASCII or Binary item; PdcommStatus.Backpressure when the pending request table or the transport is full; another status such as PdcommStatus.LimitExceeded when the PPID is too long or the service's pending capacity is used up.

`SubmitTransfer`

Method

Sends an S7F23 (Formatted Process Program Send) to the equipment.

public HsmsToken SubmitTransfer(GemFormattedProgramPayload payload)

Host only. The inputs are copied before the call returns. The S7F24 reply arrives as a GemResult with GemOutcome.FormattedTransferAck; the ACKC7 is in GemFormattedProgramTransferInfo.Acknowledgement from GemResult.GetFormattedProgramTransferInfo.

Parameters

Name	Description
`payload`	The program to send; `GemFormattedProgramPayload` describes the rules for each field.

Returns

The transport token of the accepted request.

Notes

Throws ArgumentNullException: payload, its ID, model, software revision or command list, or a command, its code, its parameter list or one of its parameters is null.
Throws ArgumentException: A string contains an invalid UTF-16 surrogate sequence.
Throws ObjectDisposedException: The endpoint or an item of payload was disposed.
Throws PdcommException: PdcommStatus.InvalidState on equipment, when the service is not configured or when GEM communication is not established; PdcommStatus.InvalidArgument when a field of payload is invalid; PdcommStatus.Backpressure when the pending request table or the transport is full; PdcommStatus.LimitExceeded when the program exceeds GemFormattedProgramTransferOptions or an item or the message exceeds the item limits.

`SubmitVerificationReport`

Method

Sends an S7F27 (Process Program Verification Send) report to the host.

public HsmsToken SubmitVerificationReport(SecsItem id, IReadOnlyList<GemFormattedProgramIssue> issues)

Equipment only. The inputs are copied before S7F27 is queued. The S7F28 reply arrives as a GemResult with GemOutcome.FormattedVerificationReportAck.

Parameters

Name	Description
`id`	The process program ID (PPID): a nonempty ASCII or Binary item of at most 120 bytes.
`issues`	The verification issues in wire order; an empty list sends an empty issue list.

Returns

The transport token of the accepted request.

Notes

Throws ArgumentNullException: id or issues, or an issue or its text, is null.
Throws ArgumentException: An issue text contains an invalid UTF-16 surrogate sequence.
Throws ObjectDisposedException: The endpoint or id was disposed.
Throws PdcommException: PdcommStatus.InvalidState on a host, when the service is not configured or when GEM communication is not established; PdcommStatus.InvalidArgument when the PPID or an issue is invalid or the issues exceed GemFormattedProgramOptions; PdcommStatus.Backpressure when the pending request table or the transport is full; PdcommStatus.LimitExceeded when the service's pending capacity is used up or the message exceeds the item limits.

`SubmitVerificationRequest`

Method

Sends an S7F31 (Verification Request Send) to the equipment.

public HsmsToken SubmitVerificationRequest(GemFormattedProgramPayload payload)

Host only. The inputs are copied before the call returns. The S7F32 reply arrives as a GemResult with GemOutcome.FormattedVerificationRequestAck; the ACKC7 is in GemFormattedProgramVerificationRequestInfo.Acknowledgement.

Parameters

Name	Description
`payload`	The program to verify; `GemFormattedProgramPayload` describes the rules for each field.

Returns

The transport token of the accepted request.

Notes

Throws ArgumentNullException: payload, its ID, model, software revision or command list, or a command, its code, its parameter list or one of its parameters is null.
Throws ArgumentException: A string contains an invalid UTF-16 surrogate sequence.
Throws ObjectDisposedException: The endpoint or an item of payload was disposed.
Throws PdcommException: PdcommStatus.InvalidState on equipment, when the service is not configured or when GEM communication is not established; PdcommStatus.InvalidArgument when a field of payload is invalid; PdcommStatus.Backpressure when the pending request table or the transport is full; PdcommStatus.LimitExceeded when the program exceeds GemFormattedProgramVerificationRequestOptions or an item or the message exceeds the item limits.

`ValidateSelection`

Method

Checks that a selection is still valid for execution and returns a snapshot of the selected program.

public GemFormattedProgramSelectionSnapshot ValidateSelection(GemFormattedProgramSelectionToken token)

Equipment only. When the call fails with PdcommStatus.StaleToken, the exception's Exception.Data holds the native stale reason as a UInt32 under the key "StaleReason": 1 the store entry was deleted, 2 the entry changed, 3 the connection generation changed, 4 the connection was lost, 5 the selection was cleared, or 6 token does not match the current selection.

Parameters

Name	Description
`token`	The token of the current selection, from `GemFormattedPrograms.SelectProgram`.

Returns

A ready selection snapshot. The caller owns it and must dispose it.

Notes

Throws ArgumentNullException: token is null.
Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: PdcommStatus.StaleToken when the selection was cleared, token does not match it, or the selection became stale; PdcommStatus.InvalidState on a host or when the query service is not configured.