RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

Character Output


Introduction

The Character Output system can send characters to the computer's output devices. They can be any or all of the following:

  • the VDU
  • the serial port
  • a file on any filing system
  • the currently selected printer

The Character Output system gives full control of the operation of each of these devices. Since they all have different characteristics, they must be controlled in different ways.

Character Output provides a means of directing characters to the device(s) that are required. It is like a train shunting yard that can send characters, like trains, to the right destination. It can also hold them, waiting until the destination is free to take them.

Overview

The Character Output system can be divided by an imaginary horizontal line. Above it is the part independent of the device(s) that the characters will end up at. Below the line is the control of each of the devices.

Terminology used
  • A device is the hardware that is used to send characters to some external form, such as shapes on a VDU or voltages on a serial line or onto a floppy disk and so on.
  • A port is like a device, though it really refers more to the actual connection to the outside.
  • A device driver is the low level code that operates a device.
  • A stream is a connection between a program and a device. Streams can also go from one program to many devices.
Back-doors

Normally, a program will go through the stream system to access output devices. However, 'back-doors' are provided to allow directly writing to a given device. A major reason for wanting to do this is speed, since the stream system necessarily takes time. Another is that this back-door approach gives much more direct control of the device and more immediate feedback on problems. A modem driving program, for example, needs to be able to react quickly to information on the serial line.

Device independence

Device independence means that any program using the stream system doesn't have to know the destination of the characters it is outputting. Most programs don't, since it will not affect their actions. If they do need to, then back-doors are available.

OS_WriteC

The core of the stream system is the SWI OS_WriteC which outputs a single character. It looks at which of the devices have been enabled and sends a copy of the character to each of them. It is in turn called by many other SWIs, printing a string for example. Characters from these other SWIs stream into OS_WriteC and from there out to the correct device.

Buffers

A program running in RISC OS works at one rate, while the hardware devices all work at different rates. This is called asynchronous operation, since the two are not synchronised. To solve this problem, buffers are used. A buffer is simply an area of memory that has been set aside to temporarily hold data. RISC OS provides buffering for all the devices used by the stream system. A program will write into a buffer, while interrupts asynchronously read it out. If a buffer became full, then RISC OS would wait until it had emptied somewhat, then continue, without the calling program ever being aware it had happened.

Devices

OS_WriteC can be set up to send to one or many of the following list of devices:

  • the printer stream
  • the serial driver
  • the spool (filing system) driver
  • the VDU driver.

The control of which devices are enabled at any time is very simple and can be changed as frequently or infrequently as desired.

These are briefly summarised below, and described in depth in later sections.

Printer stream

There are several ways in which the printer stream may be directed. Unlike the high level output streams previously discussed, where several devices may be used at once, only one printer device may be active at any one time. The printer stream is, in effect, a subpart of the full stream system.

Like the stream system, the printer stream has a number of devices it can use. The ones available by default are:

  • printer sink
  • Centronics parallel
  • serial port
  • network printer
  • user printer driver.

The printer sink is a special case. Unlike the other drivers, which operate some hardware, the printer sink is a null printer device. This simply absorbs any characters sent to it. For example, it is a device that can be used when you don't want any form of printer output with an application that uses the printer.

The Centronics parallel device allows printing on any standard parallel printer. This includes virtually all of the low cost printers sold.

The RS423 serial device can be connected to any serial printer. RS423 is like the more usual RS232 serial standard, but is better whilst still being compatible with any RS232 device.

The network printer is the one that is accessed remotely across a network. See the chapter entitled NetPrint for details of this.

Finally, the user printer driver allows programmers to write a driver to support a device not listed here.

Note that this chapter concerns itself only with the character print routines. See the chapter entitled Printer Drivers for information on the drivers that must be used for any graphical printing.

Serial output device

The device driver software takes characters from the stream system and puts them into the serial hardware, manipulating it to send them off.

The serial hardware itself changes the character into a series of voltage changes on its connection with the outside. These voltages and other control lines work together to communicate with another serial port on another machine. The baud rate of a serial port is the number of bits per second that it is sending or receiving. Under RISC OS, these rates can be controlled independently, although not all machines will support different transmit and receive rates.

