dohertj2/wwtools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ce32c5cee84d9b895a2edc7a01e238aa58a87725
wwtools/graccesscli/docs/zb-testmachine.md
T
Joseph Doherty c52d8d0171 graccesscli: correct script-edit docs to TN-537 truth (writes DO persist) 
I was wrong. AVEVA Tech Note 537 ("Creating an Application Object Script
Using GRAccess", April 2008) documents the supported pattern:
ConfigurableAttributes[<script>.<field>].SetValue(MxValue) inside a
CheckOut/Save/CheckIn cycle. graccesscli's existing
FindAttributeForMutation already follows this — writes to MxCategoryPackageOnly_Lockable
script-text fields persist correctly.

The earlier "writeback gap" diagnosis was a phantom caused by a reader-side
issue. `object attribute value get` against a script body returns
"Supported: False / Attribute value is not exposed" because
MxValueDetails uses a case-sensitive `ReadProperty(attr, "Value")` lookup
plus an accessor probe (GetBoolean -> GetInteger -> GetFloat -> GetDouble
-> GetString) that can fall through silently for some MxValue shapes. The
COM-side property is exposed as `value` (lowercase), readable as
`attr.value.GetString()` -- which the live probe at
`analysis/ide-edit-investigation/probe_setvalue/` does and confirms the
post-write content matches the marker exactly.

Live verification on $TestMachine.UpdateTestChangingInt.DeclarationsText
and $DelmiaReceiver.ProcessRecipe.{ExecuteText,DeclarationsText}:

  === verdict ===
    marker landed on same-proxy   ConfigurableAttributes: True
    marker landed on same-proxy   Attributes            : True
    marker landed on fresh-proxy  ConfigurableAttributes: True
    marker landed on fresh-proxy  Attributes            : True

The probe also confirmed that two earlier graccesscli `object scripts set`
invocations (which I had wrongly believed failed) had persisted -- the
marker text I wrote previously was still on disk in
ProcessRecipe.{ExecuteText,DeclarationsText} when read directly via
attr.value.GetString(). The probe restored both fields to their original
values.

This commit:

- Updates the misleading [Command(...)] / [CommandOption(...)]
  descriptions in GRAccessSurfaceCommands.cs back to honest versions
  citing TN-537.
- Restores the --file-using examples for `object scripts set` and
  `object scripts create` across script-editing.md, llm-integration.md,
  usage.md, and zb-testmachine.md.
- Removes the test that asserted the (wrong) EnsureMutableViaSetValue
  guard. Re-aims ScriptCommandDescriptions_… at the corrected wording.
- Removes two leftover EnsureMutableViaSetValue calls in the trigger-period
  / trigger-type write paths (both targeted MxCategoryWriteable_C_Lockable
  attributes; would never have fired even if the helper still existed).
- Adds analysis/ide-edit-investigation/REPORT.md (replacing the earlier
  wrong report) plus the probe sources under probe_setvalue/.

The MxValueDetails reader gap (case-sensitive ReadProperty + accessor
probe) is a real follow-up: `object attribute value get` should
case-insensitively read `value` and try GetString first when the
underlying MxValue.DataType is MxString. Out of scope here -- that's a
separate, smaller fix.

Test count delta: 67 -> 66 (-2 wrong tests, +1 corrected description test).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 21:33:51 -04:00

321 lines
17 KiB
Markdown
Raw Blame History

# ZB TestMachine Template And Instance Documentation
Captured read-only from galaxy `ZB` on 2026-04-28 with `graccess_cli --llm-json`.
Core commands used:
```powershell
graccess template list --galaxy ZB --pattern '%TestMachine%' --llm-json
graccess instance list --galaxy ZB --pattern '%TestMachine%' --llm-json
graccess object snapshot --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object lineage --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object children --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object snapshot --galaxy ZB --name '$TestMachine.DelmiaReceiver' --type template --llm-json
graccess object snapshot --galaxy ZB --name '$TestMachine.MESReceiver' --type template --llm-json
graccess object snapshot --galaxy ZB --name TestMachine_001 --type instance --llm-json
graccess object snapshot --galaxy ZB --name DelmiaReceiver_001 --type instance --llm-json
graccess object snapshot --galaxy ZB --name MESReceiver_001 --type instance --llm-json
```
## Object Family
`$TestMachine` is a parent template derived from the System Platform `$gMachine` base template. Older captures had blank generic `DerivedFrom` / `BasedOn` fields; newer CLI builds should prefer `object lineage` and `object children` because they use typed GRAccess relationship reads and package fallback where available. The intended IDE inheritance for this object is:
```text
$gMachine
-> $TestMachine
-> $TestMachine.DelmiaReceiver
-> $TestMachine.MESReceiver
```
`$TestMachine.DelmiaReceiver` and `$TestMachine.MESReceiver` are contained embedded templates under `$TestMachine`, not standalone peer templates in the runtime hierarchy. They become contained child objects when a `TestMachine_*` parent instance is instantiated with contained-object creation enabled.
| Object | Relationship | Notes |
| --- | --- | --- |
| `$gMachine` | Base template | System Platform machine template extended by `$TestMachine`. |
| `$TestMachine` | Derived template | Adds machine identity, test alarm, historized value, array, protected-value, and script families. |
| `$TestMachine.DelmiaReceiver` | Contained template | Embedded receiver template with recipe/download attributes and `ProcessRecipe` / `Reset` script families. |
| `$TestMachine.MESReceiver` | Contained template | Embedded receiver template with MES move-in/move-out attributes. |
The family contains two child templates:
| Template | Contained name | Checkout status |
| --- | --- | --- |
| `$TestMachine` | | `checkedOutToMe` |
| `$TestMachine.DelmiaReceiver` | `DelmiaReceiver` | `notCheckedOut` |
| `$TestMachine.MESReceiver` | `MESReceiver` | `notCheckedOut` |
There are 20 parent instances, each with one `DelmiaReceiver` child and one `MESReceiver` child.
| Parent instance range | Child ranges |
| --- | --- |
| `TestMachine_001` through `TestMachine_020` | `DelmiaReceiver_001` through `DelmiaReceiver_020`; `MESReceiver_001` through `MESReceiver_020` |
The child instances use contained hierarchical names, for example:
- `DelmiaReceiver_001` has hierarchical name `TestMachine_001.DelmiaReceiver`.
- `MESReceiver_001` has hierarchical name `TestMachine_001.MESReceiver`.
For future CLI captures, parse inheritance with lineage, children, snapshot fields, and relationship queries:
```powershell
graccess object snapshot --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object lineage --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object children --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object query-condition --galaxy ZB --type all --condition basedOn --value '$gMachine' --llm-json
graccess object query-condition --galaxy ZB --type all --condition derivedOrInstantiatedFrom --value '$gMachine' --llm-json
```
During the original capture, the two relationship queries returned empty arrays through the generic query path, so `$TestMachine -> $gMachine` was verified separately as IDE/SQL verification evidence. Normal CLI usage must not depend on SQL; SQL is only a development verification/debugging oracle.
## Snapshot Summary
| Object | Kind | Attributes | Configurable attributes | Script-like entries | Unavailable fields |
| --- | --- | ---: | ---: | ---: | ---: |
| `$TestMachine` | template | 282 | 282 | 22 | 0 |
| `$TestMachine.DelmiaReceiver` | template | 178 | 178 | 36 | 1 |
| `$TestMachine.MESReceiver` | template | 110 | 110 | 25 | 1 |
| `TestMachine_001` | instance | 282 | 282 | 22 | 0 |
| `DelmiaReceiver_001` | instance | 179 | 179 | 36 | 1 |
| `MESReceiver_001` | instance | 110 | 110 | 25 | 1 |
Earlier snapshots reported package/export fallback failures with:
```text
Library not registered. (Exception from HRESULT: 0x8002801D (TYPE_E_LIBNOTREGISTERED))
```
That was traced to .NET publisher-policy binding to the GAC `ArchestrA.GRAccess` 2.0 interop assembly plus late-bound reflection on `IgObjects.ExportObjects`. Current CLI builds disable that publisher policy and use typed `IgObjects` export calls. `object snapshot --llm-json` now reaches package fallback without a `TYPE_E_LIBNOTREGISTERED` unavailable entry.
Script metadata is readable. Direct script body readback is still not exposed through the generic local GRAccess value path, but the CLI now parses nested exported package archives and binary UTF-16 `ScriptExtension` records. `object scripts get --script UpdateTestChangingInt` and `--script UpdateTestChangingInt.ExecuteText` return the package-backed body:
```text
Me.TestChangingInt = System.Random().Next(1,1000);
```
## `$TestMachine` Attribute Structure
The base template has 282 attributes. Category distribution:
| Category | Count |
| --- | ---: |
| `MxCategoryCalculated` | 65 |
| `MxCategoryWriteable_USC_Lockable` | 46 |
| `MxCategoryPackageOnly` | 29 |
| `MxCategoryCalculatedRetentive` | 27 |
| `MxCategoryWriteable_C_Lockable` | 25 |
| `MxCategory_SystemInternal` | 22 |
| `MxCategoryPackageOnly_Lockable` | 22 |
| `MxCategoryWriteable_US` | 15 |
| `MxCategory_Constant` | 13 |
| `MxCategory_SystemWriteable` | 7 |
Data type distribution:
| Data type | Count |
| --- | ---: |
| `MxString` | 87 |
| `MxBoolean` | 63 |
| `MxInteger` | 37 |
| `MxQualifiedEnum` | 22 |
| `MxBigString` | 18 |
| `MxTime` | 17 |
| `MxQualifiedStruct` | 9 |
| `MxReferenceType` | 9 |
| `MxDataTypeEnum` | 7 |
| `MxFloat` | 5 |
| `MxElapsedTime` | 4 |
| `MxInternationalizedString` | 2 |
| `MxDouble` | 1 |
| `MxStatusType` | 1 |
Security classification distribution:
| Security classification | Count |
| --- | ---: |
| `MxSecurityUndefined` | 192 |
| `MxSecurityOperate` | 28 |
| `MxSecurityFreeAccess` | 24 |
| `MxSecurityViewOnly` | 18 |
| `MxSecurityTune` | 12 |
| `MxSecurityConfigure` | 6 |
| `MxSecuritySecuredWrite` | 1 |
| `MxSecurityVerifiedWrite` | 1 |
## `$TestMachine` Top-Level User Attributes
| Attribute | Data type | Category | Security | Lock |
| --- | --- | --- | --- | --- |
| `MachineCode` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
| `MachineDescription` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
| `MachineID` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
| `TestAlarm001` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
| `TestAlarm002` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
| `TestAlarm003` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
| `ProtectedValue` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecuritySecuredWrite` | `MxUnLocked` |
| `ProtectedValue1` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityVerifiedWrite` | `MxUnLocked` |
| `TestHistoryValue` | `MxInteger` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
| `TestStringArray` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
| `TestIntArray` | `MxInteger` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
| `TestDateTimeArray` | `MxTime` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
| `TestBoolArray` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
| `TestChangingInt` | `MxInteger` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` | `MxUnLocked` |
The CLI also read normal framework top-level attributes such as `Tagname`, `ShortDesc`, `ScanStateCmd`, `SecurityGroup`, `Area`, `Container`, `Host`, `ConfigVersion`, `ExecutionRelatedObject`, `ExecutionRelativeOrder`, `ContainedName`, and `HierarchicalName`.
Scalar value readback for the user attributes returned "not exposed by this GRAccess attribute" through the current generic value path. Use snapshots for metadata and use export/version-specific adapters when exact IDE-entered values are required.
## `$TestMachine` Attribute Families
Dot-child groups found in the base template:
| Root | Child attribute count | Purpose |
| --- | ---: | --- |
| `MachineCode` | 1 | Description metadata. |
| `MachineDescription` | 1 | Description metadata. |
| `MachineID` | 1 | Description metadata. |
| `TestAlarm001` | 45 | Alarm extension/settings family. |
| `TestAlarm002` | 45 | Alarm extension/settings family. |
| `TestAlarm003` | 45 | Alarm extension/settings family. |
| `TestHistoryValue` | 19 | Historization/settings family. |
| `UpdateTestChangingInt` | 47 | Script object/settings family. |
Alarm families for `TestAlarm001`, `TestAlarm002`, and `TestAlarm003` include:
- Identity and extension metadata: `_ExternalName`, `_InternalName`, `HasStatistics`, `_RefAttrID`, `_ExtensionAttributeDatatypes`, `_ExtensionAttributeCategories`.
- Aggregate status: `AlarmMostUrgentSeverity`, `AlarmMostUrgentMode`, `AlarmMostUrgentAcked`, `AlarmCntsBySeverity`, `AlarmMostUrgentInAlarm`, `AlarmMostUrgentShelved`.
- Runtime status: `InAlarm`, `TimeAlarmOn`, `TimeAlarmOff`, `TimeAlarmAcked`, `Acked`.
- Operator/configuration settings: `Priority`, `Category`, `AckMsg`, `DescAttrName`, `ActiveAlarmState`, `AlarmMode`, `AlarmModeCmd`, `AlarmInhibit`.
- Shelving settings: `AlarmShelveCmd`, `AlarmShelved`, `AlarmShelveStartTime`, `AlarmShelveStopTime`, `AlarmShelveReason`, `AlarmShelveUser`, `AlarmShelveNode`.
- Condition/source settings: `Alarm.TimeDeadband`, `Condition`, `ConditionCached`, `AlarmSourceAttr`.
The `TestHistoryValue` history family includes:
- Identity metadata: `_ExternalName`, `_InternalName`, `_key`, `_refHistAttrKey`, `_ExtensionAttributeDatatypes`, `_ExtensionAttributeCategories`.
- Storage behavior: `ValueDeadBand`, `ForceStoragePeriod`, `InterpolationType`, `RolloverValue`, `SampleCount`, `EnableSwingingDoor`, `RateDeadBand`.
- Display/range metadata: `TrendHi`, `TrendLo`, `EngUnits`, `Hist.DescAttrName`.
The `UpdateTestChangingInt` script family includes:
- Script text fields: `ExecuteText`, `DeclarationsText`, `StartupText`, `ShutdownText`, `OnScanText`, `OffScanText`, `Expression`.
- Package-backed `ExecuteText` body: `Me.TestChangingInt = System.Random().Next(1,1000);`.
- Trigger/execution settings: `TriggerType`, `TriggerPeriod`, `TriggerOnQualityChange`, `DataChangeDeadband`, `RunsAsync`, `ExecuteTimeout.Limit`, `AsyncShutdownCmd`.
- Runtime statistics/status: `StatsReset`, `ErrorCnt`, `ExecutionCnt`, `ExecutionTime`, `ExecutionTimeAvg`, `ExecutionTimeStamp`, `Disabled`, `State`, `_LastExpression`.
- Dependency/reference metadata: `AliasReferences`, `Aliases`, `_ExternalReferences`, `_ExternalReferenceFlags`, `_AliasReferenceFlags`, `_Guid`, `_LibraryDependencies`.
- Error metadata: `ExecutionError.Condition`, `ExecutionError.Alarmed`, `ExecutionError.Desc`, `_ErrorMessage`, `_ErrorLine`, `_ErrorColumn`, `_ErrorReport`.
- Ordering/group metadata: `ScriptExecutionGroup`, `ScriptOrder`, `_ScriptExecutionGroupEnum`.
## `$TestMachine.DelmiaReceiver`
This contained template has 178 attributes and 36 script-like metadata entries.
Main user attributes:
| Attribute | Data type | Category | Security |
| --- | --- | --- | --- |
| `DownloadPath` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
| `JobStepNumber` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
| `PartNumber` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
| `ReadyFlag` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
| `RecipeDownloadFlag` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
| `RecipeProcessedFlag` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
| `RecipeProcessResult` | `MxBoolean` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
| `RecipeProcessResultText` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
| `Username` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
| `WorkOrderNumber` | `MxString` | `MxCategoryWriteable_USC_Lockable` | `MxSecurityOperate` |
Script families:
| Root | Child count | Notable fields |
| --- | ---: | --- |
| `ProcessRecipe` | 47 | `ExecuteText`, `Expression`, startup/shutdown/on-scan/off-scan text, trigger settings, execution stats, timeout, async shutdown. |
| `Reset` | 47 | Same script/settings pattern as `ProcessRecipe`. |
## `$TestMachine.MESReceiver`
This contained template has 110 attributes and 25 script-like metadata entries.
Main user attributes:
| Attribute | Data type |
| --- | --- |
| `MoveInBatchID` | `MxInteger` |
| `MoveInCompleteFlag` | `MxInteger` |
| `MoveInErrorText` | `MxString` |
| `MoveInFlag` | `MxBoolean` |
| `MoveInJobSequenceNumber` | `MxString` |
| `MoveInMesContainerNumber` | `MxString` |
| `MoveInNumberWorkOrders` | `MxInteger` |
| `MoveInOperatorName` | `MxString` |
| `MoveInPartNumbers` | `MxString` |
| `MoveInReadyFlag` | `MxBoolean` |
| `MoveInSuccessFlag` | `MxBoolean` |
| `MoveInWorkOrderNumbers` | `MxString` |
| `MoveOutBatchID` | `MxInteger` |
| `MoveOutFlag` | `MxBoolean` |
| `MoveOutCompleteFlag` | `MxBoolean` |
| `MoveOutErrorText` | `MxString` |
| `MoveOutMesContainerNum` | `MxString` |
| `MoveOutNumberWorkOrders` | `MxInteger` |
| `MoveOutOperatorName` | `MxString` |
| `MoveOutPartNumbers` | `MxString` |
| `MoveOutWorkOrderNumbers` | `MxString` |
| `MoveOutReadyFlag` | `MxBoolean` |
| `MoveOutSuccessfulFlag` | `MxBoolean` |
All listed MES receiver user attributes were `MxCategoryWriteable_USC_Lockable`, `MxSecurityOperate`, and `MxUnLocked` in the snapshot.
## Instance Topology
All parent instances observed:
```text
TestMachine_001
TestMachine_002
TestMachine_003
TestMachine_004
TestMachine_005
TestMachine_006
TestMachine_007
TestMachine_008
TestMachine_009
TestMachine_010
TestMachine_011
TestMachine_012
TestMachine_013
TestMachine_014
TestMachine_015
TestMachine_016
TestMachine_017
TestMachine_018
TestMachine_019
TestMachine_020
```
For each parent, the galaxy contains:
- `DelmiaReceiver_NNN` with hierarchical name `TestMachine_NNN.DelmiaReceiver`.
- `MESReceiver_NNN` with hierarchical name `TestMachine_NNN.MESReceiver`.
Representative instance snapshots:
| Instance | Hierarchical name | Attributes | Scripts | Checkout |
| --- | --- | ---: | ---: | --- |
| `TestMachine_001` | `TestMachine_001` | 282 | 22 | `notCheckedOut` |
| `DelmiaReceiver_001` | `TestMachine_001.DelmiaReceiver` | 179 | 36 | `notCheckedOut` |
| `MESReceiver_001` | `TestMachine_001.MESReceiver` | 110 | 25 | `notCheckedOut` |
The parent instance shape matches `$TestMachine` by count and script metadata. `DelmiaReceiver_001` has one more attribute than `$TestMachine.DelmiaReceiver` in the captured snapshot; the extra field should be treated as instance/runtime metadata until a version-specific diff tool reports the exact delta.
## Operational Notes For LLM Automation
- Prefer `object snapshot --llm-json` for template and instance discovery.
- Use `instance list --pattern '%TestMachine%' --llm-json` for current topology before editing.
- Treat `$TestMachine` as an extension of `$gMachine`; verify with `object lineage` first, then snapshot relationship fields, then package fallback/unavailable details.
- Use `template instantiate --create-contained` when creating `TestMachine_*` instances so `DelmiaReceiver` and `MESReceiver` child objects are created with the parent.
- Edit embedded child objects by targeting the child instance tagname, such as `DelmiaReceiver_001`, or its hierarchical name when a command supports hierarchical lookup.
- Do not mutate `$TestMachine` until the existing checkout state is understood; the template was `checkedOutToMe` during capture.
- Direct scalar value readback for many template attributes is not exposed by the current generic attribute value path.
- Direct script body readback is not exposed by the current generic value path; use `object scripts get --llm-json` package fallback for reads and `object scripts set --file <path> [--field <name>]` for script body attribute writes. The CLI follows AVEVA Tech Note 537 — writes go through `IgObject.ConfigurableAttributes[<script>.<field>].SetValue(MxValue)` and persist correctly even though `object attribute value get` may report the post-write value as "not exposed" (that's a `MxValueDetails` reader-side gap, not a write-side no-op).
- Extended attributes failed because the local COM type library was not registered.
Reference in New Issue View Git Blame Copy Permalink