═══ 1. Description ═══ (C) Copyright International Business Machines Corporation 1993. All rights Reserved. Augustus MMDCCXLV AUC IBM United Kingdom Laboratories Ltd. This is a simple 32-bit configurable multi-document highlighting editor version of the software analysis programmes which were written together with the CMS programme ANALYSE in order to establish the prСcognita for the CICS restructure project. This version has been written using C Set/2 and MASM V6.0. The programme 'ALPHA.EXE' should be copied to an OS/2 V2.x directory. The Alpha Fonts may be used if the file 'ALPHA.FON' is copied to an OS/2 V2.x directory and installed. provides basic browse and edit functions, will invoke the appropriate compiler, display the programme call structure, cross-reference labels, highlight keywords and expand the procedure calls in a secondary window for language types :- A37,ASM,PAS,(PLS,PLX,PLI),(C,CPP,H),FOR,IPF,.. {Other languages or file extensions may be defined.} The syntax of Alpha is :- START ALPHA [file] [/p [profile name - default ALPHA.PRF]] A file may be opened from the Allocate menu or by dragging mouse button 2 with the Ctrl key pressed from a Drives window on to the Alpha window. The mouse buttons may be used to isolate a string and to search for the string within the file. Browse commands may also be entered from the command window. The Language_colour, Language_operator, Precedent_C, File_type, Comment_start, Comment_end, Transfer_pgm and Window keywords are the only ones which are recognized from the Profile. ═══ 2. Installation ═══ The minimum requirement is to transfer the binary file 'ALPHA.EXE' to a directory on your PS/2. If you want different highlight colours etc. you can edit the file 'ALPHA.PRF' and specify the parameter /p. You can also install the 'Alpha' fonts by transferring the binary file 'ALPHA.FON' to a directory on the PS/2 and selecting 'System Setup' from 'OS/2 System' and using 'Add' in the 'Edit font' of the 'Font Palette'. If you wish to access files from the host then you should also install a Transfer_pgm such as ALMCOPY. If you wish to access the OS/2 help file, ALPHA.HLP, it must be installed in the HELP path, e.g. the C:\OS2\HELP directory. ═══ 2.1. Parse exit module ═══ An optional procedure may be provided in a DLL which will be called when the child window text is being written. If the DLL, ALPHAE.DLL, has been provided in the LIBPATH then the procedure Alpha_parse_exit will be called from the WM_PAINT child window call. A sample source module ALPHAE.C is provided which may be used to create a DLL with a parser exit module. The text can be written out by the DLL module if it has been provided in the LIBPATH. ═══ 3. Menu ═══ The following menu items are available :- Item Description Allocate Will invoke the Allocate. dialogue box which may be used to open a file, invoke the Transfer programme or save the profile name. Command Will create the command dialogue box which may be used to issue a search command. Options Will allow the following options to be set :- Statement No., Tab, Keyword, Include, Grid, Box, Tool bar. Print Will invoke the print dialogue box. Window Will invoke the window selection dialogue box. Configure Will invoke the Configure Notebook. Help Will invoke the About dialogue box, the Help summary window, and the OS/2 extended help function. ═══ 3.1. Allocate ═══ The Allocate dialogue box may be used to request a file to be read. If the drive letter is changed then the OK button should be used to refresh the List boxes. {The maximum number of child windows is 16.} The Profile button will remember the file name entered in the COMBO box as the profile for subsequent invocations. {This will obviate the need for the '/p' parameter and enable a file to be dropped on to the unstarted programme.} The Transfer button will pass the contents of the Combo box to the Transfer_pgm. {The data is passed to the Transfer_pgm unmodified.} ═══ 3.2. Command ═══ The Command dialogue box may be used to issue a search command e.g. o Case sensitive search for a string. o Case sensitive search for a string in column one. o A non-case sensitive search for a string, { Normal }. o Move to a given line number, { Goto }. o Replace the text at the current cursor position with the text from the Replacement Text Entry Box. The search starts from the current cursor position +1. The COMBO box will hold the previous three search strings which were successfully entered. ═══ 3.3. Options ═══ The Options menu may be used to set the following options :- Option Description Statement No. Display the statement number in the TITLE bar followed by the last character position from mouse button 1. Tab Expand the record by using X'09' characters to round to columns n*8. Keyword Highlight the keywords. Include For the files MASM, PAS, PLS, C read the include files specified by :- include file_name, {$INCLUDE : 'file_name' }, %INCLUDE first_part_of_file_name;, #include , respectively when expanding a call etc. {The current directory together with the paths defined by the INCLUDE environment variable will be searched. The total number of open files/windows is limited to 16 so the include nesting can not exceed 16-the number of open windows. For language 4, PL/S, the file extension is appended to the first_part_of_file_name. } Grid Draw vertical grid lines through every tenth character in Grid colour. Box Switch the select area to a box format. Tool bar Display the Tool bar. ═══ 3.4. Print ═══ The Print dialogue box will allow you to print the specified record range or the highlighted area in the active window to one of :- LPT1, LPT2, LPT3. The default record range is the whole file. ═══ 3.5. Window ═══ The Window menu will give access to the following :- Item Description Cascade Will arrange the child windows so that the title text is visible. Tile Will arrange the child windows so that a partial view of each child may be seen. Close All Will close all child windows. Select Window Will show the selected window. {If the window title is selected from the List box then that child window will become the active/visible one.} File name The first six child windows may be selected to become the top child window. ═══ 3.6. Configure ═══ The Configure Notebook may be used to modify the text colour, the text font or configure the Tool bar; it contains the following pages :- 1. C - Set the text colours. 2. F - Set the text font. 3. T - Configure the Tool bar. ═══ 3.6.1. Font ═══ The Font dialogue box, which may be chosen from the Configure Notebook page F, may be used to change and remember the font. Outline fonts are not selectable. The Alpha fonts may be used if they have been installed. ═══ 3.6.1.1. Fonts ═══ A monospaced font with point sizes 8,9,10,11,16 & 20 is supplied with the ALPHA PACKAGE, which may also be used. The Alpha font will be selected by default or may be chosen from the Configure Notebook page F . To instal the Alpha fonts on OS/2 V2.x select 'System Setup' from 'OS/2 System' and use 'Add' in the 'Edit font' of the 'Font Palette'. The font point sizes (1/72") are :- Courier (8,10,12), Roman (8,10,12,14,18,24), Helvetica (8,10,12,14,18,24), System (8,10,12, {8x8, 8x16, 9x20}), "Alpha" (8{8x12}, 9{9x10}, 10{8x14}, 11{11x12}, 16{12x16}, 20{12x20}). ═══ 3.6.2. Colours ═══ The colours of the text, comments etc. may be changed and remembered by using this dialogue box. The following colours may be changed :- 1. Text - The main text colour. 2. Highlight - The mouse button 1 isolate keyword colour. 3. Locate/Position - The mouse button 2 locate string, the character position of the last mouse button 1 click and the Structure List box procedures. 4. Comment/statement# - The Comment colour, statement number and Structure List box calls. 5. Background - The main text background colour. 6. Branch - The Branch/Jump instruction colour. 7. Grid - The vertical grid line colour. 8. Select area - The mouse button 1 drag area colour. 9. Help balloon - The Tool bar Help balloon background colour. 10. Comment background - The comment background colour. ═══ 3.6.3. Configure Tool bar ═══ The Configure Tool bar dialogue box, page "T" of the Configure Notebook, may be used to Delete or Add buttons to the Tool bar and to change its size and orientation. The Configure Notebook may be invoked from the main window menu. o The Buttons List box contains the available buttons; one should be selected and the Add button pressed to add it to the Tool bar. {The text of the Buttons already in the Tool bar is displayed halftone}. o The Tool bar List box shows the current list of buttons in the Tool bar; one should be selected and the Delete button pressed to remove it. o The Entry box displays the current button size which may be changed. o The Horizontal and Vertical Radio buttons will cause the Size Entry box to be read and the floating Tool bar to be reconstructed. o The Menu Radio button will cause the Tool bar to be placed in a menu bar the next time Alpha is started. o The Configure button will cause the changes to be applied. o The Cancel button will cause the changes to be ignored. The new Tool bar structure will be remembered when Alpha is closed. If the Tool bar is changed from floating to menu then Alpha should be closed and restarted. ═══ 3.7. Help ═══ The Help menu will display the About, box the Help summary window or access the OS/2 help file ALPHA.HLP via Extended. ═══ 3.7.1. Help window ═══ This window may be invoked by the F1 key or by selecting the Help item from the Help menu item. The window may be scrolled by :- 1. Page_up - scroll up 1 window 2. Page_down - scroll down 1 window 3. Home - scroll to the top of the Help data 4. End - scroll to the end of the Help data 5.  - scroll down one line 6.  - scroll up one line The Extended help data may be accessed from the Extended item of the Help menu. ═══ 4. Function keys ═══ The mouse button 1 will highlight a string and mouse button 2 will cause a case sensitive search for this string from the current cursor position +1, {if the Ctrl key is held down the search is non-case sensitive}. If the Ctrl key is held down when mouse button 1 is clicked then the current line may be edited. If mouse button 1 is clicked twice on a label then a search from the top of the file is made for the label definition or procedure entry and a secondary window is opened, Expand. {The language structure tables are searched first so if you have specified some structure keywords via Language_operator then you will have to record the structure first, Ctrl+s.} If mouse button 1 is clicked twice on a BEGIN for PASCAL, DO for PLS or { for C then the code up to the following END etc. will not be displayed. These lines may be restored by double clicking on the suppressed line, or by F12. If button 1 is clicked twice on an Include statement when the Include option is selected then a second window will be created with the include file. The mouse button 1 may be used to scroll and select a section of the file. F1 will open the Help window. F2 will open the Configure Notebook. F3 will terminate the programme. F4 will open the Allocate or file dialogue box. F5 will repeat the previous command. F6 will open the Command dialogue box. F7 will scroll the window up 1/2 a window. F8 will scroll the window down 1/2 a window. F12 will reset the Collapse of BEGIN/END pairs etc. and place the cursor at the top left in the window. Page_Up will scroll up 1 window. Page_Down will scroll down 1 window. Home will scroll to the top of the file. End will scroll to the end of the file. Enter will repaint the current child window, and reset the cursor to the leftmost position.  - will scroll down one line  - will scroll up one line  - will scroll right one column  - will scroll left one column Note: Hold the Shift key down to select an area with the arrow keys. The Tab key will advance the cursor to the next tab position, (8n). The Tab+Shift keys will reset the cursor to the leftmost position; before the start of the line. The Insert key will toggle the Insert/Overwrite mode for modifying characters in the Child window at the current cursor position. The Insert+Shift keys will insert records from the Clipboard at the current cursor position. {The maximum number of lines which can be inserted from the Clipboard is approximately half the size of the file.} The Insert+Ctrl keys will copy the lines highlighted by the button 1 drag area to the Clipboard. The Delete key will delete the character or the select area at the current cursor position. The Delete+Shift keys will delete the select area at the current cursor position and copy it to the Clipboard. The Space+Ctrl keys will clear the selected area to blanks. The b+Ctrl keys will re-insert the last deleted records. The c+Ctrl keys will suppress/display the comments in a language file. If a single line is scrolled then the comment suppression will be disabled. The c+Ctrl+Shift keys will compile the current file. The e+Ctrl keys will edit the current line. The h+Ctrl keys will suppress/restore the lines highlighted by the button 1 drag area from the display. The s+Ctrl keys will record and display the programme structure. The s+Ctrl+Shift keys will save the last active window/file in the file name specified in the Entry box. The x+Ctrl keys will display the record references to the highlighted label. If an entry is selected the last active child window will be scrolled to that line. The n+Ctrl keys will move to a recorded bookmark in the file. {Where "n" is one of the numeric keys 0-9.} The n+Alt keys will record a bookmark in the file. ═══ 5. Profile ═══ The following keywords may be specified in the profile :- Language_colour defines the highlight colours for keywords. Up to 255 entries may be defined as follows :- file_type,keyword,colour,scan_length and are terminated by .END, invalid entries are ignored. The case and spaces within the keyword are significant, {the first character of the keyword is used for the initial scan so a leading space will slow down the screen refresh rate}. The keywords must be <=12 characters. For PL/X(PL/S) and PASCAL, languages 3 and 4, the record is folded to upper case before searching for keywords. Comment_start specifies the first two characters of the start of a comment. The string must be =<12 characters. The 6 pairs are used for :- 1 370 assembler 2 386 assembler 3 PASCAL, for Ada specify Comment_start="* ; --/*/*C " 4 PL/S, PL/AS etc. 5 C 6 FORTRAN Comment_end specifies the last two characters of the end of a comment. The string must be <=12 characters. The 6 pairs are as in Comment_start. File_type specifies the File types to be recognized. The string must be <=64 characters and terminated by a comma. The first 6 types are used for :- 1 370 assembler 2 386 assembler 3 PASCAL, (Ada) 4 PL/S, PL/AS, PL/I etc., (REXX) 5 C, CPP 6 FORTRAN For REXX files use :- "A37,ASM,PAS,CMD,C,FOR," and replace the PLS entries For Ada files use :- "A37,ASM,ADA,PLS,C,FOR," and replace the PAS entries Language_operator defines the operator keywords for each language. The second value indicates how to process the keyword, viz. '<' or '>' indicate the scan direction from the keyword to locate the label 'P' or 'C' indicates that the keyword specifies an entry point or call, ':' indicates that the label will be followed by a colon, '2' indicates that the second label following a ',' is to be used. Up to 32 entries may be defined as follows :- file_type,<|>C|P[:][2],keyword and are terminated by .END, invalid entries are ignored. The keywords must be <=12 characters. {The C-language procedure values are supplied on the Precedent_C keyword.} Precedent_C specifies the C language procedure keywords. The string must be <=64 characters and terminated by a comma. Window specifies the initial window position. If no profile is specified then Window=(0,60,420,635) is assumed. When is closed its position and size will be remembered. Transfer_pgm specifies the programme name to be invoked from the Allocate menu when the Transfer button is pressed. ═══ 5.1. Specifying a language ═══ Alpha has within it (hard coded) routines which understand certain language features e.g. 370 Assembler labels start in start in column 1, procedures are invoked by BAL, BAS etc. and PASCAL procedures are preceded by FUNCTION or PROCEDURE etc.. There are 6 languages understood by Alpha, viz. :- 1 370 Assembler 2 386 Assembler 3 PASCAL (Ada) 4 PL/AS (PL/I, REXX) 5 C 6 FORTRAN Because Ada is similar to PASCAL and PL/I & REXX are similar to PL/AS, in respect to procedure calls etc., you can also analyse these languages by pretending they are type 3 & 4 respectively. However, you can interpret any language/file type (use the highlighting facility) by suppling extra definitions in a profile which is specified as a parameter to Alpha e.g. START ALPHA /p profile_name A sample profile (ALPHA.PRF) is provided in the package, which includes comments explaining the use of the keywords. This may be edited to change/add a file extension, highlighting and programme structure by modifying the following keywords :- File_type - list of file extensions up to 64 characters Comment_start - list of comment start character pairs (blank is ignored) up to 12 characters Comment_end - list of comment end character pairs (blank is ignored) up to 12 characters Language_colour - list of keyword definitions file_type,keyword,colour,maximum scan length Language_operator - list of operator definitions file_type,attributes,keyword e.g. to add language XYZ with a routine call 'ICALL routine_name' with a structure similar to PLS. File_type="A37,ASM,PAS,XYZ,C,FOR," Language_colour XYZ,ICALL,GREEN,72 XYZ,Next_key ,(RED,YELLOW,UNDERLINE),72 Language_operator XYZ,>C,ICALL Only the first 6 language types will allow the Expand and Structure operations to be effective. This implies that you could not use all the features of Alpha for a new language which did not have the call/label syntax of one of the existing languages. The Alpha programme scans the keyword table in the order specified in the profile to the comment start in the record. ═══ 6. Tool bar ═══ The Tool bar may be used to set an option etc. quickly. The position and state of the Tool bar will be remembered when is closed. The following buttons are available :- o - Hide/re-instate highlighted records from display. o - Display/Create the structure List box. o - Toggle statement No. display. o - Cascade Child windows. o - Tile Child windows. o - Toggle Tab expansion. o - Toggle Include option. o - Repeat last Locate command. o - Display the record references to the highlighted label. o - Suppress/display the comments in a language file. If a single line is scrolled then the comment suppression will be disabled. o - Edit the current line. o - Save the file using the file name from the Entry box. o - Compile the file with the command selected from the COMBO box. o - Copy highlighted records to Clipboard. o - Copy the selected records to the Clipboard and erase from memory. o - Insert records from the Clipboard at the current cursor position. o - Delete the selected records from memory. o - Re-insert the last deleted records. o - Clear the select area to blanks. o - Switch the select area to/from a box format. If mouse button 2 is held down on a button then a small help balloon will be displayed. The structure of the Tool bar may be modified by using the Configure Tool bar page of the Configure Notebook. ═══ ═══ The C language keywords may be specified by the Precedent_C keyword in the profile, and the operators for the other languages by the Language_operator keyword. ═══ ═══ The colours may take the values :- BLUE, DARKCYAN, BLACK, DARKBLUE, DARKPINK, DARKGRAY, DARKRED, DARKGREEN, BROWN, CYAN, RED, GREEN ,PINK, YELLOW, PALEGRAY, DEFAULT, WHITE, ORANGE, PURPLE, PALEGREEN, PALEBLUE, COLOUR1. The last five colours will not be available on VGA screens. The COLOUR1 value may be set by the slider bars and will be remembered when is closed. ═══ ═══ The Help file ALPHA.HLP must be installed in the HELP path. ═══ ═══ If mouse button 1 is held down whilst the mouse is dragged to the bottom or top of the window the area will be shaded in the Select area colour. A complete line will be selected if the start position precedes the first character of a line and the end position precedes the start of the following line. The highlighted area may then be deleted, copied to the Clipboard etc.. If the mouse pointer is held at the bottom or top of the screen then the window will scroll until the mouse button is released or the pointer moved back within the window. ═══ ═══ The Structure dialog box will display the call structure for 370, 386 assembler, PASCAL, PL/AS, C and FORTRAN programmes based on the Language_operator, Precedent_C, and File_type keywords from the profile. The Procedure entry names are displayed in the "Locate" colour and and the calls in the "Comment" colour. If an entry is selected from the Structure List Box then the last active window is scrolled to that line. The Print button may be used to print the contents of the List box on LPT1. If the file contains Tab characters then Tab expansion should be active before the structure tables are built. ═══ ═══ The colours may take the values :- BLUE, DARKCYAN, BLACK, DARKBLUE, DARKPINK, DARKGRAY, DARKRED, DARKGREEN, BROWN, CYAN, RED, GREEN ,PINK, YELLOW, PALEGRAY, DEFAULT, WHITE. For XGA screens etc. the colours :- ORANGE, PURPLE, PALEGREEN, PALEBLUE, COLOUR1; may also be used. {The value of COLOUR1 may be set by adjusting the sliders on the Colour dialogue box.} ═══ ═══ Because PL/I is similar to PL/AS you can use this file type for PL/I files. For REXX files, extension ".CMD", replace PLS by CMD in the File_type and replace the PLS entries in the Language_colour by the CMD entries. {Only "CALL" or "call" subroutine calls will be recognized.} For Ada files, extension ".ADA", replace PAS by ADA in the File_type and replace the PAS entries by the ADA entries in the profile. Also specify Comment_start="* ; --/*/*C " for the Ada comment start characters. ═══ ═══ If you wish to access files from the host then you should also install a programme such as ALMCOPY {from OS2TOOLS}. The programme name may be specified in the Profile. The data from the COMBO box is passed unmodified to the Transfer Programme, e.g. H:ALPHA SCRIPT A ALPHA.SCR ═══ ═══ The current line is the top line in the window unless button 1 has been pressed when the cursor will indicate the line. ═══ ═══ o The Multi-Line Entry box may be used to modify the current line or add new lines. The number of lines added is the No. of lines in the MLE. o The Modify button will replace the current line with the contents of the MLE. o The Undo button will undo the changes to the MLE. o The Cancel button will leave the current line unchanged. o The number on the left shows the current cursor position in the MLE. o The number on the right shows the current pointer, mouse, position in the MLE. If major modifications, {The Multi-line Entry field will only accept approximately half the number of lines in the file at a time}, are to be made to the file then a purpose built editor should be used. The maximum record size allowed is 256. ═══ ═══ If the file extension is an alias the names must be placed in parenthesis, e.g. "A37,ASM,PAS,CMD,(C,CPP),FOR," ═══ ═══ The command displayed in the Compile dialogue box will be scanned and the % replaced by the file name from the file Entry box. The resultant command will be executed when the Execute button is pressed. The Standard Output for the Child process will be written to the "Output" MLE. The programme name is formed by appending ".EXE" to the first name of the command line. If the command line is modified then it will be remembered when Alpha is closed. ═══ ═══ ═══ ═══ The colour may be the text colour value or an expression, viz. :- (,,) The value UNDERLINE will select the underscore font. ═══ ═══ The Box form of the select area will cause the button 1 drag area to form a box shape. The paste function will overwrite the appropriate size box area starting with the cursor position as the top left of the box. ═══ ═══ If a file has been modified without saving when Alpha is closed or the child window is closed a dialog box will be created with the options of Continue or Cancel. o Continue will continue the operation of closing without saving. o Cancel will stop the current operation of closing so that the file may be saved.