General Points
It is possible for two programs to pass data thru gates in a variety of methods. Unforeseen advantages will accrue if there is a tendency toward standard methods. We begin to list here some conventions.
Order code kt+5 often means "start extended jump protocol" {(p3,ejp)}.
Order code kt+6 often means "return a key identical to the one called but that does not obey kt+4"
Positive return codes generally indicate a problem that the caller could not have anticipated.
Negative return codes indicate errors that may be tentatively blamed on the caller.
Return code 1 means the first key parameter should have been a prompt official space bank and wasn't. Return code 2 means it was a bank but it ran out of space.
kt+1: While most objects don't return kt+1 explicitly, a call to the slot that held a key to an object that has disappeared will be a call to a data key which returns kt+1.
A return code of kt+2 means that the order code is never valid for this class of object.
A return code of kt+3 means there was a format error in the request.
If the domain must be prompt then the co-routine part of the linkage must be performed by a backend domain which is unique for this jump.
Assume the desired jump is EJP(oc,data;K1,K2,K3,K4,K5,K6,K7 ==> rc,retdata;KA,KB,KC,KD,KE,KF,KG). The convention is as follows:
EJP stashes away the data and keys K1, K2, and K3 and calls
the resume key received from CALLER with
CALLEXIT(kt+5;==>oc,next-page-buffer;K4,K5,K6,CALLEXIT).
This is the start of the Co-routine linkage.
Jumper then calls the resume key received from EJP with EK(kt+5,second-4096-bytes;K4,K5,K6 ==> rc;,,,EK)
... this protocol continues until the jumper has passed all of the data and all the keys. If the jumper runs out of data before keys zero length strings are passed, if the jumper runs out of keys first then no keys are passed and zero data keys will be received by the jumpee.
Jumper then jumps to the resume key received from EJP with EK(oc,data;K7==>rc1,first-4096-bytes;KA,KB,KC,EK). At this point the jumpee performs the requested service and begins another extended jump protocol to return.
If rc1 is kt+5, jumper then continues an extended jump protocol to get the remaining keys and data: EK(kt+5; ==> rc,second-4096-bytes;KD,KE,KF,KG). If rc1 is not kt+5, rc is rc1, KD is EK, and the remaining keys are DK(0). Note that on the last return up to 4 keys can be passed.
In general, keys which are expected but not passed should be assumed to be DK(0).
LOOP: CALL CG(...;...==>...;..., ..., ..., CG) ... GO TO LOOP
Such a program will produce a resume key for another program CG. If that program also has the above form then the programs will behave as co-routines to each other. The co-routine protocol does not require that resume keys be provided but merely that successive jumps provide a gate and use the gate provided by the previous jump. Since most uses of the co-routine protocol involve one program that predominately produces and another that predominantly consumes data, we always label one the (_producer) and the other the (_consumer). When two programs are communicating like this we call it a co-routine interface.
We call gates that are used thus as co-routines (_co-gates). This is merely a pedagogical device to remind us of these conventions.
If two programs obey the following conventions they are called a (_byte stream producer) and a (_byte stream consumer).
The concatenation of the successive data strings should not depend on the limits provided by the consumer.
If no more data can ever be accepted, limit will be kt+1 {as if BSC were DK(0)}.
Each of these specific standards have a format number:
Lines are delimited by either the character pair (carriage return, linefeed) or the newline character at the discretion of the producer.
{ni}Pages are delimited by the character formfeed.
If limit > 4096, the operation is undefined. If limit <= 0, c will be kt+2 and no data will be returned.
SBSP(kt ==> x'019',(1,1);,,,SBSP) {i.e. co-routine producer, data format 1}.
If SBSC is not willing to accept more data, limit will be kt+1 {as if SBSC were DK(0)}.
SBSC(kt; ==> x'01a',(1,1);,,,SBSC) {i.e., co-routine consumer, data format 1}.
If SRSP is a standard record stream producer, it produces a stream of transparent records, with no imbedded format indications. Each co-routine call will deliver one logical record.
If limit > 4096, the operation will use the extended jump protocol {(p3,ejp)} to pass 4096 byte blocks until a single record has been passed. If limit <= 0, c will be kt+2 and no data will be returned.
SRSP(kt ==> x'019',(1,0);,,,SRSP) {i.e., co-routine producer, data format 0}.
If SRSC is not willing to accept more data, limit will be kt+1 {as if SRSC were DK(0)}.
SRSC(kt; ==> x'01a',(1,0);,,,SRSC) {i.e., co-routine consumer, data format 0}.
If SBRSP is a standard block record stream producer, it produces a stream of blocked logical records. Each logical record will be preceeded by a halfword containing its length in bytes. A logical record may span co-routine calls, and each co-routine call may contain multiple logical records.
If limit > 4096, the operation is undefined. If limit <= 0, c will be kt+2 and no data will be returned.
SBRSP(kt ==> x'019',(1,2);,,,SBRSP) {i.e., co-routine producer, data format 2}.
If SBRSC is not willing to accept more data, limit will be kt+1 {as if SBRSC were DK(0)}.
SBRSC(kt; ==> x'01a',(1,2);,,,SBRSC) {i.e., co-routine consumer, data format 2}.
If two programs obey these conventions they are called a (_key stream producer) and a (_key stream consumer).
The consumer's program is equivalent to:
Normally c will be 1, 2, or 3.
Normally oc will be 0. If there are no more keys to be returned (and never will be) {"end of file"}, c will be kt+1 {as if GET were DK(0)}. If no more keys can ever be accepted, oc will be kt+1 and the jump can be a fork or return.
Where c is the number of keys passed {1 to 3}.
If there are no more keys and no more keys will ever be generated, c is kt+1 and the jump can be a fork or return. If no more keys can ever be accepted, oc will be kt+1 {as if PUT were DK(0)}.
A procedure for establishing a network of co-routines is as follows: call the byte stream creator for each of the co-routine interfaces that are eventually to exist. Keep the pairs of go-gates. Create each of the members of the network in any convenient order, handing out the co-gates in the process.
This convention seems to remove the most possible logic from the various correspondents concerning initialization. When one of these programs is running it holds resume keys to each of its correspondents. We have thus made the initial conditions as much like the running conditions as possible.
Application Design notes
This convention does not support networks with loops.
Programs with outputs must initialize their resume key slots for those interfaces somehow. This is a mess.
Programs with two outputs are now supposed to provide two resume keys to serve as co-gates to the respective consumers. Clearly some legerdemain is required here.
This seems to compound the problems of initializing the units. It has the advantage of being symmetrical and easy to understand for the assembler of co-routines.
If c=1, PSB is not an official prompt space bank.
If c=2, PSB had insufficient space.
If c=3, SB is not an official space bank.