Jaap's Psion II Page

PSION One Way Interface (OWI)
1200 Baud 202 Modem

Operating Instructions


Table of Contents

1. Introduction 1.1 Disk Contents 1.2 Prerequisites 2. Driver Functions 2.1 OWIDIAL% 2.2 OWIHOOK% 2.3 OWIINIT% 2.4 OWILSTN% 2.5 OWIOFF% 2.6 OWISEND% 2.7 OWISPKR% 2.8 OWITONE% 3. Miscellaneous Functions 3.1 ISNUM% 3.2 PACK$ 3.3 UNPACK$ 4. Making Program Paks 4.1 BLDPACK Command File 4.2 Making a Bootable Pak Appendix: Undocumented functions A.1 SVIEW% A.2 CHKBB% A.3 CHKNWD%

1. Introduction

The PSION One Way Interface (OWI) allows the PSION Organiser to communicate unidirectionally with a Bell 202 receiving system. The OWI is can be used in direct line or acoustic mode. In direct line mode, it can also dial out using either DTMF touch tones or pulses.

The operation of the OWI is controlled by a set of driver functions which are contained in a DataPak located in one of the side slots of the Organiser. This document describes the driver functions, and the procedures for installing them in a DataPak.

1.1 Disk Contents

This disk contains the following files:

OWI.DOC -this documentation file
OWITEST.OPL -test and example program
 
OWIHDR_8.BIN-driver program for 8K DataPak
OWIHDR16.BIN-driver program for 16K DataPak
OWIHDR32.BIN-driver program for 32K DataPak
OWIHDR64.BIN-driver program for 64K DataPak
OWIHD128.BIN-driver program for 128K DataPak
OWIHDR_R.BIN-driver program for 32K RAM Pak
 
OWITST_8.BLD-BLDPACK command file for 8K DataPak
OWITST16.BLD-BLDPACK command file for 16K DataPak
OWITST32.BLD-BLDPACK command file for 32K DataPak
OWITST64.BLD-BLDPACK command file for 64K DataPak
OWITS128.BLD-BLDPACK command file for 128K DataPak
OWITST_R.BLD-BLDPACK command file for 32K RAM Pak

1.2 Prerequisites

Before using the OWI, or any of the software on this disk, you will need the following items:

(Note: Data Paks must be completely erased (formatted)).

Please take the time to read through the OPL Developer manual, especially the sections on the OPLTRAN, BLDPACK and MAKE utility programs. This will explain the procedures outlined here in greater detail.

For more information refer to the PSION Technical Reference Manual.

2. Driver Functions

The OWI driver functions are accessed as extensions to the basic PSION OPL language. This is similar to the LSET%, LINPUT$, and other Comms Link functions that become available when the RS-232 Comms Link is installed. There are eight OWI driver functions that are used to control the OWI and to send data:

OWIDIAL%-operate the auto dialer section of the OWI
OWIHOOK%-control the hook switch in direct line mode
OWIINIT%-initialise the OWI hardware and set parity
OWILSTN%-listen after sending data
OWIOFF% -turn the OWI hardware off
OWISEND%-send data
OWISPKR%-control the speaker (on, off)
OWITONE%-send mark or space tone frequencies

The following sections describe each function in greater detail. The test and example program (OWITEST.OPL) illustrates how the various functions are called, and in what order.

2.1 OWIDIAL%

Syntax: e% = OWIDIAL%:( tp$, phone$ )
where:e%= return error code
tp$= touch tone/pulse selection ("T" or "P")
phone$= phone number string
Description: The OWIDIAL% function is used to operate the autodialer section of the OWI in direct line mode. The two parameters passed to OWIDIAL% control the dialing method, and the phone number.

The 'tp$' parameter selects DTMF touch tones or rotary pulse dialing method. This parameter must be a string. The first character in the string must be either a "T" (touch tone) or a "P" (pulse).

The 'phone$' parameter is a string containing the phone number to be dialed. This string may contain anything, but only the following characters will be used:

