Difference between revisions of "Immediate operations"

From BeebWiki
Jump to: navigation, search
m (Added category.)
m (Minor typos and clarifications.)
 
Line 125: Line 125:
  
 
Although interrupts are disabled in the remote machine, they should be
 
Although interrupts are disabled in the remote machine, they should be
enabled if the routine is going to take much longer than 1mS to complete.
+
enabled if the routine is going to take much longer than 1ms to complete.
  
 
The maximum size of the argument block is 128 bytes.
 
The maximum size of the argument block is 128 bytes.
Line 202: Line 202:
 
This call inserts a byte into a remote machine's keyboard buffer and is used
 
This call inserts a byte into a remote machine's keyboard buffer and is used
 
by the 'send a line of text' command (OSWORD A=&14 Control byte=1), which
 
by the 'send a line of text' command (OSWORD A=&14 Control byte=1), which
should usually be used in preference to this calL See section 10.15 for
+
should usually be used in preference to this call See section 10.15 for
 
information on polling the transmit for success.
 
information on polling the transmit for success.
  
Line 486: Line 486:
 
are shown below:
 
are shown below:
  
Byte 1
+
Byte 0
 
 
 
This is defined by manufacturers and is intended to indicate the hardware
 
This is defined by manufacturers and is intended to indicate the hardware
 
design of the machine. The following are currently defined:
 
design of the machine. The following are currently defined:
Line 530: Line 529:
 
Other values Reserved
 
Other values Reserved
  
Byte 2
+
Byte 1
 
 
 
This byte indicates the manufacturer. The following are currently defined:
 
This byte indicates the manufacturer. The following are currently defined:
  
 
     Value        Manufacturer
 
     Value        Manufacturer
 
 
       00        Acorn
 
       00        Acorn
 
       01        Torch
 
       01        Torch
Line 543: Line 540:
 
       FF        SJ Research
 
       FF        SJ Research
  
Bytes 3 & 4
+
Bytes 2 & 3
 
 
 
These contain the low and high bytes of the software release version in
 
These contain the low and high bytes of the software release version in
packed Binary Coded Decimal, byte 2 contains the version number and byte 4
+
packed Binary Coded Decimal, byte 2 contains the version number and byte 3
 
the release. The easiest way to display packed BCD is to print it as if it
 
the release. The easiest way to display packed BCD is to print it as if it
 
were hexadecimal.
 
were hexadecimal.
 +
 +
Releases &00, &01 and &02 were development versions. Release &03 is 8-bit NFS
 +
with no local buffering (eg, BBC, Electron), release &04 is 8-bit NFS with
 +
local buffering (eg ANFS), release &05 is 32-bit NFS (eg RISC OS).
 +
 +
Examples:
 +
byte 0,1: &0001 Acorn BBC
 +
byte 2,3: &0360 Version 3.60
 
</pre>
 
</pre>
  

Latest revision as of 11:53, 28 October 2022

10.9 Peek                                  OSWORD A=&10 (Control byte=&81)
==========================================================================

General description
-------------------
This returns a block of memory from a remote machine into the local machine.  
See section 10.15 for information on polling the transmit for success.

On entry
--------
A=&10
YX point to the address of the control block shown below:

         0 +-----------------------------+
           |            &81              |
         1 +-----------------------------+
           |             0               |
         2 +-----------------------------+
           |       Remote station        |
           |  (station number, network)  |
         4 +-----------------------------+
           |     Pointer to start of     |
           |        local buffer         |
         8 +-----------------------------+
           |      Pointer to end of      |
           |        local buffer         |
        12 +-----------------------------+
           |     Pointer to start of     |
           |   remote machine's buffer   |
        16 +-----------------------------+

On exit
-------
A,X,Y undefined

         0 +-----------------------------+
           |          Modified           |
         1 +-----------------------------+
           |          Unchanged          |
        16 +-----------------------------+


Poke                                       OSWORD A=&10 (Control byte=&82)
==========================================================================

General description
-------------------
This sends a block of memory from the local machine into the remote machine.  
See section 10.15 for information on polling the transmit for success.

