RISCOS.com

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

 

NetPrint


Introduction and Overview

NetPrint is a filing system that allows you to access and use remote printer server machines, using Acorn's Econet network. In common with other filing systems it uses the FileSwitch module. When you are using NetPrint you can use many of the commands that FileSwitch provides. Obviously there are some operations (such as those that read stored data) that are not applicable to network printer servers.

The NetPrint module takes the commands that you give to it, either directly or via FileSwitch, and converts them to printer server commands. These commands are then sent to the printer server using the standard protocol of Econet. The printer server then acts on the commands and files that it is sent. It handles their spooling, and manages its (locally) connected printer.

Much of the above is transparent to the user, and in general to use printer servers you do not need to know printer server protocols, or how data is sent over the Econet. If you do need to know more about Econet protocols, you should see the chapter entitled Econet.

Technical Details

Naming

The network printing system is actually a filing system, and as such you can use it by giving its name as part of a file name. For example:

*Save NetPrint:Fred A000 +14C3

However, with current implementations the file name is ignored, and the 'NetPrint:' part is used to send the data to the network printer. As well as save operations, the NetPrint filing system can also open files and take data. This means that the operating system can spool to NetPrint:. This is discussed in more detail in the chapter entitled System devices.

Selecting a printer server

Whenever you open or save a file with NetPrint the software needs to know which printer server to send your data to. When you have only a single printer server on the network you should use *Configure PS to set its station number as the default. Then when you use the filename NetPrint: your printout will be sent to the correct station.

Some printer servers and spoolers support a naming protocol which allows you to refer to a particular printer by name rather than by number. Names can be up to six characters in length and are usually alphanumeric: for example Epson, Art, CDT, Laser1, Gerald, Draft, and PScrpt. It is sensible to choose a consistent set of names, based on either location, type, brand or class. Before NetPrint can use a named printer server, it must resolve the name to a station number; this process is called name binding. Put simply, the name binder broadcasts the name, and returns the number of the first server that says it is ready to accept a connection. If no suitable reply occurs within a specified time an error is returned.

NetPrint has the notion of the 'current printer server'. This is usually set by the *Configure PS printer_server command, or with the *PS printer_server command. If the printer_server is given by name, then name binding occurs; it is the returned number that is retained as the current setting. Using *PS printer_server will cause the binding to occur immediately and the result to be known. Once the number is selected, it will be used whenever you open or save a file with the name NetPrint:.

When your network has more than one printer server (or a spooler that is more than one server) you may wish to choose which server to use. The easiest is to set the name of the server as the configured default using *Configure PS printer_server.

It is always possible to override the current setting by supplying the name or number of the server you wish to use as part of the filename. For example you might specify a server by number thus:

NetPrint#233: - station number only (on current net)

NetPrint#2.253: - full net.station address

or you might specify it by name (which would then be bound) thus:

NetPrint#Daisy:
NetPrint#Epson:

When selecting a particular printer server by this method the 'current printer server' remains unaffected.

Operations supported

The NetPrint filing system supports the OS_File Save operation and the OS_Find OpenOut operation, as well as OS_BPut and OS_GBPB writes (but not backwards).

Linking NetPrint to *FX 5 4 and VDU 2

There are system variables that connect the VDU print streams to files; an example of this is the default value set up by NetPrint upon its initialisation. This is PrinterType$4, and its value is NetPrint:. You could change this value to indicate a particular printer:

NetPrint#Epson:

and set up another variable to contain a different value:

PrinterType$3 = NetPrint#2.235:

so that you can swap between printers with a *FX command. For example:

*FX 5 4
*FX 5 3

Timeouts

The dynamics of communication are controlled by several timeouts.

The values used by NetPrint for the TransmitCount, TransmitDelay, and ReceiveDelay are more fully explained in the chapter entitled Econet. These are the values used for all normal communication with the printer server.

Before attempting to connect to a printer server, NetPrint tries the immediate operation MachinePeek to the printer server. This operation uses a second set of values: the MachinePeekCount and the MachinePeekDelay. If this operation fails, the error 'Station not present' is generated. The reason for this is that stations must respond to MachinePeek. You can therefore determine quite quickly if the destination machine is actually present on the network, without having to wait the long time required for a normal transmission to timeout and report 'Station not listening'.

