Domain Macros. These macros are in DOMAIN MACLIB on the Gnosis disk. On Gnosis they are in SYS.DOMAINMAC. .

KC ik,[oc],[(pstr,pk0,pk1,pk2)],[(rstr,rk0,rk1,rk2,rk3)]
"ik" is the slot number {in the calling domain's general keys node} holding the key to be invoked.

"oc" must be an integer expression less than 4096. It will be used as the order code. If "oc" is absent, the order code must be loaded into register 1 before the KC macro.

If "pstr" is omitted, no string is passed. If it is of the form "(psaddr,pslen[,R])", a string is passed.

"psaddr" is the address of the beginning of the string to be passed. It will be loaded into general register 2. If omitted, register 2 must already be set up.

"pslen" is the length of the string. It will be loaded into general register 3. If omitted, register 3 must already be set up.

If "R" is present, the address of psaddr is an offset in the registers. E.g., if psaddr is 24, the string will begin with the high order byte of general register 6. The floating registers follow general register 15. If "R" is absent, psaddr is an address in the domain's memory.

The pk's are the slot numbers of the keys to be passed. Any may be omitted.

If "rstr" is omitted, no string is received. If it is of the form "(rsaddr,rslen[,R])", a string is received.

"rsaddr" is the address of the beginning of the area to receive the string. The address will be loaded into general register 4. If omitted, register 4 must already be set up.

"rslen" is the length of the area. It will be loaded into general register 5. If omitted, register 5 must already be set up.

If "R" is present, the address of rsaddr is an offset in the registers as above, otherwise it is an address in the domain's memory.

Specify STRINGLENGTHWANTED=1 or SLW=1 to accept the length of the offered string in general register 3.

The rk's are the slot numbers to accept the keys returned. Any may be omitted.

Specify ERR=erraddr to accept the return code in register 1 and branch to erraddr if it is nonzero.

Specify RC=R1 to accept the return code in register 1.

Specify neither of the above two to reject the return code.

LDENBL oc,rstr,k0,k1,k2,k3
Loads an entry block into floating register 2 and perhaps general registers 4 and/or 5.

oc is non-null (e.g. "ARC" or "R1") to accept the order code in R1.

rstr is null if no string is to be accepted, otherwise it is (rsaddr,rslen[,R]) as in KC.

Specify DATABYTEWANTED=1 or DBW=1 to accept the databyte in R2.

Specify STRINGLENGTHWANTED=1 or SLW=1 to accept the length of the offered string in R3.

k0, k1, k2, k3 are slot numbers to accept key parameters; a null slot number rejects that parameter.

LDEXBL ik,pstr,k0,k1,k2,k3
Loads an exit block into general register 0 and perhaps 2 and/or 3.

ik is the slot number of the key to be invoked.

pstr is null if no string is to be passed, otherwise it is (psaddr,pslen[,R]) as in KC.

k0, k1, k2, k3 are slot numbers of parameter keys to be passed; if a slot number is null, DK(0) is passed.

RETJUMP & CALLJUMP
Does a return or call jump. The program must have first loaded the exit block, entry block, and order code. CALLJUMP is seldom used because KC normally suffices.

FORKJUMP
Does a fork jump. The program must have first loaded the exit block and order code.

CONTIG
This produces no code. Its use is "CONTIG (a,b,c,d,e)". It will produce assembly errors if fields a through e are not contiguous. It requires two or more arguments. It is used near code that depends on the contiguity of fields. If the symbols a thru e are defined with EQU's, CONTIG will produce errors if those values are not sequential values.

CRASH
"CRASH a" produces what "BC a,*+1" would produce but without the assembler errors. "a" may be specified as "L", "NL", etc. or as "0101" etc. as in "BC B'0101',a". It is used to perform validity checks.

DOS
This macro results in the definition of several related macros. Those are DO, LOOP, ENDDO, WHILE, COUNT, UNTIL, and DOEXIT.

See Tymshare's "CP and CMS Assembler User's Supplement" for detailed information on their usage.

EQUAL
"EQUAL a,b" will produce an assembly error if the expressions a and b have different values. (Assemble time, not Macro time) No code is produced.

IFS
Expansion of this macro results in the definition of several related macros. They are IF, JOIN, ELSE, ENDIF and FI.

The IF macro takes as its argument the same possibilities as the CRASH macro. These macros can be used in the following combinations:

IF -- JOIN, IF -- ELSE -- FI, IF -- ENDIF

If the condition code suits the argument of the IF as control reaches the IF then control continues at the code following the IF. Otherwise control continues at the code after the matched JOIN, ELSE or ENDIF. As control reaches a JOIN control continues at the code after the JOIN. As control reaches an ELSE, control continues at the code after the matched FI. It is an error for control to reach a matched ENDIF. As control reaches a FI it continues after the FI.

A matched set of these macros may each have the same label in the label field. If these labels should not match, an MNOTES will be issued by the assembler. These symbols are not placed, as such, in the assembler's symbol table.

The LOCTR feature of the H assembler is used in an essential way in these macros. The code following the IF is compiled elsewhere in all cases. The code between the ELSE and FI is compiled inline. It is thus faster to design your code so the probability of the code following the IF is small. {A brief survey of the kernel indicates that this is true in 90% of the IFS.}

"IF 0000" is special in that it compiles no code but does switch to another LOCTR. Except for this case the IF always compiles 4 bytes of code {a BC instruction}. We have taken advantage of this in cases such as: BAL R14,a IF 1111 ... code to be executed for return to 0(R14) ENDIF ... code to be executed for return to 4(R14).

LESSTHAN
"LESSTHAN a,b" produces an assembler error unless expression a's (assembler) value is less than that of b. No code is produced.

MINMAX

CASES

Overview
KJUMPA is a procedure to trancend the domain's normal 16 slot limit. A super node is used to hold many keys and fifteen (once nine) of the domain's real slots form a cache of the supernode slots for performance.

While KJUMP is running there are no legitimate uses of the domain's real slots or the supernodes slots except via the KJUMP mechanisms. Via KJUMP there appear to be 64K slots instead of 16. These are called "c-slots" here.

C-slots are designated by halfwords in the range 0 through 2**16-2. (The value of the halfword is the index in the super node reserved for that c-slot.)

Reentrance, etc.:
The file KJUMPA TEXT consists of two CSECT's. The first CSECT contains the variables that are peculiar to a domain such as the state of the super node cache. We call this first CSECT a psect, following TSS. It is not reentrant. The second CSECT contains most of the code and is reentrant. The logic of the program KJUMPA assumes that there is a one-to-one correspondence between the psect's and the domains.

To use KJUMPA reentrantly, copy from entry point KJUMPBEG up to entry point KJUMPEND to private storage. Call the procedures by going to the appropriate offset in the private area. {Some day the loader will make this unnecessary}.

All procedure calls described in this section assume the OS calling convention, viz.:
R15 has the address of the entry point called.

R14 has the address to return to.

R13 points to a save area. 12(R13) through 71(R13) will be clobbered by the called program.

R1 points to a parameter list.

All registers are saved.

Initialization by calling KJUMPAI
Put a super node key in slot 0. Call KJUMPAI.

Just after calling KJUMPAI, the contents of C-slots 1 through 9 will be the keys that had been in general key slots 1 through 9. The initial contents of other C-slots will be the keys from the corresponding same index positions within from the super node.

The procedure KJUMPAI should be called before any of the other procedures described here. R1 points to the address of a halfword containing a c-slot index. KJUMPA will not allocate new c-slots less than or equal to that index. If KJUMPAI is not called, the index is assumed to be 9.

How to use KJUMPA
Three entry points to KJUMPA perform key invocations.
KJUMPAC does a call jump.
The parameter list for KJUMPAC consists of the DSECT EXITPARMS followed by the DSECT ENTRYPARMS. (R1 -> EXITPARMS ]
]
ENTRYPARMS)

