Psion REXX interface API.

At the moment there exist two ways for Psion to OS/2 connection which we've done : PsiFtp utility and Psion-plugin for NetDrive. Both of them use common link engine and supply basic file manipulation features. On my opinion it's not enough for comfortable work with a Psion. There is lack of conversion utilities and probably lack of functionality for independent projects. So we decided to create a REXX interface for the Psion link engine. In this document you can find quite comprehensive descriptions for each of designed routines.

Note. Current version of the Psion link engine doesn't support concurrent job for one Psion device for Psion-plugin (or PsiFtp) and REXX interface. You can't call any of REXX routines while Psion plugin is connected or PsiFtp started, and visa versa.

First of all. Psion link engine is a single dynamic-link library (DLL) - file psilib.dll, versions 1.2 and higher (look correspondent version either for PsiFtp or for Psion-plugin) content REXX interface. Here and below I admit that you have basic knowledge about external routines calling in REXX. There are different ways to load and initialise functions from psilib.dll.

- You can copy it into the directory which name contents in the LIBPATH variable in your CONFIG.SYS. And then call :

CALL RxFuncAdd 'prxInit', 'psilib.dll', 'prxInit'

CALL prxInit

- Or you put this DLL-file anywhere you want and add the name of the directory it resides to LIBPATH variable. And then perform described above code.
- Or you can do that following way :

'@SET BEGINLIBPATH=C:\NDFS\ndplugs'

CALL RxFuncAdd 'prxInit', 'psilib.dll', 'prxInit'

CALL prxInit

After one of those steps REXX interface ready to use.

All functions return status code (error code), except cases when they return information. You have to analyse it to be aware that everything is OK. All possible error codes listed below.

RET_OK = 0

RET_NOT_CONNECTED = -1

RET_NOT_ENOUGH_MEM = -2

RET_ALREADY_RUNNED = -3

RET_RUN_TIMEOUT = -4

RET_NO_SUCH_PROCESS = -5

RET_CANT_CREATE_DIR = -7

RET_CANT_DELETE_DIR = -8

RET_CANT_DELETE = -9

RET_CANT_GET_FILE = -10

RET_CANT_PUT_FILE = -11

Note : in case of severe and non-recoverable error REXX terminates with a one of standard code, consult REXX manual for additional information.

All routines could be divided into several groups :

