***************************************
*                                     *
*  Reproduction  or  translation  of  *
*  any  part of  this  documentation  *
*  without the written permission of  *
*  HoneySoft Ltd is unlawful.         *
*                                     *
*  An  Advanced User Guide  covering  *
*  all the information supplied here  *
*  and   more  is   available   from  *
*  HoneySoft Limited.                 *
*                                     *
*  Copyright (c) 1985 HoneySoft Ltd.  *
*                                     *
***************************************

     CIRKIT MODEM 1200 TO AMSTRAD
       CPC464/664/128 INTERFACE

RSX SPECIFICATION
_______________________________________

Command Overview

Several external commands are  provided
for  control of the RS232 link and  for
serial   character   transfer   on   an
individual, multiple or file basis.


Command Parameters

Most  commands  require  parameters  to
pass   information  between  them   and
BASIC,  the notation used  to  identify
the type of parameters is as follows:

The  angled  brackets  <>  indicate   a
parameter,  parameters being  separated
by   commas.   The  name   within   the
brackets is the name of the  parameter.
For example <parameter1>.

The square brackets [] indicate that  a
parameter   is  optional  and  may   be
omitted.  For example [<optional>].

Where an integer variable must be used,
the  parameter  is  suffixed  by  a   %
symbol.  For example <char>%.

Where the address of a variable must be
passed, an @ symbol is used before  the
parameter.  For example @<char>%.   The
variable  must  have  been  assigned  a
dummy value, otherwise BASIC will  flag
an    'improper    argument'     error.
Variables preceeded by an @ symbol  are
used  to  return  information  back  to
BASIC.

Parameters   may   be   integer    real
constants,  unless otherwise  indicated
by use of the % or @ symbols.


String Variables

Two  methods  of  passing  the   string
parameters  for <string> or  <filename>
are possible, depending on the  version
of Locomotive BASIC you are using.

If  you  have a CPC464  then  you  have
BASIC  1.0,  if you have  a  CPC664  or
CPC6128 then you have BASIC 1.1.

For BASIC 1.0 the parameter <string> or
<filename>  should be the address of  a
string,  as given by the symbol @,  for
example:

a$="this is a string for BASIC 1.0  and
1.1"
|WRITE, @a$

For  BASIC 1.1 either the above  method
may be used, or the string may be given
as a constant in the external command:

|WRITE, "this is a string for BASIC 1.1
only"


Command Summary

All the external commands available  to
BASIC  programs  are  summarised  here.
Full  descriptions of each command  are
given in the next section.

Note  that the bar symbol '|'  used  as
the  first character for  all  external
commands  may be obtained  by  pressing
[SHIFT]@.


RS232 Control

These   commands   are   provided   for
managing  the overall operation of  one
of the RS232 channels.

|SETUP, <baud> [,<databits>  [,<parity>
[,<stopbits> ]]]
|ERROR, @<error>%
|TIMEOUT, <time>
|CARRIER, @<char>%


Single Character Transfer

These   commands   send   and   receive
individual characters.

|PUT, <char>
|WRITE, @<char>%
|GET, @<char>%
|READ, @<char>%


Mulitple Character Transfer

These commands send and receive  blocks
of up to 255 characters.

|NULL, <nulls>
|READ, <string>
|WRITE, <string>
|COUNT, @<count>%


File Transfer

These commands are provided to transfer
data files or programs from either tape
or disc.

|FILETYPE, <type>
|SEND, <filename>
|RECEIVE, <filename>


Terminal Emulation

Configures the Amstrad for operation as
a 'dumb' terminal.

|TERMINAL, <mode>


Prestel Commands

There  are  various commands  to  allow
acess  to the the features  of  Prestel
from  within  a  BASIC  program.    The
commands are:


|CLEAR
|DISPLAY,  [<mode>  [,<col1>   [,<col2>
[,<col3>]]]]
|PRESTEL,  [<mode>  [,<col1>   [,<col2>
[,<col3>]]]]
|LOADPAGE, <filename>
|SAVEPAGE, <filename>


Loading the Commands

There  are two files on side A  of  the
cassette, the first USER.BIN holds  the
code  for the user software to  control
the   interface.    The   second   file
PRES.BIN   contains  all  the   Prestel
specific commands.