On entry
--------
A=&10
YX point to the address of the control block shown below:

         0 +-----------------------------+
           |            &82              |
         1 +-----------------------------+
           |             0               |
         2 +-----------------------------+
           |       Remote station        |
           |  (station number, network)  |
         4 +-----------------------------+
           |     Pointer to start of     |
           |        local buffer         |
         8 +-----------------------------+
           |      Pointer to end of      |
           |        local buffer         |
        12 +-----------------------------+
           |     Pointer to start of     |
           |   remote machine's buffer   |
        16 +-----------------------------+

On exit
-------
A,X,Y undefined

         0 +-----------------------------+
           |          Modified           |
         1 +-----------------------------+
           |          Unchanged          |
        16 +-----------------------------+


Remote JSR                                 OSWORD A=&10 (Control byte=&83)
==========================================================================

General description
-------------------
This call sends an argument block to a remote machine, then jumps to a
location in the remote machine. See section 10.15 for information on polling
the transmit for success.

On entry
--------
A=&10
YX point to the address of the control block shown below:

         0 +-----------------------------+
           |            &83              |
         1 +-----------------------------+
           |             0               |
         2 +-----------------------------+
           |       Remote station        |
           |  (station number, network)  |
         4 +-----------------------------+
           |     Pointer to start of     |
           | local buffer for arguments  |
         8 +-----------------------------+
           |      Pointer to end of      |
           | local buffer for arguments  |
        12 +-----------------------------+
           |  Address to CALL in remote  |
           |           machine           |
        16 +-----------------------------+

After this call the remote machine is protected against procedure calls and
OS procedure calls until the parameter block is read. The program in the
remote machine must read the parameter block (OSWORD A=&12) before exiting
(with a RTS), otherwise the remote machine will remain protected. If the
remote machine is a BBC microcomputer then the address to call must be in
the I/O processor.

Although interrupts are disabled in the remote machine, they should be
enabled if the routine is going to take much longer than 1ms to complete.

The maximum size of the argument block is 128 bytes.

On exit
-------
A,X,Y undefined

         0 +-----------------------------+
           |          Modified           |
         1 +-----------------------------+
           |          Unchanged          |
        16 +-----------------------------+


Remote procedure                           OSWORD A=&10 (Control byte=&84)
==========================================================================

General description
-------------------
This passes a block of memory to a remote machine and causes an event
(number 8) in that machine. The program in the remote machine must intercept
the event number (procedure number held in YX) and read the argument block
(OSWORD A=&12) before exiting with an RTS.

Note that the argument block must be read even if there are no arguments,
because the Rx control block will not be reopened until this has happened.

Machines with Econet version 3.34 may crash, because stations greater than
240 can override the machine protection, therefore they can overwrite the
argument block before it is read. See section 10.15 for information on
polling the transmit for success.

On entry
--------
A=&10
YX point to the address of the control block shown below:

         0 +-----------------------------+
           |            &84              |
         1 +-----------------------------+
           |             0               |
         2 +-----------------------------+
           |       Remote station        |
           |  (station number, network)  |
         4 +-----------------------------+
           |     Pointer to start of     |
           | local buffer for arguments  |
         8 +-----------------------------+
           |      Pointer to end of      |
           | local buffer for arguments  |
        12 +-----------------------------+
           |      Procedure number       |
        16 +-----------------------------+

In the remote machine the Accumulator (A register) holds the event number
(which will be 8). X will hold the low byte of the procedure number and Y
will hold the high byte.

On exit
-------
A,X,Y undefined

         0 +-----------------------------+
           |          Modified           |
         1 +-----------------------------+
           |          Unchanged          |
        16 +-----------------------------+


Remote Insert key                          OSWORD A=&10 (Control byte=&85)
==========================================================================

General description
-------------------
This call inserts a byte into a remote machine's keyboard buffer and is used
by the 'send a line of text' command (OSWORD A=&14 Control byte=1), which
should usually be used in preference to this call See section 10.15 for
information on polling the transmit for success.

