home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / postpr.zip / POSTPROC.TXT < prev   
Text File  |  1994-07-12  |  12KB  |  248 lines
  1. POSTPROC.CMD - A "ratchetware" production by D.P. Babcock.
  2.  
  3. INTRODUCTION
  4.  
  5. We are using VisPro REXX as our sole 32 bit OS/2 Client Server
  6. application development tool in conjunction with DB2/2. Via DDCS
  7. we can then build applications which access our DB2/MVS databases
  8. on the host. In building a number of these applications we've
  9. developed some coding standards that we feel make our
  10. applications more "robust" and "bullet proof." We found that we
  11. were adding these to every VisPro generated database screen and
  12. so I wrote a "Post-processor" to automatically add these to the
  13. newly generated VisPro code.
  14.  
  15. LICENSE
  16.  
  17. There is no license because this is free for your use in whatever
  18. way you see fit. All I ask is that you send me an E-MAIL (CIS
  19. 76077,3173) if you  use it telling me a bit about what it has
  20. done for you. Also, I'd like to encourage you to share your
  21. tidbits of knowledge with the rest of us. In this fashion we can
  22. all "ratchet" our skills in this environment to new heights. I've
  23. always found that I learned best from looking at someone else's
  24. real code. I hope that this little REXX program may benefit you
  25. similarly and that you will in turn share goodies that you
  26. develop. Thus, I've dubbed this kind of offering "ratchet-ware" -
  27. FREEWARE for the price of an E-MAIL and in the hope that you will
  28. produce other "ratchet-ware" for the good of us all.
  29.  
  30. THE PROGRAM
  31.  
  32. This is a simple REXX command file that is highly modular. It
  33. takes one argument - the full pathname of the canvas (in OS/2
  34. terms this is merely a subdirectory) that contains the event code
  35. files (FORM.1, *.0 files, etc.) Thus, the easiest way to use this
  36. program is to copy it to some directory and set up a PROGRAM
  37. object that points to it. By then dragging any VisPro form
  38. (canvas) icon and dropping on the program icon you will
  39. automatically invoke the command file with the full pathname
  40. passed via the drag/drop.
  41.  
  42. USE
  43.  
  44. Use the VisPro Database Diagrammer (DBD) to build a schema for
  45. your table(s). Then build a VisPro default CReate, Update,
  46. Delete, Search (CRUDS) screen by drag/dropping the table object
  47. onto a new blank canvas. At this point you have the standard
  48. VisPro application screen. Now, drag the ICON representing this
  49. screen from the project folder and drop it on the POSTPROC
  50. program icon you built above. An OS/2 window will open and you
  51. will see a number of progress STDOUT messages. When this is
  52. complete, go examine the events in the form (canvas - I use these
  53. terms interchangeably) and see what has changed. I'll outline
  54. these changes below for your convenience. Make sure your database
  55. name and qualifier are set and then EXPORT the DDL to a file
  56. named DDL.TXT. This file will be read later if it exists to
  57. further refine the data types.
  58.  
  59. WHAT IT DOES
  60.  
  61. - Looks for an UNDO subdirectory below the directory containing
  62. the form events. If one isn't found, create one and copy all of
  63. the "as generated" event code into it so that we can always get
  64. back to a "clean" start. This will be true the first time you
  65. drag/drop the form icon on the post-generator. Otherwise, it
  66. copies the files from the UNDO subdirectory into the parent to
  67. restore the event code to the original VisPro generated state.
  68.  
  69. - Creates two subprocs in the subprocs folder of the project that
  70. will be used by the generated code. SQUOTEIT and SQUOTEWC handle
  71. the problem of text input that contains apostrophes. These must
  72. be "doubled"  (i.e.  "O'Brien" becomes "O''Brien") for REXX/DB2
  73. parsing to work correctly. In addition, the outer quotes are
  74. added for character data types. SQUOTEIT (single-quote-it) and
  75. SQUOTEWC (single-quote-it-wildcarded) are the same except that
  76. the appropriate wildcarding per data type is added. This is only
  77. used therefore in the SEARCH event.
  78.  
  79. - Looks in the form subdirectory for the FORM.1 (form open event)
  80. and *.0 (form events) files. Read each of these to determine
  81. which filename contains which event by looking for identifying
  82. code fragments.
  83.  
  84. - Read the ADD event file to get a list of the column names used
  85. in this generation. This is not necessarily all of the columns in
  86. the table. Some may have been excluded by you (nullable) when you
  87. generated the form. That's why I read them here instead of merely
  88. getting them from the schema file (DDL.TXT). I also determine the
  89. data types by both looking at the original VisPro code (quoted
  90. VpGetItemValue() calls indicate character (C) data types - others
  91. are assumed numeric) because DATE, TIME and TIMESTAMP types are a
  92. hybrid of sorts (character in that they are quoted but not valid
  93. for character wildcarding or as a LIKE predicate.) I then look
  94. for a DDL.TXT file in the folder directly above the project
  95. folder. If it exists, I read it to further distinguish TIME (T)
  96. data types from character. The process will work without the
  97. DDL.TXT file but the SEARCH code will have to be modified by hand
  98. if you have any DATE, TIME or TIMESTAMP columns in the table to
  99. change the postgenerated SQOUTEWC calls from type 'C' to type
  100. 'T'.
  101.  
  102. For documentation printing, I put a comment identifying each of
  103. the events at the beginning of the event code. This is done as I
  104. visit each event code file in the following steps.
  105.  
  106. - Remove the START USING DATABASE code from the ADD event (saving
  107. it for later insertion into the FORM OPEN event)
  108.  
  109. - Put the SQUOTEIT call in the ADD pushbutton event and remove
  110. the VisPro quoting around the VpGetItemValue() calls.
  111.  
  112. - Put the SQUOTEIT call in the CHANGE pushbutton event and remove
  113. the VisPro quoting around the VpGetItemValue() calls.
  114.  
  115. - Remove the START USING DATABASE code from the CHANGE event.
  116.  
  117. - Put the SQUOTEIT call in the DELETE pushbutton event and remove
  118. the VisPro quoting around the VpGetItemValue() calls.
  119.  
  120. - Remove the START USING DATABASE code from the DELETE event.
  121.  
  122. - We found that there is a bug in the 2.0 Vispro code that causes
  123. your application to close if you perform two SEARCHES in a row
  124. without an intervening CLEAR. After working with HOCKWARE they
  125. gave us a workaround fix to put into the CONTAINER CLICKED event.
  126. It does fix the problem but you get some unnecessary iterations
  127. of this even which can be distracting. This post generator
  128. installs this "collapse" fix at this time. However, the next
  129. version of the VisPro REXX will fix this. Also, it appears that
  130. this can be avoided by merely cutting the code from this event
  131. and deletng the event and then pasting it into the CONTAINER
  132. DOUBLE-CLICKED event. Actually, with the addition of the search
  133. engine, we find this works rather nicely. Try it and see. I'd
  134. have had the generator do this automatically but since VisPro
  135. doesn't generate this event originally as a x.0 file, there was
  136. no way I could change it automatically.
  137.  
  138.  
  139. - Put the SQUOTEWC call in the SEARCH pushbutton event and remove
  140. the VisPro quoting around the VpGetItemValue() calls.
  141.  
  142. - Remove the START USING DATABASE code from the SEARCH event.
  143.  
  144. - Put the START USING DATABASE code into the FORM OPEN event.
  145.  
  146. - Fully qualify the INSERT statement in the ADD event by adding
  147. the explicit column names. We feel this is good coding practice
  148. since it will keep your code from "breaking" if a nullable column
  149. is added to the table.
  150.  
  151. - For similar reasons, fully qualify the column names in the
  152. SELECT statement of the SEARCH event. Also, we add indicator
  153. variables for ALL columns whether they are nullable or not. This
  154. doesn't seem to hurt and it certainly keeps the code from
  155. breaking if you later change a table column to nullable.
  156.  
  157. - Now for the best part. The SEARCH event is a bit anemic in that
  158. it merely returns all of the records. We wanted to beef it up a
  159. bit by creating a dynamic WHERE clause that would be built based
  160. upon the user merely filling in one or more of the fields as
  161. desired. This code is inserted. We think you'll like it and will
  162. be inspired to do even more.
  163.  
  164. - We also deal with some LARGE databases. We've found that the
  165. containers and list boxes will take only about a thousand or so
  166. records max (depends on record length) before they just quit
  167. updating. Nevertheless, the FETCH loop continues to churn while
  168. the user looks at the clock. We decided to add a Read Limit
  169. check. You can easily set the ReadLimit variable to whatever you
  170. like. On slower PC's this should probably be only a few hundred.
  171. Users can think their machines have locked up if the wait gets
  172. too long. With the new search engine, we like to give them the
  173. opportunity to quickly refine their search if they inadvertently
  174. specify too large a return set.
  175.  
  176. - Finally, since the VisPro code doesn't check the indicator
  177. variables, when you FETCH a column that is NULL it's FETCH
  178. variable retains the last non-null value for that column which in
  179. turn is loaded into the CONTAINER stem variable. This has the
  180. undesirable effect of making it appear as though all records in
  181. the CONTAINER have actual values for NULL columns that reflect
  182. the first record above them for which the column had an actual
  183. value. We added the code to clear the FETCH variables each time
  184. through the FETCH loop to prevent this "aliasing" of the data
  185. loaded into the container.
  186.  
  187. Well, there you have it so far. I'm sure that we'll discover more
  188. changes but we've done a few apps with this and it gives us a
  189. MUCH better starting place to begin customization of the
  190. generated apps. With a little study of the REXX code you will see
  191. that all of the pieces are modular and that you can pretty much
  192. pull any of the pieces you don't want or add new ones by cloning.
  193. This modularity results in a lot of re-reading of the same form
  194. event file but I think this is more than offset by the
  195. flexibility of the modularity. I know that this generator will
  196. get "broken" by the next round of VisPro improvements but the
  197. modularity will allow you (and us) to easily adapt it for the new
  198. code. It also allows you to customize it to reflect your coding
  199. standards. I'd love to hear of any that you have developed. Keep
  200. the concept of "ratchetware" in mind. I believe that I have
  201. coined this term. 
  202.  
  203. Yours for growth in our mutual professions,
  204.  
  205. Don P. Babcock Jr. P.E.
  206.  
  207. REVISION HISTORY
  208.  
  209. 7/8/94 Version 1.1
  210.  
  211. -    Each module was converted into a subroutine and call from
  212.      the main program to increase the ease of module exclusion
  213.      and addition.
  214.  
  215. -    Additional comment lines have been added at the beginning of
  216.      each event. Also, a second argument was added to the main
  217.      routine to allow the insertion of a programmer's initials.
  218.      By putting the prorammers initials in the arguments field of
  219.      a program object, they will show up as the first argument
  220.      when the form icon is drag/dropped on the program. The last
  221.      argument is always the system pathname for the drag/dropped
  222.      object. A bit more code was added to make the code backwards
  223.      compatible so that if the initials are omitted, the first
  224.      argument is considered to be the pathname.
  225.  
  226. -    Three modules were added, CommitAddPB, CommitChangePB, and
  227.      CommitDeletePB to add COMMIT's at the end of each of the
  228.      respective events. We had been relying upon the process
  229.      termination to autocommit. This works unless the process
  230.      abends in which case all of the work is rolled back.
  231.  
  232. -    A module was added, ConfirmDeletePB, that pop's up a "second
  233.      chance" confirmation for deleting records. It is too easy to
  234.      inadvertently click on the DELETE pushbutton!
  235.  
  236. 7/12/94 Verision 1.2
  237.  
  238. -    Added code to automaticall build a HINT file for the
  239.      pushbuttons. 
  240.  
  241. -    Also fixed a minor bug that would have eventually caused
  242.      problems in the SQUOTEIT and SQUOTEWC code generation. An
  243.      extra set of quotes was needed around one of the instances
  244.      of the term "value." The generated code was fine but if
  245.      VALUE had ever taken on a value in the generator, the code
  246.      would have used that instead of the literal value.
  247.  
  248.