Revision as of 15:05, 10 January 2018

The /bset command lets you assign specific ASCII values (or text) at a specific position. If the variable does not exist, a new binary variable will be created and zero-pad until <pos>. If <pos> exceeds the length of the variable, the variable will extend (by zero-padding the gap) to accommodate the new values.

Note: Important fact to remember about binary variables is that they are not limited to the local scope of the alias but instead they remain set until processing is complete. Thus it's possible to use the same binary variable within multiple aliases if they call each other during the same script execution.

Synopsis

/bset -c <&bvar> <pos> <asciivalue> [asciivalue ... asciivalue]
/bset -tac <&bvar> <pos> <string>

Switches

• -t - Indicates a string is to be written instead of literal ASCII values
• -c - Fills the binary variable with the string/ASCII values and truncates anything after it
• -a - Don't apply UTF-8 encoding to characters in the range 0-255, as long as the string parameter contains no characters > 255.

Parameters

• <&bvar> - The binary variable name to use/create
• <pos> - The position to set the new ASCII values or the string, use -1 to append. The first byte of the string is pos 1. If <pos> is greater than the existing length of the binary variable, the string is zero-padded to fill undefined bytes between <pos> and the prior end of string.
• <asciivalue> - ASCII 0-255 value to write. If values are in range 256 - 2^31-1, writes $and(value,255). If value >= 2^31, writes 255.
• [asciivalue ... asciivalue] - Succeeding ASCII values to be written
• <string> - The string to be written. The number of values is limited only by the 4150 character line length for the entire command including 'bset'

Example

Alias Example {
  ;Create a binary variable set it to "This is fun!"
  bset -t &Example 1 This is fun!
 
  ;Print out the content of the variable
  echo -a $bvar(&Example, 1-).text
}

Binary variables have the advantage that they can be accessed from anywhere during the script execution.

Alias Example {
  ;Create a binary variable
  bset -t &Example 1 Hello There Bob.
  bb
}
Alias bb {
  ; Override that last part and truncate it 
  bset -tc &Example 7 Stranger!
  cc
}
Alias cc {
  ; print the value
  echo -a $bvar(&Example, 1-).text
}

This example shows how the variable gets zero-padded if <pos> is outside the size of the variable:

Alias Example {
  ; put 'd' as the 5th byte in &var
  bset &var 5 100
  ; same as
  ; bset &var 5 $asc(d)
 
  ; will print: 0 0 0 0 100
  echo -a $bvar(&var, 1-)
 
  ; zero-pad bytes 6-8
  bset &var 9 33
  
  ; will print: 0 0 0 0 100 0 0 0 33
  echo -a $bvar(&var, 1-)
}

create variable with UTF-8 encoding:
//bset -t  &var 1 $chr(233) | echo -a $bvar(&var,1-)
returns: 195 169
//bset -ta &var 1 $chr(233) | echo -a $bvar(&var,1-)
returns: 233
-a works only when no characters are codepoint 256+
//bset -ta &var 1 $chr(233) $+ $chr(10004) | echo -a $bvar(&var,1-)
returns: 195 169 226 156 148
//bset &var 1 10004 | echo -a $bvar(&var,1-)
returns $and(10004,255) = '20' instead of the 3 encoded bytes of $chr(10004)

Binary variables are not limited to 4150 length. To fill a 7mb binary variable with all $chr(0)'s sets the last byte as 0, and allows zero-filling the prior bytes with 0x00's:

//bset &var 7654321 0 | echo -a Length of variable is $bvar(&var,0)

To fill a 7mb variable with non-zeroes, it's more efficient to lengthen with /bcopy but bset can set long variables by repeatedly appending bytes. Max length of binary string can depend on your system resources:

/fill_with_ones 7654321
 
alias fill_with_ones {
  if ($1 !isnum 1-) return | bset &var 1 1
  while ($1 > $bvar(&var,0)) {
    bset &var -1 $str(0 $chr(32),$iif($calc($1 - $bvar(&var,0)) > 999,$v2,$v1))
    echo -a current length: $bvar(&var,0)
  }
  echo -a variable length is $bvar(&var,0)
}

Compatibility

Added: mIRC v5.3
Added on: 13 Dec 1997
Note: Unless otherwise stated, this was the date of original functionality.
Further enhancements may have been made in later versions.

See also