PDComm.GemResult

Class

Represents the outcome of processing one transport event with the GEM layer.

public sealed class GemResult : IDisposable

Obtain a result from GemEndpoint.HandleEvent or from GemEvent.Result, and start with GemResult.GetInfo. The result owns native memory with a snapshot of its data; dispose it when done. It stays valid after the originating HsmsEvent and endpoint are disposed.

Every SecsItem returned by a getter is a new, independent object that the caller owns and must dispose; it stays valid after the result is disposed. Calls on one result are serialized by an internal lock.

Members

Dispose

Method

Releases the native result.

public void Dispose()

Items and values already returned from the result stay valid.

GetAlarmAt

Method

Gets one alarm entry of the alarm report or alarm list carried by the result.

public GemAlarmValue GetAlarmAt(nuint index)

The entry contains only the wire fields. The equipment's enabled state and event mappings are not part of the message.

Parameters

Name	Description
index	The zero-based entry index. A report has one entry; a list has GemAlarmResultInfo.Count entries in wire order.

Returns

The alarm ID, category, active state and text from the wire.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.OutOfRange when index is out of range, PdcommStatus.InvalidState when the result is not an alarm report or list, or another native failure status.
• Throws InvalidOperationException: The native text size changed between the size query and the copy.

GetAlarmInfo

Method

Gets the summary of the alarm report or alarm list carried by the result.

public GemAlarmResultInfo GetAlarmInfo()

The result stays readable after the endpoint that produced it is disposed.

Returns

The entry count, whether the result is a report, its W-bit and its acknowledgement state.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not a validated host-side alarm report (S5F1) or alarm list reply (S5F6 or S5F8), or another native failure status.

GetBody

Method

Gets a copy of the SECS-II body captured with the result.

public SecsItem? GetBody()

Returns

A new item that the caller owns and must dispose, or null when the result has no body, for example for a header-only message, a failure, or a body that could not be decoded.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: The native copy failed, for example with PdcommStatus.AllocationFailed.

GetCommandInfo

Method

Gets the summary of the remote command request or reply carried by the result.

public GemCommandResultInfo GetCommandInfo()

The HCACK actually sent by GemEquipment.RespondCommand is reported in GemResultInfo.Acknowledgement. The result stays readable after the endpoint that produced it is disposed.

Returns

The parameter and issue counts, the validation outcome on receipt, the completion event and the reply state.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not a validated S2F41 request or S2F42 reply, or another native failure status.

GetCommandIssue

Method

Gets one parameter acknowledgement (CPNAME and CPACK) of a remote command result.

public GemCommandError GetCommandIssue(nuint index)

For a request, the issues are those found by validation on receipt; numeric names are returned as I8 or U8 items and may differ from the wire format. For a host-side reply, the issues are the received CPACK entries with their names in wire format.

Parameters

Name	Description
index	The zero-based issue index. Order and duplicates are preserved.

Returns

The parameter name and CPACK code. The caller must dispose the returned error.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.OutOfRange when index is not less than GemCommandResultInfo.IssueCount, PdcommStatus.InvalidState when the result is not a remote command result, or another native failure status.

GetCommandName

Method

Gets the remote command name (RCMD) of a received S2F41 request.

public SecsItem GetCommandName()

Returns

An independent copy of the name item in its wire format. The caller must dispose it.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not an S2F41 request (for example a host-side reply), or another native failure status.

GetCommandParameter

Method

Gets one parameter of a received S2F41 request.

public GemCommandArgument GetCommandParameter(nuint index)

Parameters

Name	Description
index	The zero-based parameter index in wire order. Duplicates are preserved.

Returns

Independent copies of the parameter name (CPNAME) and value (CPVAL). The caller must dispose the returned argument.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.OutOfRange when index is not less than GemCommandResultInfo.ParameterCount, PdcommStatus.InvalidState when the result is not an S2F41 request, or another native failure status.

GetConstantChange

Method

Gets one ECID/ECV pair of a received S2F15 request.

public GemConstantChangeEntry GetConstantChange(nuint index)

Parameters

Name	Description
index	The zero-based pair index, less than GemConstantChangeInfo.ChangeCount.

Returns

