Marcus' Macro Scheduler Blog

The purpose of embedding a file into a Macro Scheduler script is to be able to have a script use that file on a computer that might not have the file or that the file is in an unknown location. For example a spreadsheet or database file could be embedded so that the script could work with data on a computer that does not have other access to the data. Or a custom dynamic link library (DLL) file or an executable file could be embedded to provide functionality that would not normally be found on all computers.

Though it’s not necessary to understand file construction to be able to embed files into Macro Scheduler scripts, the following discussion may help you understand what is going on in the process. This discussion may only apply to Microsoft Windows operating systems and the English keyboard.

All files are constructed from bytes. There are 256 unique 8 bit bytes sometimes referred to as octets. If you feel the need to investigate, Google the word “byte” and you will find enough information to keep you busy studying for years. ASCII (American Standard Code for Information Interchange) represents each of these 256 bytes with a unique character symbol and an integer from 0 to 255. Some of these characters are found on your keyboard. For example, if you open Notepad, then press the “A” key with your caps lock on then save the work to a file. That file will contain the byte represented in ASCII as an “A” character. The integer for ASCII character “A” is 65. The binary number, which is how the computer sees the character, is 01000001. Notice that there are 8 characters in the binary representation, that is why they are referred to as octets. To reiterate, ALL files are constructed from combinations of 256 8 bit bytes.

With a few inclusions the ASCII characters in the range from 32 through 127 are generally referred to as “text” characters. These are the characters that you can type from your keyboard. There are three notable inclusions. ASCII character number 9 is a Tab. ASCII character number 10 is a line feed and ASCII character number 13 is a carriage return. You will send ASCII characters 13 and 10, in that order, whenever you press the enter key while editing a text document.

Macro Scheduler scripts are “text” files. This means that scripts should only contain the ASCII characters in the range from 32 through 127 and the notable inclusions. Since most file types are not “text” files, they will include most or all of the 256 ASCII characters. The challenge is how to embed a non-text file within a text only Macro Scheduler script. I know of three easy answers.

In ASCII every character has a representative number. Numbers are text characters. VBScript, which is functional within Macro Scheduler scripts, can convert file bytes to ASCII numbers or ASCII numbers to file bytes.

A second way to represent bytes is by the hexidecimal equivalent of the ASCII number. Google “hexidecimal” for more information on hexidecimal (often shortened to hex). Like ASCII, hexidecimal is a text representation of each of the 256 bytes from which files are constructed. VBScript can be used to convert file bytes from hexidecimal and hexidecimal to file bytes.

A third way to represent file bytes as text is by using Base64. If you want a detailed explanation of base64 look here: http://en.wikipedia.org/wiki/Base64
Base64 represents ASCII bytes as text by grouping file bytes by threes and representing the group with a unique four character text name.

Base64 generally uses less space than ASCII or hex. ASCII uses from 1 to 3 characters to represent each character, plus you need a delimiter because you wouldn’t otherwise know where each character description began and ended. So you have a minimum of 2 characters per file byte and in most cases 4 characters per file byte. Hex is more efficient since it uses exactly 2 characters to represent each file byte and therefore no delimiter is needed. Base64 is better still because its technique only adds about 30-40% more characters than the original text and no delimiter is needed. The following example shows the efficiencies using the phrase “A quick brown fox”.

Text: A quick brown fox
17 characters

Base64: QSBxdWljayBicm93biBmb3g=
24 characters

Hex: 4120717569636B2062726F776E20666F78
34 characters

ASCII: 65 32 113 117 105 99 107 32 98 114 111 119 110 32 102 111 120
61 characters (Spaces count)

Base64 has one more huge advantage when it comes to embedding files in Macro Scheduler scripts, Base64 encoding and decoding is built into Macro Scheduler. One line of Macro Scheduler code will encode or decode a file rather than 20 lines or more to encode or decode to ASCII numbers or hex using VBScript.

Here is a process we can use to embed a base64 encoded file into a script.

The first step is to create a new script. For convenience you might call it “Base64 to clipboard”. This new script will contain the following lines.

Input>filename,Browse to Select a file for Base64 encoding
ReadFile>filename,filedata
Base64>filedata,Encode,b64data
PutClipBoard>b64data

Running this script will encode the selected file’s contents to base64 and place the base64 encoding onto the clipboard.

The next step is to get the base64 encoding into a script. Open a script in the advanced editor, place the cursor in an appropriate location and type:

Let>SomeVariable=

At the end of that line press Ctrl+C to paste the base64 encoding into the script.

We have now, encoded a file to base64 and placed the encoded file text into the script and assigned the text to a variable. The next step is to write the text back out to a file that will be used by the script. To do that we use the WriteLn> function. One very useful feature of the WriteLn> function is that by default, it adds the carriage return and line feed characters on the end of each line it writes. Unfortunately, those characters didn’t exist at the end of the original file and if we add those characters to the file we are creating, the file will be corrupt. Fortunately we can disable the default behavior by simply setting the Macro Scheduler system variable WLN_NOCRLF to 1. The next two lines will properly create our file.

Base64>SomeVariable,Decode,BinaryData
Let>WLN_NOCRLF=1
WriteLn>[Path]\[FileToCreate],wres,BinaryData

“[Path]\[FileToCreate]” is, of course, the path and file that you want the script to write for later use. “wres” is the result variable required by the WriteLn syntax. “BinaryData” is the variable that contains the Base64 decoded file information. You might want to use %TEMP_DIR% or %SCRIPT_DIR% in place of [Path] to have the file saved to the temp folder, or in the same location as the script.

The file is now available for use by the script.

Good practice dictates that we would place lines in the script to delete the file as the script is closing. And to be safe, I like to check to see if the file exists as the script is opening and if it exists, delete it there as well. So I would place the following lines at the start and at the end of a script.

IfFileExists>[Path]\\\[FileToCreate]
  DeleteFile>[Path]\[FileToCreate]
Endif

___________
Dick Lockey is M.I.S. Manager at Iowa Laser Technology, Inc., and has been using Macro Scheduler in his work since 2001. He is a regular contributor to the Macro Scheduler forums.