In the last topic, a script template has been presented which shows how to run many preprocessing and/or analysis steps across multiple subjects. If you have access to several computers in your local area network (LAN), you might want to run BrainVoyager on many workstations, i.e. each computer analyzing a subset of a large subject population. As an extension of COM, DCOM provides an elegant way to control the combined computer power of a network cluster from one single PC. Without any change in the code of the COM server (BrainVoyager) and only a small change in your clients (scripts or C++ programs), DCOM allows to execute BrainVoyager on any remote computer in your LAN on which it is installed. The following simple VBScript script is almost identical to the previously presented "simple script":
1: ' LoadDocRemote.vbs
2:
3: Set BrainVoyager = CreateObject("BrainVoyager.1", "RemoteComputer")
4: Set doc = BrainVoyager.OpenDocument("C:\cg2_recons\cg2_tal.vmr")
5: MsgBox("Document loaded !")
6: doc.SetZoomLevel(2)
7: MsgBox("Document zoomed !")
8: doc.Close
9: BrainVoyager.Exit
The only change is in the call of the CreateObject function in line 3 which now has a second argument location, which is set to "RemoteComputer". If this second argument is provided, BrainVoyager is started on the specified remote computer and not on the local one. The name of a remote computer is the same as the machine name portion of a sharename. For a network share named "\\myserver\public", the servername is "myserver". In addition, you can specify servername using DNS format or an IP address. You can also run BrainVoyager interactively on the remote machine and then invoke the System Information dialog by clicking the Help->System information... menu item. The appearing dialog shows the name of the machine under the entry "Computer name:" as shown in the figure below.
Note that the extended CreateObject function accepting the location parameter requires VBScript V5.1 or higher. Version 5.1 is the version installed with Windows 2000 and it is the version which you can install from the BrainVoyager CD for Windows NT 4.0 and Windows 98.
The tool DCOMCNFG.EXE
To change your scripts to run BrainVoyager on a remote machine is straitgthforward. Running these scripts might, however, at first lead to an error message because you probably do not have the rights to launch programs on the remote machine. Windows NT 4.0 / 2000 provide the program dcomcnfg.exe which can be used to do the necessary settings.This is mostly a matter of administration, not programming. Note that this tool modifies the registry and thus can only be run from an account with administrator privileges.
If you start dcomcnfg.exe interactively on the remote machine, the dialog shown above will appear which allows you to change default settings for security and other DCOM properties on various tabs. If you are only concerned about launching BrainVoyager on this machine from another PC, we recommend to change the settings only for BrainVoyager. Select BrainVoyager from the Application tab as shown above and then click on the Properties... button. In the appearing dialog, the most important setting to be done is to specify the users or groups that are allowed or forbidden to launch BrainVoyager. Click on the Security tab and then edit the custom launch permissions (see figure below). The default settings grant launch permission to administrators, the system user, and the interactive user. A group or individual user can be added by clicking the Add... button in the Registry Value Permissions dialog. Make sure that you are included in the people who have launch permission for BrainVoyager.
Another important setting concerns the identitiy under which BrainVoyager is started on the machine when launched by the remote client (your script or C/C++ program). Suppose a script on Paul's machine calls CreateObject to run BrainVoyager remotely on Mary's machine. Depending on the settings on Mary's machine, BrainVoyager might be launched on her machine with Paul's identity. In this case, the launched server process (BrainVoyager) is said to be "running as the activator". Any operations (for example opening files) that Paul would have been unable to perform on Mary's machine via other channels, he will be unable to accomplish via DCOM either. This makes sense from security considerations. The identity under which a process is launched remotely has, however, also another important consequence. When you launch a process as the activator, Windows NT 4.0 / 2000 creates an entirely new window station which runs completely hidden with no access to input or output devices. The standard window station which is created when a user logs on to NT and it is called the interactive window station. Only this window station gets access to the keyboard, mouse, and display device. This means that you don't see any BrainVoyager window when BrainVoyager is run as the activator. You will, however, see a "trace" of the running BrainVoyager in the Task Manager's process list. There is another way to launch a COM server, remotely, namely as a specific user or as the interactive user, the one who is currently logged in via the user interface. You can specify the identity under which the program is launched by clicking on the Identity tab in the Properties dialog which shows the following dialog:
You typically check "The interactive user" if you want to see the output of the running BrainVoyager launched by a remote client. In this case, you will be most likely logged in yourself in both machines, the local and the remote one. If you want, however, that other people can work on the machine without disturbances from a remotely controlled BrainVoyager, you should run either as a specific user (check "This user") or run as the activator (check "The launching user" ).
Since you do see nothing on the remote machine when running BrainVoyager as the activator or a specific user, your client script or program should be known to run successfully. If BrainVoyager pops up an error message, i.e. due to missing information, there is no way to continue your client code (the only "exit" then is to exit BrainVoyager). However, the output produced by your script or program are visible on the local (launching) machine which allows to get feedback about the ongoing script(s). In the example above, the MsgBox calls would pop up dialogs on the local machine thus providing feedback about the remotely running BrainVoyager. A better way to provide information about the remotely running application(s) is the Popup method of the WScript.Shell object which allows to show a dialog for a specified number of seconds only (see JScript example in "A simple script"). In a C/C++ program, the easiest way to get feedback about the remotely running BrainVoyager(s) would be to send informations to the console. It is then easily possible to run several scripts on several remote computers and to view feedback about the ongoing processes in several consoles on the local machine.
At the beginning of this topic it was shown that a small modification is sufficient to let any script run BrainVoyager on a remote computer. It is also very easy to enable remote invocation for C/C++ programs. Here the CoCreateInstance function has to be replaced with the CoCreateInstanceEx function. The following line of code is from the listing shown in the topic "A simple C++ program":
HRESULT hr = CoCreateInstance(CLSID_BrainVoyager, NULL, CLSCTX_SERVER, IID_IUnknown, reinterpret_cast<void**>(&pUnknown));
If successful, this function invokes BrainVoyager on the local machine and returns a pointer to the IUnknown interface from which a pointer to the appliction interface can be queried. To create an instance of BrainVoyager on a remote computer, the code has to be modified slightly (see also BrainVoyagerDemoClient.cpp):
COSERVERINFO si;
si.pwszName = L"RemoteComputer";
si.dwReserved1 = 0;
si.pAuthInfo = NULL;
si.dwReserved2 = 0;
MULTI_QI mqi[1];
mqi[0].pIID = &IID_IUnknown;
mqi[0].pItf = NULL;
mqi[0].hr = 0;
HRESULT hr = CoCreateInstanceEx(CLSID_BrainVoyager, NULL, CLSCTX_REMOTE_SERVER, &si, 1, mqi);
if(hr == S_OK) pUnknown = mqi[0].pItf
The first three arguments of the CoCreateInstanceEx function are identical to the CoCreateInstance function. The flag CLSCTX_SERVER has been, however, exchanged by the flag CLSCTX_REMOTE_SERVER which specifies that we want to run BrainVoyager on a remote computer. Information about the remote computer is specified with the fourth argument, a pointer to a COSERVERINFO structure. This structure has to be filled with the name of the remote computer, in our example this is "RemoteComputer". These are all the changes necessary to run the subsequent code on a remote machine. The CoCreateInstanceEx function uses, however, another method to query for an interface pointer than the CoCreateInstance function. It uses an array of structures of type MULTI_QI which allows you to call for more than one interface with one function call. Each structure contains a pointer to the ID of the requested interface, which you must set before making the call. Each structure also contains an HRESULT field (.hr) and an interface pointer which are filled on output. Since we ask only for one interface pointer (IUnknown), only one structure (mqi[0]) is filled as needed. The pointer to the mqi array is provided as the last argument of the CoCreateInstanceEx function. The fifth argument is set to the number of queried interfaces, i.e. "1" in our example. If the call to CoCreateInstanceEx is successful, we can retrieve the pUnknown pointer from the pItf field of the mqi[0] structure. From this point we can proceed exactly in the same way as in the example "A simple C++ program". Note, however, that your C++ code runs on the local (launching) machine. If you load any files for processing in you code, be aware that this might require network access. Since fMRI data analysis has to deal with large data sets, you should try to avoid file operations across the network unless you have a very fast one (at least a 100 MBit net). Generally it is recommended to first distribute the data of several subjects across the local hard disks of your machines and then to control several remote instances of BrainVoyager from one machine to work with data sets local to the respective machine. For multi-subject GLM analysis, you might want to copy (interactively or via a script) the preprocessed VTC files from the different computers into a folder of your most powerful machine.