0 - 9= digits 0-9
# = telephone pad # button
* = telephone pad * button
/ = one second pause
Examples: e% = OWIDIAL%:( "P", "555-1212")
e% = OWIDIAL%:( "T", "9//1-416-555-1212")
Returns:
0 = no error
205= wrong number of parameters
247= bad parameter value

2.2 OWIHOOK%

Syntax: e% = OWIHOOK%:( onoff% )
where:e%= return error code
onoff%= desired hook state
Description: The OWIHOOK% function is used to control the state of the hook switch in direct line mode.

The 'onoff%' parameter indicates the desired state of the hook switch:

0= ON Hook (ie. hang up)
1= OFF Hook (ie. pick up handset)
Examples: e% = OWIHOOK%:( 0 ) :rem Hang Up Phone

e% = OWIHOOK%:( 1 ) :rem Pick Up Phone
Returns:
0 = no error
205= wrong number of parameters
247= bad parameter value

2.3 OWIINIT%

Syntax: e% = OWIINIT%:( parity% )
where:e%= return error code
parity%= parity to use when sending
Description: The OWIINIT% function is used to turn on the OWI hardware, and to initialise the driver program. This function must be called once before any other OWI functions are called.

The 'parity%' parameter defines the type of parity calculation to perform on data char- acters when they are sent, and the format of each data character:

0= no parity (1 start bit, 7 data bits, 2 stop bits)
1= odd parity (1 start bit, 7 data bits, 1 odd parity bit, 1 stop bit)
2= even parity (1 start bit, 7 data bits, 1 even parity bit, 1 stop bit)
Examples: e% = OWIINIT%:( 0 ) :rem No Parity
e% = OWIINIT%:( 1 ) :rem Odd Parity
e% = OWIINIT%:( 2 ) :rem Even Parity
Returns:
0 = no error
205= wrong number of parameters
247= bad parameter value

NOTE: This function initialises all OWI hardware and driver parameters, and must not be called after any other OWI driver functions.

2.4 OWILSTN%

Syntax: e% = OWILSTN%:( spkr% )
where:e%= return error code
spkr%= speaker mode (on, off)
Description: This function is used to turn off the modem after sending data or tones, and enable the speaker to listen for voice responses.

The 'spkr%' parameter controls the state of the speaker after the modem is turned off. A value of 0 will leave the speaker turned OFF (typical in acoustic mode), or a value of 1 will leave the speaker turned ON, (typical in direct line mode).

Refer to the examples in the OWITEST.OPL program to see how the OWILSTN% function is used at the end of data transmission.

Examples: e% = OWILSTN%:( 0 ) :rem Modem OFF, Speaker OFF
e% = OWILSTN%:( 1 ) :rem Modem OFF, Speaker ON
Returns:
0 = no error
205= wrong number of parameters
247= bad parameter value

2.5 OWIOFF%

Syntax: OWIOFF%:
Description: The OWIOFF% function is called once at the end of data transmission to turn the OWI hardware off. This function will hang up the phone, and disable power to the OWI device.

OWIOFF% has no parameters, and returns nothing.

Examples: OWIOFF%:
Returns: nothing

2.6 OWISEND%

Syntax: e% = OWISEND%:( data$ )
where:e%= return error code
data$= data to transmit
Description: The OWISEND% function is the heart of the OWI driver. It transmits the characters provided in the 'data$' parameter one at a time, in order from left to right. Parity bits are added to each character according to the parity mode selected when OWIINIT% was called.

OWISEND% will send the characters in 'data$' exactly as presented. The maximum length of the data string is 255 characters. Non- printing characters (ie. Carriage Return, Line Feed, etc.) may be embedded in the string exactly as they would be in any other PSION string, (eg. CHR$(13) for Carriage Return).

Between calls to OWISEND%, the modem will transmit the Mark frequency (1200 Hz).

