Looking under the hood of the .FCW file format

First a warning – The .FCW file format is BINARY!  If you do not feel comfortable playing with bits and bytes, this may not be for you.  But if you do enjoy this type of challenge, the .FCW file format is one of the best ways to output to CC3.
Imagine you have a random maze generator and you want to output it to CC3.  You could export a script.  It would redraw your maze one line at a time.  
But there are also some problems with scripts:

• You have to run them.  This may sound obvious but consider that you have to either know the text command to open and run a script file, or you need to know where in the menu system it is.
  
• Scripts are slow.  CC3 will have to take your script and run it line-by-line.  Its as if you had set down and typed in the commands directly into CC3.
  
• Scripts are not exactly fragile, but they are not very robust either.  And, if your script fails, your users are the ones that are going to get frustrated.

Where as if you exported a .FCW file, simply the action of opening the file is all that is needed. So … if you are still with me, here we go!
One last twist – the .FCW file could be compressed.
The .FCW file format is made up of many different “Blocks” of data.  The first 4 bytes of each block (except for the first block) contains the number of bytes that the following block contains.  It starts with the FileID block.  The FileID block is the only block that is guaranteed to be uncompressed.  This 128 byte block contains quite a bit of general info on the file.  It identifies what type of file it is to other programs, and the version and sub-version number of the file format is was built with.  Last, but not least, it informs the reader that bytes after byte 128 are compressed or not.  (To save an uncompressed file, after you have clicked "Save As ...", you will be presented with the save file dialog.  If you click on the options button, you will be presented with a small dialog box.  Uncheck the "File Compression" option)
For this first blog post on the .FCW file format, I will show you how to read a binary file into a byte array and how to display it, byte-by-byte in a textbox similar to all the binary editors display it.  Being able to look inside a binary file will come in very handy in the future.  Last but not least I will show you FILEID object.

Code Snippet – How to read an entire file into a byte array

1. public byte[] ConvertFileToByteArray(string fileName)
   
2. {
   
3.     byte[] buffer;
   
4. 
   
5.     using (var fileStream = new FileStream(fileName, FileMode.Open, FileAccess.Read))
   
6.     {
   
7.         using (var binaryReader = new BinaryReader(fileStream))
   
8.         {
   
9.             buffer = binaryReader.ReadBytes((int)new FileInfo(fileName).Length);
   
10. 
    
11.             binaryReader.Close();
    
12.         }
    
13. 
    
14.         fileStream.Close();
    
15.     }
    
16. 
    
17.     return buffer;
    
18. }

Once the file is read into a byte array, I pull the first 128 bytes out of the file byte array, using an extension method to Arrays to create sub-arrays.

Code Snippet – SubArray extension method

1. public static class Extensions
   
2. {
   
3.     public static T[] SubArray<T>(this T[] data, int index, int length)
   
4.     {
   
5.         var result = new T[length];
   
6. 
   
7.         Array.Copy(data, index, result, 0, length);
   
8. 
   
9.         return result;
   
10.     }
    
11. }

Then I feed the sub-array to my FILEID object.  This object converts the bytes into the fields of the FILEID object.  We can then check the Compressed property.  If the file is compressed, the rest of the data is meaningless, so if the file is compressed, I set the background color of the textbox to a Rose color.

Code Snippet

1. using System;
   
2. using System.Text;
   
3. 
   
4. namespace DisplayBinaryFile
   
