TRANSFER

 

The TRANSFER statement sets up unformatted data transfers between memory and a device (Serial, GPIB, or file). The data transfer normally occurs in the "background." That is, the BASIC program continues to run in the "foreground" simultaneously with the background transfer. Optionally, the TRANSFER statement can wait until the transfer is complete before continuing. The syntax is:

 

TRANSFER @source-io-path TO @dest-io-path [; [term-list] [,] [EOR(term-list)] [,] [type]  ]

 

Use ASSIGN to initialize the source and destination I/O paths. The optional commas are only needed when items occur on both sides of the comma.

 

 

An outbound transfer has the form:

TRANSFER @Buff TO @Non_buff

If another outbound TRANSFER statement is executed while an outbound TRANSFER is occurring, HTBasic waits for completion of the first before starting the second. Any EOT/EOR events caused by the first transfer will then be logged and may be serviced before the next program line.

 

An inbound transfer has the form:

TRANSFER @Non_buff TO @Buff

If another inbound TRANSFER statement is executed while an inbound TRANSFER is occurring, HTBasic waits for completion of the first before starting the second. Any EOT/EOR events caused by the first transfer will then be logged and may be serviced before the next program line.

The transfer operation must be between a buffer (memory) and a device. A buffer must be declared as the source for an outbound transfer, or as the destination of an inbound transfer. One buffer can simultaneously be used for an outbound transfer and an inbound transfer. A transfer directly between two devices is not supported.

 

Buffers may be unnamed or named. An unnamed buffer is created, assigned an I/O path, and given its size by the ASSIGN statement. A named buffer is a previously declared REAL, INTEGER, LONG or COMPLEX array, or a string scalar (declared in a COM, STATIC, DIM, INTEGER, LONG, REAL, or COMPLEX statement) that has been ASSIGNed to an I/O path. Unnamed buffers are usually preferred because the size can be as large as available memory and no side-affects are possible by accessing the buffer through its variable name.

 

Buffers are circular; each buffer has a fill and empty pointer as well as a count. The fill pointer is used by an inbound transfer to identify the next location for data to be stored (inserted). The empty pointer is used by an outbound transfer and points to the next location for data to be output (removed). A value of one for either pointer means the first byte of the buffer. When the fill and empty pointers have the same value, the count can be examined to determine whether the buffer is empty or full.

 

The I/O path assigned to the buffer is called the buffer-I/O path. The I/O path assigned to the device is called the non-buffer-I/O path. The buffer should be accessed only with the buffer-I/O path. The count, fill, and empty pointers can be examined using STATUS on the buffer-I/O path. OUTPUT @buf or an inbound transfer are used to place data into a buffer. ENTER @buf or an outbound transfer are used to read and remove data from a buffer. The variable name of a named buffer should generally not be used to access the data in the buffer since the data in the buffer is unformatted and may even have the wrong byte order.

 

The type of the transfer can be specified as CONT, WAIT, or left unspecified.

 

If WAIT is specified, the transfer executes in foreground mode. Program execution does not proceed beyond the TRANSFER statement until the transfer terminates. If an error occurs, it is reported with the line number of the TRANSFER statement. If WAIT is not specified, execution continues past the TRANSFER statement and the transfer takes place in the background. Then if an error occurs, the error is not reported until the non-buffer-I/O path is referenced. The error line reported is not that of the TRANSFER, but of the statement where the non-buffer-I/O path was referenced.

 

If CONT is specified, TRANSFER executes continuously. For an inbound transfer, execution pauses when the buffer is full and continues when space is available in the buffer. For an outbound transfer, execution pauses when the buffer is empty and continues when the buffer has data available. If CONT is not specified, the end-of-transfer occurs when an outbound transfer empties the buffer or an in-bound transfer fills the buffer. Or if a termination method has been specified as explained below, the transfer terminates when the condition occurs.

 

Both WAIT and CONT can be specified together if a transfer is already active for the buffer in the opposite direction. The transfer will be continuous, but will run in the foreground.

 

If neither WAIT nor CONT is specified, the transfer occurs in the background. The end-of-transfer occurs when an outbound transfer empties the buffer or an in-bound transfer fills the buffer. Or if a termination method has been specified as explained below, the transfer terminates when the condition occurs.

 

DMA (direct memory access) is the fastest method and will be used automatically if possible. A DMA channel must be available, the interface must have the necessary hardware, and DELIM can not have been specified. Otherwise, interrupts are used.

 

One or more of the following conditions can be used:

COUNT Bytes

DELIM Character

END

RECORDS Number

If COUNT is specified, the transfer terminates after the specified number of bytes has been transferred.

 

If DELIM is specified for an inbound transfer, then the transfer is terminated after the specified character is detected. DELIM is not allowed with outbound transfers. If the delimiter string is zero length, delimiter checking is disabled. DELIM prevents DMA from being used; interrupts will be used instead.

 

If END is specified for an inbound transfer, the transfer terminates when the device dependent signal is received. On the IEEE-488 interface, END is the EOI signal. When an inbound transfer is terminated in this way, bit 3 of register 10 is set. For an outbound transfer, END does not specify a termination condition, but rather specifies that the device dependent signal (EOI) is sent with the last byte sent.

 

If RECORDS is specified, the transfer terminates when the specified number of records has been transferred. An EOR(term-list) must be specified, defining what will be considered a record for the purpose of this particular transfer. For inbound transfers the legal end-of-record termination conditions are COUNT, DELIM, and END, or some combination of these three. For outbound transfers only COUNT can be used to define a record, although END can be used to specify that the device dependent ignal (EOI) is sent with the last byte of each record.

 

ON EOR and ON EOT can be used to generate an event when an end-of-record or end-of-transfer occurs.

 

WAIT FOR EOR and WAIT FOR EOT can be used to stop further statement execution until an end-of-record or end-of-transfer occurs.

 

To terminate a CONT (continuous mode) outbound transfer without leaving data in the buffer, use the following statements:

 

 

ABORTIO or RESET will prematurely terminate a transfer and free the computer. The following will also cause the computer to "hang" until all transfers complete: GET, LOAD, RETURN, STOP, SUBEND, SUBEXIT, or modifying a program line.