Ref

Description#

A Ref to an existing object, such as Window.Ref or PaneRef, is reusable in any number of plans. A Ref a plan method returns for a step is bound to the plan that returned it: a different plan refuses it before it sends anything. The binding is a token the Plan carries, so a copy of a Plan (a plan returned by value) keeps recognizing its own refs. Do not record steps on both a plan and its copy, though: they would number the same steps differently.

A Ref from Window.Ref or Pane.Ref names the winlink or linked pane the record viewed when Ref was called. A later renumbering or move of that window is not followed, so build the plan from fresh records. A record that cannot name its placement still yields a Ref; an operation that needs the placement then refuses with a PlanError instead of falling back to the bare ID.

ServerRef addresses the server for the operations that document a server scope. The zero Ref is kept as a second spelling of it for those same operations, such as Plan.Cmd and Plan.SetEnvironment; any operation that needs an object refuses both with a PlanError.