"To talk to a Mule you have to Bray..."

The Bray DLL

This information is provided for programmers who intend to use the Bray DLL (Dynamic Linked Library) to create custom Bray applications and who need to know exactly how it operates. It is not necessary to understand any of these details in order to use the Bray Scripting Language.

For simplicity we often use the term 'Bray DLL'. In reality the Bray DLL is a file called mulebray.dll. We may use either term to describe the same file.

The Bray DLL has been named so it is unlikely to coincide with any other DLL on your system. If it does then you will have to be careful about where each is located. Refer to the section on the Physical Location of DLLs.

The Bray DLL runs in the Win32 environment (Windows 95, 98, ME, Windows NT, 2000, and XP). It should also be compatible with the Windows Vista operating system but as yet our experience with this is limited (any feedback on operations with Vista is welcome).

DLLs often contain many different Functions and Subroutines to carry out a number of different tasks. The Bray DLL can carry out a number of different tasks too but we believe 'simple is good' so the Bray DLL contains just one single Function. All Bray operations are channeled through the braymain Function. The advantage is considerable. You only need to get your code to talk to a single external Function. Only a single Declaration is needed and a simple calling routine can be written to handle ALL the Bray operations. Debugging is simplified too - just plug in a temporary MessageBox or Print statement to see what is being sent and what is returned. Easy.

Our code examples show how the DLL is called using some of the most popular programming languages. The example code can be used to form the basis of a complete computer control application. By using the Bray DLL to communicate with The Mule you control everything with a simple scripting sub language. In particular you should notice that additional code or other DLLs to control the COMs Port hardware are not needed.

Our popular language examples are not claimed to be exhaustive or even elegant - things can always be improved. Nevertheless they have all been tested and found to work correctly. Programmers working with other languages are likely to be familiar with at least one of these and should be able to convert the syntax to their own needs. Make contact if you have any difficulty or if we got something wrong (We are not expert in all languages). Example code in other languages, helpful tips, ideas or comments are all welcome.

Popular Language Examples

• Visual C# with Microsoft .NET Framework.
• Visual Basic with Microsoft .NET Framework.
• Visual Basic v4 v5 v6
• Delphi
• Power Basic
• Thin Basic

Further Bray DLL examples

General information about DLLs

Declarations

When you call a DLL Function or Subroutine in any language the compiler needs to know its location. Otherwise it will generate an error. It may, for example, say the Function is 'not defined' or similar. The code inside the DLL is outside the normal scope of your program so to avoid an error you need to tell it where to find the particular Function or Subroutine. This is done by using a Declaration. The precise detail and syntax for the Declaration differs between languages but the concept is the same for all.

Sometimes the Declaration provides the compiler with more information about the Function. For example when using .NET you can tell the compiler how to handle the parameters and the return value using the Marshal keyword. You can see examples of declarations in our Popular Language Examples.

Physical location of the DLL

If you do not use the .dll filename suffix in your Declaration Windows looks for the file in each of these locations in turn...

1. The .exe file directory.
2. The current directory.
3. The %SystemRoot%\SYSTEM32 directory.
4. The %SystemRoot% directory.
5. The directories in your Path.

If you do add the .dll file name Windows first looks in the registry to see if a special location has been registered for this DLL.

For most purposes we recommend locating the DLL in the same folder as the calling .exe because Windows looks there first and there are no path issues. If you put the DLL in a different location you may need to include the full path to the DLL in the Function Declaration.

Function details

A DLL contains Functions or Subroutines which can be called in an identical way to regular Functions or Subroutines. When a DLL makes one of these routines available to an outside program it is said to Export it.

A DLL can be written in one language and used by another because the interface between them is built to a common standard. Unfortunately there is more than one standard in use. The Bray DLL uses the "Standard Calling Convention". Languages often support this as the default (For example Visual Basic). Some languages like C/C++ or Pascal may use a different default method but all are capable of using the "Standard Calling Convention". The Declaration is often used to tell the compiler which method to use. If you are unsure how your preferred language handles calls to DLLs you should check the language documentation for the details. Our popular language examples may be used as a guide.

The Bray DLL in detail

The Bray DLL is a file called mulebray.dll It exports a Function named braymain. All operations are routed through braymain.