Each  file may be  used  independently,
but there are some restrictions to bear
in mind.

The PRESTEL code has been assembled  to
run  at 05000h and should therefore  be
loaded  only  at this address.  To  run
this   code   the   following   command
sequence should be used:

MEMORY &4FFF [ENTER]
LOAD "PRES.BIN",&5000 [ENTER]
CALL &5000 [ENTER]

The RSXs will then be logged on and may
be accessed directly. The code requires
028C0h  bytes,  and so the  area  above
078C0h is free for other programs.

The   user  to  user  code   is   fully
relocateable,  and  so  may  be  loaded
anywhere in memory provided that  there
is at least 014B0h bytes available. For
example  to load it in  directly  below
HIMEM,  the following command  sequence
should be used:

TOP=HIMEM-&14B0:MEMORY TOP-1 [ENTER]
LOAD "USER.BIN",TOP [ENTER]
CALL TOP [ENTER]

The RSXs will then be loaded at the top
of  memory and logged on. Note that  if
the code is loaded in at the same  time
as the PRESTEL, then it must either  be
loaded above 078C0h, or below 05000h.


Command Descriptions

|SETUP

Use

To  configure the interface  for  RS232
operation  by  setting the  baud  rate,
stop bits, data bits, and parity.

Syntax

|SETUP, <baud> [,<databits>  [,<parity>
[,<stopbits> ]]]

Operation

The  command  remembers  the   previous
values of parameters and these will  be
used if parameters are omitted.  If  no
previous parameters have been specified
then  the  following defaults  will  be
assumed:

  <baud>        = 1200/75 baud
  <databits>    = 7
  <parity>      = 2  (even)
  <stopbits>    = 1

Each parameter given is checked and  if
correct  replaces its  previous  value,
only   if  all  given  parameters   are
correct is the channel then setup.   At
the first error encountered the command
will  be aborted and the  channel  will
not  be  setup.   Before  opening   the
channel  the command will wait for  any
previous  characters to be  transmitted
(all  sent) using the current time  out
limit.   If  the  time  out  limit   is
exceeded  then the command  will  abort
with  a  time out  error.   Errors  are
reported by |ERROR.

The baudrate chosen with <baud> may  be
selected from one of the following:

0 = 1200 rx,   75 tx, full duplex
1 = 300  rx,  300 tx, full duplex
2 = 1200 rx, 1200 tx, half duplex

The   integer   parameter    <databits>
selects  the  required number  of  data
bits for each character to be sent  and
received.  <databits> should be in  the
range 5 to 8.

The  type  of parity to be  applied  to
transmitted,  and checked  on  received
characters, may be set with the integer
parameter  <parity>.   For  transmitted
characters,  the  extra parity  bit  is
sent after the data bits.

<parity> = 0, No parity
         = 1, ODD parity
         = 2, EVEN parity

The   integer   parameter    <stopbits>
specifies the number of stop bits to be
sent  after the data bits and  optional
parity bit.

<stopbits> = 0, 1 stop bit sent
           = 1, 1.5 stop bits sent
           = 2, 2 stop bits sent


Examples

1] Setup the interface for 300/300 baud
operation, using the existing  defaults
for databits, parity and stopbits:
                 |SETUP, 1

3]  Setup the interface for use with  a
modem on British Telecom Gold:
                 |SETUP,0,7,2,1

Notes

Full  duplex - Data can be  transmitted
both ways, simultaneously

Half   duplex  -  Data  can   only   be
transmitted  in  one  direction  at   a
time.

When   half   duplex  is   being   used
(1200/1200) the mute output is set true
(logic  1) when ever a character  needs
to be received.  The mute output is set
false (logic 0) when a character is  to
be transmitted.
_______________________________________

|ERROR

Use

Return the error code for the last used
command.

Syntax

|ERROR, @<error>%

Operation

The  parameter  <error>%  should  be  a
previously  declared integer  variable,
into  which  the error code  is  to  be
returned.  If the parameter <error>% is
omitted then the command is ignored.

Once  any  <error> has  been  read  the
error code is reset to 0.

The error codes and their meanings  are
summarised below.