A new entry that the caller owns and must dispose, with the proposed ID and value in wire format and order, and the value of the constant at receipt, or null for an unknown ID.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not a received S2F15 request; PdcommStatus.OutOfRange when index is too large.

GetConstantChangeInfo

Method

Gets the processing state of a received S2F15 request or S2F16 reply.

public GemConstantChangeInfo GetConstantChangeInfo()

Returns

The receipt validation and reply state for an S2F15 request (GemOutcome.ConstantChangesReceived), or an all-zero value with GemConstantChangeInfo.IsRequest set to false for an S2F16 reply (GemOutcome.ConstantChangeAck).

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is neither an S2F15 request nor an S2F16 reply.

GetConstantMetadata

Method

Gets one field of an entry of a received S2F30 (Equipment Constant Namelist) reply.

public SecsItem GetConstantMetadata(nuint index, GemConstantField field)

Parameters

Name	Description
index	The zero-based entry index, less than GemResultInfo.EntryCount.
field	The field, from GemConstantField.Id to GemConstantField.Units.

Returns

A new item that the caller owns and must dispose, exactly as received. An empty ASCII item may mean an absent value or an unknown ID; the reply does not say which.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidArgument when field is GemConstantField.Current or undefined; PdcommStatus.InvalidState when the result is not a constant metadata reply (GemOutcome.ConstantMetadataReceived); PdcommStatus.OutOfRange when index is too large.

GetConstantValue

Method

Gets one entry of a received S2F14 (Equipment Constant Data) reply.

public GemConstantValue GetConstantValue(nuint index)

Parameters

Name	Description
index	The zero-based entry index, less than GemResultInfo.EntryCount.

Returns

A new entry that the caller owns and must dispose. Its ID is the corresponding ID of the original request, or null when all constants were requested.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not a constant values reply (GemOutcome.ConstantValuesReceived); PdcommStatus.OutOfRange when index is too large.

GetDirectory

Method

Gets one field of a row in a received namelist reply (S1F22 or S1F24) as a new item.

public SecsItem GetDirectory(nuint index, GemDirectoryField field)

The returned item stays valid after the result and the endpoint are disposed.

Parameters

Name	Description
index	The zero-based row position, less than GemResultInfo.EntryCount.
field	GemDirectoryField.Name or GemDirectoryField.Units (ASCII items) for a data variable row; GemDirectoryField.Name (ASCII) or GemDirectoryField.VariableIds (U4 array) for an event row.

Returns

A new item that the caller owns and must dispose.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: The call failed: PdcommStatus.InvalidArgument when field is not valid for the row kind, PdcommStatus.InvalidState when the result is not a validated directory response, PdcommStatus.OutOfRange when index is out of range, or PdcommStatus.InvalidData when the row is malformed.
• Throws InvalidOperationException: The native library returned no item.

GetDirectoryAt

Method

Gets the ID and variable count of one row in a received namelist reply (S1F22 or S1F24).

public GemDirectoryEntryInfo GetDirectoryAt(nuint index)

Parameters

Name	Description
index	The zero-based row position, less than GemResultInfo.EntryCount.

Returns

The VID of a data variable row or the CEID of an event row, and the number of variable IDs (0 for data variable rows).

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: The native call failed: PdcommStatus.InvalidState when the result is not a validated directory response, PdcommStatus.OutOfRange when index is out of range, or PdcommStatus.InvalidData when the row is malformed.

GetEnhancedCommandAcknowledgements

Method

Gets the parameter acknowledgement list of an enhanced remote command result.

public SecsItem GetEnhancedCommandAcknowledgements()

Names from local validation may use a normalized numeric format.

Returns

An independent copy of the outer List item: empty for an accepted request, the validation errors frozen on receipt for a rejected request, or the exact received second field of S2F50 for a host-side reply. The caller must dispose it.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not an enhanced remote command result, or another native failure status.

GetEnhancedCommandInfo

Method

Gets the summary of the enhanced remote command request or reply carried by the result.

public GemEnhancedCommandResultInfo GetEnhancedCommandInfo()

The HCACK actually sent by GemEquipment.RespondEnhancedCommand is reported in GemResultInfo.Acknowledgement. The result stays readable after the endpoint that produced it is disposed.