The last value used is called the BroadcastDelay; this is the amount of time for which NetPrint will wait for a printer server to respond to the broadcast with the name of the printer server. If within that time no printer server with that name has responded, or all those that did were busy, the error 'No free printer server of this type' will be returned.

SWI calls


NetPrint_ReadPSNumber
(SWI &40200)

Returns the full station number of your current printer server

On entry

--

On exit

R0 = station number
R1 = net number

Interrupts

Interrupts status is unaltered
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

This call returns the full station number of your current printer server. If the current printer server is only stored as a name (eg after *SetPS printer_server_name) then zero is returned for both the net and station numbers.

Related SWIs

NetPrint_SetPSNumber, NetPrint_ReadPSName

Related vectors

None


NetPrint_SetPSNumber
(SWI &40201)

Sets the full station number used as the current printer server

On entry

R0 = station number
R1 = net number

On exit

R0, R1 preserved

Interrupts

Interrupts may be enabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call sets the full station number used by NetPrint as your current printer server.

Related SWIs

NetPrint_ReadPSNumber, NetPrint_SetPSName

Related vectors

None


NetPrint_ReadPSName
(SWI &40202)

Reads the name of your current printer server

On entry

R1 = pointer to buffer
R2 = size of buffer in bytes

On exit

R0 = pointer to buffer
R1 = pointer to the terminating null of the string in the buffer
R2 = amount of buffer left, in bytes

Interrupts

Interrupt status is unaltered
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

This call reads the name of your current printer server. If the current printer server is only stored as a number (eg after *SetPS printer_server_number) then a null name is returned.

Versions of the NetPrint module before 5.26 return R1 one greater than it should be, and hence R2 one less than it should be.

Related SWIs

NetPrint_ReadPSNumber, NetPrint_SetPSName

Related vectors

None


NetPrint_SetPSName
(SWI &40203)

Sets by name the printer server used as your current one

On entry

R0 = pointer to buffer containing null-terminated printer server name

On exit

R0 preserved

Interrupts

Interrupt status is unaltered
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call sets by name the printer server used as your current one.

Related SWIs

NetPrint_SetPSNumber, NetPrint_ReadPSName

Related vectors

None


NetPrint_ReadPSTimeouts
(SWI &40204)

Reads the current values for timeouts used by NetPrint

On entry

--

On exit

R0 = transmit count
R1 = transmit delay in centiseconds
R2 = machine peek count
R3 = machine peek delay in centiseconds
R4 = receive delay in centiseconds
R5 = broadcast delay in centiseconds

Interrupts

Interrupt status is unaltered
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

This call reads the current values for timeouts used by NetPrint when communicating with the printer server.

Related SWIs

NetPrint_SetPSTimeouts

Related vectors

None


NetPrint_SetPSTimeouts
(SWI &40205)

Sets the current values for timeouts used by NetPrint

On entry

R0 = transmit count
R1 = transmit delay in centiseconds
R2 = machine peek count
R3 = machine peek delay in centiseconds
R4 = receive delay in centiseconds
R5 = broadcast delay in centiseconds

On exit

--

Interrupts

Interrupt status is unaltered
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

This call sets the current values for timeouts used by NetPrint when communicating with the printer server.

Related SWIs

NetPrint_ReadPSTimeouts

Related vectors

None


NetPrint_BindPSName
(SWI &40206)

Converts a printer server's name to its address, providing it is free

On entry

R0 = pointer to buffer containing null-terminated printer server name

On exit

R0 = station number
R1 = net number

Interrupts

Interrupt status is unaltered
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call attempts to find a printer server with the specified name that is not busy. If one is found its address is returned in R0 and R1; otherwise an error is returned.

This call is not available in RISC OS 2.

Related SWIs

None

Related vectors

None


NetPrint_ListServers
(SWI &40207)

Returns the names of all printer servers

On entry

R0 = format code:

0 names and numbers
1 names only, sorted, no duplicates
2 names, numbers and status
R1 = pointer to buffer
R2 = length of buffer in bytes
R3 = time to take before returning, in centiseconds

On exit