CODE        INTERPRETATION
  0      No error occurred
  1      Too few parameters given
  2      Too many parameters given
  4      Time out occurred
  5      Invalid parameter encountered
  6      Line break received
  7      Framing error detected
  8      Receiver Overrun detected
  9      Received parity error
  11     Invalid baud rate specified
  13     Invalid number of data bits
  14     Invalid parity specified
  15     Invalid number of stop bits
  16     Unable to open file
  17     Unable to close file
  18     Unable to write file
  19     Unable to read file
  20     Received file checksum error

Example

Get    the    latest    error     code:
|ERROR,@error%
_______________________________________

|TIMEOUT

Use

To set the time out limit.  The default
time  out count is 1000,  corresponding
to  1 second.  This is ideal  for  most
applications, however  should the  need
arise  it  can  be  changed  with  this
command.

Syntax

|TIMEOUT, <time>

Operation

The integer parameter <time>  specifies
the time limit, in units of 1mS,  after
which a command will give up trying  to
send or receive a character.

<time>  should  be in the  range  0  to
65535
If  <time> =  0, then the time  out  is
set to zero
If <time> =  65535 (-1), then the  time
out is infinite

Examples

1]       Disable      the       timeout
|TIMEOUT,-1

2]   Set  the  timeout  to   1   second
|TIMEOUT,1000
_______________________________________

|CARRIER

Use

To  return  the status of  the  carrier
detect input

Syntax

|CARRIER, @<char>%

Operation

The  parameter  <char>%  should  be   a
predeclared   integer  variable,   into
which the status of the carrier  detect
input is to be returned.

Carrier detected: <char>% = -1  (true)
Carrier fail: <char>% =  0  (false)

Example

Test for the carrier: |CARRIER, @char%

Notes

Received  characters  will  be  ignored
unless  the  carrier  detect  input  is
true.
_______________________________________

|PUT

Use

To  transmit  a single byte  using  the
current setup and timeout count.

Syntax

|PUT, <char>

Operation

The parameter <char> is an integer byte
in  the  range  0..255  to  be  output.
<char> is taken MOD 256 to force it  to
be  in the range 0..255.   The  timeout
count set with the command |TIMEOUT  is
used.

Examples

1] Send the character 'A' to the RS232
            |PUT,ASC("A")

2] Send a carriage return
            |PUT,13

Notes

If  half  duplex operation is  in  use,
then the mute output will be set  false
(logic  0)  before  the  character   is
transmitted.
_______________________________________

|WRITE

Use

Transmit a string or byte.

Syntax

       |WRITE, <string>
or     |WRITE, @<char>%

Operation

Two   types   of   parameter   may   be
specified, either a string <string>  or
an integer <char>%.

If  a  string is given,  then  <string>
should be a reference to a  predeclared
string  variable.  Characters from  the
string  will be transmitted  until  the
end of the string is reached or until a
time  out occurs. The actual number  of
characters transmitted can be  obtained
by using |COUNT.

If a integer is given by using <char>%,
then an equivalent |PUT is performed.

The current time out is used.

Examples

1] Write out a string under version 1.0
(CPC464)   or   1.1   (CPC664)       of
Locomotive BASIC.

10  a$="send  this string  out  to  the
RS232"
20 |WRITE,@a$

2] Output a string under version 1.1 of
BASIC (CPC664):
|WRITE,"send  this  string out  to  the
RS232"

3] Output a character: |WRITE,@char%

Notes

Individual characters are sent  similar
to |PUT.
_______________________________________

|GET

Use

To  receive  a  single  byte  from  the
RS232.

Syntax

|GET, @<char>%

Operation

The  parameter  <char>%  should  be   a
previously  declared integer  variable,
into which the received character is to
be returned.

The  received character will always  be
in the range 0.255.

The timeout count set with the  command
|TIMEOUT is used.

No  characters will be received  unless
the carrier detect input is true.

Examples

1]  Receive  a  single  byte  from  the
RS232:             |GET,@char%

2] Receive a byte: |GET,@char%

Notes

If  half duplex is in  operation,  then
the mute output will be set true (logic
1)  before  attempting  to  receive   a
character.   Any  characters   received
before the mute output was set will  be
discarded.

Received  characters  will  be  ignored
unless  the  carrier  detect  input  is
true.
_______________________________________

|READ

Use

Receive  a  string  or  byte  from  the
serial interface.

