home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cscout.zip / EXE / CSCTREF.INF (.txt) < prev    next >
OS/2 Help File  |  1995-06-12  |  25KB  |  788 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
  3.  
  4. Welcome to C-Scout. 
  5.  
  6. This tool has been specially developed to help developers who are writing 
  7. complex applications for OS/2. 
  8.  
  9. The authors of C-Scout have been using a similar tool internally for their own 
  10. development work and have now released version 2 of C-Scout. Many improvements 
  11. have been added to this version in order to improve its usability and 
  12. performance. 
  13.  
  14. The tool is particularly suited for debugging and maintaining multi-process 
  15. communications systems or complex PM programs where conventional tools or 
  16. tracing can not be used because of the way they distort the system behaviour or 
  17. because no other tools are available. C-Scout is however just as much at home 
  18. in a single-threaded VIO program. 
  19.  
  20. About a priori 
  21.  
  22. Supported Environments 
  23.  
  24.  
  25. ΓòÉΓòÉΓòÉ 1.1. About a priori ΓòÉΓòÉΓòÉ
  26.  
  27. a priori computer solutions GmbH is a software house situated in Frankfurt, 
  28. Germany. It develops software products and bespoke software for several 
  29. international companies situated throughout Germany. The main platforms it 
  30. supports are OS/2, UNIX and Windows. a priori can be contacted at: 
  31.  
  32.         a priori computer solutions GmbH 
  33.         M╨ænchener Str. 13 
  34.         60329 Frankfurt 
  35.         Tel.  +49-69-239462 
  36.         Fax.  +49-69-236426 
  37.         EMAIL 100137.2315@compuserve.com 
  38.  
  39.  
  40. ΓòÉΓòÉΓòÉ 1.2. Improvements ΓòÉΓòÉΓòÉ
  41.  
  42. Many improvements have been added to this version. They include: 
  43.  
  44.     o Presentation Manager console user interface. 
  45.  
  46.     o Ability to trace multiple processes in one view. 
  47.  
  48.     o Ability to trace a DLL. 
  49.  
  50.     o Ability to trace several views simultaneously. 
  51.  
  52.     o Support for disjoint trace levels. 
  53.  
  54.     o No need to initialise tracing in the program to be traced. 
  55.  
  56.     o Added synchronous tracing capability. 
  57.  
  58.     o Added ability to register a user-written function to be called in the 
  59.       case of an error detected by the TX macro. 
  60.  
  61.     o Improved error information. 
  62.  
  63.     o Added exception handling to datt.dll. 
  64.  
  65.     o Presentation Manager dialog box for critical errors. 
  66.  
  67.     o Ability to display active processes known to C-Scout. 
  68.  
  69.     o Improved support for various compilers. 
  70.  
  71.     o Several bug fixes and minor improvements. 
  72.  
  73.  
  74. ΓòÉΓòÉΓòÉ 1.3. Supported Environments ΓòÉΓòÉΓòÉ
  75.  
  76. The following compilers have been tested with C-Scout: 
  77.  
  78.     o IBM CSet/2 V1.0 and higher. 
  79.  
  80.     o IBM C/C++ Tools V2.0 and higher. 
  81.  
  82.     o WATCOM C/C++ V10. 
  83.  
  84.     o Borland C++ for OS/2 V1.0 and higher. 
  85.  
  86.  The following restrictions apply when not using the IBM C/C++ compilers: 
  87.  
  88.  o When tracing, the name of the function is not available because only C-SET 
  89.    provides this information with a compiler macro. 
  90.  
  91.  o The C library error information in text format, which is displayed when the 
  92.    TX macro has detected an error, is not available. This is because C-Scout 
  93.    has been written using C-SET and therefore can not access the C libraries 
  94.    used by the other compilers. 
  95.  
  96.  No other restrictions are known. 
  97.  
  98.  Operating System 
  99.  
  100.  Known Restrictions 
  101.  
  102.  
  103. ΓòÉΓòÉΓòÉ 1.3.1. Operating System ΓòÉΓòÉΓòÉ
  104.  
  105. In order to run C-Scout, OS/2 Version 2.1 or higher is required. 
  106.  
  107.  
  108. ΓòÉΓòÉΓòÉ 1.3.2. Known Restrictions ΓòÉΓòÉΓòÉ
  109.  
  110. The following restrictions are known: 
  111.  
  112.  o a maximum of 32 views can be active at any one time. The number of views 
  113.    that can be defined is only limited by the resources available. Of these, 32 
  114.    can be in active trace mode. 
  115.  
  116.  o a maximum length of 2000 bytes is available to the Tracef function. This 
  117.    limits the size of the formatted buffer to 2000 bytes. 
  118.  
  119.  o the trace levels must be between 0 and 999999. 
  120.  
  121.  o a problem occurs when trying to use the trace facility in an exception 
  122.    handler when the synchronous option has been requested. This only occurs 
  123.    when PMScout is being used. The problem is under examination. 
  124.  
  125.  
  126. ΓòÉΓòÉΓòÉ 2. Installation ΓòÉΓòÉΓòÉ
  127.  
  128. C-Scout is installed by simply executing the install.exe program provided on 
  129. the diskette. This program uses the Software Installer from IBM to install the 
  130. C-Scout product in the directories the user specifies. The installer will 
  131. update the machine's Config.Sys with the necessary changes so that a re-boot is 
  132. required for the changes to become effective. 
  133.  
  134. Installation with a response file or using CID is also possible. Examples are 
  135. provided with the product. 
  136.  
  137.  
  138. ΓòÉΓòÉΓòÉ 3. License Agreement ΓòÉΓòÉΓòÉ
  139.  
  140. A license is required for each machine which uses any or all of the following 
  141. files: 
  142.  
  143.     PMSCOUT.EXE         PM Console. 
  144.     DATT.LIB            library used for linking the trace tool. 
  145.     DATT.H              include file required to compile a program. 
  146.  
  147.  A license is not required for the other files which are provided. In 
  148.  particular the production environment console - VIOSCOUT.EXE and the DLLs can 
  149.  be freely distributed. 
  150.  
  151.  The read.me contains information about the license agreement made when you use 
  152.  C-Scout. Please read this file if you have not already done so. If you do not 
  153.  agree with these terms please return all copies of C-Scout immediately. 
  154.  
  155.  
  156. ΓòÉΓòÉΓòÉ 4. How to use C-Scout ΓòÉΓòÉΓòÉ
  157.  
  158. In order to use the features of C-Scout, the developers are required to code 
  159. the API calls in their program and compile and link it together with the 
  160. supplied library and include file. At run-time, the DLLs will be loaded and 
  161. provide the execution environment for the tracing functions. 
  162.  
  163. Exactly what should be traced at runtime is specified by using a console. There 
  164. are 2 consoles available for C-Scout: 
  165.  
  166.  PMSCOUT.EXE         a PM Console 
  167.  VIOSCOUT.EXE        a VIO Console 
  168.  
  169.  Both consoles use the concept of a view for tracing. 
  170.  
  171.  A view is the object which will be traced. It contains all the necessary 
  172.  information about the processes to be traced and the relevant trace levels 
  173.  which are to be activated for these processes. 
  174.  
  175.  Additionally, information about the log filename and other information is 
  176.  stored with the view object. For more information about each setting, please 
  177.  refer to the on-line help provided with PMSCOUT.EXE. 
  178.  
  179.  Whenever the user wishes to activate tracing for a particular program or group 
  180.  of programs, he must first define a view containing the information about 
  181.  these programs. Once this has been done, the view can be started, which means 
  182.  that tracing has been activated for this view. Thereafter, whenever an API 
  183.  call is executed, a check is made to determine if the current program is being 
  184.  traced and if so, which trace levels have been set. If a match is found, then 
  185.  a message is sent to the console and the information logged (if logging has 
  186.  been activated) and displayed (if display has been requested). 
  187.  
  188.  Tracing can be stopped at any time or the settings for the view can be changed 
  189.  during tracing. The trace results can be displayed on-line in a listbox and/or 
  190.  be written to a log-file for later analysis. The logfile can be viewed from 
  191.  the PM console after tracing has been stopped for the view in question. 
  192.  
  193.  Because the developer knows most about the internals of the system he has 
  194.  developed, the PM Console was developed with the developer in mind. This is 
  195.  where the views are defined and the trace logs examined. From the PM Console 
  196.  it is also possible to create SCT files to be used by the VIO Console in the 
  197.  production environment. An SCT file contains all the information defined for a 
  198.  view and allows an end-user to activate tracing without having to know all 
  199.  about which levels and processes are involved. 
  200.  
  201.  The VIO Console does not display any trace information to the screen, but 
  202.  writes solely to a logfile. After tracing has been terminated, the logfile can 
  203.  be sent to the developers for analysis. 
  204.  
  205.  The logfile must first be formatted using the format function in the PM 
  206.  console. Therafter the resulting logfile can be viewed. 
  207.  
  208.  How to set the trace levels 
  209.  How to compile the program 
  210.  
  211.  
  212. ΓòÉΓòÉΓòÉ 4.1. How to set the trace levels ΓòÉΓòÉΓòÉ
  213.  
  214. To get an idea of how to set the trace levels for a particular view, consider 
  215. the case that you want to trace two processes, say Foo.exe and Bar.exe, which 
  216. make use of interprocess communications. You might have defined four trace 
  217. levels in a file included by both Foo.c and Bar.c, say in FooBar.h: 
  218.  
  219. #define TL_FOO_SEND     10
  220. #define TL_FOO_RCV      11
  221. #define TL_BAR_SEND     12
  222. #define TL_BAR_RCV      13
  223.  
  224. Each time Foo sends something to Bar, you could code 
  225.  
  226. Tracef( TL_FOO_SEND, "Foo sent something" );
  227.  
  228. in Foo.c and consequently, 
  229.  
  230. Tracef( TL_BAR_RCV, "Bar received something" );
  231.  
  232. in Bar.c each time Bar receives something. 
  233.  
  234. To trace Foo and Bar at the same time, you would create a new view and add the 
  235. two processes Foo.exe and Bar.exe.  For Foo, you would set the trace level to 
  236. 10/10 (i.e. all levels from 10 to 10), and for Bar you would set it to 13/13. 
  237. Once tracing for your view is started (and, of course, Foo and Bar are started 
  238. as well), you can watch Foo and Bar sending and receiving. 
  239.  
  240. Later on, you might decide that you are not only interested in what Foo 
  241. receives, but in what Foo also sends. Provided you have coded the appropriate 
  242. Tracef calls in Foo.c, you would open your view's settings and change the trace 
  243. levels for Foo.exe from 10/10 to 10/11. 
  244.  
  245. Note that it is not neccessary to use different trace levels for Foo and Bar 
  246. for sending and receiving (though we did here), as C-Scout can distinguish 
  247. between the same trace levels but from different processes. That is, you could 
  248. have coded 
  249.  
  250. #define TL_SENDING     100
  251. #define TL_RECEIVING   200
  252.  
  253. in FooBar.h, 
  254.  
  255. Tracef( TL_SENDING, "Foo sent something" );
  256.  
  257. in Foo.c and 
  258.  
  259. Tracef( TL_SENDING, "Bar sent something" );
  260.  
  261. in Bar.c, as well, and set the trace levels for Foo.exe to 100/200 to watch Foo 
  262. sending and receiving, and for Bar.exe to 100/100 to watch Bar.exe only 
  263. sending. 
  264.  
  265. Now consider the trace levels you are interested in are not consecutive, as in 
  266. the following case: 
  267.  
  268. #define TL_SENDING     100
  269. #define TL_XVAL        150
  270. #define TL_RECEIVING   200
  271.  
  272. where you might use a statement like 
  273.  
  274. Tracef( TL_XVAL, "The value of x is %i", x );
  275.  
  276. to inspect the value of some integer x in your program. 
  277.  
  278. If you now would set the trace levels for Foo to 100/200 to watch Foo sending 
  279. and receiving, you would see the value of x as well. To avoid this, you would 
  280. add Foo.exe to the view's list of processes twice: One instance with the level 
  281. set to 100/100, and the other instance with the level set to 200/200. 
  282.  
  283.  
  284. ΓòÉΓòÉΓòÉ 4.2. Compiling your program ΓòÉΓòÉΓòÉ
  285.  
  286. The program can be compiled with debug options set or with optimisation set. 
  287.  
  288. The program may be dynamically linked or statically linked to the C-Runtime 
  289. Library of your favourite compiler. The DATT.H include file must be included to 
  290. use the API functions and macros. 
  291.  
  292. Note that it is neccessary to have the file OS2.H included before DATT.H, since 
  293. DATT.H uses some of the types defined in OS2DEF.H. 
  294.  
  295. The program must be linked with the DATT.LIB and the option to respect the case 
  296. for the names of external functions should be active. This is usually the /NOI 
  297. option. 
  298.  
  299.  
  300. ΓòÉΓòÉΓòÉ <hidden> Trace Levels ΓòÉΓòÉΓòÉ
  301.  
  302. It is important for a development team to carefully plan which levels are to be 
  303. used by which program and for what purpose. This makes debugging in the 
  304. production environment a lot easier because the developer is able to pinpoint 
  305. exactly which information he requires using trace levels. 
  306.  
  307. This is particularly true when debugging a DLL. In this case all Exe programs 
  308. which use the specified levels will be traced. It is strongly recommended that 
  309. levels for a particular DLL are not used elsewhere. 
  310.  
  311.  
  312. ΓòÉΓòÉΓòÉ 5. Developer's Toolkit Functions ΓòÉΓòÉΓòÉ
  313.  
  314. This section presents the help for the developer kit functions. They are 
  315. presented in alphabetical order. 
  316.  
  317.  
  318. ΓòÉΓòÉΓòÉ 5.1. Tracef ΓòÉΓòÉΓòÉ
  319.  
  320. Select an item: 
  321.  
  322.  Function Syntax 
  323.  Description 
  324.  Notes 
  325.  Example 
  326.  
  327.  
  328. ΓòÉΓòÉΓòÉ <hidden> Syntax - Tracef ΓòÉΓòÉΓòÉ
  329.  
  330. /************************************************/
  331. /* Tracef is used to send an ASCII text string  */
  332. /* to the console for display and/or logging.   */
  333. /************************************************/
  334.  
  335. #include <datt.h>
  336.  
  337. VOID APIENTRY Tracef( const ULONG   ulLevel,
  338.                       const PSZ     pszFormat,
  339.                       argument list );
  340.  
  341.  
  342. ULONG  ulLevel
  343. PSZ    pszFormat
  344. ...    argument list
  345.  
  346.  
  347. ΓòÉΓòÉΓòÉ <hidden> ulLevel ΓòÉΓòÉΓòÉ
  348.  
  349. The level is used to identify the particular part of a system to which this 
  350. piece of code belongs. The levels should be carefully thought out beforehand so 
  351. that no two programs are using the same level as this leads to the tracing of 
  352. information which is not required. 
  353.  
  354.  
  355. ΓòÉΓòÉΓòÉ <hidden> pszFormat ΓòÉΓòÉΓòÉ
  356.  
  357. This string corresponds to the format string as used in the standard C function 
  358. printf. 
  359.  
  360.  
  361. ΓòÉΓòÉΓòÉ <hidden> argument list ΓòÉΓòÉΓòÉ
  362.  
  363. The argument list corresponds to the argument list as used in the standard C 
  364. function printf. 
  365.  
  366.  
  367. ΓòÉΓòÉΓòÉ <hidden> Description - Tracef ΓòÉΓòÉΓòÉ
  368.  
  369. Tracef determines if tracing has been activated for this process and if so, 
  370. will build a string using the format string specified by pszFormat and the 
  371. argument list in the same way as the standard C function printf. The resulting 
  372. string will be sent to the console for display and/or logging. 
  373.  
  374.  
  375. ΓòÉΓòÉΓòÉ <hidden> Notes ΓòÉΓòÉΓòÉ
  376.  
  377. In case of an error using this function a popup will be displayed with error 
  378. information. 
  379.  
  380.  
  381. ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
  382.  
  383. This example shows a program using the Tracef function to track the number of 
  384. threads which the user requested to be started. 
  385.  
  386.  
  387. /*---------------------------------*/
  388. /* include the C-Scout definitions */
  389. /*---------------------------------*/
  390. #include <datt.h>
  391.  
  392.  
  393.   case IDD_TESTDLG:
  394.       {
  395.       SHORT     sNumThreads;
  396.       TX( WinDlgBox ( HWND_DESKTOP,
  397.                       hwndClient,
  398.                       dlgpTest,
  399.                       0,
  400.                       IDD_TESTDLG,
  401.                       &sNumThreads ) == DID_ERROR );
  402.  
  403.       /* trace the number entered by the user */
  404.       Tracef( TM_INFO, "Number of threads to be started %d", sNumThreads );
  405.  
  406.       break;
  407.       }
  408.  
  409.  
  410. ΓòÉΓòÉΓòÉ 5.2. HexTrace ΓòÉΓòÉΓòÉ
  411.  
  412. Select an item: 
  413.  
  414.  Function Syntax 
  415.  Description 
  416.  Notes 
  417.  Example 
  418.  
  419.  
  420. ΓòÉΓòÉΓòÉ <hidden> Syntax - HexTrace ΓòÉΓòÉΓòÉ
  421.  
  422. /************************************************/
  423. /* Hextrace is used to send the contents of a   */
  424. /* buffer to the console without any formatting */
  425. /* taking place. The contents will be logged    */
  426. /* and/or displayed as required.                */
  427. /************************************************/
  428.  
  429. #include <datt.h>
  430.  
  431. VOID APIENTRY HexTrace( const  ULONG  ulLevel,
  432.                         const  PVOID  pvData,
  433.                         const  ULONG  ulDataLen );
  434.  
  435. ULONG  ulLevel
  436. PVOID  pvData
  437. ULONG  ulDataLen
  438.  
  439.  
  440. ΓòÉΓòÉΓòÉ <hidden> ulLevel ΓòÉΓòÉΓòÉ
  441.  
  442. The level is used to identify the particular part of a system to which this 
  443. piece of code belongs. 
  444.  
  445.  
  446. ΓòÉΓòÉΓòÉ <hidden> pvData ΓòÉΓòÉΓòÉ
  447.  
  448. This is the address of the buffer whose contents are to be displayed without 
  449. any formatting performed on the buffer. The contents will be displayed as 
  450. hexadecimal values with their ASCII equivalent next to them. 
  451.  
  452.  
  453. ΓòÉΓòÉΓòÉ <hidden> ulDataLen ΓòÉΓòÉΓòÉ
  454.  
  455. This value specifies the number of bytes in the buffer which are to be sent to 
  456. the console for display and/or logging. This value should not exceed the total 
  457. length of the buffer. 
  458.  
  459.  
  460. ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ
  461.  
  462. HexTrace determines if tracing has been activated for this process and if so 
  463. informs the console to dump the number of bytes specified by ulDataLen 
  464. beginning at the address specified by pvData to the required output medium. 
  465.  
  466.  
  467. ΓòÉΓòÉΓòÉ <hidden> Notes ΓòÉΓòÉΓòÉ
  468.  
  469. In case of an error using this function a popup will be displayed with error 
  470. information. 
  471.  
  472.  
  473. ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
  474.  
  475. This example shows a program dumping the contents of a buffer. In this example 
  476. buf is an array of char. 
  477.  
  478. /*---------------------------------*/
  479. /* include the C-Scout definitions */
  480. /*---------------------------------*/
  481. #include <datt.h>
  482.  
  483.     /* dump the contents of buf */
  484.     HexTrace( TM_DUMP, buf, sizeof(buf) );
  485.  
  486.  
  487. ΓòÉΓòÉΓòÉ 5.3. SetErrorInfo ΓòÉΓòÉΓòÉ
  488.  
  489. Select an item: 
  490.  
  491.  Function Syntax 
  492.  Description 
  493.  Notes 
  494.  Example 
  495.  
  496.  
  497. ΓòÉΓòÉΓòÉ <hidden> Syntax - SetErrorInfo ΓòÉΓòÉΓòÉ
  498.  
  499. /************************************************/
  500. /* SetErrorInfo is used to register an error    */
  501. /* handler which will be called if the TX macro */
  502. /* detects an error condition.                  */
  503. /************************************************/
  504.  
  505. #include <datt.h>
  506.  
  507. VOID APIENTRY SetErrorInfo( const PFNCH  pfnConditionHandler );
  508.  
  509. const  PFNCH  pfnConditionHandler
  510.  
  511.  
  512. ΓòÉΓòÉΓòÉ <hidden> PFNCH ΓòÉΓòÉΓòÉ
  513.  
  514. typedef FNCONHANDLER * PFNCH; 
  515.  
  516.  
  517. ΓòÉΓòÉΓòÉ <hidden> FNCONHANDLER ΓòÉΓòÉΓòÉ
  518.  
  519. typedef BOOL APIENTRY FNCONHANDLER( PTXMI ptxBuffer ); 
  520.  
  521.  
  522. ΓòÉΓòÉΓòÉ <hidden> pfnConditionHandler ΓòÉΓòÉΓòÉ
  523.  
  524. This is the address of the user function to be called if an error condition is 
  525. detected. 
  526.  
  527.  
  528. ΓòÉΓòÉΓòÉ <hidden> Description ΓòÉΓòÉΓòÉ
  529.  
  530. SetErrorInfo registers the user function on a process basis. The function is 
  531. valid for all the threads in the process. The function will be called if a TX 
  532. macro detects an error condition. The function must be of the type FNCONHANDLER 
  533. and return either TRUE or FALSE. 
  534.  
  535. If the registered function returns TRUE, the default error handler is called 
  536. after the registered handler. If the registered function returns FALSE, the 
  537. default handler is not called and the process for which the function was 
  538. registered continues. Thus, it is the developer's responsibility to terminate 
  539. the process. 
  540.  
  541.  
  542. ΓòÉΓòÉΓòÉ <hidden> Notes ΓòÉΓòÉΓòÉ
  543.  
  544. In case of an error using this function a popup will be displayed with error 
  545. information. 
  546.  
  547.  
  548. ΓòÉΓòÉΓòÉ <hidden> Example ΓòÉΓòÉΓòÉ
  549.  
  550. This example shows how a program can register its own critical error function 
  551. to be called when a TX macro detects an error. ConditionHandler is the function 
  552. which is to be registered. 
  553.  
  554.  
  555. /*---------------------------------*/
  556. /* include the C-Scout definitions */
  557. /*---------------------------------*/
  558. #include <datt.h>
  559.  
  560. /*-------------------------------*/
  561. /* My own critical error handler */
  562. /*-------------------------------*/
  563. BOOL APIENTRY ConditionHandler( PTXMI ptxBuffer )
  564. {
  565.    /* if error in second thread */
  566.    if ( ptxBuffer->tid == 2 )
  567.       {
  568.          /* continue process */
  569.          return FALSE;
  570.       }
  571.    else
  572.       {
  573.          /* call default error handler */
  574.          return TRUE;
  575.       }
  576. }
  577.  
  578.  
  579.  
  580.  
  581.     /*----------------------------------------*/
  582.     /* Register my own critical error handler */
  583.     /*----------------------------------------*/
  584.     SetErrorInfo ( ConditionHandler );
  585.  
  586.  
  587. ΓòÉΓòÉΓòÉ <hidden> PTXMI. ΓòÉΓòÉΓòÉ
  588.  
  589. Pointer to a structure of type TXmacroInfo which is detailed below: 
  590.  
  591. typedef struct __TXmacroInfo
  592.     {
  593.     UCHAR      szFunction[FN_SIZE];       /* function name                    */
  594.     UCHAR      szModuleName[CCHMAXPATH];  /* name of module                   */
  595.     ULONG      ulLineNo;                  /* current line number              */
  596.     UCHAR      szSourceLine[SL_SIZE];     /* current source line              */
  597.     APIRET     apiretRc;                  /* result of expression in TX macro */
  598.     INT        iErrNo;                    /* c runtime errno                  */
  599.     INT        iDosErrNo;                 /* c runtime dos error code         */
  600.     UCHAR      szErrBuff1 [EM_SIZE];      /* PM return code text              */
  601.     UCHAR      szErrBuff2 [EM_SIZE];      /* Kernel return code text          */
  602.     UCHAR      szErrBuff3 [EM_SIZE];      /* CRT return code text             */
  603.     TID        tid;                       /* TID                              */
  604.     PID        pid;                       /* PID                              */
  605.     }    _TXmacroInfo;
  606.  
  607.  
  608. ΓòÉΓòÉΓòÉ 6. Developer's Toolkit Macros ΓòÉΓòÉΓòÉ
  609.  
  610. As well as the APIs there are macros available which make using C-Scout easier. 
  611. The macros are documented below: 
  612.  
  613.  
  614. ΓòÉΓòÉΓòÉ 6.1. TX ΓòÉΓòÉΓòÉ
  615.  
  616. The TX macro (Test eXpression) allows the programmer to encapsulate an 
  617. expression in the macro and then if at runtime the expression evaluates to TRUE 
  618. an error screen will be displayed with relevant information. Additionally a 
  619. log-file is written containing this information for later analysis. A total of 
  620. 50 such log-files will be written before wrapping to the first log-file again. 
  621.  
  622. If tracing is active, this information will also be written to the logfile or 
  623. screen by the console. 
  624.  
  625. The macro uses a feature of the IBM C-Set compiler which defines a macro for 
  626. the function name. This is only available when using the C-Set compiler or 
  627. another compiler which provides this information. The macro can still be used 
  628. for compilers without this feature but the function name is not available. 
  629.  
  630. Once the error panel is displayed the user can decide to abort the program or 
  631. to continue. Normally the user would abort the program at this stage. 
  632.  
  633. This macro should be used to protect the program from the effects of an 
  634. unrecoverable error which would anyway lead to an abnormal end. 
  635.  
  636. The expression can contain any Operating System call and so would normally be 
  637. used to check PM or Kernel calls for example which would not normally produce 
  638. an error but if not checked would lead to unforeseen errors occurring. 
  639.  
  640. Example 
  641.  
  642.  
  643. ΓòÉΓòÉΓòÉ <hidden> TX. ΓòÉΓòÉΓòÉ
  644.  
  645. This example shows how a program can check the return code of a PM call by 
  646. using the TX macro. 
  647.  
  648.  
  649. /*---------------------------------*/
  650. /* include the C-Scout definitions */
  651. /*---------------------------------*/
  652. #include <datt.h>
  653.  
  654.    TX(! WinRegisterClass( habThis,
  655.                           TITLE,
  656.                           wpClient,
  657.                           CS_SIZEREDRAW,
  658.                           0 ) );
  659.  
  660.  
  661. ΓòÉΓòÉΓòÉ 6.2. FncEntry ΓòÉΓòÉΓòÉ
  662.  
  663. The FncEntry macro (Function Entry) is used to trace the entry point of a 
  664. function. This should be the first statement used after declaring the local 
  665. variables. 
  666.  
  667. The macro uses a feature of the IBM C-Set compiler which defines a macro for 
  668. the function name. This is only available when using the C-Set compiler or 
  669. another compiler which provides this information. The macro can still be used 
  670. for compilers without this feature but the function name is not available. 
  671.  
  672. Example 
  673.  
  674.  
  675. ΓòÉΓòÉΓòÉ <hidden> FncEntry. ΓòÉΓòÉΓòÉ
  676.  
  677. This example shows how to use the FncEntry and FncExitVoid macros in a 
  678. function. 
  679.  
  680.  
  681. /*---------------------------------*/
  682. /* include the C-Scout definitions */
  683. /*---------------------------------*/
  684. #include <datt.h>
  685.  
  686.    static  VOID fnThread ( PVOID   lfn )
  687.      {
  688.      INT     i;
  689.      PSZ     pszString;
  690.  
  691.      /* trace function entry */
  692.      FncEntry();
  693.  
  694.      /* main body of function */
  695.  
  696.      /* trace function exit */
  697.      FncExitVoid();
  698.      }
  699.  
  700.  
  701. ΓòÉΓòÉΓòÉ 6.3. FncExit ΓòÉΓòÉΓòÉ
  702.  
  703. The FncExit macro (Function Exit) is the counterpart of the FncEntry macro. 
  704. This statement should be the last statement in the function before the 
  705. terminating bracket. 
  706.  
  707. The macro generates a return statement with the specified expression used as 
  708. the parameter for the return statement. If the function is of Type void i.e. no 
  709. return code then the FncExitVoid macro should be used. 
  710.  
  711. The macro documents the function exit and return code by generating an 
  712. appropriate trace statement. A feature of the IBM C-Set compiler is used for 
  713. the function name. This is only available when using the C-Set compiler or 
  714. another compiler which provides this information. The macro can still be used 
  715. for compilers without this feature but the function name is not available. 
  716.  
  717. Example 
  718.  
  719.  
  720. ΓòÉΓòÉΓòÉ <hidden> FncExit. ΓòÉΓòÉΓòÉ
  721.  
  722. This example shows how to use the FncExit macro in a function. 
  723.  
  724.  
  725. /*---------------------------------*/
  726. /* include the C-Scout definitions */
  727. /*---------------------------------*/
  728. #include <datt.h>
  729.  
  730.    static  BOOL MyFunction( VOID )
  731.      {
  732.      INT     i;
  733.      BOOL    fRc = TRUE;
  734.  
  735.      /* trace function entry */
  736.      FncEntry();
  737.  
  738.      /* main body of function */
  739.  
  740.      /* trace function exit and return code */
  741.      FncExit( fRc );
  742.      }
  743.  
  744.  
  745. ΓòÉΓòÉΓòÉ 7. Errors ΓòÉΓòÉΓòÉ
  746.  
  747. If an internal error is detected, C-Scout will produce a popup screen 
  748. containing error information. If the error persists, please contact a priori 
  749. for support. 
  750.  
  751. The following error messages may occur: 
  752.  
  753.  o DATT Init-Error - Not Initialised 
  754.  
  755.  o DATT Alloc-Error 
  756.  
  757.  o DATT SendError (DosAllocShar..) 
  758.  
  759.  o DATT SendError (DosOpenQueue) 
  760.  
  761.  o DATT SendError (DosGiveShar.) 
  762.  
  763.  o DATT SendError (DosWriteQueue) 
  764.  
  765.  o DATT SendError (DosOpenEventSem) 
  766.  
  767.  o DATT SendError (DosWaitSem) 
  768.  
  769.  
  770. ΓòÉΓòÉΓòÉ 8. Obtaining Support ΓòÉΓòÉΓòÉ
  771.  
  772. Support for C-Scout can be obtained in one of the following ways: 
  773.  
  774.  o Telephone 
  775.  
  776.    Call +49-69-239462 and ask for the Technical Support for C-Scout. 
  777.  
  778.  o Fax 
  779.  
  780.    The fax number is +49-69-236426. 
  781.  
  782.  o EMAIL 
  783.  
  784.    send a message to 100137.2315@compuserve.com. 
  785.  
  786.  In each case please quote the version information about C-Scout which is 
  787.  available from the PMSCOUT menu by selecting Help and then Product 
  788.  Information.