Endpoint Interface

About the Endpoint Interface

If the input operation terminates normally--that is, the

InputScript

method is

called--the system automatically reposts the input spec for you to receive
additional input. Of course, you can alter this process if you want to.

Data Forms

23

All NewtonScript data needs to be transformed whenever it is sent to or received
from a foreign environment. That foreign environment may be a server or host
computer at the other end of the connection, or it may even be the communication
tool that's processing the configuration options you've passed to it. Typically,
communication tools expect C-type option data.

Whether you're sending, receiving, or using data to set endpoint options, you can
tag the data with a data form. A data form is a symbol that describes the transfor-
mations that need to take place when data is exchanged with other environments.
When you send data or set endpoint options, the data form defines how to convert
the data from its NewtonScript format. When you receive data or get endpoint
options, the data form defines the type of data expected.

Data forms are used in output specs, input specs, and endpoint option frames. The
data form is defined by a slot named

form

in these frames. If you don't define the

data form in a particular case, a default data form is used, depending on the type of
operation and the type of data being handled.

Note that when sending data, you can take advantage of the default data forms by
not explicitly specifying a data form. Because NewtonScript objects have type
information embedded in their values, the system can select appropriate default
data forms for different kinds of data being sent. For example, if you send string
data and don't specify the data form, the

'string

data form is used by default.

The symbols you use to indicate data forms are

'char

,

'number

,

'string

,

'bytes

,

'binary

,

'template

, and

'frame

. Each is best suited to certain data

and operations.:

For simple scalar values, use

'char

for characters and

'number

for integers.

For semi-aggregate forms of these kinds of data, use

'string

for a

concatenation of characters plus a terminating byte, and use

'bytes

for an

array of bytes.

For binary data, use

'binary

. This is the fastest option for sending and

receiving, since the data processing is minimal.

For more complex data, there are two aggregate data forms. You may want to
use the

'template

form if you're communicating with a remote procedure call

service that expects C-type data and that follows the exact same marshalling
restrictions the Newton does. The

'frame

form is convenient if you're

exchanging frames with another Newton.