The domain key grants its holder the ability to extract and insert all of the data and keys that would be available to a process running in the domain. It also provides access to portions of the domain which are not automatically available to programs running in the domain. The domain key thus allows examination of and intervention in the execution of the domain's program.

A domain key may be used to examine or modify the domain even while it is running. Changes to the domain take effect immediately.

Let D represent a domain key.

D(DOMAIN__GET{=0}+1;==>;K) returns C1 {the domain's meter {(p1,d1)}} and D(DOMAIN__SWAP{=32}+1;K==>;L) stores K in C1 and returns the previous contents in L.

D(DOMAIN__GET{=0}+2;==>;K) returns C2 {the domain's keeper {(p1,d2)}} and D(DOMAIN__SWAP{=32}+2;K==>;L) stores K in C2 and returns the previous contents in L.

D(DOMAIN__GET{=0}+3;==>;K) returns C3 {the domain's address segment key {(p1,d3)}} and D(DOMAIN__SWAP{=32}+3;K==>;L) stores K in C3 and returns the previous contents in L.

D(DOMAIN__REPLACE_MEMORY{=74},(4,iaddr);K ==>;L) stores K in C3 {the domain's address segment {(p1,d3)}} and iaddr in the instruction address in C4 {the domain's psw key {(p1,d4)}} and returns the previous contents of C3 in L.

If n is 10 or 11 then D(DOMAIN__GET{=0}+n; ==>;K) returns Cn and D(DOMAIN__SWAP{=32}+n;K==>;L) stores K in Cn and returns the previous contents in L. C10 and C11 are available for general use {(p1,d10)}. C10 is frequently the symbol table for the domain's DDT.

D(DOMAIN__GET{=0}+13;==>;K) returns C13 {the domain's busy flag {(p1,d13)}}.

If n<16 then D(DOMAIN__GET_KEY{=16}+n;==> c;K) returns the key from slot n of the general keys node of domain D. c = 2 iff the domain is malformed, 0 if successful.

If n<16 then D(DOMAIN__SWAP_KEY{=48}+n;K==> c;L) stores K in slot n of the general keys node of D and returns the prior contents of that slot in L. c = 2 only of the domain is malformed, 0 if successful.

D(DOMAIN__MAKE_START{=64},(1,b1);==> ;E) creates a start key E to the domain with databyte b1.

D(DOMAIN__GET_CONTROL{=68};==>,bs;) returns the right 6 bytes of the data from the data keys in C4 thru C9. {Returns zeros if slots don't hold data keys.}

{C4 is the PSW {(p1,d4)}, C5 is the trap code {(p1,trapcode)}, C6 is the monitor control reg {(p1,d6)}, C7 and C8 are the PER control regs {(p1,progevents) and C9 is the PER code and address {(p1,progevents)}.}

D(DOMAIN__GET_REGS{=70};==> c,((64,genregs),(32,floatregs));) gets all general and floating register values from the domain. c = 2 only if the domain is malformed, 0 if successful.

D(DOMAIN__PUT_REGS{=71},((64,genregs),(32,floatregs));==> c;) places values into the registers of the domain. c = 2 only if the domain is malformed, 0 if successful.

D(DOMAIN__PUT_STUFF{=75},((64,genregs),(32,floatregs),(36,bs));==> c;) places values into the registers of the domain, and creates data keys in C4 thru C9 and puts the data from bs in them {using 6 bytes from bs for each key}. c = 2 only if the domain is malformed, 0 if successful.

D(DOMAIN__MAKE_AVAILABLE{=65};==>c;) deletes all resume keys to the domain and, if the domain is running, deletes the process in the domain. C13 is set to DK(0) {available}. c is set to 0 if the domain was available and 1 if it was busy. c = 2 only if the domain is malformed.

D(DOMAIN__MAKE_BUSY{=67};==>c;EX) deletes all resume keys to the domain and deletes the process in the domain if the domain is running. C13 is set to DK(1) {busy}. c is set to 0 if the domain was available and 1 if it was busy. c = 2 only if the domain is malformed. EX is a fault key to D.

D(DOMAIN__MAKE_FAULT_EXIT{=66};==>c;EX) puts DK(1) in C13 {busy}. c = 2 only if the domain is malformed. If the domain was already busy c is set to 1 and EX is DK(0). Otherwise c is 0 and EX is a fault key to D.

D(DOMAIN__MAKE_RETURN_EXIT{=73};==>c;EX) puts DK(1) in C13 {busy}. c = 2 only if the domain is malformed. If the domain was already busy c is set to 1 and EX is DK(0). Otherwise c is 0 and EX is a return key to D.

Summary of operations that affect busy/available state

.Grab=8;Order dp* key returned if Final Code busy {c=1} available {c=0} State

MAKE_ yes available AVAILABLE

CREATE_ FAULT_ no fault busy EXIT

CREATE_ RETURN_ no return busy EXIT

* {dp = deletes resume keys and process}

Some order code should wait for the domain to become available and then produce a restart key leaving the domain busy. This would support changing the algorithm of a domain.
Calling a start key to the domain, with instructions for it to call, does that.

The domain key should identify start and resume keys as being to the same domain. They should produce the databyte of the start key and the subclass of the resume key if it is, indeed, to the same domain. This bears on the claim at (p1,unfun).

Calls on the domain key that would make the domain mal-formed should cause no change and produce a distinctive trap code.

Programming Notes:

The fastest way to initialize a domain is to initialize C4 thru C9 before initializing C16 thru C31 or the registers.

Sharing Domain Keys

It is difficult for two programs to share a domain key. This problem is particularly severe when a domain key to domain D is shared by both D and a DDT over D.

{arcane}A promising technique is to design a debugger along the following principles:

When a domain is created an extra node N is created and the only domain key is kept in N. N is formatted as a red segment node with the domain key in the position of the segment keeper. Segment keys to N are distributed to whoever needs a domain key. These segment keys perform as would a domain key when called. A node key to N is kept in D perhaps in the slot now conventionally used to keep D's symbol table.

D's keeper is a start key to a program much like the current VDK. If D should fault, VDK is in a position to retrieve the only real domain key to D and replace it {in N} by an entry to the debugger, who can now transparently interpret calls on the synthetic domain key. Note that the synthetic domain key may be safely used by either D or any other program.

If the debugger wishes it may withdraw from its relationship with D leaving things as if it had never been there.

If the node designated by D is not the root of a well-formed domain, any of the above calls may return 2 in c instead of performing the indicated action. Order codes 16 through 31 are guaranteed to do so.

{arcane}If the jumper and the invoked domain share nodes but are not the same domain, a trap may occur as described in (p1,worsejump), SC = 36 or 37. If the invoked domain and the returnee share nodes but are not the same domain, then {1} the situations of (p1,worsejump), SC = 48 and 49 are possible, and {2} if the order code is 70 {read registers} the return may not occur.