These are several facilities to move data between Gnosis and other hosts.

Tymnet File Transfer

Scenario
To transfer data from a remote system, user first builds an Auxiliary Circuit with (p2,getcircuit). This circuit is then passed the "remote file to record stream converter creator" {(p2,rfrscc)} to create a record stream producer. This record stream may, in turn, be converted into a segment or a record collection using the "protocol conversion creator" {(p2,protcc)}

To transfer data to a remote system, user first builds an Auxiliary Circuit with {(p2,getcircuit)}. This circuit is then passed the "remote file to record stream converter creator" {(p2,rfrscc)} to create a record stream consumer. This record stream may, in turn, be created from a segment or a record collection using the "protocol conversion creator" {(p2,protcc)}

Commands
See (p3,auxdef) and (p3,auxfile)

File transfer supervisor
AUXMANGRC(kt+5;SB,M,GETCIRCUIT ==> kt+5;,,,,CO)

CO(sysno,(st,string);=c;AUXMANGR)

The username is implied by the GETCIRCUIT (getcircuit) key.

The string, specified in EBCDIC, will be sent on the circuit built by GETCIRCUIT as soon as GETCIRCUIT returns. This string should contain the project code and any initial commands required to precede the file transfer. {Note that character code 0D translates to ASCII CR. The translation is as described at (sok6).} Any errors caused by errors in this command string may cause the transfer to fail and the in the worse case cause an indefinite delay for the caller. String is currently limited to 127 bytes and is in EBCDIC.

return codes

c=0 worked ok

c=1 space bank is not prompt

c=2 domain creation failed

AUXMANGC(kt; ==> x'122')

AUXMANGR(type,(filedescription);STRU ==> c,(4,extended return code))
This key does either an immediate or delayed file transfer. For order codes 4,5 (delayed transfer) the form is AUXMANGR(type,(filedescription);STRU ->c,(4.LRECL);,,,CO). CO is a record stream co-routine key that can be used by the application to access a remote file.

File description is the CMS file specification including option RECFM LRECL information. The form of this description is as specified on the AUXDEF^AUXFILE command (p3,auxfile).

STRU - Key to a Gnosis data structure that will be sent or into which the remote file will be put.

The type order code is as follows:

0 - OPEN the circuit and send string {(f-str)}

1 - GET immediate to STRU

2 - SEND immediate from STRU

3 - Setup for delayed transfer ("remember file-description")

4 - GET delayed (called at "OPEN" time)

5 - SEND delayed (called at "OPEN" time)

6 - CLOSE close circuit

kt+4 - DESTROY zap this domain

NOTE, 0 - OPEN is included for the sake of completeness. The circuit will be built implicitly when needed. CLOSE is not implicit so that multiple files can be processed with one circuit.

Return codes. Because AUXMANGR uses many keys in doing its work an extended return code scheme is used. The primary return code indicates what Keys failed and the extended (4 byte) return code indicates the return code from the failing key.

c=3 GETCIRCUIT {(getcircuit)} failed on OPEN

c=4 GETCIRCUIT failed on GETI

c=5 RFRSCC failed (first call) for GETI

c=6 RFRSCC failed (second call) for GETI

c=7 RFRSC {(rfrsc)} failed for GETI (probably multiple logons)

c=8 Creation of Protocol Converter {(protc)} failed for GETI

c=9 Failure in Protocol Converter for GETI

c=10 Status call to RFRSC failed for GETI

c=11 GETCIRCUIT failed on SENDI

c=12 RFRSCC failed (first call) for SENDI

c=13 RFRSCC failed (second call) for SENDI

c=14 RFRSC failed for SENDI (probably multiple logons)

c=15 Creation of Protocol Converter failed for SENDI

c=16 Failure in Protocol Converter for SENDI

c=17 Status call to RFRSC failed for SENDI

c=18 GETCIRCUIT failed for GETD

c=19 RFRSCC failed (first call) for GETD

c=20 RFRSCC failed (second call) for GETD

c=21 RFRSC failed for GETD

c=22 GETCIRCUIT filed for SENDD

c=23 RFRSCC failed (first call) for SENDD

c=24 RFRSCC failed (second call) for SENDD

c=25 RFRSC failed for SENDD

AUXMANGR(kt ==> ;x22)

For immediate transfers AUXMANGR destroys all domains it uses to accomplish the file transfer after the transfer is complete. On delayed transfers AUXMANG allows for the destruction of the RFRSC (rfrsc) domain via the CLOSE order code.

