home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 16 Announce / 16-Announce.zip / SNGEMI.ZIP / ERRORMGR.INF (.txt)
OS/2 Help File  |  1993-01-07  |  20KB  |  506 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. About the Error Manager Application Development Tool ΓòÉΓòÉΓòÉ
  3.  
  4. About the Error Manager Application Development Tool 
  5.  
  6. Error Manager was an idea concieved during an IBM FTN presentation of OS/2 2.0 
  7. Developer's Tools.  The presenter emphasized that a significant knowledge of 
  8. assembler was needed to make use of the debug kernal.  It seemed to us that 
  9. most OS/2 coding bugs could be found by examining all API return codes without 
  10. the hassle of using the debug kernal. 
  11.  
  12. Error Manager (EM) is a runtime API debugger and production code monitor. It 
  13. does NOT require the Debug kernel.  Even novice OS/2 programmers will find EM 
  14. to be a simple yet powerful tool to find elusive OS/2 errors.  Additionally, 
  15. Testers and Production Managers will be able to monitor software in real user 
  16. environments, and report needed fixes back to development teams. 
  17.  
  18. Error Manager acts as an error scanner, checking the return codes of the IBM 
  19. toolkit API functions.  This provides three simple functions:  it frees 
  20. developers from testing every API, eliminates the need to search for return 
  21. code descriptions and provides a means for coding a centralized error handler. 
  22.  
  23. The Error Manager works in conjuction with the IBM CSET/2 compiler, the OS/2 
  24. 2.0 Developer's Toolkit and your OS/2 software.  It notifies the developer of 
  25. errors by either logging to a file, to the Viewer program, to some other 
  26. process or internally to a window message loop. 
  27.  
  28. For more information about using the Help facility, select Help For Help in the 
  29. Help menu..* 
  30.  
  31.  
  32. ΓòÉΓòÉΓòÉ 1.1. Trademarks ΓòÉΓòÉΓòÉ
  33.  
  34. Trademarks 
  35.  
  36. The following terms are considered trademarks of Soft & GUI Incorporated: 
  37.  
  38. Error Manager
  39. ErrorMgr
  40. Command Line
  41. CmdLine
  42. Soft & GUI
  43. S&G
  44.  
  45. The following terms are registered trademarks of International Business 
  46. Machines Corporation: 
  47.  
  48. IBM
  49. OS/2
  50. Presentation Manager
  51. CSET/2
  52. OS/2 2.0 Developer's Toolkit
  53.  
  54.  
  55. ΓòÉΓòÉΓòÉ 1.2. Copyright ΓòÉΓòÉΓòÉ
  56.  
  57. Copyright 
  58.  
  59. Copyright Soft & GUI Incorporated 1992.  All rights reserved. 
  60.  
  61. Error Manager is distributed as a tool for use by a single developer. Site 
  62. licenses are available under special agreement with Soft & GUI. Additionally, 
  63. unlimited distribution rights to the runtime DLL are also available for a 
  64. minimal one-time charge. 
  65.  
  66. It is the philosophy of Soft & GUI to overcome piracy by making software 
  67. affordable.  To that end, we ask that you do your share by purchasing an honest 
  68. number of copies.  You will find that it is far cheaper than the cost of 
  69. installing a new door after the SPA comes busting in. 
  70.  
  71. If you are a small software shop trying to get started and can't afford the 
  72. list price, call us and we will work something out. 
  73.  
  74.  
  75. ΓòÉΓòÉΓòÉ 1.3. Guarantees & Responsibilities ΓòÉΓòÉΓòÉ
  76.  
  77. Guarantees & Responsibilities 
  78.  
  79. We believe Error Manager will enable you to develop better code, by making you 
  80. aware of errors for which you weren't looking and by providing a means for 
  81. writing a simple centralized error handling facility, but we don't guarantee 
  82. it.  We do guarantee that if you find a bug within Error Manager, we will try 
  83. to fix it. 
  84.  
  85. Soft & GUI does not assume any responsibility for any problems which arise as a 
  86. result of using Error Manager in any phase of the software development, test or 
  87. production cycles.  Besides, we would rather go out of business than lose a 
  88. lawsuit, frivolous or otherwise. 
  89.  
  90.  
  91. ΓòÉΓòÉΓòÉ 2. Getting Started ΓòÉΓòÉΓòÉ
  92.  
  93. Getting Started 
  94.  
  95. To install Error Manager, place the diskette in your 3.5" floppy drive. 
  96.  
  97. Copy the contents of the INCLUDE directory of the Error Manager diskette to a 
  98. directory on your hard drive.  If you create a new directory for this, be sure 
  99. to add it to the INCLUDE statement in CONFIG.SYS. 
  100.  
  101. Copy the errormgr.lib file to your hard drive.  This is commonly copied into 
  102. either the C runtime or Toolkit LIB subdirectories. If you create a new 
  103. directory for this, be sure to add it to the LIB statement in CONFIG.SYS. 
  104.  
  105. Copy the errormgr.dll file to your hard drive.  This is commonly copied into 
  106. either the C runtime or Toolkit DLL subdirectories. If you create a new 
  107. directory for this, be sure to add it to the LIBPATH statement in CONFIG.SYS. 
  108.  
  109. Copy the errormgr.inf file to your \OS2\BOOK directory.  Of course, you must 
  110. have done something like that already if you are reading this text. 
  111.  
  112. While you are in CONFIG.SYS, go ahead and set the ERRORLOG environment variable 
  113. to some filename you like. 
  114.  
  115. If you had to update CONFIG.SYS during the install process, you will have to 
  116. reboot prior to using Error Manager.  By the way, we apologize for not having a 
  117. sexy install program, but you are probably a developer and are consequently 
  118. above such trivial niceties. 
  119.  
  120.  
  121. ΓòÉΓòÉΓòÉ 3. How to use the Soft & GUI Error Manager ΓòÉΓòÉΓòÉ
  122.  
  123. How to use the Soft & GUI Error Manager 
  124.  
  125.  Using Error Manager is extremely simple. 
  126.  
  127.  1. Insert the following line between the System and Toolkit include files and 
  128.     the application specific include files in any C source files that are to be 
  129.     monitored.  Be sure that all the EM include files are in the INCLUDE search 
  130.     path.  For Example: 
  131.  
  132.         #define INCL_WIN
  133.         #include <os2.h>
  134.         #include <stdlib.h>
  135.  
  136.         #include <errormgr.h>
  137.  
  138.         #include <myapp.h>
  139.  
  140.  2. Link the application using the ErrorMgr.lib Library file.  For Example: 
  141.  
  142.         link386 myapp+mysubs,,, errormgr,myapp.def;
  143.  
  144.  3. Set the Error Manager environment variable, ERRORLOG, to indicate the 
  145.     destination for the notifications.  This can be a filename, a named pipe or 
  146.     even a COM port for those who develop with a debug terminal.  This is 
  147.     usually added to your CONFIG.SYS file.  It can be changed within any OS/2 
  148.     session by issuing a new SET statement.  For Example: 
  149.  
  150.         set ERRORLOG=errors
  151.      Or, have your program be notified internally by using the  EMSetWindow() 
  152.     API.  You may also specify a callback function to be invoked when errors 
  153.     occur by using the  EMSetCallbackFn() API. 
  154.  
  155. Just remember to make sure that the Error Manager header file directory is in 
  156. your INCLUDE path statement, that the errormgr.lib directory is in the LIB path 
  157. statement and that the errormgr.dll directory is in your LIBPATH statement in 
  158. CONFIG.SYS. 
  159.  
  160.  
  161. ΓòÉΓòÉΓòÉ 4. What does Error Manager tell me? ΓòÉΓòÉΓòÉ
  162.  
  163. What does Error Manager tell me? 
  164.  
  165. First, EM will notify a window of all errors it catches by posting a 
  166. WM_ERRORMGR message.  The default value of WM_ERRORMGR is 0x2876.  If this 
  167. value is already used by your application, it may be changed to any non-zero 
  168. value using the  EMSetMessageValue()  function.  The window which recieves the 
  169. WM_ERRORMGR messages is specified by using the  EMSetWindow()  call.  This 
  170. allows the programmer to centralize error handling in a single routine. There 
  171. are four values which can be extracted from this message: 
  172.  
  173. usFnNumber   = SHORT1FROMMP(mp1) 
  174.  
  175. usErrorNumber  = SHORT2FROMMP(mp1) 
  176.  
  177. usModuleNumber = SHORT1FROMMP(mp2) 
  178.  
  179. usLineNumber  = SHORT2FROMMP(mp2) 
  180.  
  181. The actual source module name, offending Toolkit function name and error 
  182. description can be retrieved using the  EMQueryModuleName(),  EMQueryFnName() 
  183. and  EMQueryErrorDesc() functions respectively.  Prototypes for these functions 
  184. exist in errormgr.h. 
  185.  
  186. Error Manager also generates a notification log of all errors detected to the 
  187. file specified in the environment variable, ERRORLOG.  If this is not set, no 
  188. log will be produced.  The following is an example of an actual Error Manager 
  189. notification file: 
  190.  
  191. ----------------- Session started on 6/9/92 at 15:36:51 ---------------------
  192.  
  193. WinLoadMenu() generated error 1001  - Invalid window handle (HWND)
  194. in file WNDPROC.C at line 286.
  195.  
  196. GpiSetBitmap() generated error 207F  - Invalid presentation space handle (HPS)
  197. in file WNDPROC.C at line 538.  This occurred 3 consecutive times.
  198.  
  199. The first time an error is detected, a new Session header is appended with the 
  200. current date and time.  Then, as errors are intercepted, the offending function 
  201. and the error number are displayed with a description of the error. The source 
  202. file name and line number appear on the next line.  If the same error 
  203. repeatedly occurs at the same position, a message is displayed with the number 
  204. of occurrences, rather than generating redundant notifications. 
  205.  
  206. Finally, programmers may include their own messages into the log by invoking 
  207. the  EMInsertMessage()  API.  This is very usful in situations where a 
  208. conventional debugging breakpoint would interfere (e.g. time critical 
  209. sections). 
  210.  
  211.  
  212. ΓòÉΓòÉΓòÉ 5. Error Manager Functions ΓòÉΓòÉΓòÉ
  213.  
  214. Error Manager Functions 
  215.  
  216. The following functions can be used to set error notification destinations and 
  217. to extract error information received. 
  218.  
  219.  
  220. ΓòÉΓòÉΓòÉ 5.1. EMQueryPointerValidity ΓòÉΓòÉΓòÉ
  221.  
  222. ULONG APIENTRY EMQueryPointerValidity(PVOID ptr, ULONG size); 
  223.  
  224. Determines the number of bytes which could be read without causing a memory 
  225. violation.  If 0 is returned, the pointer is not valid.  The size argument 
  226. usually contains the size of some structure or array to be read, but 0 may be 
  227. passed to find the total amount of readable memory from the pointer in 
  228. question. 
  229.  
  230. Be sure to include the EMCHKPTR.H include file which contains the function 
  231. prototype.  Additionally, each program using this function will need to add 
  232. EMCHKPTR.LIB to the library section of the link386 command. 
  233.  
  234. #define INCL_WIN
  235. #include <os2.h>
  236. #include <stdlib.h>
  237.  
  238. #include <errormgr.h>
  239. #include <emchkptr.h>
  240.  
  241. #include <myapp.h>
  242.  
  243.  
  244. ΓòÉΓòÉΓòÉ 5.2. EMSetWindow ΓòÉΓòÉΓòÉ
  245.  
  246. BOOL APIENTRY EMSetWindow(HWND hwnd); 
  247.  
  248. Determines the window (hwnd) which will receive Error Manager notification 
  249. messages.  This call is frequently made within the WM_CREATE or WM_INITDLG 
  250. message processing of the window procedure. 
  251.  
  252. Also see  EMGetWindow() 
  253.  
  254.  
  255. ΓòÉΓòÉΓòÉ 5.3. EMGetWindow ΓòÉΓòÉΓòÉ
  256.  
  257. HWND APIENTRY EMGetWindow(VOID); 
  258.  
  259. Returns a handle to the window which is currently receiving notification, or 
  260. NULL if no window has been set. 
  261.  
  262. Also see  EMSetWindow() 
  263.  
  264.  
  265. ΓòÉΓòÉΓòÉ 5.4. EMSetState ΓòÉΓòÉΓòÉ
  266.  
  267. BOOL APIENTRY EMSetState(BOOL fState); 
  268.  
  269. Allows developers turn off and on the notification mechanism.  This is usually 
  270. used around code that produces expected errors.  FALSE turns notification off, 
  271. TRUE turns it back on again.  The default state is on. 
  272.  
  273. Also see  EMGetState() 
  274.  
  275.  
  276. ΓòÉΓòÉΓòÉ 5.5. EMGetState ΓòÉΓòÉΓòÉ
  277.  
  278. BOOL APIENTRY EMGetState(VOID); 
  279.  
  280. Returns the current state of notification.  FALSE indicates that notification 
  281. is currently off, while TRUE indicates it is on. The default state is on. 
  282.  
  283. Also see  EMSetState() 
  284.  
  285.  
  286. ΓòÉΓòÉΓòÉ 5.6. EMInsertMessage ΓòÉΓòÉΓòÉ
  287.  
  288. VOID APIENTRY EMInsertMessage(PSZ pszUserMessage); 
  289.  
  290. Allows the developer to add informational messages to the error log.  This will 
  291. not generate a PM message to the internal window procedure. 
  292.  
  293. All messages will be prefixed with the string "Programmer Message - ". The 
  294. string passed may be up to 272 characters in length.  Additional characters 
  295. will be truncated. 
  296.  
  297.  
  298. ΓòÉΓòÉΓòÉ 5.7. EMQueryModuleName ΓòÉΓòÉΓòÉ
  299.  
  300. VOID APIENTRY EMQueryModuleName(USHORT usModNumber, PCHAR pModName, USHORT 
  301. usModNameLen); 
  302.  
  303. Used to extract the offending module name from data received in the WM_ERRORMGR 
  304. message.  It takes the index number passed within the message, a buffer where 
  305. the text should be placed and the size of the buffer. 
  306.  
  307.  
  308. ΓòÉΓòÉΓòÉ 5.8. EMQueryFnName ΓòÉΓòÉΓòÉ
  309.  
  310. VOID APIENTRY EMQueryFnName(USHORT usFnNumber, PCHAR pFnName, USHORT 
  311. usFnNameLen); 
  312.  
  313. Used to extract the offending API function name from data received in the 
  314. WM_ERRORMGR message.  It takes the index number passed within the message, a 
  315. buffer where the text should be placed and the size of the buffer. 
  316.  
  317.  
  318. ΓòÉΓòÉΓòÉ 5.9. EMQueryErrorDesc ΓòÉΓòÉΓòÉ
  319.  
  320. VOID APIENTRY EMQueryErrorDesc(USHORT usErrorNumber, PCHAR pDesc, USHORT 
  321. usDescLen); 
  322.  
  323. Used to extract the description of the error from data received in the 
  324. WM_ERRORMGR message.  It takes the error number passed within the message, a 
  325. buffer where the text should be placed and the size of the buffer. 
  326.  
  327.  
  328. ΓòÉΓòÉΓòÉ 5.10. EMSetMessageValue ΓòÉΓòÉΓòÉ
  329.  
  330. BOOL APIENTRY EMSetMessageValue(USHORT usNewMessageValue); 
  331.  
  332. Sets a new message value for WM_ERRORMGR.  Use this function when your 
  333. application already uses a message with this value (unlikely as that may be). 
  334. The default value of WM_ERRORMGR is 0x2876. 
  335.  
  336.  
  337. ΓòÉΓòÉΓòÉ 5.11. EMSetCallbackFn ΓòÉΓòÉΓòÉ
  338.  
  339. BOOL APIENTRY EMSetCallbackFn(VOID (*pfn)(USHORT, USHORT, USHORT, USHORT)); 
  340.  
  341. Specifies a function to be called when an error is detected.  The function 
  342. should be defined as follows: 
  343.  
  344. VOID APIENTRY MyErrorCallbackFn(USHORT usFunctionNumber, USHORT
  345. usReturnCode, USHORT usModuleNumber, USHORT usLineNumber)
  346. {
  347. :
  348. :
  349. :
  350. }
  351.  
  352. The actual source module name, offending Toolkit function name and error 
  353. description can be retrieved using the  EMQueryModuleName(),  EMQueryFnName() 
  354. and  EMQueryErrorDesc() functions respectively.  Prototypes for these functions 
  355. exist in errormgr.h. 
  356.  
  357.  
  358. ΓòÉΓòÉΓòÉ 6. Using the Soft & GUI Stream Viewer ΓòÉΓòÉΓòÉ
  359.  
  360. Using the Soft & GUI Stream Viewer 
  361.  
  362. You may use the Soft & GUI Stream Viewer, SNGVIEW.EXE, to monitor the error 
  363. manager output from PM.  Simply set the ERRORLOG environment variable to 
  364. \PIPE\VIEWER, start SNGVIEW.EXE, and run the program in question.  All Error 
  365. Manager output will be redirected to the MLE in the viewer, which can be edited 
  366. and saved as necessary. 
  367.  
  368.  
  369. ΓòÉΓòÉΓòÉ 7. Limitations ΓòÉΓòÉΓòÉ
  370.  
  371. Limitations 
  372.  
  373. Error Manager will handle software which is comprised of an unlimited number of 
  374. modules, so long as no more than 100 of said modules produce errors.  Errors 
  375. from any modules beyond the first 100 will not be reported.  If you have more 
  376. than 100 modules, we suggest you consider a redesign or make use of DLLs and 
  377. libraries. 
  378.  
  379. We limit module names to twelve (12) characters. 
  380.  
  381. We limit programmer messages to 272 characters.  See the  EMInsertMessage() API 
  382. for more details. 
  383.  
  384. Error Manager uses semaphores to control error logging, so multithreaded 
  385. applications are fully supported. 
  386.  
  387.  
  388. ΓòÉΓòÉΓòÉ 8. Unmonitored Functions ΓòÉΓòÉΓòÉ
  389.  
  390. Unmonitored Functions 
  391.  
  392. The following calls are not monitored by Error Manager.  This does not mean 
  393. that you can't use them; it only means if they blow up, we won't be telling 
  394. you.  Some of the APIs are in this list simply because they provide no feedback 
  395. of success or failure, such as the DosExit() API. 
  396.  
  397. By the way, if this seems like a long list of 36 functions, we assure you that 
  398. the list of fully supported calls is much longer; 950 toolkit APIs are fully 
  399. handled! 
  400.  
  401. DevPostDeviceModes()
  402. DosExit()
  403. GetDriverInfo()
  404. GpiQueryColorData()
  405. Gre32Entry10()
  406. Gre32Entry2()
  407. Gre32Entry3()
  408. Gre32Entry4()
  409. Gre32Entry5()
  410. Gre32Entry6()
  411. Gre32Entry7()
  412. Gre32Entry8()
  413. Gre32Entry9()
  414. GreInitialize()
  415. NlsConvertBidiNumerics()
  416. NlsEditShape()
  417. NlsInverseString()
  418. NlsQueryBidiAtt()
  419. NlsSetBidiAtt()
  420. NlsSetBidiPrint()
  421. NlsShapeBidiString()
  422. PostDeviceModes()
  423. PrfCreateGroup()
  424. PrfQueryProgramCategory()
  425. PrfQueryProgramHandle()
  426. PrtAbort()
  427. SetDriverInfo()
  428. SSAllocMem()
  429. SSFreeMem()
  430. VioGlobalReg()
  431. WinDBCSIMEControl()
  432. WinDBCSLoadFontDriver()
  433. WinDBCSModeControl()
  434. WinDBCSQueryFDDescription()
  435. WinDBCSUnloadFontDriver()
  436. WinSetErrorInfo()
  437.  
  438.  
  439. ΓòÉΓòÉΓòÉ 9. Troubleshooting ΓòÉΓòÉΓòÉ
  440.  
  441. Troubleshooting 
  442.  
  443. The following problem situations have been reported by our beta sites, along 
  444. with fixes. 
  445.  
  446.  
  447. ΓòÉΓòÉΓòÉ 9.1. Do not get error descriptions ΓòÉΓòÉΓòÉ
  448.  
  449. Do not get error descriptions 
  450.  
  451. This is most likely because you are making Win calls without having created an 
  452. anchor block.  Add WinInitialize(0) to the beginning of your main() function. 
  453. This is necessary because we make an internal call to WinGetLastError to 
  454. determine the reason for the function failure. Programs which do not use the 
  455. Win calls need not be concerned with this. 
  456.  
  457.  
  458. ΓòÉΓòÉΓòÉ 9.2. Do not get internal notification in my window procedure ΓòÉΓòÉΓòÉ
  459.  
  460. Do not get internal notification in my window procedure 
  461.  
  462. Call  EMSetWindow() with the handle of the window which is to receive 
  463. notification. 
  464.  
  465.  
  466. ΓòÉΓòÉΓòÉ 10. Ordering Information ΓòÉΓòÉΓòÉ
  467.  
  468. Ordering Information 
  469.  
  470. Error Manager is available directly from Soft & GUI Inc. and through various 
  471. software catalogs.  Discounts are available to OS/2 users groups. Site licenses 
  472. are available.  Also, unlimited distribution rights of the runtime DLL are 
  473. available for a minimal charge. 
  474.  
  475. List Price: $225 per developer. 
  476.  
  477.                              Soft & GUI Incorporated
  478.                               2224 East 21st Street
  479.                             Brooklyn, New York  11229
  480.  
  481.                                  (718) 769-8017
  482.  
  483. Please contact us for quantity discounts and site license information. 
  484.  
  485.  
  486. ΓòÉΓòÉΓòÉ 11. About Soft & GUI ΓòÉΓòÉΓòÉ
  487.  
  488. About Soft & GUI 
  489.  
  490.                              Soft & GUI Incorporated
  491.                               2224 East 21st Street
  492.                             Brooklyn, New York  11229
  493.  
  494.                                  (718) 769-8017
  495.  
  496. Soft & GUI was founded in 1991, by Arthur Goikhman.  In 1992, Steve Dacek came 
  497. on board and the two began development of Command Line.  The charter was to 
  498. make money by venturing into the untamed (and untrampled) regions of OS/2. 
  499.  
  500. Please let us know of features you would like added, or problems you encounter 
  501. using Error Manager.  Your feedback will drive all future development. 
  502.  
  503. Soft & GUI is currently working on several other projects: Command Line, an 
  504. on-demand command prompt, which allows users to execute OS/2 commands or 
  505. programs without leaving the active PM application in search of an icon or an 
  506. open OS/2 session; and KingMaker, a visual application development environment.