The Tymnet adapter (not to be confused with a Tymnet adapter under Tymshare CP) is a program that holds the sole authority {(p2,tba)} to communicate with some Tymnet base. Its only responsibility is to insure that the users of various circuits do not interfere with each other and to provide to the respective circuit users efficient and unrestricted access to the Tymnet circuit. The Tymnet adapter thus multiplexes and demultiplexes the interface between Tymnet and the host.

To see the log of the interface to Tymnet do "OSFLOAD user.systemview.prttymlf PRTTYML 0" and then "EXECUTE PRTTYML". This is a record of troubles at this interface.

See (p2,gtt) about a way to access Gnosis under VM without a dedicated Tymnet base. See (tssc) for most common use of these facilities.

TA supports three kinds of gate which are associated with a particular circuit. They are SIK {(p2,sik)}, SOK {(p2,sok)} and CCK {(p2,cck)}. They originate by the logic described in (p2,newsiksok) and (p2,auxcir) {but most programs can get them only by getting the CCK the logic described in (p2,desttcem) and then using the tap operations on the CCK}.

A circuit can be zapped at the instigation of either Tymnet or the CCK or TBLK key holders. Whatever the cause, the following happens:

CCK becomes DK(0). Any operations on CCK that were in progress return with order code kt+1.

SIK and SOK signal EOF.

If the input or output interface is tapping, the corresponding "B" key will be jumped to with order code kt+2.

TLAF(0;PSB,M,SB ==> c1;,,,CO) followed by CO(0;TLBA ==> c2;TBLK) creates a Tymnet adapter that uses TLBA {(tlba)}.
C1 is 0 if ok, 1 if PSB not a prompt space bank, 2 if not enough space in PSB.

TLAF(kt; ==> X'2020E';)

"Input" refers to messages from the circuit destined for the circuit user. (Recall that a message in a circuit is either a data byte or a control code {(cc)}.) Input is transferred by means of the byte stream protocol {(p3,bytstream)}. The byte stream consists of a sequence of (_tokens). See (p2,tokmap) for the meaning of tokens.

When the circuit is zapped, the fact that no more data will ever be transferred is signaled according to the byte stream protocol.

Messages from the circuit may be buffered by the TA. If the byte stream consumer {the circuit user} does not consume bytes fast enough {i.e., the interface spends too much time in the consuming state}, backpressure will be generated on the circuit to prevent the TA's buffers from overflowing. {This is the only way the circuit user can cause backpressure to be generated.}

The circuit user can encourage the TA to delay delivering input so that data can be grouped into larger blocks, resulting in less overhead. This is done by means of the (_activation set). Whenever any message in the activation set has been received, it and all messages preceding it will be promptly delivered to the circuit user. (Of course, messages cannot be delivered while the interface is consuming.) (N.B. The message in the activation set may not be the last message in the transmission.) Messages will also be promptly delivered when there are enough of them to reach the limit of data that the consumer will accept. Other than the above, the TA will usually not deliver any messages (even if the interface is producing), but it reserves the right to do so (for example to free up buffer space).

All control codes are in the activation set. Whether a data byte is in the activation set depends on the 8-bit (_activation set mask). A data byte is in the activation set if and only if its low 7 bits are the ASCII representation of a character in mask set i and bit i of the activation set mask is on (0 <= i <= 7).

See (p2,maskset) for definition of mask sets.

Note the following differences between this definition and the definition of mask sets used in Tymshare's VM 370 systems. Space is in set 0. Set 5 is specified to contain backspace.

"Output" refers to messages from the circuit user destined for the circuit. Output is transferred by means of the byte stream protocol {(p3,bytstream)}. The byte stream consists of a sequence of tokens {(p2,tokmap)}.

The TA will consume output promptly unless the circuit is generating backpressure.

When the circuit is zapped, the fact that no more data can ever be accepted is signaled according to the byte stream protocol.

The first byte of a token identifies the type of token. The first byte is divided into three fields as shown below. If subsequent bytes are part of the token, that is indicated below; {n} represents n data bytes.

bit{s} add'l valid for]
0 1-2 3-7 bytes In Out circuit message{s}

0 W X {WX} I O {WX bytes of data} {WX > 0}

1 0 1 I O Gobbler

1 0 2 I O Enter Deferred Echo Mode

1 0 3 I O Leave Deferred Echo Mode

1 0 4 I O Green Ball

1 0 5 I O Red Ball

1 0 6 I O Yellow Ball

1 0 7 I O Orange Ball

1 0 8 I Gray Ball

1 0 9 I Black Ball

1 0 10 I Break character

1 0 11 O Hang character

1 0 12 O Enter Transparency Mode

