{nonref}General Points

"Ask of a subroutine only what can it do for you {and how soon and how cheap}."

Occasions arise when a domain needs to call other domains for services that the first domain cannot provide. Sometimes this is because the second domain has access to data that the first domain must not access. Perhaps the authority of neither domain includes that of the other. In Gnosis, jumping thru a gate serves this function.

A gate is a kind of key that designates a domain. The domain that issues the jump must hold and designate the gate. The gate leads to the other domain where the process may run with different authority. As the authority of the domains differ, so perhaps do the responsibilities and loyalties of the programmers of the two programs. It is important to note that the gate to a domain restricts the holder merely to starting the program at a place specified by the domain and offering some data and authority. The process has moved to that domain at the conclusion of the jump. We speak of a gate to a program, but a gate specifies a domain which includes a program and typically some authority as well. If the program is a conversational query program, two gates to it may designate two domains that hold different data but designate the same program. Holding one of the gates provides access to the corresponding data. This fact does not depend on the logic of the query program.

This chapter is about what happens when a program "jumps at a gate". All keys provide some of their function by being jumped to but some key types {meter and memory keys} have other functions as well.

Intuitively there seem to be two circumstances where a domain gains control. The first circumstance is where there is a new case for the domain to consider. The second circumstance is where the domain is regaining control to resume the consideration of a case that was interrupted in order to consult {call} another domain concerning the current case. Similarly there are two reasons for control to leave a domain: when the domain is done considering a case and when another domain must be consulted about the current case.

To support this distinction there are three states of a domain: available, running and waiting. While a process is in a domain it is (_running). After a process leaves domain A by calling domain B, but before the process returns, domain A is said to be (_waiting). While a domain is running or waiting it is busy. This insures that no new process will enter this domain until the current case is finished and the working storage is no longer required. After a process is done with the current case it returns and is then said to be (_available) {for another case}. See (p1,dsterm) for the official definitions of these terms!

While discussing jumping through a gate we call the domain that invokes the gate key the (_jumper). The domain designated by the gate key is called the (_jumpee).

There are three domains involved in a domain key jump: the jumper, the domain designated by the invoked key and the returnee {the domain designated by the forth argument key if it is a resume key}. {If the jump is a call, the returnee and the jumper will be the same.} Any combination of these domains may be the same. What happens is as if the operation were done in three steps: first the key and data parameters are taken from the jumper; then the operation is performed on the domain designated by the invoked key; finally, key and data values are returned to the returnee.

There are two types of gate key, the (_start) and the (_resume).

Start

The start key is like the Fortran concept "ENTRY" and even more like the PL/I construct by that name. The start key may be used only to give control to a available domain.

The start key gives eight bits worth of "history" or status information to the jumpee {see <p1, databyte>}. This information is provided by the creator of the start key, who is usually not the same as the jumper {see <p2, crent>}.

Resume
When a domain acts in the role of a subroutine, the resume key is the key that the program explicitly uses to return to the caller when the service is complete. The resume key may be used only to give control to busy domains {(p1,dsterm)}.

When a resume key is invoked, the order code is sometimes called the (_return code).

In order that a caller need not cope with the possibility that one resume key be used twice, all slots holding resume keys to a given domain become empty when any of the resume keys is jumped to. Unless C13 of a domain has been changed with a node key, there will be no resume keys to available or running domains.

There are three kinds of resume key:

Return Key
This kind of resume key is produced when a program issues a call jump. It may be used by the jumpee or his deputy to return control to the jumper and return some parameters.

Fault Key
This kind of resume key is produced when a segment keeper is called as a result of a translation exception or protection exception {(p1,segkeepcall) and (p1,tobesk)}. A fault key may be used to trap the designated program {by offering a nonzero return code} but not to pass any parameters otherwise {there being no no entry block available}. A fault key is like a return key to a domain with a zero entry block. See (p1,jtrap) for special role of fault keys.

Restart Key
When an implicit jump occurs to a meter keeper {(m2)} or domain keeper, the kernel produces a restart key and passes it to the keeper. In the case of a trap in a domain, the restart key is to the domain. In the case of meter expiring, the restart key is to the domain that tried to use the expired resource. These keys may be used to restart the program but not to pass parameters. A nonzero return code will be ignored.