R0 = number of entries returned
R1, R2 preserved
R3 = return code:

0 timed out
1 buffer full

Interrupts

Interrupt status is unaltered
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call returns the names of all printer servers. The format and contents of the returned buffer are determined by the format code passed in R0:

R0 = 0: Names and numbers
Offset Contents
0 station number
1 net number
2 server name, zero terminated
R0 = 1: Names only, sorted by name (case insensitive), no duplicates.
Offset Contents
0 server name, zero terminated
R0 = 2: Names, numbers and status
Offset Contents
0 station number
1 net number
2 status
3 station number for status (optional)
4 net number for status (optional)
5 server name, zero terminated

Status values are as follows:

Value Name English message(s)
0 Status_Ready 'ready'
1 Status_Busy 'busy with nnn.sss'
'busy'
2 Status_Jammed 'jammed'
6 Status_Offline 'offline'
7 Status_AlreadyOpen 'already open'

For Status_Busy, the former message is used when the printer server is busy with a single known station: its number follows. The latter message is used when the printer server is busy with an unknown station, or with more than one: in this case the optional station and net numbers (at offsets 3 and 4) are set to zero.

This call is not available in RISC OS 2.

Related SWIs

NetPrint_ConvertStatusToString (SWI &40208)

Related vectors

None


NetPrint_ConvertStatusToString
(SWI &40208)

Translates a status value returned from NetPrint_ListServers into the local language

On entry

R0 = pointer to a status value byte, followed by two optional bytes containing the station and net number associated with the status
R1 = pointer to buffer to hold message
R2 = length of the buffer in bytes

On exit

R0 = value of R1 on entry
R1= pointer to the terminating zero
R2 = bytes remaining in the buffer after the terminating zero

Interrupts

Interrupt status is unaltered
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

This call translates a status value returned from NetPrint_ListServers into the local language, copying the resultant message into the specified buffer and terminating it with a zero.

This call is not available in RISC OS 2.

Related SWIs

NetPrint_ListServers (SWI &40207)

Related vectors

None

* Commands


*Configure PS

Sets the configured default network printer server

Syntax

*Configure PS printer_server

Parameters

printer_server - the name or station number of the printer server

Use

*Configure PS sets the configured default network printer server.

You do not need to be logged on to a file server to use a printer server.

The stored name or station number is only bound when the default printer is first used (ie when NetPrint: is first used, without any special fields to specify a server other than the default).

Example

*Configure PS Laser1

Related commands

*ListPS, *PS, *SetPS


*ListPS

Lists all the currently available printer servers

Syntax

*ListPS [-full]

Parameters

-full - show status of each printer server

Use

*ListPS lists all the currently available printer servers, optionally showing their status as well. The order in which they are given depends on the order in which the printer servers reply.

This command is identical to the command:

*Cat NetPrint:

or, with the -full parameter, to the command:

*Ex NetPrint:

Example

*ListPS -full
Umber    46.235  ready
Jade     44.235  ready
Mauve    93.235  ready
White    59.235  ready
Coral    32.235  jammed
Lime      2.235  ready

Related commands

*Configure PS, *PS, *SetPS


*PS

Changes the current printer server

Syntax

*PS [printer_server]

Parameters

printer_server - the name or station number of the printer server

Use

*PS changes the current printer server. The new printer server will be used next time you print to the default net printer. If the server is specified by name, it is immediately bound, and the current server set to the returned number; if the server is specified by number, the current server is set to that number.

If you don't specify a printer server, then this command returns the current printer server and its status.

Example

*PS 49.254

*PS myPS

*PS
Printer server myPS (9.235) is ready

Related commands

*Configure PS, *ListPS, *SetPS


*SetPS

Changes the current printer server

Syntax

*SetPS [printer_server]

Parameters

printer_server - the name or station number of the printer server.

Use

*SetPS changes the current printer server. This command only changes the stored name or number of the default printer server. No check is made that the printer server exists, or is available, until the next time you print to the default network printer. It is only then that an error might be generated.

If you don't specify a printer server, then this command sets the current printer server to be the default printer server (as set by *Configure PS).

Example

*SetPS 49.254

*SetPS myPS

*SetPS

Related commands

*Configure PS, *ListPS, *PS

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