Forms of the Jumps

KALL (g,oc) STRINGFROM(cse) KEYSFROM(...) RCTO(x) STRINGTO(sv) SILI KEYSTO(...);

KRETURN (g,oc) STRINGFROM(cse) KEYSFROM(...) KENTRYID(id);

KENTRY (id) OCTO(x) STRINGTO(sv) SILI KEYSTO(...) DATABYTETO(db);

KFORK (g,oc) STRINGFROM(cse) KEYSFROM(...);

The KALL, KFORK and KRETURN statements cause the suggested jump to be issued.

After the KRETURN statement, control passes to the indicated KENTRY statement when the domain holding this code is next jumped to. If control should reach a KENTRY statement by other than a KRETURN statement, ERROR will be signaled.

Each of these keywords {words in upper case} may be omitted except the first. The text following up to the next keyword is then also omitted. The "(id)" in KENTRY may also be omitted.

"oc" is an integer expression whose value becomes the parameter word in the emmited message.

Throughout this manual and especially in sections (p2,primary) and (p2,supp) we give mnemonics for these parameter words. They are of the form "type__function" where "type" and "function" are PL/I style variables and "type" describes the kind of key being called and "function" describes what is being called for.

"..." represents a string of c-slots separated by commas.

"g" is a c-slot.

A c-slot is really an integer variable {(p3,plikeynames)} whose value normally changes just once. {The value may be used to index into a supernode.}

A null c-slot in "KEYSFROM(...)" provides the value DK(0).

A null c-slot in "KEYSTO(...)" causes the received key to be discarded.

If a variable is named in the KEYSTO phrase and the variable's value is -1 then an unused c-slot index will be assigned to that variable and that new value will be used. If the value of an expression in a KEYSFROM field is -1 then the key DK(0) will be provided.

{ni}We may provide a call to free a slot. "KFREE sd;" where "sd" is a an integer variable that had occurred in a "KEYSTO(...)" jump command. sd's value will be -1 after this call.

"cse" is a character string expression whose length and value become the value of the string argument. Note that Gnosis does not support strings longer than 4096 characters.

"sv" is a character string variable. {It must be declared with the VARYING attribute.}

The maximum length that can be received through this mechanism is determined by the maximum length of the string variable "sv". Note that Gnosis does not support strings longer than 4096 characters. If the offered string is longer than the maximum length of the string variable, the excess is lost.
{ni}And if you didn't specify SILI, STRINGSIZE is signalled.

"db" should be declared as "DCL db FIXED BIN(15)" and receives the value of the databyte of the start key used to enter this domain.

"x" should be declared as "DCL x FIXED BIN (31)" and receives the order code.

"(id)" identifies a "KENTRY" statement. "id" will be used as a label and must be valid as such. The identified statement is the one that will be executed when this domain is next jumped to. If KENTRYID is omitted and there must be just one KENTRY statement, the execution will resume at that KENTRY statement.

The naming of keys:

Keys reside in c-slots. In these calls c-slots are named with the aid of variables declared as FIXED BIN(15). A reference to the variable is passed to the jump subroutine and if the value is -1 then a value is assigned to it that is different from the values assigned to other such variables in this domain. Thus the variable should normally be declared as "FIXED BIN(15) INIT(-1) STATIC".

For debugging purposes, see (kjumpadebug).

There is currently no method of reclaiming the space used to hold the keys. Thus if these variables are declared as AUTOMATIC the storage used to hold the keys will not be reclaimed when the block where the variable is declared is exited. Thus such variables should usually be declared as STATIC or EXTERNAL.

The keys your program finds initially depend on the environment it is in. See (plipack-keys) concerning programs packaged by PLIPACKER. See (p2,gnobibmx) concerning programs in factories produced by the OSFACT command. See (p2,old-oskeys) concerning even older OS environments. These keys can be referenced by c-slots declared "FIXED BIN(15) INIT(n) STATIC" for each n defined as an initial c-slot.

The statement "KALL (RETR, 0);" takes .25 ms.

"KALL (RETR, 0) KEYSFROM(RETR) KEYSTO(RETR);" takes .30 ms.

To send a key from the cache requires about 30 microseconds.

To access a key not in the cache requires about .6 ms if there are clean cache slots and 1.2 ms otherwise.