home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / o / os2_util.zip / ALPHAL.ZIP / ALPHA.TXT < prev    next >
Text File  |  1992-07-28  |  20KB  |  457 lines
  1.                         
  2.  
  3.     ********************************************************    
  4.     *                                                      *
  5.     *           (C) Copyright IBM Corp. 1992               *
  6.     *                                                      *
  7.     ********************************************************
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                            ALPHA V1.5
  15.  
  16.              Lionel de Lambert - Iunius MMDCCXLIII AUC
  17.  
  18.                 IBM United Kingdom Laboratories Ltd.
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28. This document describes the installation, function and commands of the ALPHA
  29. code analysis and browse programme which runs under the OS/2 operating 
  30. system. The languages supported are :-
  31. 370 and 386 assembler, PASCAL(Ada), PL/AS(PL/I, REXX) and C.
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46. Introduction.
  47.  
  48. This program may be of interest to those people who examine 370, 386 
  49. assembler, PASCAL(Ada), PL/AS(PL/I, REXX) and C etc. under OS/2.
  50.  
  51. This programme will provide basic browse functions for all files with a
  52. record size <=132 as well as highlighting specified keywords and allowing 
  53. user defined Marker references and flow lines, and for language files 
  54. such as 370 & 386 Assemble, PASCAL, C, PL/AS etc. ALPHA will also draw
  55. branch flow lines from 'Jump/GOTO' instructions to labels in the  same 
  56. window, will display the programme call structure, and expand the 
  57. procedure call in a secondary window.
  58.  
  59. The programme is written in PASCAL and MASM for OS/2 using Presentation 
  60. Manager calls.
  61.  
  62.  
  63. Installation
  64.  
  65. The minimum requirement is to transfer the binary file 'ALPHA EXEBIN' to 
  66. a directory on your PS/2 as 'ALPHA.EXE'.
  67.   
  68. If you want different colours, fonts etc. you can copy the text file 
  69. 'ALPHA PRF' to the PS/2 as 'ALPHA.PRF' and edit the file. You can also
  70. install the 'Alpha' fonts by transferring the binary file 'ALPHA FONBIN' 
  71. to the PS/2 as 'ALPHA.FON' and using the 'Add font' command of the 
  72. Installation menu on the 'Control Panel'. On OS/2 V2.0 select 'System Setup'
  73. from 'OS/2 System' and use 'Add' in the 'Edit font' of the 'Font Palette'. 
  74. If you wish to access files from the host then you should also install
  75. ALMCOPY. You can send commands to the host if you also install OS2CMD.
  76.  
  77.  
  78. Starting up Alpha
  79.  
  80. The syntax for starting up the Alpha programme is :-
  81.  
  82. [C:\].<START> ALPHA <file name> </p <profile name>> </m>
  83.   
  84. Where the option /m may be specified to cause the programme to be started 
  85. minimised. This is intended for use in the 'STARTUP.CMD' file as an 
  86. alternative to having the programme in the "Group - main" window, e.g.
  87.  
  88. START ALPHA /p /m
  89.  
  90. The option /p may be specified to cause the file of initial values of 
  91. colours, font etc. to be read. The default file name for this profile is 
  92. 'ALPHA.PRF'. This file may be used to set alternative start up values such 
  93. as the keyword colours. If a file name is not supplied on the OS/2 command
  94. line then the first display will ask for the file name to be browsed. 
  95. The Enter key or Enter button should be used to terminate the string, e.g.
  96.  
  97.         C:\WORK\TEST.A37<Enter_key>
  98.  
  99. If Alpha is minimised or active with or without a file allocated and the 
  100. file manager window is active then a selected file may be moved from the
  101. file manager window by dragging mouse button 2 and releasing it over the
  102. a icon or main window. This will cause the new file to be allocated.
  103.  
  104.  
  105.  
  106.  
  107. note
  108. If the window fails to appear the error, WinGetLastError, is written to the
  109. OUTPUT device. This should be directed to a printer or file e.g. 
  110. ALPHA >PRN | >file_name
  111.  
  112.  
  113. Description
  114.  
  115. This programme may be used to browse any file with a record size £132 and 
  116. may also be used with language files such as :-
  117. 370, 386 assembler, PASCAL(Ada), C, or PL/AS(PL/I, REXX) programmes etc. 
  118. on a PS/2 under OS/2 to help in analysing their structure.
  119.  
  120. The basic browse functions are :-
  121.  
  122. 1) Home - Move to top of file
  123. 2) End - Move to end of file
  124. 3) Page_up - scroll up 1 screen
  125. 4) Page_down - scroll down 1 screen
  126. 5) F7 - scroll up 1/2 screen
  127. 6) F8 - scroll down 1/2 screen
  128. 7) F19 (Shift+F7) - scroll left 1/2 screen
  129. 8) F20 (Shift+F8) - scroll right 1/2 screen
  130. 9) The Horizontal and Vertical scroll bars.
  131.  
  132. The mouse button 1 when pressed will isolate the addressed string 
  133. ' ', ',', '+' etc. as separators, and highlight it and all references in 
  134. the window or as the file is browsed.
  135. In Locate mode if mouse button 1 is pressed twice (double clicked) then the
  136. isolated string will become a search argument. If mouse button 2 is pressed
  137. once (clicked) then the next occurrence of the search argument will be 
  138. located. If mouse button 2 is double clicked then the search will start
  139. at the top of the file. 
  140.  
  141. In Expand mode if mouse button 1 is double clicked then the search string 
  142. is assumed to be a label or procedure name and a second window is opened 
  143. with the procedure code provided the label/routine name can be found.
  144.  
  145. Search commands may be issued from the command window, which may be invoked
  146. by the F6 key or the system menu icon a {Code Page 437; the icon will be α 
  147. for Code Page 850 etc.}.
  148. When the main window is displayed keywords which are associated with the 
  149. file extension will be highlighted using the colours specified in the 
  150. profile.
  151.  
  152. Note
  153. Up to 128 language keywords may be specified with their corresponding 
  154. colour and the length of the record to be scanned. Only the first 16 key 
  155. words on the line will be highlighted and the search order is the order 
  156. specified in the profile. The keyword must be <=12 characters.
  157.  
  158. The File_type keyword in the profile may be used to introduce extra file 
  159. types but the first 5 types are assumed to refer to :- 370 assembler, 386 
  160. assembler, PASCAL, PL/AS, and C in that order. With Flow on for language 
  161. files branch flow lines will be drawn from 'Branch/GOTO' instructions to 
  162. labels in the same window.
  163.  
  164. If the profile specifies Read_file=Yes, the default, then the file may be 
  165. browsed as soon as the window is opened, performance then improves once 
  166. the file is read in.
  167.  
  168.  
  169. Note
  170. Only the first 132 characters of a record are read. Once the file is read 
  171. in there is an internal switch over. If a locate etc. was in progress at 
  172. the time of the switch over the window may not display the line found; 
  173. it may be necessary to repeat the command e.g.F5.
  174.  
  175. If the profile specifies Read_file=No then only 120 records from the file 
  176. are read in to storage and scrolling takes place within this buffer unless 
  177. F4+Ctrl is pressed when the whole file is read in to memory asynchronously.
  178. As the file is scrolled up/down extra pages are read in to the buffer.
  179. The affect is that on scrolling upwards, after the window is displayed, 
  180. there may be a pause (hour glass symbol) while extra data is read in.
  181.  
  182. Small parts (£window size) of the file may be remembered and redisplayed by 
  183. using the Clipboard function. Drag the mouse with button 1 down over the 
  184. lines to be saved and press Ctrl+Insert to save the highlighted lines. 
  185. To redisplay the saved lines press Shift+Insert. The lines are displayed 
  186. from the cursor position onwards. The highlighted records may be printed 
  187. on LPT1 by pressing Insert+Alt.
  188.  
  189.  
  190. Function keys
  191.  
  192. The following keys are effective for the programme:-
  193.  
  194. Mouse button 1 will isolate and highlight the text. If button 1 is pressed 
  195. twice then the highlighted string may then be used as a search argument by 
  196. button 2.
  197.  
  198. Mouse button 2 will scan from the current position to the end of file for 
  199. the locate string, i.e. the string isolated by button 1 or by use of a 
  200. locate command from the command window (F6).
  201. If the mouse button 2 is pressed twice then the scan will start from the 
  202. top of the file.
  203.  
  204. F1 is the help key. 
  205.   F1+Alt will display/hide the current status  {The statement number is 
  206. displayed in the MINMAX  menu. R indicates that the file is being read in 
  207. to memory, S indicates that the programme structure is being recorded.} 
  208. of the programme. 
  209. F2 will change the font. The System Monospaced font is the default font,
  210. unless the Alpha font is installed.
  211. F3 will terminate programme.
  212. F4 will allocate a new file
  213.   F4+Ctrl will read the currently assigned file in to memory.
  214.  
  215. Note
  216. A separate thread is attached to read in the file whilst the file may 
  217. continue to be browsed within the 120 record buffer. The scrolling of the 
  218. file will be much faster but there may be some degradation of performance 
  219. while the file is read in to store. A maximum of 21,844 records can be read
  220. in if there is enough memory available. The start of the process is 
  221. signalled by a 130HZ beep and when the file is read in there is a beep of 
  222. 1760HZ and 880HZ, provided that "Quiet=No" is specified in the profile.
  223.              
  224. F5 will repeat the previous command
  225. F6 will issue a command.
  226.  
  227. Note
  228. This window may also be created from the system menu icon a. A child window
  229. is created in to which may be typed the command. 
  230.  
  231. F7 scroll up 1/2 screen.
  232. F8 scroll down 1/2 screen.
  233. F9 switch on/off comment suppression.
  234.     A sequence of blank or comment lines will be compressed to a single line
  235.     of « provided that he file is read in. The comment lines must begin with
  236.     characters specified in  Comment_start.
  237. F10 not used.
  238. F11 not used.
  239. F12 will move the mouse button 1 focus line {The line on which mouse button
  240.      1 was last pressed.} to the centre of screen.
  241.   F12+Ctrl will switch on/off the scale line in the centre of the window.
  242. F13 (shift+F1) will display the programme structure.
  243. F14 (shift+F2) will change the text colours.
  244. F17 (shift+F5) will locate the next Marker.
  245. F19 (Shift+F7) will scroll left 1/2 line.
  246. F20 (shift+F8) will scroll right 1/2 line.
  247. F24 (shift+F12) will reset the horizontal scroll, clear line markers etc.
  248. Page_Up will scroll up one page.
  249. Page_Down will scroll down one page.
  250. Home key will move to top of file.
  251. End  key will move to end of file.
  252. Insert+Ctrl will place mouse Button 1 drag area in Clipboard.
  253. Insert+Shift will copy Clipboard text to mouse Button 1 position - cursor.
  254. Insert+Alt will write the highlighted records to LPT1.
  255. Delete will remove the highlighted records, mouse button 1 display area, 
  256. from the window display.
  257. The Up & Down arrow keys will move the cursor.
  258. The scroll arrows, slider etc. and Page up or Page down keys may be used 
  259. for browsing.
  260.  
  261. Note
  262. If the mouse button 1 is kept depressed then the lines or characters will 
  263. scroll at 1 per second until the button is released. If the file is not 
  264. read in then the file size is estimated by adding 1000 every time the 
  265. internal array is filled. In this case the slider may be move to the end 
  266. of the vertical scroll bar before end_of_file is reached and then move up.
  267.  
  268. Enter key will terminate an input string or refresh the screen.
  269.  
  270. Help window
  271. This window may be invoked by the F1 key or the Help button on the command 
  272. window. The window may be scrolled by :-
  273.  
  274. Page_up - scroll up 1 screen
  275. Page_down - scroll down 1 screen
  276. Home - scroll to the top of the Help data
  277. End - scroll to the end of the Help data
  278. F7 - scroll up 1/2 screen
  279. F8 - scroll down 1/2 screen
  280. The Page_Up key word at the bottom of the window will scroll up 1 screen if
  281. selected by mouse button 1.
  282. The Page_Down key word at the bottom of the window will scroll down 1 
  283. screen if selected by mouse button 1.
  284.   
  285. The Help window may be cancelled by F3, the Cancel button or by Enter.
  286.  
  287.  
  288.  
  289. Allocate window
  290. The File Allocate window will be created by the F4 key or from the Allocate
  291. menu item of the command window. The file may be selected from the List box
  292. or typed in to the Entry box. The drive may be changed by selecting [a] from
  293. the List box or typing the drive letter followed by a ':' e.g. 'a:' in the 
  294. Entry box. The Path may be changed by selecting a directory name from the 
  295. List box or by typing the path name in the Entry box e.g. 'C:\WORK'.
  296. The COMBO box will hold the last three allocate texts which have been 
  297. entered.
  298.  
  299. A host file may be received and allocated by entering 
  300. '>H:fn ft fm PC_file_name'; this string is passed to Transfer_pgm (ALMCOPY)
  301. {without the '>' and with '/Q' appended} which must be installed on the PS/2.
  302. If Transfer_pgm fails the return code is displayed in red and the Entry text
  303. is left to be edited. If the requested file can not be allocated then the 
  304. allocate window together with an error message will be displayed.
  305.  
  306. A host command may be executed by entering '<host command'; this string is 
  307. passed to Command_pgm (OS2CMD) {without the '<'} which must be installed 
  308. on the PS/2. 
  309.  
  310. If the DosExecPgm call fails for either OS2CMD or ALMCOPY then the error 
  311. code is displayed in black.
  312.  
  313. Note
  314. If the Allocate window can not be contained in the main window then it will
  315. be made sysmodal; i.e. it must be closed before other windows can be used. 
  316. For 8515 type screens a more suitable value for the Window keyword in the 
  317. profile would be Window=(0,60,1000,600) for example. 
  318.  
  319. Command window
  320. This window may be invoked by the F6 key or the system menu icon a.
  321. {Code Page 437; the icon will be α for Code Page 850 etc.}
  322.  
  323. The following commands may be issued :-
  324. +n - scroll down n lines
  325. -n - scroll up n lines
  326. <n - scroll left n characters
  327. >n - scroll right n characters 
  328. :n - go to record n
  329. / - Search for string, not case dependent, from the current position in the
  330.      file.
  331. " - Search for string, as typed, from the current position in the file
  332. ' - Search for string, as typed, from the current position in the file but 
  333.     only in column 1
  334. (s-e)>file_name - will copy records from the current file starting at s and
  335.     ending with e to the file
  336.    file_name. file_name may be 'LPT2' etc., an existing file or a new file. 
  337.    If the end record number    is '*'  then the file is copied to end-of-file.
  338. (s-e)- - will remove the records from the window.
  339. ≡ε will cycle through the last 6 commands.
  340. The Delete|Backspace key will delete a character from the input text. 
  341.  
  342. If the first character is invalid then the line will be filled red until it
  343. is deleted.
  344. F3 or ENTER will close the window and enter the command.
  345. The cancel button will remove the window; only this child window will 
  346. receive input until it is terminated.
  347. The Flow button will switch on/off the drawing of flow lines. These lines 
  348. are drawn for language files from 'Branch/GOTO' instructions to labels 
  349. within the window.
  350.  
  351. The Expand/Locate button will switch on/off the label expansion. The 
  352. isolated label is expanded by locating the routine and opening a second 
  353. window containing the code. The mouse button 1 must be pressed twice 
  354. (double clicked) to cause the label to be located. A depth of 8 expand 
  355. windows is allowed, and each window may be scrolled using the scroll bar, 
  356. Page_Up, Page_Down, etc.
  357. The file must be read in to storage to use this facility. The Expand window 
  358. may be closed by F3 or the CALL menu item when the main window will remain 
  359. at the CALL. If the Routine menu is clicked then the main window will 
  360. scroll to the expand text, i.e. the called code line may be passed back to 
  361. the higher level window. The Locate menu or F6 will perform a case 
  362. sensitive forward search from the current line+1.
  363. F5 will repeat the previous locate. If Button 2 is double clicked after 
  364. moving to the expanded label then the window will be moved back to the 
  365. previous line, i.e. return to point of call.
  366. The label searched for is succeeded by ":" for PLS and preceded by 
  367. "FUNCTION" or   "PROCEDURE" in PASCAL. The label searched for is preceded 
  368. by "char", "extern", "far", "int", "long", "pascal", "pointer", "short",  
  369. "static" or "void" if the language type is C.
  370.  
  371. The Mark button will switch on/off the drawing of user flow lines defined 
  372. by the mouse button 1, or the setting of a marker. Up to 16 user lines or 
  373. markers may be associated with the file. If mouse button 1 is double clicked
  374. then a marker will be associated with the line. If mouse button 1 is pressed
  375. once then it will delimit the ends of a flow line. The markers or flow 
  376. lines remain associated with the record until F24 (Shift+F12) is pressed. 
  377. The markers enable places within the file to be remembered  and recalled by
  378. (Shift+F5). 
  379.  
  380. The Options menu may be selected to change the state of the following option
  381. s :-
  382.  
  383. Transient Options - reset when a new file is allocated.
  384.  
  385. Comment Suppression - replace a block of comment lines by one highlighted 
  386. line of «.
  387. Scale - place a scale line in the middle of the window.
  388. Status - indicate in the top left of the window the current status of file 
  389. reading etc.
  390.  
  391. Permanent Options - remain set when a new file is allocated.
  392.  
  393. Quiet - suppress the beep which indicates that the file is read in to 
  394. storage.
  395. Read_file_when_allocated - when the file has been allocated read it in to 
  396. storage by attaching a subtask. The file may be browsed whilst this is in 
  397. progress but the reading of the file in to storage will be slower.
  398. Record_structure - For language files this will cause the recording of the 
  399. calling structure when the
  400. file has been read.
  401. Tab - recognize tab characters, X'09', and skip to n*8.
  402. Proportional - use the font spacing for writing the characters rather than 
  403. the character size; this will allow proportional fonts to be used however 
  404. these are not suitable for displaying code.
  405. Keyword - allow or suppress the keyword highlighting.
  406.  
  407. The Allocate menu will create the Allocate window
  408.  
  409. The Structure menu may be used to display the call structure for 370, 386 as
  410. sembler, PASCAL, C and PL/AS programmes provided that the Record_structure 
  411. option is effective when the file is read in. For 370 assembler the 
  412. structure is based on BAL, BAS, DFHSTACK, for 386 assembler CALL, PROC 
  413. instructions, for PASCAL PROCEDURE, FUNCTION, keywords, for C char, extern,
  414. far, int, long, pascal, pointer, short, static or void keywords, and for 
  415. PL/AS PROC, CALL, keywords {Labels ⁿ27 characters are ignored}.
  416. If an entry is selected from the Programme Structure List Box then the 
  417. main window is scrolled to that line.
  418.  
  419. The Font menu may be used to dynamically change the font and character size;
  420. the change is not saved in the profile.
  421.  
  422. The Colour  menu may be used to dynamically change the text colours. The 
  423. language keyword colours must be specified in the profile.
  424.  
  425.  FONTs
  426. You can specify the initial/default font in the profile by using the Font 
  427. keyword in the profile,
  428. or you can change the font dynamically by invoking the Font window.
  429.  
  430. You can use the System Monospaced, Helvetica, Roman and Courier fonts but 
  431. the Courier font and the System Monospaced are the only monospaced fonts 
  432. supplied with OS/2. A monospaced font with point sizes 8,9,10 & 11 is 
  433. supplied with the ALPHA PACKAGE, which  may also be used.
  434. The fonts are then requested by specifying Font="Alpha",(10) etc. in the
  435. profile.
  436. The font type or face_name and size may be selected by the Font and 
  437. Character_size keywords in the profile. If a profile is not supplied then 
  438. the "Alpha",(10) font will be used if it is installed and a character_size 
  439. of (8,14) else the "System Monospaced",(10) font will be used and a 
  440. character_size of (8,16). Outline fonts are not selectable.
  441.  
  442. If the point size is not specified then the font is selected by using the 
  443. Character_size.
  444. Point sizes (1/72") are :-
  445. Courier (8,10,12), Roman (8,10,12,14,18,24),
  446. Helvetica (8,10,12,14,18,24),
  447. System (8,10,12, {8x8, 8x16,9x20),
  448. "Alpha" (8,9,10,11).
  449. If the point size is specified but an image font does not exist for this 
  450. nominal point size then the outline font, if available, will be used and 
  451. scaled by the Character_size.
  452. The font may be requested by face_name, e.g. Font="Alpha",(8).
  453.  
  454.  
  455.  
  456.  
  457.