KJUMPAR does a return jump.
The parameter list for KJUMPAR consists of the DSECT EXITPARMS followed by a pointer to the DSECT ENTRYPARMS. (R1 -> EXITPARMS ]
]
ADDR(ENTRYPARMS))

KJUMPAF does a fork jump.
The parameter list for KJUMPAF is just the DSECT EXITPARMS. (R1 -> EXITPARMS)

Here are the DSECT's referred to above. Any field which is not used will not be referenced and need not contain a valid address.
EXITPARMS DSECT
AINVOKEDKEY DS A
AINVOKEDKEY points to the halfword c-slot of the key to be invoked.

AORDERCODE DS A
AORDERCODE points to a fullword order code.

AEXITBLOCK DS A
AEXITBLOCK points to a byte. If key i is to be passed, bit i of the byte should be 1 {for i from 0 through 3}. If a string is to be passed, bit 5 should be 1. Other bits should be zero.

AKEYSFROM DS 4A
The four pointers at AKEYSFROM point to the c-slots of the keys to be passed, if any.

ASTRINGFROMADDR DS A

ASTRINGFROMLENGTH DS A

If a string is to be passed, ASTRINGFROMADDR points to the fullword address, and ASTRINGFROMLENGTH points to the fullword length, of the string.

ENTRYPARMS DSECT
AENTRYBLOCK DS A
AENTRYBLOCK points to a halfword. If key i is to be received, bit (i+8) should be 1 (for i from 0 through 3). If the return code is to be accepted, bit 4 should be 1. If the databyte is to be accepted, bit 5 should be 1. If a string is to be accepted, bit 6 should be 1. If the offered string length is to be accepted, bit 6 must be 1 and bit 7 should be 1. Bit 3 must be 1. Other bits should be zero.