Examples: e% = OWISEND%:( "Sending this"+CHR$(13) )
e% = OWISEND%:( A.item$ )
Returns:
0 = no error
205= wrong number of parameters
247= bad parameter value

2.7 OWISPKR%

Syntax: e% = OWISPKR%:( spkr% )
where:e%= return error code
spkr%= speaker mode (on, off)
Description: The OWISPKR% function provides direct control of the built in speaker. This function can be called any time to turn the speaker on or off without affecting the modem or the hook switch.

The 'spkr%' parameter is set to 0 to turn the speaker OFF, or to 1 to turn the speaker ON.

Examples: e% = OWISPKR%:( 0 ) :rem Speaker OFF
e% = OWISPKR%:( 1 ) :rem Speaker ON
Returns:
0 = no error
205= wrong number of parameters
247= bad parameter value

2.8 OWITONE%

Syntax:e% = OWITONE%:( tone% )
where:e%= return error code
tone%= frequency and duration
Description: The OWITONE% function is called to transmit Mark or Space frequency tones before and after data is transmitted. These tones are used by the receiving modem to synchronise the data line.

The 'tone%' parameter specifies the duration of the tone in milliseconds, and the frequency. Values in the range 1 to 32767 will generate Mark frequency tones (1200 Hz), or values from -1 to -32767 will generate Space frequency tones (2200 Hz).

After the specified tone has been transmitted the modem will remain enabled, and will transmit a Mark tone until OWISEND%, OWILSTN%, or OWIOFF% is called. This insures that there is no break in the transmission to the receiving modem.

Examples: e% = OWITONE%:( 4000 ) :rem send 4 second Mark tone
e% = OWITONE%:( -3000 ) :rem send 3 second Space tone
Returns:
0 = no error
205= wrong number of parameters
247= bad parameter value

3. Miscellaneous Functions

Several other functions are included with the basic OWI driver functions. These miscellaneous functions have proven useful in the past, and are provided as a convenience to OWI programmers.

The following sections describe each of these functions in greater detail.

3.1 ISNUM%

Syntax: e% = ISNUM%:( string$ )
where:e%= return error code
string$= string to check
Description: The ISNUM% function provides a convenient method of checking a string for non-numeric characters. The function will return 0 (False) if the string contains any non- digit (ie. not 0-9), or -1 (True) if the string contains all digits.
Examples: if( ISNUM%:( "12345" ) ) ...
Returns:
0 = non numeric character found
-1 = valid numeric string
205= wrong number of parameters
247= bad parameter value

3.2 PACK$

Syntax: pk$ = PACK$:( unpk$ )
where:pk$= packed numeric string
unpk$= standard character string
Description: The PACK$ function provides a convenient method of packing numeric data to conserve storage requirements. A packed string will require half the storage space of an equivalent un-packed string (ie. standard printable characters).

Strings to be packed may contain any of the following characters:

  • digits 0 to 9
  • Space (hex 20)
  • Asterisk ( * )
  • Plus Sign ( + )
  • Comma ( , )
  • Minus Sign ( - )
  • Period ( . )
Examples: pk$ = PACK$:( "123456" )
pk$ = PACK$:( "$123.45" )
Returns: string containing packed information
Error Codes:
205= wrong number of parameters
247= bad parameter value

3.3 UNPACK$

Syntax: unpk$ = UNPACK$:( pk$ )
where:unpk$= standard character string
pk$= packed numeric string
Description: The UNPACK$ function is the opposite of the PACK$ function described above. It takes a previously packed string and expands it into its original printable format.
Examples: PRINT( UNPACK$:( pk$ ) )
Returns: standard character string
Error Codes:
205= wrong number of parameters
247= bad parameter value

4. Making Program Paks

Before making a program pak you must fully understand the process for making paks as described in the PSION OPL Developer manual. This discussion assumes you understand the OPLTRAN, BLDPACK and MAKE programs, and how they use command files.

