JSBin.dll Function Reference - v.1.26.704
JSBin.dll is a component for working with binary files in VBScript.
It provides a number of functions to read, write, convert to and from Base64, and manage
byte data. Some of the functions are included for specific binary file operations
that would not be relevant with text files, such as reading or setting bit flags and
converting a number of bytes to a numeric value (or vice versa). There is more
explanation about that in the README file, but if you don't know why you might
want to read or set a bit flag then you probably also won't care.
A note about 0 Base:
Arrays start with 0 and files start with 0.
To make operations consistent the read and write functions here
also start with 0. For example, a read that starts with 3 will read
starting with the 4th byte (0, 1, 2, 3).
Likewise, a new file should be written starting at 0.
A note about datatypes:
VBS uses only the variant datatype. Binary data is written as bytes.
Because of that, binary data is not normally accessible or writable
from VBS.
To make this data available from VBS, the BinaryOps functions accept
the arrays of variants that VBS uses. The functions also return arrays of
variants. This means that the bytes returned from a file can be altered
and then used in a write operation. The component will make the necessary
datatype conversions.
General Usage Information
JSBin needs to be registered before use. Just put the file
JSBin.dll in a safe place, like the System folder, then drop it onto the RegSvr.vbs file
to register it.
JSBin.dll is written in Visual Basic 6. It requires the VB6 runtime library
(MSVBVM60.DLL, pre-installed on Windows 2000/ME/XP) but it has no other dependencies.
Methods and Properties
Function BinaryOpen(FilePath, FileLength)
ex.: ErrorCode = Bin.BinaryOpen("C:\Windows\Desktop\pic.bmp", L)
Info: Open a binary file in preparation for writing.
FilePath: Full path of file.
FleLength: Returns byte length of file.
Return:
0 - OK. FileLength returns length of file.
1 - error: file is already open with bin object. FileLength returns 0.
2 - error: other error - file open, etc. FileLength returns 0.
Notes: BinaryOpen will create a non-existing file.
Function BinaryWrite(Array, StartPoint)
ex.:ErrorCode = Bin.BinaryWrite(A1, 0)
Info: Writes binary data (as array) to file.
Array: Array of bytes to write. array elements will be converted to byte if necessary.
StartPoint: Position to start writing. Use 0 to start at beginning of file. To replace and/or
append bytes starting at the 31st byte:
BinaryWrite(A, 30) . To append
bytes to end of file:
BinaryWrite(A, (L + 1)) where L is file length returned
from BinaryOpen function.
Return:
0 - OK.
1 - no file open.
2 - Array argument is not an array.
3 - other errors, such as trying to write an array element other than 0-255.
Notes: File must be opened via BinaryOpen before writing and
must be closed using BinaryClose after writing. Failure to close file will leave it locked to other
programs.
BinaryWrite will leave any unwritten bytes intact. To replace all bytes in a file
of longer length than Ubound(Array) + 1 you must create a new file, delete the old
and rename the new.
Function BinaryClose()
ex.:ErrorCode = Bin.BinaryClose()
Info: Closes file opened by JSBin object.
Notes: No arguments. Returns 0 on success, 1 if no file is open, 2 if other error.
Function BinaryRead(FilePath, StartPoint, LengthToRead, ArrayOfBytesRead)
ex.:L = 100
ErrorCode = Bin.BinaryRead(sFilePath, 0, L, A)
Info: Read bytes from a file.
FilePath: Full path to file.
StartPoint: Byte number to begin reading; 0 for beginning of file.
LengthToRead: Number of bytes to read. Use 0 to read to end file.
( Use StartPoint = 0 and LengthToRead = 0 to read entire file.)
If StartPoint + LengthToRead is greater than file length, file
will be read to end.
ArrayOfBytesRead: Returns array of bytes, returned as variants.
Return:
0 - OK. LengthToRead returns # of bytes read. ArrayOfBytesRead returns bytes.
1 - File not found. LengthToRead returns 0. ArrayOfBytesRead returns ""
2 - StartPoint invalid. LengthToRead returns 0. ArrayOfBytesRead returns ""
3 - File is 0 length. LengthToRead returns 0. ArrayOfBytesRead returns ""
4 - Unknown error; file may be open or path may be invalid.
Notes: Using StartPoint and LengthToRead parameters, large files can be managed in a loop,
reading a section at a time.
Function Bits8ToDecimal(vString)
ex.: n = Bin.Bits8ToDecimal("00001100")
Info: Converts a string representation of 8 bits to decimal number (byte). Example
above would return 12, for instance. Useful in setting bit flags.
Return:
Returns 0 to 255 on success.
-1 - Not 8 characters.
-2 - Not binary(contains other than 1's and 0's)
-3 - Other error.
Function DecimalToBits8(vNumber)
ex.: n = Bin.Bits8ToDecimal(12)
Info: Converts a number from 0 to 255 into a string representation of bits.
Useful in reading bit flags.
Above example would return "00001100". Returns "" on error.
Converting multiple bytes and numeric values
e = Bin.GetNumFrom2Bytes(b1, b2)
e = Bin.GetNumFrom3Bytes(b1, b2, b3)
e = Bin.GetNumFrom4Bytes(b1, b2, b3, b4)
ArrayOfByteNumbers = Bin.Get2BytesFromNum(Number)
ArrayOfByteNumbers = Bin.Get3BytesFromNum(Number)
ArrayOfByteNumbers = Bin.Get4BytesFromNum(Number)
Info: The first 3 functions here convert byte values to numbers.
Numeric data is often stored in binary files by using multiple bytes. Using
the "Little Endian" system, the 1st byte on left will represent the lowest
hexadecimal exponent. So the bytes 20 10 03 00 would represent:
32 + (16 * 256) + (3 * 65536) + (0 * 16777216)
Return: Returns numeric value represented by bytes, or -1 if error.
The latter 3 functions convert a number to bytes and return an array.
Return: Returns an array of bytes to represent the given number. The array can then be written to file.
Notes: An error with these functions is not unlikely if the wrong bytes are
being read. For instance, if you mean to read 4 bytes from the bitmap file header of a white-colored bitmap, and instead
you mistakenly read 4 bytes of the actual bitmap data, you will get 255, 255, 255, 255 - which will yield an invalid
(out of range) number when calling GetNumFrom4Bytes, and will return -1.
Base64 Functions
Base64 is the encoding used to encode binary files as text, as with embedded
images in HTML email. The Base64 functions will encode or decode Base64 text. If
the text represents a file it can be written, using BinaryWrite, to reproduce that file.
These functions are somewhat slow as they convert all data back and forth
to and from variant datatype in order to accomodate the limitatios of VBScript. On smaller files
the speed won't be noticeable, but
larger files may take several seconds to convert.
Base64 is usually written in lines of 76 characters when added to email text,
but the line returns are not part of the Base64 encoding.
In order to accomodate that quirk, when converting to Base64 text JSBin
does not add
line returns, but when converting Base64 to binary, JSBin does check for - and remove - any
line returns before converting. So, in other words, there is no need to be concerned about
line returns at all with JSBin, unless formatting Base64 text for inclusion into a "hand-constructed" email.
The Base64 Methods:
___________________________________________________
• Function BytesToBase64(vArray)
___________________________________________________
s = bin.BytesToBase64(vArray)
vArray: An array of bytes (values from 0 to 255).
Returns Base64 text as string or "" on error.
___________________________________________________
• Function Base64ToBytes(vString, vArray)
___________________________________________________
e = bin.Base64ToBytes(vString, vArray)
vString: Base64 text string to convert to bytes.
vArray: Array of bytes returned.
Return: 0 - OK. 1 - error. An error will be returned
if len(vString) is less than 5.
Bit flag notes
This section is provided for guidance in setting bit flags
through VBScript.
Where the byte representing a set of bit flags is x:
To set... To 0... To 1...
bit 1 x and 254 x or 1
bit 2 x and 253 x or 2
bit 3 x and 251 x or 4
bit 4 x and 247 x or 8
bit 5 x and 239 x or 16
bit 6 x and 223 x or 32
bit 7 x and 191 x or 64
bit 8 x and 127 x or 128
ex.:
22 = 00010110 binary.
Bit 4 is 0.
To set bit 4 to 1 use:
newByteNumber = 22 or 8
That returns 30, which is 00011110.
License:
You use all script code and components from JSWare at your own risk.
The components (compiled DLL and EXE files) may be used for personal or
commercial purposes. No payment or attribution is required for either use.
The components may be redistributed if they are required as support files
for scripts or software that you have written.
Also, the script code may be used freely, in part or as whole scripts,
for any purpose, personal or commercial, without payment or attribution.
I ask only that you not redistribute these scripts and components, except
as required for your direct use. Instead, please direct others to obtain copies
of JSWare scripts and components directly from www.jsware.net.
Also, none of the code here may be redistributed under another license. If a
work using code from JSWare is distributed with restrictions of any kind
the code from JSWare must be kept exempt from those restrictions.
This includes, but is not limited to, code sold for profit, code with usage restrictions
and code distributed as so-called "Open Source" with redistribution restrictions.
Joe Priestley