1 0 13 O Leave Transparency Mode

1 0 14 Enter Alternate Output Device Mode

1 0 15 Leave Alternate Output Device Mode

1 1 16 stat I Port status

1 1 17 tc O Probe Terminal Characteristics

1 2 18 tc, val I Terminal Characteristics Response

1 2 19 tc, val O Set Terminal Characteristics.Iovr=0;

The following operations can all be in progress at once: Tap Input, Tap Output, Wait for gobbler or zap, and one other.

Any of these operations will return kt+1 if the circuit has been zapped.

CCK(0,(4,new_limit);A,B==>c,(4,old_limit),(4,ncc);D,SIK) ("Tap Input").

If a Tap Input operation is already in progress, c=2.

Otherwise, if the input interface is producing, i.e. the TA holds a co-gate and an old limit, then the co-gate is returned in D and the old limit in old_limit; key A replaces the old co-gate; new_limit replaces the old limit; c is zero; B is ignored; and SIK is DK(0).

If it is convenient for CCK users we will admit that in this case ncc is zero.

If omitted, new_limit is assumed to be 1.

If the input interface is consuming, i.e. some program holds a co-gate to the TA, the operation waits until the input interface is not in the "tapping" state, then: the input interface enters the "tapping" state; SIK is a new co-gate; A and new_limit are ignored; D is DK(0); old_limit is garbage; c is 1; and the next time the old co-gate is jumped to, the jump and its parameters (i.e. the limit) will be passed on to key B and then the input interface will leave the "tapping" state.

In either case ncc is the number of bytes that the TA has committed (to the old consumer) to send but has not sent yet (i.e. the rest of the current token). (They will be sent to the new consumer promptly.)

If it is convenient for CCK users we will admit that ncc is at most 2.

CCK(1;A,B==>c,(4,new_limit),(2,n),(n,state);D,SOK) ("Tap Output").
If a Tap Output operation is already in progress, c=2.

Otherwise, if the output interface is consuming, i.e. the TA holds a co-gate, then that co-gate is returned in D, key A replaces it, c is zero, new_limit is garbage, B is ignored, and SOK is DK(0).

If the output interface is producing, i.e. some program holds a co-gate to the TA and a limit, the operation waits until the output interface is not in the "tapping" state, then: the output interface enters the "tapping" state; SOK is a new co-gate; new_limit is the limit that applies to SOK; c is 1; A is ignored; D is DK(0); and the next time the old co-gate is jumped to, the jump and its parameters will be passed on to key B and then the output interface leaves the "tapping" state.

In either case, the TA resets its state, i.e. it interprets the next byte received from the new co-gate to be the beginning of a token. If part of a token had been received, it is ignored, unless it was a data byte token, in which case the data bytes which were received are sent on the circuit. n will be 0, 1, or 2. "state" is the shortest string of bytes that could be sent to the TA to put it back in its previous state, i.e. it describes the nature of the bytes that the old producer has committed to send but has not sent yet. There are only these cases:

.(n, state)

.(0)

.(1, M) 0 < M < 128 {M bytes of data remaining)

.(1, X'D3') Set Term. Characteristics

.(2, X'D3', tc) Set Term. Characteristics

.(1, X'B1') Probe Term. Characteristics

CCK(2;==>0;) {"Zap Circuit"}.
Zaps the circuit.

CCK(3;==>0;) ("Start Gobbling").
Turns on a flag called "gobbling".

While gobbling is on, SOK will be prompt. Messages for the circuit will be discarded beginning at this point in the output stream. However, a character gobbler is never discarded. If gobbling is turned on while SOK is consuming, it returns immediately. Only whole messages are discarded, so SOK continues to keep track of where it is within a token. Gobbling is initially off.

Programming note: In the usual situation there is one domain A generating output for SOK and another domain B which discovers a need to stop the output. B will signal the need to stop to A (via shared memory) and then do a Start Gobbling operation to ensure that A sees the signal promptly. When A does so, it sends a gobbler via SOK and then does a Stop Gobbling operation. Only A uses SOK.

CCK(4;==>c;) ("Wait for gobbler or zap").
This operation returns when the next token to be transferred across the input interface is a gobbler or the circuit is zapped. (It works even if the input interface is consuming.) c=0 in the case of a gobbler, c=kt+1 if zapped. If there is already a "wait for gobbler or zap" in progress, c = 2.

CCK(5;==>0;) ("Activate now")
If the input is producing, it promptly stops producing and returns whatever data it may have. If it is not producing, then the next time it becomes producing it will return promptly.

CCK(6;==>0;) ("Stop Gobbling")
Turns off the "gobbling" flag.