Syntax

          |READ, <string>
or        |READ, @<char>%

Operation

Two   types   of   parameter   may   be
specified, either a string <string>  or
an integer <char>%.

If  a  string is given,  then  <string>
should be the address of a  predeclared
string  variable.  Characters  will  be
read   into   the   string   upto   the
predeclared  length of the  string,  or
until  a carriage return  is  received.
The  number of characters  successfully
input can be obtained by using |COUNT.

If a integer is given by using <char>%,
then an equivalent |GET is performed.

The current time out is used.

Examples

1]  Input  a string under  version  1.0
(CPC464)    or    1.1    (CPC664)    of
Locomotive BASIC
10 a$="replace this with received data"
20 |READ,@a$

2] Input a character:  |READ,@char%

Notes

The terminating carriage return is  not
stored as part of a string.  Individual
characters  are  recieved  similar   to
|GET.
_______________________________________

|NULL

Use

Transmit  an  integer number  of  ASCII
NULL (00H) characters.

Syntax

|NULL, <nulls>

Operation

The  integer parameter <nulls>  in  the
range  0..255 specifies the  number  of
ASCII  NULL  characters  (00H)  to   be
transmitted.

The parameter <nulls> is truncated  MOD
256,  a  value of 0  will  prevent  any
nulls from being sent.

The command will wait for any remaining
characters  to be sent, before  sending
the  nulls.  The command may  abort  if
the  time out limit is  reached  whilst
waiting    for   characters    to    be
transmitted.

The  number of nulls successfully  sent
can be determined by using |COUNT.

Examples

1] Send 10 nulls to the RS232: |NULL,10
2] Send 255 nulls: |NULL,255

Notes

Null  characters are sent in  the  same
manner as |PUT.
_______________________________________

|COUNT

Use

Obtain   the   number   of   characters
transferred  by the last |NULL,  |READ,
|WRITE, |SEND, or |RECEIVE command.

Syntax

|COUNT, @<count>%

Operation

The  parameter  <count>%  should  be  a
predeclared integer variable into which
the count will be returned.  The  count
may  be in the range 0 to  65535.   The
count is reset to 0 when read.

If   an  error  occurred   during   the
operation   of  either  |NULL,   |READ,
|WRITE,  |SEND,  or |RECEIVE  then  the
count returned will give the number  of
characters   sucessfully    transferred
before the error.

Example

1] Get the count for the last command
            |COUNT,@count%
_______________________________________

|FILETYPE

Use

To set the type of file transfer to  be
used by |SEND and |RECEIVE.

Syntax

|FILETYPE, <type>

Operation

The  integer parameter <type> may  take
one of three values:

0 = ASCII file
1 = ASCII file using ARQ protocol
2 = ASCII file using XON/ XOFF

The default <type> is 0, or ASCII

If the file type is set to ASCII,  then
the  file  to be  transferred  will  be
treated   as   an  ASCII   text   file,
terminated  by  the ASCII end  of  file
character     [CTRL]Z,    01AH.     The
transmitter  will respond to  XON/XOFF,
but no handshaking is activated on  the
receiver.

The ASCII file using XON/XOFF, utilises
this  type of handshaking for both  the
receiver and the transmitter and so may
be  used for file transfer between  the
interface   and  a  database  such   as
Telecom Gold.

The   ARQ  filetype  uses   a   special
transfer  protocol that  transmits  the
data  in  blocks. Each  block  is  then
checked  for  errors,  and  if  one  is
detected then the receiver asks for the
block   to   be   retransmitted.   This
overcomes the problems with errors that
are often introduced when  transferring
data  via  a  modem  due  to  the   low
reliabilty of public telephone lines.

This filetype is therefore provided for
data   transfer  between   two   CIRKIT
interfaces.

Examples

1] Set file type to ASCII: |FILETYPE,0
2] Set the file type to ARQ protocol
            |FILETYPE,1
_______________________________________

|SEND

Use

Send a file for receiving by  |RECEIVE.
The type of file sent is determined  by
|FILETYPE.

Syntax

|SEND, <filename>

Operation

The string parameter <filename> is  the
name of the file to be sent and  should
be a reference to a predeclared  string
variable.

