Binary Files

 

mIRC allows you to read and write binary files, and to modify binary variables, by using the following commands and identifiers.

 

/bread [-ta] <filename> <S> <N> <&binvar>

This reads N bytes starting at the Sth byte position in the file and stores the result in the binary variable &binvar.

 

The -t switch reads data up to the next CR/LF.

 

The -a switch disables UTF-8 encoding of characters in the range 0-255, as long as the line contains no characters > 255.

 

Note: the Sth byte position starts at zero.

 

/bwrite [-tac] <filename> <S> [N] <text|%var|&binvar>

This writes N bytes from the specified text, %var, or &binvar, to the file starting a the Sth byte position. Any existing information at this position in the file is overwritten. If S is -1, the bytes are appended to the end of the file. If N is -1, all of the specified data is written to the file.

 

The -t switch interprets the data value as plain text and does not evaluate &binvar variables.

 

The -a switch disables UTF-8 encoding of characters in the range 0-255, as long as the line contains no characters > 255.

 

The -c switch chops the file at the end of the copied bytes.

 

Note: the Sth byte position starts at zero.

 

Note: if specifying a %var, it should be passed as % $+ var, to prevent double evaluation, as /bwrite reads directly from the variable in order to preserve spaces.

 

/bset [-tacz] <&binvar> <N> <asciivalue> [asciivalue ... asciivalue]

This sets the Nth byte in binary variable &binvar to the specified ascii value. If N is -1, the values are appended.

 

If you try to /bset a variable that does not exist, it is created and zero filled up to N bytes. If &binvar exists and you specify an N position beyond its current size, it is extended to N bytes.

 

If you specify multiple asciivalues, they are copied to successive positions after byte position N.

 

The -t switch indicates that /bset should treat the values as plain text and copy them directly into &binvar.

 

The -a switch disables UTF-8 encoding of characters in the range 0-255, as long as the line contains no characters > 255.

 

The -c switch chops &binvar at the end of the copied bytes.

 

The -z switch creates an empty &binvar or zeros an existing one.

 

/bunset <&binvar> [&binvar ... &binvar]

This unsets the specified list of &binvars.

 

/bcopy [-zc] <&binvar> <N> <&binvar> <S> <M>

This copies M bytes from position S in the second &binvar to the first &binvar at position N. This can also be used to copy overlapping parts of a &binvar to itself. If N = -1, bytes are appended to the destination &binvar.

 

If you specify the -z switch, the bytes in the second &binvar that were copied are zero-filled after the copy.

 

If you specify the -c switch, the first &binvar is chopped at the end of the copied bytes.

 

Note: If M is -1, all of the bytes from position S onwards are copied.

 

/breplace <&binvar> <oldvalue> <newvalue> [oldvalue newvalue...]

This replaces all matching ascii values in &binvar with new values.

 

/btrunc <filename> <bytes>

This truncates/extends a file to the specified length.

 

$bvar(&binvar,N,M)

Returns M ascii values starting from the Nth byte

 

Properties: text, word, nword, long, nlong

 

$bvar(&v,0)        returns the length of the binary variable

$bvar(&v,1)        returns ascii value at position N

$bvar(&v,5,3)        returns ascii values from 5 to 8

$bvar(&v,5,3).text        returns plain text from 5 to 8 up to the first zero character

 

The word, nword, long, and nlong properties return values in host or network byte order.

 

$bfind(&binvar, N, M, [name])

Searches a &binvar for a matching value, starting from position N. M can be a character value, ie. 0 to 255, or text.

 

Properties: text, textcs, regex

 

$bfind(&test, 1, mirc)        finds "mirc" starting from pos 1

$bfind(&test, 5, 32)        finds char 32 (a space) from pos 5

$bfind(&test, 1, 87 65 86)        finds WAV from pos 1

 

You can use .text/.textcs to force a case-insensitive/case-sensitive text search if the search text is a number.

 

You can use .regex to perform a regex search, where M is a regular expression. The optional [name] parameter is the $regml() name.

 

Notes on &binvar binary variables

Binary variables have no size limit, limited only by available memory, and are automatically destroyed when a script finishes processing.