Endpoint Interface

Using the Endpoint Interface

If you specify the form

'template

or

'binary

, you also must specify a

target

slot in the input spec. The

target

slot is a frame used to define additional

information pertaining to the data form.

If your input form is

'template

, then you must set the

arglist

and

typelist

slots in the

target

frame. The

arglist

array contains placeholder data, which

is filled in with actual data when it is received, and the

typelist

array contains

the template's array of types.

If your input form is

'binary

, data is written directly into the binary object that

you specify in the

data

slot of the

target

frame. You can specify a binary object,

virtual binary object, or string. Note that the binary object must be the same size as
the received data; the system will not expand or shrink the object. For information
on virtual binary objects, see Chapter 11, "Data Storage and Retrieval."

The

offset

slot in the

target

frame allows you to specify an offset in the binary

object at which to write incoming data. For instance, if you want to write the
received data in consecutive blocks in a binary object that already exists, you must
set the

data

slot to the binary object, and set the

offset

slot to the byte offset at

which you want the new data to be written for each block.

Specifying Data Termination Conditions

23

For

'string

and

'bytes

data forms, you must indicate when the input

terminates by specifying a

termination

slot. You can terminate the input on

these conditions:

when a certain number of bytes has been received (set the

byteCount

slot)

when a specific set of characters in the input stream has been found (set the

endSequence

slot)

when the communication tool returns an end-of-packet indicator (set the

useEOP

slot)

Normally with the

'binary

data form, the input is terminated when the target

object fills up. However, you can also use the

termination

slot with binary data

to specify a byte count that causes the input to terminate after a certain number of
bytes has been received. This feature is useful when you want to provide user
feedback as a large binary object is being received. Set the

byteCount

slot in the

termination

frame, and, when the input terminates, repost the input spec with the

target.offset

slot offset by the value of the

termination.byteCount

slot.

If you want to receive data that ends with a particular sequence of data, define
that sequence in the

endSequence

slot in the

termination

frame. The

endSequence

slot allows you to terminate input based on a particular sequence

of incoming data called the termination sequence. You can specify a single