The  file referenced by  <filename>  is
opened using the current filing  system
(i.e. either tape or disc) and sent out
as  an ASCII or ARQ file  according  to
the file type set with |FILETYPE.

The  number of characters  successfully
sent  before any error can be  obtained
by using |COUNT.

The current time-out count is used.

Examples

1] Send a file under version 1.0 or 1.1
of BASIC to the RS232:
            a$="test"
            |SEND,@a$

2]  Send  a file under version  1.1  of
BASIC.
            |SEND,"test"

Notes

Individual  characters are sent in  the
same manner as |PUT.

The  time  out  should be  as  long  as
possible  to prevent the transfer  from
aborting  due  to  long  delays   while
accessing the tape or disc.

For  ARQ file transfer,  the  interface
must be set up for 8 data bits with  no
parity.
_______________________________________

|RECEIVE

Use

Receive   a  file  sent  by  |SEND   or
equivalent.    The  type  of  file   to
receive is determined by |FILETYPE.

Syntax

|RECEIVE, <filename>

Operation

The string parameter <filename> is  the
name  of  the file to be  received  and
should be a reference to a  predeclared
string variable.

The  file referenced by  <filename>  is
opened using the current filing  system
(i.e. either tape or disc) and received
characters  are  stored in it.  If  the
file was sent using ARQ then a checksum
is  used  to determine if  errors  have
been received in the file.  At the  end
of transmission or on the occurrence of
any error the file is closed.

The  number of characters  successfully
stored before any error can be obtained
by using |COUNT.

Examples

1] Receive a file under version 1.0  or
1.1   of   BASIC   from   the    RS232:
a$="test"
            |RECEIVE,@a$

2] Receive a file under version 1.1  of
BASIC.
            |RECEIVE,"test"

Notes

Individual  characters are received  in
the same manner as |GET.

The  time  out  should be  as  long  as
possible  to prevent the transfer  from
aborting  due  to  long  delays   while
accessing the tape or disc.

For  ARQ file transfer,  the  interface
must be set up for 8 data bits with  no
parity.
_______________________________________

|TERMINAL

Use

To  convert  the Amstrad into  a  'dumb
terminal' for use with another computer
or modem.

Syntax

|TERMINAL, <mode>

Operation

There     are     various      terminal
configuration  modes  to  choose  from,
these  are  selected  by  the   integer
parameter  <mode>.  Four  bits   within
<mode>  select  options  to   configure
operation.  The bits used are:

Bit 0 = 0, ECHO:
No  local echo of characters  typed  at
the Amstrad keyboard.
Bit 0 = 1, NO ECHO:
Characters   typed   at   the   Amstrad
keyboard  are  locally  echoed  to  the
screen.

Bit 1 = 0, MONITOR OFF:
Control codes below ASCII 20H behave as
expected.
Bit 1 = 1, MONITOR ON:
Control  codes  below  ASCII  20H   are
displayed  as  graphics  symbols.   The
symbols  may be redefined as  necessary
before entering terminal mode.

Bit 2 = 0, NO Auto Line Feed:
Received  carriage returns are  treated
normally.  Bit 2 = 1, Enable Auto  Line
Feed:
A line feed is displayed locally  after
a carriage return is received.

Bit 3 = 0, OBEY ALL control codes:
    All control codes received will  be
sent to the screen.
Bit  3 = 1, OBEY only selected  control
codes:
    This  prevents spuriously  received
characters  from changing screen  mode,
ink   colours   and   other   desirable
effects.  The codes obeyed are:

06H, 07H, 08H, 09H, 0AH, 0BH, 0CH, 0DH,
10H, 1EH

The  screen is not cleared, the  cursor
is turned on and enabled.  There is  no
timeout,  the command finishes  when  a
key on the Amstrad giving the character
code  ASCII 0FCH is pressed.   This  is
normally given by [CTRL] [ESC].

Examples

1] Terminal with no echo: |TERMINAL,0
2] Terminal with echo & auto line feed:
|TERMINAL,5

Notes

Characters with received parity  errors
are  displayed on screen by  an  upside
down  question  mark  character,  ASCII
0AEH.

If  half duplex mode is  in  operation,
the  mute  output will only be  be  set
false (logic 0) when a character is  to
be transmitted.
_______________________________________

|CLEAR

Use