Returns

The parameter and issue counts, the data ID, the validation outcome on receipt, the completion event and the reply state.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not an S2F49 request or S2F50 reply, or another native failure status.

GetEnhancedCommandName

Method

Gets the remote command name (RCMD) of a received S2F49 request.

public SecsItem GetEnhancedCommandName()

Returns

An independent copy of the name item in its wire format. The caller must dispose it.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not an S2F49 request (for example a host-side reply), or another native failure status.

GetEnhancedCommandObject

Method

Gets the object specifier (OBJSPEC) of a received S2F49 request.

public SecsItem GetEnhancedCommandObject()

Returns

An independent copy of the ASCII object item. The caller must dispose it.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not an S2F49 request (for example a host-side reply), or another native failure status.

GetEnhancedCommandParameter

Method

Gets one parameter of a received S2F49 request.

public GemCommandArgument GetEnhancedCommandParameter(nuint index)

Parameters

Name	Description
index	The zero-based parameter index in wire order.

Returns

Independent copies of the parameter name (CPNAME) and value (CEPVAL). The caller must dispose the returned argument.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.OutOfRange when index is not less than GemEnhancedCommandResultInfo.ParameterCount, PdcommStatus.InvalidState when the result is not an S2F49 request, or another native failure status.

GetEventInfo

Method

Gets the header fields of an event report (S6F11) received by a host.

public GemEventInfo GetEventInfo()

GemEventInfo.Acknowledged becomes true after GemHost.AcknowledgeEvent succeeds for this result.

Returns

The DATAID, CEID, report count and acknowledgement state.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not an event report received by a host (GemOutcome.EventReceived).

GetEventReport

Method

Gets the report ID and value count of one report in a received event report (S6F11).

public GemEventReport GetEventReport(nuint reportIndex)

Parameters

Name	Description
reportIndex	The zero-based report position, less than GemEventInfo.ReportCount.

Returns

The report ID (RPTID) and the number of values in the report.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: The native call failed: PdcommStatus.InvalidState when the result is not a received event report, PdcommStatus.OutOfRange when reportIndex is out of range, or PdcommStatus.InvalidData when the report entry is malformed.

GetEventValue

Method

Gets a copy of one variable value (V) from a report in a received event report (S6F11).

public SecsItem GetEventValue(nuint reportIndex, nuint valueIndex)

Event values carry no VIDs. Map each position to a VID with the report definition that the host sent in S2F33. The returned item is independent of the result and of the endpoint and stays valid after both are disposed.

Parameters

Name	Description
reportIndex	The zero-based report position, less than GemEventInfo.ReportCount.
valueIndex	The zero-based value position, less than GemEventReport.ValueCount.

Returns

A new item that the caller owns and must dispose.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: The native call failed: PdcommStatus.InvalidState when the result is not a received event report, or PdcommStatus.OutOfRange when an index is out of range.

GetFormattedProgramCapabilityCommandCode

Method

Gets the command code (CCODE) of one command of the process capabilities data.

public string GetFormattedProgramCapabilityCommandCode(nuint index)

The data is available on a host S7F22 result, and on an equipment S7F21 result after GemFormattedPrograms.RespondCapabilityQuery answered it.

Parameters

Name	Description
index	The zero-based index of the command, less than GemFormattedProgramCapabilityInfo.CommandCount.

Returns

The ASCII command code.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramCapabilityCommandInfo

Method

Gets the description of one command of the process capabilities data.

public GemFormattedProgramCapabilityCommandInfo GetFormattedProgramCapabilityCommandInfo(nuint index)

The data is available on a host S7F22 result, and on an equipment S7F21 result after GemFormattedPrograms.RespondCapabilityQuery answered it.

Parameters

Name	Description
index	The zero-based index of the command, less than GemFormattedProgramCapabilityInfo.CommandCount.

Returns

The RQCMD, BLKDEF and ACDS values and the dependency and parameter counts of the command.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramCapabilityCommandName

Method

Gets the command name (CNAME) of one command of the process capabilities data.

public string GetFormattedProgramCapabilityCommandName(nuint index)

