XVI32: XVIscript interpreter

The built-in XVIscript interpreter is a powerful feature to automate tasks (e.g. apply binary patches). You can

The online help does explain the usage of XVIscript in detail.

Suppose you have often to convert Unix text files into Windows format by replacing all EOF marks $0A by $0D 0A. Although this is very easy to accomplish using the Search | Replace dialog, you could use the following almost self-explaining script: 

REM goto begin of file (always zero-based)
ADR 0
REM replace all $0A by $0D 0A
REPLACEALL 0A BY 0D 0A
As shown in the picture above right, it's very easy to select a command from the menu: it will be pasted at the current position within the editor. If a command needs additional argument(s), the pasted text does contain an appropriate explanation within <...>. This explanation will be highlighted by default, so the next key press will overwrite it. Text within (...) is only an additional hint and must be deleted; refer to the ADREOF (go to end of file) in the above picture.


Running scripts automatically from the command line

It is possible to start XVI32, open a file and execute a script automatically. If no errors do occur and changes were made, the file will be automatically saved, and XVI32 will terminate afterwards. In case of any syntax or run-time error, XVI32 will report this error. It's up to you to handle this situation, i.e. the file will not be saved automatically and XVI32 will not terminate.

The 3rd, 4th, ..., 11th command line parameters of XVI32 will be passed to the script. Please reference these parameters within the script as %1, %2, ..., %9. Example (note the quotation marks neccessary to include spaces): 

XVI32.exe readme.txt /S=c:\ProgramFiles\xvi32\universalrepl.xsc 0A "0D 0A"
In this example, 0A can be referenced as %1 and "0D 0A" as %2 within universalrepl.xsc as follows: 
REM goto begin of file (always zero-based)
ADR 0
REM in above example %1 is 0A
REM and %2 is 0D 0A
REPLACEALL %1 BY %2


Usage of batch file to process multiple files

Using the batch commands FOR and START allows to process multiple files by the same script. Example for a batch file that will convert all text files in the current directory to Unix: 
FOR %%f IN (*.txt) DO START /W c:\ProgramFiles\xvi32\xvi32.exe %%f /S=c:\ProgramFiles\xvi32\win2unix.xsc
The parameter /W of the START batch commands is ensuring that XVI32 will be relaunched not until the previous script execution has terminated. These examples are also very simple, but you probably can imagine much more sophisticated ones.


Sharing scripts over the web

On http://www.jps.net/thamiter/anitest/icon2cur.htm you'll find an explanation how to convert a Windows icon into a cursor file. To avoid mistakes while editing the file, the author of the above site could now publish simply the following XVIscript: 
REM script to convert an icon to cursor
REM http://www.jps.net/thamiter/anitest/icon2cur.htm
ADR 0
REM it must be a single-icon with 16 colors
REM 32x32 pixels not required
REM 16 colors ------------------+
REM pixels    ------------+--+  |
REM 1 icon    ------+     |  |  |
REM                 |     |  |  |
VERIFY 00 00 01 00 01 00 ?? ?? 10 00
ADR 2
REM replace 01 by 02
OVERWRITE 02
REM this is decimal ($A is hex equivalent)
ADR 10
MSG Please enter coordinates in XVI32 as XX 00 XX and save file as .CUR
Unfortunately, you must manually enter meaningful coordinates depending on the shape of the icon. In the example on the above website, you should overwrite the three bytes at the current address with 10 00 1D in XVI32.


Available Commands in alphabetical order

ADR <addr>
Go to address <addr>; <addr> is always zero-based and can be indicated either as decimal or hexadecimal (with prefix $) value. ADR should always be the first command in a script; if omitted, ADR 0 will be used as default. If the indicated address is invalid, script execution will be aborted with an error message. Examples:
ADR 32
ADR $20

ADR+ <n>
Increment current address by <n> bytes; <n> can be indicated either as decimal or hexadecimal (with prefix $) value. If the computed new address is invalid, the script will be aborted with an error message. Examples:
ADR+ 16
ADR+ $10

ADR- <n>
Decrement current address by <n> bytes; <n> can be indicated either as decimal or hexadecimal (with prefix $) value. If the computed new address is invalid, the script will be aborted with an error message. Examples:
ADR- 20
ADR- $14

ADREOF
Go to end of file, i.e. last byte.

BITAND <hex byte> [byte count]
For [byte count] bytes beginning at the current address, perform a bitwise AND operation with <hex byte>. Default for [byte count] is 1. Examples:
This will set the byte at the current address to zero:
BITAND 00
Set 20 bytes beginning at the current address to zero:
BITAND 00 20
Set $A = 10 bytes beginning at the current address to zero:
BITAND 00 $A

BITNOT [byte count]
For [byte count] bytes beginning at the current address, perform a bitwise NOT operation (i.e. each bit is inverted). Default for [byte count] is 1. Examples:
BITNOT
BITNOT 20
BITNOT $A

BITOR <hex byte> [byte count]
For [byte count] bytes beginning at the current address, perform a bitwise OR operation with <hex byte>. Default for [byte count] is 1. Examples:
BITOR 02
BITOR 02 20
BITOR 02 $A

BITSHL <bit count> [byte count]
For [byte count] bytes beginning at the current address, perform a logical left shift by <bit count> bits. Default for [byte count] is 1. Examples:
BITSHL 1
BITSHL 1 20
BITSHL 1 $A

