lyrathorpe/sibo-playground
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
feat/inventory-phase1-scan
sibo-playground/docs/2-03 IO Devices Reference 2.30_djvu.txt
T
lyrathorpe 538705a807 docs: add extra sdk docs
2026-07-06 18:30:29 +01:00

14946 lines
370 KiB
Plaintext
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
SIBO 'C' Software Development Kit
I/O DEVICES REFERENCE
Version 2.30
March 1, 1999
(C) Copyright Psion PLC 1990-97
All rights reserved. This manual and the programs referred to herein are copyrighted works of Psion PLC,
London, England. Reproduction in whole or in part, including utilization in machines capable of
reproduction or retrieval, without express written permission of Psion PLC, is prohibited. Reverse
engineering is also prohibited.
The information in this document is subject to change without notice.
Psion and the Psion logo are registered trademarks, and Psion, Psion MC, Psion HC, Psion Series 3, Psion
Series 3a, Psion Series 3c, Psion Siena and Psion Workabout are trademarks of Psion PLC.
TopSpeed is a registered trademark of Clarion Software Corporation. Intel 8086 and 80286 are registered
trademarks of Intel Corporation. IBM, IBM XT and IBM AT are registered trademarks of International
Business Machines Corp. Microsoft and MS-DOS are registered trademarks of Microsoft Corporation.
Apple and Macintosh are registered trademarks of Apple Computer Inc. VAX and VMS are registered
trademarks of Digital Equipment Corporation. Brief is a registered trademark of Underware Inc. Psion
PLC acknowledges that some other names referred to are registered trademarks.
Contents
1 Introduction
Conventions used in this manual
2 Console
Introduction
Automatic opening of a console channel
Explicit opening of a console channel
P_FSET service call convention
Panics
Console services
Open the console (p_open)
Close the console (p_close)
Write to the console (p_write)
Read a keypress (P_LFREAD)
Cancel an outstanding read (P_FCANCEL)
Test for outstanding keypresses (P_FTEST)
Flush keyboard buffer (P_FFLUSH)
Edit a string (P_FEDIT)
Sense console data (P_FSENSE)
Set the console window size (P_FSET, P_SCR_WSET)
Scroll the window content (P_LSCR_SCROLL)
Clear a rectangle (P_FSET, P_SCR_CLR)
Position cursor to next line (P_FSET, P_SCR_NEL)
Set the cursor position (absolute) (P_LFSET, P_SCR_POSA)
Set the cursor position (relative) (P_LFSET, P_SCR_POSR)
Turn the cursor on or off (P_FSET, P_SCR_CURSOR)
Set scroll lock (P_LFSET, P_LSCR_SLOCK)
Set auto wrap (P_FSET, P_SCR_WLOCK)
Set escape on or off (P_FSET, P_SCR_ESCAPE)
Set compatibility on or off (P_FSET, P_LSCR_COMPATIBILITY)
Set the use of grey on or off (P_LFSET, P_LSCR_GREY)
Additional console services
Read an event (PLEVENT_READ)
Test for outstanding event (P_LEVENT_TEST)
Get console data (P_FINQ)
Flush window server buffer (P_FWFLUSH)
Set the console output rectangle (P_FSET, P_SCR_CSET)
Set character attributes (P_FSET, P_SCR_ATTRB)
Set the screen font (P_FSET, P_SCR_FONT)
Set the last line wrap (P_FSET, P_SCR_LAST_LINE_WRAP)
Set window server flushing (P_FSET, P_SCR_FLUSH)
Disable reads (P_FSET, P_SCR_DISABLE READS)
Bring to foreground (P_FSET, P_SCR_CLIENT_FOREGROUND)
Capture a key (P_LFSET, P_SCR_CAPTURE_KEY)
Cancel a key capture (P_LFSET, PLSCR_CANCEL_CAPTURE_KEY)
Example
3 Parallel Port
Introduction
Parallel port device names
Panics
Ww &
ae es
Parallel port services
Open a parallel port (p_open)
Close a parallel port (p_close)
Write to a parallel port (P_FWRITE)
Cancel a write request (P_FCANCEL)
Sense the input control lines (P_FSENSE)
Write the output control lines (P_FSET)
Example
Introduction
Serial port device names
Panics
Serial port parameters
Baud rate
Character frame
Parity
Handshaking
Control flags
Terminator characters
Serial port errors
Serial port services
Open a serial port (p_open)
Close a serial port (p_close)
Read from the serial port (P_FREAD)
Write to the serial port (P_FWRITE)
Cancel any outstanding requests (P_FCANCEL)
Sense the serial port characteristics (P_FSENSE)
Set the serial port characteristics (P_FSET)
Flush the read buffer (P_FFLUSH)
Test for received characters (P_FTEST)
Test and set control lines (P_FCTRL)
Inquire supported serial characteristics (P_FINQ)
Introduction
Sound on MC and HC machines
Sound on Series 3 machines
Sound on Series 3a machines
Panics
Sound services
Open the sound channel (p_open)
Close the sound channel (p_close)
Cancel a write request (P_FCANCEL)
Sense sound characteristics (P_FSENSE)
Set sound characteristics (P_FSET)
Write alarm note sequence (E_LFALARM)
HC, MC and Series 3a additional sound service
Write to voice n (E_LFSSOUNDCHANNELn)
Series 3 and Series 3a additional sound service
Write DTMF dial tones (E_FDIAL)
Example
1/0 DEVICES REFERENCE
WwW WW WW WwW W
WNHONNNR RR
4 Serial Port
5 Sound
NNANAAnAnNnaannannnnnann
r
ABRRBOBBWNNHNNHNNHNKRHR SEE
ii
CONTENTS
6 The Alarm Device Driver 6-1
Introduction 6-1
Panics 6-2
Series 3, Series 3a and MC alarm services 6-2
Open the alarm channel (p_open) 6-2
Close the alarm channel (p_close) 6-2
Cancel an alarm request (P_FCANCEL) 6-2
Queue a timed alarm (A_FTIMED) 6-2
Queue an untimed alarm (A_FUNTIMED) 6-3
Series 3a additional alarm services 6-3
Queue a Series 3a timed alarm (A_FTIMED_X) 6-3
Queue a Series 3a untimed alarm (A_FUNTIMED_X) 6-4
7 The Free-Running Counter 7-1
Introduction 7-1
FRC services 7-1
Open the FRC channel (p_open) 7-1
Close the FRC channel (p_close) 7-2
Cancel the FRC request (P_FCANCEL) 7-2
Start the free-running counter (A_FTIMED) 7-2
Read the elapsed time in ELFRC_COUNTING mode (P_FREAD) 7-2
Read the elapsed time in E_-FRC_REPEATING mode (P_FREAD) 7-3
8 The Series 3 World Database 8-1
Introduction 8-1
Mode 8-1
Series 3 and Series 3a World database services 8-2
Open the World channel (p_open) 8-2
Close the World channel (p_close) 8-2
Cancel a World request (P_FCANCEL) 8-2
Find by city (WR_FIND_CITY) 8-2
Find by country (WR_FIND_COUNTRY) 8-2
Find by city and country (WR_FIND_EXACT) 8-3
Find next city (WR_NEXT) 8-3
Find previous city (WR_BACK) 8-3
Find home city (WR_GET_HOME) 8-3
Set home city (WR_SET_HOME) 8-3
Find default country (WR_GET_DEFAULT_COUNTRY) 8-4
Set default country (WR_SET_DEFAULT_COUNTRY) 8-4
Get dial string (WR_GET_DIAL_STRING) 8-4
Open file for additional data (WR_SET_EXTRA) 8-5
Modify additional data (WR_EXTRA) 8-5
Read city data (WR_GET_CITY_DATA) 8-6
Read city data (WR_GET_COUNTRY_DATA) 8-7
Calculate distance, sunrise and sunset (WR_CALC) 8-8
Read next city name (WR_NEXT_LOCK) 8-9
World file types and their locations 8-9
Main World file 8-9
World Extension file 8-9
World File format 8-9
World Extension File format 8-10
File header 8-10
Data block 8-10
iii
I/O DEVICES REFERENCE
9 Xmodem and Ymodem
Introduction
Data transfer protocols overview
One byte checksum
Two byte Cyclic Redundancy Check (CRC)
The Xmodem protocol
Link establishment
The data transfer phase
Link termination
Checksum data flow showing error recovery
The CRC variant
CRC data flow showing error recovery
The 1K variant
The 1K option data flow
Abandoning a transfer
The Ymodem protocol
Link establishment
The data transfer phase
Link termination
Ymodem file transfer data flow
The 1K variant
The G variant
Ymodem-G file transfer data flow
Abandoning a transfer
Protocol problems
Xmodem/Ymodem services
Open an Xmodem/Ymodem channel (p_open)
Close the Xmodem channel (p_close)
Connect to the remote computer (P_FCONNECT)
Disconnect from the remote computer P_FDISCONNECT)
Read data from the remote computer (P_FREAD)
Write data to the remote computer (P_FWRITE)
10 NCP and Link
iv
Introduction
Panics
The Psion logical link layer protocol
The SYS$NCP process
Connection establishment
Data transfer
The LINK process
NCP services
Open an NCP channel (p_open)
Close the NCP channel (p_close)
Connect to a remote process (P_FCONNECT)
Disconnect from the remote process (P_FDISCONNECT)
Read data from the remote process (P_LFREAD)
Write data to the remote process (P_FWRITE)
Cancel any outstanding request (P_FCANCEL)
Read supervisory information (P_FRSUPER)
Respond to a supervisory message (P_FINQ)
Sense the current channel activity (P_FSENSE)
Request the SYS$NCP terminate (P_FSTOP)
Example
°
—
XO 0 0 O_O OO O_O SOO SO 0 XO
BBWWWWNNN DN RRR
Ne)
I I I I I I I
aN
KH HB woeomOUNUUADAUUY
So
Neo
11 Cradle and Docking Station
Introduction
Cradle/Docking Station services
Open the device (p_open)
Close the channel (p_close)
Read from the device (P_FREAD)
Cancel a read (P_LFCANCEL)
Set the device type (P_FSET)
Sense the device type (P_FSENSE)
12 HC Magnetic Card Reader
Introduction
Open the MCR device (p_open)
Close the channel (p_close)
Read from the MCR device (P_FREAD)
Cancel a read (P_LFCANCEL)
Set the pull-up resistors (P_FSET)
13 HC Bar Code Reader
Hardware Description
The Bar code reader interface module
The bar code reader wand.
Device drivers
Bar code driver services
Open the bar code device (p_open)
Close the channel (p_close)
Read from the MCR device (P_FREAD)
Cancel a read (P_LFCANCEL)
14 HC Intelligent Bar Code Reader/RS232 Port
RS232/intelligent bar code reader module
The RS232 serial port interface
Power consumption
Powering the HC from an external power source
DSR auto wakeup switch
The bar code interface
Power consumption
Powering a bar code wand from the HC
Bar code symbologies
Code 128
Codabar
Interleaved 2 of 5
Code 39
The UPC/EAN bar code formats
UPC E
UPC E + 2 digits
UPC E + 5 digits
EAN 8 bar code format
EAN 8 + 2 digits
EAN 8 + 5 digits
EAN 13
EAN 13 + 2 digits
EAN 13 + 5 digits
UPC A
UPC A + 2 digits
UPC A + 5 digits
CONTENTS
I/O DEVICES REFERENCE
Bar code commands
Multiple options in a command
Issuing multiple commands
Serial intercharacter delay
Hard reset
Select bar code symbology
Check character options
Decoding options
Single read mode
Single read control
Set Interleaved 2 of 5 length
Set termination string
Code ID characters
Status request
Scanner enable
RS232 port/bar code driver services
Open the device (p_open)
Close the channel (p_close)
Sense serial port characteristics (P_FSENSE)
Set serial port characteristics (P_FSET)
Read from device (P_FREAD)
Write to device (P_FWRITE)
An example program
15 Introduction to Psion Infrared Communications
About this chapter
The IrDA protocol layer model
Introduction to Psion infrared communications
The Psion protocol layer model
The physical layer
Port geometry
Data transfer rate
Data link layer
Primary and secondary stations
IrLAP services
The network layer
IAS application logging
Discovery
Multiplexing
Link Control
The Psion IR Communications application
Third party applications
System resources
Keypresses
The IR printer port device driver
16 The AccessIr API
Using the AccessIr API
Prerequisites
Introduction to using the AccessIr API
Initialising the IR protocol stack
Opening and closing a channel to the IR device
Discovery
Selection
Connection
Sending and accepting data
Disconnection
Constants
CONTENTS
Opening and closing a channel to the IR device 16-3
Open a channel to the IR device (p_open) 16-3
Close a channel to the IR device (p_close) 16-4
Discovery, selection and connection 16-4
Discover IR enabled machines (P_FIRDISCOVER) 16-4
Select remote machine to connect to (P_FIRSELECT) 16-4
Connect to selected machine (P_FIRMAKECONNECT) 16-5
Wait for remote connect (primary) (P_FIRAWAITCONNECT) 16-5
Send and accept data 16-6
Accept data from selected remote machine (P_FREAD) 16-6
Send data to the selected remote machine (P_FWRITE) 16-6
Disconnection 16-6
Disconnect from remote machine (P_FIRDISCONNECT) 16-6
Example application 16-7
17 The IrMUX API 17-1
Using the IrMUX API 17-1
Prerequisites 17-1
Introduction to using the ITMUX API 17-1
Initialising the IR protocol stack 17-1
Logging on to and logging off from the ITMUX server 17-2
Registering/unregistering applications with the LM-IAS server 17-2
LM-IAS services 17-2
The IAS Get Value By Class message frame 17-3
The IAS Get Value By Class reply frame 17-3
Connectionless calls 17-3
Reading and writing data 17-3
Connection-oriented calls 17-3
Discovery 17-4
Connection - first time 17-4
Disconnecting - first time 17-4
Connection - second time 17-4
Reading and writing data 17-4
Disconnecting - second time 17-4
Using Exclusive mode 17-4
The IrMUX API 17-5
IrMUX message format 17-5
Log on to the IrMUX server (LM_Logon) 17-5
Log off from the ITMUX server (LM_Logoff) 17-5
Register a port number with the LM-IAS server (LM_RegisterPort) 17-5
Free registered port with LM-IAS server (LM_UnRegisterPort) 17-6
Queue a connectionless read request (LM_CLReadRequest) 17-6
Queue a connectionless write request (LM_CLWriteRequest) 17-7
Return info on in-range machines (LM_DiscoverDevicesRequest) 17-7
Attempt to connect to a remote machine (LM_ConnectRequest) 17-7
Wait for remote machine to connect (LM_WaitForConnection) 17-8
Return the status of the link (LM_StatusRequest) 17-9
Queue a read request on a connection (LM_ReadRequest) 17-9
Queue a write request on a connection (LM_WriteRequest) 17-10
Queue an unreliable read request (LM_UReadRequest) 17-10
Queue an unreliable write request (LM_UWriteRequest) 17-11
Obtain/release exclusive access (LM_AccessModeRequest) 17-11
Place the connection into Idle/Active mode (LM_IdleRequest) 17-12
Set retries on each data frame (LM_SetHandshakingLevel) 17-12
Disconnect (LM_DisconnectRequest) 17-13
1/0 DEVICES REFERENCE
18 Fast Charger
Introduction
Docking Station services
HC/Workabout docking station fast charger services
Fast charging batteries
Measuring battery capacity
Rated charge capacity of standard Psion battery packs
Example calculations
Open the fast charger device (p_open)
Close the channel (p_close)
Set the battery charge mode (FCHG_SETCHARGEMODE)
Charging Psion battery packs
Charging custom battery packs
Read battery charge mode (FCHG_READCHARGEMODE)
Read the battery status (FCHG_READSTATUS)
Read the battery status asynchronously (FCHG_ASYNCHREAD)
Cancel an asynchronous read (FCHG_CANCEL)
Fast charge the main battery (FCHG_FASTCHARGE1)
Fast charge the spare battery (FCHG_FASTCHARGE2)
Discharge the main battery (FCHG_DISCHARGE1)
Example program
18-1
18-1
18-1
18-2
18-3
18-3
18-3
18-3
18-4
18-4
18-4
18-5
18-6
18-6
18-7
18-7
18-7
18-7
18-8
18-8
CHAPTER 1
INTRODUCTION
This manual describes the I/O device drivers that have been written by Psion, except for the files device
driver and the the asynchronous timer device driver which are described in the Files and the Time,
Timers and Dates chapters of the PLIB Reference manual.
Before using any of the devices described in this manual the reader should be familiar with the contents of
the Asynchronous Requests and Semaphores and the I/O System chapters of the PLIB Reference manual.
Conventions used in this manual
I/O devices support a number of services, each specified by a function number of the form P_Fxxxx
(defined in p_file.h). For example, to write to a channel opened with a control block at *pcb, you may call:
p_ioc(pcb,P_FWRITE, additional parameters) ;
The notation p_ioc(P_FWRITE) or, more simply, P_FWRITE is used to refer to this function call.
All I/O function requests are asynchronous in principle. In practice, however, many I/O requests are
implemented synchronously, that is, the I/O operation will complete before the service call returns. For
example, the P_FCLOSE service is always implemented synchronously but the p_rREaD service is commonly
implemented asynchronously.
The description of a service that is implemented synchronously gives either the specific synchronous call
(such as p_open or p_close) or the p_iow service call prototype. Services implemented synchronously are
prototyped using only the p_iow I/O primitive, since there is no advantage in calling them
asynchronously.
A service that is implemented asynchronously may be called synchronously or asynchronously. The
description gives both the synchronous call (as described above) and the asynchronous p_ioc service call
prototype. Such a service may be called using the p_iow, p_ioc or p_ioa primitives. Note that the use of
p_ioc is in almost all cases preferable to the use of p_ioa (since the former will complete even in the
event of an error).
Note that smaller code will be generated by use of the primitives:
p_iow2, p_iow3, p_iow4, p_iow5,
p_ioc3, p_ioc4, p_ioc5d,
p_ioa3, p_ioa4, p_ioad.
Again the use of, for example, p_ioc3 is in almost all cases preferable to the use of p_ioa3. The same
statement applies to the other two variants of each function.
CHAPTER 2
CONSOLE
Introduction
The console (con: ) device provides a basic set of screen and keyboard services, suitable for use by
relatively simple character-based C application programs. OPL programs automatically open a console
channel to provide support for the screen display and keyboard commands.
The console device is implemented differently on different machines in the SIBO range:
e on the HC and Series 3 machines the console device connects directly to the window server.
e onthe MC 200 and MC 400 machines the console device is implemented by an intermediate
sysscons display process.
There are also some differences in the services that are available on different machines. These differences
are stated in the description of the particular service to which they apply.
Some of the console functions use the P_PoINT, P_RECT and P_REcTP structures. They are defined in
p_graf.h (which is included by p_cons.h) as:
typedef struct
{
WORD x; /* x coordinate */
WORD y; /* y coordinate */
} P_POINT;
typedef struct
{
P_POINT tl; /* top left coordinates */
P_POINT br; /* bottom right coordinates */
} P_RECT;
typedef struct
{
P_RECT r; /* rectangle */
P_POINT p; /* point */
} P_RECTP;
Co-ordinates are measured from the top left corner of the window (0, 0), and increment to the right (x)
and down (y). Co-ordinates are measured in character units.
When rectangles are specified the top left point is included in the rectangle and the bottom right corner is
just outside the rectangle. If a rectangle extends outside the console window then it is clipped to fit inside
the window (this feature may be used to save sensing the size of the window when a scroll or clear is
required up to the right/bottom edge of the window).
Versions of EPOC prior to version 2.32 do not support the opening of a console device when the
application program's total memory usage exceeds 32k.
I/O DEVICES REFERENCE
Automatic opening of a console channel
A channel to the console device is opened automatically during the start-up initialisation of a C program
built with the CLIB start-up module. This does not occur in the case of programs built with the PLIB
start-up module.
In PLIB programs, however, the console (if not already open) is opened automatically by the first use of
one of the PLIB simple console I/O functions (p_getch, p_printf, etc.) described in the //O System
chapter of the PLIB Reference manual.
The console channel handle of an automatically opened console device channel is stored in the pre-
defined static winHandle.
An automatically opened console is set to a size appropriate for the SIBO machine on which the
application is running. In a PLIB program you may, however, specify the window size of an automatically
opened console by setting the global p_REcT structure _DefScreenRect, as follows:
GLDEF_D _DefScreenRect;
_DefScreenRect.tl.x=0;
_DefScreenRect.tl.y=0;
_DefScreenRect.tl1.x=40; /* 40 columns */
_DefScreenRect.tl.x=8; /* 8 rows */
An automatically opened console is also set to the native mode of the machine. On the Series 3a machine
the console is opened in non-compatibility, with access to grey. In a PLIB program you may modify the
console mode by setting the global variable _pefscreenMode. The possible modes that may be set are:
use the native mode of the machine - this is the default value
compatibility mode, allowing Series 3 software to run on the Series 3a
non-compatibility mode, with grey enabled
compatibility mode, but with grey enabled
WN FO
Thus, compatibility mode may be set as follows:
GLDEF_D INT _DefScreenMode;
_DefScreenMode=1;
Values that are not relevant to a particular type of machine are simply ignored.
If used, the values of _DefScreenRect and _DefScreenMode must be set before the first usage of any
function that causes the console to be opened. Ignore the ‘duplication’ message generated by the linker
when this code is included in your application.
In CLIB programs you can prevent the automatic opening of a console channel by defining the function
p_xwind in your code, as in the following example:
extern void *winHandle;
void p_xwind (void)
{
winHandle=(void *)1;
}
int main(void)
{
return (0);
}
You should ignore the warning, given during the linking of your program, that the symbol _p_xwind is
duplicated.
2 CONSOLE
If you use this technique, your CLIB program should not, of course, make any reference to stdin, stdout
or stderr, unless you have redirected them. Setting winHandle to | (an illegal value for a handle) will
guarantee that any such reference will fail with a panic.
Explicit opening of a console channel
In a PLIB program you may, if you wish, explicitly open a console channel by means of p_open. The
console channel handle must be stored in the pre-defined static winHandle that is used for an
automatically opened console channel. For example:
GLREF_D VOID *winHandle;
p_open (&winHandle, "CON:",-1);
This is particularly important if your program uses any of the PLIB simple console I/O functions.
Otherwise you may inadvertently attempt to open two console channels from the same process and your
process will be panicked.
After explicitly opening the console and before making any other use of its services you must make it
visible by setting its size with the p_rseEt service, using the p_scr_wset function code.
Compatibility mode and the availability of grey can be set by means of the p_Fset service, using the
P_SCR_COMPATIBILITY and p_scr_GRey function codes.
P_FSET service call convention
The p_rset function provides a number of services, determined by a function code. The function code is
assigned to a uworp whose address is passed as the third parameter to the p_iow function. The convention:
INT p_iow(VOID *pcb, P_FSET, &P_SCR_CLR, P_RECT *prect);
is used to denote this. It should be interpreted as:
UWORD function;
function = P_SCR_CLR;
p_iow (pcb, P_FSET, &function,prect) ;
or equivalent.
Panics
All services (with the exception of p_open) will cause the calling process to be panicked if the passed
channel handle is not valid. Other panics are described under the particular service to which they apply.
SSS ee
Console services
p_open(CON:) Open the console
INT p_open(VOID **ppcb, CON:, -1);
Open a channel to the console device, writing the channel handle to *ppcb if successful. The console
window is not made visible until its size has been set by the p_rset service with a function code of
P_SCR_WSET.
When first opened the console properties are:
e auto wrap on
e auto flushing on
e — scroll lock off
e cursor display off
e pause key sequence enabled
e exit key sequence enabled (escape on)
e last line wrap (not available on MC) off
I/O DEVICES REFERENCE
It is recommended that ppcb should be the address of the pre-defined static winHandle, as in the
following example:
GLREF_D VOID *winHandle;
LOCAL_D UWORD func;
LOCAL_D INT err;
if ((err=p_open (&winHandle, "CON:",-1)) !=0)
{
fail:
p_notifyerr(err,"Failed to open console",NULL, NULL, NULL) ;
p_exit (0);
}
/* set the screen size */
rect.tl.x = rect.tl.y = 0;
rect.br.x 257
rect.br.y = 9;
func = P_SCR_WSET;
if ((err=p_iow4 (winHandle, P_FSET, &func, &rect) ) !=0)
{
p_close(winHandle) ;
goto fail;
}
You should not open the console yourself if your program is built with the CLIB start-up module.
The calling process is panicked if it already has an open channel to the console.
Returns zero if successful, or the negative error E_FILE_ALLOc if it failed to allocate memory for the
channel control block. In versions of EPOC prior to version 2.32, p_open("con:") will fail (and return a
negative number) if the total application memory usage exceeds 32k.
p_close Close the console
INT p_close(VOID *pcb) ;
Close the channel to the console.
Returns zero.
p_write Write to the console
INT p_write(VOID *pcb, UBYTE *buf, UWORD len);
Write len bytes of data from buf to the screen, starting at the current column (x coordinate) in the current
line (y coordinate). The value of 1en must be less than or equal to 255.
The request will always return immediately (but the text may not appear immediately if auto flushing is
turned off) and there is no advantage in calling this service in any way other than with p_write.
Characters are printed directly on the screen unless they are one of:
BELL sound the bell (buzzer)
TAB go to the next tab stop (tabs are every 8 characters)
BS backspace
CR move the cursor to the beginning of the current line
LF, VT move the cursor down one line
FF move the cursor down one screen
2 CONSOLE
If there are more characters in buf than will fit on the current line, the writing of the additional characters
depends on the auto wrap and scroll states as set by the p_rsEt service with function codes p_scR_WLOCK
and p_SCR_SLOCK:
e if auto wrap is on then any additional characters in buf are written from character position zero
in the following line. If this following line is off the screen then the screen will first be scrolled
up by one line, provided scroll lock is off.
e if auto wrap is off then the additional characters in buf successively overwrite the last character
in the line. On completion of the write request the last character in the row will therefore be the
final character in but. This assumes, of course, that there are no cursor movement characters in
buf.
The request cannot fail and so the function call always returns zero.
P_ FREAD Read a keypress
INT p_iow(VOID *pcb, P_FREAD, P_CON_KBREC *kbrec);_.VOID p_ioc(VOID *pcb, P_FREAD, WORD
*pstat, P_CON_KBREC *kbrec) ;
RRead a keypress record into the p_con_KBRECc struct pointed to by kbrec. The p_con_KBREC Struct is
defined in p_cons.h as:
typedef struct
{
UWORD keycode; /* Code for the key pressed */
UBYTE modifiers; /* State shift keys etc */
UBYTE count; /* Used to accumulate auto-repeat counts */
} P_CON_KBREC;
The content of modifiers is a set of bit flags indicating which modifier keys were held down when a key
was pressed:
W_SHIFT_MODIFIER SHIFT key down
W_CTRL_MODIFIER CONTROL key down
W_PSION_MODIFIER PSION key down
W_CAPS_MODIFIER Caps lock on
W_NUM_LOCK_MODIFIER Num lock on
The content of keycode for a standard keypress is simply its ASCII character code. There are also many
special values that the keycode can provide, corresponding to particular keypresses or keypress
combinations. These are fully described in the Events chapter of the Window Server Reference manual.
A P_FREAD request will not complete until either there is an outstanding keypress to read or the request is
cancelled. A synchronous request may therefore take an indefinitely long time to return. A prior
p_iow(P_FTEST) call will determine if there is an outstanding keypress.
The calling process is panicked if pcb is not a valid channel handle, or if there is an outstanding p_rFREAD
(Or P_EVENT_READ) request.
The completion status code is returned by the synchronous p_iow(P_FREAD) and written to *pstat by
asynchronous calls. The completion status code is zero if the p_rREAD request completed successfully, or
the negative error &_FILE_CANCEL if the request was cancelled by a p_FcaANCEL request.
P_FCANCEL Cancel an outstanding read
INT p_iow(VOID *pcb, P_FCANCEL) ;
Cancel an outstanding read; the request is harmless if there are no reads outstanding.
The request cannot fail and always returns zero.
P_FTEST Test for outstanding keypresses
INT p_iow(VOID *pcb, P_FTEST, UWORD *pflag);
Set *pflag to TRUE if there are any keypresses outstanding, otherwise set it to FALSE.
The request cannot fail and always returns zero.
1/0 DEVICES REFERENCE
P_FFLUSH Flush keyboard buffer
INT p_iow(VOID *pcb, P_FFLUSH) ;
Flush the keyboard buffer, all key presses held in the buffer are discarded.
The request cannot fail and always returns zero.
P_FEDIT Edit a string
INT p_iow(VOID *pcb, P_FEDIT, P_CEDIT *cedit, UWORD *plen);
Edit a string. The p_cepiT struct is defined in p_screen.h as:
typedef struct
{
UBYTE cursorpos; /* not used */
UBYTE trap; /* trap input errors or not */
UBYTE string[P_MAXEDITSTR]; /* string to edit */
} P_CEDIT;
Allows the user to edit the text in string. The cursor is initially positioned at the end of the string. The
user is not allowed to expand the string beyond *plen characters (string must be initially not more than
*plen characters in length). Since *plen does not include the terminating zero, its value must be Jess than
P_MAXEDITSTR (256).
Pressing the left or right arrow keys moves the cursor one character to the left or right in the string. The
HOME and END keys move the cursor to the start and end of the string.
Pressing Esc clears the content of the string. The value of trap determines what happens if Esc is pressed
when the string is already clear. If trap is TRUE, then the editing operation will complete with string
unchanged, if trap is FALSE then nothing will happen.
Returns zero, or E_LFILE_CANCEL if editing is terminated by pressing Esc.
P_FSENSE Sense console data
INT p_iow(VOID *pcb, P_FSENSE, P_RECTP *prectp) ;
Write the cursor position to (prectp->p.x,prectp->p.y) and write the window co-ordinates to prectp-
>x. The window co-ordinates are those specified by the most recent prior call to P_rsET with function code
P_SCR_WSET or P_SCR_CSET.
For example:
LOCAL_C VOID SenseConsole (VOID)
{
P_RECTP rectp;
WORD x_pos, y_pos, width, height;
p_iow (winHandle, P_FSENSE, &rectp) ;
X_pos = rectp.p.x;
y_pos = rectp.p.y;
width = rectp.r.br.x - rectp.r.tl.x;
height = rectp.r.br.y - rectp.r.tl.y;
/* do something with the coordinates here */
}
The request cannot fail and always returns zero.
2 CONSOLE
P_FSET, P_SCR_WSET Set the console window size
INT p_iow(VOID *pcb, P_FSET, &P_SCR_WSET, P_RECT *prect);
Set the console window size. A p_rEcT structure is used for historical reasons; in practice prect-
>rect .t1 should always be (0,0). For example, to set the console size to 9 lines high by 25 columns wide
(the full screen size for HC machines) you should use:
P_RECT rect;
UWORD func;
rect.tl.x rect.tl.y = 0;
rect.br.x = 25;
rect.br.y = 9;
func = P_SCR_WSET;
p_iow(winHandle, P_FSET, &func, &rect) ;
Returns zero if successful, otherwise the error =_GEN_NomEmory if unable to create a window of the new size.
P_FSET, P_SCR_SCROLL Scroll the window content
INT p_iow(VOID *pcb, P_FSET, &P_SCR_SCROLL, P_RECTP *pscrl)j;
Scroll the rectangle pscri->r by the vector amount (pscr1->p.x,pscrl->p.y). The area left behind the
trailing edge(s) is cleared. Scrolling a rectangle is not affected by setting or clearing the scroll lock.
pscrl->r describes the rectangle to scroll;
pscrl->p.x gives the horizontal distance to scroll (negative left, positive right);
pscrl->p.y gives the vertical distance to scroll (negative up, positive down).
For example:
LOCAL_C VOID scroll(WORD amnt_v, WORD amnt_h)
/* scroll the whole window vertically amnt_v and horizontally amnt_h */
{
UWORD func;
P_RECTP scrl;
p_iow(winHandle, P_FSENSE, &scrl);
scrl.r.br.x -= scrl.r.tl.x;
scrilsr.br vy == serlar.tl.y;
scrl.r.tl.x = 0;
scrl.r.tl.y = 0;
scrl.p.x = amnt_h;
scrl.p.y = amnt_v;
func = P_SCR_SCROLL;
p_iow(winHandle, P_FSET, &éfunc, &éscrl) ;
}
Returns zero.
P_FSET, P_SCR_CLR Clear a rectangle
INT p_iow(VOID *pcb, P_FSET, &P_SCR_CLR, P_RECT *prect);
Clear the rectangle *prect. If *prect extends outside the console window then it is clipped so that only
the part that intersects with the window is cleared.
For example:
LOCAL_C VOID clear(P_RECT *prect)
{
INT func;
func = P_SCR_CLR;
p_iow(winHandle, P_FSET, &éfunc,prect) ;
}
Returns zero.
I/O DEVICES REFERENCE
P_ FSET, P_SCR_NEL Position cursor to next line
INT p_iow(VOID *pcb, P_FSET, &P_SCR_NEL) ;
Move the cursor position to the first column on the next line. If the current row is the bottom row then,
provided scroll lock is not set, the window image scrolls up.
Returns zero.
P_FSET, P_SCR_POSA Set the cursor position (absolute)
INT p_iow(VOID *pcb, P_FSET, &P_SCR_POSA, P_POINT *ppoint);
Position the cursor to the point *ppoint. If *ppoint is outside the window the cursor moves to the the
position in the window closest to *ppoint.
Returns zero.
P_FSET, P_SCR_POSR Set the cursor position (relative)
INT p_iow(VOID *pcb, P_FSET, &P_SCR_POSR, P_POINT *ppoint);
Position the cursor by adding the displacement *ppoint to its current co-ordinates. If *ppoint is outside
the window the cursor moves to the the position in the window closest to *ppoint.
Returns zero.
P_FSET, P SCR_CURSOR Turn the cursor on or off
INT p_iow(VOID *pcb, P_FSET, &P_SCR_CURSOR, UWORD *pflag);
Turn the cursor off if *pflag is FALSE, turn it on if *pflag is TRUE.
Turning the cursor on or off has no affect on the screen driver output other than enabling or disabling the
display of the cursor.
Returns zero.
P_FSET, P_ SCR_SLOCK Set scroll lock
INT p_iow(VOID *pcb, P_FSET, &P_SCR_SLOCK, UWORD *pflag);
Turn scroll lock off if *pflag is FALSE, turn it on if *pflag is TRUE.
When scroll lock is on scrolling of the console (caused by either P_scR_NEL or p_write) is disabled. It has
no effect on scrolling by means of P_rsET with function code P_SCR_SCROLL.
Returns zero.
P_FSET, P_SCR_WLOCK Set auto wrap
INT p_iow(VOID *pcb, P_FSET, &P_SCR_WLOCK, UWORD *pflag);
Turn auto wrap off if *pflag is FALSE, turn it on if *pflag 1s TRUE.
If auto wrap is off then character printing by p_write stops at the right margin, with further characters
successively overwriting the last character in the line. If auto wrap is on then trying to write a character
beyond the end of the line causes the cursor to move to the start of the next line. If the cursor is in the last
line of the window (and scroll lock is off) this will cause a scroll.
Returns zero.
2 CONSOLE
P_FSET, P_ SCR_ESCAPE Set escape on or off
INT p_iow(VOID *pcb, P_FSET, &P_SCR_ESCAPE, UWORD *pflag);
Turn escape handling off if *pf1ag is FALSE, turn it on if *pflag iS TRUE.
If escape handling is off then the user will not be able to use the exit key sequence to exit the console
application. The exit key sequence is PSION-ESC on HC and Series 3 machines, PSION-E on (English-
language) MC machines (PSION-? on foriegn language MCs, where ? is a character that depends on the
language). Additionally, on MC machines, the stop menu button will be disabled when escape is off.
Escape handling is initially on.
Returns zero.
P_FSET, P_SCR_COMPATIBILITY Set compatibility on or off
INT p_iow(VOID *pcb, P_FSET, &P_SCR_COMPATIBILITY, UWORD *pflag);
This function code is only available on machines that contain version 4, or later, of the window server.
Turn compatibility off if *pf1ag is FALSE, turn it on if *pflag iS TRUE.
If compatibility is turned on, all drawing to the screen of the Series 3a is performed in double pixel mode.
On Series 3a machines, compatibility mode is initially on.
Returns zero.
Note: A tru value of *pf1ag must be the value 1. Any other non-zero value may be interpreted differently
on future machines.
P_FSET, P_SCR_GREY Set the use of grey on or off
INT p_iow(VOID *pcb, P_FSET, &P_SCR_GREY, UWORD *pflag);
This function code is only available on machines that contain version 4, or later, of the window server.
Turn the use of grey off if *pfiag 1s FALSE, turn it on if *pflag iS TRUE.
On Series 3a machines, the use of grey is initially off.
Returns zero.
Additional console services
The following services have been implemented to support OPL/g on HC and Series 3 machines. They are
not available on machines in the MC range.
If your application is sufficiently complex to require these services it is recommended that you consider
writing it as a window server application rather than using the console device.
P_EVENT READ Read an event
INT p_iow(VOID *pcb, P_EVENT_READ, P_CON_KBREC *kbrec) ;
VOID p_ioc(VOID *pcb, P_EVENT_READ, WORD *pstat, P_CON_KBREC *kbrec) ;
RRead an event record (including keypress events) into the p_con_KBrREc struct pointed to by kbrec. The
P_CON_KBREC Struct is defined in p_cons.h as:
typedef struct
{
UWORD keycode; /* Code for the key pressed */
UBYTE modifiers; /* State shift keys etc */
UBYTE count; /* Used to accumulate auto-repeat counts */
} P_CON_KBREC;
I/O DEVICES REFERENCE
If the event was a keypress (a wM_KEy event) the result is exactly as for a P_FREAD request, described
earlier.
Other window server events result in one of the following values being written to keycode:
CONS_EVENT_FOREGROUND received a WM_FOREGROUND event
CONS_EVENT_BACKGROUND received a WM_BACKGROUND event
CONS_EVENT_ON_OFF received a WM_ON event
CONS_EVENT_COMMAND received a WM_COMMAND event
Future versions of the console device may report additional event types. Applications should be written to
ignore event types other than those listed above.
A P_EVENT_READ request will not complete until either an event is received or the request is cancelled. A
synchronous request may therefore take an indefinitely long time to return. A prior p_iow (P_EVENT_TEST)
call will determine if there is an outstanding event to be read.
The calling process is panicked if pcb is not a valid channel handle, or if there is an outstanding
P_EVENT_READ (or P_FREAD) request.
The completion status code is returned by the synchronous p_iow(P_EVENT_READ) and written to *pstat
by asynchronous calls. The completion status code is zero if the P_LEVENT_READ request completed
successfully, or the negative error E_LFILE_CANCEL if the request was cancelled by a P_FcANCEL request.
P_EVENT_ TEST Test for outstanding event
INT p_iow(VOID *pcb, P_EVENT_TEST, UWORD *pflag);
Set *pflag to TRUE if there are any events (including keypress events) outstanding, otherwise set it to
FALSE.
The request cannot fail and always returns zero.
P_FINQ Get console data
INT p_iow(VOID *pcb, P_FINQ, CONSOLE_INFO *pinfo);
Return information about the window server resources used by the console. coNSOLE_iInFo is defined in
p_cons.has:
typedef struct
{
UINT window_handle; /* window server id of the console window */
UINT font_handle; /* window server id of the console font */
UINT line_height; /* pixel height of a console line - font height + leading */
UINT char_width; /* pixel width of a monospaced console character */
} CONSOLE_INFO;
Returns zero.
P_FWFLUSH Flush window server buffer
INT p_iow(VOID *pcb, P_FWFLUSH) ;
Flush the commands buffered to the window server - has no effect when auto flushing is on.
Returns zero.
P_FSET, P_SCR_CSET Set the console output rectangle
INT p_iow(VOID *pcb, P_FSET, &P_SCR_CSET, P_RECT *prect);
Set the console output rectangle. All subsequent output is restricted (and wrapped) to the rectangle
described by prect within the console window.
Returns zero if successful, or E_GEN_aRG if any part of prect is outside the console window (i.e. either of
prect->tl.x Or prect->t1.y is less than zero, or prect->br.x Of prect->br.y respectively exceed the
width or height of the console window).
2-10
2 CONSOLE
P_FSET, P_SCR_ATTRB Set character attributes
INT p_iow(VOID *pcb, P_FSET, &P_SCR_ATTRB, UWORD *pattrib);
Set the character attributes (style) to be used to display future characters written to the console. This
service permits the mixing of a number of different styles in the console window.
The value of *pattrib may be
P_SCR_NORMAL No additional style
or any combination of the bit flags:
P_SCR_BOLD Bold
P_SCR_REVERSE Reverse video
P_SCR_UNDLINE Underlined
P_SCR_BLINK Blinking
P_SCR_ITALIC Italics
It is not guaranteed that all the above attributes are supported in all versions of the console for the HC and
Series 3, but unsupported attributes are harmlessly ignored.
Any attribute which would have the effect of changing the width of a displayed character (such as
P_SCR_BOLD in current machines) is ignored. At the time of writing, no machine supports p_scR_BLINK.
For example:
UWORD func;
UWORD attrib;
p_printf("This is normal");
func = P_SCR_ATTRB;
attrib = P_SCR_UNDLINE;
p_iow (winHandle, P_FSET, &func, &attrib) ;
p_printf("This is underlined");
attrib = P_SCR_NORMAL;
p_iow (winHandle, P_FSET, &func, &attrib) ;
p_printf ("Back to normal text");
Returns zero.
P_FSET, P SCR_FONT Set the screen font
INT p_iow(VOID *pcb, P_FSET, &P_SCR_FONT, P_SCR_SET_FONT *pfont);
Set the console font and style for the entire window to those specified by the content of the
P_SCR_SET_FONT Struct pointed to by pfont. The struct is defined in p_cons.h as:
typedef struct
{
UWORD id; /* font id */
UWORD style; /* font style */
} P_SCR_SET_FONT;
The allowed values for the font ia and style are those that are appropriate for setting a window server
graphics context (see the Window Server Reference manual). Note that the font must be monospaced; if
you set id to be the font id of a proportional font you should also include G_sty_mono in style.
For example:
UWORD func;
P_SCR_SET_FONT font;
font.id = WS_FONT_BASE;
font.style = G_STY_MONO|G_STY_DOUBLE;
func = P_SCR_FONT;
p_iow(winHandle, P_FSET, &func, &font) ;
Since the size of the console window may be altered by changing the font, a call to p_rserT with function
code p_scr_Font will automatically clear and resize the console.
I/O DEVICES REFERENCE
It is not possible to mix different fonts and/or styles in the console window by means of this service.
Certain aspects of the font style may be changed using the P_FsET service with function code
P_SCR_ATTRB.
Returns zero.
P_FSET, P_SCR_LAST_ LINE WRAP Set the last line wrap
INT p_iow(VOID *pcb, P_FSET, &P_LAST_LINE_WRAP, UWORD *pflag);
Turn last line wrap on if *pflag is TRUE, turn it off if *pflag is FALSE.
If last line wrap is off then the display immediately wraps and scrolls (provided wrapping and scrolling
are not disabled) when a character is printed to the bottom right position in the console.
Last line wrap is initially off.
Returns zero.
P_FSET, P_SCR_FLUSH Set window server flushing
INT p_iow(VOID *pcb, P_FSET, &P_SCR_FLUSH, UWORD *pflag);
Disable auto-flushing if *pflag is FALSE, enable it if *pflag is TRUE.
Auto-flushing is initially enabled.
When auto-flushing is enabled each window server function call is flushed immediately.
If auto-flushing is disabled, one or more window server function calls may be buffered. Execution of a
window server function may therefore be deferred until after the initiating function call has returned. In
such a case a function may return a window server error that was caused by an earlier, but buffered,
function call.
Returns zero.
P_FSET, P_SCR_DISABLE_READS Disable reads
INT p_iow(VOID *pcb, P_FSET, &P_SCR_DISABLE_READS, UWORD *pflag) ;
Disable reads if *pflag is TRUE, enable reads if *pflag iS FALSE.
A console application which needs to receive events directly from the window server, by calling
wGetEvent, should first disable reads. Otherwise all events are preferentially reported to the console.
No P_FREAD Of P_EVENT_READ request should be outstanding when this service is called and no more reads
may be performed until reads are re-enabled.
Initially reads are enabled.
Returns zero.
P_FSET, P_SCR_CLIENT_FOREGROUND Bring to foreground
INT p_iow(VOID *pcb, P_FSET, &P_SCR_CLIENT_FOREGROUND, UWORD *pid);
Make the process with process ID *pid the foreground process. Use a value of zero for «pid to bring the
current process to the foreground.
The service does nothing if the process specified by *pid does not exist.
Returns zero.
2 CONSOLE
P_FSET, P_SCR_CAPTURE KEY Capture a key
INT p_iow(VOID *pcb, P_FSET, &P_SCR_CAPTURE_KEY, CONSOLE_CAPTURE_KEY *pcapt) ;
Specify a keypress that is to be sent to the calling process, irrespective of its foreground/background status.
The keypress combination to be captured is specified by the content of the consoLE_CAPTURE_KEY Struct,
defined in p_cons.h as:
typedef struct
{
UWORD code;
UBYTE modifier_mask;
UBYTE dont_care_mask;
} CONSOLE_CAPTURE_KEY;
Every time a key is pressed the window server evaluates
(key_pressed==code) && ((key_pressed_modifiersédont_care_mask) ==modifier_mask)
and if the result is TRuz then the keyboard event is sent to the process that specified the capture.
For example,
UWORD func;
CONSOLE_CAPTURE_KEY capture;
capture.code = W_SPECIAL_KEY|'a';
capture.modifier_mask = W_PSION_MODIFIER;
capture.dont_care_mask = W_PSION_MODIFIER|W_SHIFT_MODIFIER;
func=P_SCR_CAPTURE_KEY;
p_iow (winHandle, P_FSET, &func, &capture) ;
captures PSION+A and PSION+CTRL+A.
See also the equivalent window server function wcapturekey, described in the Window Server Reference
manual. The struct elements code, modifier_mask and dont_care_mask correspond to the wcaptureKey
parameters keycode, modifiers and modifier_mask respectively.
Returns zero if successful, or =_FILE_ExIst if the specified keycode/modifier combination is currently
captured by any process.
P_FSET, P_SCR_CANCEL_CAPTURE_KEY Cancel a key capture
INT p_iow(VOID *pcb, P_FSET, &P_SCR_CANCEL_CAPTURE_KEY, CONSOLE_CAPTURE_KEY *pcapt) ;
Cancel a key capture set up by p_rset with function code p_scR_caPTURE_KEY. The content of pcapt must
exactly match that used to initiate the capture.
Returns zero if successful, or E_F1LE_nx1st 1f the keycode/modifier combination is not marked as
captured.
I/O DEVICES REFERENCE
Example
The following short program exercises many of the services described above. It consists of two parts, the
first of which simply receives keys typed by the user and reports them by type on the screen. The second
part enables the user to scroll a part of the display and to set the console attributes (scroll lock, line wrap
etc) to see how they affect the way typed characters are displayed.
#include <plib.h>
#include <p_cons.h>
#include <wskeys.h>
GLREF_D VOID *winHandle;
LOCAL_D P_RECTP RectP;
#define CON_HEIGHT 9
#define CON_WIDTH 25
LOCAL_C VOID doSetMode (UWORD mode, VOID *al)
/*
Shell to P_FSET
Hf,
{
INT err;
if ((err=p_iow4 (winHandle, P_FSET, &mode, al) ) !=0)
p_notifyerr(err,"Set service failed",NULL,NULL, NULL) ;
LOCAL_C VOID clear_line (VOID)
/*
position cursor to begining of the line and clear the line
*/
{
P_RECTP rectp;
p_iow3 (winHandle, P_FSENSE, &rectp) ;
rectp.p.x = 0;
doSetMode (P_SCR_POSA, &rectp.p) ;
rectp.r.tl.x = 0;
rectp.r.br.x = CON_WIDTH;
rectp.r.tl.y = rectp.p.y;
rect.r.br.y = rectp.p.y + 1;
doSetMode (P_SCR_CLR, &rectp.r);
}
LOCAL_C VOID ReportKey (VOID)
{
P_CON_KBREC kbrec;
p_printf ("Press Any Key (ESC quits)\r\n");
FOREVER
{
p_iow3 (winHandle, P_FREAD, &kbrec) ;
clear_line();
if (kbrec.modifiers&W_PSION_MODIFIER)
p_printf ("Psion key %x",kbrec.keycode) ;
else if (p_isprint (kbrec.keycode) )
p_printf ("Normal key %c",kbrec.keycode) ;
else if (kbrec. keycode==W_KEY_ESCAPE)
break;
else
p_printf("Non printable key %x",kbrec.keycode) ;
LOCAL_C VOID TryModes (VOID)
{
INT wrap_lock,scroll_lock, escape;
P_RECTP rectp;
P_CON_KBREC kbrec;
escape = TRUE; /* set toggle flags to default values */
wrap_lock = TRUE;
scroll_lock = FALSE;
rectp.r.tl.x = 5; /* define a rectangle for scrolling */
rectp.r.tl.y = 1;
rectp.r.br.x = 20;
rectp.r.br.y = 6;
FOREVER
{
p_iow3 (winHandle, P_FREAD, &kbrec) ;
if (! (kbrec.modifiers&W_PSION_MODIFIER) )
{
if (p_isprint (kbrec.keycode) )
p_putch (kbrec.keycode) ;
else if (kbrec.keycode==W_KEY_RETURN)
doSetMode (P_SCR_NEL, 0);
else if (kbrec.keycode=='\b')
/* make backspace destructive */
p_print("\b \b");
else if (kbrec.keycode==W_KEY_ESCAPE)
break;
}
else
{
kbrec.keycodeé&=(~W_SPECIAL_KEY) ;
switch (kbrec. keycode)
{
case W_KEY_LEFT:
rectp.p.x = (-1);
rectp.p.y = (-1);
scroll: doSetMode (P_SCR_SCROLL, &rectp) ;
break;
case W_KEY_RIGHT:
rectp.p.x = (1);
rectp.p.y = (1);
goto scroll;
case W_KEY_DOWN:
rectp.p.x = 1;
rectp.p.y = 0;
goto scroll;
case W_KEY_UP:
rectp.p.x = (-1);
rectp.p.y = 0;
goto scroll;
case 'w': /* PSION modifier always gives lower case key */
wrap_lock = !wrap_lock;
doSetMode (P_SCR_WLOCK, &wrap_lock) ;
break;
case 's':
scroll_lock = !scroll_lock;
doSetMode (P_SCR_SLOCK, &scroll_lock) ;
break;
case 'q':
escape = !escape;
doSetMode (P_SCR_ESCAPE, &escape) ;
break;
default: /* do nothing */
break;
}
2 CONSOLE
I/O DEVICES REFERENCE
GLDEF_C INT main(VOID)
/*
Allow user to type characters etc
xf
{
INT err;
P_RECT rect;
if ((err=p_open (&winHandle, "CON:",-1)) !=0)
{
p_notifyerr(err,"No Console device",NULL, NULL, NULL) ;
p_exit (0);
}
rect.tl.x = rect.tl.y = 0; /* set the screen size */
rect.br.x = CON_WIDTH;
rect.br.y = CON_HEIGHT;
doSetMode (P_SCR_WSET, &rect) ;
p_printf ("Simple console program") ;
ReportKey ();
p_putch(0x0c) ; /* form feed to clear screen */
p_printf ("Type characters or:");
p_printf ("Psion <- scrolls left/up");
p_printf ("Psion -> scrolls rght/dn");
p_printf("Psion Down scrolls down");
p_printf("Psion Up scrolls up");
p_printf("Psion W toggles wrap lock");
p_printf("Psion S toggles scrl lock");
p_printf("Psion Q toggles escape");
TryModes () ;
p_close(winHandle) ;
return(0);
}
CHAPTER 3
PARALLEL PORT
Pc 9 EEEEEEEEEEE—— Ss
Introduction
One or more standard centronics parallel ports are available on all SIBO machines, in the form of either a
dual serial/parallel expansion module (for example, the HC and MC ranges) or a parallel expansion
module (such as the parallel 3-link for the Series 3). The HC cradle provides a third parallel port.
Parallel port device names
Depending on the number and location of ports available, the port device names are "PAR:A", "PAR:B" and
"PAR:C". For example, the Series 3 recognises only "PaAR:a", but an MC fitted with two serial/parallel
expansion modules recognises "Ppar:a" (left hand module, looking from the front of the machine) and
"PAR:B" (right hand module, looking from the front of the machine).
The parallel port driver is an output-only device driver that does not support a read service.
Panics
All services (with the exception of p_open) will cause the calling process to be panicked if the passed
channel handle is not valid. Other panics are described under the particular service to which they apply.
Parallel port services
p_open(PAR:) Open a parallel port
INT p_open(VOID **pcb, TEXT *pname, -1);
Open a channel to the parallel port *pname, where pname points to the string "PAR:A", "PAR:B" OF
"PAR:C", writing the address of the channel control block to *pcb.
The parallel port lines are powered up and all control lines are cleared low. The port will continue to
consume power until the channel is closed.
Returns zero if successful, or one of the following negative error numbers:
E_FILE_ALLOC failed to allocate memory for the control block
E_FILE_DEVICE the port does not exist
E_FILE_LOCKED or the port is already open
E_GEN_INUSE
p_close Close a parallel port
INT p_close(VOID *pcb);
Power down the parallel port lines and close the port channel corresponding to the specified control block,
first cancelling any outstanding Pp_FwRITE request.
Returns zero.
1/0 DEVICES REFERENCE
P_FWRITE Write to a parallel port
INT p_iow(VOID *pcb, P_FWRITE, VOID *buf, UWORD *plen);
VOID p_ioc(VOID *pcb, P_FWRITE, WORD *pstat, VOID *buf, UWORD *plen)j;
Write *plen bytes of data from buffer buf to the parallel port. It is the user's responsibility to preserve the
data at *pbuf and *plen until the write request completes.
The write request will never complete if the parallel port is not physically connected to a functioning
receiver. It is therefore advisable always to write asynchronously to the parallel port, and to use a timer
that provides a timeout on each write, as illustrated in the example at the end of this chapter.
Panics if a P_FWRITE request is currently outstanding, or if pcb is not a valid channel handle.
The completion status code is returned by the synchronous p_iow(P_FWRITE) and written to *pstat by
asynchronous calls. The completion status code is zero if the P_FWRITE request completed successfully, or
one of the following negative error numbers:
E_FILE_WRITE failed to write
E_FILE_CANCEL the write was cancelled by a call to the P_FcANCcEL service
P_FCANCEL Cancel a write request
INT p_iow(VOID *pcb, P_FCANCEL) ;
Cancel any outstanding P_FwRITE request, causing it to complete with an E_FILE_CANCEL completion code.
If a write request is outstanding then an indeterminate amount of data will have been written to the
parallel port before the request is cancelled.
Performing a cancel is harmless if no write request is outstanding.
Returns zero.
P_FSENSE Sense the input control lines
INT p_iow(VOID *pcb, P_FSENSE, UWORD *port);
This service is not, at the time of writing, available for any version of either the Series 3 or the Series 3a.
It is only available for machines in the HC and MC ranges that contain EPOC with a version number of
2.30 or later.
Write the current values of the centronics port input control lines to *port (all control lines are cleared
low when the port is opened).
The input control line values are defined, in p_par.h, according to the following table, where the pin
numbers are those appropriate for a 25-way D-type connector.
Symbol Control line Pin number
S_BUSY Busy 11
S_ACK Acknlg 10
S_ERROR Error 15
S_PE Paper error 12
Following the call, the values of the remaining bits at *port are undefined.
Returns zero.
P_FSET Write the output control lines
INT p_iow(VOID *pcb, P_FSET, UWORD *type, UWORD *port);
This service is not, at the time of writing, available for any version of either the Series 3 or the Series 3a.
It is only available for machines in the HC and MC ranges that contain EPOC with a version number of
2.30 or later.
Set or clear the centronics output control lines (all control lines are cleared low when the port is opened).
3-2
3 PARALLEL PORT
If *t ype is 1 then the control lines corresponding to the bits set in *port will be set high.
If *t ype is 0 then the control lines corresponding to the bits set in *port will be cleared low.
The output control line values are defined, in p_par.h, according to the following table, where the pin
numbers are those appropriate for a 25-way D-type connector.
Symbol Control line Pin number
S_SPARE === See below
S_INIT Init 16
S_AUTOFD Autofeed 14
S_SELECT Select 17
Any other bits set in *port are ignored.
The s_sparz bit is not available on the centronics connector. It may be of use in custom hardware designs
as it corresponds to pin 42 of the Psion-specific custom peripheral chip, astcs5. Changing this bit will
have no effect on the standard RS232/parallel expansion module.
Returns zero.
EEE
Example
The following example copies one or more files to a parallel port. It uses many of the parallel port
services, and illustrates the use of a timer to provide a timeout in conjunction with the p_rwRITE service.
include <p_std.h>
include <p_sys.h>
include <p_file.h>
include <epoc.h>
LOCAL_D VOID *fcb=NULL;
LOCAL_D VOID *pcb=NULL;
LOCAL_D VOID *tcb=NULL;
LOCAL_C VOID Report (INT err)
TEXT buf [E_MAX_ERROR_TEXT_SIZE];
p_errs (&buf[0],err);
p_printf("%s", &buf[0]);
}
LOCAL_C INT BufToParallel (VOID)
{
WORD len;
WORD pstat,tstat;
ULONG time;
TEXT buf [64];
len=p_read(fcb, &buf[0], 64);
if (len>=0)
{
p_ioc5 (pcb, P_FWRITE, &pstat, &buf[0],é&len) ;
time=50; /* 5 second timeout */
p_ioc4 (tcb, P_FRELATIVE, &tstat, &time) ;
p_iowait ();
if (pstat==E_FILE_PENDING) /* timer timed out */
{
p_iow2 (pcb, P_FCANCEL) ;
p_waitstat (&pstat) ;
return (E_FILE_CANCEL) ;
}
p_iow2 (tcb,P_FCANCEL); /* cancel timer */
p_waitstat (&tstat) ;
}
return (len);
}
1/0 DEVICES REFERENCE
LOCAL_C VOID FileToParallel (VOID)
{
INT err;
if ((err=p_open(&pcb, "PAR:A",-1))<0) /* open parallel port */
{
Report (err) ;
return;
}
FOREVER
{
if ((err=BufToParallel()) <0)
{
if (err!=E_FILE_EOF)
Report (err) ;
break;
}
}
p_close (pcb);
pcb=NULL;
}
GLDEF_C INT main(VOID)
{
INT err;
TEXT bb[P_FNAMESIZE];
if ((err=p_open(&tcb,"TIM:",-1))<0) /* open timer for timeouts */
{
Report (err) ;
return (0);
}
while (p_getl("Enter file name:
{
if ((err=p_open (&fcb, &bb[0],P_FOPEN|P_FSTREAM) ) <0) /* open a file */
{
Report (err);
continue;
}
FileToParallel();
p_close(fcb);
}
p_close(tcb);
return(0);
}
Note that this example is based on the assumption that the only two asynchronous events that can occur
are the completion of a write to the parallel port and the expiry of the timer. For further discussion of a
more general case, see the description of p_ioc in the PLIB Reference manual.
", &bb[0],P_FNAMESIZE) )
CHAPTER 4
SERIAL PORT
eee ————————>>>——EE—————>>>>eE~— Ss
Introduction
The serial driver in the EPOC operating system supports a fully interrupt driven industry-standard RS-232
serial link.
The driver consists of two cooperating layers. The lower driver is a physical device driver (PDD). It
provides a set of services that hide any hardware dependencies from the upper layer.
The upper layer of the driver is a logical device driver (LDD). It provides the logical (hardware
independent) services that are described in this chapter. Incoming data is buffered at this level.
Serial port device names
The first serial port on a SIBO machine has the device name "Tty:a". Many machines in the SIBO range
have more than one serial port available; a second port has the device name "TTy:8". For example, a
Series 3 fitted with a 3 Link (RS232) recognises only "tty:a", but an MC fitted with two serial/parallel
expansion modules recognises "TTy:a" and "tTy:B" (left and right hand modules respectively, looking
from the front). HC machines have a third port, on the cradle, with the device name "TTy:c".
HC machines also support serial ports with TTL level signals with device names "TTY:D", "TTY:E",
"TTy:F" (direct TTL levels) and "tTv:c", "TTy:H", "TTY:1" (inverted TTL levels). These ports are not
described in this chapter.
Panics
All services (with the exception of p_open) will cause the calling process to be panicked if the passed
channel handle is not valid. Other panics are described under the particular service to which they apply.
eee
Serial port parameters
The serial port parameters are set and sensed with the aid of a p_sRcuar struct, defined in p_serial.h as:
typedef struct
UBYTE tbaud; /* transmit baud rate */
UBYTE rbaud; /* receive baud rate */
UBYTE frame; /* number of data, parity and stop bits */
UBYTE parity; /* parity type */
UBYTE hand; /* handshake flags */
UBYTE xon; /* XON character */
UBYTE xoff; /* XOFF character */
UBYTE flags; /* controlling flags */
ULONG tmask; /* terminator mask */
} P_SRCHAR;
The possible settings are described in the following subsections.
One of the major problems with serial communications is ensuring that both ends of a physical link are
using the same port parameters. Typically, if one or more of the parameters differ, some data may be
transferred successfully whilst other data may not. This can make it difficult to determine which
parameter is incorrect.
1/0 DEVICES REFERENCE
Baud rate (tbaud, rbaud)
The Baud rate is, strictly speaking, a measure of the electrical signalling rate (the frequency of electrical
impulses) of a communications link. In practice, however, it is used to specify the data transfer rate, in
bits per second. The Baud rate and the data transfer rate are equal if one bit of data is encoded in each
signalling period.
For back-to-back serial communications the Baud rate and the data transfer rate are equivalent. It is only
when considering data transfer over a modem that the Baud rate and data transfer rate may differ.
Typically, modems that transfer data at a rate higher than 1200 bits per second encode more than | bit of
data into a single signalling period. For such a modem the Baud rate will differ from the data transfer
rate.
The transmit and receive Baud rates (tbaud and rbaud respectively) may be set to one of the following
values, which are defined in p_serial.h:
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
P_BA
D_50
D_75
D_110
D_134
D_150
D_300
D_600
D_1200
D_1800
D_2000
D_2400
D_3600
D_4800
D_7200
D_9600
D_19200
D_38400
D_56000
U
U
U
U
U
U
U
U
U
U
U
U
U
U
U
U
U
U
The default value for both tbaud and rbaud is P_BAuD_9600. None of the SIBO serial port hardware
currently supports split Baud rates (separate transmit and receive Baud rates).
All machines in the SIBO range support Baud of rates of P_BAUD_50 to P_BAUD_9600 inclusive. In addition
the MC 200, MC 400 and Series 3a machines support a rate of P_BAUD_19200. The HC and Series 3
machines can also be set to use P_BAUD_19200. However, the clock speed on current machines is slightly
too slow to handle this rate of data transfer, and overrun errors occur fairly frequently. Error correcting
protocols (eg Link) will run on the HC and Series 3 at 19200 Baud but, because of the high number of
retransmissions, they are slower than if they were run at 9600 Baud.
At 19200 Baud an interrupt occurs approximately every 500 microseconds. The following table shows the
number of instruction cycles available on a range of machines between two interrupts occurring at this
rate.
Machine Clock speed Instruction cycles
HC 3.84MHz 480
Series 3 3.84MHz 480
Series 3a 7.68MHz 960
IBM PC/AT 4.77MHz 596
MC 200/400 7.68MHz 960
Character frame (¢rame)
The basic unit of transmission is the RS-232 asynchronous character frame. This is a sequence of bits
which consists of one start bit, between five and eight data bits, an optional parity bit and one or two stop
bits.
The start and stop bits are used to synchronise the data transmission.
The number of data bits required largely depends on the nature of the data that is being transferred. For
example, eight data bits are needed to transmit arbitrary binary data bytes, but seven bits are sufficient to
transmit text, containing only ASCII character codes with values not exceeding Ox7F.
Including a parity bit provides for an elementary degree of error detection in the transmitted data.
4-2
4 SERIAL PORT
The value of frame describes the character frame. It may contain one of one of the following values,
defined in p_serial.h:
P_DATA_5 5 data bits
P_DATA_6 6 data bits
P_DATA_7 7 data bits
P_DATA_8 8 data bits
The value in frame may be ored with any combination of:
P_TWOSTOP 2 stop bits if set, 1 if clear
P_PARITY parity bit is present if set
All SIBO machines support all of the above settings. The default value of frame is
P_DATA_8
for eight data bits, one stop bit and no parity.
In the majority of cases the total number of bits needed to transmit a single character is close to ten (for
example, one start bit, seven data bits, one parity bit and one stop bit). As a result, a reasonable estimate
of the character transfer rate is usually found by dividing the Baud rate by ten.
Parity (parity)
If present, the parity bit may be set or cleared to ensure that the combined sum of the set data and parity
bits is either odd (odd parity) or even (even parity). Alternatively it may be always set (mark parity) or
always clear (space parity). If the p_parrty bit is set in fiela, then parity should be set to one of the
following values, defined in p_serial.h:
P_PAR_EVEN even parity
P_PAR_ODD odd parity
P_PAR_MARK mark parity
P_PAR_SPACE space parity
Provided that p_partty is set in frame, the parity bit is generated (for transmission) and verified (on
receipt) by the port hardware. Reporting of parity errors may be suppressed by setting p_IGNORE_PARITY in
flags (see below).
The default value of parity is zero. No machine in the SIBO range supports either mark or space parity.
Handshaking (xon, xoff, hand)
Handshaking (also called flow control or buffer control) is a mechanism by which either end of a
communications link can pause and restart data transmission from the other end. There are two basic
forms:
e software handshaking
e hardware handshaking
Handshaking is required to prevent one end from sending data faster than the receiving end can process it.
For example, you may be able to send data to a printer at 9600 Baud, but it is unlikely that the printer is
capable of printing 960 characters per second. The printer will use handshaking to suspend the
transmission of data from time to time (when its internal buffer becomes full) and restart it when it is able
to receive more characters (some buffer space becomes available).
Software handshaking involves the transmission of particular characters, one to suspend and one to
resume transmission. This is usually called XON/XOFF handshaking, since the characters normally
selected to suspend and resume transmission are XOFF (0x13, pc3) and XON (0x11, pDc1) respectively.
Other characters may be used, provided that both ends of the communications link agree.
Software handshaking can sensibly be used only to transfer data that has pure textual content. Arbitrary
binary data may include bytes with values equal to one or other of the handshaking control characters.
The remote end will not be able to distinguish between such a character being sent as data or as a
handshaking control. For example, a WordStar file may contain the binary value 0x13 (XOFF) as an
underscore range marker. On receipt of this character the remote end will not transfer any data until it
receives an XON and so the transfer process may hang. More importantly, the XOFF character will be
removed from incoming data, being interpreted as a control character rather than as data. Thus, in the
above example, underscore range markers will be lost during the transfer.
The character codes used to resume and suspend transmission in software handshaking are stored in xon
and xoff. The default values are DC1 (0x11) and DC3 (0x13) respectively.
I/O DEVICES REFERENCE
Hardware handshaking involves the setting of a particular electrical state on specific control lines. It
usually involves a pair of lines, the output from one end being the input to the other, and vice versa. A
common cause of failure of hardware handshaking is the use of an improperly wired cable. Various
control line combinations may be used, as listed below.
DSR/DTR This form of handshaking uses the RS-232 control lines Data Set Ready (DSR)
and Data Terminal Ready (DTR). These lines were not originally intended for
use as data flow control lines, but were meant to be used to indicate the
presence or absence of a remote machine. However, many printers use
DSR/DTR handshaking to control the flow of data from a computer.
The receiver's output line (DTR) is held inactive (-ve) to suspend data transfer
and set active (+ve) to resume data transfer. This signal is expected to arrive
on the remote (sending) machine's DSR input line.
RTS/CTS This form uses the RS-232 control lines Request To Send (RTS) and Clear To
Send (CTS). These lines are the ones originally intended for use to control data
flow from either end. RTS/CTS handshaking is normally used for hardware
handshaking with a modem, and the DSR and DTR lines are used for their
originally intended purposes of indicating that a remote machine exists and the
port is open.
The output line (RTS) is held inactive (-ve) to suspend data transfer and set
active (+ve) to resume data transfer. This signal is received by the remote
machine via the CTS input line (ie its now Clear To Send data).
The Data Carrier Detect (DCD) line is not a control of flow handshaking line as described above. It is a
condition indicator from a modem to indicate that a connection now exists with a remote modem. The
DCD signal is an input only signal and there is no corresponding output line.
The form of handshaking to be used is specified by the value of hana. It should contain a combination of
the following bits, defined in p_serial.h:
P_OBEY_XOFF If set, receipt of the characters specified in xoff and xon suspend and resume
data transmission. If clear, these characters are treated as ordinary data. This
controls input XON/XOFF handshaking, which is independent of output
XON/XOFF handshaking.
P_SEND_XOFF If set, the characters specified in xoff and xon are transmitted to the remote
device to suspend and resume data transmission from the remote device. This
controls output XON/XOFF handshaking, which is independent of input
XON/XOFF handshaking.
P_IGN_CTS If clear, the driver will set its RTS line inactive to suspend transmission from
the remote device, and transmission will be suspended when the remote device
sets its RTS (incoming CTS) line inactive (RTS/CTS handshaking). If set, then
RTS is permanently active and the state of the input CTS line is ignored.
P_OBEY_DSR If set, transmission will be suspended when the remote device sets its DTR
(incoming DSR) line inactive (DTR/DSR handshaking). If clear, the state of
the incoming DSR line is ignored. In all cases the DTR line is held
permanently active while the seial port is powered up and open.
P_FAIL_DSR This is ignored unless p_oBEY_pDsR is set. If P_FAIL_DsR is set and the remote
device sets its DTR line inactive then any outstanding P_FWRITE or P_FREAD
request is completed with an E_FILE_LINE error (rather than simply suspending
transmission). The CCITT recommendations state that a serial port should hold
its DTR line active while the port is powered up and active. Setting
P_FAIL_psR allows application code to detect that a conforming remote device
has been removed or the connection broken.
P_OBEY_DCD If set, then transmission is suspended if the remote device sets the incoming
DCD line inactive. If clear, the state of the DCD line is ignored.
P_FAIL_DCD This is ignored unless P_oBEY_pDcD is set. If P_FAIL_pcp is set and the remote
device sets the incoming DCD line inactive then any outstanding P_FWRITE or
P_FREAD request is completed with an &_FILE_LINE error (rather than simply
suspending transmission).
4 SERIAL PORT
The default value of hana is zero, setting RTS/CTS handshaking.
In addition to using the control lines for hardware data flow control (which is transparent to the
application code), the serial port services allow the explicit testing of the state of the control lines or, for
example, to wait for the DCD line to be driven by a modem.
Control flags (¢1ags)
The control flags specify how the device driver should handle certain events. At the time of writing there
is only one control flag, defined in p_serial.h:
P_IGNORE_PARITY The presence or absence of a parity bit in received data is not under the
receiver's control. Setting p_1GNoRE_PaRITy causes the serial driver to discard
any parity errors on received data. A character received with a parity error is
placed in the receive buffer and treated as a normal character, even though it
may be in error.
For future compatibility the remaining bits of £1ags should be zero.
The default value of £1ags is zero.
Terminator characters (tmask)
A receiver has no universally reliable way of knowing when the transmitter has no more data to send.
Once some data has been received, the receiver may be entitled to assume that a period (say, five seconds)
in which no data arrives means that no further data will arrive. Clearly, this is not foolproof.
This problem may be solved provided that the transmitter cooperates with the receiver to the extent of
sending mutually agreed terminating characters.
One or more terminating characters may be specified by setting one or more bits of tmask. This consists of
32 bit flags, each corresponding (in order, from bit zero to bit 31) to a terminating character code in the
range 0x00 to ox1f inclusive.
Thus, setting bit zero (0x00000001) selects character code 0x00 to be a terminating character and setting
bit 26 (0x04000000) selects crru—z. An important use is to set bit 13 and/or bit 10 to select cr and/or Lr.
This allows text to be read a line at a time from a serial port.
The default value of tmask is zero, to select no terminating characters.
Serial port errors
Several errors can arise from a serial port that do not occur elsewhere. They include:
E_FILE_PARITY A parity error means that the received electrical signal corresponding to the
parity bit does not match the parity value calculated from the received data
bits. This is typically caused by electrical noise and usually indicates that the
data has been corrupted in transmission. Parity error detection is not
particularly robust, since many errors pass undetected.
E_FILE_FRAME A framing error means that the received electrical signal does not match the
start and stop bits. This most commonly occurs if data is being sent at a Baud
rate which differs from that which the receiver is expecting. Alternatively it
may mean that the number of stop bits expected by the receiver is greater than
the number being sent by the transmitter.
E_FILE_OVERRUN An overrun error occurs when the received electrical signal does not match the
stop bits. Overrun and framing errors are very similar and it is often difficult to
differentiate between them. Some devices may not report them as different
errors.
E_FILE_LINE A line error is generated when the hardware detects an inactive signal on an
input control line that the receiver requires to be permanently active (see also
Handshaking in the Serial port parameters section).
I/O DEVICES REFERENCE
I a SS SS 8 tev oo _TT_|vam_J =]
Serial port services
p_open(TTY:) Open a serial port
INT p_open(VOID **ppcb, TEXT *pname,-1) ;
Open a channel to the serial port *pname, where pname points to a serial port device name, as specified
earlier. If successful, write the channel to *ppcb and return zero.
For example:
if (!p_open(&pSerial, "TTY:A",-1) )
{
p_close(pSerial);
}
If successful the port will be powered up and the DTR line will be driven active to indicate to a connected
remote device that the port is open.
When opened a serial port will adopt its default characteristics of
e =©Baud
e data bits, no parity, 1 stop bit
e ~=RTS/CTS handshaking
e DCl1 is the XON, DC3 is the XOFF character
e Parity errors are not ignored
e No terminator characters
These characteristics may be incorrect for the required usage. To ensure that no received data is lost from,
say, a buffered modem, the RTS line will not be driven active until either the first P_rFREAD request or the
setting of some serial characteristics. (This, of course, assumes that the remote device is using RTS/CTS
handshaking.)
The call to p_open returns zero if successful, or a negative error. Errors include:
E_GEN_NOMEMORY there is not enough memory available to open the device
E_GEN_INUSE the specified port is currently in use
E_FILE_DEVICE an illegal or non-existent device is specified
E_FILE_LOCKED attempting to open too many channels to the device driver
p_close Close a serial port
INT p_close(VOID *pcb) ;
Close the specified channel to the serial driver.
The internal receive data buffer is flushed. If a character is currently being transmitted, the P_FCLOSE
request waits until its transmission is complete. The transmit data register becomes empty.
Any outstanding serial driver P_FREAD or P_FWRITE requests are cancelled.
The RTS and DTR lines are set inactive to indicate that the serial port is no longer in use and the serial
port is powered down.
Returns zero.
4 SERIAL PORT
P_FREAD Read from the serial port
INT p_iow(VOID *pcb, P_FREAD, VOID *buf, UWORD *plen);
VOID p_ioc(VOID *pcb, P_FREAD, WORD *pstat, VOID *buf, UWORD *plen)j;
Read up to *pien bytes to *buf from the serial port. The supplied buffer is assumed to be at least *pien
bytes long. The only limit to the amount of data that can be received in one call is the size of the data
buffer at but. It is the user's responsibility to preserve the data space pointed to by buf and plen until the
P_FREAD request completes.
The p_rreap request will typically take a significant length of time to complete and should normally be
called asynchronously in a quality system.
The request will complete when one of the following occurs:
@ *plen bytes have been received and transferred to *but. The request completes with zero
completion status code.
e areceive error is detected. The number of bytes received before the the error occurred is written
to *plen and these bytes transferred to *buf. The request completes with a negative error
completion status code.
¢ one of the terminating characters specified by the tmask field of the serial characteristcs is
received. The number of bytes received, including the terminating character, is written to *plen
and these bytes transferred to *buf. The request completes with zero completion status code.
e the request is cancelled. The number of bytes so far transferred to *buf is written to *plen.
The request completes with the —_F1LE_caNcEL completion status code.
The buffering mechanism at the serial driver's logical device driver level means that, following a
P_FCANCEL request, more characters may be available that have not yet been transferred to *but. The user
should test for this by calling the p_rtEst service and, if necessary, calling the p_rREAD service
synchronously to extract the remaining characters, as in the following example.
len=100;
p_ioc(pSerial,P_FREAD, &stat, &buf[0],&len) ;
p_iow(pSerial, P_FCANCEL) ;
p_waitstat (&stat); /* use up P_FREAD signal */
p_printf("Buf[] contains %d bytes",len);
p_iow(pSerial, P_FTEST, &len) ;
if (len)
p_read(pSerial,&buf[0],len); /* will complete immediately */
p_printf("There are %d more bytes available",len);
The calling process is panicked if a p_FREaD request is already outstanding or if pcb is not a valid channel
handle.
The completion status code is returned by the synchronous p_iow(P_FREAD) and written to *pstat by
asynchronous calls. The completion status code is zero if the p_rREaD request completed successfully,
otherwise it is a negative error number. Errors include:
E_FILE_PARITY a parity error occurred while receiving a character. This error will only be
reported if the user has not set p_IGNORE_PARITY in the serial characteristics.
Otherwise the error is discarded and the character (although in error) will
simply be transferred to *buE.
E_FILE_FRAME a serial framing error has occurred.
E_FILE_OVERRUN a serial overrun error has occurred.
E_FILE_LINE a line failure has occurred.
E_GEN_OVER the internal serial driver buffer has become full and further incoming
characters have been discarded. Some form of handshaking is required to slow
the transmitter down.
1/0 DEVICES REFERENCE
E_FILE_RECORD a terminator mask has been set, *plen bytes have been received and written
into *pbuf but no terminator character has been received. No characters have
been lost or received in error but the data format being received is not as
expected. This may or may not be regarded as an error, depending on the
application.
P_FWRITE Write to the serial port
INT p_iow(VOID *pcb, P_FWRITE, VOID *buf, UWORD *plen);
VOID p_ioc(VOID *pcb, P_FWRITE, WORD *pstat, VOID *buf, UWORD *plen)j;
Transmit *plen characters from the buffer at buf, obeying the currently selected handshaking.
The only limit to the amount of data that can be transmitted in one call is the size of the data buffer at buf.
A value of zero for *plen is permissible. It is the user's responsibility to preserve the data space pointed to
by buf and plen until the write request completes.
A P_FWRITE request will typically take a significant length of time to complete and should normally be
called asynchronously in a quality system.
A P_FWRITE request may be cancelled by using the P_FcANCEL service. The P_FWRITE request will complete
with the E_FILE_CANCEL completion status code. The serial driver does not report how many bytes have
been transmitted before the request was cancelled.
The P_FWRITE service can be used to wait for changes in hardware flow control lines. For example, a
physical link to a remote PC could be deemed to be established when the DSR line is set active. A
P_FWRITE request of zero bytes with handshaking set to P_OBEy_psR will only complete when the DSR line
is set active, as in the following example:
P_SRCHAR serChar;
p_iow(pSerial, P_FSENSE, &serChar) ;
serChar.hand|=P_OBEY_DSR;
p_iow(pSerial, P_FSET, &serChar) ;
len=0;
if (!p_iow(pSerial,P_FWRITE, &ébuf[0],é&len) )
{ /* DSR now being driven */
serChar.hand|=P_FAIL_DSR;
p_iow(pSerial,P_FSET, &serChar) ;
}
serChar.hand&=~ (P_OBEY. DSR|P FAIL_DSR) ;
p_iow(pSerial, P_FSET, &serChar) ;
In this example the serial handshaking is first set so that the first P_FWRITE request will wait until the
remote machine's DTR (incoming DSR) line is set active, at which time connection is deemed to have
been established. The handshaking is then set to cause any following read or write requests to fail if the
connection is lost (incoming DSR line set inactive). Finally, the handshaking is restored to its original
state.
The calling process is panicked if a P_FwRITE request is already outstanding, or if pcb is not a valid
channel handle.
The completion status code is returned by the synchronous p_iow(P_FWRITE) and written to *pstat by
asynchronous calls. The completion status code is zero if the P_FWRITE request completed successfully,
otherwise it is a negative error number. Errors include:
E_FILE_LINE a line failure has occurred.
P_FCANCEL Cancel any outstanding requests
INT p_iow(VOID *pcb, P_FCANCEL) ;
Cancel any outstanding P_FREAD and P_FWRITE requests, causing them to complete with the
E_FILE_CANCEL completion status code.
See the descriptions of the p_FREAD and P_FwRITE services for their behavior with respect to P_FCANCEL.
The p_FCANCEL service 1s harmless if no P_FREAD Or P_FWRITE requests are outstanding.
The P_FCANCEL service cannot fail and returns zero.
4-8
4 SERIAL PORT
P_FSENSE Sense the serial port characteristics
INT p_iow(VOID *pcb, P_FSENSE, P_SRCHAR *pch) ;
Write the current serial characteristics to the p_sRcHar struct pointed to by pch.
The p_FSENSE service cannot fail and returns zero.
P_FSET Set the serial port characteristics
INT p_iow(VOID *pcb, P_FSET, P_SRCHAR *pch) ;
Set the serial port characteristics to those passed in the p_srcuar struct pointed to by pch.
An application which wishes to change the serial port characteristics will normally first sense the current
characteristics, using the p_rsENsE service. It will then make the required change and use the p_rsEt
service to apply the new characteristics.
The calling process is panicked if there is an outstanding Pp_FREAD or P_FWRITE request or if pcb is not a
valid channel handle.
Returns zero if the p_rsrET request completed successfully, otherwise a negative error. Errors include:
E_GEN_ARG one or more of the values specified in the p_srcuar struct is illegal. The
current characteristics are not changed.
E_GEN_NSUP one of the required characteristics is not supported by this particular driver.
The current characteristics are not changed.
E_FILE_LINE either DSR is inactive and p_ratL_psr has been specified or DCD is inactive
and p_rarL_pcp has been specified (or both).
P_FFLUSH Flush the read buffer
INT p_iow(VOID *pcb, P_FFLUSH) ;
Discard the current contents of the internal serial read buffer (at the logical device driver level) and clear
any outstanding error status. Any handshaking that has paused transmission from the remote device is
cleared so that the remote device is free to resume transmission.
The p_FFLuSH service cannot fail and returns zero.
P_FTEST Test for received characters
INT p_iow(VOID *pcb, P_FTEST, UWORD *plen);
Set *pien to the number of bytes that are currently available in the serial driver's internal buffer.
Following the call it is guaranteed that there are at least *p1en bytes available. These bytes may be read
synchronously, since a synchronous p_REaD request to read *pien bytes will complete immediately.
By the time the p_rrest request has completed there may be more than *pien bytes available, since data
is received under interrupt control.
The calling process is panicked if there is an outstanding p_rREaD request or if pcb is not a valid channel
handle.
The p_Ftest service cannot fail and returns zero.
P_FCTRL Test and set control lines
INT p_iow(VOID *pcb, P_FCTRL, UBYTE *pctrl);
Read the current state of the CTS, DSR and DCD input control lines to *pctr1 as a bit mask and,
optionally, set the DTR output control line.
I/O DEVICES REFERENCE
The following bit flags are defined in p_serial.h:
P_SRCTRL_CTS if set CTS is active, otherwise it is inactive
P_SRCTRL_DSR if set DSR is active, otherwise it is inactive
P_SRCTRL_DCD if set DCD is active, otherwise it is inactive
If the byte pointed to by * (pctr1+1) is non-zero it is used to set the state of the DTR output line. If non-
zero it should take one of the following values, defined in p_serial.h:
P_SRDTR_ON to set DTR active
P_SRDTR_OFF to set DTR inactive
Returns zero if the p_FcTRL request completed successfully, otherwise a negative error number. Errors
include:
E_GEN_NSUP this driver does not support the setting of the DTR line. All current SIBO
machines support the setting of the DTR line.
P_FINQ Inquire supported serial characteristics
INT p_iow(VOID *pcb, P_FINQ, UWORD *pmask) ;
Write three words, into *pmask, * (pmask+1) and * (pmask+2), containing the serial characteristics that the
driver supports. Each word consists of a set of bit flags with each bit set indicating a supported
characteristic.
The first word, at *pmask, indicates a combination of the following potentially supported Baud rates,
defined in p_serial.h:
P_SRINQ_50
P_SRINQ_75
P_SRINQ_110
P_SRINQ_134
P_SRINQ_150
P_SRINQ_300
P_SRINQ_600
P_SRINQ_1200
P_SRINQ_1800
P_SRINQ_2000
P_SRINQ_2400
P_SRINQ_3600
P_SRINQ_4800
P_SRINQ_7200
P_SRINQ_9600
P_SRINQ_19200
The serial driver in all SIBO machines reports that all the above Baud rates are suppported, however see
Baud rate in the earlier Serial port parameters section for a discussion of the use of 19200 Baud.
The second word, at * (pmask+1), indicates a combination of the following potentially supported Baud
rates, defined in p_serial.h:
P_SRINQ_38400
P_SRINQ_56000
SIBO machines do not currently support either of these Baud rates.
The third word, at * (pmask+2), indicates support for a combination of the following characteristics,
defined in p_serial.h:
P_SRINQ_DATAS supports 5 data bits
P_SRINQ_DATA6 supports 6 data bits
P_SRINQ_DATA7 supports 7 data bits
P_SRINQ_DATA8 supports 8 data bits
P_SRINQ_STOP2 supports sending 2 stop bits
P_SRINQ_PAREVEN supports even parity
P_SRINQ_PARODD supports odd parity
P_SRINQ_PARMARK supports mark parity
4 SERIAL PORT
P_SRINQ_PARSPACE supports space parity
P_SRINQ_SETDTR supports the setting of DTR
P_SRINQ_SPLIT supports the setting of split Baud rates
The SIBO machines support all of the above except p_sRINQ_PARMARK, P_SRINQ_PARSPACE and
P_SRINQ_SPLIT.
The p_Fing service cannot fail and returns zero.
ee
Example
The following example, which assumes that the serial port is connected to a modem, uses many of the
serial services described above.
After opening a console it sends a dialling string to the modem and waits for a connection to a remote
modem. It then receives text records transmitted by the remote modem and displays them in the console
window. This continues until the user exits the program by pressing the ESCAPE key.
include <plib.h>
include <p_serial.h>
include <p_keyb.h>
define OPEN_TIMER 0
define OPEN_PORT 1
define DTR_HAND 2
define DIALLING 3
define LINE_FEED 0x0a
LOCAL_D VOID *pTimer=0; /* Timer channel handle */
LOCAL_D WORD timStat; /* Timer completion status */
LOCAL_D VOID *pSerial=0; /* Serial channel handle */
LOCAL_D WORD serWriteStat; /* Serial write completion status */
LOCAL_D WORD serReadStat; /* Serial read completion status */
GLREF_D VOID *winHandle; /* Console channel handle */
LOCAL_D WORD winStat; /* Console completion status */
LOCAL_C VOID reportError(INT func, INT error)
UBYTE bb[100];
switch (func)
{
case OPEN_TIMER:
p_puts("Failed to open timer channel");
break;
case OPEN_PORT:
p_puts("Failed to open serial port");
break;
case DTR_HAND:
p_puts ("Modem not driving DSR");
break;
case DIALLING:
p_puts ("Failed to connect to remote Modem") ;
break;
default:
p_puts ("Unknown function error");
}
p_errs(&bb[0],error);
p_puts (&bb[0]);
p_close(pSerial) ;
p_close(pTimer) ;
p_exit (1);
}
I/O DEVICES REFERENCE
LOCAL_C VOID QueueTimer (ULONG timeout)
{
p_ioc(pTimer,P_FREAD, &timStat, &timeout) ;
}
LOCAL_C VOID CancelTimer (VOID)
{
p_iow(pTimer,P_FCANCEL) ;
p_waitstat (&timStat) ;
}
LOCAL_C VOID QueueSerialWrite(UBYTE *buf,UWORD *plen)
p_ioc(pSerial,P_FWRITE, &serWriteStat,buf,plen) ;
LOCAL_C VOID CancelSerialWrite (VOID)
p_iow(pSerial,P_FCANCEL) ;
p_waitstat (&serWriteStat) ;
LOCAL_C setHand(INT clrflag, INT setflag)
P_SRCHAR sch;
p_iow(pSerial,P_FSENSE, &sch) ;
sch. hand&=clrflag;
sch.hand|=set flag;
return (p_iow(pSerial,P_FSET, &sch) );
}
LOCAL_C VOID resetModem (VOID)
/*
Reset a modem by driving DTR low for 2 seconds
x
{
UBYTE bb[2];
bb [1]=P_SRDTR_OFF;
p_iow(pSerial,P_FCTRL, &bb[0]);
p_sleep(20L);
bb [1]=P_SRDTR_ON;
p_iow(pSerial,P_FCTRL, &ébb[0]);
}
LOCAL_C dialNumber (VOID)
/*
Returns zero if successful, else -ve error number
ey.
{
UWORD len;
INT ret;
len=11;
QueueSerialWrite ("ATD9, 123456", &len) ;
QueueTimer(50L); /* 5 secs to send dial string */
p_iowait ();
if (serWriteStat !=E_FILE_PENDING)
{ /* sent dial string */
CancelTimer();
if (!serWriteStat)
{ /* sent dial string Ok */
if ((ret=setHand(-1,P_OBEY_DCD) ) !=0)
return (ret);
len=0;
QueueSerialWrite("",&len); /* Wait for DCD */
QueuveTimer(1200L); /* 2 mins to get through */
p_iowait ();
if (serWriteStat !=E_FILE_PENDING)
{
CancelTimer ();
if (!serWriteStat)
{
if ((ret=setHand(-1,P_FAIL_DCD) ) !=0)
return (ret);
}
else
CancelSerialWrite();
}
else /* timeout sending dial string */
CancelSerialWrite();
return (serWriteStat) ;
}
4 SERIAL PORT
I/O DEVICES REFERENCE
GLDEF_C main (VOID)
{
INT ret;
UWORD len;
P_SRCHAR sch;
P_CON_KBREC kbrec;
UBYTE key[2];
UBYTE buf [128+2];
p_puts("Serial Driver Example"); /* opens a console */
if ((ret=p_open (&pTimer, "TIM:",-1)) !=0)
reportError (OPEN_TIMER, ret) ;
if ((ret=p_open(&pSerial,"TTY:A",-1)) !=0)
reportError (OPEN_PORT, ret) ;
resetModem () ;
if ((ret=setHand(-1,P_OBEY DSR|P FAIL_DSR) ) !=0)
reportError (DTR_HAND, ret);
if ((ret=dialNumber () ) !=0)
reportError (DIALLING, ret) ;
p_iow(pSerial,P_FSENSE, &sch) ;
sch.tmask=(1<<LINE_FEED); /* read a record at a time */
p_iow(pSerial,P_FSET, é&sch) ;
len=128;
p_ioc(pSerial,P_FREAD, &éserReadStat, &buf[0],é&len);
p_ioc(winHandle, P_FREAD, &winStat, &kbrec) ;
FOREVER
{
p_iowait ();
if (serReadStat !=E_FILE_PENDING)
{ /* serial read completed */
if (!serReadStat || serReadStat==E_FILE_RECORD)
{
buf [len]=0;
p_puts(&buf[0]); /* display that record */
len=128;
p_ioc(pSerial,P_FREAD, &serReadStat, &buf[0],&len);
continue;
}
p_iow (winHandle, P_FCANCEL) ;
p_waitstat (&winStat) ;
break; /* Comms failure */
}
if (kbrec.keycode==P_KB_ESCAPE)
{ /* Nominated exit key */
p_iow(pSerial,P_FCANCEL) ;
p_waitstat (&serReadStat) ;
break;
}
key [0] =kbrec. keycode;
p_write(pSerial, &key[0],1);
p_ioc (winHandle, P_FREAD, &winStat, &kbrec) ;
}
resetModem () ;
p_close(pSerial) ;
p_close(pTimer) ;
return (0);
}
CHAPTER 5
SOUND
Pm S_ |
Introduction
On all machines sound can be generated from an internal speaker driven by the snp: device driver.
In addition all machines, with the exception of the Series 3a, include a built-in piezo-electric buzzer that
can be used for emitting warning beeps and other simple sounds. The Series 3a contains software that
emulates a buzzer, emitting the sound via the speaker. Using the buzzer has the advantage that (except on
the Series 3a) much less power is needed to drive it. In all cases the buzzer (or the buzzer emulator) is
controlled by means of the p_sound routine.
In all machines output to the sound channel is disabled if either the E_sounp_DEvice bit of the sound flag
is clear or the E_SOUND_DISABLE bit of the sound flag is set. These flags are manipulated by the p_get snd
and p_setsnd functions, described in the PLIB Reference manual.
Sound on MC and HC machines
MC and HC machines can emit sound from either a piezo-electric buzzer or an amplifier-driven
loudspeaker. In normal circumstances the buzzer output is controlled by the PLIB p_souna function and
the snp: sound device driver controls output to the speaker.
AS a power-conserving strategy, all sound output is directed to the buzzer if the main battery voltage is
less than the warning voltage level and no mains supply is connected.
The speaker is a two voice output device, that is, it can play two-note chords. This means that DTMF tone
dialing is possible.
The sound services provide for the generation of a wide range of notes or note sequences.
Sound on Series 3 machines
The Series 3 can emit sound from either a piezo-electric buzzer or an amplifier-driven loudspeaker. In all
circumstances the buzzer output is controlled by the PLIB p_souna function and the snp: sound device
driver controls output to the speaker.
The Series 3 sound device driver services are limited to providing either DTMF dialling tones or simple
alarm sounds. The user who wishes to generate more complex sounds must load a suitable device driver -
a simple example, SVDFRC.LDD, can be found on the SIBOSDK disk included with this manual.
Sound on Series 3a machines
The Series 3a can emit sounds from an amplifier-driven loudspeaker, using either the snp: sound device
driver or the built-in buzzer emulator. In all circumstances the buzzer emulator output is controlled by the
PLIB p_sound function. The Series 3a speaker is a two voice output device that can play two distinct notes
at the same time. The snp: sound device driver provides the same services as on the HC and MC
machines, thus allowing for the generation of a wide range of notes or note sequences.
The Series 3a can also record and play .wve digital sound files - see the General System Services chapter
of the Plib Reference manual. These are especially useful for adding custom alarm sounds.
Panics
All services (with the exception of p_open) will cause the calling process to be panicked if the passed
channel handle is not valid. Other panics are described under the particular service to which they apply.
5-1
I/O DEVICES REFERENCE
—E—EE—Ee——————— ee.
Sound services
The services listed in this section are available on all SIBO machines.
p_open(SND:) Open the sound channel
INT p_open(VOID **pcb, "SND:", -1);
Open a channel to sound device.
Returns zero if successful, or one of the following errors:
E_FILE_ALLOC failed to allocate memory for the control block
E_GEN_FAIL sound device is disabled
E_FILE_LOCKED or port is already open or in use
E_GEN_INUSE
p_close Close the sound channel
INT p_close(VOID *pcb) ;
Close the sound channel.
Returns zero.
P_FCANCEL Cancel a write request
INT p_iow(VOID *pcb, P_FCANCEL) ;
Cancel any outstanding write request. Performing a cancel is harmless if no write request is outstanding.
Returns zero.
P_FSENSE Sense sound characteristics
INT p_iow(VOID *pcb, P_FSENSE, E_SOUND *psound) ;
Sense the sound channel characteristics. The &_sounp struct is defined in epoc.h as:
typedef struct
{
UBYTE beatsPerMinute;
UBYTE volume;
} E_SOUND;
The value of beat sPerMinute has no significance for the Series 3 machine. On HC, MC and Series 3a
machines beat sPerMinute may vary from E_SOUND_MIN_BPM (2) to E_SOUND_MaAx_BpM (240). The default
value is 120.
On HC, MC and Series 3a machines volume may vary from E_SOUND_MAx_VOLUME (0) to
E_SOUND_MIN_VOLUME (5). On Series 3 machines the value is restricted to the range | to 4 inclusive. On the
Series 3a volumes | and 2 are identical, as are 4 and 5 - there are thus only four actual volumes. In all
cases a smaller value of volume gives a louder sound. The default value is 1.
Returns zero.
P_FSET Set sound characteristics
INT p_iow(VOID *pcb, P_FSET, E_SOUND *psound);
Set the sound channel characteristics from the data in the E_souNp struct, as described for the P_FSENSE
service. Setting a value for beat sPerMinute has no effect for the Series 3 machine.
5 SOUND
To set one sound characteristic without changing the other you should call p_rsense before p_rset. For
example:
E_SOUND sound;
p_iow (pcb, P_FSENSE, &sound) ;
sound.volume = 2;
p_iow (pcb, P_FSET, &sound) ;
will set volume without changing beat sPerMinute.
Returns zero if successful, or =_ceN_azc if either of the characteristics is out of range.
E FALARM Write alarm note sequence
VOID p_ioc(VOID *pcb, E_FALARM, WORD *pstat, UWORD *palarm) ;
INT p_iow(VOID *pcb, E_FALARM, UWORD *palarm) ;
Write one of the two standard alarm note sequences.
The alarm note sequence is selected by *palarn:
0 ‘rings’ sequence
1 ‘chimes’ sequence
For example,
UWORD alarm;
alarm=1;
p_iow (pcb, E_FALARM, é&alarm) ;
Panics if an E_FALARM, E_FSSOUNDCHANNELn Of E_FDIAL request is currently outstanding, or if pcb 1s not a
valid channel handle.
The completion status code is returned by the synchronous p_iow(E_FALARM) and written to *pstat by
asynchronous calls. The completion status code is zero if the p_rwrITE request completed successfully, or
E_FILE_CANCEL if the write was cancelled by a call to the p_rcancEL service.
HC, MC and Series 3a additional sound service
This service is available only on HC, MC and Series 3a machines.
E FSSOUNDCHANNELn Write to voice n
VOID p_ioc(VOID *pcb, E_FSSOUNDCHANNELn, WORD *pstat, WORD *pnotes, WORD *plen);
Write *plen notes to voice n (n may be | or 2) of the sound channel. The value of *pien must be less than
or equal to 16384 (0x4000).
The parameter pnotes should point to an array of *pien notes. A note consists of two worps, the first
giving the note frequency in Hz (middle A is 440Hz) and the second gives the note duration in beats. By
default there are 120 beats per minute, but this value may be changed using p_rset. A zero frequency
corresponds to silence.
To allow the output to both voices to be synchronised, neither output will start until both
E_FSSOUNDCHANNEL1 and E_FSSOUNDCHANNEL2 Services have been called.
Panics if an E_FSSOUNDCHANNELn (on the same channel) or an F_FALARM request is currently outstanding,
or if pcb is not a valid channel handle.
The completion status code is written to *pstat. It is zero if the request completed successfully, otherwise
it is a negative error code.
If you only require to use one of the voices you must still call both services but can, for example, set the
value pointed to by pien to zero for the =_FSOUNDCHANNEL2 service.
I/O DEVICES REFERENCE
Note: the sound and volume should always be sensed, and then set, immediately after opening the sound
channel and before playing sound. This is required even if you wish to play sound at the default volume
and beats per minute.
The following example will output a rising and falling scale (known as the ice-cream van at Psion):
#include <plib.h>
LOCAL_C VOID PlaySound(VOID *pcb)
{
WORD notesl1[] = {1048,24,524,12};
WORD notes2[] = {1048,4,1320,4,1568,4,2092,4,1568,4,1320,4,1048,12};
WORD sndstat1,sndstat2;
WORD lenl,len2;
INT i;
lenl = sizeof (notes1) /4;
len2 = sizeof (notes2) /4;
p_ioc5 (pcb, E_FSSOUNDCHANNEL1, ésndstat1, &notes1[0],é&lenl);
p_ioc5 (pcb, E_FSSOUNDCHANNEL2, &ésndstat2, &notes2[0],&len2) ;
i= -1;
do
{
p_iowait ();
itt;
} while (sndstatl == E_FILE_PENDING && sndstat2 == E_FILE_PENDING) ;
if (sndstatl == E_FILE_PENDING)
p_waitstat (&sndstatl);
else
p_waitstat (&sndstat2) ;
while (i--)
p_iosignal();
}
GLDEF_C INT main(VOID)
{
VOID *pcb;
E_SOUND sound;
p_open(&pcb, "SND:",-1);
p_iow (pcb, P_FSENSE, &sound) ;
p_iow (pcb, P_FSET, &sound) ;
PlaySound (pcb) ;
p_close (pcb);
return (0);
}
Series 3 and Series 3a additional sound service
This service is available only on Series 3 and Series 3a machines.
E FDIAL Write DTMF dial tones
VOID p_ioc(VOID *pcb, E_FDIAL, WORD *pstat, TEXT *pstr, E_DIAL *pdial);
INT p_iow(VOID *pcb, E_FDIAL, TEXT *pstr, E_DIAL *pdial);
Write a DTMF tone sequence from the zero terminated string *pstr, with timing as specified by the
content of the E_DIAL struct pointed to by pdial. This struct is defined in epoc.h as:
typedef struct
{
UBYTE toneLengthTicks; /* tone length in 1/32 sec */
UBYTE delayLengthTicks; /* inter-tone delay in 1/32 sec */
UWORD pauseLengthTicks; /* pause length in 1/32 sec */
} E_DIAL;
5 SOUND
DTMF tones are produced for the following valid characters:
e the digits 0 to 9
e upper or lower case alphabetic characters in the range A to F
e the characters # (0x23) and * (0x2A) which are converted to F and E respectively.
Space and comma characters generate a pause of length specified by the &_p1at struct element
pauseLengthTicks. All other characters are ignored.
The string at pstr may be of any length, but the total number of valid tone and pause generating characters
characters in it may not exceed 26.
For example, assuming a dial-out code of 9,
E_DIAL dial;
TEXT digits[10];
dial.toneLengthTicks=8;
dial.delayLengthTicks=8;
dial.pauseLengthTicks=48;
p_scpy (&digits[0],"9,0711234") ;
p_iow(pcb,E_FDIAL, &digits[0],&dial) ;
will emit the DTMF dialling tones to dial the external number 071 1234.
Panics if an E_FDIAL Of E_FALARM request is currently outstanding, or if pcb is not a valid channel handle.
The completion status code is returned by the synchronous p_iow(E_FDIAL) service and written to *pstat
by an asynchronous call. The completion status code is zero if the E_Fp1aL request completed successfully,
or one of the following errors:
E_FILE_CANCEL the write was cancelled by a call to the p_rcancEL service
E_GEN_ARG the string contains too many valid characters
a ———
Example
The following code implements a simple tone dialing system for HC, MC or Series 3a machines.
#include <plib.h>
#include <p_cons.h>
#include <wskeys.h>
GLREF_D VOID *winHandle;
LOCAL_D WORD tones1[] =
941,1,697,1,697,1,697,1,770,1,770,1,770,1, 852,1, 852,1,852,1,941,1,941,1};
LOCAL_D WORD tones2[] =
1336,1,1209,1,1336,1,1447,1,1209,1,1336,1,1447,1,1209,1,1336,1,1447,1,1209,1,1477,1};
LOCAL_C VOID dial(VOID *psoundcb, INT tone)
WORD len = 1;
WORD sl_status;
WORD *ptonel, *ptone2;
if(tone >= 0 && tone <= 11)
{
ptonel = &tones1[0] + tone*2;
ptone2 = &tones2[0] + tone*2;
p_ioc5 (psoundcb, E_FSSOUNDCHANNEL1, &sl1_status,ptonel, &len) ;
p_iow4 (psoundcb, E_FSSOUNDCHANNEL2, ptone2, &len) ;
p_waitstat (&sl_status) ;
}
IEVICES REFERENCE
VOD
GLDEF_C INT main(VOID)
{
INT c,tone,err;
VOID *psoundcb;
UWORD func;
P_RECT rect;
E_SOUND sound;
if ((err=p_open (&winHandle, "CON:",-1)) !=0)
{
p_notifyerr(err,"No Console device",NULL, NULL, NULL) ;
p_exit (1);
}
rect.tl.x
rect.tl.y = 0; /* set the screen size */
rect.br.x = 25;
rect.br.y = 9;
func = P_SCR_WSET;
p_iow4 (winHandle, P_FSET, &func, &rect) ;
p_printf ("Tone dial demo");
if ((err=p_open (&psoundcb, "SND:",-1)) !=0)
{
p_notifyerr(err,"Cannot open sound device",NULL, NULL, NULL) ;
p_close (winHandle) ;
p_exit (1);
}
sound.volume = 3;
sound.beatsPerMinute = 76;
p_iow3 (psoundcb, P_FSET, &sound) ;
FOREVER
{
c = p_getch();
if (c==W_KEY_RETURN) ;
break;
p_putch (c);
if (c=='"*')
tone = 10;
else if (c=='#"')
tone = 11;
else
tone =c - '0O';
dial (psoundcb, tone) ;
}
p_close (psoundcb) ;
p_printf("\r\nDemo finished");
p_printf ("Press any key to exit");
p_getch ();
p_close(winHandle) ;
return (0);
}
CHAPTER 6
THE ALARM DEVICE DRIVER
Introduction
The atm: device driver supplied on Series 3, Series 3a and MC machines provides support for alarms
(as used in the Agenda application). A process may specify an alarm sound (Series 3a only), an alarm
message and an appointment time.
The following picture illustrates the screen display for an untimed alarm on a Series 3a machine.
Alarm (Agenda) 12:32:18 pm
Alarm: Mon 18th Oct
Finish the alarm server chapter ...
Clear alarm Snooze Silence
Note that the appointment date is displayed but not the appointment time.
The following picture illustrates the screen display for a timed alarm on a Series 3a machine.
Alarm (Agenda) 12:58:89 pm
Alarm: Mon 18th Oct 2:46 pm
Finish the alarm server chapter ...
Clear alarm Snooze Silence
—Enter_|
Both the time and the date of the appointment are displayed.
An alarm is set by sending an alarm request to the alarm device driver (atu: ). This request may be made
synchronously, using p_iow, or asynchronously, by using p_ioc, for example.
Note that the alarm server holds a copy of the data relating to an outstanding alarm request. An
outstanding alarm can therefore survive the termination of its parent, that is, the process that made the
alarm request. Such an alarm is referred to as an orphaned alarm.
An orphaned alarm is automatically reparented when an identical alarm request is made. This feaure is
used by, for example, the Agenda application. Thus, even if an Agenda file is repeatedly closed and
reopened, an entry with an alarm will not be marked with a large number of identical alarm requests.)
I/O DEVICES REFERENCE
Panics
An application will be panicked if it makes an alarm request before any previous alarm request from that
application has completed. All services (with the exception of p_open) will cause the calling process to be
panicked if the passed channel handle is not valid.
The #defines and structs for the alarm server device are in the header file hasrv.h.
Series 3, Series 3a and MC alarm services
The Series 3a also has additional services that are described in the following section.
Note that all alarm services are provided by the Time application that is built into Series 3 and Series 3a
machines, rather than being an integral part of the operating system.
p_open(ALM:) Open the alarm channel
INT p_open(VOID **pcb, "ALM:", -1);
Open a channel to the alarm device.
Returns zero if the alarm device is opened successfully, otherwise one of the following errors:
E_GEN_OPEN
E_GEN_NOMEMORY
E_FILE_NXIST
p_close Close the alarm channel
INT p_close(VOID *pcb);
Close the alarm device channel.
Returns zero.
P_FCANCEL Cancel an alarm request
INT p_iow(VOID *pcb, P_FCANCEL) ;
Cancel any outstanding alarm request. Performing a cancel is harmless if no alarm request is outstanding.
Returns zero.
A_FTIMED Queue a timed alarm
VOID p_ioc(VOID *pcb, A_FTIMED, WORD *pstat, A_DETAILS *pd, TEXT *pm) ;
Queue a timed alarm specified by a pointer to an A_DETAILS struct, and a pointer to a zero terminated text
message.
The A_DETAILS struct would be defined as follows:
typedef struct
{
ULONG absTime;
ULONG dueTime;
} A_DETAILS;
¢ absTime is the alarm time as a system time.
¢ dueTime is the appointment time as a system time.
The appointment time should not be earlier than the time of the alarm.
The text message pointed to by pm should be a zero terminated string of not more than 65 characters
including the zero terminator. If no text message is required then pm should point to the null string.
The completion status is written to *pstat. The status is zero if the service completed successfully
otherwise a negative error number.
6-2
6 THE ALARM DEVICE DRIVER
A_FUNTIMED Queue an untimed alarm
VOID p_ioc(VOID *pcb, A_FUNTIMED, WORD *pstat, A_DETAILS *pd, TEXT *pm);
Queue an untimed alarm specified by a pointer to an a_DETAILSs Struct, and a pointer to a zero terminated
text message.
This service is identical to a_rTIMED (see above) except that only the day and month of the appointment
time are displayed, the hours and minutes being omitted.
Series 3a additional alarm services
The services listed in this section are only available on the Series 3a machine.
A_FTIMED X Queue a Series 3a timed alarm
VOID p_ioc(VOID *pcb, A_FTIMED_X, WORD *pstat, AXDATA *pa, TEXT *pm);
Queue a timed alarm specified by a pointer to an axpata struct, and a pointer to a zero terminated text
message.
The axpara struct is defined in hasrv.h as follows:
typedef struct
{
ULONG absTime;
ULONG dueTime;
SE_SND sound;
} AXDATA;
@ absTime 1s the alarm time as a system time.
@ dueTime is the appointment time as a system time.
® sound is the alarm sound (see below).
The se_swp struct defines the sound to be made and is defined in hasrv.h as follows:
typedef struct
{
UBYTE len;
TEXT name[8];
UBYTE zero_term;
} SE_SND;
¢ en is the length of the string in the name field.
¢ name specifies the name of the alarm sound (see below).
@ zero_term is the nuut character.
The element name in the sE_swp struct can have one of the following values:
e asingle byte containing a value between | and 16 inclusive. Currently only 1, 2 and 16 are used,
corresponding to the rings, chimes and silent alarms respectively. The contents of following
unused bytes are not significant. For example:
AXDATA axdata
axdata.sound.len=1;
axdata.sound.name[0]=1;
would set the rings sound.
I/O DEVICES REFERENCE
¢ anon-zero-terminated string specifying one of the .wve digital sound files resident in the ROM.
Currently these are: SYS$ALO/ for a 'Fanfare', SYS$AL02 for 'Soft bells' and SYS$AL03 for
‘Church bells’. For example:
AXDATA axdata
axdata.sound.len=8;
p_scopy (&axdata.sound.name[0],"SYSSAL03") ;
would set the 'Church bells' sound.
¢ anon-zero-terminated string specifying a .wve sound file resident in a local \wve\ directory. The
contents of following unused bytes are not significant. For example:
AXDATA axdata
axdata.sound.len=p_slen("mysound") ;
p_scopy (&axdata.sound.name[0],"mysound") ;
would set the sound to be that contained in a \wve\mysound.wve file.
The message pointed to by pm should be a zero terminated string of not more than 161 characters,
including the zero terminator. If no text message is required, then pm should point to a null string.
The completion status is written to *pstat. The status is zero if the service completed successfully
otherwise a negative error number.
A_FUNTIMED X Queue a Series 3a untimed alarm
VOID p_ioc(VOID *pcb, A_FUNTIMED_X, WORD *pstat, AXDATA *pa, TEXT *pm);
Queue an untimed alarm specified by a pointer to an axpata struct, and an associated text message.
This service is identical to the A_FTIMED_x service (see above) except that only the day and month of the
appointment time are displayed, the hours and minutes being omitted.
CHAPTER 7
THE FREE-RUNNING COUNTER
Introduction
The Series 3a and Workabout machines are supplied with a device driver for a built in free-running
counter (FRC). This device driver may be accessed by applications and provides for the measurement of
elapsed time with an accuracy of +/- 2ppm (corresponding to 2.6 seconds per month) and a resolution of
1/1024 seconds.
The free-running counter device driver may be used in one of three ways:
e to provide a value that increments once every 1/1024 second, effectively a relative clock. An
application can read the value at any time, without resetting it.
e to trigger an event after a specified interval, in units of 1/1024 second. In effect this provides the
same function as a relative timer, except that the free-running counter works to a higher
resolution.
e to provide a value that increments once every specified time interval, in units of 1/1024 second.
This allows an application to create a relative clock, with the resolution tailored to the
application's requirements. The value is reset to zero each time that it is read.
As the FRC device driver can support only one process at any one time, applications should use it for no
longer than is absolutely necessary.
An application that only needs to work with time intervals with a resolution of 1/32 second or greater
should not use the FRC, but should use either a relative or an absolute timer: details of these timers can be
found in the Time, Timers and Dates chapter of the Plib Reference manual.
FRC services
The FRC: device driver is specific to the Series 3a and Workabout machines.
All services (with the exception of p_open) will cause the calling process to be panicked if the passed
channel handle is not valid. Other panics are described under the particular service to which they apply.
p_open(FRC:) Open the FRC channel
INT p_open(VOID **pcb, "FRC:", -1);
Open a channel to the FRC device.
Returns zero if the device was opened successfully, otherwise a negative error code. Errors include:
E_FILE_OPEN The device can not be accessed as it is in use.
E_GEN_NOMEMORY There is insufficient memory to allow a channel to be opened.
I/O DEVICES REFERENCE
p_close Close the FRC channel
INT p_close(VOID *pcb) ;
Close the device channel, first cancelling any outstanding read request.
Returns zero.
P_FCANCEL Cancel the FRC request
INT p_iow(VOID *pcb, P_FCANCEL) ;
Cancel any outstanding request. Performing a cancel is harmless if no request is outstanding.
Returns zero.
P_FSTART Start the free-running counter
INT p_iow(VOID *pcb, P_FSTART, UWORD *pmode, UWORD *pint);
Start the free-running counter.
The uworp pointed to by pmode must specify one of the following modes, defined in epoc.h:
E_FRC_COUNTING a counter increments every 1/1024 seconds from an initial value of zero. The
value of pint is ignored.
E_FRC_REPEATING a counter increments every *pint multiple of 1/1024 seconds, starting from
zero. The value of *pint should be in the range 10 to 65535, representing time
intervals approximately in the range of 0.01 to 64 seconds.
Any outstanding P_FREAD request will be cancelled and the counter reset to zero.
Returns zero if the request completed successfully, otherwise returns a negative error number. Errors
include:
E_GEN_NSUP an invalid mode was specified.
E_GEN_RANGE the specified repeat interval is not valid, i.e. it is in the range 0 to 9 inclusive.
P_ FREAD Read the elapsed time in E_ FRC_COUNTING mode
VOID p_ioc(VOID *pcb, P_FREAD, WORD *pstat, ULONG *argl);
INT p_iow(VOID *pcb, P_FREAD, ULONG *argl1);
Sense the current counter value, following a previous P_FSTART request that set E_LFRC_COUNTING mode.
The value written to *arg1 is the time, in units of 1/1024 seconds, since the last P_rsTarT request. The
value is not reset by the P_FREAD request.
The application will be panicked if an earlier P_FREAD request is outstanding.
The completion status is written to *pstat for p_ioc and returned by p_iow. It is zero if the request
completed successfully. Otherwise it is a negative error number. Errors include:
E_GEN_OVER the elapsed number of repeat intervals is too large to be written to *arg1.
E_FILE_CANCEL the P_FREAD request was cancelled before it completed.
E_FILE_READ either the counter was not running, or the machine was switched off while the
counter was running.
7 FRC
P_ FREAD Read the elapsed time in E_ FRC_REPEATING mode
VOID p_ioc(VOID *pcb, P_FREAD, WORD *pstat);
INT p_iow(VOID *pcb, P_FREAD) ;
Sense the current counter value, following a previous p_rstTarT request that set E_FRC_REPEATING mode.
The completion status value that results from a successful call to this service is the number of complete
time intervals (as specified by the earlier p_rstart request) that have elapsed since the last request for
either a P_FSTART Of a P_FREAD Service. The service will not complete until one time interval has elapsed,
otherwise completion is immediate. Time is not lost between successive P_FREAD requests, since the FRC
hardware is not reset.
The application will be panicked if an earlier p_rREaD request is outstanding.
The completion status is written to *pstat for p_ioc and returned by p_iow. It is a positive value if the
request completed successfully. Otherwise it is a negative error number. Errors include:
E_GEN_OVER the elapsed number of repeat intervals exceeds 32767.
E_FILE_CANCEL the p_FREAD request was cancelled before it completed.
E_FILE_READ either the counter was not running, or the machine was switched off while the
counter was running.
CHAPTER 8
THE SERIES 3 WORLD DATABASE
Introduction
The World database is supported by all of the Series 3 range of machines. It stores a range of data for a
large number of countries - in practice only small or very recently created countries are not present.
Further data is stored for the larger cities in each country.
The wip: device driver allows an application to navigate the database by means of a number of search
services. A successful search sets the current city and/or country for other services that can access or
update the constituent data according to specific requirements. It supports multiple channels.
The services of this device driver are provided by the World application that is built into the ROM of all
machines in the Series 3 range.
The data stored in the database includes various codes required for dialling as follows:
e the national code for each country.
e the international prefix code for each country.
e the national prefix for long distance calls.
The database also includes the following data for each city:
e the deviation of the local time from Greenwich Mean Time.
e the times of sunset and sunrise expressed as a local time (these are actually calculated).
e the latitude and the longitude of the city.
e the coordinates of the city on the World map.
e the zone for daylight saving time (DST).
An application may also:
e set its home city.
e set its default country.
The database supports the creation of a file containing extra items which may be either new cities, or
replacement data for existing cities: only 32 extra items may be included in any one file. (A greater
number of extra items would significantly degrade the performance of the database search operations.)
Mode
A minority of services change the mode of the the database which can effect the operation of subsequent
services. Thus the wR_NEXT service moves to the next city if the database is in city mode. Otherwise the
WR_NEXT Service moves to the next country.
A service is assumed not to change the mode unless it is explictly stated to the contrary.
1/0 DEVICES REFERENCE
Series 3 and Series 3a World database services
Note that these services are provided by the World application that is built into Series 3 and Series 3a
machines, rather than being an integral part of the operating system.
p_open(WLD:) Open the World channel
INT p_open(VOID **ppcb, "WLD:", Oxffff);
Open a channel to the World database and write the handle of the channel to «ppcb.
Returns zero on success, otherwise a negative error code including the following:
E_FILE_ALLOC failed to allocate memory for the control block.
p_close Close the World channel
INT p_close(VOID *pcb) ;
Close the channel to the World database specified by pcb.
Returns zero on success.
P_FCANCEL Cancel a World request
INT p_iow(VOID *pcb, P_FCANCEL) ;
Cancel any outstanding World request on channel pcb and return zero - performing a cancel is harmless if
there is no outstanding request.
The P_FCANCEL request cannot fail.
WR_FIND_CITY Find by city
INT p_iow(VOID *pcb, WR_FIND_CITY, TEXT *match, WR_FIND_RES *result) ;
Find the first city that matches the string at address match writing the name of the matching city and the
associated country to the WR_FIND_RES struct pointed to by result - the matching is not case sensitive.
The WR_FIND_RES struct is defined as follows:
typedef struct
{
TEXT city [WR_MAX_NAME+1];
TEXT country [WR_MAX_NAME+1];
} WR_FIND_RES;
The significance of the members of the WwR_FIND_RES struct is as follows:
city the name of the matching city expressed as a zero terminated string.
country the name of the associated country expressed as a zero terminated string.
Returns WR_FOUND on success, Or WR_NOT_FOUND otherwise.
WR_FIND_COUNTRY Find by country
INT p_iow(VOID *pcb, WR_FIND_COUNTRY, TEXT *match, WR_FIND_RES *result);
Find the first country that matches the string at address match writing the name of the matching country
and its capital city to the wR_FIND_RES struct pointed to by result - the matching is not case sensitive.
8 SERIES 3 WORLD DATABASE
The wR_FIND_RES Struct is defined as follows:
typedef struct
{
TEXT city [WR_MAX_NAME+1];
TEXT country [WR_MAX_NAME+1];
} WR_FIND_RES;
The significance of the members of the wR_FIND_REs struct is as follows:
city the name of the capital city of the matching country expressed as a zero
terminated string.
country the name of the matching country expressed as a zero terminated string.
Returns wR_FOUND on success, Or WR_NOT_FOUND otherwise.
WR_FIND_EXACT Find by city and country
INT p_iow(VOID *pcb, WR_FIND_EXACT, WR_FIND_RES *match) ;
Find the country that exactly matches the city specified in match->city, or if this is NuLL, the country
specified in match->country - the matching is not case sensitive.
For a description of the wR_FIND_REs Struct, see the above descriptions of the wR_Finp_crTy and
WR_FIND_COUNTRY Services.
Returns wR_FOUND on success, Or WR_NOT_FOUND otherwise.
WR_NEXT Find next city
VOID p_iow(VOID *pcb, WR_NEXT, WR_FIND_RES *result) ;
Write the names of the next city and the associated country, or the next country and its capital city,
depending on the mode, to the wR_FIND_REs struct pointed to by result.
The service is always successful.
WR_BACK Find previous city
VOID p_iow(VOID *pcb, WR_BACK, WR_FIND_RES *result);
Write the name of the previous city and the associated country, or the previous country and its capital city,
depending on the mode, to the wR_FIND_REs struct pointed to by result.
The service is always successful.
WR_GET_HOME Find home city
VOID p_iow(VOID *pcb, WR_GET_HOME, WR_FIND_RES *result);
Write the names of the home city and the associated country to the wR_FIND_REs struct pointed to by
result.
The service is always successful.
WR_SET HOME Set home city
INT p_iow(VOID *pcb, WR_SET_HOME) ;
Set the home city to the current city.
This is a system wide setting.
Returns zero on success, or WR_NOTVALID_ERR if the current city is no longer valid 1.e. the current city has
been deleted.
1/0 DEVICES REFERENCE
WR_GET_DEFAULT_ COUNTRY Find default country
VOID p_iow(VOID *pcb, WR_GET_DEFAULT_COUNTRY, WR_FIND_RES *result);
Write the name of the default country and its capital city to the wR_FIND_RES struct pointed to by result.
Note that the service sets the database to city mode.
The service is always successful.
WR_SET_ DEFAULT COUNTRY Set default country
INT p_iow(VOID *pcb, WR_SET_DEFAULT_COUNTRY) ;
Set the default country current country to the current country.
Note that the service sets the database to country mode.
Returns zero on success, Or E_GEN_UNDER if the current city is no longer valid i.e. the current country has
been deleted.
WR_GET_DIAL_STRING Get dial string
INT p_iow(VOID *pcb, WR_GET_DIAL_STRING, TEXT *inString, TEXT *outString);
Convert the string pointed to by inst ring into a dial string, written to the buffer pointed to by out string.
The output string may be played using the sound device: for futher details of tone dialling see the Sound
chapter of the I/O Devices Reference manual.
During the conversion, both spaces and hyphens are removed, but commas are left unchanged. A full stop
is interpreted as marking the end of the input string. For the significance of commas see the Sound
chapter of the //O Devices Reference manual. As an example, 0-171,123 4567.89 would be converted to
0171,1234567.
Returns zero on success, otherwise one of the following negative error codes:
E_GEN_ARG either the input string includes only one square bracket, or the country
specified in square brackets does not match a country in the database.
E_GEN_OVER at some stage in the conversion, the output string exceeded the maximum
allowed length of wR_MaAx_DIAL_STRING characters.
The conversion is illustrated by the following examples:
009 44 171 234 5678
009 is an international access code which indicates that an international call is being made. The example
international access code is that of Denmark. In the United Kingdom the international access code is 001.
44 is a country code which indicates the destination country. The example country code is that of the
United Kingdom.
171 is an area code - in this case it is the Inner London code.
234 5678 is the local telephone number.
For this example the service simply outputs 009441712345678.
009 44 (0) 171 234 5678
(0) is the national prefix and is enclosed in brackets to indicate that it is not required for international
calls.
the other components are as described above.
the output string is 009441712345678. In this case the number corresponds to calling London from
Denmark.
+44 171 234 5678
+ is an abbreviation for the international access code.
44 is the country code for the United Kingdom.
171 is the area code.
234 5678 is the local number.
8-4
8 SERIES 3 WORLD DATABASE
the interpretation of the string depends on the home country. When this is Denmark, the service replaces
the plus character with the international access code of Denmark giving 009441712345678. On the other
hand, when the home country is the United Kingdom, the plus character and the country code are replaced
with the national prefix and the output string is 01712345678.
171 234 5678 [United Kingdom]
171 is the area code.
234 5678 is the local number.
[United Kingdom] is a convenient means of specifying the destination country: note the space between the
last digit and the first bracket and that the country is specified in full.
When the home country is Denmark, the output string is 009441712345678.
When the home country is the United Kingdom, the output string is 01712345678.
0 171 234 5678
0 is the national prefix - sometimes referred to as the STD prefix - and is omitted on international calls.
the output string is 0171 234 5678.
WR_SET_EXTRA Open file for additional data
INT p_iow(VOID *pcb, WR_SET_EXTRA, WORD *flag, TEXT *name) ;
Open a file to store extra cities where name should point to the full file specification stored as a zero
terminated string and f1ag should always be set to p_FoPEN.
The filename is parsed with an extension of . wip.
The service will fail if the file does not exist.
Returns zero on success, otherwise £_GEN_1macE if the file is either badly formatted, or has a different
database version number, or a system error code.
WR_EXTRA Modify additional data
INT p_iow(VOID *pcb, WR_EXTRA, WORD *func, WR_EXTRA_DATA *data);
Add, update or delete database entries in the file opened by the earlier wR_sET_ExTRa call.
The service assumes that an extra World database file has been opened using the wR_sET_EXTRA Service.
The func argument may take one of the following values:
WR_EXTRA_ADD_CITY specifies that a city should be added to the World database - the data is read
from the wR_EXTRA_DATA union pointed to by data. The city must be in an
existing country.
The wR_EXTRA_DATA union is defined as follows:
typedef union
{
WR_CITY_DATA ci;
WR_COUNTRY_DATA co;
} WR_EXTRA_DATA;
For further details of the wr_crTy_pata struct, see the description of the
WR_GET_CITY_DATA service.
WR_EXTRA_UPDATE_CITY specifies that a city in the World database should be updated - the new data is
read from the wR_EXTRA_DATA union pointed to by data. The city must be in an
existing country.
For details of the wR_ExTRA_DATA union see above. For details of the
WR_COUNTRY_DATA Struct see the description of the wR_GET_COUNTRY_DATA
service.
I/O DEVICES REFERENCE
WR_EXTRA_DELETE_CITY delete a city in the extra database file - the name of the city and the name of
the country are read from the wR_EXTRA_DATA union pointed to by data.
WR_EXTRA_UPDATE_COUNTRY — update a country in the World database - the data associated with the country is
read from the WR_EXTRA_DATA union pointed to by data. Renaming a country
does not delete or otherwise modify the member countries
On success, the service returns either zero or one of the following values:
WR_REVERTED the city has reverted to its original built-in data.
WR_DELETED the city has been deleted.
Otherwise the service returns a negative error code which includes the following:
E_GEN_ARG tried to update a non-existent country, or specified a non-existent city as the
capital of a country.
WR_TOO_MANY_ERR attempted to exceed the maximum allowed number of items in the extra World
database file. The maximum number of allowed items is 32.
WR_DUPLICATE_ERR the new name for a city/country matches an already existing name.
WR_NOT_VALID attempted to delete a built-in city.
WR_DELHOME_ERR attempted to delete the home city.
WR_DEL_CAPITAL_ERR attempted to delete a capital city.
WR_GET_ CITY DATA Read city data
INT p_iow(VOID *pcb, WR_GET_CITY_DATA, WR_CITY_DATA *result);
Write data associated with the current city to the wR_cITy_pata struct pointed to by result.
The wR_c1tTy_pata struct is defined as follows:
typedef struct
{
WR_FIND_RES f;
UBYTE units;
UBYTE DST;
WORD GMT;
LATL latl;
TEXT dial [WR_MAX_DIAL+1];
TEXT STD[WR_MAX_CODE+1];
P_POINT pos;
} WR_CITY_DATA;
The members of the wR_cr1Ty_pata struct have the following significance:
£ the names of the current city and the associated country: for further details see
the description of the WwR_FIND_CITY service.
units may be one of the following values:
WR_UNITS_MILES the units of distance are to be miles.
WR_UNITS_KILOMETERS the units of distance are to be kilometers.
WR_UNITS_NAUTICAL the units of distance are to be nautical miles.
DST may be one of the following values:
0x00 the daylight saving time is to be constant.
0x02 the daylight saving time is to be European.
0x04 the daylight saving time is to be American.
0x08 the daylight saving time is to be Southern.
8 SERIES 3 WORLD DATABASE
GMT the local time - this is expressed as a deviation from Greenwich Mean Time in
units of minutes.
latl the Lat struct is defined as follows:
typedef struct
{
WORD iLat;
WORD iLong;
} LATL;
the iat member gives the latitude of the city in units of minutes of arc.
Positive values correspond to northern latitudes.
the iLtong member gives the longitude of the city in units of minutes of arc.
Positive values correspond to western longitudes.
dial the city dialling code - stored as a zero terminated string.
STD the city area code - stored as a zero terminated string.
pos the coordinates of the city on the World map: used, for example, by the World
application.
Returns zero on success, otherwise WR_NOTVALID_ERR if the item is no longer valid, for example, if the
current city has been deleted or renamed.
WR_GET_COUNTRY_DATA Read city data
INT p_iow(VOID *pcb, WR_GET_COUNTRY_DATA, WR_CITY_DATA *result);
Write the data for the current country to the wR_counTRY_pata Struct pointed to by result.
The wR_countRy_pata struct is defined as follows:
typedef struct
{
WR_FIND_RES f;
UBYTE baseGMT;
UBYTE DST;
WORD GMT;
CO_DIAL dial;
} WR_COUNTRY_DATA;
The members of the wR_counrry_para struct have the following significance:
£ contains the names of the current country and the associated capital city: for
further details see the description of the wR_FIND_COUNTRY Service.
baseGMT reserved for internal use.
DST may be one of the following values:
0x00 the daylight saving time is to be constant.
0x02 the daylight saving time is to be European.
0x04 the daylight saving time is to be American.
oxos the daylight saving time is to be Southern.
GMT the local time - this is expressed as the deviation from Greenwich Mean Time
in units of minutes.
dial the country dialling code information (see below).
The co_prat struct is defined as follows:
typedef struct
{
TEXT dialIntra[WR_MAX_INTRA+1];
TEXT dialInter [WR_MAX_INTER+1];
TEXT dial [WR_MAX_CODE+1;
UBYTE dummy;
} CO_DIAL;
1/0 DEVICES REFERENCE
The significant members of the co_p1at struct have the following meaning:
dialintra a zero terminated string of up to four digits, containing the national dialling
prefix.
dialiInter a zero terminated string of up to four digits, containing the international
dialling prefix.
dial a zero terminated string of up to eight digits, containing the national code.
Returns zero on success, otherwise WR_NOTVALID_ERR indicating that the current country is no longer
valid, for example, if the current country has been renamed.
WR_CALC Calculate distance, sunrise and sunset
VOID p_ioc(VOID *pcb, WR_CALC, WORD *pstat, WORD *state, WR_CALC_DATA *calc);
INT p_iow(VOID *pcb, WR_CALC, WORD *state, WR_CALC_DATA *calc);
Obtain the distance of the target city from the home city and the local sunrise and sunset times.
The calculation proceeds in stages in order that it may be discontinued as and when required.
The first time the wR_catc service is called, *state must be set to WR_START_STATE. The service should
then be repeatedly called until *st ate is equal to WR_END_STATE indicating that the calculation is
complete.
The wR_cALc_paArTa struct is defined as follows:
typedef struct
{
WR_CITY_DATA in;
WR_CALC_OUT out;
} WR_CALC_DATA;
The members of the wR_catc_pata struct have the following significance:
in specifies the data for the target city: for further details of the wR_cITy_paTa
struct see the description of the wR_GET_CITY_DATA service.
out the result of the calculation: the wR_caLc_out struct is defined as follows:
typedef struct
{
WORD distance;
WORD sunRise;
WORD sunSet;
WORD always;
} WR_CALC_OUT
the distance member specifies the distance from the home city in the
specified units.
the sunRise member specifies the time of sunrise - this is a local time in units
of minutes.
the sunSet member specifies the time of sunset - this is a local time in units of
minutes.
the always member specifies whether the city is always dark (-1), always light
(1) or neither (0).
The completion status code is returned by the synchronous p_iow and written to *pstat by the
asynchronous p_ioc.
The completion status code is zero if the request completed successfully, otherwise a negative error code.
8 SERIES 3 WORLD DATABASE
WR_NEXT_ LOCK Read next city name
INT p_iow(VOID *pcb, WR_NEXT_LOCK, WR_FIND_RES *result);
Writes the name of the next city as a zero terminated string to the city member of the wR_FIND_REs struct
pointed to by result.
The name of the associated country is also written to the country member of the wR_FIND_REs struct
pointed to by result.
Returns zero on success, otherwise a negative error.
World file types and their locations
This section gives a summary of the file structures used by the World Server. The main bulk of the data is
stored using a complex compression algorithm. This cannot be duplicated realistically by a third party
developer, and the functionality is available through the World Server device driver, so it is not given in
detail.
Main World file
The main World database file is stored in the ROM. For a single-language ROM it is:
ROM::WORLD.DAT
For a multi-lingual ROM is:
ROM::WORLD._<lang>
where lang is the language number selected as returned by p_get language, formatted as a 2-digit number,
left-filled with 0 if the language number is <10.
For English the filename of the World file in a multi-lingual ROM is ROM::WORLD.DAT. In a multi-
lingual ROM you are obviously going to have a number of such World files.
World Extension file
Users by default get an extension file World.dat created, but they can make their own world extension
files with different names. These files contain changes to the main data (city additions and changes, and
country changes), which the World Server reads to override the main world database file.
World File format
First 2 bytes The World file variant signature. This is a scrambled combination of the file version
and language. (Each language can have up to 15 versions; these correspond to new
releases.)
Next 30 bytes 15 two-byte table pointers. These point to tables, or key positions within tables
Remaining data Various tables, including a decode table, because all the data following is encoded.
I/O DEVICES REFERENCE
World Extension File format
File header
A World Extension File has a header of 32 bytes:
First 16 bytes World Extension File signature worldFileType**<0x0>
17-18th bytes World file variant signature. On creation is copied from the main database file. Files
which are opened which do not match the main database file are rejected.
19-20th bytes Unsigned WORD containing size of extra data block
21st-32nd bytes Not used, filled with oxo bytes
Data block
The extra data block follows, which is a string of leading byte count data blocks. Each contains either
city or country alteration information. With the Series 3a and its newer brothers, there is a limit on the
number of blocks to 32 (excluding the final, empty, field). This data block is at least one byte long
(0x0, i.e. a leading byte count list terminator).
CHAPTER 9
XMODEM AND YMODEM
Introduction
All Psion SIBO machines include an Xmodem/Ymodem device driver which implements the industry
standard Xmodem and Ymodem data transfer protocols. Only the data transfer protocols are implemented.
The applications perform the required file I/O.
The Psion SIBO Xmodem/Ymodem device driver is attached to a lower level driver which must support
the services provided by the Psion SIBO serial device driver. As it is an attached driver it can run over any
serial channel without modification.
There are numerous variations of both the Xmodem and the Ymodem protocols. The following are
supported:
e Xmodem Checksum
e Xmodem CRC
e Xmodem CRC (1K)
e Ymodem
e Ymodem (1K)
e Ymodem-G
e Ymodem-G (1K)
I _
Data transfer protocols overview
The Xmodem and Ymodem protocols were established to allow two way error correcting data transfers
between remote computers. The protocols define the data as a series of data blocks each of which is
transmitted with a check for data corruption (a few other bytes are also added - see later sections). The
Xmodem/Y modem device driver supports either a one byte checksum or a two byte CRC data integrity
check.
One byte checksum
The one byte checksum is the sum of the bytes in the data block with the carries discarded. A one byte
checksum is not as reliable an integrity check as a two byte CRC.
Two byte Cyclic Redundancy Check (CRC)
The two byte CRC is the remainder after the datablock (treated as a large binary number) is divided by a
sixteen bit number. The supplied device driver uses the CRC sixteen bit divisor recommended by the
CCITT (in polynomial form this is x!° + x!? + x> + 1). The reader should be aware that other CRCs are
also in widespread use (the CRC-16 polynomial for example).
I/O DEVICES REFERENCE
The Xmodem protocol
The Xmodem data transfer protocol was developed in the late seventies as a 'quick hack' for transferring
data between dissimilar machines. It was written on and for machines that had eight bit UARTS
(Universal Asynchronous Receivers and Transmitters) and is thus an eight bit data transfer protocol.
The protocol is very simple and thus easy to port to other machines. This and the fact that the original
implementation was placed in the public domain very early in its life has meant that the Xmodem protocol
has become a defacto industry standard data transfer protocol.
The protocol lacks many features considered mandatory in modern data transfer protocols including full
duplex transfer and windowing. Worse still it is not robust: corruption of acknowledgement characters or
the data frame header characters can fool the protocol into adopting the wrong state.
The file transfer facilities provided by applications that use the protocol simply send the body of the file as
data in data frames. Since the protocol was originally developed on CP/M machines, text files should
consist of lines of printable ASCII terminated by the CRLF (0x0d 0x0a) character sequence, with the file
terminated with the SUB (0x1a) character. It is the responsibility of the application to perform the
required file translation. The SIBO filing system allows text files to be opened in 'stream' mode (i.e. as a
constant data stream with each text record delimited by CRLF characters), see the P_FSTREAM_TEXT
section within the Files chapter of the PLIB Reference Manual. The local filing system of machines in the
SIBO range store data in the same format as MSDOS. Thus a text file can be opened using the P_FsTREAM
mode and still present CRLF delimited data. However a remote filing system, that of the Macintosh for
example, would not necessarily store data in the same format.
Binary files can be transferred with the Xmodem protocol. In this case no format is implied. All the data
should be written to file as it is presented in the Xmodem data frames.
Link establishment
The Xmodem protocol does not define a distinct link establishment phase. The sender of the data waits for
a link establishment character (NAK) and then sends the first data frame. When the first data frame is
received the link is established and both sides are in the data transfer phase.
If the sender (receiver) does not receive the expected NAK character (data frame) within a reasonable time
(two minutes for example) it should quit. The receiver will continue sending NAK characters at regular
intervals until either the first data frame is received or the allowed time period has elapsed.
The data transfer phase
The sender transmits a series of Xmodem Checksum data frames. These consist of:
SOH the start of header character (0x01).
Block number a one byte binary number labelling each data block. The number wraps to zero
at Oxff.
oxff - block number the one's complement of the block number. This validates the block number.
Data block a block of 128 data bytes.
One byte checksum the sum of the data bytes with the carrys discarded.
Each frame must contain exactly 132 bytes. Thus when there is insufficient data to fill the data block
padding must be added. Typically the padding consists of end of file (SUB) characters, although NULL
characters would probably be better when sending binary files.
If the data and the block number have not been corrupted the receiver will send a positive
acknowledgement character (ACK) requesting the sender to transmit the next data frame. Otherwise the
receiver will transmit a negative acknowledgement character (NAK) requesting the sender to retransmit
the previous (corrupted) data frame.
Link termination
An Xmodem link termination phase does not exist separately to the data transfer phase. When the last
data frame has been transmitted the sender transmits a one byte EOT character that informs the receiver
that there is no more data. The receiver should acknowledge this in the same way that a normal data
frame is acknowledged, that is with either ACK or NAK characters. Once successfully acknowledged the
link has terminated.
9-2
9 XMODEM AND YMODEM
Checksum data flow showing error recovery
Sender Receiver
NAK
<timeout>
NAK
SOH,0x01,0xFE,<128bytes>,CHK
NAK
SOH,0x01,0xFE,<128bytes>,CHK
ACK
SOH,0x02,0xFp,<128bytes>,CHK
ACK
SOH,0x03,0xFc,<128bytes>,CHK
<timeout>
SOH,0x03,0xFc,<128bytes>,CHK
ACK
EOT
NAK
EOT
ACK
The CRC variant
Xmodem CRC differs from the Xmodem Checksum protocol only in the data integrity check and the link
establishment character.
The Xmodem CRC protocol data frames include a two byte CRC data integrity check (with the high byte
being sent before the low byte) in place of the one byte checksum. This gives an improved data integrity
check at the expense of an extra byte of non-data - data frames are thus 133 bytes long. The PLIB function
p_crce will generate the required CRC.
The receiver establishes an Xmodem CRC link by sending a C (0x43) link establishment character. The
link establishment will fail if the sender does not support the CRC mode.
CRC data flow showing error recovery
Sender Receiver
C
<timeout>
Cc
SOH, 0x01,0xFE,<128 bytes>,CRCHI,CRCLO
ACK
SOH,0x02,0xFD,<128 bytes>,CRCHI,CRCLO
NAK
SOH,0x02,0xFpD,<128 bytes>,CRCHI,CRCLO
<timeout>
SOH,0x02,0xFD,<128 bytes>,CRCHI,CRCLO
ACK
EOT
ACK
The 1K variant
The 1K variant allows the sender to transmit 1024 bytes of data per data frame. Each 1K data frame starts
with an STX character (not an SOH character) and is otherwise identical to an Xmodem CRC data frame.
The link establishment, data transmission and link termination phases are the same as for the Xmodem
CRC protocol.
The 1K option allows 1024 byte data frames to be intermixed with 128 byte data frames, with the
restriction that a retransmitted frame must be the same size as the originally transmitted frame.
1K data frames are more sensitive to corruption (remember that the whole data block is destroyed by the
corruption of only one data byte). Thus 1K protocols should not be used when the transmission line is
noisy.
The 1K Xmodem variant supports only a two byte CRC data integrity check. It is inadvisable to use a one
byte checksum with 1K data frames and this option is not supported by the supplied driver.
I/O DEVICES REFERENCE
The 1K option data flow
Sender Receiver
C
STX,0x01,0xFE,<1024 bytes>,CRCHI,CRCLO
ACK
STX,0x02,0xFD,<1024 bytes>,CRCHI,CRCLO
NAK
STX,0x02,0xFD,<1024 bytes>,CRCHI,CRCLO
<timeout>
STX,0x02,0xFD,<1024 bytes>,CRCHI,CRCLO
ACK
SOH,0x03,0xFc,<128 bytes>,CRCHI,CRCLO
ACK
STX,0x04,0xFB,<1024 bytes>,CRCHI,CRCLO
ACK
EOT
ACK
Abandoning a transfer
The Xmodem specification does not explicitly provide for abandoning a data transfer session. In practice
various implementations will request link abandonment by sending a series of CAN (0x18) characters.
This method does not work well when the sender is currently transmitting a data frame. The safest option
is to continue sending the data frame and afterwards transmit the CAN characters. For a high quality
interface this alternative implies an unacceptable wait (for the 1K protocol with a 1200 baud transmission
rate the wait would be about eight seconds). The second alternative is to quit data frame transmission
immediately and send a series of CAN characters (which could be misinterpreted as belonging to the
abandoned data frame). Even if the receiver misinterprets some CAN characters the session will
eventually be abandoned.
When sending data the supplied driver will simply stop transmitting the current data frame and send a
CAN character immediately.
When receiving data the supplied driver will send a CAN character.
If a CAN character is received by the driver (except as part of a data frame) it will fail any outstanding
request with the E_FILE_CANCEL completion status.
The Ymodem protocol
The Ymodem protocol was developed from the realisation that the Xmodem protocol has several
weaknesses:
e Only one file can be transferred per command. The file name must be entered at both ends of the
link implying that the user has direct or indirect access to both computers (in addition to the
Xmodem link).
e The transferred files can contain up to 127 (or even 1023) useless bytes. These are added to pad
out the last data block.
e The time and date that the file was last modified are lost.
Some of the other weaknesses of the original specification had already been resolved by developing
variants of the Xmodem protocol. These variants (discussed in the previous section) allow for a more
sophisticated data integrity check (the CRC variant) and larger data frames (the 1K variant).
The three weaknesses in the above list are all concerned with file transfer rather than data transfer. Unlike
Xmodem, the Ymodem protocol is specifically designed for file transfer.
The Ymodem protocol does not attempt to overcome problems with or enhance the actual data flow
protocol. Thus Ymodem is subject to the same data corruption problems as Xmodem.
All Ymodem variants use CRCs.
9 XMODEM AND YMODEM
Link establishment
The Link establishment phase is identical to that for Xmodem CRC except that the first data frame
transmitted has a block number of zero rather than one. This block contains file information as follows:
e A zero terminated name. This is either the fully specified path name for the file to be transferred
or (more commonly) the file name with no path specified. In either case the name must be
acceptable to both the sender's and receiver's filing systems (in general machines that have
different filing systems will accept only the file name). This field is mandatory.
e = The file length. This is stored as a sequence of decimal digits immediately following the zero
terminated name. The receiver may use the file length to set the end of file position at the end of
the transfer. If further fields are present the file length must be present. If there are no further
fields the file length is optional.
e = The file modification date. This is stored as a sequence of octal digits specifying the time at
which the file was last modified in seconds from 00:00:00, January 1, 1970 (Unix time). A
single space character separates the file modification date from the file length. If further fields
are present the file modification date must be present. If there are no further fields the file
modification date is optional.
e The mode. This is stored as a sequence of octal digits and specifies the file mode. Unless the file
was sent from a Unix machine the mode is set to zero. Files sent from Unix machines that have
the mode set to 0x8000 are assumed to be a Unix type regular file. The mode field is separated
from the file modification date by a single space character. If further fields are present the mode
must be present. If there are no further fields the mode is optional.
e Serial number. This is stored as a sequence of octal digits and specifies the serial number of the
sender's software. The receiver's use of this number is optional. The serial number field is
separated from the mode field by a single space character. This field is optional.
All undefined fields, and the remaining bytes of the data frame, should be set to zero to allow for future
compatibility.
The following code fragment generates the first data frame containing the required Ymodem information
for filename, length and modification date.
p_bfil(&buf[0],128,0);
p_finfo(pFilename, &info) ;
p=p_scpy (&buf[0],pFilename) +1;
pt=p_gltob(p,info.size,10);
*ptt=" ';
pt=p_gltob(p,info.modst, 8);
When the first frame arrives the receiver should attempt to open the specified file. If the open request is
successful the receiver should send back an ACK to continue with the transfer, otherwise a CAN to cancel
the transfer.
When there are no more files to transfer the link connection should be re-established with a zero length
file name, after which the batch file transfer ends.
The data transfer phase
The data transfer phase is identical to the Xmodem CRC data transfer phase.
Link termination
The Ymodem file transfer termination phase does not exist separately from the data transfer phase. When
the file has been transmitted a one byte EOT character is sent to the receiver. The receiver should
acknowledge this in the same way that a normal data frame is acknowledged using either ACK or NAK
characters. The transfer of the file is now complete. When one or more additional files are to be sent the
sender must reestablish a link with the receiver and send the next file in exactly the same manner. When
all files have been sent the sender must send an initial (block number zero) data frame containing a zero
length file name.
I/O DEVICES REFERENCE
Ymodenm file transfer data flow
Sender Receiver
C
SOH, 0x00,0xFF,<filename,len...>,CRCHI,CRCLO
ACK
SOH,0x01,0xFE,<128bytes>,CRCHI,CRCLO
ACK
SOH,0x02,0xFD,<128bytes>,CRCHI,CRCLO
ACK
EOT
ACK
C
SOH,0x00,0xf£,<file name,len...>,CRCHI,CRCLO
ACK
SOH,0x01,0xFE,<128bytes>,CRCHI,CRCLO
ACK
SOH,0x02,0xFD,<128bytes>,CRCHI,CRCLO
ACK
EOT
ACK
C
SOH,0x00,0xf£,<null file name>,CRCHI,CRCLO
ACK
The 1K variant
The 1K variant allows the sender to transmit 1024 bytes of data per frame. The 1K variant data frames are
identical to Xmodem 1K data frames (with the exception of the first frame as discussed earlier).
The G variant
The Ymodem-G protocol does not have any specified way of reporting an error to the sender, or more
specifically of requesting a re-transmission of a broken data frame. The only advantages over straight
ASCII transfer is that the receiver can detect errors (although nothing can be done about them) and
multiple files can be transferred. The design philosophy seems to have been that error correcting modems
guarantee that the files are not corrupted during transfer and that the inclusion of software error corection
severely reduces the modem's throughput. However error correcting modems only ensure that the data is
not corrupted during the transfer from one modem to another.They do not check for corruption of the data
while it is being sent from the computer to the modem, and vice versa. A typical problem can occur with
PCs connected to networks where some network software insists on disabling interrupts for extended
periods of time, certainly long enough to get serial overrun errors. The Ymodem-G protocol is highly
susceptible to such errors.
A Ymodem-G link is established by the receiver sending a G (0x47) character.
The Ymodem-G protocol only has acknowledgement characters after the first data frame (indicating that
the file was successfully opened) and after the EOT character (indicating that the file was successfully
closed).
The supplied device driver will send a CAN character if an error was detected while in Ymodem-G mode.
This will typically abort the entire transfer.
9 XMODEM AND YMODEM
Ymodem.-G file transfer data flow
Sender Receiver
G
SOH, 0x00,0xFr,<filename,len...>,CRCHI,CRCLO
G
SOH,0x01,0xFE,<128bytes>,CRCHI,CRCLO
SOH,0x02,0xFp,<128bytes>,CRCHI,CRCLO
EOT
ACK
G
SOH,0x00,0xf£,<file name,len...>,CRCHI,CRCLO
G
SOH,0x01,0xFE,<128bytes>,CRCHI,CRCLO
SOH,0x02,0xFpD,<128bytes>,CRCHI,CRCLO
EOT
ACK
G
SOH,o0x00,0xf£,<null file name>,CRCHI,CRCLO
Abandoning a transfer
The Ymodem specification does not explicitly provide for abandoning a data transfer session. Various
implementations will send CAN (0x18) characters in an attempt to inform the remote computer that the
data transfer session should be abandoned.
When sending data the supplied driver will simply stop transmitting the current data frame and send a
CAN character immediately.
When receiving data the supplied driver will send a CAN character.
If a CAN character is received by the driver (except as part of a data frame) it will fail any outstanding
request with the E_FILE_CANCEL completion status.
Protocol problems
The primary task of any data transfer protocol is to ensure that the data sent is the same as the data
received. If the physical media being used could not corrupt the data then ASCII file transfer would be
ideal since no overheads are required in validating the data.
Although the Xmodem and Ymodem protocols address the majority of problems concerned various holes
in the error recovery have been pointed out. For example:
e Synchronisation will be lost if the NAK character sent by the receiver is corrupted to an ACK
character. The transfer will thus fail.
e = The use of different link establishment and acknowledgement characters for Xmodem, Ymodem
and Ymodem-G protocols can lead to confusion if the character is corrupted. For example, the
Ymodem protocol attempts to establish the link by sending a C character. Corruption of the
C to aG would fool the receiver into connecting in Ymodem-G mode.
e The use of anonymous acknowledgement characters for requesting data frame (re)transmission
can cause timing problems. For example, consider a receiver that sends an ACK or NAK
character requesting transmission of a data frame and finds that the sender is preoccupied. The
protocol allows for the receiver to wait for a specified time interval and then send another ACK
or NAK character. This will work fine unless the sender replies after transmission of the second
ACK or NAK character, and before its receipt. In this case the receiver will assume that the
transmitted data frame corresponds to the second ACK or NAK character and thus
synchronisation will be lost.
In actual field usage the Xmodem and Ymodem protocols perform more than adequately.
I/O DEVICES REFERENCE
ee en
Xmodem/Ymodem services
p_open(XMD:) Open an Xmodem/Ymodem channel
INT p_open(VOID **ppXmodem, "XMD:", —-1);
Attach the Xmodem/Ymodem driver to the open channel specified by ppxmodem. All I/O requests on that
channel will now be routed to the Xmodem/Ymodem device driver.
The passed channel is assumed to support the set of services provided by the serial driver. Currently only
the try: driver supports the serial services.
For example:
VOID *pcb;
if (!p_open(&pcb, "TTY:A",-1) )
{
if (!p_open(&pcb, "XMD:",-1) )
{
p_close (pcb);
}
p_close (pcb)
}
Note that two calls to p_close are required, one to close the channel to the Xmodem/Ymodem driver and
the second to close the channel to the serial driver.
The Xmodem/Ymodem driver senses the current serial driver's characteristics, removes any XON/XOFF
handshaking, sets the terminator mask to zero and sets the framing to eight bits, no parity and one stop
bit. The original serial characteristics are restored when the driver is closed.
Once a channel to the Xmodem/Ymodem driver has been opened, the application must connect to the
computer at the remote end. This done with the p_FconNECT service.
The calling process will be panicked if the serial driver to which the Xmodem/Ymodem driver is attached
has any outstanding requests on it.
Returns zero if the request completed successfully otherwise a negative error number.
p_close Close the Xmodem channel
INT p_close(VOID *pXmodem) ;
Close the Xmodem channel specified by pXmodem. The device driver should be closed when the file
transfer has completed. All I/O requests on the driver channel will then be routed to the underlying serial
driver.
Every outstanding request on the Xmodem/Ymodem driver will be completed, its completion status word
will be set to E_FILE_CANCEL and a signal will be generated.
The characteristics of the serial driver are restored to the values held before the Xmodem/Ymodem driver
was opened.
The p_FCLOSE request cannot fail and returns zero.
P_FCONNECT Connect to the remote computer
VOID p_ioc(VOID *pXmodem, P_FCONNECT, WORD *pstat, UWORD &type, UWORD &mode) ;
INT p_iow(VOID *pXmodem, P_FCONNECT, UWORD &type, UWORD &mode) ;
Obtain a connection to a computer assumed to be running some Xmodem/Ymodem software.
The connection type can be established as one of:
@ =P_XMDM_ACCP
e P_XMDM_INIT
9-8
9 XMODEM AND YMODEM
where p_xmpmM_accp would be used to accept a connection (the application wishes to transmit a file or
files) and p_xmpM_1nrtT would be used to initiate the connection (the application wishes to receive a file or
files).
The connection mode determines the file transfer mode and can be one of:
P_XMDM_CRCORCHECKSuUM _ the connection should be established in either Xmodem checksum or Xmodem
CRC mode depending on which mode is supported by the remote computer.
The driver has a bias towards CRC mode. When transmitting connection
request characters it sends two CRC connection request characters (C,0x43) to
every checksum connection request character (NAK,0x15). When accepting a
connection it will throw away the first NAK character it receives while waiting
for a potential C character.
P_XMDM_CHECKSUMMODE the connection should be established in Xmodem checksum mode only. This
will connect to a remote computer that is using checksum mode faster than the
P_XMDM_CRCORCHECKSUM option. (If the remote computer is trying to establish a
connection in CRC mode a connection will still be established. This fact will
be reported to the caller.)
P_XMDM_CRCMODE the connection should be established in Xmodem CRC mode only. If the
remote computer does not support CRC mode no connection will be
established.
P_YMODEM_MODE the connection should be established using the Ymodem batch protocol.
P_YMODEM_G_MODE the connection should be established using the Ymodem-G batch protocol.
As an option on any of the protocols that support CRC error checking (Xmodem CRC and all the
Ymodem variants) the p_xmpM_onz_x flag can be ored into mode to indicate that data frames of size 1K
can be transmitted and received.
For example:
mode=P_XMDM_CRCMODE | P_XMDM_ONE_K;
When this flag is not set the Xmodem/Ymodem driver will refuse to accept 1K data frames and will
instead reply with NAK characters. This will eventually cause the data transfer to fail.
When a connection cannot be established, the reason for the failure will be written back to the completion
status word.
If the connection is successfully established the completion status word will contain zero and the actual
connection mode will be written back to mode.
For example:
type=P_XMDM_INIT;
mode=P_XMDM_CRCORCHECKSUM;
if (!p_iow(pXmodem, P_FCONNECT, &type, &mode) )
{
if (mode==P_XMDM_CRCMODE)
p_puts ("CRC mode")
else if (mode==P_XMDM_CHECKSUMMODE)
p_puts ("Checksum mode")
}
Note that the data space for mode must be preserved until the connection request completes.
In general the connection request will take an extended time. Thus the request should be made
asynchronously. The connection request can be cancelled with the p_FDISCONNECT service.
If the p_FconnEcT request was started successfully the I/O request returns either zero or a negative error
number.
The completion status word is returned by the synchronous p_iow request and written to *pstat by the
asynchronous p_ioc request. It is set to =_FILE_PENDING while the request is outstanding and zero on
successful completion. If the request fails to complete it is set to a negative error number.
The calling process will be panicked if there is an outstanding p_rcoNnNECcT request.
I/O DEVICES REFERENCE
Examples
To receive files using the Xmodem-CRC 1K protocol:
type=P_XMDM_INIT;
mode=P_XMDM_CRCMODE | P_XMDM_ONE_K;
if (!p_iow(pXmodem, P_FCONNECT, &type, &mode) )
{
}
To send files using the Ymodem batch protocol:
type=P_XMDM_ACCP;
mode=P_YMODEM_MODE;
if (!p_iow(pXmodem, P_FCONNECT, &type, &mode) )
{
}
To send files using the Ymodem-G 1K batch protocol:
type=P_XMDM_ACCP;
mode=P_YMODEM_G MODE |P XMYM_ONE_K;
if (!p_iow(pXmodem, P_FCONNECT, &type, &mode) )
{
P_FDISCONNECT Disconnect from the remote
INT p_iow(VOID *pXmodem, P_FDISCONNECT) ;
Disconnect from the remote computer.
The P_FDISCONNECT request can also be used to abandon the Xmodem/Ymodem session during the
connection establishment or data transfer phases.
If a connection has already been established then the p_rp1IscoNnNEcT request will cause a CAN character
to be transmitted to the remote computer. This may or may not be picked up by the remote
Xmodem/Ymodem implementation to indicate that the data transfer phase is being abandoned. The
Xmodem/Ymodem protocols do not have any standard mechanism for abandoning data transfer.
If no connection has been established yet, or if the transfer is now complete, no characters will be
transmitted to the remote computer.
Any outstanding asynchronous requests will be cancelled by the p_FpIsconnEcT request, and their
completion status words set to E_FILE_CANCEL. For each outstanding request a signal will be generated
and must be used up by the application.
Typically the p_FDISCONNECT request would be called synchronously.
The P_FDISCONNECT request can not fail and returns zero.
Example
type=P_XMDM_INIT;
mode=P_XMDM_CRCORCHECKSUM;
p_ioc (pXmodem, P_FCONNECT, &xStat, &type, &mode) ;
p_ioc(pConsole, P_FREAD, &kStat, &kbr) ;
p_iowait();
if (xStat!=E_FILE_PENDING)
{ /* Xmodem connect completed */
}
else
{ /* key press occurred - cancel P_FCONNECT */
p_iow (pXmodem, P_FDISCONNECT) ;
p_waitstat (&xStat);
9 XMODEM AND YMODEM
P_FREAD Read data from the remote computer
VOID p_ioc(VOID *pXmodem, P_FREAD, WORD *pstat, UBYTE *buffer, UWORD *plen)j;
INT p_iow(VOID *pXmodem, P_FREAD, UBYTE *buffer, UWORD *plen);
Read data from the remote computer. If the connection was not established with a type of p_xmpm_rntT the
request will fail with the negative error E_FILE_DISc.
When data is available it will be written to the buffer pointed to by buffer and the length of the data will
be written to *plen.
When the end of data indicator (EOT) from the remote computer is received the p_rreap request will be
completed with the (negative) z_F1ILE_zoF error number.
The application is responsible for supplying a buffer large enough to hold the largest data frame that can
arrive. If the p_xmpM_onz_k mode flag was set in the p_rconnecT request this is 1024 bytes otherwise it is
128 bytes.
If the Ymodem protocols are being used the first data frame read will contain the Ymodem file
information.
If the p_rREAD request was started successfully the synchronous I/O request returns zero otherwise it
returns a negative error number.
Whilst an asynchronous P_FREAD request is outstanding the completion status word is set to
E_FILE_PENDING. On completion the status word is set to zero if the read request completed successfully
otherwise a negative error number. In particular the completion code is set to E_F1LE_zoF if there is no
more data to read.
The calling process will be panicked if there is an outstanding p_rREapD request.
Examples
Receiving multiple files using the Ymodem protocol:
type=P_XMDM_INIT;
mode=P_YMODEM_G_MODE;
FOREVER
{
if (ret=p_iow(pXmodem, P_FCONNECT, &type, &mode) )
break;
if (ret=p_iow(pXmodem, P_FREAD, &fileinfo[0],élen) )
break;
if (!p_slen(&fileinfo[0]))
{ /* finished multi-file receive */
ret=0;
break;
}
p_open (&pFile, &fileinfo[0],P_FUPDATE|P_FSTREAM|P_FREPLACE) ;
while (! (ret=p_iow(pXmodem, P_FREAD, &buf[0],&len) ) )
{
if (ret=p_write (pFile, ébuf[0],1len) )
break;
}
if (ret==E_FILE_EOF)
{
/* Truncate the file as specified in fileinfo[] */
}
p_close(pFile) ;
/* set the file modification date */
if (ret!=E_FILE_EOF)
break;
}
p_iow (pXmodem, P_FDISCONNECT) ;
if (ret)
p_puts ("Error receiving files");
I/O DEVICES REFERENCE
Receiving a single file using the Xmodem protocol:
type=P_XMDM_INIT;
mode=P_XMDM_CRCORCHECKSUM;
if (!p_iow(pXmodem, P_FCONNECT, &type, &mode) )
{ /* Xmodem connect completed */
p_open (&pFile, "temp.tmp", P_FUPDATE |P_FSTREAM|P_FREPLACE) ;
while (! (ret=p_iow(pXmodem, P_FREAD, &buf[0],&len) ) )
{
if (ret=p_write(pFile, ébuf[0],1len) )
break;
}
p_close(pFile) ;
p_iow (pXmodem, P_FDISCONNECT) ;
if (ret!=E_FILE_EOF)
p_puts ("Error occurred");
P_FWRITE Write data to the remote computer
VOID p_ioc(VOID *pXmodem, P_FWRITE, WORD *pstat, VOID *buffer, UWORD *plen);
INT p_iow(VOID *pXmodem, P_FWRITE, VOID *buffer, UWORD *plen);
Write data to the remote computer. If the connection was not established with a type of P_xmpM_accp the
request will fail with the negative error E_FILE_DISc.
Data can be written in buffers of 128 or 1024 bytes, although the device driver does not check whether or
not the connect request specified the p_xmpm_onE_x flag. If the receiver has not been set up to receive
1024 byte frames (the 1k option) it will in general fail to accept the data.
The 1K option specification allows the user to intermix the transmission of 128 and 1024 byte frames, this
driver conforms to that specification.
If the write request is for fewer than 128 bytes the internal transmit buffer is padded to 128 bytes with
SUB (0x1a) characters. If the request is for more than 128 but fewer than 1024 characters, the internal
buffer will similarly be padded with SUB characters.
As an exception to the above, if a write request of zero length is received this is taken to indicate that the
end of text marker should be transmitted to the remote computer, thus completing that data transfer.
Unlike for many device drivers the application does not have to preserve the data buffer or the length word
data spaces until data transmission has completed.
If the Ymodem protocols are being used the first data frame to be written is assumed to contain the
Ymodem file information.
If the p_rwRITE request was started successfully the I/O request returns zero otherwise it returns a negative
error number.
Whilst an asynchronous P_FWRITE request is outstanding the completion status word is set to
E_FILE_PENDING. On completion the status word is set to zero if the write request completed successfully
otherwise, it is set to a negative error number.
The calling process will be panicked if there is an outstanding P_FwRITE request.
9 XMODEM AND YMODEM
Examples
Sending a single file using the Xmodem protocol:
type=P_XMDM_ACCP;
mode=P_XMDM_CRCMODE;
if (!p_iow(pXmodem, P_FCONNECT, &type, &mode) )
{ /* Xmodem connect completed */
p_open (&pFile, "temp.tmp", P_FOPEN|P_FSTREAM|P_FSHARE) ;
while ((len=p_read(pFile, &ébuf[0],128) )>0)
{
if (ret=p_iow(pXmodem, P_FWRITE, &buf[0],&len) )
break;
}
if (!ret && (!len || len==E_FILE_EOF) )
{
len=0; /* Force EOT to be sent */
p_iow (pXmodem, P_FWRITE, &buf[0],&len);
}
p_close(pFile) ;
p_iow (pXmodem, P_FDISCONNECT) ;
if (ret)
p_puts ("Error occurred") ;
Sending multiple files using the Ymodem protocol:
type=P_XMDM_INIT;
mode=P_YMODEM MODE |P XMDM_ONE_K;
FOREVER
{
if (ret=p_iow(pXmodem, P_FCONNECT, &type, &mode) )
break;
if (! (ret=getNextFileName (&name[0]) ) )
break; /* gets Ymodem 1st frame info */
len=128;
if (ret=p_iow(pXmodem, P_FWRITE, &name[0],&len);
break;
p_open (&pFile, gname[0],P_FOPEN|P_FSTREAM|P_FSHARE) ;
while ((len=p_read(pFile, &buf[0],1024) )>0)
if (ret=p_iow(pXmodem, P_FWRITE, &buf [0], &len) )
break;
if (!ret && (!len || len==E_FILE_EOF) )
len=0; /* Force EOT to be sent */
p_iow (pXmodem, P_FWRITE, &buf[0],&len);
p_close(pFile);
if (ret)
break;
}
p_iow (pXmodem, P_FDISCONNECT) ;
if (ret)
p_puts ("Error sending files");
CHAPTER 10
NCP AND LINK
Introduction
This chapter describes the Psion Link application and the peer to peer data transfer services that are
provided to enable client server type applications to communicate with each other when the client and
server processes exist on different machines.
The basic Link application consists of two processes: LINK and syssncp. The Linx process varies from
machine to machine and provides only the user interface and one basic service. The syss$ncpP process is
identical on all machines and handles the physical connection and data transfer services.
The Link application is organised in four layers, each of which is responsible for a particular job:
e Physical Layer: for example the Serial Driver. This layer provides a set of services that hide any
hardware dependencies from the Logical Layer.
e Logical Link Layer. This layer provides the logical (hardware independent) services required by
the third layer.
e Data Transport and Multiplexing Layer
e = Application Layer
The first three layers are contained within the syssncp process, whose services are accessed via the NcP:
device driver. The syssncp process provides the data transport mechanism that allows client server
processes on different machines to communicate with each other.
There are many possible application layers, one of which is the LINK process. Client and server processes
are also examples of application layer processes.
Panics
All services (with the exception of p_open) will cause the calling process to be panicked if the passed
channel handle is not valid. Other panics are described under the particular service to which they apply.
The Psion logical link layer protocol
The Psion Link protocol provides the logical link layer services required by the syssncp process. The
services provided are fairly primitive. The syssncp process adds value to these services. A brief summary
of the protocol is presented here to aid in the explanation of the overall system.
The Psion Link protocol is a proprietary protocol based on the MNP protocol. It provides a symmetrical
‘error-free’ link between computers including:
e Full duplex data transmission.
e 16 bit CRC error detection.
e Multiple retransmissions.
e Dataframe sequencing.
e Variable dataframe size up to a maximum of 300 bytes per dataframe.
e A window size of one.
10-1
I/O DEVICES REFERENCE
One of the major design criteria of the protocol was that it could be implemented in a very small amount
of code and required a small working set. Thus features such as large data frames (eg 1K) and windowing
were rejected.
The protocol is a data transfer protocol, not a file transfer protocol. The file transfer or more accurately
file access and management services are provided by application layer processes.
The SYS$NCP process
The two primary functions of the syssncp process are connection establishment and data transfer.
Connection establishment
A connection is established when the following criteria have been met:
e A physical link has been established.
e A logical link has been established.
e The syssncp process has successfully exchanged logon messages with its remote counterpart.
If any of the above fail or the remote counterpart is not compatible a connection will not be established.
A physical link is deemed to have been established when the local machine detects that the remote
machine is driving the DTR (local machines DSR) hardware handshaking line (for further details see the
Serial Port chapter).
When establishing a modem link, a physical link is deemed to have been established when a modem
driver reports that an incoming call has arrived or that the dial request has been sucessful.
A logical link is deemed to have been established when the Pp_FconneEcT request on the link layer protocol
driver completes sucessfully.
The syssncp processes exchange logon messages that contain a version number and the time at which the
process was started.
The version numbers are checked to ensure compatibility (for possible future expansion).
The communicating sys$NncP processes exchange the time at which each was started so as to allow
connection re-establishment in the event of an error at either the logical or physical layer. The re-
establishment of the application layer connections (if present) will be transparent to the applications.
Data transfer
The syssncp process creates eight separate logical (software implemented) channels through which
applications can communicate. The first channel, channel zero, is used by the sys$ncp process, leaving
seven channels free for client server applications. When sending data the syssncp process multiplexes the
eight logical channels into one physical channel. Conversely, when receiving data the process
demultiplexes the data from one physical channel to eight logical channels.
The transferred data can be divided into control data and application data.
Control data is the data exchanged between communicating syssNcp processes that concerns application
connection, disconnection and data flow control.
Application data is the data exchanged between connected applications. It is transparent to the sys$ncP
process (which places no significance on any of the transferred bytes). Full 8 bit data transfer is available.
The syssncp process simply ensures that the data sent on a particular channel is routed to the correct
destination process.
The syssncp process removes a limitation of the logical link layer, namely the data frame size. The
SYSSNCP process will 'segment' application data such that the only frame size limitation is that of the
particular application.
10-2
10 NCP AND LINK
The LINK process
The three primary tasks of the LINK process are:
e to provide a user interface for the Link application
e to respond to state changes in the syssncp process
e to set up the remote filing system, after successful connection establishment.
On both the Series 3 and the HC, the Link application has no visible user interface: the application is
started and stopped by the system process. For example, on the Series 3 the user turns the Link application
on or off and sets the baud rate by selecting the Remote link option on the Special menu. The system
process launches or terminates the application accordingly.
Since there is no user interface on the Series 3 and the HC, all state changes are handled without
prompting the user for a response. See the p_rFRsuPER and P_FINQ services described below.
When the syssncp informs the L1nx process that a connection has been established the L1nx process at
each end runs a process called syssrrsv (the remote file server process). The syssrrsv process provides
remote file access and management services. The L1nx process then adds the REM-:: filing system PDD
(Physical Device Driver) to the file server, thus creating a client server pair.
The 1nx process also sets itself up as an IPC (InterProcess Communication) message receiver. An
application may send the following messages to the LINK process:
LNKMSG_TERMINATE request that the Link application terminate. This involves removing the remote
file system client server pair, and informing the syssncp process that it should
terminate. Instead of sending a message directly an application can use the
p_pterminate system service to send this message indirectly.
LNKMSG_LOADREMOTE request that a message to load and run a specified process be sent to the remote
LINK process. The message is assumed to contain up to E_Max_NamE + 2 bytes.
The message consists of the name of the remote process that is to be loaded
followed by an optional leading byte count command line. If a command line
is required then the process name must be padded out to z_max_namE + 2 bytes
(with NULLS) for compatiblity purposes. The name is parsed with .JMG and
the resultant file name (no device or path) taken as the match pattern for a
search that will firstly look in the default directory of the remote LINK process
(typically LOC::M:\) then in the root directory of any devices that exist on the
remote machine and finally in the ROM. If a process is sucessfully loaded it
will be resumed immediately, the remote L1nx process will force a context
switch to allow the newly loaded process to run, typically for long enough to
open a channel on the nce: device. The resultant process id and full process
name are sent from the remote L1Nnx to the local tnx process. The local L1nk
process will write back the full process name into the buffer passed and
complete the IPC message send with the positive remote process id or negative
error number, very similar to the return values for p_execc.
LNKMSG_CONFIG request that the L1nx process inform the syssncp process to change its driver
configuration. The message parameter is the full pvrs struct to be passed to the
SYSSNCP process.
The tnxmsc_... message numbers can be found in link_def.h and the pvrs struct definition is in sys$ncp.h.
NCP services
p_open(NCP:) Open an NCP channel
INT p_open(VOID **ppNcp,"NCP:",-1);
Requests that a channel to the SYS$NCP process be opened and a channel allocated to the calling process
in preparation for connection to, and communication with, a remote process.
10-3
I/O DEVICES REFERENCE
The nep: device driver is a root device driver, it does not require any opened channels to be passed to the
p_open request. All I/O requests on the allocated channel will be routed to the sys$ncp process by this
device driver automatically.
Opening a channel does not cause any data to be transferred to the remote machine.
A single process may open as many channels on the ncp: device as it likes.
If a process terminates for any reason without closing the channel to the ncp: device the syssNncP process
will tidy up, reporting to any remotely connected channel that this channel has now been closed.
Returns zero if the open request completed sucessfully otherwise a negative error number. A typical error
is that the syssncp process is not currently running in which case the E_FILE_NxIST error value will be
returned.
Example
if (!p_open(&pNcp, "NCP:",-1) )
{
p_close(pNcp) ;
}
p_close() Close the NCP channel
INT p_close(VOID *pNcp) ;
Requests that the currently opened channel to the syssncp process be closed.
Any outstanding I/O requests will be completed with the E_FILE_CANCEL completion status and a signal
will be generated.
If the process is still connected to a remote process the remote process will be informed that the
connection has been closed, any outstanding requests the remote process has will be completed with the
E_FILE_DIsc completion status.
The close request cannot fail and always returns zero.
P_FCONNECT Connect to a remote process
VOID p_ioc(VOID *pNcp, P_FCONNECT, WORD *pstat, UBYTE *pname, UWORD *plen);
INT p_iow(VOID *pNcp, P_FCONNECT, UBYTE *pname, UWORD *plen);
Requests that the channel be connected to a remote channel that has been opened by the named process.
In a typical client server application only the client process would make a p_FCoNNECT request. The server
process would typically open an nce: channel and queue a P_FREAD request awaiting its first command
from a client.
If both processes of an application attempt to obtain a connection they should ensure that their counterpart
is running and has an nce: channel open before making the P_FCONNECT request otherwise the request will
fail with the E_FILE_NxIstT completion status. Obviously if the connection request fails with the
E_FILE_NXIST completion status the request can be retried. The number of retries should, however, be
limited.
If an open channel is already connected to a remote channel the request will complete sucessfully.
In the Link application both of the L1nx processes attempt to obtain a connection. In this case both of
these processes will be running and have an ncp: channel open, since they launch the syssncpP process in
the first place.
The pname parameter is a pointer to a buffer containing the name of the remote process to connect with.
The name is used as the match parameter to the p_pidfind service on the remote machine. If that process
does not exist or does not have an opened syssncp channel the request will fail with the =_FILE_NxIsT
completion status. The data space pointed at is assumed to remain valid until the completion of the
P_FCONNECT request.
10-4
10 NCP AND LINK
The plen parameter points to a word containing the length of the buffer at pname including the zero
terminator. The data space pointed at is not required to remain valid until the completion of the
P_FCONNECT request.
The p_Fconnect request will typically take a significant length of time and as such should be called
asynchronously in a quality system.
The p_FconnectT request may be cancelled by using the p_FcanceEt service, the original request will be
completed with r_FILE_CANCEL completion status and a signal generated.
How the remote process came to be running in the first place is of no concern to the syssncp process, it is
however of great concern to an application writer.
Three primary methods are available to get the remote process running:
e Inturnkey systems the remote process may be automatically loaded by the system initialisation.
e The user may be prompted to run the remote process from the command shell or system
applications.
e An application can request that the Linx process run the remote process on its behalf.
The latter of these three methods is the most general and is best explained by an example as given below.
The completion status is written to *pstat by an asynchronous request and returned by a synchronous
request. The status is zero if the service completed successfully, otherwise it is a negative error number.
Errors include:
E_FILE_NXIST the named process does not have a channel open on the remote syssncp.
E_FILE_DISC the link is disconnected, there is no data path available to talk to the remote
SYSSNCP.
E_FILE_LINE the link was disconnected whilst attempting to send data to the remote
SYSSNCP.
E_FILE_RETRAN the retransmission threshold was reached because the link has been
disconnected.
Example
Simple connection to a currently running remote process:
if ('!p_open(&pNcp, "NCP:",-1) )
{
len=8; /* incl zero terminator */
if (!p_iow(pNcp, P_FCONNECT, "RPROC.*", &len) )
{
p_iow(pNcp, P_FDISCONNECT) ;
}
p_close (pNcp) ;
}
Connection to a remote process that is not currently running:
if ((linkPid=p_pidfind("LINK.*") ) <0)
p_exit (1);
p_scpy (&bb[0],"RPROC.IMG"); /* name only, no paths */
p=(&bb[0]);
if (p_msendreceivew (linkPid, LNKMSG_LOADREMOTE, &p) <0)
p_exit (1);
len=p_slen(&bb[0])+1; /* full process name here now */
if (!p_iow(pNcp, P_FCONNECT, &bb[0], &len) )
{
p_iow(pNcp, P_FDISCONNECT) ;
}
10-5
I/O DEVICES REFERENCE
P_FDISCONNECT Disconnect from the remote process
INT p_iow(VOID *pNcp, P_FDISCONNECT) ;
Requests that the current connection to a remote process be broken. An application may use the channel to
connect to the same remote process or a different remote process if required.
Any outstanding P_FREAD or P_FWRITE requests will be completed with the E_FILE_CANCEL completion
status and a signal generated.
A P_FDISCONNECT request is harmless if no connection has been established or the current connection is
temporarily disconnected.
The p_FDISCONNECT request cannot fail and returns zero.
P_ FREAD Read data from the remote process
VOID p_ioc(VOID *pNcp, P_FREAD, WORD *pstat, UBYTE *buf, UWORD *plen);
INT p_iow(VOID *pNcp, P_FREAD, UBYTE *buf, UWORD *plen);
Requests that the next 'message' sent by the remote process be placed in the buffer provided, the length of
which be written to *plen.
A ‘message’ is the data sent by the remote application process in a P_FWRITE request. The contents of the
message and its format are entirely determined by the application using the ncp: channel.
The buffer provided must be large enough to hold the largest message that can be sent by the remote
application at this point in time (it does not necessarily follow that this is the largest possible message that
can be sent). The syssncp process does not check that the buffer provided is large enough, it simply writes
the message into the buffer. If the buffer is not large enough then other data will invaribly become
corrupted.
The data space pointed at by both the buf and plen parameters must be preserved until the P_FREAD
request completes.
The p_FREAD request will typically take a significant length of time and as such should be called
asynchronously in a quality system.
The p_FREAD request may be cancelled by using the P_FcaNcEt service, the original request will be
completed with E_FILE_CANCEL completion status and a signal generated.
A channel connection does not have to exist for a process to queue a P_FREAD request on the channel. In a
typical client-server application the client would run the remote server process which would open an NcP:
channel and queue a P_FREAD request. The client would queue a P_FCONNECT request and when complete
send the server any messages as required using the P_FWRITE service.
The calling process will be panicked if a p_FREAD request is currently outstanding or if pNcp is not a valid
channel handle.
The completion status is written to *pstat by an asynchronous request and returned by a synchronous
request. The status is zero if the service completed successfully, otherwise it is a negative error number.
Errors include:
E_FILE_LINE the physical link has failed. This is typically caused by the remote machine
or switching off or the pack doors being opened. The application process if a
E_FILE_RETRAN server Can re-queue a P_FREAD request awaiting the next message. Typically
the server should preserve the current state awaiting the next request. A client
would typically report the error and await user input before retrying the
operation.
E_FILE_DISC the channel has become disconnected because the remote application process
has terminated (either normally or abnormally). The application should tidy up
any resources and terminate.
E_GEN_RECEIVER the remote syss$NcpP process is terminating or a new one has attempted to
connect to the local syssncp process. The application should tidy up any
resources and terminate.
Example
See the client-server example at the end of this chapter.
10 - 6
10 NCP AND LINK
P_FWRITE Write data to the remote process
VOID p_ioc(VOID *pNcp, P_FWRITE, WORD *pstat, UBYTE *buf, UWORD *plen);
INT p_iow(VOID *pNcp, P_FWRITE, UBYTE *buf, UWORD *plen)j;
Requests that the 'message' contained in the buffer of length *pien be sent to the connected process.
The data space pointed to by buf must be preserved until the p_rwriTE request completes.
The syssncp process contains a flow control mechanism such that if a process sends data to a connected
process faster than it can handle it, backwards pressure is applied to the sending process by the local
syssncp process. This mechanism is transparent to both the sender and receiver of the message. This flow
control is such that a sending process may send data as fast as it likes without the receiver ever being
swamped.
The amount of data that can be sent in one message is only restricted to the size of the sending processes
data space (64K less the stack, static variables and other allocated cells) however, the receiving process
must have a buffer as large as the largest message that can be sent.
A channel must be connected to a remote channel before a p_FwritTE request is made, if not the request
will complete with z_r1LE_p1sc completion status.
When the p_FwRITE request completes sucessfully this indicates that the remote process to which the
message has been sent has received that message. It does not indicate that the remote process has
sucessfully processed that message.
The p_FrwrRITE request will typically take a significant length of time and as such should be called
asynchronously in a quality system.
The p_FwrITE request may be cancelled by using the p_FcanceEt service, the original request will be
completed with &_FILE_CANCEL completion status and a signal generated.
The calling process will be panicked if a p_rwRitE request is currently outstanding or if pNcp is not a valid
channel handle.
The completion status is written to *pstat by an asynchronous request and returned by a synchronous
request. The status is zero if the service completed successfully, otherwise it is a negative error number.
Errors include £_FILE_LINE, E_FILE_RETRAN, E_FILE_DISsc and E_GEN_RECEIVER, all of which have the
same meaning as for the p_rREAD service.
Example
See the client-server example at the end of this chapter.
P_FCANCEL Cancel any outstanding request
INT p_iow(VOID *pNcp, P_FCANCEL)
Requests that any outstanding requests be cancelled, the outstanding requests will complete with the
E_FILE_CANCEL completion status and a signal be generated. It is indeterminate as to how much of the
message being sent to the remote process (using P_FWRITE) has actually been sent.
The p_rcancex request should typically only be used to cancel requests immediatly before the application
terminates.
The p_FcancEL request cannot fail and returns zero.
P_FRSUPER Read supervisory information
INT p_iow(VOID *pNcp, P_FRSUPER, NCLINK_INFO *pinfo, UWORD *plen);
This function should only be called by a process that replaces the L1nxK process.
Requests that the next state change be written back to the supplied buffer.
One process in the system is responsible for receiving the state change messages and responding to them.
In the supplied system this is the tnx process. In order for the process receiving the state change
messages to ensure that it does not miss any of the messages (and cause potential system deadlock) it
should have a process priority higher than that of the syssncp process. A priority of OxBO is adequate.
10-7
I/O DEVICES REFERENCE
A connection does not have to exist (and infact should not exist before the first request is made) for this
request to be queued sucessfully.
Some state changes are purely informational and can be used as such as required, others require some
action before the syssNncp process can continue. The action may be hard coded into the LINK process
(typically the non user interface versions) or prompt the user for a solution to the new state.
The following informational state changes are reported:
PHYS_PHYS_LINK_ESTABLISHED, a physical link has been sucessfully established. The L1nx
process on the Series 3 and HC ignores this message.
PHYS_WAITING_FOR_CALL, the physical layer is waiting for an incoming call from the modem
driver in order to obtain a physical connection. The L1nx process on the Series 3 cannot receive
this status message as there is no modem driver available. On an HC the message is ignored.
PHYS_DIALLING_NUMBER, the physical layer is currently dialing a phone number in order to obtain
a physical connection. The phone number that is being dialled is in the 'phoneno' field of the
Dvrs struct. The LINK process on the Series 3 cannot receive this status message as there is no
modem driver available. On an HC the message is ignored.
PHYS_CONFIGURING_MODEM, the physical layer is currently waiting for the modem driver to finish
sending modem configuration commands. The Linx process on the Series 3 cannot receive this
status message as there is no modem driver available. On an HC the message is ignored.
PHYS_NCP_LINK_ESTAB_OK, a connnection to a remote sys$ncp process has been established or re
established if the physical or logical connections have previously failed. The L1Nx process on the
Series 3 and HC ignores this message. The connection details are contained in the pvrs struct.
PHYS_NCP_LINK_ESTAB_NEW_NCP, a connection to a remote sys$ncp process has been established,
however the remote sys$ncp is different to the one we were connected to earlier. The connection
details, eg port and baud rate are contained in the pvrs struct. The LINK process on the Series 3
and HC should respond by sending a NCLINK_CTRL_NEW_NCP_OK response.
The following error state changes are reported, they all require some action, the response is sent back to
the syssncp process via the P_FINQ service.
10-8
PHYS_NCP_LINK_ESTAB_INVALID_VER, the remote sys$ncp is version 1.0. We cannot continue
with the session since the operation of the two sys$ncp's is significantly different. There are very
few version 1.0 syssncp's. The local end should terminate by responding with the appropriate
p_FINQ message.
PHYS_NCP_LINK_END, the remote syssncp is terminating, the local end should either prompt for
continuation or termination and respond to the sys$ncpP with the appropriate p_FINQ message.
PHYS_SERCONFIG_FAILED, the physical layer has reported that the serial port the user has
specified does not exist. The local end should report the error to the user and typically terminate
by sending the appropriate p_FINQ message.
PHYS_CHARS_FAILED, the physical layer has reported that an attempt to set the serial
characteristics failed, presmably because the serial driver does not support the specified
configuration. The local end should report the error to the user and typically terminate by
sending the appropriate p_FINQ message.
PHYS_LINK_FAILED, the logical link layer driver has reported that the link has failed. If the
physical connection was over a modem link or a previous logical link connection has been made
the local end should ask the user for confirmation to re-try for a physical connection. If no link
has ever been established (no pHys_NCP_LINK_ESTAB_OK status message been received) the local
end should simply ask the syssNcp process to retry for a link.
PHYS_CONNECT_FAILED, the waiting for a physical connection has failed, typically this is caused
by a modem being removed from the serial port whilst waiting for an incoming call to arrive.
The local end should either exit or request the physical action be re-tried by sending the
appropriate P_FINQ response.
10 NCP AND LINK
@ PHYS_INIT_FAILED, the physical layer has reported that the initialisation of the modem failed,
presumably because of an invalid modem configuration string. The local end should either exit
or request the physical action be re-tried by sending the appropriate p_r1No response.
@ PHYS_DIAL_FAILED, the physical layer has reported that dialling the phone number failed. The
local end should either exit or request the physical action be re-tried by sending the appropriate
P_FINQ response.
@ PHYS_MDMCONFIG_FAILED, the physical layer has reported that sending additional modem
configuration strings has failed. The local end should either exit or request the physical action be
re-tried by sending the appropriate p_F1Nno response.
The p_FRsupPER request will typically take a significant length of time. In a high quality system it should
be called asynchronously.
The p_FRSUPER request may be cancelled by using the p_rcancet service. The original request will be
completed with k_FILE_CANCEL completion status and a signal generated.
All syssncp defines and structure definitions can be found in sys$ncp.h.
The calling process will be panicked if a p_rFRsuPER request is currently outstanding or if pNcp is not a
valid channel handle.
The p_rRsuPER request cannot fail and returns zero.
P_FINQ Respond to a supervisory message
INT p_iow(VOID *pNcp, P_FINQ, INT response, DVRS *pdvr) ;
This function should only be called by a process that replaces the LINK process.
In response to a P_FRSUPER event the state change process handler (typically L1nk) must send back a
response.
A response message may be one of the following:
@ NCLINK_CTRL_RETRY, to retry the action that failed. This would typically retry for a link
connection or a physical connection depending on which event occured earlier. The pdvr
parameter is irrelevant for this message type.
@ NCLINK_CTRL_EXIT, to request that all channels be closed, the local syssncp process inform the
remote syssncp process that it is about to terminate and actually break the physical and logical
connections. The pavr parameter is irrelevant for this message type.
@ NCLINK_CTRL_NEW_NCP_oK, to inform the syssncp process that the different remote syssncp
process is acceptable and that the controlling process (L1nx) has sorted out any channels that it is
responsible for (the remote filing system channels). The pdvr parameter is irrelevant for this
message type.
At any point in time a proces may inform the syssncp process that it should restart with new parameters
by sending it the following message
¢ NCLINK_CTRL_NEW_CONFIG, restart the syssncp process with the new configuaration as specified
in pavr. If any of the parameters are illegal or the request fails then a subsequent P_FRSUPER
request will received the failure state.
The p_ring request cannot fail and returns zero.
All syssncp defines and structure definitions can be found in sys$ncp.h.
10-9
1/0 DEVICES REFERENCE
P_FSENSE Sense the current channel activity
INT p_iow(VOID *pNcp, P_FSENSE, NCLINK_SREC *prec);
If an application wishes to determine the channel activity occuring within the syssNncpP process the
statistical information contained in an NCLINK_sREC structure can be obtained.
The prec parameter is assumed to point to an aray of 8 NCLINK_SREC structures, one for each of the
possible channels that the syssncp process can handle. Channel 0 is used by the syssncp process and the
information in that array entry should be discarded.
All syssncp defines and structure definitions can be found in sys$ncp.h.
The P_FSENSE request cannot fail and returns zero.
P_FSTOP Request the SYS$NCP terminate
INT p_iow(VOID *pNcp, P_FSTOP);
If an application process wishes to terminate the syssncp process and all connected client server
applications it should use the P_FsTop service.
When the syssncp process receives this request it will fail all outstanding requests on all open channels
immediately with a E_FILE_D1Isc completion status then tell the remote syssncp process that it is about to
terminate. Any further requests made by any application proces on any channel will fail with the
E_GEN_NOPROC completion status.
The syssncp process will not terminate until all channels have been closed by all the application
processes.
Server processes will typically always have an outstanding P_FREAD request or be processing a request the
result of which is required to be sent back to the client. In both cases it will make a request on the ncP:
channel that will fail. If the error handling is as suggested in the P_rFREAD and P_FWRITE error section then
the server will terminate gracefully.
Client processes on the other hand tend not to make any requests until user input requires them to, hence
typically do not have any outstanding or make any requests on the ncp: channel.
In a high quality system the client should close its cp: channel as soon as it is informed that the syssncp
process is about to terminate.
If the client process is the one that makes the p_rstop request is not too much of a problem for it to know
to close its channel.
If the client does not make the request it will not know to close its channel. A solution to this is for a
client process to always have a P_FREAD request outstanding even though it may never read any data from
the remote process. If it does read data from the remote process (presumably after writing a request to the
remote process to make the data available) then it can still use the outstanding p_rReap to read this data.
nn EEE
Example
This example is for a client server application which allows a process to be run on a remote machine. The
full path name is specified. The connection establishment and data transfer phases are illustrated in as
simple a manner as is possible. For clarity the code does not implement the full error handling required in
a working application.
10 - 10
The client side
GLDEF_C VOID main(VOID)
{
WORD len,nlen, pid;
VOID *pNcp;
TEXT *p;
TEXT srvName [20];
TEXT cmd[80]
if (pid=p_pidfind("LINK.*") ) <0)
p_exit (1);
if (p_open(&pNcp, "NCP:",-1) )
p_exit (1);
p_scpy (&srvName[0],"EXECSRV") ;
p=(&srvName[0]);
if (p_msendreceivew (pid, LNKMSG_LOADREMOTE, &p) <0)
p_exit (1);
len=p_get1l("Name and command line", &cmd[0],80);
if (len)
{
nlen=p_slen(&srvName[0])+1;
if (!p_iow(pNcp, P_FCONNECT, &ésrvName[0], &nlen) )
{
if (!p_iow(pNcp, P_FWRITE, &cmd[0], &len) )
{
if (!p_iow(pNcp, P_FREAD, &cmd[0], &len) )
{
pid=cmd[0]+(cmd[1]<<8);
if (pid>0)
p_printf("Remote pid %x",pid);
else
p_puts ("No such process");
}
p_iow (pNcp, P_FDISCONNECT) ;
}
}
p_close(pNcp) ;
p_exit (0);
}
The server side
GLDEF_C VOID main(VOID)
{
WORD len, pid;
VOID *pNcp;
TEXT *pname, *pcmd;
TEXT cmd[80]
if (p_open(&pNcp, "NCP:",-1) )
p_exit (1);
if (!p_iow(pNcp,P_FREAD, &cmd[0], &len) )
{
pname=p_skipwh (&cmd[0]);
pcemd=p_skipch (pname) ;
if (*pcmd)
{
*pcmd++=0; /* zero terminate proc name */
pemd=p_skipch (pcmd) ;
}
pid=p_exec (pname, pcmd, p_slen(pcmd) ) ;
cmd [0]=pid;
cmd[1]=pid>>8; /* return pid or error */
len=2;
p_iow(pNcp, P_FWRITE, &cmd[0],é&len) ;
}
p_close(pNcp);
p_exit (0);
}
10 NCP AND LINK
10-11
CHAPTER 11
CRADLE AND DOCKING STATION
Introduction
This chapter refers to two units: the HC cradle and the docking station for HC and Workabout computers.
In this document the term ‘Cradle’ refers to the HC cradle, (which connects to the side pins of older HC
models). The term ‘Docking Station’ refers both to the HC docking station, (which connects to an HC LIF
interface fitted to the bottom of the HC), and to the Workabout docking station. The term ‘computer’
refers to an HC or Workabout.
This chapter describes the services which are supported by the Cradle/Docking Station device driver
(crD:). The Fast Charger services provided by the Docking Station are described in the Fast Charger
chapter.
The Cradle/Docking Station device driver (cRD:) reports changes of state when a computer is inserted or
removed from the Cradle or Docking Station. It is supplied to allow a program to perform specific
operations automatically when the computer is inserted into the Cradle or Docking Station and to ‘tidy up'
when the computer is removed.
Notes:
1. the Cradle/Docking Station device does not have to be open to use the Cradle/Docking
Station expansion port. The operating system will automatically stop and start active devices
in the cradle.
2. the "Cradle/Docking Station in" signal is generated when the computer first touches the
connector, but software running on the computer must wait until the connection is fully
home before attempting to access any device in the Cradle/Docking Station.
If a user inserts the computer into the cradle slowly, EPOC may not recognise that the
Cradle/Docking Station expansion port is present. It such a case it may be prudent to open
and close an expansion device using the Cradle/Docking Station device as an indicator of the
connection state. If an attempt to open a device when the computer is inserted into the
Cradle/Docking Station fails, a retry can be attempted after a delay of, say, two seconds.
Cradle/Docking Station services
p_open(CRD:) Open the device
INT p_open(VOID **ppcb,"CRD:",-1);
Open a channel to the current Cradle or Docking Station device, as set by any previous call to the P_FsET
service. If there has been no previous call to this service, or if the machine has just been reset, it will open
a channel to the Cradle/Docking Station.
Returns zero if the device is opened successfully, otherwise a negative error. Errors include:
E_GEN_NOMEMORY failed to allocate memory for control block
E_FILE_LOCKED or port is already open or
E_GEN_INUSE in use
11-1
I/O DEVICES REFERENCE
p_close Close the channel
INT p_close(VOID *pcb)
Close the channel. Returns zero.
P_FREAD Read from the device
VOID p_ioc(VOID *pcb, P_FREAD, WORD *pstat, UWORD *pcstate);
INT p_iow(VOID *pcb, P_FREAD, UWORD *pcstate) ;
Read a change of state from the Cradle/Docking Station, writing the new state to *pcstate.
When called for the first time after opening the device it will complete immediately, reporting the current
state. Thereafter it will complete whenever the computer is removed from or inserted into the
Cradle/Docking Station.
On completion *pcstate is TRUE if the computer is currently in the Cradle/Docking Station and Fats if
the computer is out of the Cradle/Docking Station.
Panics if a P_FREAD request is currently outstanding, or if pcb is not a valid channel handle.
The completion status code is returned by the synchronous p_iow(P_FREAD) and written to *pstat by
asynchronous calls. The completion status code is zero if the P_FREAD request completed successfully, or
E_FILE_CANCEL if the read was cancelled.
P_FCANCEL Cancel a read
INT p_iow(VOID *pcb,P_FCANCEL) ;
Cancel any outstanding P_FREAD request. Performing a cancel is harmless if no read request is
outstanding.
Returns zero.
P_FSET Set the device type
INT p_iow(VOID *pcb,P_FSET,WORD *pctype) ;
If *pctype 1s TRUE, sets all future cRD: operations to apply to the Docking Station and all accesses to port
C and related ports to apply to any expansion fitted into the Docking Station. It will also check that a valid
Docking Station expansion is fitted to the bottom of the HC. Since this call requires use of the high speed
serial channel on the bottom if the HC and affects all port C devices, it will fail with E_cEN_1nusE if
anything is open on port B or port C.
If *pctype is FALSE, sets all future cRD: operations to apply to the Cradle and all accesses to port C and
related ports to apply to any expansion fitted into the Cradle. Since this call affects all port C devices, it
will fail with E_cEN_InusE if anything is open on port C.
Note: This setting will remain even after the crp: device is closed. It will remain in force until it is
changed by another call to p_FsEt, or until the machine is reset. It is envisaged that one call will be made
to this function when an application first runs, and that this will set the device type for the life of the
application.
E_GEN_NOMEMORY failed to allocate memory for the control block
E_GEN_INUSE the port is in use (e.g. TT Y:B is open when trying to set to the Docking Station,
or TTY:C in the Docking Station is open when trying to set to the Cradle)
P_FSENSE Sense the device type
INT p_iow(VOID *pcb,P_FSENSE,WORD *pctype) ;
The current device type is returned in *pctype. If set to TRUE then the Docking Station is the current type,
if set to FALSE then the Cradle is the current type.
Note: This service does not check if the hardware is actually present (e.g. if an HC LIF interface is fitted)
and therefore may be called at any time. To check if the hardware is present, use the P_FSET service.
Returns zero.
11-2
CHAPTER 12
HC MAGNETIC CARD READER
Introduction
The HC Magnetic Card Reader (vcr: ) device driver is built into the HC's operating system.
The MCR interface may be fitted to the top (wcr:a) or bottom (Mcr:8B) of the HC, or in the cradle (wcr:c).
MCR services
p_open(MCR:) Open the MCR device
INT p_open(VOID **ppcb, "MCR:A",-1);
Open a channel to a Magnetic Card Reader device.
Returns zero if the device was opened successfully, otherwise a negative error. Errors include:
E_GEN_NOMEMORY failed to allocate memory for control block
E_FILE_DEVICE no interface found in specified slot
E_FILE_NAME invalid device name
E_FILE_LOCKED or port is already open or
E_GEN_INUSE in use
p_close Close the channel
INT p_close(VOID *pcb)
Close the Magnetic Card Reader device channel.
Returns zero.
P_FREAD Read from the MCR device
VOID p_ioc(VOID *pcb, P_FREAD, WORD *pstat, UBYTE *bufl, UBYTE *buf2);
INT p_iow(VOID *pcb, P_FREAD, UBYTE *bufl, UBYTE *buf2);
Read either or both tracks of a card. Track 1 is read into *bufi and track 2 into *buf2, where each buffer
must be at least 256 bytes long. The data in each buffer is written as leading byte count ASCII text. The
leading byte count is zero if the read was not successful.
Either buf1 or buf2 may be passed as NULL to disable reading of the relevant track. For example, to read
only track 2:
UWORD stat;
UBYTE buf[256];
p_ioc(pcb, P_FREAD, &stat, NULL, &buf[0]);
p_waitstat (&stat);
I/O DEVICES REFERENCE
Track 1 usually contains alphanumeric data (card holder's name and account number) while track 2
contains numeric data only. The most common MCRs read only track 2.
Panics if a P_FREAD request is currently outstanding, or if pcb is not a valid channel handle.
The completion status code is returned by the synchronous p_iow(P_FREAD) and written to *pstat by
asynchronous calls. The completion status code is zero if the P_FREAD request completed successfully, or
one of the following negative error numbers:
E_FILE_READ an error was detected decoding the data
E_GEN_OVER device driver buffer overflow
E_FILE_CANCEL the read was cancelled
P_FCANCEL Cancel a read
INT p_iow(VOID *pcb,P_FCANCEL) ;
Cancel any outstanding P_FREAD request. Performing a cancel is harmless if no read request is
outstanding.
Returns zero.
P_FSET Set the pull-up resistors
VOID p_iow(VOID *pcb, P_FSET, UWORD *mask);
This service is only available in EPOC versions 2.32 or later.
Set the programmable pull-up/pull-down resistors on the five MCR reader lines.
The MCR device contains programmable 100k ohm pull-up/pull-down resistors on each of the reader
lines DATA1, CLK1, DATA2, CLK2 and cus. By default when the MCR device is opened these are set to pull
down.
The resistor on each line is controlled by a bit in «mask. If the bit is set to 1 the resistor is programmed to
pull-up, if the bit is cleared to 0 the resistor is programmed to pull-down.
The bits which control each line should be defined in the application source file, according to the
following table:
Symbol Value (binary) Line
M_DATA1PU 00000001 Track 1 data
M_CLK1PU 00000010 Track 1 clock
M_DATA2PU 00000100 Track 2 data
M_CLK2PU 00001000 Track 2 clock
M_CLSPU 00010000 Card present signal
All other bits are ignored.
12-2
CHAPTER 13
HC BAR CODE READER
Hardware Description
The Bar code reader interface module
The bar code interface module is a grey plastic moulding which is designed to fit into one of the slots at
either end of the HC. To insert the module you will need to open the rear door of the HC, and unlock one
of the interface slots to remove the existing module or blank. Place the bar code reader module into the
slot and gently ease it home making sure it fits snugly. Once this is done you will need to lock the module
in place by moving the black switch into the locked position. After this close the door again otherwise the
HC will refuse to switch on.
The interface may be fitted to the top (BaR:a) or bottom (BaR:8B) of the HC.
The bar code reader wand.
The bar code wand is supplied with a locking mini-din plug which fits into the mini-din socket in the top
of the bar code module. Simply lining up the grooves and pushing the plug home will lock the plug into
place. The locking plug type is used so that if the HC is accidentally suspended by the bar code reader
cable, the machine will not come off the connector. To remove the wand from the module grip the plastic
moulding which surrounds the plug and pull gently. The plastic cover will slide back slightly releasing its
grip on the module. From there the plug should easily slide out.
[Me a Sees
Device drivers
At the time of writing, there is no bar code device driver or decoding software built into the HC's
operating system. Bar code readers are supported by separate device driver files which must be loaded by
the application code, by means of either the PLIB p_toadida function or the OPL DevLoadLpp call.
There are currently five combined decoder/device drivers:
BAREAN . LDD supports EAN8, EAN13, UPC and UPCE decoding
BARC39.LDD supports CODE 39 decoding
BARITF.LDD supports Interleaved 2 of 5 (ITF) decoding
BAR128.LDD supports CODE 128 decoding
BARMPLES . LDD supports Modified Plessey decoding
BARRAW. LDD supports raw decoding
None of the currently available drivers supports auto discrimination of bar codes.
Installing the LDD optional component of the SDK copies these files into the \sibosdkNlib directory. The
required LDD must be copied into the appropriate directory on the HC using MCLINK.
A device driver may be loaded, for example, by:
p_loadldd("BARC39.LDD") ;
To remove the device (and free the memory it uses) you should call
p_devdel ("BAR") ;
or the equivalent OPL DevDelete call.
The bar code device driver software is updated from time to time; update information is available from
Psion Support.
13-1
1/0 DEVICES REFERENCE
SSS ee |
Bar code driver services
p_open(BAR:) Open the bar code device
INT p_open(VOID **ppcb, "BAR:",-1);
Open a channel to a bar code device by means of a previously loaded bar code device driver.
Returns zero if the device was opened successfully, otherwise a negative error. Errors include:
E_GEN_NOMEMORY failed to allocate memory for control block
E_FILE_DEVICE no interface found in specified slot
E_FILE_NAME invalid device name
E_FILE_LOCKED or port is already open or in use
E_GEN_INUSE
p_close Close the channel
INT p_close(VOID *pcb)
Close the bar code device channel.
Returns zero.
P_FREAD Read from the MCR device
VOID p_ioc(VOID *pcb, P_FREAD, WORD *pstat, UBYTE *buf);
INT p_iow(VOID *pcb, P_FREAD, UBYTE *buf) ;
Read a bar code into *buf, which must be at least 256 bytes long. The data is written as leading byte count
ASCII text. The leading byte count is zero if the read was not successful. The first character of the text
indicates the type of the bar code:
EAN8 or EAN13
UPC
Code 39
ITF
Code 128
Modified Plessey
UPCE
az 7t0aNwS
The remainder of the text is the decoded bar code data.
Panics if a P_FREAD request is currently outstanding, or if pcb is not a valid channel handle.
The completion status code is returned by the synchronous p_iow(P_FREAD) and written to *pstat by
asynchronous calls. It is zero if the P_FREAD request completed successfully, or one of the following
negative error numbers:
E_GEN_OVER device driver buffer overflow
E_FILE_CANCEL the read was cancelled
P_FCANCEL Cancel a read
INT p_iow(VOID *pcb,P_FCANCEL) ;
Cancel any outstanding p_FREAD request. Performing a cancel is harmless if no read request is
outstanding.
Returns zero.
13-2
CHAPTER 14
HC INTELLIGENT BAR CODE READER/RS232 PORT
See the HC Bar Code Reader chapter, for the description of the device driver for an alternative HC bar
code reader expansion module.
RS232/intelligent bar code reader module
The RS232/intelligent bar code reader is an expansion module which contains an intelligent bar decoding
micro controller. The module is fully compatible with the HC, HC-DOS and RWAN series of computers.
The expansion module provides one serial port connection to the HC computer, and this port is shared
between the two interfaces. The serial port may be configured by software to open a channel either to the
PC-AT style RS232 interface, or to the intelligent bar code scanner interface; both interfaces cannot be
used simultaneously. This module has been designed to allow an HC computer to read bar code labels,
using a wand attached to the bar code reader interface. Data collected from bar code scans may then be
transferred to an external computer (such as an IBM PC-AT compatible machine) from the HC computer,
via the RS232 serial port interface.
The bar code reader interface contains an intelligent micro controller that will automatically read and
decode data from a bar code wand (or a wand emulator) connected to the expansion module. The unit can
read and automatically discriminate between the following bar code formats:
e EAN/JAN 8
e EAN/JAN 13
e UPCA
e UPCE
e Codabar
© Code 128
e Interleaved 2 of 5
e Code 39 (standard or extended)
The interface may be programmed to verify scanned data against check digits/characters on bar code
labels and to read, or to ignore any supplement digits in a bar code, as required.
The micro controller will transmit bar code data to the HC computer as an ASCII string of characters:
i.e. each digit or character read from a bar code label will be transmitted to the HC computer as one
ASCII-coded character. The order of the bar code data will always be transmitted to the HC computer in
the correct order (i.e. reading from left to right across the bar code label), irrespective of the direction that
the bar code label was actually scanned. By default, the end of each complete bar code scan will be marked
by a single ASCII carriage return character.
The micro controller inside the expansion module is programmable. It may be instructed to decode only a
subset of the bar code symbologies that it recognises, to transmit check digits and check characters with
each bar code scan, read or ignore supplement digits, as well as many other bar code symbology-specific
options. The micro controller can also be programmed to mark the end of each scan with a customised
ASCT terminating string of up to four characters, in place of the default carriage return termination
character. This document contains detailed information on how to program the micro controller from
C, and from OPL programs.
14-1
I/O DEVICES REFERENCE
You may connect this expansion module either to the top slot, or to the bottom slot of an HC computer.
When the expansion module has been plugged into the top slot on the computer, the RS232 port can be
accessed by opening TTy:a, and the bar code interface may be accessed by opening TTy:p; if the module
has been connected to the bottom slot on the computer, then the RS232 port can be accessed by opening
TTy:B and the bar code interface may be accessed by opening TTyY:E.
The bar code interface communicates to the host computer at the following (standard HC Comms)
settings:
e Baud
e data bits
e — stop bit
e Xon/Xoff handshaking (No hardware handshaking)
The expansion module possesses two, male 9-pin D-type connectors: the RS232 connector is a standard
PC-AT type connector!; the bar code interface connector is a standard click-lock D-type connector for a
bar code wand.
To reduce power consumption, the bar code interface and the RS232 port interface are only powered up
when the channel to the serial port is open.
The RS232 serial port interface
The RS232 interface provides standard RS232 level signals to a 9-pin D-type male connector. The
connector is PC-AT compatible, although pin 9 (normally the Rr pin) is not driven by the interface. When
the interface unit has been connected to the top slot of the HC, then the RS232 port may be accessed by
opening the try:a device. If the unit has been connected to the bottom slot of the HC, then the RS232 port
may be accessed by opening TTY:B.
The table below displays the pinout for the PC-AT type RS232 serial port.
DCD input
RX input
TX output
DTR output
Ground (ov)
DSR input
RTS output
CTS input
Optional vsup connection
OMANDNKRWNKH
Power consumption
The RS232 port is only powered up when the appropriate channel is open. The interface will draw
approximately 10mA, plus the current drawn by the device connected to the other end of the RS232 cable.
If the remote device is a PC-AT type computer, then the total current drawn by the interface will typically
be 20mA, although this figure may vary from one PC to another.
When the HC computer is also powering an external device through the RS232 port, then that external
device should not draw more than:
e =250mA from the HC if no other expansion modules are attached to the HC, or
e 200mA from the HC if another expansion module is attached to the HC and is powered up.
Please note also that external device will draw current from the HC computer even when the HC computer
has been switched off. Consequently, the external device ought to have its own on/off switch, and to avoid
excessive battery drain, the external device should be switched off when it is not in use.
'The ringing indicator (Rt) pin has not been implemented on the RS232 port. It may, however, be
connected permanently to the HC computer vsup power supply rail, if required. This action will allow an
external unit such as an infrared laser scanner to have power supplied to it through the RI connection in
the serial link cable, from the HC computer.
14-2
14 HC INTELLIGENT BAR CODE READER/RS232 PORT
Powering the HC from an external power source
The HC computer may be powered by an external source through pin 9 of the RS232 interface. To do this, a
2-pin header on the RS232/bar code interface expansion module PCB should be shorted together with a jumper.
(The 2-pin header is located at the extreme bottom left-hand side of the PCB, if the expansion module is oriented
so that the electrical components are uppermost and the two D-type connectors face upwards.)
This alteration will route the vsup main power supply rail from pin 9 of the serial port to the HC
computer. The external vsup power supply should be in the range of 7-10v. The external power supply
should be diode-isolated from the HC to prevent any power drain from the HC computer.
Please note that the main battery inside the HC computer will not be charged if power is supplied to the
HC from the RS232 port.
DSR auto wakeup switch
If required, the interface and HC computer may be woken up by an external device whenever the psp pin
of the RS232 link is asserted. To enable this facility, move the PCB switch (located at the bottom left-hand
corner of the circuit board) to the left-hand position. (If you hold the module with the component side of
the PCB facing you and the D-type connectors facing upwards, the switch is located to the bottom left
hand corner of the PCB.)
The bar code interface
The bar code reader interface contains a Hewlett-Packard HBCR-1610 series bar decoding micro
controller which is capable of reading and discriminating between the following bar code formats:
EAN/JAN 8, EAN/JAN 13, UPC A, UPC E, Codabar, Code 128, Interleaved 2 of 5 and standard or
extended Code 39 bar labels.
The interface possesses a 9-pin D-type click-lock male connector which may be attached to many standard
digital wands and wand emulating scanner units. However undecoded laser scanners (HHLC) are not
supported by this interface.
When the interface unit has been connected to the top slot of the HC, then the bar code port may be
accessed by opening the rry:p device. If the unit has been connected to the bottom slot of the HC, then the
bar code port may be accessed by opening trv:&. To conserve power, the bar code interface is only
powered up while the serial port is open.
The bar code interface communicates to the host computer with the following settings:
e Baud
e data bits, no parity and 1 stop bit
e Parity errors are not ignored
These are the default serial port settings for the HC computer. However, in addition, the bar code port
must also be set up so that:
e the tmask parameter of the serial port characteristics identifies the last character in the
terminating string for each incoming message, from the bar code interface. The default
terminating string is a single carriage return character: i.e. tmask=2000.
e the cts/rts handshaking protocol is disabled, by setting the 1cn_cts flag.
Full details are given later in this section, which describe how tmask and 1cN_cts may be set from within
a C or an OPL program. Please note that these two settings are only required to configure the bar code
ports Try:p and rry:& for the bar code interface; they do not apply to the RS232 ports rry:a and Try:B.
The table below displays the pinout for the two expansion module ports.
DCD input
Bar data input
Not connected
Switched vsup output
DSR input
DTR output
Ground (ov)
Ground (ov)
Switched 5v regulated output
OMDANANDNHRWNF
I/O DEVICES REFERENCE
Power consumption
External units should not draw more than:
e =250mA from the HC if no other expansion modules are attached to the HC, or
e 200mA from the HC if another expansion module is attached to the HC, and is powered up.
The bar code port draws an idle current of 1OmA, and typically 24mA when a scan is in progress. This
figure does not include the additional current drawn by the wand, or scanner, attached to the interface. To
conserve power, the RS232 interface is only powered up while the serial port is open.
Powering a bar code wand from the HC
The HC computer can supply a 5v ( +5%) regulated supply and a vsup (6-10v) supply to an external bar
code wand, or a wand emulating device (such as an RS232 laser scanner). These two power supplies are
available on pin 9 and pin 4, respectively, on the bar code interface connector.
To allow the HC to supply power an external unit a simple adjustment must be made to the expansion
module: a 2-pin header on the PCB of the RS232/bar code interface expansion module must be shorted
together with a jumper. (The 2-pin header is located at the extreme bottom left-hand side of the PCB, if
the expansion module is oriented so that the electrical components are uppermost and the two D-type
connectors are facing upwards.)
The two power supply outputs on the bar code interface (and the decoding IC) are switched on only when
the port is open. As a result, the power will be switched off when the HC computer powers down - if it is
left unused for longer than the timeout period. Please note that all of the custom settings programmed into
the bar code interface with escape sequences will be lost when the port is closed, or if the HC auto-powers
down.
Please note that the 2-pin header should only be taken if the external unit must be powered by the HC, or
if the HC must be powered by the external device.
[eyeee TS
Bar code symbologies
The bar code reader interface will transmit data from each bar code scan as a stream of ASCII text data.
Each data stream will be terminated by the default termination string (a carriage return character, 00d).
Alternatively, the interface may be programmed to terminate each stream of scan data with a custom
termination string of up to four characters.
Bar code data will always be transmitted to the host computer in the correct order (i.e. from left to right),
irrespective of the direction in which the bar label was originally scanned. Bar code labels containing
supplement digits can only be scanned in the forwards direction (i.e. from left to right); all other bar code
labels may be scanned either forwards or backwards. The interface may be programmed to include, or
strip out, check characters and ID characters in the transmitted data, as desired. The maximum scanning
rate for any bar code format is 30 ips
The remainder of this section will now describe each bar code format that may be scanned by the
interface. In each case, the programmable options that are associated with each format will also be
described.
Code 128
Code 128 labels contain a variable number of digits, and one check character. There are three types of
Code 128 bar code labels that may be decoded by the bar code interface: code A, code B and code C. Both
Code A and Code B labels may contain a maximum of 31 characters; Code C labels may contain a
maximum of 62 characters.
No user-definable options are available to alter Code 128 bar code data. The bar code reader interface will
always check the label data against the check character on the bar code label, but the check character will
never be transmitted as part of the scanned data.
14-4
14 HC INTELLIGENT BAR CODE READER/RS232 PORT
Codabar
Codabar labels contain one start character, a number of digits and one stop character. Only one user-
definable option exists with Codabar format data: the bar code reader interface may be programmed to
transmit, or to ignore any start and stop characters in the label data.
The start and stop characters may be any of the following four upper case characters: 'A', 'B', 'C’, or 'D'. A
start character does not have to be the same as the stop character.
The table below illustrates the effect that each Codabar option will have on the output data from the bar
code interface.
Start/stop chars Input label data Output data
Transmit A123456B 123456
Ignore A123456B A123456B
Interleaved 2 of 5
An Interleaved 2 of 5 bar code will always contain an even number of digits (including the check digit)
and no characters. It may also contain a number of additional check sum digits also. The maximum
number of digits that may be contained within a label is 32; the minimum number is 2. The interface may
be programmed to read either:
e any Interleaved 2 of 5 labels containing any even number of digits within the range of 2 and 32
digits,
e only Interleaved 2 of 5 labels containing 6 or 14 digits, or
e only Interleaved 2 of 5 labels containing a preset, even number of digits.
There will always be one check digit at the end of the bar code label. The bar code scanner interface may
be programmed to verify the scanned data against this check digit, and it may also be programmed either
to transmit the check digit as part of the output data string, or to omit the check digit from the output data.
In the table below, 123456 represents a bar code scan containing the valid check digit 6 and 123457
represents a scan that contains the invalid check digit 7. The output generated by the bar code interface is
displayed in the right-hand column.
Input data Verify the check Transmit the check digit ? Output data
digit?
23456 No Yes or No 23456
123457 No Yes or No 23457
123456 Yes No 2345
123457 Yes No No output
23456 Yes Yes 23456
123457 Yes Yes No output
Code 39
A Code 39 bar code label may contain a minimum of one character and a maximum of 32 characters. It
will contain no digits. The bar code reader interface may be programmed to verify the label check
character, and to transmit the check character in the output data message, or strip the check character
from the output data.
In the following table, ancx represents a Code 39 label containing the valid check character x, and the
string apcp represents a Code 39 label containing an invalid check character p.
14-5
1/0 DEVICES REFERENCE
Input label data Verify the check Transmit the check Output data
character? character
ABCD No Yes or No ABCD
ABCX No Yes or No ABCX
ABCD Yes No No output
ABCX Yes No ABC
ABCD Yes Yes No output
ABCX Yes Yes ABCX
The user interface may be programmed in Code 39 scans may be converted as character pairs (as defined
by the Code 39 symbology) or alternatively, each character in the scan may be decoded individually.
The UPC/EAN bar code formats
The UPC/EAN bar code family all contain a fixed number of digits, and all contain one check digit. The
bar code reader interface may be programmed to verify this check digit against the rest of the scanned
data. The interface may also be programmed to transmit the check digit as part of the bar code, or to omit
the check digit from the output data.
There twelve variants in the UPC/EAN family of bar codes. Note that JAN 8 labels are equivalent to EAN
8 format labels and JAN 13 labels are equivalent to EAN 13 format labels.
UPC E
The UPC E bar code label format contains a leading ID character, one number system digit, six data digits
and one check digit. The leading ID character must be an ASCII 'E’. The check digit will be followed by 2
supplement digits in UPC E + 2 digit labels, and with 5 supplement digits in UPC E + 5 digit labels.
The bar code interface may be programmed to remove the ID character, or the check digit from the data
transmitted to the host computer. UPC E bar code label data may also be expanded into UPC A bar code
format automatically by the interface unit - in which case the six existing data digits will be expanded to
ten digits, and the leading ID character will become an ASCII'A'. Refer to the UPC A section in this
chapter for more information about this label format.
The following table displays the four different user-definable options available for modifying the output
data from UPC E scans.
Transmit ID char Transmit check digit Standard output (UPC E) Expanded output (UPC A)
No No dddddd ndddddddddd
Yes No Endddddd Andddddddddd
No Yes dddddd nddddddddddc
Yes Yes Endddddd Anddddddddddc
where
gE = an ID character 'E' (0x45)
a =an ID character 'A' (0x41)
d= one data digit
n = one number system digit
= one check digit
Q
a
= one supplement digit
14 HC INTELLIGENT BAR CODE READER/RS232 PORT
UPC E + 2 digits
As its name suggests, the UPC E + 2 bar code label format contains a leading ID character, one number
system digit, six data digits, one check digit and two supplement digits. The leading ID character must be
an ASCIL'E'. UPC E bar code label data may also be expanded into UPC A bar code format automatically
by the interface unit - in which case the six existing data digits will be expanded to ten digits, and the
leading ID character will become an ASCII 'A’.
The bar code interface may be programmed to remove the ID character, or the check digit from the output
data transmitted to the host computer. The following table displays the four different options available:
Transmit ID char Transmit check digit Standard output (UPC E) Expanded output (UPC A)
No No ddddddss nddddddddddss
Yes No Enddddddss Anddddddddddss
No Yes ddddddss nddddddddddcss
Yes Yes Enddddddss Anddddddddddcss
where:
gE = an ID character 'E' (0x45)
a =an ID character 'A' (0x41)
a = one data digit
n = one number system digit
c = one check digit
s = one supplement digit
UPC E + 5 digits
As its name suggests, the UPC E + 5 bar code label format contains a leading ID character, one number
system digit, six data digits, one check digit and five supplement digits. The leading ID character must be
an ASCII 'E'. UPC E bar code label data may also be expanded into UPC A bar code format automatically
by the interface unit - in which case the six existing data digits will be expanded to ten digits, and the
leading ID character will become an ASCII 'A’.
The bar code interface may be programmed to remove the ID character, or the check digit from the output
data transmitted to the host computer. The following table displays the four different options available:
Transmit ID char Transmit check digit Standard output (UPC E) Expanded output (UPC A)
No No ddddddsssss nddddddddddsssss
Yes No Enddddddsssss Anddddddddddsssss
No Yes ddddddsssss nddddddddddesssss
Yes Yes Enddddddsssss Anddddddddddcsssss
where:
gE = an ID character 'E' (0x45)
a=an ID character 'A' (0x41)
d = one data digit
n = one number system digit
c = one check digit
s = one supplement digit
14-7
I/O DEVICES REFERENCE
EAN 8 bar code format
The EAN 8 bar code label format contains the following components: two leading ID characters, two flag
digits, five data digits and one check digit. The two leading ID characters will be the upper case string:
"ER w t.
The bar code interface may be programmed to remove the two ID characters, or the check digit from the
output data transmitted to the host computer. The following table displays the four different options
available:
Transmit ID chars Transmit check digit Output
No No ffddddd
Yes No FFf£fddddd
No Yes ffddddde
Yes Yes FF £fdddddc
where:
F = an ID character 'F' (0x46)
f = one flag digit
d = one data digit
c = one check digit
EAN 8 + 2 digits
The EAN 8 + 2 bar code label format contains the following components: two leading ID characters, two
flag digits, five data digits, one check digit and two supplement digits. The two leading ID characters will
be the upper case string "FF".
The bar code interface may be programmed to remove the two ID characters, or the check digit from the
output data transmitted to the host computer. The following table displays the four different options
available:
Transmit ID chars Transmit check digit Output
No No ffdddddss
Yes No FFf£fdddddss
No Yes ffdddddess
Yes Yes FFf£fdddddcss
where:
F = an ID character 'F' (0x46)
£ = one flag digit
d = one data digit
c = one check digit
s = one supplement digit
EAN 8 + 5 digits
The EAN 8 + 5 bar code label format contains the following components: two leading ID characters, two
flag digits, five data digits, one check digit and five supplement digits. The two leading ID characters will
be the upper case string "FF".
14 HC INTELLIGENT BAR CODE READER/RS232 PORT
The bar code interface may be programmed to remove the two ID characters, or the check digit from the
output data transmitted to the host computer. The following table displays the four different options
available:
Transmit ID chars Transmit check digit Output
No No ffdddddsssss
Yes No FFffdddddsssss
No Yes ffdddddcsssss
Yes Yes FFf£ffdddddcsssss
where:
Fr = an ID character 'F' (0x46)
f = one flag digit
a = one data digit
c = one check digit
s = one supplement digit
EAN 13
The EAN 13 bar code label format contains the following components: a leading ID character, two flag
digits, ten data digits and one check digit. The leading ID character will be an ASCII upper case 'F’.
The bar code interface may be programmed to remove the ID character, or the check digit from the output
data transmitted to the host computer. The following table displays the four different options available:
Transmit ID char Transmit check digit Output
No No ffdddddddddd
Yes No Fff£dddddddddd
No Yes ffddddddddddc
Yes Yes Ff fdddddddddde
where:
Fr =an ID character 'F' (0x46)
f = one flag digit
ad = one data digit
c = one check digit
EAN 13 + 2 digits
The EAN 13 + 2 bar code label format contains the following components: a leading ID character, two
flag digits, ten data digits, one check digit and two supplement digits. The leading ID character will be an
ASCII upper case 'F’.
The bar code interface may be programmed to remove the ID character, or the check digit from the output
data transmitted to the host computer. The following table displays the four different options available:
Transmit ID char Transmit check digit Output
No No ffddddddddddss
Yes No Fffddddddddddss
No Yes ffddddddddddess
Yes Yes Fffddddddddddecss
14-9
I/O DEVICES REFERENCE
where:
F = an ID character 'F' (0x46)
£ = one flag digit
d = one data digit
c = one check digit
s = one supplement digit
EAN 13 + 5 digits
The EAN 13 + 5 bar code label format contains the following components: a leading ID character, two
flag digits, ten data digits, one check digit and five supplement digits. The leading ID character will be an
ASCII upper case 'F’.
The bar code interface may be programmed to remove the ID character, or the check digit from the output
data transmitted to the host computer. The following table displays the four different options available:
Transmit ID chars Transmit check digit Output
No No ffddddddddddsssss
Yes No Fffddddddddddsssss
No Yes ffddddddddddesssss
Yes Yes Fffddddddddddesssss
where:
F = an ID character 'F' (0x46)
f = one flag digit
d = one data digit
c = one check digit
s = one supplement digit
UPCA
The UPC A bar code label format contains a leading ID character, one number system digit, ten data
digits and one check digit. The leading ID character must be an ASCII 'A’.
The bar code interface may be programmed to remove the ID character, or the check digit from the output
data transmitted to the host computer. The following table displays the four different options available:
Transmit ID chars Transmit check digit Output
No No ndddddddddd
Yes No Andddddddddd
No Yes ndddddddddde
Yes Yes Anddddddddddc
where:
a=an ID character 'A' (0x41)
n = one number system digit
d = one data digit
c = one check digit
14-10
14 HC INTELLIGENT BAR CODE READER/RS232 PORT
UPC A + 2 digits
The UPC A + 2 bar code label format contains a leading ID character, one number system digit, ten data
digits, one check digit and two supplement digits. The leading ID character must be an ASCII 'A’.
The bar code interface may be programmed to remove the ID character, or the check digit from the output
data transmitted to the host computer. The following table displays the four different options available:
Transmit ID chars Transmit check digit Output
No No nddddddddddss
Yes No Anddddddddddss
No Yes nddddddddddcss
Yes Yes Anddddddddddcss
where:
a =an ID character 'A' (0x41)
n = one number system digit
a = one data digit
c = one check digit
s = one supplement digit
UPC A + 5 digits
The UPC A +5 bar code label format contains a leading ID character, one number system digit, ten data
digits, one check digit and five supplement digits. The leading ID character must be an ASCII 'A’.
The bar code interface may be programmed to remove the ID character, or the check digit from the output
data transmitted to the host computer. The following table displays the four different options available:
Transmit ID chars Transmit check digit Output
No No nddddddddddsssss
Yes No Anddddddddddsssss
No Yes nddddddddddesssss
Yes Yes Anddddddddddcsssss
where:
a=an ID character 'A' (0x41)
n = one number system digit
d = one data digit
c = one check digit
s = one supplement digit
Bar code commands
This section describes the commands that may be used to program the HC bar code reader interface.
The bar code interface is programmed by writing an escape sequence to the interface unit via a serial port.
With two exceptions, each escape sequence consists of a short text string in the following format:
<Esc>-y<code><command>
14-11
I/O DEVICES REFERENCE
1. <Esc> is the escape character (0x1b)
2. - isa'-' character (0x2d)
3. y isa'y' character (0x79) or a'y' character (0x59)
4
<code> is a parameter to the command, consisting of sequence of one to three numeric digit,
representing a decimal number between zero and 255.
5. <command> is an upper case alphabetic character identifying the command to be executed.
The two exceptions are the hard reset command:
<ESc>E
and the command to set the data termination string, which includes additional text following the letter
that identifies the command:
<Esc>-y<code><command><text>
In all cases the escape sequence must not contain any embedded spaces.
Commands to the bar code reader interface do not have to be issued individually. The /ssuing multiple
commands section in this chapter describes how several commands may be issued as a multiple escape
sequence, within one text string.
Multiple options in a command
Many of the bar code interface commands offer more than one option, selected by the <code> value. To
select multiple options from a single command, simply sum all the required individual <code> values
together, and then pass this summed value as the <code> value within the escape sequence.
For example, the Select bar code symbology command <Esc>-y<code>F (described later in this chapter)
contains options to select five different bar code formats. For example, a <code> value of | selects Code
39, a value of 4 selects Codabar and a value of 8 selects UPC/EAN. You can select all three formats in a
single command by setting the <code> value to 1+4+8 = 13, as follows:
<Esc>-y13F
Issuing multiple commands
Several individual escape sequence commands may be concatenated together and be transmitted to the bar
code interface as a single escape sequence. To do this, append one or more additional <code><command>
character sequences to the end of a standard, single, escape sequence.
When issuing multiple commands, all of the intermediate <command> ASCII characters must be lower case
letters, and the terminating <command> character must be an upper case ASCII character.
As with a single command, the escape sequence must not contain any embedded spaces.
For example, following three commands:
<Esc>-y13F Select Codabar, UPC/EAN and Code 39 symbologies
<Esc>-y2H Do not transmit Codabar start and stop characters
<Esc>-y1D Insert a 10 ms delay between each data character
may be concatenated into a single escape sequence:
<Esc>-y13£2h1D
The order of issuing commands is usually not important, so that the following three escape sequences are
all functionally identical:
<Esc>-y13f£2h1D
<Esc>-y2h1d13F
<Esc>-y1d13£2H
Exceptions to this rule are mentioned explicitly in the following descriptions of the individual commands.
14-12
14 HC INTELLIGENT BAR CODE READER/RS232 PORT
Serial intercharacter delay <Esc>-y<code>D
Enable or disable a ten millisecond delay between the transmission of each data character in the bar code
data string.
<code> Option
0 No delay
1 Turn 10 millisecond delay on
The default value is equivalent to the command <zsc>-yop.
Hard reset <Esc>E
Perform a hard reset and run a self-test.
A hard reset will take approximately one second to complete. During this time, the bar code reader
interface will not react to any further commands that may be written to it.
All previous escape sequence commands sent to the bar code interface will be aborted when a hard reset is
executed. After the reset has taken place, all of the interface options will revert to their default values.
If the interface has failed its self-test, it will immediately transmit one of the following four messages:
ROM SELF TEST FAILED<CR><LF>
PROCESSOR SELF TEST FAILED<CR><LF>
LOWER RAM SELF TEST FAILED<CR><LF>
UPPER RAM SELF TEST FAILED<CR><LF>
No message will be issued if the interface has passed the self-test.
Note that the diagnostic messages will always be terminated by a carriage return (0x0d) and line feed
(0x0a) character pair, regardless of any previous command to set the termination characters.
All subsequent messages from the interface will be terminated with a (default) single carriage return
character.
A Hard Reset will not normally be issued as part of a multiple instruction escape sequence, because it will
cause all prior commands to be overridden by default settings, and all subsequent commands within the
escape sequence to be ignored by the bar code reader interface while it resets itself.
Select bar code symbology <Esc>-y<code>F
Set the barcode reader to recognise one or more barcode formats, as indicated in the following table:
<code> Enable bar code format:
1 Code 39
2 Interleaved 2 of 5
4 UPC/EAN
8 Codabar
16 Code 128
For example, to read Code 39 and UPC/EAN bar codes only, use:
<Esc>-y5F
If a bar code format has not been enabled, then the bar code reader will ignore all scans in that code
format.
The default setting for this option is equivalent to the command <zsc>-y31F.
Note that it may be necessary to set additional interface options to enable the interface to read certain bar
code formats.
14 - 13
1/0 DEVICES REFERENCE
Check character options <Esc>-y<code>G
Enable or disable verification/check digits and check characters within bar code scans. The precise action
of this command is dependent upon the bar code format being scanned, as indicated below.
The default state corresponds to the command <Esc>-y0c.
Code 39 and Interleaved 2 of 5
For Code 39 and Interleaved 2 of 5 bar codes, the bar code reader may be programmed to verify, or to
ignore check characters in the bar code scan. In addition, the bar code reader may be programmed to
transmit, or to omit the verification character from the scan data when it is transmitted to the host
computer.
<code> Option
0 Do not verify check characters
1 Verify Code 39 check characters
2 Verify Interleaved 2 of 5 check characters
8 Transmit Code 39 and Interleaved 2 of 5 check characters
UPC/EAN
The contents of UPC/EAN bar code scans are always checked against the check digit. However, the bar
code reader may be programmed to transmit, or to omit the check digit when the scan data is transmitted
to the host computer. Note that the check digit in a UPC E bar code is never transmitted to the host
computer.
The bar code reader may also be programmed to decode UPC E 0 bar codes, or it may be programmed to
automatically discriminate between UPC E 0 and UPC E 1 version bar codes.
<code> Option
0 Read UPC E 0 only, transmit UPC/EAN check digit
32 Do not transmit UPC/EAN check digit
64 Read both UPC E 0 and UPC E 1
Decoding options <Esc>-y<code>H
This command provides several assorted programming options to the programmer. For UPC/EAN bar
code scans, the bar code reader may be programmed to accept (zero, two or five) supplemental digits in
the code, and to expand UPC E bar codes automatically into a UPC A code format, if required.
The bar code reader may also be programmed using this command to decode Code 39 bar codes in
standard, or in extended mode. If the extended option is selected, then the bar code reader will encode
each character pair into the corresponding ASCII characters; if standard mode is selected, then each
character in the scan data is decoded individually.
The bar code reader may also be programmed to retain (or discard) Codabar start and stop characters in
the scan data it transmits to the host computer.
<code> Option
1 Extended Code 39
0 Standard Code 39
2 Do not transmit Codabar start and stop characters
0 Transmit Codabar start and stop characters
4 Read UPC bar codes only
0 Read both UPC and EAN bar codes
8 Decode UPC/EAN 2 digit supplement data
0 Do not decode UPC/EAN 2 digit supplement data
16 Decode UPC/EAN 5 digit supplement data
0 Do not decode UPC/EAN 5 digit supplement data
32 Expand UPC E bar codes into UPC A bar codes
14-14
14 HC INTELLIGENT BAR CODE READER/RS232 PORT
0 Do not expand UPC E bar codes
64 Auto discriminate UPC/EAN supplementals
0 Require UPC/EAN supplementals
128 Transmit UPC/EAN ID characters
0 Do not transmit UPC/EAN ID characters
The default setting is equivalent to the command <zsc>-y0H.
Notes
When the option is set to decode UPC/EAN 2 digit (or 5 digit) supplement data, then the bar code label
must be scanned in the forwards direction only.
Only UPC/EAN bar codes containing supplement digits may be read by the interface if either, or both of
these options has been enabled. Both the 2 digit and 5 digit options may be enabled together to allow both
types of bar code scans to be read by the interface, if required.
If the supplement digit options are not enabled by this command, then bar code labels containing
supplement digits may still be scanned, and they may be scanned in both directions (i.e. forwards or
backwards). However the supplement digit data is not transmitted to the host computer.
Single read mode <Esc>-y<code>J
This command will force the bar code reader to abort any current scan and not transmit that scan data to
the HC.
Enabling Single read mode means that the bar code reader will read a single bar code label each time a
Single read control command is issued.
When Single read mode is disabled, the bar code reader will attempt to read a bar code label whenever a
label is scanned.
<code> Option
1 Single read mode is enabled
0 Single read mode is disabled
The default value is equivalent to the command <zsc>-you.
Single read control <Esc>-y<code>K
This command will force the bar code reader to abort any current scan and not transmit that scan data to
the HC.
When Single read mode has been enabled (see above), the-Single read control may be used to enable the
bar code reader, so that it then will read one scan.
<code> Option
1 Read next scan
Set Interleaved 2 of 5 length <Esc>-y<code>M
This command presets the length of Interleaved 2 of 5 bar code read by the bar code reader.
There are three length checking options available:
<code> Option
0 The bar code may have a variable length, between 4 and 32 digits
1..32 The bar code is <code> digits long (even values only)
33 The bar code may only contain either 6 or 14 digits
The default setting is equivalent to the command <zsc>-yom.
14-15
I/O DEVICES REFERENCE
Notes
Although the Interleaved 2 of 5 bar code length may be set to the minimum setting (i.e. two digits), short
Interleaved 2 of 5 bar codes may well appear in other, longer bar codes. As a result, false readings may be
given when other formats of bar code label are scanned, which may be misinterpreted as two digit
Interleaved 2 of 5 labels. Consequently, the minimum setting of 2 digits in this option is not
recommended.
An Interleaved 2 of 5 bar label must contain an even number of digits. If <code> is set to an odd number
between one and thirty one, then the micro controller will automatically round up the value to the next
higher even number.
Set termination string <Esc>-y<code>O<string>
This command will force the bar code reader to abort any current scan and not transmit that scan data to
the HC.
Append the termination string <string> to the end of every bar code data message transmitted to the
HC computer by the micro controller, to mark the end of that message.
The default termination string is a single carriage return character (0x0a). However, a user-defined
termination string may be defined with this command, which will be used to terminate all subsequent
message transmitted by the bar code reader interface. An example escape sequence, which substitutes the
characters "stop" as the terminating string in place of the default value, is:
<Esc>-y4Ostop
A termination string may contain a maximum of four characters and a minimum of zero characters. The
total number of characters contained within the termination string must be passed as the <code> argument
of the escape sequence.
The default termination string transmitted by the bar code reader is a single carriage return character
(0x0d).
Unlike all other sequence commands described in this document, the ASCII characters for the termination
string follow the command identifier character that normally terminates a command. As a result this
command must be positioned last, if issued within an escape sequence that contains more than one
command (even if the terminating string contains zero characters).
For example, consider the commands:
<Esc>-y4Ostop Set the termination string to "stop"
<Esc>-y1D Insert a 10 ms delay between each data character
If these commands are combined in a single escape sequence, that sequence must be:
<Esc>-yl1d40stop
Code ID characters <Esc>-y<code>Q
Instruct the bar code reader to add a lower case ID character to the data message transmitted to the HC, to
identify the symbology of the bar code. This ID code character is transmitted before the bar label data.
The following values will enable, and disable this option:
<code> Option
1 Transmit ID characters
0) Do not transmit ID characters
The table below displays which lower case ASCII character ('a' - 'e') is used to identify each type of bar
code label:
ID character Bar code format
Code 39
Interleaved 2 of 5
UPC/EAN/JAN
Codabar
Code 128
o0oaadaas ow
The default state is equivalent to the command <Esc>-y0o.
14 - 16
14 HC INTELLIGENT BAR CODE READER/RS232 PORT
Status request <Esc>-y<code>S
This command will force the bar code reader to abort any current scan and not transmit that scan data to
the HC.
Return a data string to the host computer, containing information about the status of the firmware inside
the bar code reader.
<code> Option
1 Transmit the status message
The status message that is transmitted back to the HC in response to this instruction is:
HBCR-161X Version 15.x
followed by the current termination string, where "15.x" represents the present revision level of the
firmware inside the bar code reader interface.
Scanner enable <Esc>-y<code>W
This command will force the bar code reader to abort any current scan and not transmit that scan data to
the HC.
Enable or disable the bar code reader.
When disabled, the bar code scanner will not read data from any bar code labels.
<code> Option
1 Enable the bar code scanner
0 Disable the bar code scanner
The default is for the bar code scanner to be enabled.
RS232 port/bar code driver services
The RS232 port/bar code device driver supports all the services that are described in the Serial Port
chapter of this manual. This section describes only those services that provide modified or additional
behaviour when used with the bar code reader interface. These include services to open the port, write
data to the bar code interface and read data from a bar code wand connected to the port.
p_open(TTY:) Open the device
INT p_open(VOID **ppcb, "TTY:B",-1);
Open a channel to the RS232 port/bar code device.
The table below displays which device should be accessed to open the RS232 port or the bar code reader
interface, when the expansion module has been inserted into either of the the top and bottom slots of the HC.
Slot RS232 port _Bar code port
Top TTY:A TTY2¢
Bottom TTY:B TTY:D
On opening a channel, RS232 port, the bar code reader interface and any connected wand or scanner will
all be powered up automatically.
Returns zero if the device was opened successfully, otherwise a negative error.
For example, the following code fragment illustrates the opening of a channel to the bar code interface
with the device in the top slot of the HC.
LOCAL_D VOID *pHandle;
INT result;
result=p_open (&pHandle, "TTY:D",-1);
14-17
1/0 DEVICES REFERENCE
p_close Close the channel
INT p_close (VOID *pcb)
Close the channel to the RS232 port/bar code device.
Returns zero.
Closing the channel will also cause the RS232 port/bar code interface to be powered down. To save battery
power, a device should be closed as soon as it is no longer required.
Note that when the device is closed, or when the HC automatically powers down, all of the information
programmed into the bar code interface will be lost. If you do not wish to use the default settings of the
bar code reader interface, then you will need to reprogram your custom settings back into the interface
when the device is next opened.
P_FSENSE Sense serial port characteristics
INT p_iow(VOID *pcb, P_FSENSE, P_SRCHAR *pserial);
Sense the serial port characteristics, writing them to the P_sRcuar struct (defined in p_serial.h) pointed to
by pserial.
The P_FSENSE service cannot fail and returns zero.
If using the bar code interface, the serial port characteristics must be altered once a channel is opened, to
allow the interface to communicate successfully with the HC. See the description of the P_Fset service for
further details.
P_FSET Set serial port characteristics
INT p_iow(VOID *pcb, P_FSET, P_SRCHAR *pserial);
Set the serial port characteristics from the P_sRcHar struct (defined in p_serial.h) pointed to by pserial.
Returns zero if the P_FSET service completed successfully, otherwise returns a negative error.
If using the bar code interface, the serial port characteristics must be altered once a channel is opened, to
allow the interface to communicate successfully with the HC. Since the bar code interface does not use
RTS/cTS handshaking, the cts line in the serial port must be disabled.
The following code fragment illustrates the use of the P_FsENSE and P_FSET services to disable RTS/cTS
handshaking:
#include <p_serial.h>
LOCAL_D P_SRCHAR srChar;
LOCAL_D VOID *pHandle;
f_leave (p_open (&pHandle, "TTY:D",-1));
p_iow(pHandle,P_FSENSE,&srChar); /* read default settings into srChar */
srChar.hand=P_IGN_CTS; /* suspend RTS/CTS handshaking */
p_iow (pHandle, P_FSET, &srChar) ; /* set up port with new settings */
Note that this code assumes that it is called under the protection of p_enter.
P_FREAD Read from device
VOID p_iow (VOID *pcb, INT P_FREAD,VOID *buf,UINT *plen)j;
VOID p_ioc (VOID *pcb, INT P_FREAD,WORD *pfstat,VOID *buf,UINT *plen)j;
Read up to *plen bytes of data from the device into the buffer pointed to by buf. The buffer is assumed to
be of sufficient length to receive the data. If using an asynchronous P_FREAD service, it is the caller's
responsibility to preserve the data space pointed to by buf and plen until the service completes.
The result is returned by a call to p_iow and written to *pfstat by the asynchronous call. The result is
zero if the service completed successfully, otherwise it is a negative error.
14 - 18
14 HC INTELLIGENT BAR CODE READER/RS232 PORT
A read operation may take an indefinite time to complete and it should therefore be executed
asynchronously within a quality system. For clarity, the following example code uses synchronous reads.
define MAX_BARCODE 128
define TERMINATE_CHAR 0x0d
VOID *pHandle;
TEXT *p;
NT len;
UINT count;
TEXT buf [MAX_BARCODE+2];
len=0;
count=1;
p=ébuf [0];
FOREVER
{
p_iow(pHandle,P_FREAD,p, &count) ;
lent+=1;
if ( (*p++==TERMINATE_CHAR) | | (len>=MAX_BARCODE_LEN) )
{
*--p=0; /* convert to a zero-terminated string */
len-=1;
break;
}
}
p_printf("Bar code is %s, containing %d bytes", &ébuf[0],len);
P_FWRITE Write to device
INT p_iow(VOID *pcb, INT P_FWRITE,VOID *buf,UINT *plen);
VOID p_ioc(VOID *pcb, INT P_FWRITE,WORD *pfstat,VOID *buf,UINT *plen);
Write up to *pien bytes of data from the buffer pointed to by buf to the device. If using an asynchronous
P_FWRITE Service, it is the caller's responsibility to preserve the data space pointed to by buf and plen
until the service completes.
The result is returned by a call to p_iow and written to *pfstat by the asynchronous call. The result is
zero if the service completed successfully, otherwise it is a negative error.
A write operation may take an indefinite time to complete and should therefore be executed
asynchronously within a quality system. For clarity, the following example uses a synchronous write.
The following code fragment transmits the escape sequence <Esc>—y1d24f2u to the bar code reader
interface:
#define MAX COMMAND 64
VOID *pHandle;
UINT len;
UBYTE command [MAX_COMMAND+2];
p_scpy (&command[0],"\033-y1d24f£2H") ;
len=p_slen(&command[0]) ;
p_iow (pHandle, &command [0], &len) ;
14-19
I/O DEVICES REFERENCE
An example program
The program listed below will operate a bar code interface connected to either the top, or the bottom of the
HC. The program will read scanned bar code data from the reader interface, display that information on
the screen and then await a key press. The scanning operation may be repeated as many times as required.
Press the X key after a scan to exit the program; pressing the V key will display the firmware status of the
software inside the bar code interface.
This program is only given here as a simple example of how to program the micro controller and read
scan data: a quality system should carry out more rigorous testing for errors, and should also use
asynchronous operations to read and write the data.
#include <plib.h>
#include <p_serial.h>
#define MAX _STRING 128
LOCAL_D VOID *pHandle;
GLDEF_C INT main (void)
{
P_SRCHAR srChar;
INT len, onebyte,result, reply;
TEXT buffer [MAX_STRING+2];
/* Try to open a port */
if (p_open(&pHandle, "TTY:D",-1) <0)
{
if ((result=p_open (&pHandle, "TTY:E",-1) ) <0)
p_panic(result);
}
/* Set up serial port characteristics */
p_iow (pHandle, P_FSENSE, &srChar) ;
srChar.hand=P_IGN_CTS;
p_iow (pHandle, P_FSET, &srChar) ;
buffer[0]='\0';
onebyte=1;
do
{
/* Display menu on screen */
p_printf(" BAR CODE SCANNER") ;
p_printf("%s",buffer) ;
p_printf("\npress V for Version,");
p_printf Le X to eXit");
p_printf (* or any other key");
p_printf Cy to scan a label");
reply=p_tofold(p_getch());
if (reply=='V')
p_write (pHandle, "\033-y1S",5);
if (reply!='X"')
{ /* Read input from the bar code interface */
len=0;
do
{
p_iow (pHandle, P_FREAD, &buffer[len],é&onebyte) ;
} while (buffer[lent+]!=13 && len<MAX_STRING) ;
len--;
buffer [len]=0;
p_sound (5,300);
}
14 - 20
14 HC INTELLIGENT BAR CODE READER/RS232 PORT
if (reply!='X"')
{
if (reply!='V')
p_printf ("CODE %s",buffer) ;
else
{
p_printf(" Version:\n &$s",buffer);
p_printf("Press key to continue");
p_getch();
}
}
} while (reply !='X');
p_close (pHandle) ;
return (0);
}
14-21
CHAPTER 15
INTRODUCTION TO PSION
INFRARED COMMUNICATIONS
Note: This document is a beta version and may be subject to change.
About this chapter
The use of infrared (IR) as a medium allows devices to communicate without using a connecting cable.
The Psion Series 3c (S3c) and Psion Siena both run an Infrared Communications (“Beaming”)
application. This application sits on top of a communications protocol stack that implements the standards
set by the Infrared Data Association (IrDA), (see http://www.irda.org/irda/irdabout.html). These standards
specify both the physical and the link layer. This chapter describes the application programming interface
to the Psion implementation of the IrDA standards, and gives details of the standards only where relevant.
For a full understanding of infrared communications you should read the IrDA standards documents,
copies of which are downloadable from the IrDA website, (http://www. irda.org/irda/standrd.html). The
three relevant standards employed by Psion are tabulated below:
IrDA standard Communications layer
Serial Infrared Link Management Protocol (IrLMP) Network layer (OSI layer 3)
Serial Infrared Link Access Protocol (IrLAP) Data link layer (OSI layer 2)
Serial Infrared Physical Layer Link Specification (SIR) Physical layer (OSI layer 1)
The IrDA protocol layer model
Application Software
Client side Process
Boundary
Server side Transport entities
e.g. IrDA IR “Tiny” TP
IrDA Link Management Protocol Layer (IrLMP)
IrDA Link Access Protocol Layer (IrLAP)
IrDA Serial Infrared Layer (SIR)
The IrDA protocol stack
15-1
1/0 DEVICES REFERENCE
Introduction to Psion infrared communications
Important note:
The Psion S3a and Psion Siena IR ports are designed only for IDA compliant communication. They are
not suitable for communication with machines that use other standards.
The Psion protocol layer model
Application Software
C/OPL SDK Examples Psion IR Printing Psion IR Communications
Accesslr API
= “IRP” API
“IRP:”
. ; Accesslr : “AIR:”
Client side IPC
IrMUX API
Server side
Link Management Protocol Layer (IrLMP)
Link Access Protocol Layer (IrLAP)
Serial Infrared Layer (SIR)
The Psion infrared protocol stack
The physical layer
The Serial Infrared Device Driver (SIR) provides services to the layer above it (IrLAP), and directly
controls the Psion computer’s hardware.
Port geometry
The Psion serial infrared software supports a link between two machines from zero to at least one metre
apart as shown below. These machines can be two Psions (S3c or Siena) or a Psion and another device
such as a printer with an IrDA compliant interface. The ports on the two machines do not need be aligned
perfectly.
Infrared
Ports
Machine 1
Length of
link
Otoim
Machine 2
The port geometry for two machines using IrDA infrared communications
Internally the Psion IR port is configured as below:
15 -2
15 INTRODUCTION TO PSION INFRARED COMMUNICATIONS
lie a F Output i
Driver
Encoder & LED
Encoder/ IR
Decoder Transducer
Module Module
IR Receive Detector &
Condor chip
Psion Active
data bus Output
Interface
IR In
Decoder MH Receiver i Active
james Input
Interface
The internal organization of the Psion serial infrared
communications port
The Condor chip contains a UART which handles both standard wire based RS232 communications and
IR communications. The device is switched between these two modes and cannot handle both at the same
time.
Data transfer rate
The Psion serial infrared communications port operates at the standard IrDA speed of 9600 Baud. It can
also work at other speeds on the S3c and Siena, (these are optional to the IrDA standard):
Speed (Baud) S3c Siena
2,400 Yes Yes
9,600 Yes Yes
19,200 Yes Yes
38,400 Yes No
57,600 Yes No
115,200 Yes No
Data link layer
The IrDA data link layer protocol (IrLAP) is based on the standard asynchronous HDLC and SDLC half
duplex protocols.
It has the following extra features, (mostly to handle the mobile, ad-hoc nature of the medium):
e Extended addressing
e Dynamic address conflict resolution
e Extended error recovery mechanisms
e Dynamic station discovery/identification
e Extended connection setup, (so that stations can negotiate to establish the best connection speed
that both connecting machines can support)
e Any station can contend to become a primary station
e Extended rules for medium access, (to resolve contention between stations competing for control
of the medium).
IrLAP uses services provided by the physical layer (SIR), and provides services to the layer above it (ITLMP).
15 -3
I/O DEVICES REFERENCE
Primary and secondary stations
At any given instant there may be at most one IrLAP connection between a given pair of stations (IrDA
compliant machines). One of the machines must assume the role of IrLAP primary station while the other
must assume the role of IrLAP secondary station.
An IrDA primary station is a machine that takes responsibility for data flow control and for unrecoverable
data link errors.
An IrDA secondary station is any station that has an IrLAP connection active and that has not assumed
the role an IrLAP primary station.
IrLAP services
IrLAP provides two general types of services:
e Connectionless services
e Connection-oriented services
A connectionless service involves either the general broadcast of a message from a station, and/or the
general reception of a message by a station, without the necessity of identifying the other station (if any)
involved. Connectionless messages (datagrams) are sent with the expectation that they will be received
correctly; there is no acknowledgement of correct receipt. If a message is received incorrectly, a higher
layer must ask for re-transmission.
A connection-oriented service requires that both stations involved in the message transfer have knowledge
of the other’s characteristics. A logical session is set up between the primary and secondary station, and
there is acknowledgement that messages are correct.
The network layer
The IrDA Link Management Protocol (IrLMP) uses services provided by the data-link layer beneath it
(IrLAP) and provides services to clients above (i.e., transport entities and/or applications).
IrLMP consists of two parts, both of which are accessible by the Psion IrMUX API using IPC:
e LM-IAS (Link Management Information Access Service)
e LM-MUX (Link Management Multiplexer)
AccessIr is an API added by Psion to simplify IR communications - it is not part of the IrDA protocol
standard - and sits above IrLMP on the client side. It uses the AIR: device driver.
An application developer can choose to use either the API to AccessIr (recommended) or the API to
IrMUX. Whichever one is used the sequence of operations required to set up, use and close down an IR
link is similar.
For a connection-oriented service the link management process involves several stages:
e IAS application logging (secondary station)
e discovery (primary sation)
e §=multiplexing the link (primary sation)
e controlling the link (primary sation)
e closing down the link (primary sation)
IAS application logging
The IAS works by each IrDA device keeping a database of the services (IR enabled applications) that the
device currently has available. Applications must register with the IAS server on their station so that they
are added to this database. Software on one machine can then find out the services available on another
machine by querying the database of services on that machine. Applications can also remove themselves
from the IAS database.
15-4
Discovery
15 INTRODUCTION TO PSION INFRARED COMMUNICATIONS
Discovery is the process whereby the IrDA primary station sets up a database of the secondary stations
that are currently within IR communication range. This database is distinct from the IAS database.
Each record in the discovery log is a DISCovERY_LOG struct:
typedef struct
{
UINT solicited;
UINT sniff;
ULONG devAddr;
UINT lapVersion;
UBYTE info[32];
} DISCOVERY_LOG;
The piscovery_toe fields are:
solicited
sniff
devAddr
lapVersion
info
If TRUE, indicates that the discovered information was solicited by an explicit discovery
request by the host station. If FALSE, indicates that the discovered information was
unsolicited (i.e. responding to a previously received discovery XID CMD frame).
If TRUE, indicates that the remote (discovered) device is a sniffing device.
The remote (discovered) station’s 32-bit device address.
The 16-bit IrDA version number of the remote (discovered) IrLap layer. Should hold oxoo
indicating that the remote machine conforms to the IrDA IrLAP 1.00 specification
32 bytes of user-defined data passed from the remote (discovered) station to the host
station. This discovery information is used by peer MUX layers for identification
purposes. At the current default baud of 9600, only 23 bytes of the discovery info field can
actually be used.
For a Psion machine info will contain the non-zero-terminated string “Psion Series3” or
“Psion Siena” for an S3c or Siena respectively.
The info field also contains the following bytes:
byte
2 bytes
Character set
Service hint
Indicates the character set supported by the remote machine; 0xoo here indicates
ASCII
Give an indication as to the level of IrLMP support provided by the discovered
device.
The service hint bitfields are as follows:
BYTEI1:
Bit
0
6
q
Function
PnP Compatible
PDA/Palmtop
Computer
Printer
Modem
Fax
LAN Access
Extension
6
7
Function
Telephony
File Server
IrCOMM
reserved
reserved
reserved
reserved
Extension
Full details can be found in the IrDA IrLAP specification.
15-5
I/O DEVICES REFERENCE
Multiplexing
Multiplexing the link allows independent applications (services) to exchange data using a single IrLAP
link. Software on one machine can discover the services available on another machine by querying the
database of services on that machine.
Link Control
Managing the use of the multiplexed link is called Link Control. This includes allowing certain client
applications to take exclusive control of the IrLAP link connection, (Exclusive mode).
The Psion IR Communications application
The Psion IR Communications application (sometimes called IR Beaming) uses the Psion Link Paste
mechanism when sending data, (see the Link Paste chapter in the OLIB Reference manual). The IR
Communications application takes whatever data was highlighted in the most recent application to declare
itself to be the Link Paste Server (or the selected file in a System Screen file list or directory), and uses
that as the data/file to send. Receiving data over IR works independently of the Link Paste mechanism.
Third party applications
Any existing application that supports the Link Paste mechanism will work with the Psion IR
Communications application to send data. In general this means that it must be an HWIM program,
because it uses the ATS mechanism. To modify an HWIM program so that it can use IR Receive:
e add the Bring keycode (21) to the accelerator list
e map the Bring keycode to the command manager method used to implement “bring”
functionality
It is much more involved to add IR Receive capability to non-HWIM applications, such as HWIF ones.
They could be made to explicitly look for the IPC messages relating to the Bring keycode, but this is not
SO easy.
System resources
A SYS_IR_POWER_LEVEL resource has been added, giving the text “High” and “Low” for Infrared power
levels.
A syYS_PRINTER_IR resource has been added, giving the text “Infrared” as a printer type.
Keypresses
Normally, IR-related keys are captured by the built-in IR data transfer application. If the user disables IR,
by selecting another mode of communication, these keypresses are absorbed by the ws_process_key
method of any application’s instance of wsERv. As a general service to the user, the method also displays
an “Infrared not enabled” information message.
The ws_process_key method of the wsserv class performs the following additional action on the Series 3c:
e if the keypress is w_kEY_IR_LINK, 0x142 (which would normally be captured by the infrared
file/record transfer software) display an information message to the effect that Infrared is disabled
The ws_process_key method of the wserv class performs the following additional action on the Siena:
e if the keypress is one of w_kEY_IR_BRING, 0x140 Of W_KEY_IR_SEND, 0x141 (which would
normally be captured by the infrared file/record transfer software) display an information
message to the effect that Infrared is disabled.
15 INTRODUCTION TO PSION INFRARED COMMUNICATIONS
The IR printer port device driver
Psion Series 3c machines are capable of point and shoot printing using IR, to IrDA compliant printers.
Infrared enabled printers on the market at the time of writing include:
e HPLaserJet 5P
e ~=6HP DeskJet 340
e §6©Citizen PN60
The Psion IR printer port device driver rrp: is an example of a device driver that sits logically above AIR:
on the client side. It works in exactly the same way as the normal par: parallel port device driver. The
IRP: device driver automatically starts the IR protocol stack.
Siena models do not have the driver in ROM. The driver JRLPT.LDD is installed in \SIBOSDK\LIB as
part of the LDD component of the optional disk, to be loaded onto a Siena if required.
15-7
CHAPTER 16
THE ACCESSIR API
Note: This document is a beta version and may be subject to change.
Using the Accesslr API
Prerequisites
It is essential that the Introduction to Psion Infrared Communications chapter has been read before this
chapter.
Introduction to using the Accesslr API
The AccessIr API facilitates Infrared communication between two Psion machines (Series 3c and/or
Siena), using the AIR: device driver, accessir.ldd. This API is much easier to use than the IrMUX API,
but gives less flexibility. It is therefore recommended that the AccessIr API is used for all simple IR
communication applications. It is not present in the Siena ROM, but is installed in the \S/BOSDK\LIB
directory as part of the LDD component of the SIBO C SDK Optional disk, to be loaded onto a Siena if
required.
The AIR: device driver is not present in the ROM of Siena machines, and is 1.7KB in size. It must be
loaded first (after transfer onto the machine’s internal drive) by using:
p_loadldd(“ACCESSIR.LDD”)
The AIR: device driver must be unloaded at the end on the Siena using:
p_devdel (“ACCESSIR”, E_LDD)
Otherwise there are no differences between using the AccessIr API on the Siena and on the Series 3c.
Only a connection-oriented option is available.
AccessIr requires the IR protocol stack to be started first (as it must be when using the TMUX API).
There are then seven steps in the communication process for the primary station:
1. Open a channel to the AccessIr device driver
Discover and log the remote machines
Select a remote machine
Connect to the selected remote machine
Send or accept data
Disconnect
SP NE Ps, Ee IBS
Close the channel to its IR device
16-1
I/O DEVICES REFERENCE
There are five steps in the process for the secondary station:
1. Open achannel to the AccessIr device driver
2. Wait for the primary station to connect
3. Send or accept data
4. Optional Disconnect
5. Close the channel to the AccessIr device driver
In all the code examples and function call prototypes below, either p_iow(), p_ioa() Of p_ioc() may be
used where p_iow() is given. The constants used in the AccessIr API are defined in the p_file.h PLIB
include file.
Initialising the IR protocol stack
Before the IR protocol stack can be used it must be initialized, by doing a p_execc. The protocol stack is
started as a separate process.
The argument *name is sys$IRDA.1IMc in the example code segment below:
LOCAL_C HANDLE loadIRDAserver (TEXT *name)
{
INT err;
TEXT serverPath[P_FNAMESIZE];
HANDLE server_pid=NULL;
/* Start the IR process & store its server_pid in property */
if (E_FILE_NXIST==(server_pid=p_pidfind (name) ) )
{ /* Load from M, then from wherever we are... */
f_fparse (name, "LOC: :M:\\", &serverPath[0],NULL) ;
if ((server_pid=p_execc(&serverPath[0],
(UBYTE*) &Server_pid,
sizeof (server_pid) )) <0)
{
f_fparse (name, "ROM::\\",&serverPath[0],NULL) ;
if ((server_pid=p_execc(&serverPath[0],
(UBYTE*) &Server_pid,
sizeof (server_pid) )) <0)
{ /* Error...no irda! */
return (0);
}
}
if (0!=(err=p_presume (server_pid) ) )
return (0);
}
p_sleept (5L); /* Give IRDA a chance to get going! */
return (server_pid);
}
Opening and closing a channel to the IR device
Before a connection can be made, a channel must first be opened to the IR device using p_open(*AIR:”).
This channel must be closed when IR operations have ceased, using p_close().
Example
if (!p_open(&pIR,”AIR:”,0) )
{
p_close(pIR);
}
Discovery
Secondly, a log must be obtained of all remote machines that it is possible to communicate with, using
p_iow (P_FIRDISCOVER) .
Selection
The machine to connect to is then selected from the log, using p_iow (P_FIRSELECT).
16-2
16 THE ACCESSIR API
Connection
Connection is then made by the primary station to the selected secondary station, using
p_iow (P_FIRMAKECONNECT). The secondary station sends a zero terminated string of up to 56 bytes of
connect data to the primary station, when the connection is accepted.
The remote machine must be awaiting connection; it is put in this state by using
p_iow (P_FIRAWAITCONNECT). The primary station then sends a zero terminated string of up to 56 bytes of
connect data to the secondary station when connection is successful.
Sending and accepting data
The primary station may then either send data, using p_iow(P_FWRITE), or accept data from the secondary
station using p_iow(P_FREAD).
Likewise the secondary station may either accept data from the primary station, using p_iow(P_FREAD), OF
send data using p_iow(P_FWRITE).
Disconnection
Once data transfer is complete the connection between the two stations must be discontinued by the
primary station or secondary station, using p_iow(P_FIRDISCONNECT).
Constants
The constants used in the function calls below have the following numerical equivalents:
P_FREAD 1
P_FWRITE
P_FIRDISCONNECT
P_FIRDISCOVER
P_FIRSELECT
2
4
P_FITRAWAITCONNECT 5
6
i
8
P_FIRMAKECONNECT
Opening and closing a channel to the IR device
p_open(“AIR:”) Open a channel to the IR device
INT p_open(VOID *pcb,”AIR:”,0);
Open a channel to the IR device, (IrDA Open function).
If successful the port will be powered up.
Arguments
VOID *pcb Handle
“AIR:” Device name
0 Mode
Return value
INT Zero if the channel was opened successfully; else a
negative error code
Possible errors include:
E_GEN_INUSE Port in use by another client
E_GEN_NOMEMORY Insuffient memory to make connection
16 -3
1/0 DEVICES REFERENCE
Example
if (!p_open(&pIR,”AIR:”,0) )
{
is cies (pIR) ;
}
p_close Close a channel to the IR device
INT p_close(VOID *pcb) ;
Close an open channel to the IR device, (IrDA Close function).
The internal receive data buffer is flushed. If a frame of data is currently being transmitted then
transmission is completed before closure. The transmit data buffer becomes empty. Any outstanding IR
driver read or write requests are cancelled.
Arguments
VOID *pcb Handle
Return value
INT Zero
Example
p_close (pcb) ;
Discovery, selection and connection
p_iow(P_FIRDISCOVER) Discover IR enabled machines
INT p_iow(VOID *pcb,P_FIRDISCOVER, VOID *buf,UWORD *pNslots) ;
Obtain the log of remote machines, (IrDA Discover function).
Arguments
VOID *pcb Handle
P_FIRDISCOVER IR service
VOID *buf Buffer to receive discovery list; on return
contains the list of machines found
UWORD *pNslots Pointer to word containing the number of slots; on
return contains the number of machines found
Return value
INT Maximum number of machines to find
Example
p_iow (pcb, P_FIRDISCOVER, Buffer, pNslots) ;
p_iow(P_FIRSELECT) Select remote machine to connect to
INT p_iow(VOID *pcb,P_FIRSELECT,VOID *Address) ;
Select a machine to connect to, (IrDA Select function).
Arguments
VOID *pcb Handle
P_FIRSELECT IR service
VOID *Address Pointer to long containing machine address
16-4
16 THE ACCESSIR API
Return value
INT Zero
Example
p_iow (pcb, P_FIRSELECT, &Address) ;
p_iow(P_FIRMAKECONNECT) Connect to selected machine
INT p_iow(VOID *pcb,P_FIRMAKECONNECT, TEXT *pname,VOID *buf[0]);
Connect to the selected remote machine, IrDA Make Connect function), where pname points to a string
containing the name of the application to connect to.
Arguments
VOID *pcb Handle
P_FIRMAKECONNECT IR service
TEXT *pname Name of application to connect to. This is a
zero terminated string, maximum 25 characters
long (excluding terminator).
VOID *buf [0] Zero terminated string. On return contains up
to sixty bytes of connect data from remote
machine, if successful
Return value
INT Maximum data send size or negative error
Example
Either p_iow(), p_ioc() OF p_ioa() can be used, e.g.:
p_iow (pcb, P_FIRMAKECONNECT,”Bob’s Chat program”, &Buffer[0]);
IOW (Handle%, 8, #UADD (ADDR (Name$) , 1) , }UADD (ADDR (Buf fer$) , 1) )
Note: contents of Name$ and Buffer$ must be zero terminated
p_iow(P_FIRAWAITCONNECT) Wait for remote connect (primary)
INT p_iow(VOID *pcb,P_FIRAWAITCONNECT, TEXT *pname,VOID *buf[0]);
Wait for a remote machine to connect as the primary station, IrDA Accept Connection function), where
pname points to a string containing the name of the application to connect to on the local machine.
Arguments
VOID *pcb Handle
P_FIRAWAITCONNECT IR service
TEXT *pname Name of your application
VOID *buf[0] Zero terminated string. On return contains up
to 56 bytes of connect data from remote
machine, if successful
Return value
INT Maximum data send size or negative error
Example
Either p_iow(), p_ioc() OF p_ioa() can be used, e.g.:
p_iow (pcb, P_FIRAWAITCONNECT,”Bob’s Chat program”, &Buffer[0]);
16-5
1/0 DEVICES REFERENCE
Send and accept data
p_iow(P_FREAD)
Accept data from selected remote machine
INT p_iow(VOID *pcb,P_FREAD,VOID *Data[0],UWORD *Length) ;
Accept data from the remote machine (IrDA Read function).
Arguments
VOID *pcb
P_FREAD
VOID *Data[0]
UWORD *Length
Return value
INT
Example
Handle
IR service
Buffer to receive data
Pointer to word to receive data length. On
return contains the amount of data received
Zero or negative error,
Either p_iow(), p_ioc() OF p_ioa() can be used, e.g.:
p_iow (pcb, P_FREAD, &Data[0],&Length) ;
p_iow(P_FWRITE) Send data to the selected remote machine
INT p_iow(VOID *pcb,P_FWRITE, VOID *Data[0],UWORD *Length) ;
Send data to the remote machine (IrDA Write function).
Arguments
VOID *pcb Handle
P_FWRITE IR service
VOID *Data[0]
UWORD *Length
Buffer of data to be sent
Pointer to word to containing data length
Return value
INT Zero or negative error
Example
Either p_iow(), p_ioc() OF p_ioa() can be used, e.g.:
p_iow (pcb, P_FWRITE, &Data[0],&Length) ;
SSS SSS SS |
Disconnection
p_iow(P_FIRDISCONNECT) Disconnect from remote machine
INT p_iow(VOID *pcb,P_FIRDISCONNECT) ;
Disconnect from the connected remote machine and cancel all requests, (IrDA Disconnect function).
Arguments
VOID *pcb Handle
P_FIRDISCONNECT IR service
Return value
INT Zero or negative error,
Example
p_iow (pcb, P_FIRDISCONNECT) ;
IOW (Handle%, 4, #0, #0)
16 - 6
16 THE ACCESSIR API
Example application
The following application allows one Psion machine to act like a sending teletype (constantly queueing IR
write calls) and another Psion to act like a receiving teletype (constantly queueing IR read calls).
/* MODULE - ACCESSIR.C
Copyright (C) Psion PLC 1995/6
*/
include <plib.h>
ifndef EPOC
GLREF_D P_DEVICE p_serial,p_file,p_keyb,p_timer;
endif
LOCAL_D VOID *pIr;
LOCAL_D UBYTE buf[256];
LOCAL_D TEXT connData[64]=" ";
LOCAL_D TEXT printstring[24]="Welcome to IR printing!";
LOCAL_D UWORD slots;
LOCAL_D INT readlen,writelen,ret,i;
LOCAL_D UBYTE devName [24];
LOCAL_D ULONG devAddr;
LOCAL_C HANDLE LoadIrdaServer (TEXT *name)
INT err;
TEXT serverPath[P_FNAMESIZE];
HANDLE serverPid=NULL;
/* Start the IRDA stack as a separate process and store its pid */
p_printf ("Trying to start %s",name) ;
if ((serverPid=p_pidfind(name) ) ==E_FILE_NXIST)
{/* Try to load irda from M first */
f_fparse (name, "LOC: :M:\\", &serverPath[0],NULL) ;
if ((serverPid=p_execc(&serverPath[0],
(UBYTE *)&serverPid, sizeof (serverPid) ) ) <0)
{/* Try to load irda from ROM */
f_fparse (name, "ROM::\\",&serverPath[0],NULL) ;
if ((serverPid=p_execc(&serverPath[0],
(UBYTE *)&serverPid, sizeof (serverPid) ) ) <0)
{/* Error ! No irda */
return (0);
}
}
if ((err=p_presume (serverPid) ) <0)
return (0);
}
p_sleept (5L); /* Give irda a chance to get going */
return (serverPid) ;
}
LOCAL_C VOID PrintMenu ()
{
D2 PLEINCE (MAREE ARE RES REA A ERIN) 7
p_printf ("Press \'p\' to make station primary");
p_printf ("Press \'s\' to make station secondary");
p_printf ("Press \'q\' to quit");
Pp DLLME ECU AREER EAR ARR RRR EAE HRI MY ;
}
16-7
1/0 DEVICES REFERENCE
LOCAL_C INT DiscoverDevices ()
{
p_printf ("Doing a discovery");
slots=6;
p_iow(pIr, 6, &buf[0],&slots); /* P_FIRDISCOVER */
p_printf ("Devices found = %d",slots);
if (slots>0)
{/* We have discovered at least one device */
devAddr= *((ULONG *) (&buf[4]));
/* Discovery nickname is last 23 bytes of info */
p_bcpy (devName, &buf[12],23);
i=0;
while (devName[i]>=0x20 && i<23)
itt+;
devName[i]='\0';
p_printf ("Remote devAddr = 0x%08X",devAddr) ;
p_printf ("Remote device = %s",devName) ;
return (0);
}
else
p_printf ("Trying again");
return (-1);
LOCAL_C INT ConnectToFirstDevice()
{
p_printf ("Selecting machine");
ret=p_iow(pIr,7,&devAddr); /* P_FIRSELECT */
p_printf ("Connecting to machine %08X",devAddr) ;
if ((ret=p_iow(pIr,8,"Test",&connData[0]) ) <0) /* P_FIRMAKECONNECT */
{
p_printf("Connect failed with ret = %d",ret);
p_getch();
return (0);
}
p_printf ("Successfully connected machine") ;
}
LOCAL_C VOID TransmitData()
{
INT ret;
p_printf ("Writing keypresses to IR port - ESC to cancel");
writelen=1;
while ((ret=p_getch()) !=27)
{/* OK as long as not escape */
buf [0]=ret;
p_iow(pIr,2, &buf[0],&writelen) ; /* P_FWRITE */
p_print ("%s", &buf[0]);
}
LOCAL_C INT WaitForConnect ()
{
INT ret;
p_printf ("Connecting as a secondary");
if ((ret=p_iow(pIr,5,"Test",&connData[0])) <0) /* P_FIRAWAITCONNECT */
{
p_printf ("Wait for connect failed with ret = %d",ret);
p_getch ();
return(-1);
}
p_printf ("Accepted a connection");
}
16-8
16 THE ACCESSIR API
LOCAL_C INT ReadData()
{
readlen=1;
if ((ret=p_iow(pIr,1,é&buf[0],&readlen) ) <0) /* P_FREAD */
{
p_printf ("Error on reading");
if (ret==DisconnectErr)
p_printf ("Primary has disconnected") ;
return (ret);
}
p_print ("%s", &buf[0]);
return (1);
}
LOCAL_C VOID Disconnect ()
p_printf ("Disconnecting") ;
p_iow(pIr,4); /* P_FIRDISCONNECT */
GLDEF_C INT main(VOID)
TEXT servername[20]="SYSSIRDA.IMG";
#ifndef EPOC
p_inst (&p_file, &ép_serial, &p_keyb, &p_timer, NULL) ;
#endif
p_printf("Psion Software (c) October 1996");
PUPBENEL (MAA AAAAAAAK AAA RAK AKA RAK KAA RA RAK ARE RARE ) -
p_printf("Starting simple AccessIr beaming app");
if ((ret=LoadIrdaServer (servername) ) ==NULL)
{
p_printf ("Problem loading Irda stack");
p_getch();
return (0);
}
p_printf ("Successfully kicked open the irda stack as separate process");
if ((ret=p_open(&pIr, "AIR:",-1)) <0)
{
p_printf ("Cannot open AccessIr driver ret = %d",ret);
p_getch();
return (0);
}
p_printf ("Successfully opened AccessIr driver");
startLoop:
PrintMenu () ;
ret=p_getch();
switch (ret)
{
case 'p!:
case 'P';
/* PRIMARY STATION - TRANSMITTER */
if ((ret=DiscoverDevices ()) <0)
goto startLoop;
ConnectToFirstDevice () ;
TransmitData();
Disconnect ();
break;
16-9
1/0 DEVICES REFERENCE
case 's!':
case 'S':
/* SECONDARY STATION - RECEIVER */
if ((ret=WaitForConnect () ) <0)
break;
while ((ret=ReadData())>0)
/* Keep reading until failure */ ;
break;
case 'q':
case 'Q':
p_printf ("Terminating program") ;
break;
default:
goto startLoop;
break;
}
p_close(pIr); /* This also kills the IrDA process */
p_printf("End of program — Hit key to esc");
p_getch();
return (0);
}
16 - 10
CHAPTER 17
THE IRMUX API
Using the IrMUX API
Prerequisites
It is essential that the Introduction to Psion Infrared Communications chapter has been read before this
chapter.
Introduction to using the IrMUX API
The IrMUX API facilitates Infrared communication between two Psion machines (Series 3c and/or Siena).
This section explains how to use each call that can be made to the IrMUX server using IPC on a SIBO
(EPOC/16) based computer system. This API is more difficult to use than the AccessIr API, but
potentially gives more flexibility. For simple IR communication applications it is recommended that the
AccessIr API is used.
With the IrMUX API connectionless or connection-oriented calls are available.
This set of protocols uses machine addresses and port IDs (rather than application names as for the
AccessIr API).
The packets of data used must be exactly the right size, there is no error correction and there is no
guarantee of transfer.
Initialising the IR protocol stack
Before the IR protocol stack can be used it must be initialized, by doing a p_execc. The protocol stack is
started as a separate process. This is done in exactly the same way as when using the AccessIr API. When
the last application has logged off, the protocol stack will clean up and terminate itself automatically.
17-1
I/O DEVICES REFERENCE
The argument *name is SySSIRDA. IMG in the example code segment below:
LOCAL_C HANDLE loadIRDAserver (TEXT *name)
{
INT err;
TEXT serverPath[P_FNAMESIZE];
HANDLE server_pid=NULL;
/* Start the IR process & store its server_pid in property */
if (E_FILE_NXIST==(server_pid=p_pidfind (name) ) )
{ /* Load from M, then from wherever we are... */
f_fparse (name, "LOC: :M:\\", &serverPath[0],NULL) ;
if ((server_pid=p_execc(&serverPath[0],
(UBYTE*) &server_pid,
sizeof (server_pid) ) ) <0)
{
f_fparse (name, "ROM::\\",&serverPath[0],NULL) ;
if ((server_pid=p_execc(&serverPath[0],
(UBYTE*) &Server_pid,
sizeof (server_pid) )) <0)
{ /* Error...no irda! */
return (0);
}
}
if (0!=(err=p_presume (server_pid) ) )
return (0);
}
p_sleept (5L); /* Give IRDA a chance to get going! */
return (server_pid);
}
Logging on to and logging off from the IrMUX server
Before an application can use IrMUX services it must log on. When it has finished it must log off.
Logging on to the IrMUX server
The LM_Logon function call is used to log on to the ITMUX server.
Logging off from the IrMUX server
The tm_Logof¢ function call is used to log off from the IrMUX server.
Registering/unregistering applications with the LM-IAS server
This is independent of the process of sending or receiving data. An application can either:
e register iself in the LM-IAS database
¢ unregister iself from the LM-IAS database
Registering the port with the LM-IAS server
The tM_RegisterPort function call is used to register the application with the LM-IAS server.
Unregistering the port with the LM-IAS server
The LM_UnRegisterPort function call is used to unregister the application with the LM-IAS server.
LM-IAS services
The LM_GetValueByClass message has not been implemented as a direct IPC service, but an IAS Get
Value By Class frame must be passed from the LM-IAS server of the primary station to the LM-IAS
server of the secondary station. The secondary station replies with another specially formatted frame of
data.
The LM-IAS server on a remote machine is reached by starting a connection to the remote machine,
(using the LM_connectRequest function), with a remote port of zero.
17-2
17 THE IRMUX API
The IAS Get Value By Class service can only be used with a connection to a remote LM-IAS server.
Direct read and write access to a remote LM-IAS port has not been blocked in order to allow future
expansion. A client should not attempt to send frames directly to a remote LM-IAS connection (other than
the Get Value By Class message) without a full understanding of the implications of such actions.
Developers should study the IrDA IrLMP specification.
The IAS Get Value By Class message frame
The format of the frame that must be sent from the primary station is:
byte 0x84
byte name length
n bytes application name, not including zero terminator
byte 0x12
byte “IrDA: IrLMP:LsapSel”
The IAS Get Value By Class reply frame
The format of the frame returned by the LM-IAS server on the secondary station is:
byte AND with ox3r and compare with 4; if not equal to 4, failed
byte 0
byte non-zero
byte don’t care
byte don’t care
byte don’t care
byte 1
byte 0
word 0
byte port number
Connectionless calls
Data may either be sent or received in a connectionless manner. This process involves one step:
e Queue a connectionless read or write request
The first application to read the transmitted data is the one that gets it.
Reading and writing data
The LM_cLReadRequest function call is used to queue a connectionless read request.
The LM_cLwriteRequest function call is used to queue a connectionless write request.
Connection-oriented calls
The steps in the process for a secondary station are:
1. Register the application with the secondary station’s LM-IAS server
2. Wait for the primary station to connect
The steps in the process for a primary station are:
1. Discover and log the remote machines
2. Connect to the LM-IAS server on the selected remote machine
3. Ask for a particular registered application (by preparing and sending a LM_GetvalueByClass
message)
4. Wait for the reply (the secondary station returns a port ID for the required application)
5. Close the LM-IAS connection
17-3
I/O DEVICES REFERENCE
6. Reconnect using the port ID previously returned for the required application on the
secondary station
7. Send or accept data (either reliably or unreliably)
8. Disconnect
Discovery
The LM_DiscoverDevicesRequest function call is used by the primary station to return information about
machines within transmission range.
Connection - first time
The bm_connectRequest function call is used by the primary station (with a remote port of zero) to
attempt to connect to the LM-IAS server of the remote machine.
If successful the primary station sends an IAS Get Value By Class frame to the secondary station. The
secondary station sends back a frame containing the ID of the port for the application required (previously
registered by the secondary station with its LM-IAS server).
Disconnecting - first time
The LM_DisconnectRequest function call is used by the primary station to disconnect the two
communicating machines, before subsequent reconnection.
Connection - second time
The bm_connectRequest function call is used by the primary station to attempt to re-connect to the remote
machine, using the port ID for the required application, returned previously.
Reading and writing data
Reading and writing data may be done either reliably or unreliably. If unreliable red/write is used then the
data is only sent once.
The LM_ReadRequest function call is used to queue a connection-oriented read request.
The LM_writeRequest function call is used to queue a connection-oriented write request.
The tM_UReadRequest function call is used to queue an unreliable connection-oriented write request.
The bM_UwriteRequest function call is used to queue an unreliable connection-oriented write request.
Disconnecting - second time
The bM_DisconnectRequest function call is used by the primary station to disconnect the two
communicating machines.
Using Exclusive mode
If an application on the primary station wants to be sure of control over the link then it should use
Exclusive mode. A call to bM_AccessModeRequest gives exclusive access to ITMUX. This means that only
that one application can talk, and all other applications are blocked.
If you want to stop other applications from placing IrMUX into Exclusive mode, then the connection
(which always starts in Idle mode) can be put into Active mode, by using the LM_IdleRequest function
call. This should only be done during critical periods of communication. The connection should be put
back in Idle mode when the critical period has finished, by using another call to LM_tdleRequest.
When in Exclusive mode, if the client application is not responding to incoming data quickly enough, the
number of retries to be used on each data frame can be changed (from the default of 1), using the
LM_SetHandshakingLevel function call. The number of retries must be set back to 1 when IrMUX leaves
Exclusive mode.
When exclusive use of IrMUX is no longer required, another call to bm_AccessModeRequest should be
made.
The current status of the link can be found with a call to tM_statusRequest.
17-4
17 THE IRMUX API
The IrMUX API
IrMUX message format
The muxmessace struct has the format shown below.
typedef struct
{
E_MESSAGE Mess; // Message Control
VOID * MessConn; // Connection Handle
VOID * MessArgl; // Argument 1
VOID * MessArg2; // Argument 2
UINT MessArg3; // Argument 3
} MUXMESSAGE
The £_messace struct has the format shown below.
typedef struct message
{
struct message next;
UBYTE *status;
UINT type; // Message Number
HANDLE pid;
} E_MESSAGE;
The Message Number specified for each function below should be used as the type 1n an E_MESSAGE
struct, itself used as the mess field of a muxmEssacE struct.
Argument 1, Argument 2 and Argument 3 refer to the three muxmessace fields MessArg1, MessArg1 and
MessArgl.
For a full description of how to use these structs with the server function p_mreceive, see the chapter
Processes and Inter-Process Messaging in the PLIB Reference manual, and also the chapter Inter-Process
Communication in the OLIB Reference manual.
Unless specified below the argument values are unchanged when the function call returns.
Errors from IrLAP (returned in the status element of the z_messace struct) are documented in the IrDA
Serial Infrared Link Access Protocol (IrLAP) standard document.
LM_Logon Log on to the IrMUX server
Message Number 1
Use this function call to log on to the IrMUX server.
LM_Logoff Log off from the IrMUX server
Message Number 2
Use this function call to log off from the ITMUX server. This will stop any connections still held open by
the client.
LM_RegisterPort Register a port number with the LM-IAS server
Message Number 10
Use this function call to register an application with the LM-IAS server.
The application name must be less than twenty five characters in length and zero terminated.
17-5
1/0 DEVICES REFERENCE
Arguments
Connection Handle Pointer to a vorp*; on return contains the LM-
IAS entry handle
Argument 1 Pointer to a buffer containing the application
name
Argument 2 Irrelevant
Argument 3 The port number
Value of status in the E_MESSAGE struct on return:
OKAY Register successful
E_GEN_NOMEMORY No memory to complete request
E_GEN_RANGE Errors from IrLAP
LM_UnRegisterPort Free registered port with LM-IAS server
Message Number 11
Use this function call to free a registered port number with the LM-IAS server.
Arguments
Connection Handle Entry handle
Argument | Pointer to buffer containing class name
Argument 2 Irrelevant
Argument 3 Irrelevant
LM_CLReadRequest Queue a connectionless read request
Message Number 4
Use this function call to queue a connectionless read request.
It should be noted that in the case of all reads, if a frame is received which is longer than the requested
data size the frame will be truncated and data will be lost. If a received frame is smaller than the length
requested the actual amount of data received will be placed into the urnt pointed to by argument2.
Arguments
Connection Handle Irrelevant
Argument | Pointer to a buffer to receive the data; on return
contains the received data
Argument 2 Pointer to a uInT containing the number of
bytes required; on return the urnt contains the
actual amount of data returned
Argument 3 Irrelevant
Value of status in the = _mMEeSSAGE Struct on return:
OKAY Read complete
E_GEN_INUSE Read already queued
E_MUX_ABORT IrMUX has been destroyed
17 - 6
LM_CLWriteRequest
Message Number 5
17 THE IRMUX API
Queue a connectionless write request
Use this function call to queue a connectionless write request.
Arguments
Connection Handle
Argument 1
Argument 2
Argument 3
Value of status in the E_MESSAGE struct on return:
OKAY
E_GEN_NOMEMORY
(various)
LM_DiscoverDevicesRequest
Message Number 6
Irrelevant
Pointer to a buffer containing the data to send;
Pointer to a uInT containing the number of
bytes to send
Irrelevant
Write successful
No memory to complete request
Errors from IrLAP
Return info on in-range machines
Use this function call to return information about machines within transmission range.
IrMUX will either instruct IrLAP to perform a discovery operation or will return the results of a previous
discovery.
Arguments
Connection Handle
Argument 1
Argument 2
Argument 3
Value of status in the E_MESSAGE struct on return:
MUX_DISCOVERY_COMPLETE
MUX_CACHE_USED
E_GEN_NOMEMORY
E_MUX_ABORT
LM_ConnectRequest
Message Number 9
Irrelevant
Pointer to a buffer of size at least
slots*sizeof (DISCOVERY_LOG) ; on return
contains the discovery log
Pointer toa urnT containing the number of
slots; on return contains the number of
discoveries
Irrelevant
Discovery complete
Results of previous discovery used
Could not complete request
IrMux has been destroyed
Attempt to connect to a remote machine
Use this function call to attempt to connect to a remote machine. Supplying a home Port number of -1 will
cause IrMUX to generate one for you. A remote port number of zero is used to connect to the remote LM-
IAS server. See the appropriate IrDA IrLAP document for details of the connect_stRuct and how to set
port numbers and other connection parameters.
17-7
1/0 DEVICES REFERENCE
Arguments
Connection Handle Pointer to a vorp* to receive the connection
handle on return
Argument | Pointer to a CONNECT_STRUCT containing
connect parameters; on return the
CONNECT_STRUCT contains the actual connection
parameters
Argument 2 Pointer to a buffer of 60 bytes of connection
data; on return the buffer contains connection
data from the other machine
Argument 3 Irrelevant
Value of status in the E_MESSAGE struct on return:
OKAY Connection complete
E_GEN_NSUP Unsupported parameters or port number
E_GEN_INUSE Port number in use by another client
E_MUX_BUSY A discovery is in process
E_MUX_EXCLUSIVE Another connection already has exclusive
access to IrMUX
E_GEN_NOMEMORY Insuffient Memory to make connection
E_MUX_REMOTEDISCONNECT Remote forced disconnection
E_MUX_TIMOUTDISCONNECT Forced disconnection, timout
E_MUX_LOGOFFDISCONNECT Forced disconnection, client logoff
E_MUX_USERDISCONNECT User cancelled connection
E_MUX_LAP IrLAP cannot complete this request
LM_WaitForConnection Wait for remote machine to connect
Message Number 8
Use this function call to get a remote machine to wait for connection through a specified port number.
Arguments
Connection Handle Pointer to vorp* to receive connection handle
on return
Argument | Pointer to a CONNECT_STRUCT containing
connect parameters; on return the
CONNECT_STRUCT contains the actual connection
parameters
Argument 2 Pointer to a buffer of 60 bytes of connection
data; on return the buffer contains connection
data from the other machine
Argument 3 Irrelevant
17-8
Value of status in the E_MEeSSAGE Struct on return:
OKAY
E_GEN_NSUP
E_GEN_INUSE
E_GEN_NOMEMORY
E_MUX_REMOTEDISCONNECT
E_MUX_TIMOUTDISCONNECT
E_MUX_LOGOFFDISCONNECT
E_MUX_USERDISCONNECT
LM_StatusRequest
Message Number 21
17 THE IRMUX API
Connection complete
Unsupported parameters or port number
Port number in use by another client
Insuffient memory to make connection
Remote forced disconnection
Forced disconnection, timout
Forced disconnection, client logoff
User cancelled connection
Return the status of the link
Use this function call to return the status of the link and where abouts IrLAP is holding un-ACKed data.
Arguments
Connection Handle
Argument 1
Argument 2
Argument 3
Value of status in the E_MESSAGE struct on return:
OKAY
E_MUX_NOCONNECTION
LM_ReadRequest
Message Number 24
Connection handle
Pointer to an rntT to hold the link quality on
return
Pointer to an int to hold the number of un-
ACKed frames on return
Irrelevant
Request complete
Connection handle invalid or connection
removed by other end
Queue a read request on a connection
Use this function call to queue a read request on a connection.
This function will panic the client process if a read is already queued on that connection.
Arguments
Connection Handle
Argument 1
Argument 2
Argument 3
Connection handle
Pointer to a buffer to receive the data on return
Pointer to a uINT containing the number of
bytes required; on return the urnt contains the
amount of data returned
Irrelevant
17-9
1/0 DEVICES REFERENCE
Value of status in the = _mMesSAGE Struct on return:
OKAY Read complete
E_MUX_REMOTEDISCONNECT Remote forced disconnection
E_MUX_TIMOUTDISCONNECT Forced disconnection, timout
E_MUX_LOGOFFDISCONNECT Forced disconnection, client logoff
E_MUX_USERDISCONNECT User cancelled connection
E_MUX_NOCONNECTION Connection handle invalid or connection
removed by other end
E_MUX_ABORT IrMUX has been destroyed
LM_WriteRequest Queue a write request on a connection
Message Number 25
Use this function call to queue a write request on a connection.
The maximum length of a data frame that can be sent is returned as part of the connection
parameters from a connect request. Do not exceed this length.
Arguments
Connection Handle Connection handle
Argument | Pointer to a buffer containing the data to send
Argument 2 Pointer to a uInT containing the number of
bytes to send
Argument 3 TRUE if more data is to follow
Value of status in the = _mMesSAGE Struct on return:
OKAY Write successful
E_GEN_NOMEMORY No memory to complete request
E_MUX_NOCONNECTION Connection handle invalid or connection
removed by other end
(various) Errors from IrLAP
LM_UReadRequest Queue an unreliable read request
Message Number 26
Use this function call to queue an unreliable read request on a connection.
In unreliable reading, data is sent only once.
This function will panic the client process if a read is already queued on that connection.
Arguments
Connection Handle Connection handle
Argument | Pointer to a buffer to receive the data on return
Argument 2 Pointer to a urnT containing the number of
bytes required; on return the urnt contains the
actual amount of data returned
Argument 3 Irrelevant
17 - 10
17 THE IRMUX API
Value of status in the = _mMesSSAGE Struct on return:
OKAY Read complete
E_MUX_REMOTEDISCONNECT Remote forced disconnection
E_MUX_TIMOUTDISCONNECT Forced disconnection, timout
E_MUX_LOGOFFDISCONNECT Forced disconnection, client logoff
E_MUX_USERDISCONNECT User cancelled connection
E_MUX_NOCONNECTION Connection handle invalid or connection
removed by other end
E_MUX_ABORT IrMUX has been destroyed
LM_UWriteRequest Queue an unreliable write request
Message Number 27
Use this function call to queue an unreliable write request on a connection.
In unreliable writing, data is sent only once.
Arguments
Connection Handle Connection handle
Argument | Pointer to a buffer containing the data to send
Argument 2 Pointer to a uInT containing the number of
bytes to send
Argument 3 TRUE if more data to follow
Value of status in the = _MESSAGE Struct on return:
OKAY Write successful
E_GEN_NOMEMORY No memory to complete request
E_MUX_NOCONNECTION Connection handle invalid or connection
removed by other end
(various) Errors from IrLAP
LM_AccessModeRequest Obtain/release exclusive access
Message Number 22
Use this function call to obtain/release exclusive access to ITMUX.
Arguments
Connection Handle Connection handle
Argument 1 LM_ExclusiveMode to obtain exclusive access or
LM_Mult iplexMode to release exclusive access
to IrMUX
Argument 2 Irrelevant
Argument 3 Irrelevant
17-11
1/0 DEVICES REFERENCE
Value of status in the = _MESSAGE Struct on return:
OKAY Request complete
E_GEN_MEMORY Not enough memory to complete the request
E_GEN_INUSE Unable to enter exclusive mode
E_MUX_BUSY Another client is attempting to enter exclusive
mode
E_MUX_EXCLUSIVE Another client already has exclusive access
E_MUX_NOCONNECTION Connection handle invalid or connection
removed by other end
E_MUX_ABORT IrMUX is being destroyed
E_GEN_NSUP Argument | does not contain either
LM_ExclusiveMode Of LM_MultiplexMode
E_MUX_REMOTEDISCONNECT Remote forced disconnection
E_MUX_TIMOUTDISCONNECT Forced disconnection, timout
E_MUX_LOGOFFDISCONNECT Forced disconnection, client logoff
E_MUX_USERDISCONNECT User cancelled connection
LM_IdleRequest Place the connection into Idle/Active mode
Message Number 23
Use this function call to place the connection into Idle/Active mode.
This implementation does not follow the IrMUX specification in that communication can be carried out in
both Active and Idle modes. Being in active mode simply acts as a block to other clients placing IIMUX
into Exclusive mode.
A connection always starts in Idle mode. To stop other clients gaining exclusive access to I1MUX by
entering Active mode, a client must put its own connection into Active mode. It is recommend that Active
mode is only used during critical periods of data communication.
Arguments
Connection Handle Connection handle
Argument 1 Irrelevant
Argument 2 Irrelevant
Argument 3 TRUE for Idle mode, ratse for Active mode
Value of status in the E_MESSAGE struct on return:
OKAY Mode change successful
E_MUX_BUSY Connection busy
E_MUX_NOCONNECTION Connection handle invalid or connection
removed by other end
LM_SetHandshakingLevel Set retries on each data frame
Message Number 28.
Use this function call to set the number of retries on each data frame, if the client application is not
responding to incoming data quickly enough.
This should only be enabled when in Exclusive mode. When use of exclusive mode has finished
LM_SetHandshakingLevel should be used to reset the number of retries to 1.
17 - 12
Arguments
Connection Handle
Argument 1
Argument 2
Argument 3
LM_DisconnectRequest
Message Number 20
17 THE IRMUX API
Connection handle
Irrelevant
Irrelevant
The number of times to resend each frame,
0 (zero) for inactive.
Disconnect
Use this function call to disconnect. This will cancel any requests on the connection.
Arguments
Connection Handle
Argument 1
Argument 2
Argument 3
Value of status in the = _mMEesSSAGE Struct on return:
OKAY
E_MUX_NOCONNECTION
E_MUX_BUSY
Connection handle
Irrelevant
Irrelevant
Irrelevant
Disconnect complete
Connection handle invalid or connection
removed by other end
IrMUX is busy. The application shoul wait a
short time and try again. May be ignored if
logging off.
17 - 13
CHAPTER 18
FAST CHARGER
Introduction
This chapter describes Fast Charger services for the HC and Workabout docking stations.
In this document the term ‘Docking Station’ refers both to the HC docking station, (which connects to an
HC LIF interface fitted to the bottom of the HC), and to the Workabout docking station. The term
‘computer’ refers to an HC or Workabout.
Docking Station services
There are two variants of the docking station: one model has been designed for the HC computer and one
model has been designed for the Workabout computer. The docking station may be used to fast charge the
battery inside the "docked" computer.
The docking station Fcc: device driver may be used to charge (or discharge) the main battery under the
direct control of an HC/Workabout computer which has been inserted in the docking station holster. The
device driver may also be used to supply that computer with information about the battery charge status.
Notes:
1. the HC/Workabout docking station expansion port cannot be used whilst using the (Fcc:).
2. the HC/Workabout docking station will charge batteries without any external software
control from a docked computer.
See also the Cradle and Docking Station chapter for details of the cradle device driver crp:.
Using the Docking Station
Use of the Docking Station is complicated by the fact that one high speed serial channel is used to
communicate to three possible interfaces.
1. The interface in the bottom of the HC (1.e. Barcode, RS232 etc.)
2. The electronics in the device
3. Any expansion fitted to the device.
As a result of this, only one interface at a time can be opened on this channel, 1.e. either the RS232 in the
HC bottom expansion (port TTY:B) or the RS232 in the Docking Station expansion slot (port TTY:C).
HC/Workabout docking station fast charger services
The Fcc: device driver will allow a C application running on a machine in the docking station holster to
monitor and control the state of the docking station fast charger circuitry. The docking station is capable
of charging , discharging and performing a capacity check of the main battery inside the computer in a
variety of operating modes. It may also be used to charge (but not discharge) a spare battery installed in
the spare battery compartment of the docking station.
Important note: the fast charger circuit in the docking station will charge batteries automatically without
requiring any explicit calls to the rcc: device driver; only in a few circumstances should it actually be
18-1
I/O DEVICES REFERENCE
necessary to use FCG: (as described in this chapter) to give implicit instructions to the docking station. In
normal circumstances, it is not necessary to run software on the SIBO machine to control or monitor the
battery charging/discharging process.
There are two variants of the fast charger device driver, where each driver is tailored for use with one
specific SIBO computer and docking station. The fast charger device driver which may be used with an
HC computer is called sys$chgh.ldd; the fast charger device driver which may be used with a Workabout
computer is called sys$fchg.ldd. Both device drivers may be found in the path \sibosdk\lib\ on installation
of the relevant SIBO C Software Development Kit optional components onto your PC (from the /dd.zip
file).
The library file fcharge.h (located in the path \sibosdk\include\) contains C constant declarations which
may be used with either the sys$chgh.ldd or the sys$fchg.ldd device driver.
The fast charger does not allow a direct measurement of the status of each battery. As a result, the Fcc:
device drive will determine the status of each battery indirectly by measuring the charge pulses applied
by the charger circuitry to the battery pack over a short period of time. For this reason, some of the Fcc:
I/O operations may take a number of seconds to complete.
The fast charger device driver will only run if the Psion computer is resting in the docking station holster.
Fast charging batteries
The docking station may be used to charge the battery inside the "docked" computer, or a battery located
in the spare battery compartment on the top of the docking station. Only one battery pack can be charged
at any one time.
The fast charge circuitry possesses four modes of charging:
fast charge charge the battery pack with a preset current, and for a preset charge period (or
shorter, depending upon the charge status of the battery).
top off the battery pack is now 90-95% fully-charged; supply a lower current (typically C/10)
after completion of the fast charge, to fully-charge the cells
trickle charge supply a small charge current (typically C/30) to maintain the charge in a fully-
charged battery pack
discharge discharge the main battery at a fixed discharge current
If you wish to control the fast charger explicitly from a C program running on the "docked" Psion
computer, then the program should carry out the following steps:
1. open a channel to the fast charger device driver with the call p_open(voID **ppcb,
"PCG:A",-1);
2. set up the charge current and maximum charging time period with a call to
FCHG_SETCHARGEMODE (if this step is omitted, then default settings will be used).
3. instruct the device driver to charge the main battery (or the spare battery) with
FCHG_FASTCHARGEx. This command will commence the charging of the battery at a default
current and over a default time period.
4. close the channel to Fcc: with p_close (VOID *pcb)
Whilst the Fcc: channel is open, the C program may also monitor the progress of the charging process, if
required. Calls to FCHG_FASTCHARGEx may be omitted if the C program wishes only to monitor the progress
of the charging process.
The maximum charge time period set with a FCHG_SETCHARGEMODE call is used as a backup safety feature
to ensure that the fast charging process terminates before any damage can occur to the battery pack. For
this reason, it is essential that the charge time is set correctly, in relation to the charge rate which
you wish to use. The two main terminators used by the fast charge circuitry to detect the end of the
charging process are voltage and temperature slope. These two terminators are managed by the fast
charger hardware.
IMPORTANT: Never charge a standard Psion battery pack with a charge rate that exceeds 1C
without first contacting the battery supplier for advice. High charge rates in excess of 1C will
reduce the life of the battery pack and may create a risk of explosion or fire.
18 -2
18 FAST CHARGER
Measuring battery capacity
The Fcc: device driver may be used to determine the charge capacity of a battery pack. If the time taken to
fully-discharge a fully-charged battery pack is measured, then the relative battery charge capacity may be
determined from the following equation:
M=(10* T, *I-)/(*C,)
where:
e M-= the reduction in battery charge capacity of the battery under test (%)
e Ty, = measured discharge time (minutes)
e I. =discharge current (mA)
e C, =rated battery capacity of battery under test (mAh)
Rated charge capacity of standard Psion battery packs
The rated charge capacity for the standard Psion HC and Workabout battery packs is displayed in the
table below. This table also contains the standard discharge time and the standard discharge current for
each variant of the docking station. .
Docking station Rated capacity C; (mAh) Discharge time T,, (mins) Discharge current I,
(mA)
HC 650 130 300
Workabout 845 175 290
Example calculations
Example 1: If a fully-charged HC battery pack takes 100 minutes to discharge, at the (fixed) discharge
current of 300mA, then the measured capacity of that HC battery pack is 77%.
ie. M= (10 * T,)* 1,)/ (6 * C. ) = (10 * 100 * 300) / (6 * 650) = 77%
Example 2: If a fully-charged Workabout battery pack takes 120 minutes to discharge, at the (fixed)
discharge current of 290mA, then the measured capacity of that Workabout battery pack is 69%,
Le. M=(10 * 120 * 290) / (6 * 845) = 69%
The charge capacity of custom batteries may also be determined using the same equation. Care must be
taken to use the correct value of I, in the equation, where I, is defined by the docking station variant that
is being used to discharge the custom battery pack.
p_open(FCG:A) Open the fast charger device
INT p_open(VOID **ppcb,"FCG:A",-1);
Open a channel to the docking station fast charger device.
Returns zero if the device is opened successfully, otherwise a negative error. The p_open operation will
fail if the docking station is not present.
If the channel is opened successsfully, the charging current and charging time will be preset to the default
settings. The device driver will then immediately begin polling the status of the battery. This polling
operation may take up to forty seconds to complete.
Errors include:
E_GEN_NOMEMORY failed to allocate memory for control block
E_FILE_LOCKED port is already open
E_GEN_INUSE port in use
E_FILE_DEVICE device does not exist
1/0 DEVICES REFERENCE
p_close Close the channel
INT p_close (VOID *pcb) ;
Close the fast charger device channel.
Any outstanding FCHG_xxx operations will be cancelled by p_close.
Returns zero.
FCHG_SETCHARGEMODE Set battery charge mode
#include “fcharge.h”
INT p_iow(VOID *pcb,FCHG_SETCHARGEMODE, WORD *pmode) ;
Set the charge current and the maximum charging time period.
Two pieces of information must be passed to the docking station fast charger circuitry (in pmode):
e the current which will be used to charge the battery
e the maximum period of time which the battery will be charged.
The contents of pmode should contain a value which is constructed from two integers. The three least
significant bits in pmode should identify the charge time period; the four most significant bits in pmode
should identify the charge current. (The present charge mode may be read by calling the
FCHG_READCHARGEMODE function.)
This information may be selected from the fixed options that are supported by the docking station. The
minimum charging current that one could select should not be less than a quarter of the battery capacity
(unless the battery pack is known to be already partially charged).
Example: The capacity of the standard Workabout battery is 850mA. The minimum charging current that
one could use is 0.25 X 850 = 212mA (approx. 200mA = FcHG_ccLow2).
Please refer to the tables below for information about the discrete charge currents which may be supplied
by the docking station. This table also contains the names of the C constants, defined in fcharge.h, that
are associated with each charge current setting for the docking station.
Charging Psion battery packs
The following tables display suggested combinations of charge current and charge times that are suitable
for the standard Psion HC and Workabout battery packs:
Charge period Charge current for standard Charge current for standard
Psion HC battery pack Psion Workabout battery pack
1C 700mA 850mA
C/2 350mA 500mA
C/4 175mA 200mA
The above charge period/charge currents correspond to the following C constants in fcharge.h:
Charge period Charge current for standard Charge current for standard
Psion HC battery pack Psion Workabout battery pack
FCH_CTIME1C FCHG_DEFAULTCC FCHG_DEFAULTCC
FCH_CTIMEC2 FCH_CC350mA FCH_CC500mA
FCH_CTIMEC4 FCH_CCLOW2 FCH_CCLOW2
High charging currents should only be selected in situations where special, high capacity, fast charge
battery packs are being used. Lower charging currents are recommended in circumstances where the
ambient temperature is above 35°C, or where lower capacity battery packs are used.
The minimum charging current that may be selected should not be less than a quarter of the battery
capacity (unless the battery pack is known to be already partially-charged). Incorrect settings will result in
under-charge or damage to batteries.
18-4
18 FAST CHARGER
Charging custom battery packs
The docking station may also be used to charge custom battery packs with different charge-current
requirements.
The fast charger device driver and docking station support the following charge times:
Charge period Jfcharge.h constant Maximum charge period (minutes)
2C FCHG_CTIME2C 45
1C FCHG_CTIME1C 90
C/2 FCHG_CTIMEC2 180
C/4 FCHG_CTIMEC4 360
The fast charger device driver and docking station support the following charge currents:
fcharge.h constant HC docking station current Workabout docking station current
FCHG_CCLOW1 100mA 130mA
FCHG_CCLOW2 175mA 200mA
FCHG_CC350mA 350mA 350mA
FCHG_CC500mA 500mA 500mA
FCHG_CC650mA 650mA 650mA
FCHG_DEFAULTCC 700mA 850mA
FCHG_CC850mA 850mA 850mA
FCHG_CC1000mA 1A 1A
FCHG_CC1100mA LIA LIA
FCHG_CCHIGH1 1.2A 1.3A
FCHG_CCHIGH2 1.4A 1.5A
IMPORTANT: Never charge a standard Psion battery pack with a charge rate that exceeds 1C
without first contacting the battery supplier for advice. High charge rates in excess of 1C will
reduce the life of the battery pack and may create a risk of explosion or fire.
Notes:
1. The standard power supply that is provided with the Workabout docking cradle has a
maximum current rating of 1A. As a result, battery charge currents in excess of 850 mA
cannot be supported by the standard power supply provided with the docking station.
If you wish to fast charge batteries using currents greater than 850 mA, a 2A power supply
must be used with the Workabout docking station. Suitable power supplies are available
from Psion; for further details please contact the Psion Sales staff.
The HC docking station is provided with a 2A power supply and hence is capable of
handling the entire charge current range supported by the device driver.
2. Charging currents below or equal to 200mA have a tolerance of + 30% and
currents greater then 300mA have a tolerance of + 15%.
18-5
I/O DEVICES REFERENCE
FCHG_READCHARGEMODE Read battery charge mode
#include “fcharge.h”
INT p_iow(VOID *pcb,FCHG_READCHARGEMODE,WORD *pmode) ;
Read the charge current and the maximum charging time period settings.
The present charge rate and the required charging period will be returned to pmode.
The contents of pmode will contain a value which is constructed from two integers. The three least
significant bits in pmode will identify the charge time period; the four most significant bits in pmode will
identify the charge current. The charge mode may be altered by calling the FcHc_SETCHARGEMODE function.
The table that appears in the FcHG_SETCHARGEMODE section (above) contains all of the valid combinations
of charge current/charge period settings for HC and Workabout machines.
Zero is returned if the FcHG_SETCHARGEMODE request completed successfully, or a negative value if an error
has occurred.
FCHG_READSTATUS Read the battery status
#include “fcharge.h”
INT p_iow(VOID *pcb, FCHG_READSTATUS,WORD *pstatel,WORD *pstate2);
Read the present charge status of each battery from the docking station device, writing the new charge
states to pstatel and pstate2.
The status of the main battery inside the computer held in the holster is returned in pst ate1; if a spare
battery has been inserted in the spare battery compartment of the docking station, then the status of this
battery will be returned to pstate2.
On completion, pstate1 and pstate2 may contain one of the following integer values:
FCHG_UNKNOWN the battery is in an unknown state
FCHG_NOTCHARGING the battery is not charging.
If the docking station has been instructed to discharge the main battery, then
FCHG_READSTATUS will return a FCHG_NOTCHARGING value to indicate that the
battery is indeed being discharged
FCHG_FASTCHARGING The battery is fast charging
FCHG_TOPPINGOFF The battery is now charged to 90-95% of its maximum capacity and it is now
being topped off by the fast charger circuitry
FCHG_TRICKLE The battery is being trickle charged
The Fcc: device driver calculates the present charge status of a battery by measuring the duration of
charge pulses that the battery receives from the docking station. A charge pulse from the docking station
may last 40 seconds; as a result, it is possible that a call to FcHc_READSTATUS may not be able to determine
the present charge status of a battery at the precise moment in time when the call is made.
In this situation, a FCHG_UNKNowN status message will be returned for the status of that battery. This does
not mean that the battery charge status is indeterminate; another FCHG_READSTATUS call in the future may,
however, be able to return a valid status value for the charge status of that battery.
Zero is returned if the FcHG_READSTATUS request completed successfully, or a negative value if an error has
occurred.
18 - 6
18 FAST CHARGER
FCHG_ASYNCHREAD Read the battery status asynchronously
#include “fcharge.h”
INT p_ioc(VOID *pcb,FCHG_ASYNCHREAD, WORD *pstatel,WORD *pstate2);
Read the present charge status of each battery from the docking station device asynchronously, writing the
new charge states to pstate1 and pstate2 when the charge status of either battery alters.
The rFcHG_ASYNCHREAD operation may be cancelled at any time by a call to FcHG_CANCEL.
FCHG_ASYNCHREAD Will return immediately after initiating a request to receive battery status information
when the status of either battery changes. At some time in the future, the new status of the main battery
inside the computer in the holster will be returned in pstate1; if a spare battery has been fitted inside the
compartment in the top of the docking station, then the status of this battery will be returned to pstate2.
Panics if pcb is not a valid channel handle, or if an FcHG_ASYNCHREAD operation is outstanding.
Returns zero if the rcHG_ASYNCHREAD request completed successfully, or a negative value if an error has
occurred.
FCHG_CANCEL Cancel an asynchronous read
#include “fcharge.h”
INT p_iow(VOID *pcb,FCHG_CANCEL) ;
Cancel any outstanding rcHG_ASYNCHREAD request. Performing a cancel is harmless if no read request is
outstanding.
Returns zero.
FCHG_FASTCHARGE1 Fast charge the main battery
#include “fcharge.h”
INT p_iow(VOID *pcb, FCHG_FASTCHARGE1) ;
Begin fast charging the main battery that is inside the computer fitted to the docking station holster.
The present settings for the charge current and charge time period (as set by p_open or
FCHG_SETCHARGEMODE) will be used by the fast charger circuitry to charge the battery.
FCHG_FASTCHARGE1 will return zero if it completes successfully, or a negative value if an error occurs.
Please note: only one battery may be charged at any one time; 1.e. the main battery cannot be charged
while a battery in the spare battery compartment is being charged.
If you wish to charge the main battery and the spare battery, then the software which calls rce: should
charge one battery, sense when that battery is charged sufficiently, and then charge the second battery.
FCHG_FASTCHARGE2 Fast charge the spare battery
#include “fcharge.h”
INT p_iow(VOID *pcb, FCHG_FASTCHARGEZ2) ;
Begin fast charging the battery that is in the spare battery compartment of the docking station.
The present settings for the charge current and charge time period (as set by p_open or
FCHG_SETCHARGEMODE) will be used by the fast charger circuitry to charge the battery.
FCHG_FASTCHARGE2 will return zero if it completes successfully, or a negative value if an error occurs.
Please note: only one battery may be charged at any one time; i.e. a battery in the spare battery
compartment cannot be charged while the main battery is being charged.
If you wish to charge the main battery and the spare battery, then the software which calls rce: should
charge one battery, sense when that battery is charged sufficiently, and then charge the second battery.
Note: if the main battery is charging and the spare battery is waiting, then the rcuc_FASTCHARGE2 function
will over-ride the status of the main battery and start charging the spare battery instead.
18 -7
I/O DEVICES REFERENCE
FCHG_DISCHARGE1 Discharge the main battery
#include “fcharge.h”
INT p_iow(VOID *pcb, FCHG_DISCHARGE1) ;
Begin discharging the main battery fitted inside the computer fitted to the docking station holster.
The FCHG_DISCHARGE1 command will initiate a sequence of operations which will take a few seconds to
complete. If any additional calls are made to Fcc: in this period, those commands will return a negative
completion code and the instructions will be ignored.
The discharging current is fixed by the fast charger circuitry and may therefore not be altered by software.
The discharge current for the HC docking station is set to 300 mA +3%. The discharge current for the
Workabout docking station is set to 290 mA +3%.
FCHG_DISCHARGE1 will return zero if it completes successfully, or a negative value if an error occurs.
Notes:
1. when the docking station has been instructed to discharge a battery, subsequent
FCHG_READSTATUS operations will each return a FCHG_NOTCHARGING status code - which
should be interpreted as meaning that the battery is discharging (as expected).
2. The spare battery cannot be discharged by Fce:.
Example program
An example C application may be found in the file path \sibosdk\wkdemo\, on installation of this SDK
onto your PC.
charger.c is a Workabout computer program which monitors and controls the fast charger circuitry in the
docking station. This program allows the main battery, or spare battery to be charged, or the main battery
to be discharged, and the status of both batteries to be monitored.
Note: This program will only run if the Workabout computer has been placed into the holster of a docking
station.
/* Fastcharger for Workabout */
/* Example application */
/* (C) Copyright Psion Software PLC 1997 */
include <p_std.h>
include <p_file.h>
include <p_sys.h>
include <p_keyb.h>
include <epoc.h>
include "fcharge.h"
GLREF_D VOID *winHandle;
LOCAL_C VOID State(WORD Val)
switch (Val)
{
case 0:
p_printf(" Unknown") ;
break;
case l:
p_printf(" Not Charging") ;
break;
case 2:
p_printf(" Fast Charging");
break;
case 3:
p printf (" Topping Off");
break;
default:
p_printf(" Trickle");
18-8
GLDEF_C VOID main(VOID)
/*
{
VOID *pcb;
WORD One, OldOne;
WORD Two, OldTwo;
WORD KStat,Disch;
WORD LogOne[100];
WORD LogTwo[100];
WORD P1=0,P2=0, Temp;
ULONG TTime;
P_CON_KBREC Key;
TEXT X1Str[1l];
WORD X1=0;
ULONG XE=0,DischTime;
TEXT *X1Ptr;
INT Item;
for (Item=0; Item<100; Item++)
{
LogOne [Item] =0;
LogTwo [Item] =0;
}
p_devdel ("FCG",E_LDD) ;
p_printf ("Loading");
if (p_loadldd("m:\\sys$fchg.1dd") <0)
p_panic(0);
p_printf ("Opening test");
if (p_open (&pcb, "FCG:A",-1) <0)
p_panic(1);
p_printf ("Closing test");
if (p_close (pcb) <0)
p_panic(2);
p_printf ("Opening test part II");
if (p_open (&pcb, "FCG:A",-1) <0)
p_panic (3);
p_printf ("Cant remove test");
if (p_devdel ("FCG:",E_LDD) >=0)
p_panic(4);
p_printf ("Setting the charge Mode");
p_iow (pcb, P_FCHG_READCHARGEMODE, &One) ;
if (One!=(P_FCHG_DEFAULTCC | P_FCHG_CTIME1C) )
p_panic(5);
p_printf ("Test the charge Mode");
if (p_iow (pcb, P_FCHG_SETCHARGEMODE, &One) !=0)
p_panic(6);
p_printf("Set Rubbish charge Mode");
One=-1;
if (p_iow (pcb, P_FCHG_SETCHARGEMODE, &One) ==0)
p_panic(7);
p_iow (pcb, P_FCHG_READSTATUS, &One, &Two) ;
p_print ("Battery one:");
State (One) ;
p_print ("Battery two:");
State (Two) ;
p_printf("Asynch test1");
p_iow (pcb, P_FCHG_ASYNCHREAD, &One, &Two) ;
p_print ("Battery one:");
State (One) ;
p_print ("Battery two:");
State (Two) ;
p_printf("Asynch test2");
p_iow (pcb, P_FCHG_ASYNCHREAD, &One, &Two) ;
p_print ("Battery one:");
State (One) ;
p_print ("Battery two:");
State (Two) ;*
18 FAST CHARGER
18-9
1/0 DEVICES REFERENCE
18 - 10
p_ioc4 (winHandle, P_FREAD, &KStat, &Key) ;
TTime=p_date();
Disch=0;
DischTime=0;
FOREVER
{
if (KStat!=E_FILE_PENDING) /* Was it the keyboard */
{
p_iowait(); /* not really the way to do this -oh well */
if (Key.keycode=='Q' | | Key. keycode=='q'
p_exit (0);
|| Key.keycode==27)
else if (Key.keycode=='D' | | Key. keycode=='d"')
{
p_printf ("Start discharge");
TIime=p_date();
if (p_iow(pcb,P_FCHG_DISCHARGE) )
p_panic(8);
Disch=1;
}
else if (Key.keycode=='F' || Key.keycode=='f')
p_printf("Start Fastchargel") ;
TTime=p_date();
if (p_iow(pcb,P_FCHG_FASTCHARGE1) )
p_panic (9);
else if (Key. keycode=='G' | | Key. keycode=='g')
p_printf("Start Fastcharge2") ;
TTime=p_date();
if (p_iow(pcb,P_FCHG_FASTCHARGEZ2) )
p_panic(9);
else if (Key. keycode=='C'! | | Key. keycode=='c"')
p_getl("Current: ",&X1Str[0],10);
X1Ptr=&X1Str[0];
p_stoi(&X1Ptr,&X1);
}
else if (Key.keycode=='/' | | Key. keycode=='?')
{
if (Disch==1)
p_printf("Discharging: %d", (p_date()-TTime) );
else
{
p_printf("Discharge Time: %d1",DischTime) ;
if (X1>0 && DischTime>0)
{
XE= (850*60*60*10) /X1;
XE= (DischTime*100*10) /XE;
p_printf("Capacity (Cell) %d%%", (UWORD) (XE) );
}
}
else if (Key. keycode=='1')
{
p_printf("Battery one Log");
Temp=0;
while (Temp<P1)
if (LogOne[Temp++]>0)
State (LogOne[Temp-1]);
}
else if (Key. keycode=='2')
{
p_printf ("Battery two Log");
Temp=0;
while (Temp<P2)
if (LogTwo[Temp++]>0)
State (LogTwo[Temp-1]);
18 FAST CHARGER
else if (Key.keycode=='H' | | Key.keycode=="'h' | | Key. keycode==290 | |
Key. keycode==291)
{
p_printf£("");
p_printf("C...Enter Discharge current");
p_printf("D...Start Discharge");
p_printf("F...Fastcharge Batteryl");
p_printf("G...Fastcharge Battery2");
p_printf("?...Show Discharge time");
p_printf("1...Show Batteryl Log");
p_printf("2...Show Battery2 Log");
poipraent ft ((C"On-. 2QUrt™): 3.
p_printf£("");
}
p_ioc4 (winHandle, P_FREAD, &KStat, &Key) ;
}
OldOne=One;
OldTwo=Two;
p_iow (pcb, P_FCHG_READSTATUS, &One, &Two) ;
if (OldOne!=One || OldTwo!=Two)
{
if (OldOne==1 && Disch==1 && One!=1)
{
Disch=0;
DischTime=(p_date()-TTime) ;
p_printf ("Discharge Time: %d",DischTime) ;
}
p_printf("Time: %d", (p_date()-TTime) );
if (One!=O0ldOne)
{
if (P1>50)
P1=0;
LogOne [P1++]=One;
}
if (Two!=OldTwo)
{
if (P2>50)
P2=0;
LogTwo [P2++]=Two;
}
p_print ("Battery one:");
State (One) ;
p_print ("Battery two:");
State (Two) ;
}
18 - 11
INDEX
.wve files
digital sound files, 5-1
A_FTIMED
alarm device, 6-2
A_FTIMED_X
alarm device, 6-3
A_FUNTIMED
alarm device, 6-3
A_FUNTIMED_X
alarm device, 6-4
AccessIr
infrared API, 16-1
AccessIr API
infrared, 15-4
AIR:
infrared device, 15-4, 16-1, 16-2
loading on Siena, 16-1
alarm
device I/O introduction, 6-1
note sequence SND: device, 5-3
alarm device
A_FTIMED, 6-2
A_FTIMED_X, 6-3
A_FUNTIMED, 6-3
A_FUNTIMED_X, 6-4
ALM: introduction, 6-1
p_close, 6-2
P_FCANCEL, 6-2
p_open(ALM:), 6-2
panics, 6-2
services additional S3a, 6-3
services $3 S3a & MC, 6-2
alarm services
time application $3 S3a, 6-2
ALM: device
introduction, 6-1
see alarm device, 6-1
asynchronous
I/O functions, 1-1
bar code
Codabar start and stop characters, 14-5
maximum scanning rate, 14-4
supplement digits, 14-4
bar code command syntax
HC bar code/RS232 module, 14-11
bar code commands
HC bar code/RS232 module, 14-11
bar code formats UPC/EAN
HC bar code/RS232 module, 14-6
bar code interface
comms settings, 14-2
HC bar code/RS232 module, 14-3
bar code symbologies
HC bar code/RS232 module, 14-4
bar code wand connector
HC bar code/RS232 module, 14-2
BAR: device
see HC bar code reader, 13-1
battery capacity
docking station fast charger, 18-3
HC, 18-3
Workabout, 18-3
baud rates
infrared, 15-3
beaming
infrared communications application,
15-6
bottom slot
HC bar code/RS232 module, 14-2
CLIB
programs CON: device use of, 2-1
Codabar
start and stop characters, 14-5
communications
infrared application, 15-6
CON: device
automatic opening, 2-1
CLIB based programs, 2-1
example code, 2-14
explicit opening, 2-3
handle of, 2-2
introduction, 2-1
OPL programs, 2-1
PLIB based programs, 2-2
see console device, 2-1
Condor chip
serial infrared, 15-3
connection
second time (LM-IAS server)
infrared, 17-4
connection first time (LM-IAS server)
infrared, 17-4
connectionless calls
infrared, 17-3
connectionless read request
infrared, 17-3
connectionless write request
infrared, 17-3
connection-oriented calls
infrared, 17-3
console device
automatic opening of CON: device, 2-1
example code, 2-14
explicit opening of CON: device, 2-3
handle of, 2-2
I/O, 2-1
p_close, 2-4
P_EVENT_READ, 2-9
P_EVENT_TEST, 2-10
P_FCANCEL, 2-5
P_FEDIT, 2-6
P_FFLUSH, 2-6
P_FINQ, 2-10
P_FREAD, 2-5
P_FSENSE, 2-6
1/0 DEVICES REFERENCE
P_FSET service call convention, 2-3
P_FTEST, 2-5
P_FWFLUSH, 2-10
p_open(CON:), 2-3
P_SCR_ATTRB, 2-11
P_SCR_CANCEL_CAPTURE_KEY,
2-13
P_SCR_CAPTURE KEY, 2-13
P_SCR_CLIENT_FOREGROUND, 2-12
P_SCR_CLR, 2-7
P_SCR_COMPATIBILITY, 2-9
P_SCR_CSET, 2-10
P_SCR_CURSOR, 2-8
P_SCR_DISABLE_READS, 2-12
P_SCR_ESCAPE, 2-9
P_SCR_FLUSH, 2-12
P_SCR_FONT, 2-11
P_SCR_GREY, 2-9
P_SCR_LAST_LINE_WRAP, 2-12
P_SCR_NEL, 2-8
P_SCR_POSA, 2-8
P_SCR_POSR, 2-8
P_SCR_SCROLL, 2-7
P_SCR_SLOCK, 2-8
P_SCR_WLOCK, 2-8
P_SCR_WSET, 2-7
p_write, 2-4
panics, 2-3
services, 2-3
services additional, 2-9
cradle device
introduction, 11-1
introduction HC, 11-1
p_close(CRD:), 11-2
P_FCANCEL, 11-2
P_FREAD, 11-2
P_FSENSE, 11-2
P_FSET, 11-2
p_open(CRD:), 11-1
services, 11-1
CRC
XYmodem device, 9-1
CRD: device
introduction, 11-1
see cradle device, 11-1
services, 11-1
data transfer
link I/O, 10-1
database
world application services $3 S3a, 8-2
device driver
FCG: docking station, 18-2
infrared accessir.ldd, 16-1
serial port LDD, 4-1
serial port PDD, 4-1
Siena infrared printing, 15-7
devices
AJR: infrared, 15-4, 16-1, 16-2
alarm I/O introduction, 6-1
ALM: introduction, 6-1
BAR: introduction, 13-1
CON: introduction, 2-1
console I/O, 2-1
ii
CRD: introduction, 11-1
FCG: docking station, 18-1
FRC: I/O introduction, 7-1
FRC: introduction, 7-1
HC bar code reader I/O introduction, 13-1
HC bar code/RS232 module, 14-1
HC cradle I/O introduction, 11-1
HC docking station I/O introduction, 11-1
HC intelligent bar code Reader, 14-1
HC magnetic card reader I/O, 12-1
I/O introduction, 1-1
I/O Introduction, 1-1
IRP: infrared printing, 15-7
MCR: introduction, 12-1
NCP I/O introduction, 10-1
PAR: introduction, 3-1
parallel port I/O, 3-1
serial port I/O introduction, 4-1
SIR: infrared, 15-2, 15-3
SND: introduction, 5-1
sound I/O introduction, 5-1
TTY: introduction, 4-1
WLD: introduction, 8-1
Workabout docking station I/O
introduction, 11-1
world database I/O introduction, 8-1
XMD: introduction, 9-1
Xmodem I/O introduction, 9-1
Ymodem I/O introduction, 9-1
dial tones
sound device DTMF, 5-4
disconnecting first time (LM-IAS server)
infrared, 17-4
disconnecting second time
infrared, 17-4
discovery
infrared, 15-5, 17-4
DISCOVERY_LOG
structure infrared, 15-5
docking station
battery capacity calculations, 18-3
device introduction HC, 11-1
device introduction Workabout, 11-1
fast charger, 18-1
FCG: device, 18-1
FCG: device driver, 18-2
FCHG_ASYNCHREAD, 18-7
FCHG_CANCEL, 18-7
FCHG_DISCHCHARGE, 18-8
FCHG_FASTCHARGE 1, 18-7
FCHG_FASTCHARGE2, 18-7
FCHG_READCHARGEMODE, 18-6
FCHG_READSTATUS, 18-6
FCHG_SETCHARGEMODE, 18-4
p_close, 18-4
p_open, 18-3
docking station device
p_close(CRD:), 11-2
P_FCANCEL, 11-2
P_FREAD, 11-2
P_FSENSE, 11-2
P_FSET, 11-2
p_open(CRD:), 11-1
INDEX
services, 11-1
DTMF
sound device dial tones, 5-4
E_FALARM
sound device, 5-3
E_FDIAL
sound device, 5-4
E_FSSOUNDCHANNELn
sound device, 5-3
E_MESSAGE struct
structure infrared, 17-5
example application
infrared transfer, 16-7
example program
fast charger Workabout, 18-8
infrared transfer, 16-7
exclusive mode
infrared, 17-4
expansion module
HC bar code/RS232 module, 14-2
extension file
world database, 8-9
fast charger
docking station, 18-1
example program Workabout, 18-8
FCHG_ASYNCHREAD, 18-7
FCHG_CANCEL, 18-7
FCHG_FASTCHARGE I, 18-7
FCHG_FASTCHARGE2, 18-7
FCHG_FASTDISCHARGE I, 18-8
FCHG_READCHARGEMODE, 18-6
FCHG_READSTATUS, 18-6
FCHG_SETCHARGEMODE, 18-4
introduction, 18-1
p_close(FCG:A), 18-4
p_open(FCG:A), 18-3
services, 18-1
FCG:
device, 18-1
FCHG_ASYNCHREAD
fast charger, 18-7
FCHG_CANCEL
fast charger, 18-7
FCHG_FASTCHARGE1
fast charger, 18-7
FCHG_FASTCHARGE2
fast charger, 18-7
FCHG_FASTDISCHARGE1
fast charger, 18-8
FCHG_READCHARGEMODE
fast charger, 18-6
FCHG_READSTATUS
fast charger, 18-6
FCHG_SETCHARGEMODE
fast charger, 18-4
file format
world database, 8-9
world database extension, 8-10
FRC: device
I/O introduction, 7-1
introduction, 7-1
p_close, 7-2
P_FCANCEL, 7-2
P_FREAD, 7-2, 7-3
P_FSTART, 7-2
p_open(FRC:), 7-1
services $3a & Workabout, 7-1
free running counter
see FRC: device, 7-1
get value by class frame
infrared, 17-2
infrared IAS, 17-3
get value by class reply frame
infrared IAS, 17-3
handshaking level
infrared, 17-4
HC
battery capacity calculation, 18-3
HC bar code device
p_close, 13-2
P_FCANCEL, 13-2
P_FREAD, 13-2
p_open(BAR:), 13-2
HC bar code reader
device driver, 13-1
hardware description, 13-1
interface module, 13-1
services, 13-2
wand, 13-1
HC bar Code reader
device I/O introduction, 13-1
HC bar code/RS232 module
2-pin header, 14-3, 14-4
5v regulated power supply, 14-4
auto power-off HC, 14-4
bar code command syntax, 14-11
bar code commands, 14-11
bar code formats UPC/EAN, 14-6
bar code symbologies, 14-4
bar code wand connector, 14-2
bottom slot, 14-2, 14-3
charging the main battery, 14-3
CTS input, 14-2
DCD input, 14-2, 14-3
device introduction, 14-1
diode isolation, 14-3
DSR auto wakeup switch, 14-3
DSR input, 14-2, 14-3
DTR output, 14-2, 14-3
example code, 14-20
expansion module, 14-2
HBCR-1610 series micro controller, 14-3
idle current of interface, 14-4
IGN_CTS serial port characteristic, 14-3
interface comms settings, 14-3
losing micro controller program data,
14-4
maximum output current, 14-2
optional Vsup connection, 14-2
p_close, 14-18
P_FREAD, 14-18
P_FSENSE, 14-18
P_FSET, 14-18
P_FWRITE, 14-19
p_open(TTY:), 14-17
power consumption, 14-2
1/0 DEVICES REFERENCE
power consumption wand, 14-4
powering an external device, 14-4
programming, 14-1
RI pin of the RS232 port, 14-2
RS232 port pinout table, 14-2
RTS output, 14-2
RTS/CTS handshaking protocol, 14-3
RX input, 14-2
scanning current for the interface, 14-4
services, 14-17
switched Sv regulated output, 14-3
switched Vsup output, 14-3
switching off the external unit, 14-2
tmask serial port characteristics, 14-3
top slot, 14-2, 14-3
TTY:A, 14-2
TTY:B, 14-2
TTY:D, 14-2, 14-3
TTY:E, 14-2, 14-3
TX output, 14-2
undecoded laser scanners, 14-3
Vsup input voltage supply range, 14-3
wand emulator, 14-1
Xon/Xoff handshaking, 14-2
HC cradle device
introduction, 11-1
see cradle device, 11-1
HC docking station
device introduction, 11-1
HC intelligent bar code reader
device introduction, 14-1
see HC bar code/RS232 module, 14-1
HC magnetic card device
introduction, 12-1
p_close, 12-1
P_FCANCEL, 12-2
P_FREAD, 12-1
P_FSET, 12-2
p_open(MCR:), 12-1
services, 12-1
HC magnetic card reader
device I/O, 12-1
HWIM
infrared applications, 15-6
I/O devices
introduction, 1-1
see devices, 1-1
I/O function
asynchronous, 1-1
p_ioc, 1-1
p_ioca, 1-1
p_iow, 1-1
synchronous, 1-1
TAS
infrared, 15-4
idle mode
infrared, 17-4
include file
infrared constants p_file.h, 16-2
infrared
AccessIr API, 15-4, 16-1
AIR: device, 15-4, 16-1, 16-2
AIR: device on Siena, 16-1
iv
baud rates, 15-3
beaming communications application,
15-6
communications AccessIr API, 16-1
communications application, 15-6
communications IrMUX API, 17-1
Condor serial chip, 15-3
connection first time (LM-IAS server),
17-4
connection second time (LM-IAS server),
17-4
connectionless calls, 17-3
connectionless read request, 17-3
connectionless services IrLAP, 15-4
connectionless write request, 17-3
connection-oriented calls, 17-3
connection-oriented services IrLAP, 15-4
constant P_FIRAWAITCONNECT, 16-3
constant P_FIRDISCONNECT, 16-3
constant P_FIRDISCOVER, 16-3
constant P_ FIRMAKECONNECT, 16-3
constant P_FIRSELECT, 16-3
constant P_FREAD, 16-3
constant P_FWRITE, 16-3
constants p_file.h, 16-2
device driver accessir.ldd, 16-1
disconnecting first time (LM-IAS server),
17-4
disconnecting second time, 17-4
discovery, 15-5, 17-4
example application, 16-7
exclusive mode, 17-4
handshaking level, 17-4
HWIM applications, 15-6
TAS, 15-4
IAS get value by class frame, 17-2, 17-3
IAS get value by class reply frame, 17-3
idle mode, 17-4
IPCS methods, 17-1
IrDA protocol model, 15-1
IrDA standard, 15-1
IrLAP, 15-1
IrLAP layer, 15-2, 15-3
IrLAP services, 15-4
IrLMP, 15-1, 15-4
IrLMP layer, 15-3
IrMUX API, 15-4, 17-1
IrMUX message format, 17-5
IrMUX server logoff, 17-2
IrMUX server logon, 17-2
ISO OSI layers, 15-1
link control, 15-6
link paste, 15-6
LM_AccessModeRequest, 17-4, 17-11
LM_CLReadRequest, 17-6
LM_CLWriteRequest, 17-7
LM_ConnectRequest, 17-2, 17-4, 17-7
LM_DisconnectRequest, 17-4, 17-13
LM_DiscoverDevicesRequest, 17-4, 17-7
LM_GetValueByClass, 17-2
LM_IdleRequest, 17-12
LM_Logoff, 17-2, 17-5
LM_Logon, 17-2, 17-5
INDEX
LM_ReadRequest, 17-4, 17-9
LM_RegisterPort, 17-2, 17-5
LM_SetHandshakingLevel, 17-4, 17-12
LM_StatusRequest, 17-9
LM_UnRegisterPort, 17-2, 17-6
LM_UReadRequest, 17-4, 17-10
LM_UWriteRequest, 17-4, 17-11
LM_WaitForConnection, 17-8
LM_WriteRequest, 17-4, 17-10
LM-IAS, 15-4
LM-IAS server registering, 17-2
LM-IAS server unregistering, 17-2
LM-MUxX, 15-4
loadIRDAserver() example code, 16-2
message number | (IrMUX), 17-5
message number 10 (IrMUX), 17-5
message number 11 (rMUX), 17-6
message number 2 (IrMUX), 17-5
message number 20 (IrMUX), 17-13
message number 21 (IrMUX), 17-9
message number 22 (IrMUX), 17-11
message number 23 (IrMUX), 17-12
message number 24 (IrMUX), 17-9
message number 25 (IrMUX), 17-10
message number 26 (IrMUX), 17-10
message number 27 (IrMUX), 17-11
message number 28 (IrMUX), 17-12
message number 4 (IrMUX), 17-6
message number 5 (IrMUX), 17-7
message number 6 (IrMUX), 17-7
message number 8 (IrMUX), 17-8
message number 9 (IrMUX), 17-7
multiplexing, 15-6
MUXMESSAGE structure, 17-5
OSI layers, 15-1
p_close, 16-2, 16-4
P_FIRAWAITCONNECT, 16-3, 16-5
P_FIRDISCONNECT, 16-3, 16-6
P_FIRDISCOVER, 16-2, 16-4
P_FIRMAKECONNECT, 16-3, 16-5
P_FIRSELECT, 16-2, 16-4
P_FREAD, 16-3, 16-6
P_FWRITE, 16-3, 16-6
p_mreceive, 17-5
p_open(AIR:), 16-2, 16-3
primary station, 15-4
printer IRP: device, 15-7
printer IRP: device Siena, 15-7
protocol stack - initializing, 17-1
protocol stack example code, 17-2
protocol stack SYS$IRDA.IMG, 16-2,
17-2
Psion protocol model, 15-2
read request, 17-4
read request unreliable, 17-4
retries, 17-4
secondary station, 15-4
SIR, 15-1
SIR: device, 15-2, 15-3
SYS_IR_POWER_LEVEL, 15-6
SYS_PRINTER_IR, 15-6
unreliable read request, 17-4
unreliable write request, 17-4
write request, 17-4
write request unreliable ), 17-4
infrared communication
introduction to Psion IR, 15-1
IPCS
infrared methods, 17-1
IrDA
infrared protocol model, 15-1
standard, 15-1
IrLAP
infrared, 15-1
infrared layer, 15-2, 15-3
IrLAP services
infrared, 15-4
IrLMP
infrared, 15-1, 15-4
infrared layer, 15-3
IrmMUxX
infrared API, 17-1
IrMUX API
infrared, 15-4
IrMUX message format
infrared, 17-5
IrMUX server
infrared logoff, 17-2
infrared logon, 17-2
IRP:
infrared printer device, 15-7
ISO OST layers
infrared, 15-1
key code
W_KEY_IR_BRING, 15-6
W_KEY_IR_LINK, 15-6
W_KEY_IR_SEND, 15-6
Link
data transfer, 10-1
example code, 10-10
inter-process messages, 10-3
panics, 10-1
process, 10-1
protocol, 10-1
protocol I/O introduction, 10-1
LINK
process, 10-3
link control
infrared, 15-6
link paste
infrared, 15-6
LM_AccessModeRequest
infrared, 17-4, 17-11
LM_CLReadRequest
infrared, 17-6
LM_CLWriteRequest
infrared, 17-7
LM_ConnectRequest
infrared, 17-2, 17-4, 17-7
LM_DisconnectRequest
infrared, 17-4, 17-13
LM_DiscoverDevicesRequest
infrared, 17-4, 17-7
LM_GetValueByClass
infrared, 17-2
I/O DEVICES REFERENCE
LM_IdleRequest
infrared, 17-12
LM_Logoff
infrared, 17-2, 17-5
LM_Logon
infrared, 17-2, 17-5
LM_ReadRequest
infrared, 17-4, 17-9
LM_RegisterPort
infrared, 17-2, 17-5
LM_SetHandshakingLevel
infrared, 17-4, 17-12
LM_StatusRequest
infrared, 17-4, 17-9
LM_UnRegisterPort
infrared, 17-2, 17-6
LM_UReadRequest
infrared, 17-4, 17-10
LM_UWriteRequest
infrared, 17-4, 17-11
LM_WaitForConnection
infrared, 17-8
LM_WriteRequest
infrared, 17-4, 17-10
LM-IAS
infrared, 15-4
LM-IAS server
LM-MUX
infrared, 15-4
loadIRDAserver()
infrared example code, 16-2
magic static
CON: device handle winHandle, 2-2
magnetic card device
see HC magnetic card device, 12-1
main world file
location, 8-9
maximum scanning rate
bar codes, 14-4
MCR: device
introduction, 12-1
see HC magnetic card device, 12-1
multiplexing
infrared, 15-6
MUXMESSAGE structure
infrared, 17-5
NCP
panics, 10-1
NCP device
I/O introduction, 10-1
NCP: device
example code, 10-10
p_close, 10-4
P_FCANCEL, 10-7
P_FCONNECT, 10-4
P_FDISCONNECT, 10-6
P_FINQ, 10-9
P_FREAD, 10-6
infrared registering, 17-2
infrared unregistering, 17-2
process SYS$NCP, 10-1
P_FRSUPER, 10-7
P_FSENSE, 10-10
P_FSTOP, 10-10
P_FWRITE, 10-7
p_open(NCP:), 10-3
process SYS$NCP, 10-2
services, 10-3
note sequence
SND: device, 5-3
OPL
CON: device use of, 2-1
OSI layers
infrared, 15-1
p_close
alarm device, 6-2
console device, 2-4
FRC: device, 7-2
HC bar code device, 13-2
HC bar code/RS232 module, 14-18
HC magnetic card device, 12-1
infrared, 16-2, 16-4
NCP: device, 10-4
parallel port, 3-1
serial port, 4-6
sound device, 5-2
world device, 8-2
XYmodem device, 9-8
p_close(CRD:)
close device, 11-2
p_close(FCG:A)
fast charger device, 18-4
P_EVENT_READ
console device, 2-9
P_EVENT_TEST
console device, 2-10
P_FCANCEL
alarm device, 6-2
cancel read from device, 11-2
console device, 2-5
FRC: device, 7-2
HC bar code device, 13-2
HC magnetic card device, 12-2
NCP: device, 10-7
parallel port, 3-2
serial port, 4-8
sound device, 5-2
world device, 8-2
P_FCONNECT
NCP: device, 10-4
XYmodem device, 9-8
P_FCTRL
serial port, 4-9
P_FDISCONNECT
NCP: device, 10-6
XYmodem device, 9-10
P_FEDIT
console device, 2-6
P_FFLUSH
console device, 2-6
serial port, 4-9
p_file.h
infrared constants, 16-2
INDEX
P_FINQ
console device, 2-10
NCP: device, 10-9
serial port, 4-10
P_FIRAWAITCONNECT
infrared, 16-3, 16-5
infrared constant, 16-3
P_FIRDISCONNECT
infrared, 16-3, 16-6
infrared constant, 16-3
P_FIRDISCOVER
infrared, 16-2, 16-4
infrared constant, 16-3
P_FIRMAKECONNECT
infrared, 16-3, 16-5
infrared constant, 16-3
P_FIRSELECT
infrared, 16-2, 16-4
infrared constant, 16-3
P_FREAD
console device, 2-5
FRC: device, 7-2, 7-3
HC bar code device, 13-2
HC bar code/RS232 module, 14-18
HC magnetic card device, 12-1
infrared, 16-3, 16-6
infrared constant, 16-3
NCP: device, 10-6
read from device, 11-2
serial port, 4-7
XYmodem device, 9-11
P_FRSUPER
NCP: device, 10-7
P_FSENSE
console device, 2-6
HC bar code/RS232 module, 14-18
NCP: device, 10-10
parallel port, 3-2
sense the device type, 11-2
serial port, 4-9
sound device, 5-2
P_FSET
HC bar code/RS232 module, 14-18
HC magnetic card device, 12-2
parallel port, 3-2
serial port, 4-9
service call convension, 2-3
set the device type, 11-2
sound device, 5-2
P_FSTART
FRC: device, 7-2
P_FSTOP
NCP: device, 10-10
P_FTEST
console device, 2-5
serial port, 4-9
P_FWFLUSH
console device, 2-10
P_FWRITE
HC bar code/RS232 module, 14-19
infrared, 16-3, 16-6
infrared constant, 16-3
NCP: device, 10-7
parallel port, 3-2
serial port, 4-8
XYmodem device, 9-12
p_ioc
I/O function, 1-1
p_ioca
I/O function, 1-1
p_iow
I/O function, 1-1
p_mreceive
infrared, 17-5
p_open(AIR:
infrared)
infrared, 16-2
p_open(AIR:)
infrared, 16-3
p_open(ALM:)
alarm device, 6-2
p_open(BAR:)
HC bar code device, 13-2
p_open(CON:)
console device, 2-3
p_open(CRD:)
open device, 11-1
p_open(FCG:A)
fast charger device, 18-3
p_open(FRC:)
FRC: device, 7-1
p_open(MCR:)
HC magnetic card device, 12-1
p_open(NCP:)
NCP: device, 10-3
p_open(PAR:)
parallel port, 3-1
p_open(SND:)
sound device, 5-2
p_open(TTY:)
HC bar code/RS232 module, 14-17
serial port, 4-6
p_open(WLD:)
world device, 8-2
p_open(XMD:)
XYmodem device, 9-8
P_SCR_ATTRB
console device, 2-11
P_SCR_CANCEL_CAPTURE_KEY
console device, 2-13
P_SCR_CAPTURE KEY
console device, 2-13
P_SCR_CLIENT_FOREGROUND
console device, 2-12
P_SCR_CLR
console device, 2-7
P_SCR_COMPATIBILITY
console device, 2-9
P_SCR_CSET
console device, 2-10
P_SCR_CURSOR
console device, 2-8
P_SCR_DISABLE_READS
console device, 2-12
P_SCR_ESCAPE
console device, 2-9
I/O DEVICES REFERENCE
P_SCR_FLUSH
console device, 2-12
P_SCR_FONT
console device, 2-11
P_SCR_GREY
console device, 2-9
P_SCR_LAST_LINE_WRAP
console device, 2-12
P_SCR_NEL
console device, 2-8
P_SCR_POSA
console device, 2-8
P_SCR_POSR
console device, 2-8
P_SCR_SCROLL
console device, 2-7
P_SCR_SLOCK
console device, 2-8
P_SCR_WLOCK
console device, 2-8
P_SCR_WSET
console device, 2-7
p_write
console device, 2-4
panics
alarm device, 6-2
console device, 2-3
Link, 10-1
NCP, 10-1
parallel port device, 3-1
serial port device, 4-1
sound device, 5-1
PAR: device
example code, 3-3
introduction, 3-1
see parallel port, 3-1
parallel port
device I/O, 3-1
example code, 3-3
p_close, 3-1
P_FCANCEL, 3-2
P_FSENSE, 3-2
P_FSET, 3-2
P_FWRITE, 3-2
p_open(PAR:), 3-1
panics, 3-1
parity errors
HC bar code/RS232 module, 14-3
PC-AT style RS232 port
HC bar code/RS232 module, 14-1
PLIB
programs CON: device use of, 2-2
power consumption
HC bar code/RS232 module, 14-4
primary station
infrared, 15-4
printer device
IRP: infrared, 15-7
protocol
Link introduction, 10-1
protocol stack
infrared - initializing, 17-1
Psion infrared
protocol model, 15-2
read request
infrared, 17-4
read request unreliable
infrared, 17-4
retries
infrared, 17-4
RI pin of the RS232 port
HC bar code/RS232 module, 14-2
RS232 device
see serial port, 4-1
RS232 port pinout table
HC bar code/RS232 module, 14-2
secondary station
infrared, 15-4
serial infrared
Condor chip, 15-3
serial port
baud rate, 4-2
character frame, 4-2
control flags, 4-5
device driver LDD, 4-1
device driver PDD, 4-1
device I/O introduction, 4-1
errors, 4-5
example code, 4-11
handshaking, 4-3
HC TTL levels, 4-1
p_close, 4-6
P_FCANCEL, 4-8
P_FCTRL, 4-9
P_FFLUSH, 4-9
P_FINQ, 4-10
P_FREAD, 4-7
P_FSENSE, 4-9
P_FSET, 4-9
P_FTEST, 4-9
P_FWRITE, 4-8
p_open(TTY:), 4-6
panics, 4-1
parameters, 4-1
parity, 4-3
services, 4-6
terminator characters, 4-5
Siena infrared
printer IRP: device driver, 15-7
SIR
infrared, 15-1
SIR:
infrared device, 15-2, 15-3
SND: device
example code, 5-5
introduction, 5-1
see sound device, 5-1
sound
buzzer emulator, 5-1
buzzer piezo, 5-1
device I/O introduction, 5-1
digital files, 5-1
HC machines, 5-1
MC machines, 5-1
INDEX
S3 machines, 5-1
S$3a machines, 5-1
sound device
E_FALARM, 5-3
E_FSSOUNDCHANNEL1, 5-3
example code, 5-5
p_close, 5-2
P_FCANCEL, 5-2
P_FSENSE, 5-2
P_FSET, 5-2
p_open(SND:), 5-2
panics, 5-1
services, 5-2
services additional HC MC S3a, 5-3
services additional S3 S3a, 5-4
SND: introduction, 5-1
structures
DISCOVERY_LOG infrared, 15-5
E_MESSAGE infrared, 17-5
MUXMESSAGE infrared, 17-5
supplement digits
bar codes, 14-4
synchronous
I/O functions, 1-1
SYS$IRDA.IMG
infrared protocol stack, 16-2, 17-2
SYS$NCP
process, 10-1, 10-2
SYS_IR_POWER_LEVEL
infrared, 15-6
SYS_PRINTER_IR
infrared, 15-6
time application
alarm services $3 S3a, 6-2
top slot
HC bar code/RS232 module, 14-2
TTY: device
example code, 4-11
introduction, 4-1
parameters, 4-1
see serial port, 4-1
TTY:A
HC bar code/RS232 module, 14-2
TTY:B
HC bar code/RS232 module, 14-2
TTY sD
HC bar code/RS232 module, 14-2
TTY:E
HC bar code/RS232 module, 14-2
unreliable read request
infrared, 17-4
unreliable write request
infrared, 17-4
W_KEY_IR_BRING
key code, 15-6
W_KEY_IR_LINK
key code, 15-6
W_KEY_IR_ SEND
key code, 15-6
wand emulator
HC bar code/RS232 module, 14-1
winHandle
magic static CON: device handle, 2-2
WLD: device
introduction, 8-1
see world device, 8-1
Workabout
battery capacity calculation, 18-3
Workabout docking station
device introduction, 11-1
see docking station device, 11-1
world application
database S3 S3a, 8-2
world database
contents, 8-1
file extension, 8-9
file format, 8-9
file format extension file, 8-10
file types and locations, 8-9
see also world device, 8-1
world database device
see world device, 8-1
world device
database contents, 8-1
file extension, 8-9
file format, 8-9
file format extension file, 8-10
file types and locations, 8-9
I/O introduction, 8-1
introduction, 8-1
mode, 8-1
p_close, 8-2
P_FCANCEL, 8-2
p_open(WLD:), 8-2
services, 8-2
WR_BACK, 8-3
WR_CALC, 8-8
WR_EXTRA, 8-5
WR_FIND_CITY, 8-2
WR_FIND_COUNTRY, 8-2
WR_FIND_EXACT, 8-3
WR_GET_CITY_DATA, 8-6
WR_GET_COUNTRY_DATA, 8-7
WR_GET_DEFAULT_COUNTRY, 8-4
WR_GET_DIAL_STRING, 8-4
WR_GET_HOME, 8-3
WR_NEXT, 8-3
WR_NEXT_LOCK, 8-9
WR_SET_DEFAULT_COUNTRY, 8-4
WR_SET_EXTRA, 8-5
WR_SET_HOME, 8-3
world file
extension, 8-9
format, 8-9
format extension file, 8-10
main, 8-9
world.dat
location, 8-9
WR_BACK
world device, 8-3
WR_CALC
world device, 8-8
WR_EXTRA
world device, 8-5
WR_FIND_CITY
world device, 8-2
ix
I/O DEVICES REFERENCE
WR_FIND_COUNTRY
world device, 8-2
WR_FIND_EXACT
world device, 8-3
WR_GET_CITY_DATA
world device, 8-6
WR_GET_COUNTRY_DATA
world device, 8-7
WR_GET_DEFAULT_COUNTRY
world device, 8-4
WR_GET_DIAL_STRING
world device, 8-4
WR_GET_HOME
world device, 8-3
WR_NEXT
world device, 8-3
WR_NEXT_LOCK
world device, 8-9
WR_SET_DEFAULT_COUNTRY
world device, 8-4
WR_SET_EXTRA
world device, 8-5
WR_SET_HOME
world device, 8-3
write request
infrared, 17-4
write request unreliable
infrared), 17-4
XMD: device
introduction, 9-1
see XYmodem device, 9-1
Xmodem device
I/O introduction, 9-1
see XYmodem device, 9-1
Xon/Xoff handshaking
HC bar code/RS232 module, 14-2
XYmodem device
checksum CRC, 9-1
checksum one byte, 9-1
device driver, 9-1
device I/O, 9-1
example connect code, 9-10
example disconnect code, 9-10
example file receive code, 9-11
example file recieve code, 9-12
example file send code, 9-10, 9-13
p_close, 9-8
P_FCONNECT, 9-8
P_FDISCONNECT, 9-10
P_FREAD, 9-11
P_FWRITE, 9-12
p_open(XMD:), 9-8
protocol problems, 9-7
protocols, 9-1
services, 9-8
Xmodem protocol, 9-2
Ymodem protocol, 9-4
Ymodem device
I/O introduction, 9-1
see XYmodem device, 9-1
Reference in New Issue View Git Blame Copy Permalink