CCK(256+A; ==> c;) ("Set activation set mask").
0 <= A <= 255. If the input interface is producing, c=1. Otherwise c=0 and the activation set mask is set to A.

CCK(kt;==>X'20E';)

There can be three operations in progress simultaneously on this key: "Get new circuit", "Build circuit", and one other.

Initially, the interface is shut and the base timeout is short.

TBLK(0,((2,hostno),(2,key));RECEPF ==> c;errlog) "Start"

Brings up the interface. Sets the host number and key to be used. 0 < key < 256.

Errlog is a byte stream producer which will deliver error messages. See the listing of the Tymnet adapter for the format of these messages.

Data from errlog should be consumed promptly.

RECEPF is a key which will be called as follows for each circuit that is built to the base:

RECEPF(0;PSB,M,SB ==> 0;,,,CO) followed by

CO(0,(4,soklim);SIK,SOK,CCK) (this is a fork)

These calls should be prompt.

c = 0 if successful, 1 if a start has already been done, 2 if there is an error in the data supplied.

TBLK(1,(1,shut);==>;) "Open/Shut"
Makes the interface shut if shut is 1, open if it is 0.

TBLK(2; ==> rc,env-data;) "Read environmental data"
If no environmental data has been received since the TBLK was created, env-data is null. Otherwise env-data contains the most recent environmental data beginning with the version byte. The return code rc is 0 if the base interface is up, 1 if it is down.

TBLK(3,login string; ==> c,(4,limit),(4,localport); SIK,SOK,CCK) "Build aux circuit"
Builds an aux circuit from the host. Login string has in order, the username, a colon, the decimal host number, and the login line terminator (carriage return or semicolon). Login string must have between 1 and 26 characters inclusive.

Return codes:

0: Done. SIK, SOK, CCK, and the string are returned.

1 <= c <= 255: The circuit could not be built, and c is the error code from the supervisor. Known error codes are:

1 format error in login string

2 username not in MUD

3 MUD unreadable due to disk error

4 Other (including destination host down, destination host cannot be reached through the network, circuits busy, initiating or destination host out of ports, destination host is shut and username does not have shut override, username not valid on destination host, etc.)

5 error related to dialout request

6 timeout

7 access not permitted or (for Lemcom) ISIS unable to complete request

8 Tymnet base has reached limit of circuits it can build. (i.e. out of origination ports)

The last time that this symptom occurred was when there were many circuit fragments that went between the base code within the ISIS slot and the network. We think that these arose when a circuit zapper arrived from Tymnet and would have been passed into the host. See (p3,tech-supp).

The normal way for such a circuit to disappear is for the host to reply with a circuit zapper. But we were using long base timeouts and the host wasn't there. When Gnosis restarted it had no knowledge of the circuit fragments. If zappers did arrive in the host after the restart the host presumably ignored them because it believed that there were no circuits for those channels. The base code does not zap those circuit fragments upon host reset because that was once observed to crash the ISIS system {dispatcher}.

The solution for now (until the base code is fixed) is to ask Network operations to reset that base slot. See (p3,isis-slot).

9 queue too long, try again later

256: Login string is empty or has too many characters

257: There is already a domain trying to build a circuit.

258: The attempt to build a circuit was terminated by a network supervisor reset or interface reset.

Loose end: need a way to abort this if it takes too long. Also need to specify a protocol that will allow building more than one circuit at once.

TBLK(4;==>0,(8,tod),(4,sup clock);) "Read supervisor clock"
Returns the last value of the supervisor clock observed and the local time of day at which it was observed. Returns zeroes if the clock has not been observed.

TBLK(5,(2,port);==>c;) "Zap circuit"
Zaps the circuit on the indicated port. c=0 if there was a circuit, 1 if not, 2 if port number missing or too large.

This operation is needed for the case when Tymnet thinks there is no circuit (so no zapper can be sent from the other end) but for some reason Gnosis thinks there is.

TBLK(6,(1,timeout);==>;) "Set Time-out"
The base uses the timeout to decide when the host has crashed.

This operation sets the base timeout to 32 seconds if timeout is 1, 4096 seconds if it is 0.

TBLK(7; ==> c;) "Stop"
If the Tymnet adaptor is already stopped, or there is a "stop" operation in progress, c=1. Otherwise, takes the base interface down, signals EOF on the errlog byte stream, and returns c=0 when that is accomplished.

TBLK(8; ==> 0,(4,cpsin),(4,cpsout);) "Query data rates"
Returns the number of data characters per second of input (base to host) and of output (host to base). The values are averaged over five minutes.

