diff --git a/clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/LiveGatewayWrite2Tests.cs b/clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/LiveGatewayWrite2Tests.cs
index cce6fb07..5290301c 100644
--- a/clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/LiveGatewayWrite2Tests.cs
+++ b/clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/LiveGatewayWrite2Tests.cs
@@ -27,8 +27,9 @@ public sealed class LiveGatewayWrite2Tests(ITestOutputHelper output)
}
///
- /// The source timestamp after Write2 equals the timestamp sent. On a host whose clock is not
- /// UTC this fails until mxaccessgw#228 is fixed (MXAccess reads the VT_DATE as local time).
+ /// The source timestamp after Write2 equals the timestamp sent. MXAccess reads the VT_DATE
+ /// time argument as box-local time; a worker without the mxaccessgw#228 fix sends UTC clock
+ /// fields, so on a host whose clock is not UTC this fails by the host's UTC offset.
///
/// A task that represents the asynchronous operation.
[LiveGatewayWriteFact(requireTimestampOptIn: true)]
diff --git a/docs/GatewayTesting.md b/docs/GatewayTesting.md
index d5e055d6..efa2e194 100644
--- a/docs/GatewayTesting.md
+++ b/docs/GatewayTesting.md
@@ -141,7 +141,7 @@ so it is skipped unless all of these are set:
| `MXGATEWAY_LIVE_GATEWAY_ENDPOINT` | Gateway gRPC endpoint, e.g. `http://:5120`. |
| `MXGATEWAY_LIVE_GATEWAY_API_KEY_FILE` | File (mode 0600) holding the `mxgw_...` key. `MXGATEWAY_LIVE_GATEWAY_API_KEY` works too, but the file keeps the key out of the environment. The key needs `session:open`, `session:close`, `invoke:read`, `invoke:write`, `events:read`; a `Write tag globs` constraint scoped to the test item is enough. |
| `MXGATEWAY_LIVE_GATEWAY_WRITE_ITEM` | A test-only, writable **Int32** attribute. No default on purpose. On the DEV box use a Z28062 receiver attribute such as `MESReceiver_025.MoveInBatchID`, never anything on Z28061. |
-| `MXGATEWAY_LIVE_GATEWAY_ASSERT_WRITE2_TIMESTAMP` | `1` also runs `Write2_SupervisoryAdvise_KeepsSentTimestamp`. On a host whose clock is not UTC it fails until #228 is fixed. |
+| `MXGATEWAY_LIVE_GATEWAY_ASSERT_WRITE2_TIMESTAMP` | `1` also runs `Write2_SupervisoryAdvise_KeepsSentTimestamp`. On a host whose clock is not UTC it fails against a worker older than the #228 fix (the stored time is off by the host's UTC offset). |
Each test does Register, AddItem, **AdviseSupervisory**, reads the original value from the first
`OnDataChange`, `Write2`s a different value with a timestamp 30 s in the past, waits for the
@@ -158,6 +158,12 @@ dotnet test clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests --filter FullyQualif
Run on the DEV box (vd03, gateway `2b13564e`) on 2026-11-12: the value test passed, and the
timestamp test failed with exactly the #228 shift (sent `01:36:51Z`, stored `06:36:51Z`; vd03 is UTC-5).
+The worker fix for #228 converts the time argument to box-local time; rerun the timestamp test
+with `MXGATEWAY_LIVE_GATEWAY_ASSERT_WRITE2_TIMESTAMP=1` after that worker is deployed to the box.
+
+The windev smoke `WorkerLiveMxAccessSmokeTests.GatewaySession_WithLiveWorker_Write2ValueWithTimestampToAdvisedItem`
+also sends a whole-second timestamp 30 s in the past and, when the completion is `Ok`, asserts the
+stored source timestamp equals it. It logs the box's zone, because on a UTC box the check cannot fail.
## Dev-rig Probes
diff --git a/docs/WorkerConversion.md b/docs/WorkerConversion.md
index 9be993fd..343f62ea 100644
--- a/docs/WorkerConversion.md
+++ b/docs/WorkerConversion.md
@@ -119,6 +119,17 @@ default:
`GetVariantTypeName` maps CLR types to canonical `VT_*` strings (`VT_BOOL`, `VT_I4`, `VT_BSTR`, `VT_DATE`, and so on). Unmapped CLR types fall back to `CLR:` so the wire format never silently invents a `VT_*` tag it cannot justify. Array element tags are wrapped as `SAFEARRAY()` by `CreateArrayVariantType`.
+### Timestamps: the two directions differ
+
+MXAccess does not use one time convention for both directions, so the worker does not either.
+
+- **Read (OnDataChange source timestamps, `VT_DATE` values).** MXAccess hands the worker UTC clock fields. `ToTimestamp` treats an unspecified-kind `DateTime` as UTC and converts a local-kind one with `ToUniversalTime`. A plain `Write` on vd03 (UTC-5) reports the current UTC time as its source timestamp, which confirms this.
+- **Write time argument (`Write2`, `WriteSecured2`, `Write2Bulk`, `WriteSecured2Bulk`).** MXAccess reads the `VT_DATE` time argument as **box-local** time and converts it to UTC itself. A `VT_DATE` has no offset field, and the COM marshaler ignores `DateTime.Kind`, so passing the UTC clock fields stored the source timestamp shifted by the box's UTC offset. On vd03 a `Write2` sent at `01:33:00Z` was stored at `06:33:00Z` (#228). `ConvertToComTimestamp` therefore converts the `timestamp_value` instant with `TimeZoneInfo.ConvertTimeFromUtc` into the worker box's zone (`TimeZoneInfo.Local`, DST rules included) before the COM call. The command executor uses it for the time argument only; `ConvertToComValue` still renders a timestamp *value* as UTC, because whether a `Time`-typed attribute value write follows the same rule has not been proven.
+
+UTC to local is always defined: every UTC instant has exactly one local wall-clock time, and the conversion never produces a local time that does not exist (the skipped spring-forward hour). The one loss is on the MXAccess side. In the hour that repeats when DST ends, two UTC instants an hour apart share one local wall-clock time, and the offset-less `VT_DATE` cannot say which one is meant, so MXAccess may store an instant from that hour 1 h off. Run the worker box on UTC if exact timestamps across the fall-back hour matter. On a UTC box the conversion is the identity, which is why #228 could not be seen there.
+
+A time argument of another kind (a string or a number) carries no zone and is passed through unchanged; its meaning is the caller's. Consumers must send `timestamp_value` as a UTC instant, as the proto `Timestamp` already is.
+
### Why lossless preservation matters
The MXAccess engine returns values whose semantic type only fully resolves after consulting the engine's own attribute metadata. Clients that round-trip these values through the gateway (replay, parity fixtures, diagnostics) need the original `VT_*` tag, the engine-declared `MxDataType`, and any conversion diagnostic; otherwise edge cases such as decimal-to-double rounding, ulong overflow, or an unknown SAFEARRAY element type become invisible bugs. Storing both the typed projection and the raw fields in the same `MxValue`/`MxArray` lets cross-language clients recover the original observation byte-for-byte where possible and detect lossy cases where it is not.
diff --git a/gateway.md b/gateway.md
index 13e2771f..ff05894b 100644
--- a/gateway.md
+++ b/gateway.md
@@ -1366,6 +1366,13 @@ Known important parity areas from existing captures:
`AuthenticateUser` → `WriteSecured`/`WriteSecured2` path must send
`AdviseSupervisory` for the item before a user id on a plain write is
recorded; otherwise the user id is ignored.
+- MXAccess reads the `Write2`/`WriteSecured2` time argument as box-local
+ time, while it reports source timestamps as UTC. Clients send
+ `timestamp_value` as a UTC instant; the worker converts it to the box's
+ local wall-clock time (DST included) before the COM call, so the stored
+ source timestamp equals the instant sent (#228). In the hour that repeats
+ when DST ends, the offset-less `VT_DATE` cannot distinguish the two
+ instants, so MXAccess may store one 1 h off. See `docs/WorkerConversion.md`.
- Writing an array attribute replaces the whole array — it is not an
element-wise patch. To change a subset of elements the caller must send the
full array (unchanged elements included); sending only the changed elements
diff --git a/src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs b/src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs
index d5f3f588..9e732563 100644
--- a/src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs
+++ b/src/ZB.MOM.WW.MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs
@@ -319,11 +319,21 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
LogEvent(initialValue);
originalValue = initialValue.Value;
+ // A whole-second instant 30 s in the past, so a stored source timestamp
+ // can be compared exactly and cannot be confused with the write time.
+ DateTime sentTimestampUtc = DateTime.UtcNow.AddSeconds(-30);
+ sentTimestampUtc = new DateTime(
+ sentTimestampUtc.Ticks - (sentTimestampUtc.Ticks % TimeSpan.TicksPerSecond),
+ DateTimeKind.Utc);
+ output.WriteLine(
+ $"Write2 timestamp sent={sentTimestampUtc:O} box zone={TimeZoneInfo.Local.Id} offset={TimeZoneInfo.Local.GetUtcOffset(sentTimestampUtc)}");
+
MxCommandReply writeReply = await fixture.Service.Invoke(
CreateWrite2Request(
sessionId,
registerReply.Register.ServerHandle,
- addItemReply.AddItem.ItemHandle),
+ addItemReply.AddItem.ItemHandle,
+ sentTimestampUtc),
new TestServerCallContext()).ConfigureAwait(false);
LogReply("Write2", writeReply);
@@ -362,6 +372,34 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
output.WriteLine($"Write2 completion category={status.Category} detail={status.Detail}");
}
+ // #228: MXAccess reads the Write2 time argument as box-local time, so
+ // the worker must convert the UTC instant before the COM call. When the
+ // provider applied the write, the source timestamp it reports must be
+ // the instant sent. On a UTC box this cannot fail either way, so the
+ // zone is logged above. A refused write (no data change) is logged,
+ // not asserted, as before.
+ bool applied = writeComplete.Statuses.Count > 0
+ && writeComplete.Statuses.All(status => status.Category == MxStatusCategory.Ok);
+ if (applied)
+ {
+ MxEvent writtenValue = await eventWriter
+ .WaitForMessageAsync(
+ candidate => candidate.Family == MxEventFamily.OnDataChange
+ && candidate.ItemHandle == addItemReply.AddItem.ItemHandle
+ && candidate.WorkerSequence > initialValue.WorkerSequence,
+ IntegrationTestEnvironment.LiveMxAccessEventTimeout,
+ streamCancellation.Token)
+ .ConfigureAwait(false);
+ LogEvent(writtenValue);
+ DateTime? storedTimestampUtc = writtenValue.SourceTimestamp?.ToDateTime();
+ output.WriteLine($"Write2 timestamp stored={storedTimestampUtc:O}");
+ Assert.Equal(sentTimestampUtc, storedTimestampUtc);
+ }
+ else
+ {
+ output.WriteLine("Write2 timestamp not checked: the completion was not Ok, so nothing was applied.");
+ }
+
// Restore the original value with a plain Write on the same supervisory advise.
MxCommandReply restoreReply = await fixture.Service.Invoke(
CreateWriteRequest(
@@ -1666,7 +1704,8 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
private static MxCommandRequest CreateWrite2Request(
string sessionId,
int serverHandle,
- int itemHandle)
+ int itemHandle,
+ DateTime timestampUtc)
{
return new MxCommandRequest
{
@@ -1688,7 +1727,7 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
{
DataType = MxDataType.Time,
VariantType = "VT_DATE",
- TimestampValue = Timestamp.FromDateTime(DateTime.UtcNow),
+ TimestampValue = Timestamp.FromDateTime(timestampUtc),
},
},
},
diff --git a/src/ZB.MOM.WW.MxGateway.Worker.Tests/Conversion/VariantConverterTimestampTests.cs b/src/ZB.MOM.WW.MxGateway.Worker.Tests/Conversion/VariantConverterTimestampTests.cs
new file mode 100644
index 00000000..1f4aaa69
--- /dev/null
+++ b/src/ZB.MOM.WW.MxGateway.Worker.Tests/Conversion/VariantConverterTimestampTests.cs
@@ -0,0 +1,156 @@
+using System;
+using System.Globalization;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Worker.Conversion;
+using ZB.MOM.WW.MxGateway.Worker.Tests.TestSupport;
+using ProtobufTimestamp = Google.Protobuf.WellKnownTypes.Timestamp;
+
+namespace ZB.MOM.WW.MxGateway.Worker.Tests.Conversion;
+
+///
+/// Tests for the Write2/WriteSecured2 time-argument conversion (#228): MXAccess
+/// reads the VT_DATE time argument as box-local time, so the worker must
+/// hand it the UTC instant as local wall-clock time. Every zone is injected, so
+/// the results do not depend on the zone of the machine running the tests.
+///
+public sealed class VariantConverterTimestampTests
+{
+ ///
+ /// Verifies the UTC-to-local conversion across zones and DST boundaries.
+ /// The first row is the live vd03 case from #228: sent 01:33:00Z, which
+ /// MXAccess stored as 06:33:00Z before the fix.
+ ///
+ /// Zone name in .
+ /// UTC instant sent on the wire (ISO 8601).
+ /// Expected local wall-clock time handed to MXAccess.
+ [Theory]
+ // UTC-5 in November (EST): the #228 live case.
+ [InlineData("Eastern", "2026-11-13T01:33:00", "2026-11-12T20:33:00")]
+ // UTC-4 in July (EDT).
+ [InlineData("Eastern", "2026-07-15T12:00:00", "2026-07-15T08:00:00")]
+ // Spring forward (2026-03-08 07:00Z): the last EST second, then the first EDT
+ // instant. Local 02:xx does not exist that night and is never produced.
+ [InlineData("Eastern", "2026-03-08T06:59:59", "2026-03-08T01:59:59")]
+ [InlineData("Eastern", "2026-03-08T07:00:00", "2026-03-08T03:00:00")]
+ // Fall back (2026-11-01 06:00Z): the last EDT second, then the first EST instant.
+ [InlineData("Eastern", "2026-11-01T05:59:59", "2026-11-01T01:59:59")]
+ [InlineData("Eastern", "2026-11-01T06:00:00", "2026-11-01T01:00:00")]
+ // Fixed negative and positive (non-whole-hour) offsets.
+ [InlineData("UTC-5", "2026-11-13T01:33:00", "2026-11-12T20:33:00")]
+ [InlineData("UTC+05:30", "2026-11-13T01:33:00", "2026-11-13T07:03:00")]
+ [InlineData("UTC+05:30", "2026-12-31T20:00:00", "2027-01-01T01:30:00")]
+ // A UTC box: the conversion is the identity, which is why #228 cannot be seen there.
+ [InlineData("UTC", "2026-11-13T01:33:00", "2026-11-13T01:33:00")]
+ public void ConvertToComTimestamp_WithTimestampValue_ReturnsBoxLocalWallClockTime(
+ string zone,
+ string utc,
+ string expectedLocal)
+ {
+ VariantConverter converter = new(ResolveZone(zone));
+
+ object? result = converter.ConvertToComTimestamp(CreateTimestampValue(ParseUtc(utc)));
+
+ DateTime local = Assert.IsType(result);
+ Assert.Equal(ParseUnspecified(expectedLocal), DateTime.SpecifyKind(local, DateTimeKind.Unspecified));
+ }
+
+ ///
+ /// Verifies the documented fall-back ambiguity: two UTC instants an hour
+ /// apart become the same local wall-clock time, which the offset-less
+ /// VT_DATE cannot tell apart. The conversion itself is exact; the
+ /// 1 h loss is on the MXAccess side.
+ ///
+ [Fact]
+ public void ConvertToComTimestamp_InRepeatedFallBackHour_MapsTwoInstantsToOneWallClockTime()
+ {
+ VariantConverter converter = new(TestTimeZones.Eastern);
+
+ DateTime daylight = Assert.IsType(
+ converter.ConvertToComTimestamp(CreateTimestampValue(ParseUtc("2026-11-01T05:30:00"))));
+ DateTime standard = Assert.IsType(
+ converter.ConvertToComTimestamp(CreateTimestampValue(ParseUtc("2026-11-01T06:30:00"))));
+
+ Assert.Equal(ParseUnspecified("2026-11-01T01:30:00"), DateTime.SpecifyKind(daylight, DateTimeKind.Unspecified));
+ Assert.Equal(daylight.Ticks, standard.Ticks);
+ Assert.True(TestTimeZones.Eastern.IsAmbiguousTime(DateTime.SpecifyKind(daylight, DateTimeKind.Unspecified)));
+ }
+
+ /// Verifies the default converter uses the worker box's own zone.
+ [Fact]
+ public void ConvertToComTimestamp_WithDefaultConverter_UsesTimeZoneInfoLocal()
+ {
+ DateTime utc = ParseUtc("2026-11-13T01:33:00");
+
+ object? result = new VariantConverter().ConvertToComTimestamp(CreateTimestampValue(utc));
+
+ Assert.Equal(TimeZoneInfo.ConvertTimeFromUtc(utc, TimeZoneInfo.Local), Assert.IsType(result));
+ }
+
+ ///
+ /// Verifies the conversion is limited to the time argument: a timestamp
+ /// written as an attribute value is unchanged, because whether a
+ /// Time-typed value write follows the same local-time rule is unproven.
+ ///
+ [Fact]
+ public void ConvertToComValue_WithTimestampValue_StaysUtcEvenWithZoneInjected()
+ {
+ DateTime utc = ParseUtc("2026-11-13T01:33:00");
+ VariantConverter converter = new(TestTimeZones.FixedUtcMinus5);
+
+ object? result = converter.ConvertToComValue(CreateTimestampValue(utc));
+
+ Assert.Equal(utc, Assert.IsType(result));
+ }
+
+ /// Verifies a non-timestamp time argument carries no zone and passes through unchanged.
+ [Fact]
+ public void ConvertToComTimestamp_WithStringValue_PassesThroughUnchanged()
+ {
+ VariantConverter converter = new(TestTimeZones.FixedUtcMinus5);
+
+ object? result = converter.ConvertToComTimestamp(new MxValue { StringValue = "2026-11-13 01:33:00" });
+
+ Assert.Equal("2026-11-13 01:33:00", Assert.IsType(result));
+ }
+
+ /// Verifies an MXAccess-null time argument stays a CLR null.
+ [Fact]
+ public void ConvertToComTimestamp_WithNull_ReturnsNull()
+ {
+ VariantConverter converter = new(TestTimeZones.FixedUtcMinus5);
+
+ Assert.Null(converter.ConvertToComTimestamp(new MxValue { IsNull = true }));
+ }
+
+ /// Verifies an unspecified-kind input is treated as UTC, the rule the proto timestamp follows.
+ [Fact]
+ public void ToMxAccessLocalTime_WithUnspecifiedKind_TreatsInputAsUtc()
+ {
+ VariantConverter converter = new(TestTimeZones.FixedUtcMinus5);
+
+ DateTime result = converter.ToMxAccessLocalTime(ParseUnspecified("2026-11-13T01:33:00"));
+
+ Assert.Equal(ParseUnspecified("2026-11-12T20:33:00"), DateTime.SpecifyKind(result, DateTimeKind.Unspecified));
+ }
+
+ private static TimeZoneInfo ResolveZone(string zone) => zone switch
+ {
+ "Eastern" => TestTimeZones.Eastern,
+ "UTC-5" => TestTimeZones.FixedUtcMinus5,
+ "UTC+05:30" => TestTimeZones.FixedUtcPlus0530,
+ "UTC" => TimeZoneInfo.Utc,
+ _ => throw new ArgumentOutOfRangeException(nameof(zone), zone, "Unknown test zone."),
+ };
+
+ private static MxValue CreateTimestampValue(DateTime utc) => new()
+ {
+ DataType = MxDataType.Time,
+ VariantType = "VT_DATE",
+ TimestampValue = ProtobufTimestamp.FromDateTime(utc),
+ };
+
+ private static DateTime ParseUtc(string value) => DateTime.SpecifyKind(ParseUnspecified(value), DateTimeKind.Utc);
+
+ private static DateTime ParseUnspecified(string value) =>
+ DateTime.ParseExact(value, "yyyy-MM-ddTHH:mm:ss", CultureInfo.InvariantCulture, DateTimeStyles.None);
+}
diff --git a/src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessCommandExecutorTests.cs b/src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessCommandExecutorTests.cs
index 5ee79648..6221da43 100644
--- a/src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessCommandExecutorTests.cs
+++ b/src/ZB.MOM.WW.MxGateway.Worker.Tests/MxAccess/MxAccessCommandExecutorTests.cs
@@ -554,6 +554,9 @@ public sealed class MxAccessCommandExecutorTests
FakeMxAccessComObjectFactory factory = new(fakeComObject);
using StaRuntime runtime = CreateRuntime();
using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
+ // #228: MXAccess reads the time argument as box-local time. Inject a
+ // fixed UTC-5 zone so the expected shift does not depend on this machine.
+ session.MxAccessLocalTimeZone = TestTimeZones.FixedUtcMinus5;
await session.StartAsync(workerProcessId: 1234);
DateTime timestamp = new(2026, 5, 19, 12, 0, 0, DateTimeKind.Utc);
@@ -567,7 +570,7 @@ public sealed class MxAccessCommandExecutorTests
Assert.True(result.WasSuccessful);
Assert.Equal(811, result.ItemHandle);
Assert.Equal(100, fakeComObject.WriteValue);
- Assert.Equal(timestamp, fakeComObject.WriteTimestamp);
+ Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType(fakeComObject.WriteTimestamp).Ticks);
Assert.Equal(7, fakeComObject.WriteUserId);
Assert.Contains("Write2:81:811", fakeComObject.OperationNames);
}
@@ -606,6 +609,9 @@ public sealed class MxAccessCommandExecutorTests
FakeMxAccessComObjectFactory factory = new(fakeComObject);
using StaRuntime runtime = CreateRuntime();
using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
+ // #228: MXAccess reads the time argument as box-local time. Inject a
+ // fixed UTC-5 zone so the expected shift does not depend on this machine.
+ session.MxAccessLocalTimeZone = TestTimeZones.FixedUtcMinus5;
await session.StartAsync(workerProcessId: 1234);
DateTime timestamp = new(2026, 5, 19, 13, 30, 0, DateTimeKind.Utc);
@@ -620,7 +626,7 @@ public sealed class MxAccessCommandExecutorTests
Assert.Equal(33, fakeComObject.WriteCurrentUserId);
Assert.Equal(44, fakeComObject.WriteVerifierUserId);
Assert.Equal(999, fakeComObject.WriteValue);
- Assert.Equal(timestamp, fakeComObject.WriteTimestamp);
+ Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType(fakeComObject.WriteTimestamp).Ticks);
Assert.Contains("WriteSecured2:83:831", fakeComObject.OperationNames);
}
@@ -1027,6 +1033,9 @@ public sealed class MxAccessCommandExecutorTests
using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
// Same rationale as the Write forwarding test above.
session.WriteCompletionTimeout = TimeSpan.Zero;
+ // #228: MXAccess reads the time argument as box-local time. Inject a
+ // fixed UTC-5 zone so the expected shift does not depend on this machine.
+ session.MxAccessLocalTimeZone = TestTimeZones.FixedUtcMinus5;
await session.StartAsync(workerProcessId: 1234);
DateTime timestamp = new(2026, 5, 19, 12, 0, 0, DateTimeKind.Utc);
@@ -1037,7 +1046,7 @@ public sealed class MxAccessCommandExecutorTests
Assert.Equal(MxCommandKind.Write2, reply.Kind);
Assert.Equal(710, fakeComObject.WriteItemHandle);
Assert.Equal(456, fakeComObject.WriteValue);
- Assert.Equal(timestamp, fakeComObject.WriteTimestamp);
+ Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType(fakeComObject.WriteTimestamp).Ticks);
Assert.Equal(6, fakeComObject.WriteUserId);
}
@@ -1077,6 +1086,9 @@ public sealed class MxAccessCommandExecutorTests
using MxAccessStaSession session = new(runtime, factory, new NoopEventSink());
// Same rationale as the WriteSecured forwarding test above.
session.WriteCompletionTimeout = TimeSpan.Zero;
+ // #228: MXAccess reads the time argument as box-local time. Inject a
+ // fixed UTC-5 zone so the expected shift does not depend on this machine.
+ session.MxAccessLocalTimeZone = TestTimeZones.FixedUtcMinus5;
await session.StartAsync(workerProcessId: 1234);
DateTime timestamp = new(2026, 5, 19, 13, 30, 0, DateTimeKind.Utc);
@@ -1087,7 +1099,7 @@ public sealed class MxAccessCommandExecutorTests
Assert.Equal(ProtocolStatusCode.Ok, reply.ProtocolStatus.Code);
Assert.Equal(MxCommandKind.WriteSecured2, reply.Kind);
Assert.Equal(1011, fakeComObject.WriteValue);
- Assert.Equal(timestamp, fakeComObject.WriteTimestamp);
+ Assert.Equal(timestamp.AddHours(-5).Ticks, Assert.IsType(fakeComObject.WriteTimestamp).Ticks);
Assert.Equal(33, fakeComObject.WriteCurrentUserId);
Assert.Equal(44, fakeComObject.WriteVerifierUserId);
}
diff --git a/src/ZB.MOM.WW.MxGateway.Worker.Tests/TestSupport/TestTimeZones.cs b/src/ZB.MOM.WW.MxGateway.Worker.Tests/TestSupport/TestTimeZones.cs
new file mode 100644
index 00000000..4f68b396
--- /dev/null
+++ b/src/ZB.MOM.WW.MxGateway.Worker.Tests/TestSupport/TestTimeZones.cs
@@ -0,0 +1,44 @@
+using System;
+
+namespace ZB.MOM.WW.MxGateway.Worker.Tests.TestSupport;
+
+///
+/// Custom time zones built in code, so tests of the #228 Write2 time-argument
+/// conversion behave the same on every machine whatever its own zone or its
+/// registry time-zone data.
+///
+internal static class TestTimeZones
+{
+ ///
+ /// Gets a US-Eastern-shaped zone: UTC-5 standard, UTC-4 daylight, DST from
+ /// the second Sunday of March 02:00 to the first Sunday of November 02:00
+ /// (the vd03 zone). In 2026 DST starts at 2026-03-08T07:00Z and ends at
+ /// 2026-11-01T06:00Z.
+ ///
+ public static TimeZoneInfo Eastern { get; } = CreateEastern();
+
+ /// Gets a fixed UTC-5 zone with no DST.
+ public static TimeZoneInfo FixedUtcMinus5 { get; } = TimeZoneInfo.CreateCustomTimeZone(
+ "Test UTC-5", TimeSpan.FromHours(-5), "Test UTC-5", "Test UTC-5");
+
+ /// Gets a fixed UTC+05:30 zone with no DST (a positive, non-whole-hour offset).
+ public static TimeZoneInfo FixedUtcPlus0530 { get; } = TimeZoneInfo.CreateCustomTimeZone(
+ "Test UTC+05:30", new TimeSpan(5, 30, 0), "Test UTC+05:30", "Test UTC+05:30");
+
+ private static TimeZoneInfo CreateEastern()
+ {
+ TimeZoneInfo.TransitionTime dstStart = TimeZoneInfo.TransitionTime.CreateFloatingDateRule(
+ new DateTime(1, 1, 1, 2, 0, 0), month: 3, week: 2, DayOfWeek.Sunday);
+ TimeZoneInfo.TransitionTime dstEnd = TimeZoneInfo.TransitionTime.CreateFloatingDateRule(
+ new DateTime(1, 1, 1, 2, 0, 0), month: 11, week: 1, DayOfWeek.Sunday);
+ TimeZoneInfo.AdjustmentRule rule = TimeZoneInfo.AdjustmentRule.CreateAdjustmentRule(
+ new DateTime(2007, 1, 1), DateTime.MaxValue.Date, TimeSpan.FromHours(1), dstStart, dstEnd);
+ return TimeZoneInfo.CreateCustomTimeZone(
+ "Test Eastern",
+ TimeSpan.FromHours(-5),
+ "Test Eastern",
+ "Test Eastern Standard",
+ "Test Eastern Daylight",
+ new[] { rule });
+ }
+}
diff --git a/src/ZB.MOM.WW.MxGateway.Worker/Conversion/VariantConverter.cs b/src/ZB.MOM.WW.MxGateway.Worker/Conversion/VariantConverter.cs
index 8d7c4a7c..810fc877 100644
--- a/src/ZB.MOM.WW.MxGateway.Worker/Conversion/VariantConverter.cs
+++ b/src/ZB.MOM.WW.MxGateway.Worker/Conversion/VariantConverter.cs
@@ -9,6 +9,31 @@ namespace ZB.MOM.WW.MxGateway.Worker.Conversion;
public sealed class VariantConverter
{
+ private readonly TimeZoneInfo? mxAccessLocalTimeZone;
+
+ ///
+ /// Initializes a converter that renders timestamped-write time arguments in
+ /// the worker box's local zone ().
+ ///
+ public VariantConverter()
+ : this(mxAccessLocalTimeZone: null)
+ {
+ }
+
+ ///
+ /// Initializes a converter with an explicit zone for the timestamped-write
+ /// time argument. Tests inject a fixed zone so they do not depend on the
+ /// zone of the machine that runs them.
+ ///
+ ///
+ /// Zone MXAccess reads the Write2/WriteSecured2 time argument in,
+ /// or for resolved per call.
+ ///
+ public VariantConverter(TimeZoneInfo? mxAccessLocalTimeZone)
+ {
+ this.mxAccessLocalTimeZone = mxAccessLocalTimeZone;
+ }
+
///
/// Converts an object value to an MxValue without a specified data type.
///
@@ -157,6 +182,69 @@ public sealed class VariantConverter
};
}
+ ///
+ /// Converts the time argument of a timestamped write (Write2,
+ /// WriteSecured2 and their bulk forms) into the CLR object MXAccess
+ /// expects. Unlike , a
+ /// timestamp_value instant is rendered as box-local wall-clock time.
+ ///
+ ///
+ ///
+ /// MXAccess reads the VT_DATE time argument as local time on the worker
+ /// box and converts it to UTC itself, while a VT_DATE carries no
+ /// offset and the COM marshaler ignores . Passing
+ /// the UTC clock fields therefore stored the source timestamp shifted by the
+ /// box's UTC offset (+5 h on a UTC-5 box, #228). The read direction is the
+ /// opposite and stays as it is: MXAccess hands OnDataChange timestamps over
+ /// as UTC, and ToTimestamp treats them as UTC.
+ ///
+ ///
+ /// The UTC-to-local step uses
+ /// with the zone's DST rules, so it is exact and never yields an invalid
+ /// local time. The one residual loss is on the MXAccess side: in the hour
+ /// that repeats when DST ends, two UTC instants share one local wall-clock
+ /// time, and the offset-less VT_DATE cannot say which one is meant,
+ /// so MXAccess may store an instant from that hour 1 h off. Clients that
+ /// need exact timestamps across the fall-back hour should run the worker
+ /// box on UTC.
+ ///
+ ///
+ /// Only the timestamp_value kind is converted. Any other kind (a
+ /// string or a number) carries no zone, so it is passed through unchanged
+ /// as before and its meaning is the caller's.
+ ///
+ ///
+ /// Protobuf time argument of a timestamped write.
+ /// A COM-marshalable value for the MXAccess time argument.
+ public object? ConvertToComTimestamp(MxValue timestamp)
+ {
+ if (timestamp is null)
+ {
+ throw new ArgumentNullException(nameof(timestamp));
+ }
+
+ if (!timestamp.IsNull && timestamp.KindCase == MxValue.KindOneofCase.TimestampValue)
+ {
+ return ToMxAccessLocalTime(timestamp.TimestampValue.ToDateTime());
+ }
+
+ return ConvertToComValue(timestamp);
+ }
+
+ ///
+ /// Converts a UTC instant to the wall-clock time MXAccess expects for a
+ /// timestamped-write time argument. See .
+ ///
+ /// UTC instant ( or unspecified).
+ /// The same instant as wall-clock time in the MXAccess zone.
+ public DateTime ToMxAccessLocalTime(DateTime utcDateTime)
+ {
+ DateTime utc = utcDateTime.Kind == DateTimeKind.Local
+ ? utcDateTime.ToUniversalTime()
+ : DateTime.SpecifyKind(utcDateTime, DateTimeKind.Utc);
+ return TimeZoneInfo.ConvertTimeFromUtc(utc, mxAccessLocalTimeZone ?? TimeZoneInfo.Local);
+ }
+
private static Array ConvertToComArray(MxArray array)
{
return array.ValuesCase switch
diff --git a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs
index 4d542ae0..bf6c759d 100644
--- a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs
+++ b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessCommandExecutor.cs
@@ -497,7 +497,7 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor
write2Command.ServerHandle,
write2Command.ItemHandle,
variantConverter.ConvertToComValue(write2Command.Value),
- variantConverter.ConvertToComValue(write2Command.TimestampValue),
+ variantConverter.ConvertToComTimestamp(write2Command.TimestampValue),
write2Command.UserId);
MxCommandReply reply = CreateOkReply(command);
@@ -580,7 +580,7 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor
writeSecured2Command.CurrentUserId,
writeSecured2Command.VerifierUserId,
variantConverter.ConvertToComValue(writeSecured2Command.Value),
- variantConverter.ConvertToComValue(writeSecured2Command.TimestampValue));
+ variantConverter.ConvertToComTimestamp(writeSecured2Command.TimestampValue));
MxCommandReply reply = CreateOkReply(command);
AwaitWriteCompletion(
@@ -726,7 +726,8 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor
session.Write2Bulk(
write2BulkCommand.ServerHandle,
write2BulkCommand.Entries,
- value => variantConverter.ConvertToComValue(value)));
+ value => variantConverter.ConvertToComValue(value),
+ timestamp => variantConverter.ConvertToComTimestamp(timestamp)));
}
private MxCommandReply ExecuteWriteSecuredBulk(StaCommand command)
@@ -785,7 +786,8 @@ public sealed class MxAccessCommandExecutor : IStaCommandExecutor
session.WriteSecured2Bulk(
writeSecured2BulkCommand.ServerHandle,
writeSecured2BulkCommand.Entries,
- value => variantConverter.ConvertToComValue(value)));
+ value => variantConverter.ConvertToComValue(value),
+ timestamp => variantConverter.ConvertToComTimestamp(timestamp)));
}
private MxCommandReply ExecuteReadBulk(StaCommand command)
diff --git a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessSession.cs b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessSession.cs
index 31576d8c..c3c37b38 100644
--- a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessSession.cs
+++ b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessSession.cs
@@ -793,11 +793,16 @@ public sealed class MxAccessSession : IDisposable
/// The MXAccess server handle.
/// The write2 entries to process.
/// Converts protobuf MxValue to COM-compatible variant.
+ ///
+ /// Converts the per-entry time argument; it differs from
+ /// because MXAccess reads the time argument as box-local time (#228).
+ ///
/// The per-entry write results, in the order the entries were provided.
public IReadOnlyList Write2Bulk(
int serverHandle,
IReadOnlyList entries,
- Func convertValue)
+ Func convertValue,
+ Func convertTimestamp)
{
ThrowIfDisposed();
if (entries is null)
@@ -810,6 +815,11 @@ public sealed class MxAccessSession : IDisposable
throw new ArgumentNullException(nameof(convertValue));
}
+ if (convertTimestamp is null)
+ {
+ throw new ArgumentNullException(nameof(convertTimestamp));
+ }
+
List results = new(entries.Count);
foreach (Write2BulkEntry entry in entries)
{
@@ -820,7 +830,7 @@ public sealed class MxAccessSession : IDisposable
serverHandle,
entry.ItemHandle,
convertValue(entry.Value),
- convertValue(entry.TimestampValue),
+ convertTimestamp(entry.TimestampValue),
entry.UserId)));
}
@@ -869,11 +879,16 @@ public sealed class MxAccessSession : IDisposable
/// The MXAccess server handle.
/// The WriteSecured2 entries to process.
/// Converts protobuf MxValue to COM-compatible variant.
+ ///
+ /// Converts the per-entry time argument; it differs from
+ /// because MXAccess reads the time argument as box-local time (#228).
+ ///
/// The per-entry write results, in the order the entries were provided.
public IReadOnlyList WriteSecured2Bulk(
int serverHandle,
IReadOnlyList entries,
- Func convertValue)
+ Func convertValue,
+ Func convertTimestamp)
{
ThrowIfDisposed();
if (entries is null)
@@ -886,6 +901,11 @@ public sealed class MxAccessSession : IDisposable
throw new ArgumentNullException(nameof(convertValue));
}
+ if (convertTimestamp is null)
+ {
+ throw new ArgumentNullException(nameof(convertTimestamp));
+ }
+
List results = new(entries.Count);
foreach (WriteSecured2BulkEntry entry in entries)
{
@@ -898,7 +918,7 @@ public sealed class MxAccessSession : IDisposable
entry.CurrentUserId,
entry.VerifierUserId,
convertValue(entry.Value),
- convertValue(entry.TimestampValue))));
+ convertTimestamp(entry.TimestampValue))));
}
return results;
diff --git a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs
index 505c533e..bc8997d4 100644
--- a/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs
+++ b/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessStaSession.cs
@@ -229,6 +229,16 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
///
internal TimeSpan WriteCompletionTimeout { get; set; } = ResolveWriteCompletionTimeout();
+ ///
+ /// Zone the command executor renders the Write2/WriteSecured2 time
+ /// argument in, handed over at .
+ /// (the production value) means
+ /// . Internal-settable as a test seam so
+ /// Worker.Tests assert the #228 conversion independently of the zone of
+ /// the machine that runs them.
+ ///
+ internal TimeZoneInfo? MxAccessLocalTimeZone { get; set; }
+
///
/// Cadence the alarm poll loop waits between polls. Resolved from the
/// launcher environment; internal-settable as a test seam (set before
@@ -362,7 +372,7 @@ public sealed class MxAccessStaSession : IWorkerRuntimeSession
staRuntime,
new MxAccessCommandExecutor(
session,
- new VariantConverter(),
+ new VariantConverter(MxAccessLocalTimeZone),
alarmCommandHandler,
// ReadBulk and the write-completion wait need to pump
// Windows messages while they wait for the inbound COM