=== === FaCE (Front-end for ACE CE) === === Object Computing, Inc. === St. Louis, Missouri === Copyright (C) 2002. All rights reserved. === === V1.01, March 30th, 2002 === == What's FaCE? FaCE is a simple front-end framework for testing and debugging non-Windows CE applications on the Pocket PC 2002 platform. Originally, FaCE was developed to test ACE and TAO components internally in Object Computing, Inc. However, since it has shown dramatic increase of productivity in a lot shorter amount of time, it has been prepared as a package for all programmers who want to test and run existing codes (non-WinCE native codes) on Pocket PC 2002 and WinCE 3.0. The features of FaCE are: 1. command line parameter support 2. command line history support (never type in same command line again) 3. output displayed on the windows screen 4. output to file (with append and overwrite support) 5. does not use MFC 6. almost no modification to existing user code 7. easy to enable and disable after install * Default project files only contain Pocket PC 2002 platform configuration. A new configuration can be added for other WinCE 3.0 platform from eVC. == Package Contents Files contained in FaCE package are: Main Framework Files for both ACE users and non-ACE users - ACE_Racer.bmp - FaCE.h & cpp - FaCE.ico - FaCE.rc - newres.h - resource.h - TAO.bmp ACE entry point definition file - FaCE_OS.h Additional Framework files for non-ACE users - CE_ARGV.h & cpp - CE_Screen_Output.h & cpp Files for loading skeleton FaCE from eVC - FaCE.vcp & vcw : FaCE Project files for ACE users - FaCENOACE.vcp & vcw : FaCE Project files for non-ACE users - Main.cpp : almost empty entry point function Misc. Files - ACE.ico : a bonus icon of ACE logo - License.txt : license and warranty information - ReadMe.txt : this document == Requirement - Microsoft(C) eMbedded Visual Studio/C++ (eVC) 3.0 - Pocket PC 2002 SDK ** For ACE-users only: - ACE+TAO installed and configured for WinCE build only for ACE-users - ace and ace_os libraries built for WinCE and loaded on machine == Important Note It has been reported that certain Pocket PC 2002 machines with ARM processor can be totally dead and will not even respond to the hard reset. While the real cause of this problem is unknown, HP has released a patch for this problem. We have tested it, and it seems working fine on our machine (HP Jornada 568), which is our 5th machine that has been running fine for the longest time. As this has been identified by hardware manufacturer and can be fixed as HP did, Object Computing, Inc. (OCI) or any member of ACE+TAO community cannot be responsible for this problem. If this problem happens during debugging, contact your hardware manufacturer for fix or replacement. It has found that almost all Pocket PC 2002 machines regardless of manufacturers have same problem. Also, Phil Mesnier at OCI has found that virtual function calls under certain situation can cause a problem that randomly changes parameter and pointer values over function calls. This is due to the incorrect instructions generated by eVC for ARM processor. So far, no solution or patch has been released by compiler vendor, although vendor is aware of this problem. Since Pocket PC 2002 is based on WinCE 3.0, ACE+TAO as well as FaCE should be able to run on any WinCE 3.0 platform by adding a new configuraion with minimal change. == Installation & Setup 1. Create a subdirectory named 'FaCE' (or anything in your taste) under your current project directory. 2. Copy FaCE_OS.h to the ACE_ROOT/ace directory, and add following line at the end of your ACE_ROOT/ace/config.h file: #include "FaCE_OS.h" 3. Copy main framework files listed above and add them into "your" project (NOT FaCE.vcw/vcp). For non-ACE users, copy additional framework files for non-ACE users in addition to the main framework files. It would be a good idea to create a new folder in your project and put all FaCE files into it. This way, it will be easy to disable FaCE by setting the folder excluded from the build on the folder property option. ** IMPORTANT! ** FaCE does NOT use MFC. Thus, if your project is already set for 'Not using MFC', then do not change the setting. * Note: Make sure those files are not shared by multiple executables. Each project must have its own copy of those files. It is a good idea to create a separate folder on your project and put FaCE related files into that folder. In that case, if you want to disable FaCE and run by using normal 'main', then you can simply set the whole FaCE folder excluded from build in the project setting menu. 4. Change your 'main()' function part similar to the following example. #ifdef ACE_HAS_WINCE #include "FaCE/FaCE.h" // use the name of subdirectory you created int FaCE_MAIN (int argc, ACE_TCHAR *argv[]) #else int ACE_TMAIN (int argc, ACE_TCHAR *argv[]) // ACE normal entry point #endif Change the directory name for "FaCE/FaCE.h" if necessary. For non-ACE users, use 'UNDER_CE' instead of 'ACE_HAS_WINCE'. == Possible Additional Change Above change will be the only change if your program compiles and links fine under eVC. It does not mean that your program is WinCE-ready but just means that your program does not include the libraries that are not supported by WinCE, such as iostream. For ACE users, good examples will be the ACE test programs under $ACE_ROOT/test. For non-ACE users, I highly recommend to create a project for WinCE first if it has not already been done and write your code using wmain. Try compile and link your program without FaCE to check your program does not include any libraries not supported by WinCE. FaCE supports text output by aliasing 'cout' in FaCE.h; however, it is NOT a real iostream but an alias for CE_Screen_Output class. You may need to use '#ifdef UNDER_CE' for your iostream includes, if you want to share the code among different platforms. Also, it is important to match the parameter types for 'wmain' function. For WinCE, it MUST be in the format of: int FaCE_MAIN (int, wchar_t**) and you can leave your original wmain type as it was for non-CE platform definition. 5. Go to 'ResourceView' or double-click on the 'FaCE.rc'. Open 'String Table -> String Table' from the resource browse view, and change the string value (caption) defined for 'IDS_APP_TITLE' from 'FaCE' to your program name. This will help identifying multiple FaCE-fied applications when you brose them through system memory -> running programs in case of crash. 6. That's it! ** Optionally, you can personalize the icons defined for FaCE for your own. To do this easily, load "FaCE.vcw" (requires ACE library) or "FaCENOACE.vcw" from eVC. Also, FaCENOACE.vcw can be used as 'hello world'-type starting frame-work for non-WinCE programmers. ** Non-ACE users may see the warning messages saying, "Could not find the file xxx", for ace.h, Log_Msg.h, OS.h, and CE_Screen_Output.h. This is due to the eVC's not-so-perfect precompilation file checking and totally harmless. ** Later if you don't want to use FaCE anymore, simply restore your original main function and remove FaCE files from your project (or exclude FaCE files from build). ACE library does not have to be rebuilt as FaCE_OS.h only contains macro. == Running FaCE 1. Command line option User can specify the command line option for the program by using 'Settings -> Command Line' from the FaCE menu. FaCE will automatically save all user-entered command line parameters as a ASCII format file named 'Parameters.txt' in the root directory of WinCE device/emulator. User can edit and change by openning this file from any text editor and save as a ASCII text file with DOS standard CR/LF combo. This will greatly save time especially when you are working on the Pocket PC machine that does not have keyboard. Remember NOT to convert file format to Unicode; it must be standard DOS ASCII text file. 2. Output Saving You can save output to file by selecting 'Tools -> Save To File'. By default, FaCE will not create/save any file. Also, any output received before setting up this feature will not be saved. If the file with specified name exists, FaCE will ask whether you want to append to the end of file or erase and overwrite. All output files will be saved in the root directory of the system. 3. Running Your Program 'Setting -> Run' will execute your program. Two tags, 'START' and 'END' indicate the beginning and end of your code. For ACE users, any log message sent to ACE message log (ACE_DEBUG, for example) will be displayed on the screen. Also, if you have setup to save to file, the same contents will be saved to the file as well. Note that the output will NOT have ACE internal tags (i.e. Dec 04 14:51:12.000 2001@LM_DEBUG@) because FaCE uses callback message function, and ACE does not pass those tags along with the output message. For non-ACE users, you can declare your own local copy of CE_Screen_Output object. For example, you can declare CE_Screen_Output object in your cpp file like: CE_Screen_Output cout; and use it like, int a = 100; wchar_t* strTemp = L"Hello, world!"; cout << L"String : " << strTemp << L"a = " << a << endl; Remember, CE_Screen_Output is just a simple text output function and does not have the full capabilities of iostream, which is not available for WinCE 3.0. 4. In case of crash If you have started your code, but the code crashes, which can be easily identified by looking for the 'END' tag, then you can use Windows CE's memory program to kill the process (Start -> Settings -> System tag -> Memory -> Running Programs tag). If you have changed IDS_APP_TITLE in the resource viewer, then you will see the name you have specified; otherwise, FaCE will be listed. You can select the name and stop the process by clicking 'Stop' button. Sometimes, you may need to reset the machine if you cannot access memory program. == Note - This FaCE framework does not use any MFC; it only uses general Win32 API, thus, your project setting does not have to be changed. - FaCE is for the 'legacy' Unix/DOS style console applications that do not use any Win32 and MFC for Windows OS. Programs that are already using native Windows/WinCE API's will not need FaCE framework. - If you run your application from FaCE (Settings -> Run), 'START' and 'END' will appear at the beginning and end of output messages from your application. If you see 'END' lable after execution, you can run your program again without exit and start up FaCE again. - Make sure to terminate FaCE by selecting 'Settings -> Exit'. It will completely terminate FaCE session; Clicking on the 'X' button at the top-left corner of the screen will not, just like most WinCE programs. - FaCE_MAIN is only for the WinCE port of ACE, ensuring proper windows system message filtering along with proper registraion so that user can see the process from memory setting and task switcher applications. - ACE and FaCE do not overrides native WinMain. If you are developing for Windows OS only, your WinMain should be just safe from any overrides. In this case, of course, you don't need to use FaCE package. == Question or Comment If you have question and/or comment specific to the FaCE, please contact Si Park at spark@ociweb.com or Justin Michel at michel_j@ociweb.com. For general ACE+TAO support, please refer to comp.soft-sys.ace or contact Object Computing, Inc. at http://www.ociweb.com.