FileReadX plugin for Take Command / TCC / TCC/LE

beta version 0.90.5 2024-11-05

Charles Dye

Purpose:

This plugin attempts to reimplement some discontinued former features from Vincent Fatica’s 4UTILS plugin. I am attempting to match his documented syntax fairly closely, but undocumented behaviors, edge conditions, error handling, and so on, are likely to be different.

Installation:

To use this plugin, copy FileReadX.dll to some known location on your hard drive. (If you are still using the 32-bit version of Take Command, take FileReadX-x86.dll instead of FileReadX.dll.) Load the .DLL file with a PLUGIN /L command, for example:

plugin /l c:\bin\tcmd\test\filereadx.dll

If you copy the .DLL file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.

Plugin Features:

New Commands:
`DEC`	`INC`
New Functions:
`@FILEREADI`	`@FILEREADX`	`@FILEWRITEX`

Syntax Note:

The syntax definitions in the following text use these conventions for clarity:

`BOLD CODE`	indicates text which must be typed exactly as shown.
`CODE`	indicates optional text, which may be typed as shown or omitted.
Bold italic	names a required argument; a value must be supplied.
Regular italic	names an optional argument.
ellipsis…	after an argument means that more than one may be given.

Examples are shown in a gray box:

rem This is an example: inc /v count

Some command options take an argument. These are shown with a colon between the option and its argument: /A:arg

If you like, you may substitute an equals sign for the colon: /A=arg This is handy if the arg is a filename, and you want to use tab completion to enter the filename.

Or you can omit the colon: /Aarg

New Commands:

DEC — Decrement an environment variable.

Syntax:
DEC /Q /V /Z varname

`/Q`	quietly — do not display error messages
`/V`	verbose — display new value
`/Z`	treat non-numeric variables as zero
varname	the name of the variable to decrement; required

The variable name varname is required. It may contain letters, digits, dollar signs, hyphens, periods, and underscores; it must not begin with a digit. If the specifed environment variable does not exist, it will be created with a value of -1.

If the environment variable does exist, it should contain:

a decimal number: decimal digits only, with an optional leading + or - sign; or
a hexadecimal number with a leading 0x; or
an octal number with a leading 0o.

The updated value will be in the same format as the original value. If the environment variable contains anything other than a number in one of the above formats, INC will give an error unless you also specify /Z.

Decimal values are signed 64-bit integers; hex and octal values are unsigned.

New Functions:

@FILEREADI — Reads and returns variable-sized integers from a file, in a variety of formats.

Syntax:
%@FILEREADI[handle,valsize]

handle	as returned by `@FILEOPEN`
valsize	integer size in bytes

Handle and valsize are both required. Valsize ranges from 1 to 8. The valsize may optionally be followed by a letter to select the format:

`d`	unsigned decimal integer (the default)
`x`	hexadecimal with leading `0x`, lowercase
`X`	hexadecimal with leading `0x`, upperease
`h`	hexadecimal with no prefix, lowercase
`H`	hexadecimal with no prefix, uppercase
`s`	signed decimal integer
`S`	signed decimal integer, with `+` for nonnegative values
`o`	octal with leading `0o`

If you do not specify a format, the default is unsigned decimal. If you append an exclamation point to the format, the order of the bytes will be reversed, e.g. 4x! to return a big-endian doubleword in hexadecimal.

If there are fewer than valsize bytes remaining in the file, @FILEREADI returns **EOF**.

@FILEREADX — Reads bytes from a file, and returns them as hexadecimal values.

Syntax:
%@FILEREADX[handle,count,fmt]

handle	as returned by `@FILEOPEN`
count	the maximum number of bytes to return
fmt	the format in which to return values

This function can return up to 4,096 bytes at a time. If you do not specify a count, the default is 1.

If there are fewer than count bytes remaining in the file, @FILEREADX returns only what is there. If there is no more data, @FILEREADX returns **EOF**.

Byte values are separated with spaces. The optional fmt parameter lets you select the format:

`0`	unsigned decimal integers
`1`	hexadecimal with a leading `0x`
`2`	hexadecimal with no prefix (the default; suitable for `@FILEWRITEX`)
`3`	signed decimal integers
`4`	signed decimal integers, with `+` for nonnegative values
`5`	octal with a leading `0o`

Startup Message:

This plugin displays an informational line when it initializes. The message will be suppressed in transient or pipe shells. You can disable it for all shells by defining an environment variable named NOLOADMSG, for example:

set /e /u noloadmsg=1

Changes:

Version	Date	Changes
0.90.5	2024-11-05	PLUGIN_BUFFER_MAX is 32K bytes, not 32K characters. `@FILEREADX`: check for buffer overflow (because it is possible to overflow a 16K buffer).
0.90.4	2024-10-14	Tweaks to the help text; no changes to operation.
0.90.3	2024-10-11	First release.

Status and Licensing:

Consider this beta software. It may well have issues. Try it at your own risk. If you find a problem, you can report it in the JP Software support forum.

FileReadX is currently licensed only for testing purposes. I may make binaries and source code available under some free license once I consider it ready for use.

Download:

You can download the current version of this plugin from https://charlesdye.net/dl/filereadx.zip.

handle	as returned by `@FILEOPEN`
val1, val2, val3, etc.	byte values in hexadecimal

— Quick Links —