Psion REXX Interface API Reference
Mike Potapoff
Preface
This set of functions, named hereinafter as library is designed for control and take care of Psion.
To include the possibility of use this library, user have to copy files PsiREXX.dll and PsiLib.dll to the directory, stated in LIBPATH.
Before the user can call any described below function, it is required to register function names in REXX. So do it as shown:
CALL RxFuncAdd 'psiRxInit', 'psiREXX', 'psiRxInit'
CALL psiRxInit
All mentioned functions except getting info return RET_OK on normal completion. On abnormal completion functions return error code, listed below. And in case of severe error (such as too few arguments) functions are terminated with REXX error INVALID_ROUTINE (code 40).
Return Values for Functions
RET_OK = 0
RET_NOT_CONNECTED = -1
RET_ALREADY_RUNNED = -2
RET_RUN_TIMEOUT = -3
RET_NO_SUCH_PROCESS = -4
At present time the library uses next internally predefined constants
| _DELAY_TOTAL_ |
= 30L |
/* |
Max wait time to start/stop process in seconds |
*/ |
| _DELAY_DELTA_ |
= 500L |
/* |
Interval between checks in milliseconds |
*/ |
| _MAX_PROCESSES_ |
= 32 |
/* |
Max process number – defines process table size |
*/ |
I hope it’s enough. If you think other :-) let me know
Functions
Functions released now can be divided into four groups
- Library Initialization
- Connection to Psion
- Control the Processes on Psion
- Getting Psion Info
I have the intention to add file manipulation functions in the very near future
Library Initialization
There are 2 functions in this group – for registering and deregistering all the other functions:
psiRxInit
| Description: |
The function registers (makes available in REXX) all the other functions. It also closes connection to Psion if there is one. |
| Format: |
psiRxInit |
| Parameters: |
none |
| Return Value: |
RET_OK |
| Example: |
call psiRxInit |
psiRxExit
| Description: |
The function deregisters all the other functions. If necessary, it also closes existing connection to Psion. |
| Format: |
psiRxExit |
| Parameters: |
none |
| Return Value: |
RET_OK |
| Example: |
call psiRxExit |
Connection to Psion
This group controls the connection to Psion and include 2 functions:
psiRxConnect
| Description: |
The function closes the existing connection to Psion (if any) and establishes new one. |
| Format: |
psiRxConnect(PortName, ComBaud, Locale) |
| Parameters: |
|
| PortName |
optional, text string appeared as “COM1”, “COM2”, etc. If next parameters are needed, use empty string (“”) |
| ComBaud |
optional, number up to 115200 (from standard set for COM port bauds) |
| Locale |
optional, text string (for example, “IBM-866”) |
| Notes: |
There are some default conventions for parameters. If any parameter is omitted, function tries to get it from the correspondent environment variable. If such variable wasn’t defined, function uses default value. |
| Parameter |
Environment Variable |
Default Value |
| PortName | PSICOM | COM2 |
| ComBaud | PSIBAUD | 115200 |
| Locale | PSICP | IBM-1251 |
| Return Values: |
RET_OK, RET_NOT_CONNECTED |
| Example: |
rc = psiRxConnect("COM2", 38400) |
psiRxDisconnect
| Description: |
The function closes the existing connection to Psion (if any). |
| Format: |
psiRxDisConnect |
| Parameters: |
none |
| Return Value: |
RET_OK |
| Example: |
call psiRxDisConnect |
Control the Processes on Psion
This group allows user to run, track and terminate tasks on Psion and consists of 4 functions:
psiRxProgStart
| Description: |
Asks Psion to run a task by its name and exits without waiting. If third parameter is present, waits for the task to be running and then returns Process ID. |
| Format: |
psiRxProgStart(ProcName, ProcArgs, PID) |
| Parameters: |
|
| ProcName |
mandatory, full path (including drive letter) to task to run or full filename to file, associated with application; text string |
| ProcArgs |
optional, task’s parameter list, text string |
| PID |
optional, text string, contains variable’s name to return Process ID to. When is present, returns PID even if RET_ALREADY_RUNNED |
| Return Values: |
RET_OK, RET_NOT_CONNECTED, RET_ALREADY_RUNNED, RET_NO_SUCH_PROCESS, RET_RUN_TIMEOUT |
| Example: |
rc = psiRxProgStart("C:\Documents\Word", "file", "ID")
SAY "Word's PID = " ID |
psiRxProgKill
| Description: |
Asks Psion to terminate the task by its name or PID and exits without waiting. If Flag is present function waits for ending of the process. |
| Format: |
psiRxProgKill(ProcName, Flag) |
| Parameters: |
|
| ProcName |
mandatory, full path to task to kill or PID, text string |
| Flag |
optional, when exists tells function to wait for task ending |
| Return Values: |
RET_OK, RET_NOT_CONNECTED, RET_NO_SUCH_PROCESS, RET_RUN_TIMEOUT |
| Example: |
rc = psiRxProgKill(ID) |
psiRxProgList
| Description: |
Gets the list of tasks, running on Psion, and/or the list of process IDs for these tasks. |
| Format: |
psiRxProgList(PIDList, TaskList) |
| Parameters: |
|
| PIDList |
optional, when presents, gives the stem’s* name as a text string to return the Process IDs to. Upon returning “PIDList”.0 contains PIDs counter |
| TaskList |
optional, when presents, gives the stem’s* name as a text string to return the Task Names to. Upon returning “PIDList”.0 contains Tasks counter |
| |
*stem is a standard method to gain an access to the structure fields from within REXX (See REXX Reference for details) |
| Return Value: |
RET_OK, RET_NOT_CONNECTED |
| Example: |
rc = psiRxProgList(, "Tasks")
SAY 'Total Tasks running:' Tasks.0
SAY 'Task List'
DO i = 1 to Tasks.0
SAY Tasks.i
END |
psiRxProgRunning
| Description: |
Tests if given task is running on Psion. |
| Format: |
psiRxProgRunning(Task) |
| Parameters: |
|
| ProcName |
mandatory, full path to running task or PID |
| Return Values: |
RET_OK, RET_NOT_CONNECTED, RET_NO_SUCH_PROCESS |
| Example: |
IF psiRxProgRunning(ID) == RET_NO_SUCH_PROCESS THEN
SAY 'No Such Task' |
Getting Psion Info
This group allows the user to get some useful information about his Psion. There are 4 functions in this group:
psiRxGetVersion
| Description: |
Returns the version of connected Psion. |
| Format: |
psiRxGetVersion |
| Parameters: |
none |
| Return Value: |
Psion’s version, text string or RET_NOT_CONNECTED |
| Example: |
SAY "Version = " psiRxGetVersion() |
psiRxGetOwner
| Description: |
Returns the owner’s name of your :-) Psion. |
| Format: |
psiRxGetOwner |
| Parameters: |
none |
| Return Value: |
Psion’s owner, text strings, separated by LineFeed or RET_NOT_CONNECTED |
| Example: |
SAY "Owner: " psiRxGetOwner() |
psiRxGetMachine
| Description: |
Returns the Psion’s type. |
| Format: |
psiRxGetMachine |
| Parameters: |
none |
| Return Value: |
Psion’s machine type, number from the table below or RET_NOT_CONNECTED |
| Code | Machine Type |
|---|
| 0 | Unknown |
| 1 | PC |
| 2 | MC |
| 3 | HC |
| 4 | Series 3 |
| 5 | Series 3a, 3c, or 3mx |
| 6 | Workabout |
| 7 | Sienna |
| 8 | Series 3c |
| 32 | Series 5 |
| 33 | WinC |
| Example: |
SAY "Psion's Type: " psiRxGetMachine() |
psiRxGetInfo
| Description: |
Returns information about Psion, stored as a stem |
| Format: |
psiRxGetOwner(Info) |
| Parameters: |
|
| Info |
mandatory, text string with the stem name, where information will be stored to. Upon return “Info”.0 contains parameters number, while “Info”.i contains i parameter name and parameters itself are in “Info”.ParamName. See example below for details |
| Return Value: |
parameters number or RET_NOT_CONNECTED |
| Example: |
CALL psiRxGetInfo "Info"
SAY "Total Parameters: " Info.0
SAY "MachineType: " Info.MachineType
SAY "ROMversion: " Info.ROMversion
SAY "ROMbuilt: " Info.ROMbuilt
SAY "MachineName: " Info.MachineName
SAY "DisplayWidth: " Info.DisplayWidth
SAY "DisplayHeight: " Info.DisplayHeight
SAY "MachineUID: " Info.MachineUID
SAY "Time: " Info.Time
SAY "RAMsize: " Info.RAMsize
SAY "ROMsize: " Info.ROMsize
SAY "RAMmaxFree: " Info.RAMmaxFree
SAY "RAMfree: " Info.RAMfree
SAY "RAMdiskSize: " Info.RAMdiskSize
SAY "Language: " Info.Language
|
Example
/*** Psion REXX Interface API Usage Example ******/
/*** (c) 2001 Mike Potapoff ******/
/*** Function Return Code Definitions ************/
RET_OK = 0
RET_NOT_CONNECTED = -1
RET_ALREADY_RUNNED = -2
RET_RUN_TIMEOUT = -3
RET_NO_SUCH_PROCESS = -4
SAY 'Psion REXX Interface v1.0. Usage Example'
SAY '(c) 2001 Mike Potapoff'
SAY
SAY 'Registering all Functions for further usage'
CALL RxFuncAdd 'psiRxInit', 'psiREXX', 'psiRxInit'
CALL psiRxInit
SAY 'Connecting to Psion, attached to COM1...'
IF psiRxConnect("COM1") \== RET_OK THEN DO
SAY 'Err: Connection to Psion Failure.'
SAY ' Check the Connection or Parameters.'
CALL psiRxExit
EXIT
END
SAY 'Ok'
SAY
SAY 'Getting Various Information from Psion'
SAY
SAY 'Version = ' psiRxGetVersion()
SAY 'Machine = ' psiRxGetMachine()
SAY
/*** Owner Info consists of some strings. Parse it ***/
own = psiRxGetOwner()
SAY "Owner's Info:"
DO i = 1 BY 1 WHILE LENGTH(STRIP(own)) \= 0
PARSE VALUE own WITH s '0A'x own
say 'Line' i '=' s
END
SAY
SAY 'Get Other Information'
rc = psiRxGetInfo('Info')
SAY 'Info Pieces = ' Info.0
SAY
DO i = 1 to Info.0 by 1
INTERPRET 'j = Info.' || Info.i
SAY Info.i " = " j
END
SAY
SAY 'Testing process control routines'
SAY
SAY 'Spreadsheet Run and Wait for PID...'
ps = psiRxProgStart("C:\Documents\Sheet", 0, "id")
SELECT
WHEN ps = RET_OK THEN
SAY 'Task is Run, its ID = ' id
WHEN ps = RET_ALREADY_RUNNED THEN
SAY 'Task is Already Run, its ID = ' id
WHEN ps = RET_NO_SUCH_PROCESS THEN
SAY 'Err: No such task'
WHEN ps = RET_RUN_TIMEOUT THEN
SAY "Err: Psion didn't return task's PID in reasonable time"
END
SAY
SAY "Testing if Task is Running by it's PID..."
IF psiRxProgRunning(id) == RET_OK THEN
SAY 'Ok'
ELSE
SAY 'Err: No Such Process'
SAY
SAY "Testing if Task is Running by it's Name..."
IF psiRxProgRunning("C:\Documents\Sheet") == RET_OK THEN
SAY 'Ok'
ELSE
SAY 'Err: No Such Process'
SAY
SAY "Getting Tasks and PIDs Lists..."
call psiRxProgList 'PIDList', 'taskList'
SAY 'Ok, Total Number of Processes Running:' PIDList.0
SAY
SAY 'Process List'
DO i = 1 to PIDList.0
SAY PIDList.i taskList.i
END
SAY
SAY 'Terminating Task without wait...'
SAY 'Stop by Name: ' psiRxProgKill("C:\Documents\Sheet")
SAY 'Stop by ID: ' psiRxProgKill(id)
SAY
SAY 'Testing if Task Still Runnung...'
SAY 'Running: ' psiRxProgRunning(id)
SAY
SAY 'Terminating Task and waiting...'
SAY 'Stop: ' psiRxProgKill(id,1)
SAY 'Running: ' psiRxProgRunning(id)
SAY
SAY 'Testing completed. Exiting.'
CALL psiRxExit
EXIT
/*
End of Example
*/