Graphically: 0001RDSL KKKK0000

ARETURNCODE DS A
If the return code is to be accepted, ARETURNCODE points to a fullword which will receive the returned order code.

AKEYSTO DS 4A
The four pointers at AKEYSTO point to halfword variables containing the c-slots to receive the keys, if any.
The special c-slot value -1 directs KJUMPA to allocate a c-slot. The value of the allocated c-slot replaces the -1 as the value of the halfword variable. Any c-slot can be allocated that has not been previously allocated and is not below the limit specified to KJUMPAI. Sorry, currently indexes cannot be deallocated.

ASTRINGTOADDR DS A

ASTRINGTOLENGTH DS A

If a string is to be accepted, ASTRINGTOADDR points to the fullword address, and ASTRINGTOLENGTH points to the fullword length, of the area to receive the string.

AOFFEREDLENGTH DS A
If the offered string length is to be accepted, AOFFEREDLENGTH points to a fullword which will receive the offered string length.

ADATABYTE DS A
If the databyte is to be accepted, ADATABYTE points to a byte which will receive the databyte.

The entry KJUMPAK takes in R1 a pointer to a pointer to a c-slot. Use KJUMPAK when the key value in that c-slot is no longer required. Its effect is to save the effort of copying the key from the cache to the super-node. The result is that the key value may be replaced by an older value, which is why you only use KJUMPAK if you aren't going to use the value.

The entry KJUMPAE resets the status of the cache and the domain's key slots to that of before any KJUMP requests.

The new KJUMP does not restore general slots 10 thru 15 to their original keys.

This describes the state of the KJUMPA code sufficiently to find keys in or out of the cache. Slot 0 of the domain holds a key to a supernode (p2,snode) that holds keys not currently in the cache. An array of 15 words is kept at symbolic address LRU (an ENTRY) that remembers what logical slots are represented in the cache. The format of such a word is: 16 bits of logical slot number (the value of the PL/I variable representing the slot), an 8 bit "dirty flag" and an 8 bit number of the slot it this domain which holds the key. Later entries in this table represent more recently used slots.