On entry
--------
A=&10
YX point to the address of the control block shown below:

         0 +-----------------------------+
           |            &85              |
         1 +-----------------------------+
           |             0               |
         2 +-----------------------------+
           |       Remote station        |
           |  (station number, network)  |
         4 +-----------------------------+
           |     Pointer to buffer       |
         8 +-----------------------------+
           |   Pointer to buffer + 1     |
        12 +-----------------------------+
           |            &00              |
        16 +-----------------------------+

The buffer (which is 1 byte long) holds the byte to send to the remote station.

On exit
-------
A,X,Y undefined

         0 +-----------------------------+
           |          Modified           |
         1 +-----------------------------+
           |          Unchanged          |
        16 +-----------------------------+


Start REMOTE                               OSWORD A=&10 (Control byte=&85)
==========================================================================

General description
-------------------
This call is used to start a REMOTE. See section 10.15 for information on
polling the transmit for success.

On entry
--------
A=&10
YX point to the address of the control block shown below:

         0 +-----------------------------+
           |            &85              |
         1 +-----------------------------+
           |             0               |
         2 +-----------------------------+
           |       Remote station        |
           |  (station number, network)  |
         4 +-----------------------------+
           |     Pointer to buffer       |
         8 +-----------------------------+
           |   Pointer to buffer + 1     |
        12 +-----------------------------+
           |            &01              |
        16 +-----------------------------+

On exit
-------
A,X,Y undefined

         0 +-----------------------------+
           |          Modified           |
         1 +-----------------------------+
           |          Unchanged          |
        16 +-----------------------------+


Update workspace                           OSWORD A=&10 (Control byte=&85)
==========================================================================

General description
-------------------
This call causes a remote machine to write the state of its screen to a
position in its Econet workspace (whence it can be read by the local machine
by PEEKing this workspace). See section 10.15 for information on polling the
transmit for success.

On entry
--------
A=&10
YX point to the address of the control block shown below:

         0 +-----------------------------+
           |            &85              |
         1 +-----------------------------+
           |             0               |
         2 +-----------------------------+
           |       Remote station        |
           |  (station number, network)  |
         4 +-----------------------------+
           |     Pointer to buffer       |
         8 +-----------------------------+
           |   Pointer to buffer + 1     |
        12 +-----------------------------+
           |            &02              |
        16 +-----------------------------+

On exit
-------
A,X,Y undefined

         0 +-----------------------------+
           |          Modified           |
         1 +-----------------------------+
           |          Unchanged          |
        16 +-----------------------------+

In the remote machine the data is written to the address (in the I/O
processor) pointed to by locations &9E and &9F plus &E9. This data is shown
below:

         0 +-----------------------------+
           |  Address of top of screen   |
         2 +-----------------------------+
           |  Palette (physical colours  |
           |     defined on screen)      |
        18 +-----------------------------+
           |      Mode number (0-7)      |
        19 +-----------------------------+
           | Address of start of screen  |
        21 +-----------------------------+
           |   Mark/Space for colours    |
        23 +-----------------------------+


Fatal Error                                OSWORD A=&10 (Control byte=&85)
==========================================================================

General description
-------------------
This causes a fatal error in a remote machine. It is easier to use the high
level fatal error call (OSWORD A=&14 Control byte=2). See section 10.15 for
information on polling the transmit for success.

On entry
--------
A=&10
YX point to the address of the control block shown below:

         0 +-----------------------------+
           |            &85              |
         1 +-----------------------------+
           |             0               |
         2 +-----------------------------+
           |       Remote station        |
           |  (station number, network)  |
         4 +-----------------------------+
           |     Pointer to buffer       |
         8 +-----------------------------+
           |   Pointer to buffer + 1     |
        12 +-----------------------------+
           |            &03              |
        16 +-----------------------------+

On exit
-------
A,X,Y undefined

         0 +-----------------------------+
           |          Modified           |
         1 +-----------------------------+
           |          Unchanged          |
        16 +-----------------------------+


Halt                                       OSWORD A=&10 (Control byte=&86)
==========================================================================

General description
-------------------
Halts all non-interrupt operations in the I/O processor of a remote machine.
If a Tube is running on the remote machine, then that will continue running
until it tries to communicate with the I/O processor. See section 10.15 for
information on polling the transmit for success.