Remote File Conversion
RFRSCC(kt+5;PSB,M ==> c;,,,CO)

CO(0;SIK,SOK,CCK ==> c;RFRSC,RT)

RFRSC is the converter key and RT is a key that is used to query the status of the transfer, retrieve the "miscellaneous traffic", and destroy the domain.

Return codes

c=1 Space bank not prompt

c=2 Creation failed (god was resting)

RFRSCC(kt; ==> x'121')

RFRSC
This key sends the actual CMS AUXFILE command on the circuit and synchronizes with the CMS AUXFILE facility.

RFRSC(0,(file description); ==> c,(2,lrecl);,,,CO)

GET CMS file

File description is a CMS file description including FILENAME FILETYPE FILEMODE

Lrecl is the record length field from the CMS FSCB and specifies the maximum size record expected.

CO is a co-routine producer key over which the data travels using "blocked record" format.

RFRSC(1,(file description); ==>c;,,,CO)
PUT file - transfers data to a CMS file

File description is a CMS file description including FILENAME FILETYPE FILEMODE and optionally RECFM and LRECL (default Fixed 80)

CO is a co-routine consumer key obeying the blocked record protocol

Return codes
c=3 error scanning file description

c=5 synchronization error with CMS AUXFILE

This may be caused if the Gnosis 191 disk is not accessed on the target machine. Also caused by multiple logons. (The response text was not as expected).

c=6 circuit zapped during initial logon (very unlikely)

kt+2 circuit zapped during the "AUXFILE" dialog (such as user already logged on)

RFRSC(kt; ==> x'21')

PROGRAMMING NOTE
Since RFRSC {and the subsequent key CO} and RT are keys to the same domain it is possible to become confused and call a blocked key. This can happen if an error is detected by the process using the CO key during a data transfer. Such an error might be caused by getting an unexpected and fatal return code from some process such as a record keeper. In these cases it is necessary to abort the data transfer process before attempting to use the RT key to retrieve the circuit keys. Calling the CO key with an order code greater than KT will serve this purpose. For input KT+1 will cause the RFRSC domain to reject the order code as invalid and free the domain by returning to instead of calling the caller. For output FORKING with order code of kt+1 may cause the receiving process to detect end of file {assuming it is done on a record boundary} but will cause the RFRSC domain to return to a zero data key. Order codes greater than KT+1) will always cause the RFRSC domain to return. The OS simulator does this automatically if delayed transfers used or if the PROTC domain is used to "move" the file.

PROGRAMMING NOTES
At user validation time the ADMINISTRATOR uses the GETCIRCUITC key to generate a key to a specific Tymnet userid. This key will be given to the command system created for the validated user and will be in the directory of that user.

The AUXDEF and AUXFILE commands use the AUXMANGRC key to create a domain that will manage file transfers to the specific Tymnet id available with the GETCIRCUIT key supplied. The AUXMANGR key is called with the appropriate order codes to direct the process.

Delayed Transfers

The AUXDEF command first calls the AUXMANGR domain with the file description and then the AUXMANGR key is put into the directory. There will be separate AUXMANGR domains for each AUXDEF because these domains may be active simultaneously depending on the restrictions of the remote host.

At "OPEN" time (in the OS simulator) AUXMANGR is called for the delayed transfer and the circuit is opened, the initial string is sent, a remote file conversion routine is created and called to send the AUXFILE command to the remote host. The co-routine key that is returned is used by the simulator (or other process) to do the data transfer. After the co-routine key has signalled end of file the AUXMANGR key can be called to close the circuit. This domain is not normally destroyed (especially by the simulator) so that the same key can be used to transfer the same file at a later time. The AUXMANGR key can be thought of as a capability to a remote file.

Immediate Transfers
The AUXMANGR key is used to accomplish the transfer. The delayed mode is not used to avoid recursion. (Create protocol conversion routine and give it the AUXMANGR key as in the delayed mode). The AUXFILE command will call AUXMANGR to perform the transfer. The AUXMANGR domain will create and RFRSC domain and a PROTC domain, call the GETCIRCUIT key to open the circuit, call the RFRSC domain to initiate the AUXFILE process, and finally give the PROTC domain the Gnosis structure key and the RFRSC co-routine key and wait for completion. All domains used by AUXMANGR will be deleted at completion of the transfer.