Calls that are specific to the serial port, whether they refer to input or output (eg those to set the baud rate, or to explicitly send/receive a character from/to the serial port), are gathered together in the chapter entitled Serial device.

Spool device

In RISC OS, you can spool characters to a file on a filing system as if it were a sequential device. The term itself is an archaic one that has passed down from early mainframe computers.

It is very easy to use a spool file. There is a command to start spooling output to a named file, and another to stop spooling and close the file. Also, you can change the file you are spooling to at any time, without having to close and re-open it.

VDU device

The VDU device driver will put any characters or graphics onto the screen. Some characters are displayed directly, while others are interpreted as graphics commands. This chapter contains details of the interface to the VDU system, but for a detailed description of the VDU system, refer to the VDU Drivers.

Technical Details

Device independence

The core of the output stream is the SWI OS_WriteC. This is called via WrchV, the Write Character vector. Note that if this vector is ever replaced then all of the other routines that use it will also be redirected. OS_WriteC is called by many routines; in this chapter OS_WriteS, OS_Write0, OS_WriteN, OS_NewLine, OS_PrettyPrint and OS_WriteI.

OS_Byte 3 controls which devices characters get sent to. It sets a byte in which each bit represents a different output device state. Some of these bits enable whether a device gets characters or not. There are complications however, which are described fully in the following sections.

Printer stream

The printer stream can be enabled by OS_Byte 3 or using VDU codes. The selection of the printer is done by OS_Byte 5. The printer can be made to ignore a specific character by using OS_Byte 6.

OS_Byte 3

Three bits in the byte sent to OS_Byte 3 to select output streams control whether a character is sent to the printer. In addition, a character may also be sent to the printer under the control of the VDU stream.

Bit 2 provides global control over the printer. If this bit is set, then it is not possible for OS_WriteC to cause a character to be inserted into the printer buffer. If it is clear, then the character may or may not be sent to the printer, depending on the state of the other bits.

Bit 6 acts in a similar way: if it is clear, characters may be sent to the printer, but if it is set, they are stopped. There is still one way of getting characters to the printer if bit 6 is set; this is described below.

Assuming bits 2 and 6 are clear, then the simplest way of enabling the printer is by setting bit 3. When this is done, all characters sent to OS_WriteC (except the printer ignore character) will be inserted into the printer buffer.

VDU printer control

