SWI Translator
by Lewis G. Kirby

The May 1992 issue of RISC User contained the application SysCon to convert SWI name strings to and from numbers. This application, SWItrans, provides an additional facility by converting any SYS string in a Basic file into a variable; the variable name is the same as the string but in lower-case characters and ending with "%" (i.e. an integer variable). As a bonus, any hex or decimal SYS numbers are also converted to the user-friendly variable. As explained in the original SysCon article, this facility gives you the best of both worlds by combining speed of operation with readability of SWI names. 

Running the application installs an icon on the icon bar in the usual way. To use the application, drag a tokenised Basic program to the icon bar icon. You will be presented with a Save dialogue box so that the name of the transformed file can be entered. The initial name provided by default is the same as the original but with "-" appended to it, but you may change the name as required. Save the transformed program by clicking on OK, pressing Return, or dragging the Basic file icon to a directory viewer. The original file is transformed into a program with the SWI strings and literal numerics replaced by meaningful integer variables; these are initialised, when the transformed program runs, by a new procedure "PROCswiTrans" the definition of which is appended to the file. The original program is preserved.

The file dropped into the icon must be a tokenised Basic program (there is a check for this). It is scanned for SYS statements; any which are found are examined to see whether the SWI is specified by literal string, hexadecimal numeric, or decimal numeric. If this is the case then the string or numeric is replaced by an integer variable whose name is the same as the SWI string except it is in lower case and a "%" is appended to make it an integer. For example, the statements:

   SYS "OS_SWINumberFromString",,name$ TO num%;v%
   SYS &39,,name$ TO num%;v%
   SYS 57,,name$ TO num%;v%

would all be replaced by:

   SYS os_swinumberfromstring%,,name$ TO num%;v%

Any other type of entry after the SYS token is left unchanged.

When the Basic file has been transformed, a new procedure "PROCswiTrans" is appended; this sets the values of all of the new variables. This is invoked by a statement inserted near the beginning of the file - in fact directly before the first line which does not begin with the REM token. Note that if there have been no replacements then an error message to that effect is displayed and no transformation takes place.

If a previously transformed file is transformed again then the user will have to carry out the following actions:

  1. The call to "PROCswiTrans" near the start of the transformed file will be duplicated; one of the calls should be removed (although no harm is done if it is not).

  2. There may be more than one version of "PROCswiTrans"; these must be joined so that there is only one. Note that after concatenation some variables may be defined more than once; no harm is done in this case since the same values will be used, but you may remove duplicates.

Obviously there should not already be a "PROCswiTrans" in the file (apart from one possibly added previously by the SWITrans application).

There is no simple way to convert a transformed file back to the original; however, once you have converted the program it should not be necessary to restore the original method of calling SWIs.

 As with the application SysCon in the May 1992 RISC User, the SWI string is only recognised if the appropriate module is present; for example, the call

   SYS "ColourTrans_ColourNumberToGCOL"

would only be recognised if the ColourTrans module is installed. If it is not and the file to be transformed contains such a call then SWITrans displays an error. In this case the remedy is to install the relevant modules before using SWITrans.

The series of SWIs &100 to &1FF are treated in a special way; for example, 

   SYS &167

becomes

   SYS os_writei67%

If a transformed line becomes longer than 255 characters then the application displays an appropriate message; try splitting the offending line and performing the conversion again.

If SWItrans encounters a line ending with "SYS" then an error is reported.

If the insertion of the call to "PROCswiTrans" causes a duplicate line number then the program will automatically be renumbered whenever it runs. This may simply be remedied by renumbering it yourself and saving it.

The transformed program cannot be given the same name as the original unless the transformed program is dragged to a different directory viewer.

The number of SWIs the program can handle is specified by the variable "maxSWI%", initially set to 1000. You can change this if required.