The OWI driver functions are supplied on this disk in the form of pak header files (.BIN files). These will be loaded into fully erased Data or RAM Paks as part of the pak building process. When the pak is installed in an Organiser the driver functions will be 'booted' into memory, and will extend the OPL language functions.

More information on how this process works can be found in the PSION Technical Reference Manual, in the section on External Interfacing.

4.1 BLDPACK Command File

The easiest way to build a pak file suitable for programming into a Data or RAM Pak is to use the command file mode in BLDPACK. In fact, to install the OWI driver functions this is the only way. This disk contains example BLDPACK command files for each of the different pak sizes. For example, the BLDPACK command file for 16K Data Paks contains the following information:

OWITEST 16 OWIHDR16 BIN OWITEST OB3 OWITEST

The first line names the pak file (.OPK file) that will be produced (here it will be OWITEST.OPK). It also specifies the size of pak that will be generated (eg. 16 K).

The second line tells BLDPACK to include the OWI driver functions for 16K Data Paks (OWIHDR16.BIN).

The third line tells BLDPACK to load a Translated (with OPLTRAN) OPL program (eg. OWITEST).

To substitute your own programs, you may change the pak name (on line 1), or the OPL program(s) on line 3. You must not change the order of the file (ie. the .BIN file must be on line 2), but you can add more OPL programs to the end.

To change the size of the pak, change the size parameter on line 1, and the OWIHDR file name on line 2. The values must match. For RAM Paks, the pak size on line 1 will be 32, and the OWIHDR file must be OWIHDR_R.BIN.

4.2 Making a Bootable Pak

When the OWI driver functions are 'booted' into the Organiser, the driver will search slots B: and C: for an OPL program called "BOOT". If a program by this name is found, the word "BOOT" will be added to the PSION main menu and an EXEcute key will be forced into the keyboard buffer in the Organiser. This will cause the Organiser to immediately being executing the BOOT program.

This feature is handy if you want to automatically start your program every time the PSION is turned on. What you put in the BOOT program is up to you; you can enter an endless loop providing only the functions you want your users to see, or you can execute a RETURN statement and get back to the PSION main menu.

Using this feature is required if you are using the industrial model Organisers (P250 and P350). Both of these units require that a program called BOOT be located on one of the side data pak slots.


Appendix. Undocumented functions

By Jaap Scherphuis.

Some functions were not documented in the manual file I received. These functions will be explained here.

A.1 SVIEW%

Syntax: key% = SVIEW$:(line%, view$ )
where:key%= code of key pressed
line%= line to view string on
view$= String to view
Description: The SVIEW% function is exactly like the OPL VIEW function except that the left and right arrow keys do not change the scroll direction but also exit the viewing like any other key.
Examples: key% = SVIEW$:(1, "String to be scrolled on screen")
Returns: standard character code of key pressed
Error Codes:
205= wrong number of parameters
247= bad parameter value

A.2 CHKBB%

Syntax: valid% = CHKBB%:(bar$ )
where:valid%= -1 if barcode is valid
bar$= barcode string to check
Description: The CHKBB% function checks a six digit string and returns -1 if it has a valid MSI-Plessey modulo 10 checksum. It returns 0 if the string is not of length 6, or if the checksum fails.
Examples: IF CHKBB%:(bar$) :PRINT "Valid" :ENDIF
Returns: True (-1) if valid, else false (0).
Error Codes:
205= wrong number of parameters
247= bad parameter value

A.3 CHKNWD%

Syntax: valid% = CHKNWD%:(bar$ )
where:valid%= -1 if barcode is valid
bar$= barcode string to check
Description: The CHKNWD% function ckecks a six digit string and returns -1 if it has a valid MSI-Plessey modulo 11 checksum. It returns 0 if the string is not of length 6, or if the checksum fails.
Examples: IF CHKNWD%:(bar$) :PRINT "Valid" :ENDIF
Returns: True (-1) if valid, else false (0).
Error Codes:
205= wrong number of parameters
247= bad parameter value