home *** CD-ROM | disk | FTP | other *** search
/ Software of the Month Club 1995 March / SOFM_Mar1995.bin / pc / os2 / alphal / alpha1.txt < prev    next >
Text File  |  1995-01-27  |  30KB  |  727 lines
  1.  
  2.     *******************************************************************
  3.     *                                                                 *
  4.     * (C) Copyright International Business Machines Corporation 1993. *
  5.     *                 All rights Reserved.                            *
  6.     *                                                                 *
  7.     *******************************************************************
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                            ALPHA1 V1.7
  15.  
  16.              Lionel de Lambert - Iunius MMDCCXLIII AUC
  17.  
  18.                 IBM United Kingdom Laboratories Ltd.
  19.  
  20.                        21 September 1994
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28. This document describes the installation, function and commands of the ALPHA1 
  29. Software analysis programme which runs under the OS/2 (v1.3 & v2.x) 
  30. operating systems.
  31.  
  32. The languages supported are :-
  33. 370 and 386 assembler, PASCAL(Ada), PL/X(PL/I, REXX), C and FORTRAN.
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47. Introduction.
  48. =============
  49.  
  50. This programme may be of interest to those people who examine 370, 386
  51. assembler, PASCAL(Ada), PL/AS(PL/I, REXX), C, FORTRAN etc. under OS/2.
  52. This programme was written together with the CMS programme ANALYSE in
  53. order to establish some of the praecognita for the CICS restructure
  54. project.
  55.  
  56. This programme will provide basic browse functions for all files with a
  57. record size <=256 as well as highlighting specified keywords and allowing
  58. user defined Marker references and flow lines, and for language files
  59. such as 370 & 386 Assemble, PASCAL, PL/AS, C, FORTRAN etc.
  60. ALPHA will also draw branch flow lines from 'Jump/GOTO' instructions
  61. to labels in the  same window, will display the programme call structure,
  62. and expand the procedure call in a secondary window.
  63.  
  64. The programme is written in PASCAL and MASM for OS/2 using Presentation
  65. Manager calls.
  66.  
  67.  
  68. Installation
  69. ============
  70.  
  71. The minimum requirement is to transfer the binary file 'ALPHA1.EXE' to
  72. a directory on your PS/2.
  73.  
  74. If you want different colours, fonts etc. you can copy the text file
  75. 'ALPHA.PRF' to the PS/2 and edit the file. You can also
  76. install the 'Alpha' fonts by transferring the binary file 'ALPHA.FON'
  77. to the PS/2 and using the 'Add font' command of the
  78. Installation menu on the 'Control Panel' on OS/2 V1.3. On OS/2 V2.x select
  79.  'System Setup'  from 'OS/2 System' and use 'Add' in the 'Edit font' of
  80. the 'Font Palette'.
  81. If you wish to access files from the host then you should also install the
  82. 'Transfer_pgm' (ALMCOPY). You can send commands to the
  83. host if you also install a 'Command_pgm' (OS2CMD).
  84.  
  85.  
  86. Starting up Alpha
  87.  
  88. The syntax for starting up the Alpha programme is :-
  89.  
  90. [C:\] <START> ALPHA1 <file name> </p <profile name>> </m>
  91.  
  92. Where the option /m may be specified to cause the programme to be started
  93. minimised. This is intended for use in the 'STARTUP.CMD' file as an
  94. alternative to having the programme in the "Group - main" window, e.g.
  95.  
  96. START ALPHA1 /p /m
  97.  
  98. The option /p may be specified to cause the file of initial values of
  99. colours, font etc. to be read. The default file name for this profile is
  100. 'ALPHA.PRF'. This file may be used to set alternative start up values such
  101. as the keyword colours. If a file name is not supplied on the OS/2 command
  102. line then the first display will ask for the file name to be browsed.
  103. The Enter key or Enter button should be used to terminate the string, e.g.
  104.  
  105.         C:\WORK\TEST.A37<Enter_key>
  106.  
  107. On OS/2 V1.3 if Alpha is minimised or active with or without a file
  108. allocated and the file manager window is active then a selected
  109. file may be moved from the file manager window by dragging mouse button 2
  110. and releasing it over the Ω icon or main window.
  111. This will cause the new file to be allocated.
  112. On OS/2 V2.x a file from a Drives window may be dropped on to the Alpha
  113. Icon of the unstarted programme.
  114.  
  115.  
  116.  
  117.  
  118. note
  119. If the window fails to appear the error, WinGetLastError, is written to the
  120. OUTPUT device. This should be directed to a printer or file e.g.
  121. ALPHA >PRN | >file_name
  122.  
  123.  
  124. Description
  125. ===========
  126.  
  127. This programme may be used to browse any file with a record size <=256 and
  128. may also be used with language files such as :-
  129. 370, 386 assembler, PASCAL(Ada), PL/AS(PL/I, REXX), C, and FORTRAN
  130. programmes etc. on a PS/2 under OS/2 to help in analysing their structure.
  131.  
  132. The basic browse functions are :-
  133.  
  134. 1) Home - Move to top of file
  135. 2) End - Move to end of file
  136. 3) Page_up - scroll up 1 screen
  137. 4) Page_down - scroll down 1 screen
  138. 5) F7 - scroll up 1/2 screen
  139. 6) F8 - scroll down 1/2 screen
  140. 7) F19 (Shift+F7) - scroll left 1/2 screen
  141. 8) F20 (Shift+F8) - scroll right 1/2 screen
  142. 9) The Horizontal and Vertical scroll bars.
  143.  
  144. The mouse button 1 when pressed will isolate the addressed string using
  145. ' ', ',', '+' etc. as separators, and highlight it and all references in
  146. the window or as the file is browsed.
  147. In Locate mode if mouse button 1 is pressed twice (double clicked) then the
  148. isolated string will become a search argument. If mouse button 2 is pressed
  149. once (clicked) then the next occurrence of the search argument will be
  150. located. If mouse button 2 is double clicked then the search will start
  151. at the top of the file.
  152.  
  153. In Expand mode if mouse button 1 is double clicked then the search string
  154. is assumed to be a label or procedure name and a second window is opened
  155. with the procedure code provided the label/routine name can be found.
  156.  
  157. Search commands may be issued from the command window, which may be invoked
  158. by the F6 key or the system menu icon Alpha.
  159.  
  160. When the main window is displayed keywords which are associated with the
  161. file extension will be highlighted using the colours specified in the
  162. profile.
  163.  
  164. Note
  165. Up to 128 language keywords may be specified with their corresponding
  166. colour and the length of the record to be scanned. Only the first 16
  167. keywords on the line will be highlighted and the search order is the order
  168. specified in the profile. The keyword must be <=12 characters.
  169.  
  170. The File_type keyword in the profile may be used to introduce extra file
  171. types but the first 6 types are assumed to refer to :- 370 assembler, 386
  172. assembler, PASCAL, PL/AS, C, and FORTRAN in that order. With Flow on for
  173. language files branch flow lines will be drawn from 'Branch/GOTO'
  174. instructions to labels in the same window.
  175.  
  176. If the profile specifies Read_file=Yes, the default, then the file may be
  177. browsed as soon as the window is opened, performance then improves once
  178. the file is read in.
  179.  
  180.  
  181. Note
  182. Only the first 256 characters of a record are read. Once the file is read
  183. in there is an internal switch over. If a locate etc. was in progress at
  184. the time of the switch over the window may not display the line found;
  185. it may be necessary to repeat the command e.g. F5.
  186.  
  187. If the profile specifies Read_file=No then only 120 records from the file
  188. are read in to storage and scrolling takes place within this buffer unless
  189. F4+Ctrl is pressed when the whole file is read in to memory asynchronously.
  190. As the file is scrolled up/down extra pages are read in to the buffer.
  191. The affect is that on scrolling upwards, after the window is displayed,
  192. there may be a pause (hour glass symbol) while extra data is read in.
  193.  
  194. Small parts (<=window size) of the file may be remembered and redisplayed
  195. by using the Clipboard function. Drag the mouse with button 1 down over the
  196. lines to be saved and press Ctrl+Insert to save the highlighted lines.
  197. To redisplay the saved lines press Shift+Insert. The lines are displayed
  198. from the cursor position onwards. The highlighted records may be printed
  199. on LPT1 by pressing Insert+Alt.
  200.  
  201.  
  202. Function keys
  203. =============
  204.  
  205. The following keys are effective for the programme:-
  206.  
  207. Mouse button 1 will isolate and highlight the text. If button 1 is pressed
  208. twice then the highlighted string may then be used as a search argument by
  209. button 2.
  210.  
  211. Mouse button 2 will scan from the current position to the end of file for
  212. the locate string, i.e. the string isolated by button 1 or by use of a
  213. locate command from the command window (F6).
  214. If the mouse button 2 is pressed twice then the scan will start from the
  215. top of the file.
  216.  
  217. F1 is the help key.
  218.   F1+Alt will display/hide the current status. {The statement number is
  219. displayed in the TITLE bar. R indicates that the file is being read in
  220. to memory, S indicates that the programme structure is being recorded.}
  221. F2 will change the font. The System Monospaced font is the default font,
  222. unless the Alpha font is installed.
  223. F3 will terminate programme.
  224. F4 will allocate a new file
  225.   F4+Ctrl will read the currently assigned file in to memory.
  226.  
  227. Note
  228. A separate thread is attached to read in the file whilst the file may
  229. continue to be browsed within the 120 record buffer. The scrolling of the
  230. file will be much faster but there may be some degradation of performance
  231. while the file is read in to store. A maximum of 21,844 records can be read
  232. in if there is enough memory available. When the file is read in there is
  233. a beep of 1760HZ to indicate that the file has been read and one of 880HZ
  234. to idicate that the structure has been recorded, provided that "Quiet=No"
  235. is specified in the profile.
  236.  
  237. F5 will repeat the previous command
  238. F6 will issue a command.
  239.  
  240. Note
  241. This window may also be created from the system menu icon Alpha. A child
  242. window is created in to which may be typed the command.
  243.  
  244. F7 scroll up 1/2 screen.
  245. F8 scroll down 1/2 screen.
  246. F9 switch on/off comment suppression.
  247.     A sequence of blank or comment lines will be compressed to a single line
  248.     of  provided that he file is read in. The comment lines must begin with
  249.     characters specified in Comment_start and end with the characters
  250.     specified in Comment_end.
  251. F10 not used.
  252. F11 not used.
  253. F12 will move the mouse button 1 focus line {The line on which mouse button
  254.      1 was last pressed.} to the centre of screen.
  255.   F12+Ctrl will switch on/off the scale line in the centre of the window.
  256. F13 (shift+F1) will display the programme structure.
  257. F14 (shift+F2) will change the text colours.
  258. F17 (shift+F5) will locate the next Marker.
  259. F19 (Shift+F7) will scroll left 1/2 line.
  260. F20 (shift+F8) will scroll right 1/2 line.
  261. F24 (shift+F12) will reset the horizontal scroll, clear line markers etc.
  262. Page_Up will scroll up one page.
  263. Page_Down will scroll down one page.
  264. Home key will move to top of file.
  265. End  key will move to end of file.
  266. Insert+Ctrl will place mouse Button 1 drag area in Clipboard.
  267. Insert+Shift will copy Clipboard text to mouse Button 1 position - cursor.
  268. Insert+Alt will write the highlighted records to LPT1.
  269. Delete+Ctrl will remove the highlighted records, mouse button 1 display
  270. area, from the window display.
  271. Delete+Shift will restore the deleted records.
  272. The Up & Down arrow keys will move the cursor.
  273. The scroll arrows, slider etc. and Page up or Page down keys may be used
  274. for browsing.
  275.  
  276. Note
  277. If the mouse button 1 is kept depressed on the scroll bar arrows then the
  278. lines or characters will scroll until the button is released.
  279. If the file is not read in then the file size is estimated by adding 1000
  280. every time the internal array is filled.
  281. In this case the slider may move to the end of the vertical scroll bar
  282. before end_of_file is reached and then move up.
  283.  
  284. Enter key will terminate an input string or refresh the screen.
  285.  
  286. Help window
  287. -----------
  288. This window may be invoked by the F1 key or the Help button on the command
  289. window. The window may be scrolled by :-
  290.  
  291. Page_up - scroll up 1 screen
  292. Page_down - scroll down 1 screen
  293. Home - scroll to the top of the Help data
  294. End - scroll to the end of the Help data
  295. F7 - scroll up 1/2 screen
  296. F8 - scroll down 1/2 screen
  297. The Page_Up key word at the bottom of the window will scroll up 1 screen if
  298. selected by mouse button 1.
  299. The Page_Down key word at the bottom of the window will scroll down 1
  300. screen if selected by mouse button 1.
  301. The OS/2 help file, ALPHA.HLP, may be accessed by selecting '?' from
  302. the system menu.
  303.  
  304. The Help window may be cancelled by F3, the Cancel button or by Enter.
  305.  
  306.  
  307.  
  308. Allocate window
  309. ---------------
  310. The File Allocate window will be created by the F4 key or from the Allocate
  311. menu item of the command window. The file may be selected from the List box
  312. or typed in to the Entry box. The drive may be changed by selecting ¿aα from
  313. the List box or typing the drive letter followed by a ':' e.g. 'a:' in the
  314. Entry box. The Path may be changed by selecting a directory name from the
  315. List box or by typing the path name in the Entry box e.g. 'C:\WORK'.
  316. The COMBO box will hold the last three allocate texts which have been
  317. entered.
  318.  
  319. A host file may be received and allocated by entering
  320. '>H:fn ft fm PC_file_name'; this string is passed to Transfer_pgm (ALMCOPY)
  321. {without the '>' and with '/Q' appended} which must be installed on the PS/2.
  322. If Transfer_pgm fails the return code is displayed in red and the Entry text
  323. is left to be edited. If the requested file can not be allocated then the
  324. allocate window together with an error message will be displayed.
  325.  
  326. A host command may be executed by entering '<host command'; this string is
  327. passed to Command_pgm (OS2CMD) {without the '<'} which must be installed
  328. on the PS/2.
  329.  
  330. If the DosExecPgm call fails for either OS2CMD or ALMCOPY then the error
  331. code is displayed in black.
  332.  
  333. Note
  334. If the Allocate window can not be contained in the main window then it will
  335. be made sysmodal; i.e. it must be closed before other windows can be used.
  336. For 8515 type screens a more suitable value for the Window and Default_chr
  337. keywords in the profile might be Window=(0,120,1020,650) and
  338. Default_chr=(14,20) for example.
  339.  
  340. Command window
  341. --------------
  342. This window may be invoked by the F6 key or the system menu icon Alpha.
  343.  
  344. The following commands may be issued :-
  345. +n - scroll down n lines
  346. -n - scroll up n lines
  347. <n - scroll left n characters
  348. >n - scroll right n characters
  349. :n - go to record n
  350. / - Search for string, not case dependent, from the current position in the
  351.      file.
  352. " - Search for string, as typed, from the current position in the file
  353. ' - Search for string, as typed, from the current position in the file but
  354.     only in column 1
  355. (s-e)>file_name - will copy records from the current file starting at s and
  356.     ending with e to the file file_name.
  357.     file_name may be 'LPT2' etc., an existing file or a new file.
  358.    If the end record number is '*'  then the file is copied to end-of-file.
  359. (s-e)- - will remove the records from the window.
  360.  will cycle through the last 6 commands.
  361. The Delete|Backspace key will delete a character from the input text.
  362.  
  363. If the first character is invalid then the line will be filled red until it
  364. is deleted.
  365.  
  366. F3 or ENTER will close the window and enter the command.
  367.  
  368. The cancel button will remove the window; only this child window will
  369. receive input until it is terminated.
  370.  
  371. The Flow button will switch on/off the drawing of flow lines. These lines
  372. are drawn for language files from 'Branch/GOTO' instructions to labels
  373. within the window.
  374.  
  375. The Expand/Locate button will switch on/off the label expansion. The
  376. isolated label is expanded by locating the routine and opening a second
  377. window containing the code. The mouse button 1 must be pressed twice
  378. (double clicked) to cause the label to be located. A depth of 8 expand
  379. windows is allowed, and each window may be scrolled using the scroll bar,
  380. Page_Up, Page_Down, etc.
  381. The file must be read in to storage to use this facility. The Expand window
  382. may be closed by F3 or the CALL menu item when the main window will remain
  383. at the CALL. If the Routine menu is clicked then the main window will
  384. scroll to the expand text, i.e. the called code line may be passed back to
  385. the higher level window. The Locate menu or F6 will perform a case
  386. sensitive forward search from the current line+1.
  387. F5 will repeat the previous locate. If Button 2 is double clicked after
  388. moving to the expanded label then the window will be moved back to the
  389. previous line, i.e. return to point of call.
  390. The label searched for is succeeded by ":" for PLS and preceded by
  391. "FUNCTION" or   "PROCEDURE" in PASCAL. The label searched for is preceded
  392. by "char", "extern", "far", "int", "long", "pascal", "pointer", "short",
  393. "static" or "void" if the language type is C. The label searched for is
  394. preceded by "FUNCTION" or "SUBROUTINE" if the language type is FORTRAN.
  395. (The language keywords may be specified by the Language_operator keyword
  396. in the profile. The C language values, language 5, may be set by the
  397. Precedent_C keyword in the profile.)
  398.  
  399. The Mark button will switch on/off the drawing of user flow lines defined
  400. by the mouse button 1, or the setting of a marker. Up to 16 user lines or
  401. markers may be associated with the file. If mouse button 1 is double clicked
  402. then a marker will be associated with the line. If mouse button 1 is pressed
  403. once then it will delimit the ends of a flow line. The markers or flow
  404. lines remain associated with the record until F24 (Shift+F12) is pressed.
  405. The markers enable places within the file to be remembered and recalled by
  406. (Shift+F5).
  407.  
  408. The Options menu may be selected to change the state of the following
  409. options :-
  410.  
  411. Transient Options - reset when a new file is allocated.
  412.  
  413. Comment Suppression - replace a block of comment lines by one highlighted
  414. line of .
  415. Scale - place a scale line in the middle of the window.
  416. Statement_# - will display the current line number in the TITLE bar.
  417. Status - indicate in the top left of the window the current status of file
  418. reading etc.
  419.  
  420. Permanent Options - remain set when a new file is allocated.
  421.  
  422. Quiet - suppress the beep which indicates that the file is read in to
  423. storage.
  424. Read_file_when_allocated - when the file has been allocated read it in to
  425. storage by attaching a subtask. The file may be browsed whilst this is in
  426. progress but the reading of the file in to storage will be slower.
  427. Record_structure - For language files this will cause the recording of the
  428. calling structure when the file has been read.
  429. Tab - recognize tab characters, X'09', and skip to n*8.
  430. Proportional - use the font spacing for writing the characters rather than
  431. the character size; this will allow proportional fonts to be used however
  432. these are not suitable for displaying code.
  433. Keyword - allow or suppress the keyword highlighting.
  434.  
  435. The Allocate menu will create the Allocate window
  436.  
  437. The Structure menu may be used to display the call structure for 370,
  438. 386 assembler, PASCAL, PL/AS, C and FORTRAN programmes provided that the
  439. Record_structure option is effective when the file is read in.
  440. For 370 assembler the structure is based on BAL, BAS, DFHSTACK,
  441. for 386 assembler CALL, PROC instructions, for PASCAL PROCEDURE,
  442. FUNCTION, keywords, for C char, extern, far, int, long,
  443. pascal, pointer, short, static or void keywords, for PL/AS PROC,
  444. CALL, keywords, and for FORTRAN FUNCTION, SUBROUTINE, CALL
  445. keywords {Labels ƒ27 characters are ignored}. The C language keywords
  446. may be specified by the Precedent_C keyword in the profile, and the operators
  447. for the other languages by the Language_operator keyword.
  448. If an entry is selected from the Programme Structure List Box then the
  449. main window is scrolled to that line.
  450. The Print button may be used to print the contents of the List box on LPT1.
  451.  
  452. The Font menu may be used to dynamically change the font and character size;
  453. the change is not saved in the profile.
  454.  
  455. The Colour  menu may be used to dynamically change the text colours. The
  456. language keyword colours must be specified in the profile.
  457.  
  458. FONTs
  459. -----
  460. You can specify the initial/default font in the profile by using the Font
  461. keyword in the profile, or you can change the font dynamically by invoking
  462. the Font window.
  463.  
  464. You can use the System Monospaced, Helvetica, Roman and Courier fonts but
  465. the Courier font and the System Monospaced are the only monospaced fonts
  466. supplied with OS/2 V1.3. A monospaced font with point sizes 8,9,10,11,16
  467. & 20 is supplied with the ALPHA PACKAGE, which may also be used.
  468. The fonts are then requested by specifying Font="Alpha",(10) etc. in the
  469. profile.
  470. The font type or face_name and size may be selected by the Font and
  471. Character_size keywords in the profile. If a profile is not supplied then
  472. the "Alpha",(10) font will be used if it is installed and a character_size
  473. of (8,14) else the "System Monospaced",(10) font will be used and a
  474. character_size of (8,16). Outline fonts are not selectable.
  475.  
  476. If the point size is not specified then the font is selected by using the
  477. Character_size.
  478. Point sizes (1/72") are :-
  479. Courier (8,10,12), Roman (8,10,12,14,18,24),
  480. Helvetica (8,10,12,14,18,24),
  481. System (8,10,12, {8x8, 8x16,9x20),
  482. "Alpha" (8{8x12},9{9x10},10{8x14},11{11x12},16{12x16},20{12x20}).
  483. If the point size is specified but an image font does not exist for this
  484. nominal point size then the outline font, if available, will be used and
  485. scaled by the Character_size.
  486. The font may be requested by face_name, e.g. Font="Alpha",(8).
  487.  
  488.  
  489. Profile
  490. -------
  491. A profile may be specified defining the following keyword values :-
  492.  
  493. {Colours may take the values :-
  494. BLUE, DARKCYAN, BLACK, DARKBLUE, DARKPINK, DARKGRAY, DARKRED, DARKGREEN,
  495. BROWN, CYAN, RED, GREEN ,PINK, YELLOW, PALEGRAY, DEFAULT, WHITE}
  496.  
  497. Text_colour specifies the colour of the window text.
  498.  
  499. Highlight_colour is used for the isolate function of mouse button 1.
  500.  
  501. Locate_colour is used for the argument for the locate function.
  502.  
  503. Comment_colour - the first comment_colour is used for comment lines
  504. beginning, /*, {, *, ;, C  and for the 'scale' background.
  505. The second comment_colour is  used for the compressed comment line
  506. and for the Clipboard highlight.
  507.  
  508. Branch_colour is used for 370, 386 branch instructions.
  509.  
  510. Expand_colour is used for the text in the label expansion window.
  511.  
  512. Back_ground is use to specify the main window background colour.
  513.  
  514. File_type specifies the File types to be recognized. The string must be
  515. ▓64 characters and terminated by a comma. The first 6 types are
  516. used for :-
  517.    1 370 assembler
  518.    2 386 assembler
  519.    3 PASCAL, (Ada)
  520.    4 PL/S, PL/AS, PL/I  etc., (REXX)
  521.    5 C
  522.    6 FORTRAN
  523. For REXX files use :- "A37,ASM,PAS,CMD,C,FOR," and replace the PLS entries
  524. under the Language_colour keyword.
  525. For Ada  files use :- "A37,ASM,ADA,PLS,C,FOR," and replace the PAS entries
  526. under the Language_colour keyword.
  527.  
  528. Comment_start specifies the first two characters of the start of a comment.
  529. The string must be ▓12 characters.  The 6 pairs are used for :-
  530.    1 370 assembler
  531.    2 386 assembler
  532.    3 PASCAL, for Ada specify Comment_start="* ; --/*/*C "
  533.    4 PL/S, PL/AS etc.
  534.    5 C
  535.    6 FORTRAN
  536.  
  537. Comment_end specifies the last two characters of the end of a comment.
  538. The string must be ▓12 characters.  The 6 pairs are used as for
  539. Comment_start
  540.  
  541. Precedent_C specifies the C language procedure keywords. The string
  542. must be <=64 characters and terminated by a comma. E.g.
  543. Precedent_C="char,extern,far,int,long,pascal,pointer,short,static,void,"
  544.  
  545. Language_colour  defines the highlight colours for key words. Up to 128
  546. entries may be defined as follows :-
  547.  file_type,key_word,colour,scan_length
  548. and are terminated by .END, invalid entries are ignored.  The keywords
  549. must be <=12 characters.
  550.  
  551. Language_operator defines the operator keywords for each language.
  552. The second value indicates how to process the keyword, viz.
  553. < or > indicate the scan direction from the keyword to locate the label,
  554. 'P' or 'C' indicates that the keyword specifies an entry point or call,
  555. ':' indicates that the label will be followed by a colon,
  556. '2' indicates that the second label following a ',' is to be used.
  557. Up to 32 entries may be defined as follows :-
  558. file_type,<║>C║P[:][2],keyword
  559. and are terminated by '.END', invalid entries are ignored.
  560. The keywords must be <=12 characters. The C-language procedure
  561. values are supplied on the Precedent_C keyword.
  562.  
  563. Font  may take the values :-
  564. Courier|System|Helvetica|Roman|Alpha<,Bold|Italic><,(Point_size)> or a
  565. face name may be specified e.g. Font="Alpha",(10)
  566.  
  567. Character_size specifies the (width,height) of the characters.
  568. The character width is used to select the size of the Font if the  point
  569. size is not specified on the "Font" keyword.
  570.  
  571. Read_file takes the value Yes|No and specifies whether the file  is to be
  572. read in after allocation.
  573.  
  574. Flow takes the value On|Off and specifies whether to draw flow lines from
  575. branch statements to labels.
  576.  
  577. Expand takes the value On|Off and specifies that Expand mode will  be
  578. effective once the file is read in.
  579.  
  580. Marker takes the value On|Off  and specifies whether mouse button 1 will
  581. define marker values.
  582.  
  583. Language takes the values :-
  584.  *<,Language> {The '*' implies determine the language from the file suffix}.
  585. If a Language is also given then this will be the default if the file type
  586. can not be found in "File_type", e.g.
  587. Language=*,PAS. For PL/I, REXX use Language=PLS etc.
  588.  A37 - 370 assemble
  589.  ASM - 386 macro assemble
  590.  PAS - Pascal (Ada)
  591.  PLS - PL/S or PL/AS etc. (PL/I, REXX)
  592.  C   - C language
  593.  FOR - FORTRAN
  594.  
  595. Default_chr specifies the default character width and height used for
  596. scaling the Allocate and Command dialogue boxes. The default value is
  597. (10,16), for 8515, 8516 screens a default value of (14,20) is used.
  598.  
  599. Window  specifies the initial window position.
  600. If no profile is specified then Window=(0,4h,63.5w,26h)
  601. {(0,120,1020,650) for 8515/8516 screens} is assumed where w and h are
  602. the Default_chr width & height.
  603.  
  604. Quiet will suppress the beep on completion of file read.
  605.  
  606. Record_structure will record the CALL structure for 370 & 386 assembler,
  607. PASCAL, PL/AS, C and FORTRAN programmes, as the file is read in to memory.
  608.  
  609. Tab will use X'09' as the tab character to move to column n*8 when file is
  610. read.
  611.  
  612. Proportional  will use the Font character spacing rather than the Character
  613. width to place the characters.
  614.  
  615. Keyword will highlight the specified keywords.
  616.  
  617. Statement_number sets the display of the statement number On|Off.
  618.  
  619. Command_pgm specifies the programme name invoked by <.
  620.  
  621. Transfer_pgm specifies the programme name invoked by >.
  622.  
  623. Alpha has within it (hard coded) routines which understand certain language
  624. features e.g. 370 Assembler labels start in start in column 1, procedures are
  625. invoked by BAL, BAS etc. and PASCAL procedures are preceded by FUNCTION
  626. or PROCEDURE etc.. The keywords and their attributes may be set by the
  627. Language_operator keyword in the profile.
  628. There are 6 such languages 'understood' by Alpha, viz. :-
  629.  
  630.  1 370 Assembler
  631.  2 386 Assembler
  632.  3 PASCAL (Ada)
  633.  4 PL/AS (PL/I, REXX)
  634.  5 C
  635.  6 FORTRAN
  636.  
  637. Because Ada is similar to PASCAL and PL/I & REXX are similar to PL/AS,
  638. in respect to procedure calls etc., you can also analyse these languages
  639. by pretending they are type 3 & 4 respectively.
  640.  
  641. However, you can interpret any language/file type (use the highlighting
  642. facility) by suppling extra definitions in a profile which is specified as a
  643. parameter to Alpha e.g.
  644.  
  645.   START ALPHA1 /p profile_name
  646.  
  647. A sample profile (ALPHA.PRF) is provided in the package, which includes
  648. comments explaining the use of the keywords. This may be edited to change/add
  649. a file extension, highlighting and programme structure by modifying the
  650. following keywords :-
  651.  
  652. File_type - list of file extensions up to 32 characters
  653. Comment_start - list of comment start character pairs (blank is ignored)
  654.                 up to 12 characters.
  655. Comment_end - list of comment end character pairs (blank is ignored)
  656.                 up to 12 characters.
  657. Language_colour - list of keyword definitions
  658.   file_type,keyword,colour,maximum scan length
  659. Precedent_C - list of procedure keywords for language 5 which precede
  660. a procedure definition, up to 64 charcaters.
  661. Language_operator - list of operator definitions
  662.   file_type,attributes,keyword
  663.  
  664.  
  665. e.g. to add language XYZ with a routine call 'ICALL routine_name' and
  666. a structure similar to PL/S
  667.  
  668. File_type="A37,ASM,PAS,XYZ,C,"
  669. Language_colour
  670. XYZ,ICALL,DARKGREEN,72
  671. XYZ,Next_key ,RED,72
  672. .END
  673. Language_operator
  674. XYZ,>C,ICALL
  675. .END
  676.  
  677. Only the first 6 language types will allow the Expand, Flow and Structure
  678. operations to be effective. This implies that you could not use all the
  679. features of Alpha for a new language which did not have the call/label
  680. syntax of one of the existing languages.
  681.  
  682. The Alpha programme scans the keyword table in the order specified in the
  683. profile to the comment start in the record for a maximum of 16 found
  684. entries. A keyword_found array is created and the text is written by
  685. running down the array from the last to the first so if the entries
  686. in the profile were in the order :-
  687.  
  688. PLS, END LOOP,GREEN,72
  689. PLS, END,DARKCYAN,72
  690.  
  691. Then the 'END LOOP' would overwrite the 'END'; spaces are significant.
  692.                     
  693.  
  694.  
  695. Note for CICS users.
  696. --------------------
  697. CICS users may browse/analyse CICS code by using CRUISE
  698. on VM to access the correct level of CICS
  699. and saying 'CRUISE ( NOMENU O212' etc.
  700. (or saying '<CRUISE ( NOMENU O212' in the Allocate window).
  701.  
  702. Then from the ALPHA Allocate window issue :-
  703.  
  704. <HSXMOVE DFHZRAC O212-AC E TEMP A Z ( UNPACK 
  705. (to unpack the file )
  706.  
  707.  
  708. >H:TEMP A Z TEMP.A37 {to copy the file on to the PS/2}
  709.  
  710.  
  711. If you have an HSXUPROF or HSXPROF on your A-disk
  712. {there is a default one on the Y-disk}
  713. with an entry for ALMCOPY e.g.
  714.  
  715. hsx 'SET ACXFR56A ON '
  716.  
  717. hsx 'SET ACXFR54B ON '
  718.  
  719. Then issue 'HSXPROF ON' to load HSX on CMS,
  720. and ALMCOPY will unpack the file when transferring it to the PS/2 so
  721. you can omit the HSXMOVE step.
  722. The ISPCTOOL-200 disk should be accessed for ALMCOPY5
  723. {the CMS side of ALMCOPY}.
  724.  
  725. =================== End of ALPHA1.TXT ======================================
  726.  
  727.