Allocates a memory buffer of the desired size.
BinaryAlloc( size )
(i) size: size in bytes of the desired memory buffer.
(i) handle: returns a handle to a buffer of the indicated size.
When operations on a particular buffer are complete, it should be released with the BinaryFree function.
Use this function to allocate a memory buffer for Binary operations. Up to 128 separate buffers may be allocated concurrently. Nearly any reasonably sized buffer may be allocated, assuming sufficient system memory and page file space is available. While users of 32-bit Windows versions may allocate, theoretically, over 2 billion bytes, the real, practical bounds are not established and will vary with system configuration.
Notes:
32-bit WinBatch and 32-bit Compiled scripts
On 32-bit x86 systems and WOW64 x64 subsystems process's are limited to 4GBs of addressable virtual memory, of which 2GB, or optionally 3GB, can be addressed within process-private virtual memory. Now, within that range, you have the program's main EXE file and *EVERY* DLL that it has loaded, all consuming some of that virtual memory address space. On top of that, you have other heap-based memory allocations that the EXE and DLLs may make as their code is executed, and all that heap memory occupies portions of the process-private virtual address space. Then, all of the pages of virtual memory that the process has mapped have to either reside in physical memory, or have to be paged out to the paging file. The memory manager in the kernel takes care of these paging activities automatically. Given those assumptions, the single largest contiguous block of virtual address space that can be allocated will be limited, in practice to approximately 1.2GB to 1.5GB in size, and that's provided that you have enough page file space and enough physical memory. When you count all of the other "overhead" that fragments your virtual memory address space, that upper limit can drop down significantly lower, which is where you see most binary buffer allocations in WinBatch having a maximum size of approximately 800MB. This type of limitation isn't unique to WinBatch and its binary buffers. This limitation applies to *ANY* program that attempts to make such huge memory allocation requests. Available process memory is very dynamic and any information returned could very easily be rendered inaccurate before it was ever used to allocate a buffer. There is currently no way to determine the max allocation size other than attempting to allocate and then capture the 1126 error.
64-bit WinBatch and 64-bit Compiled scripts
64-bit WinBatch and 64-bit compile WIL scripts on 64-bit x64 systems can allocate buffers much larger than the approximate 800MB mentioned above because the 64-bit versions of WinBatch and the Compiler are large address aware. The max binary buffer size is determined by available virtual memory. Available virtual memory is determined in part by the amount of physical memory, page file size limit, and the requirements of other processes executing on the system. Not all computer systems have the same amount of physical memory nor executing processes so the maximum binary buffer size can very greatly from system to system at any given time. Very large binary buffers may also have a negative impact on script performance depending on the task. Keep this in mind when using very large binary buffers with 64-bit WinBatch and Compiled scripts.
; This example edits the Config.sys file
; by adding a new line to the bottom of the file.
;
fs=FileSize("C:\CONFIG.SYS")
; Allocate a buffer the size of your file + 100 bytes.
binbuf = BinaryAlloc(fs+100)
If binbuf == 0
Message("Error", "BinaryAlloc Failed")
Else
; Read the file into the buffer.
BinaryRead(binbuf, "C:\CONFIG.SYS")
; Append a line to the end of the file in buffer.
BinaryPokeStr(binbuf, fs, "DEVICE=C:\FLOOGLE.SYS%@crlf%")
; Write modified file back to the file from the buffer.
BinaryWrite(binbuf, "C:\CONFIG.SYS")
binbuf=BinaryFree(binbuf)
EndIf
Message("BinaryAlloc", "Done.")
Binary Operations, BinaryCopy, BinaryFree, BinaryRead, DllCall, IntControl 42