5. {
   
6.     public class FILEID
   
7.     {
   
8.         #region Fields
   
9.         public char[] ProgId = new char[26];
   
10.         public char[] VerText = new char[4];
    
11.         public char[] VerTextS = new char[14];
    
12.         public byte[] DosChars = new byte[3];
    
13.         public byte DBVer;
    
14.         public bool Compressed;
    
15.         public byte[] Filler = new byte[78];
    
16.         public byte EndFileID;
    
17.         #endregion
    
18. 
    
19.         public int Length { get; set; }
    
20. 
    
21.         public FILEID(byte[] buffer)
    
22.         {
    
23.             ProgId = Encoding.ASCII.GetChars(buffer.SubArray(0, 26));
    
24.             VerText = Encoding.ASCII.GetChars(buffer.SubArray(26, 4));
    
25.             VerTextS = Encoding.ASCII.GetChars(buffer.SubArray(30, 14));
    
26.             DosChars = buffer.SubArray(44, 3);
    
27.             DBVer = buffer.SubArray(47, 1)[0];
    
28.             Compressed = BitConverter.ToBoolean(buffer.SubArray(48, 1), 0);
    
29.             Filler = buffer.SubArray(49, 78);
    
30.             EndFileID = buffer.SubArray(127, 1)[0];
    
31. 
    
32.             Length = 128;
    
33.         }
    
34. 
    
35.         public byte[] GetBytes()
    
36.         {
    
37.             var returnValue = new byte[Length];
    
38. 
    
39.             Array.Copy(Encoding.ASCII.GetBytes(ProgId), 0, returnValue, 0, 26);
    
40.             Array.Copy(Encoding.ASCII.GetBytes(VerText), 0, returnValue, 26, 4);
    
41.             Array.Copy(Encoding.ASCII.GetBytes(VerTextS), 0, returnValue, 30, 14);
    
42.             Array.Copy(DosChars, 0, returnValue, 44, 3);
    
43.             Array.Copy(BitConverter.GetBytes(DBVer), 0, returnValue, 47, 1);
    
44.             Array.Copy(BitConverter.GetBytes(Compressed), 0, returnValue, 48, 1);
    
45.             Array.Copy(Filler, 0, returnValue, 49, 78);
    
46.             Array.Copy(BitConverter.GetBytes(EndFileID), 0, returnValue, 127, 1);
    
47. 
    
48.             return returnValue;
    
49.         }
    
50.     }
    
51. }

Here is a link to the entire Visual Studio 2010 project

A more modern example of Intercom

In the last post, I introduced Intercom with an old example I wrote using VB6.  This post will be a much more modern example using C#.

I’ve also included a “Round Trip” example where the command is initiated via CC3.  By adding this small macro, you now have a command that draws a diamond on the screen.

Code Snippet

1. MACRO DIAMOND
2. GP TEMP ^DCenter:
3. SENDM 2 TEMP
4. ENDM

What this does is as the user to get a point (GP) and then send it via Intercom to the c# application.

Once it gets to the c# code, it takes the string from CC3 (all data sent from CC3 via Intercom is in strings), splits it on the comma and converts the two substrings into doubles.  Then it creates a command string and passes it back to CC3.

Code Snippet

1. var strNumbers = System.Text.Encoding.ASCII.GetString(bytMsg).Split(',');
2. var x = double.Parse(strNumbers[0]);
3. var y = double.Parse(strNumbers[1]);
4.  
5. var strDiamond = "LINE \n" +
6.                     (x - 100) + "," + y + " \n" +
7.                     x + "," + (y - 100) + " \n" +
8.                     (x + 100) + "," + y + " \n" +
9.                     x + "," + (y + 100) + " \n" +
10.                     (x - 100) + "," + y + " \n\n" +
11.                     "ENDM";
12.  
13. icSendMsg(20, strDiamond);

Here is a link to the C# portion

An introduction to Intercom

Intercom was originally written in C code for inclusion in C programs. For C programmers this was quite acceptable. Unfortunately the vast majority of non-professional programmers do not work in C, so something needed to be done.

I've taken the original C code and placed it into a plain C DLL. Most higher level languages like C#, VB.Net, VB6 and Delphi can utilize the subroutines in a C DLL. When I originally wrote about Intercom (way back in 1999 – You can tell, because the title of the example application reads: “Intercom with CC2), I was a professional Visual Basic programmer I used VB6 as my language of choice in the following example.

First, what is intercom? Intercom is code that creates a memory-mapped file that both CC3 and your program can use. What this means is that in memory a chuck of space is set aside, half for you and half for CC3. You can only read your half and you can only write to CC3's half. CC3 on the other hand can do just the opposite.

Whenever a new message is written, a 'New mail flag' is raised. CC3 looks for a raised flag automatically. Your program needs to check periodically.

Second, what is it that is sent back and forth between CC3 and a program? Intercom sends an integer and a string back and forth. To CC3 these have very strict meanings. The integer is part of the name of the macro it will now run and the string is used as input data.

If you sent CC3 via intercom the number 123 then the macro CC3 will attempt to run in named RCV123 and the string will now reside inside the variable RCVDATA.

CC3 ships with an important macro: RCV20.  If you run the exe in the VBIntercom zip file (Intercom.exe) and enter 20 and LINE 0,0 1000,1000 you will see.

See? The macro RCV20 contains nothing but RCVDATA in it. This macro will run whatever text is sent to it, so this means that the calling program can dynamically build and run scripts/control CC3.

To connect to the DDL, you need to use Declare Statements. See the code in the VB6 form for the exact syntax, later l will post C# examples.

Here is a link to the original C code for Intercom.

Here is a link to the Intercom code wrapped into a plain C DLL plus the old VB6 example.