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%
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.
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 |
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.
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.
| Syntax: | e% = OWIDIAL%:( tp$, phone$ )
| |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| 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:
| |||||||||
| Examples: |
e% = OWIDIAL%:( "P", "555-1212")
e% = OWIDIAL%:( "T", "9//1-416-555-1212") | |||||||||
| Returns: |
|
| Syntax: | e% = OWIHOOK%:( onoff% )
| ||||||
|---|---|---|---|---|---|---|---|
| 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:
| ||||||
| Examples: |
e% = OWIHOOK%:( 0 ) :rem Hang Up Phone
e% = OWIHOOK%:( 1 ) :rem Pick Up Phone | ||||||
| Returns: |
|
| Syntax: | e% = OWIINIT%:( parity% )
| ||||||
|---|---|---|---|---|---|---|---|
| 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:
| ||||||
| Examples: |
e% = OWIINIT%:( 0 ) :rem No Parity
e% = OWIINIT%:( 1 ) :rem Odd Parity e% = OWIINIT%:( 2 ) :rem Even Parity | ||||||
| Returns: |
|
NOTE: This function initialises all OWI hardware and driver parameters, and must not be called after any other OWI driver functions.
| Syntax: | e% = OWILSTN%:( spkr% )
| ||||||
|---|---|---|---|---|---|---|---|
| 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: |
|
| 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 |
| Syntax: | e% = OWISEND%:( data$ )
| ||||||
|---|---|---|---|---|---|---|---|
| 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: |
|
| Syntax: | e% = OWISPKR%:( spkr% )
| ||||||
|---|---|---|---|---|---|---|---|
| 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: |
|
| Syntax: | e% = OWITONE%:( tone% )
| ||||||
|---|---|---|---|---|---|---|---|
| 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: |
|
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.
| Syntax: | e% = ISNUM%:( string$ )
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
| 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: |
|
| Syntax: | pk$ = PACK$:( unpk$ )
| ||||||
|---|---|---|---|---|---|---|---|
| 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:
| ||||||
| Examples: | pk$ = PACK$:( "123456" )
pk$ = PACK$:( "$123.45" ) | ||||||
| Returns: | string containing packed information | ||||||
| Error Codes: |
|
| Syntax: | unpk$ = UNPACK$:( pk$ )
| ||||||
|---|---|---|---|---|---|---|---|
| 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: |
|
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.
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.
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.
By Jaap Scherphuis.
Some functions were not documented in the manual file I received. These functions will be explained here.
| Syntax: | key% = SVIEW$:(line%, 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: |
|
| Syntax: | valid% = CHKBB%:(bar$ )
| ||||||
|---|---|---|---|---|---|---|---|
| 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: |
|
| Syntax: | valid% = CHKNWD%:(bar$ )
| ||||||
|---|---|---|---|---|---|---|---|
| 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: |
|