To  clear the Prestel frame  buffer  to
spaces.

Syntax

|CLEAR

Operation

No parameters are required.

If   any  parameters  are  given,   the
command is ignored.

The  memory  used  to  hold  the   last
received  page from Prestel is  cleared
to spaces, erasing its contents.

Notes

This  command  is  independent  of  the
Prestel screen modes.
_______________________________________

|DISPLAY

Use

To  redisplay the current Prestel  page
in either screen mode.

Syntax

|DISPLAY,   [<mode>  [,<col1>  [,<col2>
[,<col3>]]]]

Operation

If no parameters are given the page  is
redisplayed  in  Prestel mode  0.   The
parameter <mode> should be either 0  or
1.

For  mode 0 the ink colours are set  up
accordingly.

For  mode  1,  up  to  three   optional
colours may be specified in addition to
the  black background. If  no  optional
colours   are  specified  the   current
settings are used.

Examples

1]  Redisplay  the  page  in  mode   0:
|DISPLAY

2]  Redisplay  the  page  in  mode   1:
|DISPLAY,1,2,6,18

Notes

The recommended colours for Mode 1  are
2, 6 and 18.

The  previous  ink  colours,  nor   the
screen  mode,  are restored  after  the
page has been displayed.

Ink  colours specified for mode  0  are
ignored.

For mode 1 the ink colours are stippled
to  achieve  the effect  of  more  than
three colours.
_______________________________________

|PRESTEL

Use

To  enter the main Prestel terminal  in
one of two screen modes.

Syntax

|PRESTEL,   [<mode>  [,<col1>  [,<col2>
[,<col3>]]]]

Operation

If no parameters are given the page  is
redisplayed  in  Prestel mode  0.   The
parameter <mode> should be either 0  or
1.

For Prestel mode 0 the ink colours  are
set up accordingly.

For  mode  1,  up  to  three   optional
colours may be specified in addition to
the  black background. If  no  optional
colours   are  specified  the   current
settings are used.

The  [COPY]  key is used  as  a  reveal
toggle.

If the command |SETUP cannot be  found,
because the user RSX code has not  been
loaded, then the interface will be  set
up for 7 data bits, 1200/75 baud,  even
parity.   Otherwise the  settings  from
|SETUP will be used.

Examples

Prestel mode 0:    |PRESTEL
Prestel mode 1:    |PRESTEL, 1,2,6,18

Notes

The  ink  colours and screen  mode  are
restored  to their values prior to  the
|PRESTEL command.

The recommended colours for Mode 1  are
2, 6 and 18.

Ink  colours specified for mode  0  are
ignored.

For mode 1 the ink colours are stippled
to  achieve  the effect  of  more  than
three colours.

Prestel  mode  is  exited  when  a  key
returning  ASCII 0FCH is pressed,  this
is normally given by [CTRL] [ESC].
_______________________________________

|LOADPAGE

Use

To  reload  a Prestel page  saved  with
|SAVEPAGE.

Syntax

|LOADPAGE, <filename>

Operation

The  parameter <filename> should  be  a
reference to a string variable, set  to
the name of the file.

Data  is read from the file  using  the
currently active filing system,  either
TAPE  or AMSDOS and will overwrite  any
existing page.

The   page  can  be  redisplayed   with
|DISPLAY.

Examples

1] Load the file "page1":
       a$="page1":  |LOADPAGE, @a$


2] Load a page under BASIC 1.1:
       |LOADPAGE, "page1"

Notes

The  file is loaded using  the  current
filing system, either TAPE or AMSDOS.
_______________________________________

|SAVEPAGE

Use

To  save  the contents of  the  Prestel
frame buffer to a data file.

Syntax

|SAVEPAGE, <filename>

Operation

The  parameter <filename> should  be  a
reference to a string variable, set  to
the name of the file.

Data  is written to the file using  the
currently active filing system,  either
TAPE or AMSDOS.

Examples

1]  Save  the page to the  file  called
"page1":
            a$="page1": |SAVEPAGE,@a$

2] Save the page under BASIC 1.1:
            |SAVEPAGE, "PAGE1"

Notes

The file is saved in BINARY format.  If
AMSDOS  is  in use then the  file  will
have  a .BIN extension added to  it  if
none is specified.
_______________________________________