On the Gnosis tools disk there is an exec called PUNFILE. "PUNFILE gname a b c (opt" transmits the CMS file named "a b c" to the virtual reader of the virtual machine running Gnosis where there is a program that will accept the data and place it in a Gnosis file called "USER.SYS.READER.gname". If there is already an object there by that name it will be deleted first.

If opt is "SEGMENT" then the Gnosis file will be a segment in file transfer format. If opt is "record" then the Gnosis file will be a entry sequenced record collection.

The facility at (print) is used to provide a path from Gnosis running on a virtual machine to CMS on the same machine. "KC USER.PUB.PRINT 0 (%XJACK,SEG)" will cause the information in segment or record collection SEG to appear in the virtual reader of VM user name JACK.

This mechanism is still of use mainly because it becomes available earlier in a big bang that the "READER" facility {(reader)}.

Scenario

Suppose user U wants to transfer a file from CMS to Gnosis and he is interested in the record structure.

He gives a Gnosis operator access to the file.

E.g. he puts it on a disk on a machine that runs Gnosis in a virtual machine and tells the operator the password and file name.

The operator owns a minidisk called a transfer disk, which is formatted in a certain way. He runs the CMS program GSEND that copies the file to the disk, formatting it into Gnosis pages, preserving record information.

Then the operator mounts that minidisk on the Gnosis machine.

E.g., on the Gnosis machine he links to the disk at some address in the range 130:137 and (if necessary) issues a ready command to cause a device end interrupt.

Then, on Gnosis, the program GRCV reads the pages and constructs a segment.
User U has a program on Gnosis that calls a (public) entry to:
present proper identification (e.g. a password established when the user gave the operator access to the CMS file),

pass a space bank for the operator to use, and

receive the segment in return.

GSENDFMT
A transfer disk must be formatted at the time a set of disk packs (a "pack set") is formatted for Gnosis.

GSENDFMT is an example of a CMS program that formats a minidisk at virtual address 134 as a transfer disk.

{local-lore}The Gnosis 1AC disk is sometimes used for non-volatility.

GSENDFMT initializes a variable, kept on the disk, that indicates the next CDA to use. GRCV has a variable that determines what CDA's it expects next. That variable is initialized at Big Bang time to the same value that GSENDFMT provides. Thus executions of GRCV must follow executions of GSEND in an alternating sequence and GSENDFMT must be executed at the time of a Big Bang. Thus each execution of GRCV must follow an execution of GSEND and each execution of GSEND must follow an execution of GRCV except for the first which must follow GSENDFMT.

For each transfer, new CDA's are used. They are allocated from a large range, namely 2**23 through 2**24-1
{(kernel-logic,xfer-range)}. The program GRCV has a range key for this range.

Any time Gnosis is restarted, CDA's can be recycled.

GSEND
GSEND is the CMS program that writes a CMS file onto a transfer disk. It can be invoked as a command by typing "GSEND fn ft fm" where "fn ft fm" describes the file to be transferred. If fm is omitted "*" is used. The transfer disk is assumed to be at device address X'134'.

The return code returned by GSEND is a password to be supplied to GRCV. 256 <= password < 2**16.

Each time GSEND is used it writes in a new, higher set of CDA's. Only one file can be transferred at once.

{GSEND seems to report "Error writing device 134." when the 134 disk is too small.}

GRCV {File Segment Receiver}
See (p3,ixport) for a format compatible facility for moving files between CMS under the Keykos CP simulator and the native world.

The command described in (p3,receive) invokes GRCV for a terminal user.

GRCV is the name of the Gnosis program that receives transferred files, and also the name of a generally available key to that program.

At any given time GRCV is ready to receive a file starting at a certain cda in the transfer range (the "current cda"). GSENDFMT initializes the transfer disk so that GSEND will write the first file at page cda 2**23+1. GRCV is initialized with this value as its current cda.

GRCV(pw;SB1,M,SB2==>c;S) where pw is not kt, reads the file at the current cda and returns a key S to a fresh segment which contains the data.

If the current cda is not mounted, c is 4. If there is a permanent I/O error accessing the transfer disk, c is 5.

pw must match the password returned at the time the file was written onto the transfer disk; if not, c will be 3.

SB1, M, SB2, and other values of c are as described for the fresh segment creator (p2,fsc).

The format of the data in the fresh segment is as follows. The first 4 bytes contain the number of records in the file. The rest of the fresh segment contains the records, in order. Each record consists of 4 bytes telling the number of bytes of data in the record, followed by the bytes of data. This length does not include the length of the 4 byte length field.

GRCV(kt;==>X'60D';)