The most common way of controlling the printer is through the VDU driver. If the VDU stream is enabled (bit 1 of the output stream's byte is clear), then sending the code ASCII 2 (Ctrl-B) to OS_WriteC enables the VDU printer stream. Once this is done, all printable characters and some control characters sent to the VDU stream will also go to the printer. Sending ASCII 3 (Ctrl-C) to the VDU disables the copying of characters to the printer.

A further control code, ASCII 1 (Ctrl-A), causes the next character to be sent to the printer (if enabled by Ctrl-B), but not to the screen. All characters may be sent this way, including the control codes which are usually ignored by the VDU printer stream, and the printer ignore character.

If either bit 6 or bit 2 of the streams byte is set, then the VDU printer stream has no effect. The exception is when the character is preceded by a Ctrl-A. In this case, bit 6 will not prevent the character from being sent, although bit 2 will.

More details of the VDU printer stream control codes are given in the chapter entitled VDU Drivers.

The flow of control of the filtering - which controls which characters sent to the VDU stream also get sent to the printer - is summarised by the diagram below:


Flow of control of filtering in the printer stream

OS_Byte 5

Regardless of how a character gets to the printer stream, it is then sent to the current printer device. This is set by OS_Byte 5. It is passed a byte which can select one of 256 potential drivers, 4 of which are supplied with RISC OS.

  • printer sink
  • parallel
  • serial
  • network

When an OS_Byte 5 is used, the new destination streams come into effect only when all the current contents of the printer buffer have been sent to the previously-selected driver. This means that when you issue this OS_Byte, the calling task may appear to hang until the current printer buffer's contents are cleared. This may be forced by generating an escape condition.

The default printer device is stored in CMOS RAM and is set by *Configure Print.

OS_Byte 245

OS_Byte 245 (SWI &F5) may be used to read the current printer type, but not to set it, as it does not wait for the printer buffer to empty first. Because of this, it does not enable interrupts, so may be used to read the printer type from within an interrupt routine.

Ignore character

The printer ignore character is one which is suppressed from the printer stream, unless it got there via the VDU printer stream and was preceded by ASCII 1 (Ctrl-A). The character can be set and read using OS_Byte 246. For compatibility with older Acorn operating systems, OS_Byte 6 can also set it and OS_Byte 245 can read it.

*Ignore can be used to set the printer ignore character from the CLI. *Configure Ignore will set it permanently in CMOS RAM. The default value is 10, an ASCII linefeed.

No ignore

There may be no printer ignore character, in which case all characters are sent. This is called the NoIgnore state and can be set with OS_Byte 182.

*Ignore with no parameter has the same effect from the CLI. *Configure Ignore with no other parameters will set the NoIgnore state permanently in CMOS RAM.

Serial device

The serial device is provided as a DeviceFS (Device Filing System) device. For full details, see the chapter entitled DeviceFS, and the Serial device. The latter chapter also contains all calls that are specific to the serial port, whether they refer to input or output - such as those to set the baud rate, or to explicitly send/receive a character to/from the serial port.

(Under RISC OS 2, the serial device was provided by the SystemDevices module. See the chapter entitled The RISC OS 2 serial device.)

OS_Byte calls in this chapter

OS_Bytes 3 and 5 can be used to select the serial port as an output stream. OS_WriteC and the SWIs that use it would be used to write to its buffer, with RISC OS handling buffer full conditions and so on. (However, there are preferred calls for sending a byte to the serial port; see the chapter entitled Serial device.)

When bit 0 of the OS_Byte 3 streams byte is set, characters sent to OS_WriteC are passed to the serial output stream. In particular, they are inserted into the serial output buffer (buffer number 2), where they remain until removed by the interrupt routine dealing with serial transmission.

Note that if the serial port is selected as the printer by OS_Byte 5, and the serial port is enabled by setting bit 0 of the stream's byte with OS_Byte 3, then the character is inserted into both buffers. This means that eventually the character is printed twice, first from the serial output buffer and then from the printer buffer. To solve this problem, make the printer another device type, such as the printer sink, which allows data sent to the printer to be ignored.

Spool device

When a spool file is opened, all characters subsequently displayed using OS_WriteC are also sent to that file, using the OS_BPut routine. This action continues until the file is closed.

Opening and closing

There are two ways of opening and closing a spool file. The simplest is to use the CLI commands *Spool or *SpoolOn to start output going into the named file.

To stop spooling and close the file, a *Spool or *SpoolOn command with no parameters must be issued, or you can stop it directly by using OS_Byte 199 documented below.

OS_Byte 3

The spool file stream can be temporarily disabled by setting bit 4 of the streams byte in OS_Byte 3. This does not close the file, but prevents OS_WriteC from trying to send the character to file.

OS_Byte 199

OS_Byte 199 (SWI &C7) provides direct control over the spool file, without the necessity of using the CLI. It reads and writes the location which holds the handle of the current spool file. If this is zero, OS_WriteC makes no attempt to use the spool stream, as no file is open. You will only need to use this command for sophisticated programs that, say, keep swapping between several spool files.

VDU device

The VDU driver will display characters and graphics on the screen. The value of the character sent determines its effect. Below is a list of the meanings of different characters. Note that in Teletext modes, a different set is in use.

    Character Meaning
    0 - 31 VDU commands (graphics and control)
    32 - 126 ASCII characters
    127 Delete
    128 - 159 Acorn defined characters, and user definable characters
    160 - 255 ISO international characters

Note that if defining characters in the range 128 - 159 under the Desktop, you should always first read the current definition of the character using OS_Word 10 and then redefine it for the duration of the redraw. Always ensure that the character definition is restored (not set to the default using *FX 25) before calling XWimp_Poll again.

Disabling VDU driver

If an OS_Byte 3 with bit 1 set is sent, then the VDU driver is disabled. This prevents all output from appearing on the screen. Also, as control codes will not be acted on, it disables the VDU printer stream, described in an earlier section.

Disabling the VDU, by setting this bit, is independent of the ASCII 21 (Ctrl-U), which will disable the VDU drivers. The main difference is that the VDU printer stream will still work, if already enabled by ASCII 2 (Ctrl-B), after an ASCII 21.

VDUXV

VDUXV is the VDU extension vector. When an OS_Byte 3 with bit 1 clear (VDU enabled) and bit 5 set (VDUXV enabled) is issued, characters that would usually be sent to the VDU drivers are sent instead to the routine on the VDU extension vector. This allows you to replace the VDU drivers, usually temporarily. The font manager, for example, uses this facility.

The character sent to VDUXV can be sent to the printer stream by setting the carry flag on return from the vector.

See the chapter entitled Software vectors for more details on installing a routine on this vector.

Direct Control

OS_Plot can be used to write to the VDU directly rather than going through the stream system. It is consequently faster. It is described in OS_Plot.

SWI Calls


OS_WriteC
(SWI &00)

Writes a character to all of the active output streams

On entry

R0 = character to write

On exit

R0 preserved

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call sends the byte in R0 to all of the active output streams. This is called as a low level writer by several other routines.

OS_WriteC calls the Write character vector WrchV, the default action of which is to send the character to all active output streams. If this vector is replaced using OS_Claim (see OS_Claim), then all of the SWIs that use this vector will be funnelled into the replacement routine.

All the routines that call OS_WriteC may not actually call OS_WriteC or even WrchV unless there is some pressing reason to do so. For example, if WrchV is being intercepted by someone else as well as the default ROM routine, or if a spool file is active, or if the printer is active etc.

Related SWIs

OS_WriteS, OS_Write0, OS_NewLine, OS_PrettyPrint, OS_WriteN, OS_WriteI, OS_Byte 3

Related vectors

WrchV


OS_WriteS
(SWI &01)

Writes the following string to all of the active output streams

On entry

--

On exit

--

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call sends the string that immediately follows the SWI instruction to all of the active output streams. It uses OS_WriteC directly a character at a time. The string is terminated by a null byte.

This SWI alters its return address so that execution continues at the word after the end of the string. Consequently you must not conditionally execute this SWI.

Related SWIs

OS_WriteC

Related vectors

WrchV


OS_Write0
(SWI &02)

Writes an indirect string to all of the active output streams

On entry

R0 = pointer to null-terminated string to write

On exit

R0 = pointer to the byte after the null byte

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call sends the string pointed to by R0 to all of the active output streams. It uses OS_WriteC directly a character at a time. The string is terminated by a null byte.

Related SWIs

OS_WriteC

Related vectors

WrchV


OS_NewLine
(SWI &03)

Writes a line feed followed by a carriage return to all of the active output streams.

On entry

--

On exit

--

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call writes a line feed followed by a carriage return to all of the active output streams. It uses two calls to OS_WriteI to do so, which in turn call OS_WriteC.

Related SWIs

OS_WriteC, OS_WriteI

Related vectors

WrchV


OS_Byte 3
(SWI &06)

Selects the output streams that are active

On entry

R0 = 3 (reason code)
R1 = bit mask for output streams

On exit

R0 preserved
R1 = previous stream specification
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call selects which output stream(s) are active, and will hence receive all subsequent output. A bit mask in R1 determines this:

    Bit Effect if set
    0 Enables serial driver
    1 Disables VDU drivers
    2 Disables VDU printer stream
    3 Enables printer (independently of the VDU)
    4 Disables spooled output
    5 Calls VDUXV instead of VDU drivers (see the chapter on VDU)
    6 Disables printer, apart from VDU 1,n
    7 Not used

The interpretations of all of these bits are described in subsequent sections. All bits are zero by default. This means that the VDU drivers, the VDU printer stream and the spool stream are enabled, and other streams disabled

Details of how bits 1, 2, 3 and 6 interact is described in the Technical Details onwards.

Related SWIs

OS_Byte 236

Related vectors

ByteV, VDUXV, WrchV


OS_Byte 5
(SWI &06)

Sets which PrinterType$... variable holds the printer output path

On entry

R0 = 5 (reason code)
R1 = number n of PrinterType$n variable to use (0 - 255)

On exit

R0 = preserved
R1 = previous printer driver type
R2 = corrupted

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call sets which PrinterType$... variable holds the path to use for subsequent printer output.

For R1 = n the path held in the variable PrinterType$n is used. The default values of these variables route printed output as follows:

    n Printer
    0 Null (no output)
    1 Parallel port
    2 Serial port
    3 Path in system variable PrinterType$3 (reserved for user printer driver)
    4 Network printer (handled through NetPrint)
    5-255 Paths in system variables PrinterType$5 to PrinterType$255

Under RISC OS 2 values of 0, 1 or 2 explicitly set output as given above, rather than by consulting the variables PrinterType$0, $1 and $2.

The default variable to use is set by *Configure Print; for this purpose, n is restricted to the range 0 - 7.

Note that if the current PrinterType$... variable is set to the serial device's path, and the serial port is enabled by setting bit 0 of the stream's byte, then the character is inserted into both buffers. This means that eventually the character is printed twice (first from the serial output buffer), so this practice is not recommended.

The new PrinterType$... variable comes into effect only when all the current contents of the printer buffer have been sent to the path held in the previously selected variable. This means that when this OS_Byte is issued, or the corresponding *FX command, the machine may appear to hang until the current printer buffer's contents are cleared. (You may force this to happen by acknowledging an escape condition from the foreground, provided that the escape side effects are enabled.)

Related SWIs

OS_Byte 8, OS_Byte 245

Related vectors

ByteV


OS_Byte 6
(SWI &06)

Sets the printer ignore character

On entry

R0 = 6 (reason code)
R1 = ASCII code of ignore character

On exit

R0 = preserved
R1 = previous ignore character
R2 = corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call sets the printer ignore character to the specified ASCII code. This character is filtered out when printing is enabled via the VDU printer stream or OS_Byte 5.

The default value of the printer ignore character is set by *Configure Ignore. You may temporarily change it using this OS_Byte, or *Ignore. The latter has the advantage that it also allows a NoIgnore state to be set.

Related SWIs

OS_Byte 5, OS_Byte 182, OS_Byte 246

Related vectors

ByteV


OS_Byte 182
(SWI &06)

Reads/writes the printer NoIgnore state

On entry

R0 = 182 (reason code)
R1 = 0 to read or new state to write
R2 = 255 to read or 0 to write

On exit

R0 = preserved
R1 = state before being overwritten
R2 = corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The state stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((state AND R2) XOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.

This call allows reading the current NoIgnore state or changing it to a new value.

If the value read or written is >=&80 (ie has bit 7 set), then the printer ignore character is not used. If bit 7 is clear, then the current printer ignore character is filtered out.

The default setting of this flag is controlled by *Configure Ignore and may be changed temporarily using *Ignore.

Related SWIs

OS_Byte 6, OS_Byte 246

Related vectors

ByteV


OS_Byte 199
(SWI &06)

Reads/writes the spool file handle

On entry

R0 = 199 (reason code)
R1 = 0 to read or new handle (as returned by OS_Find) to write
R2 = 255 to read or 0 to write

On exit

R0 = preserved
R1 = handle before being overwritten
R2 = corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call reads/writes the spool file handle, which sets the destination of spooled data. The handle must have been correctly returned from a previous call to OS_Find. If the file handle is zero, or if spooling is disabled by OS_Byte 3, then no spooled data is sent.

Related SWIs

OS_Byte 3, OS_Find

Related vectors

ByteV


OS_Byte 236
(SWI &06)

Read/write character destination status

On entry

R0 = 236 (reason code)
R1 = 0 when reading or new status when writing
R2 = 255 to read or 0 to write

On exit

R0 = preserved
R1 = status before being overwritten
R2 = cursor key status (see OS_Byte 237, OS_Byte 237)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The status stored is changed by being masked with R2 and then exclusive ORd with R1. ie ((status AND R2) XOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.

This call reads and writes the output stream's value. This can also be written by OS_Byte 3. See OS_Byte 3 for a list of the bit values.

Related SWIs

OS_Byte 3

Related vectors

ByteV


OS_Byte 245
(SWI &06)

Reads which PrinterType$... variable holds the printer output path

On entry

R0 = 245 (reason code)
R1 = 0
R2 = 255

On exit

R0 = preserved
R1 = value before being overwritten
R2 = value of printer ignore character (see OS_Byte 246, OS_Byte 246)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call reads which PrinterType$... variable holds the path to use for subsequent printer output

For R1 = n the path held in the variable PrinterType$n is used. The default values of these variables route printed output as follows:

    n Printer
    0 Null (no output)
    1 Parallel port
    2 Serial port
    3 Path in system variable PrinterType$3 (reserved for user printer driver)
    4 Network printer (handled through NetPrint)
    5-255 Paths in system variables PrinterType$5 to PrinterType$255

Under RISC OS 2 values of 0, 1 or 2 explicitly set output as given above, rather than by consulting the variables PrinterType$0, $1 and $2.

The value stored must not be changed by making R1 and R2 other than the values stated above. Use OS_Byte 5 instead to write.

This call does not wait for the printer buffer to empty first. Because of this, it does not enable interrupts, and so may be used to read the printer type from within an interrupt routine.

Related SWIs

OS_Byte 5

Related vectors

ByteV


OS_Byte 246
(SWI &06)

Read/write printer ignore character

On entry

R0 = 246 (reason code)
R1 = 0 to read or new ASCII value to write
R2 = 255 to read or 0 to write

On exit

R0 = preserved
R1 = value before being overwritten
R2 = corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The value stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((value AND R2) XOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.

This call allows reading the current state of the printer ignore character or changing it to a new value.

Related SWIs

OS_Byte 6, OS_Byte 182

Related vectors

ByteV


OS_PrettyPrint
(SWI &44)

Write an indirect string with some formatting to all of the active output streams

On entry

R0 = pointer to null-terminated string to write
R1 = pointer to dictionary (0 means use the internal RISC OS dictionary)
R2 = pointer to null-terminated special string

On exit

R0 = preserved
R1 = preserved
R2 = preserved

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call acts like OS_Write0, with several differences:

  • Several characters have special meanings to OS_PrettyPrint.
  • It will break a line at a SPACE (ACSII 32) if the next word will not fit on the line; it will not do this at hard spaces.
  • Compacted text is handled.

The following characters in the string have special meanings:

  • CR (ASCII 13) causes a newline to be generated.
  • TAB (ASCII 9) causes a tabulation to the next multiple of eight columns.
  • SPACE (ASCII 31) is a hard space.
  • ESC (ASCII 27) indicates that a dictionary entry should be substituted.

Compacted text uses an escape character in the print string to indicate a dictionary entry. It is followed immediately by a byte which is the dictionary entry number. If this byte is in the range 1 to 255, then the appropriate string in the dictionary is substituted. If it is 0, then the special string pointed to by R2 on entry is substituted. (This is used in particular by the *Help command.)

The format of a dictionary is a linear list of entries, which can recursively refer to other dictionary entries; each entry is a length byte followed by a null-terminated string. This means that a dictionary does not have to have 255 entries. It can be ended at any point with a zero length entry.

The content of the RISC OS dictionary is summarised below:

    Token String
    0 string pointed to by R2
    1 "Syntax: *"string pointed to by R2
    2 " the "
    3 "director"
    4 "filing system"
    5 "current"
    6 " to a variable. Other types of value can be assigned with *"
    7 "file"
    8 "default "
    9 "tion"
    10 "*Configure "
    11 "name"
    12 " server"
    13 "number"
    14 "Syntax: *"string pointed to by R2" <"
    15 " one or more files that match the given wildcard"
    16 " and "
    17 "relocatable module"
    18 CR"C(onfirm)"TAB"Prompt for confirmation of each "
    19 "sets the "
    20 "Syntax: *"string pointed to by R2" [<disc spec.>]"
    21 "}"CR"V(erbose)"TAB"Print information on each file "
    23 "spriteLandscape [<XScale> [<YScale> [<Margin> [<Threshold>]]]]]"
    24 " is used to print a hard copy of the screen on EPSON-"
    25 "."CR"Options: (use ~ to force off, eg. ~"
    26 "printe"
    27 "Syntax: *"string pointed to by R2" <filename>"
    28 "select"
    29 "xpression"
    30 "Syntax: *"string pointed to by R2" ["
    31 "sprite"
    32 " displays"
    33 "free space"
    34 " {off}"
    35 "library"
    36 "parameter"
    37 "object"
    38 " all "
    39 "disc"
    40 " to "
    41 " is "

Related SWIs

OS_WriteC

Related vectors

None


OS_PrintChar
(SWI &5D)

Send a character to the printer stream

On entry

R0 = character to print

On exit

R0 = preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call sends a character to the printer. OS_Bytes 3 and 5 control whether there is a printer selected and which device it is.

Note that the printer ignore character (see OS_Byte 6, OS_Byte 6) is not used by this call.

Related SWIs

None

Related vectors

None


OS_WriteN
(SWI &46)

Write a counted string to the VDU

On entry

R0 = pointer to string to write
R1 = number of bytes to write

On exit

R0, R1 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

If the VDU is the only active stream, this call uses the low-level VDU drivers directly, and is therefore much more efficient than using multiple calls to OS_WriteC. Also, because no special character is used to mark the end of the string, any VDU sequence may be sent.

Related SWIs

OS_WriteC, OS_WriteS, OS_Write0

Related vectors

WrchV


OS_WriteI
(SWIs &100-1FF)

Write an immediate byte to all of the active output streams

On entry

--

On exit

--

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call writes the character contained in the bottom byte of the SWI number, using OS_WriteC. It has the advantage of being more compact and quicker for a program using it than the equivalent usage of OS_WriteC. For example, to write a 'J' character, you would use:

SWI OS_WriteI + ASC"J"

Related SWIs

OS_WriteC

Related vectors

WrchV

*Commands


*Configure Ignore

Sets the configured printer ignore character

Syntax

*Configure Ignore [ASCII_code]

Parameters

ASCII_code - ASCII code, from 0 to 255

Use

*Configure Ignore sets the configured printer ignore character to the specified ASCII code. This character is filtered out when printing is enabled via the VDU printer stream or OS_Byte 5. With no parameter, the NoIgnore state is configured, so all characters will be printed.

The default value is 10 (ASCII linefeed). On some printers, you may find this causes lines to overprint each other, in which case you should omit the ASCII code so all characters are sent to the printer. *Configure Ignore 0 will not ensure all characters are printed; it will set the configured printer ignore character to ASCII 0 (the null character).

The change takes effect on the next hard reset.

Example

*Configure Ignore 10 - Do not print ASCII character 10

*Configure Ignore - Print all characters

Related commands

*Ignore

Related SWIs

OS_Byte 6, OS_Byte 5, OS_Byte 182, OS_Byte 246

Related vectors

None


*Configure Print

Sets the configured default destination for printed output

Syntax

*Configure Print n

Parameters

n - 0 to 7

Use

*Configure Print sets the configured default destination for printed output. For a value n the path held in the variable PrinterType$n is used. The default values of these variables route printed output as follows:

    n Printer
    0 Null (no output)
    1 Parallel port
    2 Serial port
    3 Path in system variable PrinterType$3 (reserved for user printer driver)
    4 Network printer (handled through NetPrint)
    5-7 Paths in system variables PrinterType$5, 6 or 7

Under RISC OS 2 values of 0, 1 or 2 explicitly set output as given above, rather than by consulting the variables PrinterType$0, $1 and $2.

The change takes effect on the next hard reset.

Example

*Configure Print 1 - select the parallel printer port

Related commands

None

Related SWIs

OS_Byte 5

Related vectors

None


*Ignore

Sets the printer ignore character

Syntax

*Ignore [ASCII_code]

Parameters

ASCII_code - ASCII code, from 0 to 255

Use

*Ignore sets the printer ignore character to the specified ASCII code. This character is filtered out when printing is enabled via the VDU printer stream or OS_Byte 5. With no parameter, the NoIgnore state is set, so all characters are printed.

The default value is 10 (ASCII linefeed). On some printers, you may find this causes lines to overprint each other, in which case you should omit the ASCII code so all characters are sent to the printer. *Ignore 0 will not ensure all characters are printed; it will set the printer ignore character to ASCII 0 (the null character).

OS_Byte 6 performs the same action as this command; OS_Byte 246 also reads and writes the printer ignore character. OS_Byte 182 controls the NoIgnore state.

Example

*Ignore 10 - Do not print ASCII character 10

*Ignore - Print all characters

Related commands

None

Related SWIs

OS_Byte 5, OS_Byte 6, OS_Byte 182, OS_Byte 246

Related vectors

None

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015