The data is available on a host S7F22 result, and on an equipment S7F21 result after GemFormattedPrograms.RespondCapabilityQuery answered it.

Parameters

Name	Description
index	The zero-based index of the command, less than GemFormattedProgramCapabilityInfo.CommandCount.

Returns

The ASCII command name, at most 16 characters.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramCapabilityDependencyAt

Method

Gets one value of a dependency list of one command of the process capabilities data.

public ushort GetFormattedProgramCapabilityDependencyAt(nuint command_index, uint field, nuint dependency_index)

The data is available on a host S7F22 result, and on an equipment S7F21 result after GemFormattedPrograms.RespondCapabilityQuery answered it.

Parameters

Name	Description
command_index	The zero-based index of the command, less than GemFormattedProgramCapabilityInfo.CommandCount.
field	The dependency list, a GemFormattedProgramDependency value: 1 BCDS, 2 IBCDS, 3 NBCDS, 4 IACDS or 5 NACDS. Other values fail with PdcommStatus.InvalidArgument. The single ACDS value is GemFormattedProgramCapabilityCommandInfo.AfterDependency.
dependency_index	The zero-based index of the value, less than the matching count in GemFormattedProgramCapabilityCommandInfo.

Returns

The U2 dependency value.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramCapabilityInfo

Method

Gets the S7F21/S7F22 process capabilities information of this result.

public GemFormattedProgramCapabilityInfo GetFormattedProgramCapabilityInfo()

Returns

The transaction state and the CMDMAX, BYTMAX and command count of the capability data.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramCapabilityModel

Method

Gets the equipment model type (MDLN) of the process capabilities data.

public string GetFormattedProgramCapabilityModel()

The data is available on a host S7F22 result, and on an equipment S7F21 result after GemFormattedPrograms.RespondCapabilityQuery answered it.

Returns

The equipment model type (MDLN) text.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramCapabilityParameter

Method

Gets one parameter description of one command of the process capabilities data.

public SecsItem GetFormattedProgramCapabilityParameter(nuint command_index, nuint parameter_index)

The data is available on a host S7F22 result, and on an equipment S7F21 result after GemFormattedPrograms.RespondCapabilityQuery answered it.

Parameters

Name	Description
command_index	The zero-based index of the command, less than GemFormattedProgramCapabilityInfo.CommandCount.
parameter_index	The zero-based index of the parameter within the command.

Returns

A new list SecsItem of 4, 5 or 9 items that describes the parameter. The caller owns the returned item and must dispose it.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramCapabilitySoftwareRevision

Method

Gets the software revision (SOFTREV) of the process capabilities data.

public string GetFormattedProgramCapabilitySoftwareRevision()

The data is available on a host S7F22 result, and on an equipment S7F21 result after GemFormattedPrograms.RespondCapabilityQuery answered it.

Returns

The software revision (SOFTREV) text.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramId

Method

Gets the process program ID (PPID) of the S7F27 verification report.

public SecsItem GetFormattedProgramId()

The report is available on a host result for a received S7F27, and on the equipment's verification negotiation results, which carry the prepared S7F27 report.

Returns

A new ASCII or binary SecsItem holding the PPID. The caller owns the returned item and must dispose it.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramInfo

Method

Gets the S7F27/S7F28 process program verification information of this result.

public GemFormattedProgramInfo GetFormattedProgramInfo()

Returns

The transaction state and the PPID format and issue count of the received report.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramIssueAt

Method

Gets one issue of the S7F27 verification report.

public GemFormattedProgramIssue GetFormattedProgramIssueAt(nuint index)

The report is available on a host result for a received S7F27, and on the equipment's verification negotiation results, which carry the prepared S7F27 report. A result without a report fails with PdcommStatus.OutOfRange rather than PdcommStatus.InvalidState.

Parameters

Name	Description
index	The zero-based index of the issue, less than GemFormattedProgramInfo.IssueCount.

Returns

The issue code, its sequence number (SEQNUM) and its text (ERRW7).

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramQueryCommandCode

Method

Gets the command code (CCODE) of one command of the returned formatted process program.

public SecsItem GetFormattedProgramQueryCommandCode(nuint index)