TBLK(9,(1,NID),login string; ==>
c,(4,limit),(4,localport); SIK,SOK,CCK) "Build normal circuit"
Builds a normal circuit from the host. NID is the Network ID to be used for the circuit (see Tymnet documentation). Login string has in order, the username, a colon, the decimal host number, a semicolon, the password, and the login line terminator (carriage return or semicolon). Login string must have between 1 and 157 characters inclusive. The password and its preceeding semicolon are omitted if the username has no password.

Return codes are the same as for Build Aux Circuit.

TBLK(kt+4;==>c;) Destroy
Return code c: 0 if ok, 1 if not stopped

TBLK(kt;==>X'1020E';)

According to a conversation this afternoon with Joe Rinde we have the following possibilities with regards to multiple bases on a 370.

Configuration Rules:

Each Lemcom base requires an ISIS slot.

One Tymnet engine can support several slots limited by load and memory requirements.

One Tymnet engine cannot have more than one slot serving the same host number.

This is perhaps easy to change.

Dallas currently has three engines running ISIS. If we used two host numbers then each of these engines could serve both of those host numbers. We would then have 6 slots each with its own ISIS slot serving one 370.

The fact that we are running on 3 engines gives us reliability. Using two host numbers is bad because we must arbitrarily segregate our customers. This isn't really much of a problem however.

All of these considerations leave unanswered the question of our costs. We need the answers to the following questions:

What is the cost of moving a character thru an ISIS slot.

How much does an ISIS slot cost plus the Lemcom hardware?

How much does it cost to move a character thru Tymnet?

How much does it cost to keep a circuit for a unit of time including the access port and access phone?

{arcane}GETCIRCUITC
This key is in the privileged facility node (privnode) and is used by SYSTOOL to generate and destroy keys to circuit builders for a specific Tymnet username.

GETCIRCUITC(0,(sl,tymnetid); ==> c;GETCIRCUIT)

GETCIRCUIT is the key to build a circuit to the specified Tymnet id.

"sl" is the length of the string "tymnetid" and must be between 1 and 12, tymnetid is in EBCDIC.

c = 1 duplicate Tymnet Id specified (only one key allowed for each Tymnet id)

c = 4 Tymnet id all blanks

GETCIRCUITC(1,(sl,tymnetid); ==> c)
Destroys the GETCIRCUIT key that would build a circuit to the Tymnet id specified.
c = 2 No such key exists

GETCIRCUITC(kt; ==> x'120')

{ni}GETCIRCUITCPW
This key produces objects called just as GETCIRCUIT objects {(getcircuit)} are called. Such objects remember a password however.

GETCIRCUITCPW(0,((2,sl),(sl,tymnetid),(2,pwl), (pwl,password),sn); ==> c;GETCIRCUIT)

GETCIRCUIT is the key to build a circuit to the specified Tymnet id.

"sl" is the length of the string "tymnetid" and must be between 1 and 12, tymnetid is in ASCII. (pwl,password) is the ASCII password required by the network supervisor.

c = 4 Tymnet id all blanks

If sn is '' then the holder of GETCIRCUIT may specify the system number. If sn is (4,sysno) then GETCIRCUIT will build circuits only to that system.

Design Notes
Tymnet will not want to install bases with "auxfile license" for turnkey Gnosis systems. To do so would impact much of the security of computers connected to Tymnet, to bugs existing or introduced into the Gnosis TA program. While we would not intend for typical turnkey users to meddle with TA or the TBLK key that is only an intention.

Note that this function can be implemented in a Gnosis system whose base lacks "aux circuit license".

An essential difference is that such a getcircuit object must be replaced when a password is changed!

GETCIRCUIT
This key will create auxiliary circuits to the designated host. See (p3,auxdef) for this functionality from the command system.

GETCIRCUIT(sysno; ==> c,(4,limit);SIK,SOK,CCK)

sysno is a binary number in the range 0 - kt-1 that designates the Tymnet host.

The USERNAME is fixed by the System Administrator when the GETCIRCUIT key is obtained from GETCIRCUITC.

SIK,SOK, and CCK are the circuit keys {(tymnet)}. Limit is the largest string accepted by SOK.

Return codes.

c=n where n<512 the return code from TBLK(3,(username); ==> (4,limit);SIK,SOK,CCK) (p2,tblk)

c=513 internal error

c=514 no TBLK key in system

GETCIRCUIT(kt; ==> x'20')

GETCIRCUIT(kt+4; ==> 0)

Destroy self

GETCIRCUIT(kt+6; ==> 0;GETCIRCUIT)
In order to protect the key, should it be desirable to give the key to some other user, a copy that will not honor kt+4 can be made. Order code of kt+6 returns a single key that will behave the same as the original key but will not honor kt+4.