1. Working environment initialisation and control functions.
2. Psion connection control functions.
3. Psion informative functions.
4. Psion processes control functions (kind of RPC interface).
5. Psion files/directories manipulation functions.

   Working environment initialisation and control group.

   There are two functions in this group :

   prxInit [(MaxProc,MaxWait)]

   Description : Initialises working environment for other Psion interface REXX procedures. It registers them, creates all necessary buffers etc.

   Parameters : It has two optional parameters :

   MaxProc - maximum number of processes on Psion (Process list size). Default it is 32. If your Psion is rather heavily loaded you should increase that up to appropriate value.

   MaxWait - time in seconds, process start and termination latency time. Default it is 30 sec. If your Psion is heavily loaded or you use big programs on it, you should increase this parameter. If this timeout is exceeded and process control routine doesn't find its action finished it will return RET_RUN_TIMEOUT.

   Return values : RET_OK, RET_NOT_ENOUGH_MEM

   Example : CALL prxInit ( 64, 20 )

   prxQuit

   Description : De-registers all other functions, frees all allocated memory, perhaps finishes a connection if there is any exists.

   Parameters : None.

   Return values : RET_OK

   Example : CALL prxQuit

   Psion connection control functions.

   prxConnect ([PortName,ComBaud,PsionLocale,startRPC])

   Description : Establishes a new connection with a Psion on the selected port, with a selected baud rate. It closes previously created connection is it was any.

   Parameters : All parameters are optional.

   PortName text string like "COM1", "COM2", etc. If next parameters are needed, use empty string ("")

   ComBaud number up to 115200 (from standard set of COM port bauds)

   PsionLocale text string, for example, "IBM-866" (from the standard set of Locale names, consult your OS/2 User manual for that).

   startRPC number 0 - means don't start RPC service if you haven't such on your Psion (for old models), 1 or omitted - means start RPC connection. By default Psion-engine always starts RPC service.

   Note. There are some conventions for parameters. If any parameter is omitted, it will be taken 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 | 115 200
   PsionLocale | PSICP | IBM-1251

   Return values : RET_OK, RET_NOT_CONNECTED

   Example : CALL prxConnect ( "COM1", 38400 )

   prxDisconnect

   Description: The function closes the existing connection to Psion (if any).

   Parameters: None

   Return values: RET_OK

   Example: CALL prxDisconnect

   Psion informative functions.

   Note. All of those functions base on RPC service. So if you don't have it started, informative functions won't work.

   prxPsionVersion

   Description: Returns the version for connected Psion.

   Parameters: None

   Return values: text string - Psion's version or RET_NOT_CONNECTED.

   Example: SAY "Version = " prxPsionVersion()

   prxPsionOwner

   Description: Returns the owner's name of your :-) Psion.

   Parameters: None

   Return values: Psion's owner credentials, text strings, separated by LineFeed or RET_NOT_CONNECTED

   Example: SAY "Owner: " prxPsionOwner()

   prxPsionType

   Description: Returns the Psion's type.

   Parameters: None

   Return values: Psion's machine type, number from the table below or RET_NOT_CONNECTED

   Code | Machine type | Code | Machine type | Code | Machine type
   0 | Unknown | 4 | Series 3 | 8 | Series 3c
   1 | PC | 5 | Series 3a, 3x, 3Mx | 32 | Series 5
   2 | MC | 6 | Workabout | 33 | WinC
   3 | HC | 7 | Sienna |  |

   Example: SAY "Psion's Type: " prxPsionType()

   prxPsionParameters (Info)

   Description: Returns information about Psion, stored as a stem. Note stem is a standard method to gain an access to the structure fields from within REXX (See REXX Reference for details).

   Parameters: this single parameter is Info mandatory, text string with the stem name, where information will be stored to. Upon return 'Info'.0 contains parameters number, when 'Info'.i contains i parameter's name and parameter value is placed in 'Info'.ParamName. See example below for details.

   Return values: parameters number or RET_NOT_CONNECTED

   Example:

   CALL prxPsionParameters "Param"

   SAY "Total Parameters: " Param.0

   SAY "MachineType: " Param.MachineType

   SAY "ROMversion: " Param.ROMversion

   SAY "ROMbuilt: " Param.ROMbuilt

   SAY "MachineName: " Param.MachineName

   SAY "DisplayWidth: " Param.DisplayWidth

   SAY "DisplayHeight: " Param.DisplayHeight

   SAY "MachineUID: " Param.MachineUID

   SAY "Time: " Param.Time

   SAY "RAMsize: " Param.RAMsize

   SAY "ROMsize: " Param.ROMsize

   SAY "RAMmaxFree: " Param.RAMmaxFree

   SAY "RAMfree: " Param.RAMfree

   SAY "RAMdiskSize: " Param.RAMdiskSize

   SAY "Language: " Param.Language

   Psion processes control functions.

   This group allows user to run, track and terminate tasks on Psion. Note. All of those functions base on RPC service. So if you don't have it started, process control functions won't work.

   prxTaskStart(ProcName [, ProcArgs, PID])

   Description: Asks Psion to open file and run associated with it application or simply run a task by its name. If third parameter is presented, waits until the task starts and then returns Process ID, else exits without waiting.

   Parameters:

   ProcName is a mandatory parameter - text string, full path (including drive letter) to a program filename to run or full filename of an application data file;

   ProcArgs is an optional parameter - text string, task's parameters space separated;

   PID optional, text string, contains variable's name to return Process ID to. When is present, returns PID although function returns RET_ALREADY_RUNNED;

   Return values: RET_OK, RET_NOT_CONNECTED, RET_ALREADY_RUNNED, RET_NO_SUCH_PROCESS, RET_RUN_TIMEOUT

   Example:

   rc = prxTaskStart("C:\Documents\Sheet", "", "ID1")

   SAY "PID for file 'Sheet' = " ID1

   rc = prxTaskStart("Z:\System\Apps\Word\Word.app", "", "ID2") SAY "Word's PID = " ID2

   prxTaskIsRunning(Task [, PID])

   Description: Tests if given task is running on Psion.

   Parameters:

   ProcName is a mandatory parameter, text string, PID or full path to file opened or running.

   PID optional, text string, contains variable's name to return Process ID to. When is present, function returns PID for selected task.

   Return values: RET_OK, RET_NOT_CONNECTED, RET_NO_SUCH_PROCESS

   Example:

   IF prxTaskIsRunning(Name, 'ID') == RET_NO_SUCH_PROCESS THEN

   SAY 'No Such Task'

   ELSE

   SAY "Task's PID = " ID

   prxTaskList (PIDList [, FileList])

   Description: Gets the list of process IDs (tasks running) and/or the list of files opened and associated with applications.

   Parameters:

   PIDList is mandatory parameter, text string, stem's name to return the Process IDs to. Upon returning "PIDList".0 contains PIDs number.

   FileList optional, when is presented, gives the stem's name as a text string to return the Task Names to. Upon returning "FileList".0 contains Files number.

   Return values: RET_OK, RET_NOT_CONNECTED

   Example:

   rc = prxTaskList("Tasks")

   SAY 'Total Tasks running:' Tasks.0

   SAY 'Task List'

   DO i = 1 to Tasks.0

   SAY Tasks.i

   END

   prxTaskKill(ProcName [, Flag])

   Description: Asks Psion to terminate the task by its PID or filename. If Flag is presented function waits for ending of the process, else exits without waiting.

   Parameters:

   ProcName is a mandatory parameter, text string, full path to task PID to kill or to filename;

   Flag optional, when exists tell function to wait until task ends.

   Return values: RET_OK, RET_NOT_CONNECTED, RET_NO_SUCH_PROCESS, RET_RUN_TIMEOUT.

   Example:

   rc = prxTaskKill(ID)

   prxTaskKillX (PIDmask [, Flag])

   Description: Asks Psion to terminate all the tasks which names begin with PIDmask. If Flag is presented function waits for ending of the process, else exits without waiting.

   Parameters:

   PIDmask mandatory, text string, mask for PIDs to kill,

   Flag optional, when exists tells function wait until task ends.

   Return Values: RET_OK, RET_NOT_CONNECTED, RET_NO_SUCH_PROCESS, RET_RUN_TIMEOUT

   Example:

   rc = prxTaskKillX('Word')

   Psion files/directories manipulation functions.

   Common notes for all file manipulation routines. If file name is not a full file name including directory name functions are assured that file resides on the current path. Functions perform all necessary name conversions considered to code pages on their own.

   prxPWD

   Description: Gets a current working path on Psion.

   Parameters: None

   Return values: test string - full name on current path on Psion.

   Example:

   SAY 'Current Dir:' prxPWD()

   prxCD (DirName)

   Description: Sets new current path on Psion.

   Parameters:

   DirName is a mandatory parameter, text string, new path on Psion.

   Return values: RET_OK, RET_NO_SUCH_DIR

   Example:

   CALL prxCD('D:\Documents')

   prxMD (DirName)

   Description: Creates new directory on Psion. Note. Current version can't create directories recursively.

   Parameters:

   DirName is a mandatory parameter, text string, name of a directory to create on Psion.

   Return values: RET_OK, RET_CANT_CREATE_DIR

   Example:

   CALL prxMD('D:\MyDocuments')

   prxRD (DirName)

   Description: Removes directory on Psion. Note. Current version can't delete directories recursively.

   Parameters:

   DirName is a mandatory parameter, text string, name of a directory to create on Psion.

   Return values: RET_OK, RET_CANT_DELETE_DIR

   Example:

   CALL prxRD('D:\MyDocuments')

   prxFileList(List, [DirMask])

   Description: Returns directory content on DirMask.

   Parameters:

   List is mandatory parameter, text string, stem's name to return the list of files. Upon returning "List".0 contains total number of files in list. Each item looks like this line :

   "Welcome to Series 5 12688 08/06/1997"

   DirMaskis an optional parameter, text string, file mask to list files. If it is omitted, function returns list of files for current directory on Psion.

   Return values: RET_OK, RET_NO_SUCH_DIR.

   Example:

   CALL prxFileList 'Dr', s

   SAY 'Files in dir ' s

   DO i = 1 to Dr.0 by 1

   SAY Dr.i

   END

   prxDel(FileName)

   Description: Deletes indicated file on Psion.

   Parameters:

   FileName is a mandatory parameter, text string, name of the file to delete. Note. Current version can't delete file with attribute "Read-Only" set.

   Return values: RET_OK,RET_CANT_DELETE.

   Example:

   SAY 'rc =' prxDel("C:\MyDocumets\Agenda")

   prxRen(OldName,NewName)

   Description: Renames indicated file on Psion from OldName to NewName.

   Parameters:

   OldName is a mandatory parameter, text string, name of the file to rename from.

   NewName is a mandatory parameter, text string, name of the file to rename to.

   Return values: RET_OK,RET_CANT_RENAME

   Example:

   CALL prxRen("C:\Agenda","C:\MyDocumets\CurrentAgenda")

   prxGet(PsionFileName,PCFileName)

   Description: copies one file from Psion to PC.

   Parameters:

   PsionFileName is a mandatory parameter, text string, name of the Psion file to copy from.

   PCFileName is a mandatory parameter, text string, name of the PC file to copy to.

   Return values: RET_OK,RET_CANT_GET_FILE

   Example:

   SAY 'rc =' prxGet("D:\Docs\ImportantNote","C:\APPS\File1")

   prxPut(PCFileName,PsionFileName)

   Description: copies one file from PC to Psion.

   Parameters:

   PCFileName is a mandatory parameter, text string, name of the PC file to copy from.

   PsionFileName is a mandatory parameter, text string, name of the Psion file to copy to.

   Return values: RET_OK,RET_CANT_PUT_FILE.

   Example:

   SAY 'rc =' prxPut("C:\APPS\File1","D:\Docs\ImportantNote")

   prxGetFileInfo(FileName)

   Description: Reads Psion file attributes as a text string consists of letter for each corresponding attribute or '-'. For example 'RH--A--' or '----A---'. In first case file has "Read-Only", "Hidden" and "Archived" attributes. In second case file has only one "Archived" attribute.

   Parameters:

   FileName is a mandatory parameter, text string, name of the file to read attributes.

   Return values: RET_OK,RET_CANT_GETATTR.

   Example:

   SAY 'Attributes for ' d 'is ' prxGetFileInfo(d)

   prxSetFileInfo(FileName,Attributes)

   Description: Sets Psion file attributes.

   Parameters:

   FileName is a mandatory parameter, text string, name of the file to set attributes for.

   Attributes is a mandatory parameter, text string consists of letters for attributes to set or remove. List of available :

   R - read-only

   H - hidden

   S - system

   A - archived

   To set an attributes you should add before the corresponded letter '+'. To remove an attributes you should add before the letter '-' (See example).

   Return values: RET_OK,RET_CANT_SETATTR.

   Example:

   SAY 'rc =' prxSetFileInfo("D:\Documents\Word","+R-H")

   Complete example of using those procedures you can find in the PsiFtp distributive. There are two files included : psiREXXfile.cmd and psiREXXproc.cmd.

   I dare say that is all. If you have any suggestions or remarks, you are welcome.

   (C) 2001 Andrei A. Porodko <porro@cbs-edu.chel.su>

   Mike A. Potapoff <mike@cbs-edu.chel.su>