The program is available when GemFormattedProgramQueryInfo.Present is 1: on a host S7F26 result that carries the program, or on an equipment S7F25 result after the equipment answered it with a stored program.

Parameters

Name	Description
index	The zero-based index of the command, less than GemFormattedProgramQueryInfo.CommandCount.

Returns

A new SecsItem holding the ASCII or unsigned integer command code (CCODE). The caller owns the returned item and must dispose it.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramQueryCommandInfo

Method

Gets the parameter count and the command code format of one command of the returned formatted process program.

public GemFormattedProgramCommandInfo GetFormattedProgramQueryCommandInfo(nuint index)

The program is available when GemFormattedProgramQueryInfo.Present is 1: on a host S7F26 result that carries the program, or on an equipment S7F25 result after the equipment answered it with a stored program.

Parameters

Name	Description
index	The zero-based index of the command, less than GemFormattedProgramQueryInfo.CommandCount.

Returns

The parameter count of the command and the SECS-II format of its command code (CCODE).

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramQueryId

Method

Gets the process program ID (PPID) that the S7F25 requested.

public SecsItem GetFormattedProgramQueryId()

Every query result carries the requested PPID, whether or not the program is present.

Returns

A new ASCII or binary SecsItem holding the PPID. The caller owns the returned item and must dispose it.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramQueryInfo

Method

Gets the S7F25/S7F26 formatted process program request information of this result.

public GemFormattedProgramQueryInfo GetFormattedProgramQueryInfo()

Returns

The transaction state, the format of the requested PPID and whether the program is present.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramQueryModel

Method

Gets the equipment model type (MDLN) of the returned formatted process program.

public string GetFormattedProgramQueryModel()

The program is available when GemFormattedProgramQueryInfo.Present is 1: on a host S7F26 result that carries the program, or on an equipment S7F25 result after the equipment answered it with a stored program.

Returns

The equipment model type (MDLN) text.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramQueryParameter

Method

Gets one parameter (PPARM) of one command of the returned formatted process program.

public SecsItem GetFormattedProgramQueryParameter(nuint command_index, nuint parameter_index)

The program is available when GemFormattedProgramQueryInfo.Present is 1: on a host S7F26 result that carries the program, or on an equipment S7F25 result after the equipment answered it with a stored program.

Parameters

Name	Description
command_index	The zero-based index of the command, less than GemFormattedProgramQueryInfo.CommandCount.
parameter_index	The zero-based index of the parameter within the command.

Returns

A new SecsItem holding the parameter (PPARM). The caller owns the returned item and must dispose it.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramQuerySoftwareRevision

Method

Gets the software revision (SOFTREV) of the returned formatted process program.

public string GetFormattedProgramQuerySoftwareRevision()

The program is available when GemFormattedProgramQueryInfo.Present is 1: on a host S7F26 result that carries the program, or on an equipment S7F25 result after the equipment answered it with a stored program.

Returns

The software revision (SOFTREV) text.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramTransferCommandCode

Method

Gets the command code (CCODE) of one command of the received formatted process program.

public SecsItem GetFormattedProgramTransferCommandCode(nuint index)

Only an equipment result for a received S7F23 carries the program; an S7F24 result does not.

Parameters

Name	Description
index	The zero-based index of the command, less than GemFormattedProgramTransferInfo.CommandCount.

Returns

A new SecsItem holding the ASCII or unsigned integer command code (CCODE). The caller owns the returned item and must dispose it.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramTransferCommandInfo

Method

Gets the parameter count and the command code format of one command of the received formatted process program.

public GemFormattedProgramCommandInfo GetFormattedProgramTransferCommandInfo(nuint index)

Only an equipment result for a received S7F23 carries the program; an S7F24 result does not.

Parameters

Name	Description
index	The zero-based index of the command, less than GemFormattedProgramTransferInfo.CommandCount.

Returns

The parameter count of the command and the SECS-II format of its command code (CCODE).

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramTransferId

Method

Gets the process program ID (PPID) of the received formatted process program.

public SecsItem GetFormattedProgramTransferId()

Only an equipment result for a received S7F23 carries the program; an S7F24 result does not.

Returns