On entry
--------
A=&10
YX point to the address of the control block shown below:

         0 +-----------------------------+
           |            &86              |
         1 +-----------------------------+
           |             0               |
         2 +-----------------------------+
           |       Remote station        |
           |  (station number, network)  |
         4 +-----------------------------+

On exit
-------
A,X,Y undefined

         0 +-----------------------------+
           |          Modified           |
         1 +-----------------------------+
           |          Unchanged          |
        16 +-----------------------------+


Continue                                   OSWORD A=&10 (Control byte=&87)
==========================================================================

General description
-------------------
Restarts the I/O processor of a remote machine after a Halt command (OSWORD
A=&10 Control byte=&86). See section 10.15 for information on polling the
transmit for success.

On entry
--------
A=&10
YX point to the address of the control block shown below:

         0 +-----------------------------+
           |            &87              |
         1 +-----------------------------+
           |             0               |
         2 +-----------------------------+
           |       Remote station        |
           |  (station number, network)  |
         4 +-----------------------------+

On exit
-------
A,X,Y undefined

         0 +-----------------------------+
           |          Modified           |
         1 +-----------------------------+
           |          Unchanged          |
        16 +-----------------------------+


Identify Machine                           OSWORD A=&10 (Control byte=&88)
==========================================================================

General description
-------------------
This call interrogates a remote machine returning codes containing values to
distinguish between manufacturers, machine types and software versions. See
section 10.15 for information on polling the transmit for success.

On entry
--------
A=&10
YX point to the address of the control block shown below:

         0 +-----------------------------+
           |            &88              |
         1 +-----------------------------+
           |             0               |
         2 +-----------------------------+
           |       Remote station        |
           |  (station number, network)  |
         4 +-----------------------------+
           |  Pointer to start of local  |
           |           buffer            |
         8 +-----------------------------+
           |   Pointer to end of local   |
           |       buffer (start+4)      |
        12 +-----------------------------+

On exit
-------
A,X,Y undefined

         0 +-----------------------------+
           |          Modified           |
         1 +-----------------------------+
           |          Unchanged          |
        16 +-----------------------------+

The first four bytes of the buffer are relevant. The meaning of these bytes
are shown below:

Byte 0
This is defined by manufacturers and is intended to indicate the hardware
design of the machine. The following are currently defined:

Value        Type of machine

SJ Research
  FF        Z80 CP/M
  FE        SJ Research File Server
  FD        RM480Z
  FC        Nascom 2 (running CP/M)
  FB        IBM Interface board
  FA        SCSI Interface
  F9        SJ Research 80386 UNIX
  F8        SJ Research GP server

Acorn
  00        Reserved
  01        BBC Microcomputer (OS 1 or 2)
  02        Atom
  03        System 3 or System 4
  04        System 5
  05        Master 128 (OS 3)
  06        Electron
  07        Archimedes (OS 6)
  08        Reserved for future machine
  09        Communicator
  0A        Master 128 ET
  0B        Filestore
  0C        Master Compact (OS 5)
  0D        EcoLink card for PCs
  0F        UNIX workstation
  0F        RISC PC
  10        Iyonix
  11        A9

  40        ZX Spectrum
  41        Amstrad CPC

  50        Econet-Ethernet Gateway

Other values Reserved

Byte 1
This byte indicates the manufacturer. The following are currently defined:

    Value        Manufacturer
      00         Acorn
      01         Torch
      02         Reuters
      40         J.G.Harston
      50         Phillip Blundell
      FF         SJ Research

Bytes 2 & 3
These contain the low and high bytes of the software release version in
packed Binary Coded Decimal, byte 2 contains the version number and byte 3
the release. The easiest way to display packed BCD is to print it as if it
were hexadecimal.

Releases &00, &01 and &02 were development versions. Release &03 is 8-bit NFS
with no local buffering (eg, BBC, Electron), release &04 is 8-bit NFS with
local buffering (eg ANFS), release &05 is 32-bit NFS (eg RISC OS).

Examples:
byte 0,1: &0001 Acorn BBC
byte 2,3: &0360 Version 3.60

See also

Networking calls