The braymain function in detail

The braymain function takes two parameters and returns a string.

First parameter: braycmd

The first parameter is a number, it represents a particular command. In the documentation and example code we use the term braycmd to describe this parameter.

The braycmd parameter is an integer of 32 bits (4 bytes). It does not matter if it is a signed or unsigned value because only low positive values are ever used. Be aware Microsoft changed the size of a number of Variable Types with the introduction of the .NET Framework.

If you use an undefined value for braycmd the string returned from the function will contain an error message.

Second parameter: braystring

The second parameter is a string. In the documentation and example code we use the term braystring to describe this parameter.

Some braymain operations do not really need a string parameter. Nevertheless you must always supply a second parameter when you call the function otherwise it will fail. In these cases you can pass a dummy string, the string content will be ignored by the function. It is even possible to pass a null string but there is danger here! If you declare the string but forget to give it a null value then the string pointer is likely to point to an invalid area of memory and the whole system will abort with a General Protection Fault. Failing to initialise a string is an easy mistake to make and for this reason we recommend you adopt a dummy string approach.

In reality the second parameter is not the string itself but a pointer to the string. The pointer is a 32 bit (4 byte) address indicating where the start of the string resides in memory. The DLL reads the pointer address and picks up the first character of the string at that address. It then increments the pointer and picks up the next string character at the new address. This process is repeated until it finds a memory location holding a byte of value zero. This indicates the end of the string.

Computers can use a number of different ways to represent strings. The string type just described is called an ASCIIZ string. We use this method because it is compatible with a wide range of systems and languages. Windows API calls often use this string type. Microsoft refers to it as a LPStr string.

Like Windows API calls the Bray DLL uses traditional ANSI (ASCII) strings where each character is a single byte. Many computer languages use Unicode strings by default where each character is two bytes long. Examples of this are Visual Basic and C#. With these languages it is necessary to convert between the two. Refer to our Popular Language Examples to see how this is done.

Data returned from the braymain function

Data returned from the function is always in the form of a string. In the documentation and example code we use the term brayretstring to describe it.

Just like the second parameter described above the returned value is not really a string but a 32 bit (4 byte) pointer to the string. The returned string is retrieved from memory in exactly the way described for the second parameter. In practice the means of doing this is often built into the language itself and the string is retrieved automatically. Refer to our Popular Language Examples to see how this is done.

The Bray DLL Reference

Tabulated summary of the braymain function

braycmd	braystring	Returned string	Purpose of the braymain command
0   getId	null or dummy	typically: "v1.5.32"	Get the DLL identification string
1   doBrayLine	Line of Bray script	Always "OK"	Parse and execute this line of Bray Script
2   getAstream	null or dummy	A:stream	Get the current Action Stream
3   getEstream	null or dummy	E:stream	Get the current Error Stream
4   getCstream	null or dummy	C:stream	Get the current Commentary Stream
5   getSstream	null or dummy	S:stream	Get the current Source Stream
6   putAstream	Stream text	Always "OK"	Inject text into the A:stream
7   putEstream	Stream text	Always "OK"	Inject text into the E:stream
8   putCstream	Stream text	Always "OK"	Inject text into the C:stream
9   putSstream	Stream text	Always "OK"	Inject text into the S:stream
10  initBray	null or dummy	Always "OK"	Prepare for a new Bray Script
11  endBray	null or dummy	Always "OK"	The current Bray Script is finished, release resources
12  getErrCount	null or dummy	Error count	Return the error count since the current script started
20  useCom	example: "COM1"	"OK" or Error Message	Use this COM port for future Channel 0 operations
General notes on parameters and returned values
Maximum buffer size for strings is 512 characters. One byte is reserved for a zero byte terminator so maximum length string you can use is 511 characters. You should not pass a string longer than this. Parameters are not case sensitive. For example the COM port parameter can be sent COM1 or com1 or Com1. Similarly you should not rely on returned string data having a particular case. Words like 'OK' or 'Error' are currently returned consistently but this may change in the future. Do not rely on particular formats or capitalisation for returned strings or Stream Data Strings except where specifically defined. Formats for returned strings are defined in the particular section dealing with each DLL command. Formats for Stream data are defined in the section on Streams and Channels in the Bray Script section.