A new ASCII or binary SecsItem holding the PPID. The caller owns the returned item and must dispose it.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramTransferInfo

Method

Gets the S7F23/S7F24 formatted process program send information of this result.

public GemFormattedProgramTransferInfo GetFormattedProgramTransferInfo()

Returns

The transaction state, the ACKC7 code and the PPID format and command count of the received program.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramTransferModel

Method

Gets the equipment model type (MDLN) of the received formatted process program.

public string GetFormattedProgramTransferModel()

Only an equipment result for a received S7F23 carries the program; an S7F24 result does not.

Returns

The equipment model type (MDLN) text.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramTransferParameter

Method

Gets one parameter (PPARM) of one command of the received formatted process program.

public SecsItem GetFormattedProgramTransferParameter(nuint command_index, nuint parameter_index)

Only an equipment result for a received S7F23 carries the program; an S7F24 result does not.

Parameters

Name	Description
command_index	The zero-based index of the command, less than GemFormattedProgramTransferInfo.CommandCount.
parameter_index	The zero-based index of the parameter within the command.

Returns

A new SecsItem holding the parameter (PPARM). The caller owns the returned item and must dispose it.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramTransferSoftwareRevision

Method

Gets the software revision (SOFTREV) of the received formatted process program.

public string GetFormattedProgramTransferSoftwareRevision()

Only an equipment result for a received S7F23 carries the program; an S7F24 result does not.

Returns

The software revision (SOFTREV) text.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramVerificationNegotiationInfo

Method

Gets the S7F29/S7F30 process program verification negotiation information of this result.

public GemFormattedProgramVerificationNegotiationInfo GetFormattedProgramVerificationNegotiationInfo()

Read the PPID and the issues of the prepared S7F27 report with GemResult.GetFormattedProgramId and GemResult.GetFormattedProgramIssueAt.

Returns

The negotiation state, its terminal outcomes, the PPGNT code and the correlation value.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramVerificationRequestCommandCode

Method

Gets the command code (CCODE) of one command of the received formatted process program.

public SecsItem GetFormattedProgramVerificationRequestCommandCode(nuint index)

Only an equipment result for a received S7F31 carries the program; an S7F32 result does not.

Parameters

Name	Description
index	The zero-based index of the command, less than GemFormattedProgramVerificationRequestInfo.CommandCount.

Returns

A new SecsItem holding the ASCII or unsigned integer command code (CCODE). The caller owns the returned item and must dispose it.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramVerificationRequestCommandInfo

Method

Gets the parameter count and the command code format of one command of the received formatted process program.

public GemFormattedProgramCommandInfo GetFormattedProgramVerificationRequestCommandInfo(nuint index)

Only an equipment result for a received S7F31 carries the program; an S7F32 result does not.

Parameters

Name	Description
index	The zero-based index of the command, less than GemFormattedProgramVerificationRequestInfo.CommandCount.

Returns

The parameter count of the command and the SECS-II format of its command code (CCODE).

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramVerificationRequestId

Method

Gets the process program ID (PPID) of the received formatted process program.

public SecsItem GetFormattedProgramVerificationRequestId()

Only an equipment result for a received S7F31 carries the program; an S7F32 result does not.

Returns

A new ASCII or binary SecsItem holding the PPID. The caller owns the returned item and must dispose it.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramVerificationRequestInfo

Method

Gets the S7F31/S7F32 verification request information of this result.

public GemFormattedProgramVerificationRequestInfo GetFormattedProgramVerificationRequestInfo()

Returns

The transaction state, the ACKC7 code and the PPID format and command count of the received program.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramVerificationRequestModel

Method

Gets the equipment model type (MDLN) of the received formatted process program.

public string GetFormattedProgramVerificationRequestModel()

Only an equipment result for a received S7F31 carries the program; an S7F32 result does not.

Returns

The equipment model type (MDLN) text.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetFormattedProgramVerificationRequestParameter

Method

Gets one parameter (PPARM) of one command of the received formatted process program.

public SecsItem GetFormattedProgramVerificationRequestParameter(nuint command_index, nuint parameter_index)

Only an equipment result for a received S7F31 carries the program; an S7F32 result does not.