BITSHR <bit count> [byte count]
For [byte count] bytes beginning at the current address, perform a logical right shift by <bit count> bits. Default for [byte count] is 1. Examples:
BITSHR 1
BITSHR 1 20
BITSHR 1 $A

BITXOR <hex byte> [byte count]
For [byte count] bytes beginning at the current address, perform a bitwise XOR operation with <hex byte>. Default for [byte count] is 1. Examples:
BITXOR 02
BITXOR 02 20
BITXOR 02 $A

CHARCON <XCT file name>
Load indicated character conversion file and perform a character conversion beginning at current address. The XCT file must exist at run-time, otherwise the script will be aborted. Performing a character conversion will not change the current address. Example:
ADR 0
CHARCON C:\ProgramFiles\XVI32\DOSWIN.xct

DEL <n>
Delete <n> bytes; <n> can be indicated either as decimal or hexadecimal (with prefix $) value. The current address will not be changed as long at it remains valid; otherwise, the current address will be set to end of file. If n is less or equal 0, a syntax error occurs. If there are not enough bytes to delete, this will cause a run-time error. Examples:
DEL 64
DEL $40

EXIT
Terminate execution of script (without error). Useful e.g. to execute a script only partially. The EXIT command does not terminate syntax checking, i.e. the syntax check is always performed for the complete script.

FIND <hex string>
Find next occurrence of <hex string>. If a joker (wildcard) byte was previously defined using the JOKERON command, the appropriate byte will match any byte within the file. If no match of <hex string> is found, this will cause a run-time error. Example:
FIND 0D 0A

FINDASC <string>
Find (case sensitive) next occurrence of <string>. If a joker (wildcard) byte was previously defined using the JOKERON command, the appropriate byte will match any byte within the file. If no match of <string> is found, this will cause a run-time error. Note: any usage of a % character within <string> will be considered as reference of a command line parameter. If a % character should be taken literally, you must use the FIND command instead. Leading and trailing blanks within <string> are allowed. Example:
FIND Hello

INSERT <hex string>
Insert <hex string> before current address. Afterwards, the current address will be right after the last inserted byte. Example:
INSERT FF FF

JOKERON <hex char>
Define a joker (wildcard) byte that is used by all following FIND, REPLACE, and REPLACEALL commands. A joker (wildcard) byte will match any byte. If hex byte is invalid (or more than one byte), this will cause a syntax error. Example:
JOKERON FF

JOKEROFF
Disable previously defined joker (wildcard) byte, i.e. all following FIND, REPLACE, and REPLACEALL commands will not use use a joker (wildcard) byte.

MSG <message>
Display <message> on screen. This command is ignored when executing a script from the command line using the /S parameter. The message is shown within a memo, so you can copy it to clipboard. The following placeholders are expanded (case sensitive; numbers are decoded in decimal format):
\n line break
$BYTE decode current address as byte
$WORD decode from current address 2 bytes as word (provided 2 bytes are existing)
$INT ditto 2 bytes as integer
$LONG ditto 4 bytes as long integer
$IEEE32  ditto 4 bytes as float
$IEEE64  ditto 8 bytes as float
Examples:
MSG File successfully patched!\nPlease save.
ADR 1023
MSG Decoded at address 1023\nWord: $WORD\nLong: $LONG

OVERWRITE <hex string>
Overwrite bytes beginning at current address with <hex string>. Afterwards, the current address will be right after the last byte that was overwritten. If there are not enough bytes to overwrite, this will cause a run-time error. Example:
OVERWRITE 00 00 00

REM
Line contains remark ignored by XVI32script. Lines beginning with a semicolon are also treated as comments. Examples:
REM This is a comment
;this line is ignored too

REPLACE <from hex string> BY <to hex string>
Find next occurrence of <from hex string> and replace by <to hex string>. If a joker (wildcard) byte was previously defined using the JOKERON command, the appropriate byte will match any byte within the file. Afterwards, the current address will be at the last replaced byte. If no match of <from hex string> is found, this will cause no run-time error. Empty <to hex string> is allowed. Example:
REPLACE 0D 0A BY 0A

REPLACEALL <from hex string> BY <to hex string>
Same as above, but all occurrences are replaced.

REPLACEASC <from string> BY <to string>
Find next occurrence of ASCII-string <from string> and replace by <to string>. If a joker (wildcard) character was previously defined using the JOKERON command, the appropriate byte will match any character within the file. Afterwards, the current address will be at the last replaced byte. If no match of <from string> is found, this will cause no run-time error. Empty <to string> is allowed. Note: any usage of a % character within <from string> or <to string> will be considered as reference of a command line parameter. If a % character should be taken literally, you must use the REPLACE command instead. Leading and trailing blanks within <from string> and <to string> are allowed, as shown in the following example where <from string> has both leading and trailing blank:
REPLACE  xvi32  BY xvi32
REM     ^-----^ leading and trailing blank

REPLACEALLASC <from string> BY <to string>
Same as above, but all occurrences are replaced.

VERIFY <hex string>
Verify that <hex string> is found at current address, otherwise execution of script will be aborted with an error message. Use ?? within the hex string as joker (wildcard) byte that matches any byte. It is also possible to indicate several alternative hex strings separated by OR. Examples:
VERIFY 0D 0A
VERIFY FF ?? FF
VERIFY FF 00 FF OR FF 01 FF
VERIFY FF 00 FF OR 00 ?? FF

[Back to XVI32 home]