GRCV Control(x;==>0;) where x is not kt, sets the current cda to x.

This operation can have the effect of aborting any previous transfer which was incomplete. The current cda should only be increased (otherwise, aborted transfers could get un-aborted). The GRCV Control key is closely held by the operator. It is used to maintain synchrony between GRCV and GSEND.

{arcane}The operator can determine the value of x to use from the internals of the GSEND program or by doing the following CMS commands:

C>DDR

ENTER: >INPUT 134 3330 SCRATCH

ENTER: >TYPE 0 1 2 (H

CYL 000 HD 01 REC 002 COUNT ...

04096 1000 DATA LENGTH

00000 0000 ... ... ... ... 008ccccc ... 00032 0020 ... ...

The value of x to use is ccccc (hex).

GRCV Control(kt;==>X'70D';)

GRCV and GRCV Control are prompt.

If you have forgotten the password, you can discover it by the following CMS commands:

C>DDR

ENTER: >INPUT 134 3330 SCRATCH

.(where 134 is the device address of the transfer disk)

ENTER: >TYPE 0 1 4 (H

CYL 000 HD 01 REC 003 COUNT ...

04096 1000 DATA LENGTH

00000 0000 pppppppp ... ...

pppppppp is the password in hexadecimal.

The Factory GRCV is a one-hole factory whose .program is fetcher, whose .component 2 is GRCV, and whose alleged name is X'1060D'.

Note

Once a page is read by Gnosis, it may stay in Gnosis core until the pager purges it. The page must never be written into under Gnosis; that way, it won't matter if the disk it came from is dismounted (as it will be when the next file is transferred).

SRUP {Multiple File Segment Receiver and UnPacker}
SRUP is a mechanism to simplify transferring several files to a single user.

SRUP(pw;SB1,M,SB2 ==> c,data;K,,,NF) "Receive segments"

Where pw < 2**16. Receives a file by a call of the form GRCV(pw;SB1,M,SB2). The file is expected to be in the following format:

Multiple File Format

This is a file in format (p2,record-file-format). It consists of a sequence of (_subfile)s. A subfile is a sequence of records in the following format:
First record:
4 bytes of C'MULT' {to identify multiple file format}

4 bytes containing the number of subrecords in this subfile

0 to 132 bytes of anything, called the "file header".

Subsequent records are the subrecords of the subfile.

The CMS Exec MGSEND on the Gnosis tools disk will produce a file in Multiple File Format. It is self-documenting. The file headers produced have the 18-character CMS file identifier.

SRUP unpacks the file and puts the subrecords of each subfile in new fresh segments in the standard disk file transfer format (p2,record-file-format).

If SB2 runs out of space, the call may never return (because the SRUP back-end will crash).

The return code c indicates:

0 - There are one or more subfiles. K is the fresh segment containing the first subfile, data has its file header, and NF is a key to call to get the rest of the subfiles as follows:
NF(0; ==> c,data;K,,,NF) where c means:
0 - there is another subfile, K has it, data is its file header, and NF gets the rest.

4 - file is not in multiple file format. K has the file as returned by GRCV. NF(0;==>0;) returns all other storage used.

5 - there are no more subfiles

1 - SB1 not an official prompt space bank

2 - SB1 out of space

3 - password pw incorrect

4 - file is not in multiple file format. K has the file as returned by GRCV. NF(0;==>0;) returns all other storage used.

5 - there are no subfiles

6 - SB2 is out of space.

7 - the transfer disk range is not mounted

8 - there is a permanent disk error on the transfer range

SRUP(kt; ==> X'1C';)

SRUP is a factory with the same .hole as FGRCV (p2,fgrcv).

Server keys
TRANSPARTC
TRANSPARTC(0;SB,M,SB ==> c,TRANSPART,TRANSPARTQ)
Create a Participation Registration key. There can be a Participation Registration key for each server. This is to allow selective exposure of data to the insecurity of file transfer.

TRANSPARTQ
TRANSPARTQ(0,(PW) ==>c;SB,M,DIRECTORY)
TRANSPARTQ is used by the server to verify the password of a file sent to Gnosis from another server. PW is the password that indicates the destination of the file. If c is nonzero the password is invalid. If c is 0 then SB and M represent resources from which to build the file, and DIRECTORY is the key into which the name of the file is placed or from which the file is sent.

This key is used only for files that are transmitted as a result of a request from a remote server.

TYMNETSC
TYMNETSC(kt+5;SB,M,SB ==>kt+5;,,,CO)

CO(host;GETC,TRANSPARTQ ==> c;SERVER)

Create a server for Tymnet based file transfer. The GETC key determines the Tymnet username that the server connects to. HOST determines the Tymnet host for this server. TRANSPARTQ is the query key for the participation key for this server. TRANSPARTQ keys may be shared among many servers.

TYMNETSAC
TYMNETSAC(0;SIK,SOK,CCK)
This key is an application controller that creates Tymnet servers as a result of some host logging into Gnosis with a file transfer username. The server has access to a TRANSPARTQ key to resolve passwords. The circuit is the responsibility of the caller. If the circuit breaks the server dissolves. When the file transfer is complete, the server dissolves.

TRANDISKSC
TRANDISKSC(kt+5;SB,M,SB ==> kt+5;,,,CO)

CO(kt+5;SIK,SOK,CCK ==> kt+5;,,,CO)

CO(0;GRCV,TRANSPARTQ ==>c;SERVER)

Create a server for a transfer disk based file transfer. The GRCV key determines which transfer disk is used. SIK,SOK,CCK are keys to a ZAPPER module that represents a permanent circuit for the server. A CMS server on the same host will login to this circuit (LUD name chosen by administrator) to establish a control path for the file transfers. TRANSPARTQ is the query entry to the participation key for this server

SERVER
SERVER(0,(USERNAME,Remote-File-Name);KEY ==> c)
Send the file represented by KEY to the USERNAME and file name specified. A user would not have this key because it allows transmitting to any userid available to the server. C indicates the success of the transmission

SERVER(1,(USERNAME,[PW]Remote-File-Name);SB,M ==>c;SegmentKEY)
Receive the specified File from the specified USERNAME into a segment. SB and M are used to create the segment. C indicates the success of the transmission. If c is nonzero, all space allocated to receive the segment will have been returned to SB.

PW is part of the Remote-File-Name and may represent a read password to a mini disk for this USERNAME. The disk address will also have to be part of the Remote-File-Name.

SERVER(2,(USERNAME,[PW]Remote-File-Name);SB,M ==>c;RecordKEY)
Receive the specified File from the specified USERNAME into a record collection. SB and M are used to create the record collection. C indicates the success of the transmission. If c is nonzero, all space allocated to receive the record collection will have been returned to SB.

TRANSFERC
TRANSFERC(0,(USERNAME);SERVER ==> c;TRANSFER)
Create a user transfer request key for this server for a particular remote username. The SERVER key determines the host and the technology used for this transfer request key.

User keys
TRANSPART
TRANSPART(0,(PW);SB,M,DIRECTORY ==>c;TRANSPARTM)
This key is used to register with some server or group of servers a set of resources to be used for files that come into Gnosis from a remote host. If a remote host asks for a file from this group of resources, then the DIRECTORY key will be used to obtain the key to this file.

PW is a user selected 64 bit password. This password becomes the external name for this resource group. A remote server will specify this password on incoming files and for resolving file names for transfer from Gnosis. If the password is not unique, c will be nonzero.

There is one of these keys for each technology. There may be more.

TRANSPARTM is the only key that can be used to change the password associated with these resources, or the resources associated with this password. It is also the only key that can delete this password or resources from the participation registry.

TRANSPARTM
TRANSPARTM(0,(PASSWORD) ==> c)
Change the password associated with the resources controlled by this key. C is nonzero if the password is not unique, or if this key has been deleted.

TRANSPARTM(1;SB,M,DIRECTORY ==> c)
Change the resources associated with the password controlled by this key. C is nonzero if this key has ben deleted.

TRANSPARTM(2 ==> c)
Delete participation. C is zero if this is successful.

TRANSFER
TRANSFER(0,Remote-File-Name;KEY ==> c)
Send a file represented by KEY to the Remote-File-Name. The host, technology, and USERNAME are determined by the key. This key represents a weakening of the SERVER key in that the USERNAME is fixed. C indicates the success of this operation.

TRANSFER(1,[PW]Remote-File-Name;SB,M ==> c;KEY)
Receive the Remote-File-Name into the resources SB,M. Return the KEY if successful. If c is nonzero, then no resources are used.

PW is a remote password (like a mini-disk password) that is included as part of the file name. A disk address is also part of the file name.

TRANSFER(kt+6 ==> c;TRANSFER)
Produce a key just like this one except that it will not obey either KT+6 or KT+4.

This is currently documented only in the beginning of the file MACCVT ASSEMBLE. Sorry.