Parameters

Name	Description
command_index	The zero-based index of the command, less than GemFormattedProgramVerificationRequestInfo.CommandCount.
parameter_index	The zero-based index of the parameter within the command.

Returns

A new SecsItem holding the parameter (PPARM). The caller owns the returned item and must dispose it.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data, or with PdcommStatus.OutOfRange when an index is past the end or the indexed entry is absent.

GetFormattedProgramVerificationRequestSoftwareRevision

Method

Gets the software revision (SOFTREV) of the received formatted process program.

public string GetFormattedProgramVerificationRequestSoftwareRevision()

Only an equipment result for a received S7F31 carries the program; an S7F32 result does not.

Returns

The software revision (SOFTREV) text.

Notes

• Throws NotSupportedException: The loaded native library does not export the formatted process program result accessors.
• Throws ObjectDisposedException: The result has been disposed.
• Throws PdcommException: The native accessor failed, for example with PdcommStatus.InvalidState when the result does not carry this formatted process program data.

GetInfo

Method

Gets the summary of the result: kind, outcome, transaction, codes, token and GEM state.

public GemResultInfo GetInfo()

Returns

The result summary.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: The native call failed.

GetProgramBody

Method

Gets a copy of the PPBODY of a received S7F3 request or S7F6 reply.

public SecsItem? GetProgramBody()

Returns

A new item that the caller owns and must dispose, or null when an S7F6 reply reports an unknown program.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not an S7F3 request or S7F6 reply.

GetProgramId

Method

Gets a copy of a PPID of a process program result.

public SecsItem GetProgramId(nuint index)

Parameters

Name	Description
index	The zero-based PPID index, less than GemProgramInfo.IdCount.

Returns

A new item that the caller owns and must dispose.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws InvalidOperationException: The native library returned no item.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not a process program result; PdcommStatus.OutOfRange when index is too large.

GetProgramInfo

Method

Gets the state of a received stream 7 process program request or reply.

public GemProgramInfo GetProgramInfo()

The values reflect the result at the time of the call; they change after GemEquipment.RespondProgram or GemEquipment.ConfirmProgramReply.

Returns

The transaction, PPID count, acknowledgement, and local installation and reply state.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not a process program request or reply.

GetProgramItem

Method

Gets a copy of a PPID or the PPBODY of a process program result.

public SecsItem? GetProgramItem(GemProgramField field, nuint index = 0)

PPIDs are available for S7F1, S7F3, S7F5 and S7F17 requests and for S7F6 and S7F20 replies. The body is available for S7F3 requests and S7F6 replies.

Parameters

Name	Description
field	The field to read.
index	For GemProgramField.Id, the zero-based PPID index, less than GemProgramInfo.IdCount; for GemProgramField.Body, 0.

Returns

A new item that the caller owns and must dispose, or null for the body of an S7F6 reply that reports an unknown program. A stored empty body is returned as an empty item.

Notes

• Throws ArgumentOutOfRangeException: field is not a defined value.
• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not a process program result or has no such field; PdcommStatus.OutOfRange when index is too large.

GetQueryInfo

Method

Gets the report query details of a received query or a query reply.

public GemQueryInfo GetQueryInfo()

Returns

The query details. For a query received by equipment, only the kind, ID, GemQueryInfo.IsRequest and GemQueryInfo.Responded are set.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not a received query or a valid query reply, for example a failed, malformed, aborted or unrelated result.

GetQueryReport

Method

Gets one report of an S6F16 event report reply.

public GemQueryReportInfo GetQueryReport(nuint reportIndex)

Parameters

Name	Description
reportIndex	The zero-based report index, less than GemQueryInfo.ReportCount.

Returns

The report ID (RPTID) and its value count, in the order the reply carried them.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState unless the result is an S6F16 reply; PdcommStatus.OutOfRange for an invalid index.

GetQueryValue

Method

Gets one value of a report query reply.

public GemQueryValue GetQueryValue(nuint reportIndex, nuint valueIndex)

Parameters

Name	Description
reportIndex	The zero-based report index for an S6F16 reply; must be 0 for S6F20 and S6F22 replies.
valueIndex	The zero-based value index within the report or reply.

Returns

A new value that the caller owns and must dispose. Only S6F22 values carry a variable ID (VID); duplicate VIDs keep their wire order.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState unless the result is a query reply; PdcommStatus.OutOfRange for an invalid index.

GetSpoolError

Method

Gets one stream error of an S2F44 received by the host.

public GemSpoolResultError GetSpoolError(nuint index)

An S2F44 with RSPACK 0 has no errors.

Parameters

Name	Description
index	The zero-based position, less than GemSpoolInfo.ErrorCount.

Returns

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

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not an S2F44 received by the host; PdcommStatus.OutOfRange when index is too large; PdcommStatus.InvalidData when the body cannot be parsed; or another native failure such as PdcommStatus.AllocationFailed.
• Throws InvalidOperationException: The native library returned no function list.

GetSpoolInfo

Method

Gets the spooling details of a spooling request, reply or delivery result.

public GemSpoolInfo GetSpoolInfo()

Spooling results have the outcome GemOutcome.SpoolReceived, GemOutcome.SpoolConfigurationAck, GemOutcome.SpoolConfigurationData, GemOutcome.SpoolControlAck, GemOutcome.SpoolDeliveryResponse, GemOutcome.SpoolDeliveryWritten or GemOutcome.SpoolDeliveryFailed.

Returns

The spooling details as of the last operation on this result.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not a spooling result.

GetSpoolSelection

Method

Gets one stream selection of an S2F43 received by the equipment or of an S2F60 received by the host.

public GemSpoolResultSelection GetSpoolSelection(nuint index)

Parameters

Name	Description
index	The zero-based position, less than GemSpoolInfo.SelectionCount.

Returns

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

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState when the result is not such a message; PdcommStatus.OutOfRange when index is too large; PdcommStatus.InvalidData when the body cannot be parsed; or another native failure such as PdcommStatus.AllocationFailed.
• Throws InvalidOperationException: The native library returned no function list.

GetStatusName

Method

Gets one entry of a validated S1F12 status variable name list.

public GemStatusName GetStatusName(nuint index)

Parameters

Name	Description
index	The zero-based entry index, less than GemResultInfo.EntryCount.

Returns

The status variable ID, name and units.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState unless the outcome is GemOutcome.NamesReceived; PdcommStatus.OutOfRange for an invalid index.
• Throws InvalidOperationException: The native entry size changed during the read.

GetStatusValue

Method

Gets one status variable value of a validated S1F4 reply.

public GemStatusValue GetStatusValue(nuint index)

Parameters

Name	Description
index	The zero-based entry index, less than GemResultInfo.EntryCount.

Returns

A new value that the caller owns and must dispose. For a selected request the ID matches the request order; for an all-values request GemStatusValue.Id is null.

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState unless the outcome is GemOutcome.ValuesReceived; PdcommStatus.OutOfRange for an invalid index.

TryCopyAlarmAt

Method

Copies one alarm entry of the alarm report or alarm list into a caller-supplied buffer.

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

Parameters

Name	Description
index	The zero-based entry index.
info	When this method returns, contains the alarm ID, category and active state.
text	The buffer that receives the alarm text as ASCII bytes. No terminating NUL is appended.
required	When this method returns, contains the text length in bytes.

Returns

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

Notes

• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.OutOfRange when index is out of range, PdcommStatus.InvalidState when the result is not an alarm report or list, or another native failure status.

TryCopyStatusName

Method

Copies one entry of a validated S1F12 status variable name list into caller buffers.

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

Parameters

Name	Description
index	The zero-based entry index, less than GemResultInfo.EntryCount.
id	Receives the status variable ID (SVID), or zero when the method returns false.
name	The buffer that receives the ASCII name bytes; no terminator is added.
nameRequired	Receives the name length in bytes.
units	The buffer that receives the ASCII units bytes; no terminator is added.
unitsRequired	Receives the units length in bytes.

Returns

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

Notes

• Throws ArgumentException: name and units overlap.
• Throws ObjectDisposedException: The result was disposed.
• Throws PdcommException: PdcommStatus.InvalidState unless the outcome is GemOutcome.NamesReceived; PdcommStatus.OutOfRange for an invalid index.