OS/2 Professional/OS2PRO194.ISO/os2/prgramer/alpha/alpha2.hlp

OS/2 Help File | 1993-12-14 | 23.9 KB | 482 lines

ΓòÉΓòÉΓòÉ 1. Description ΓòÉΓòÉΓòÉ

*******************************************************************
*                                                                 *
* (C) Copyright International Business Machines Corporation 1993. *
*                 All rights Reserved.                            *
*                                                                 *
*******************************************************************


          Lionel de Lambert - Augustus MMDCCXLV AUC


              IBM United Kingdom Laboratories Ltd.

A simple 32 bit multi-document browse version of the Alpha code analysis
programme has been written using C Set/2 and MASM V6.0. The programme 'ALPHA2
EXEBIN' should be copied to an OS/2 V2.0 directory as ALPHA2.EXE. The Alpha
Fonts. may be used if the file 'ALPHA.FONBIN' is copied to an OS/2 V2.0
directory as ALPHA.FON.

This is a simple multiple document file browse with highlighting of keywords
for language types :- A37,ASM,PAS,PLS,C,FOR,..

The syntax of Alpha2 is :-

 START ALPHA2 [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 'ALPHA2 EXEBIN' to a
directory on your PS/2 as 'ALPHA2.EXE'.

If you want different highlight colours etc. you can copy the text file 'ALPHA
PRF' to the PS/2 as 'ALPHA.PRF' and edit the file. You can also install the
'Alpha' fonts by transferring the binary file 'ALPHA FONBIN' to the PS/2 as
'ALPHA.FON' and selecting 'System Setup' from 'OS/2 System' and use '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 from the OS2TOOLS disk.

If you wish to access the OS/2 help file, ALPHA2.HLP, it must be installed in
the HELP path.


ΓòÉΓòÉΓòÉ 3. Menu ΓòÉΓòÉΓòÉ

The Allocate item will invoke the Allocate. dialogue box which may be used to
allocate a file or invoke the Transfer programme.

The Command dialogue box may be used to issue a search command.

The Options menue may be used to set the following options :- Statement No.,
Tab, Keyword, Include, Grid.

The Font item will invoke the Font dialogue box.

The Colour item will invoke the Colour dialogue box.

The Print item will invoke the print dialogue box.

The Window item will invoke the window selection dialogue box.

The Help item will invoke the About dialogue box, the Help window, and the OS/2
extended help function.


ΓòÉΓòÉΓòÉ 3.1. Allocate ΓòÉΓòÉΓòÉ

The Allocate dialogue box is 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 Entry 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.

The search starts from the current line number +1.

The COMBO box will hold the previous three search strings which were
successfully entered.


ΓòÉΓòÉΓòÉ 3.3. Options ΓòÉΓòÉΓòÉ

The Options menue may be used to set the following options :-

o Statement No. - display the statement number in the TITLE bar followed by the
  last character position from mouse button 1.

o Tab - expand the record by using X'09' characters to round to columns n*8.

o Keyword - highlight the keywords.

o 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 <file_name>, 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. }

o Grid - Draw vertical grid lines through every tenth character in Grid colour.


ΓòÉΓòÉΓòÉ 3.4. Font ΓòÉΓòÉΓòÉ

The Font dialogue box may be used to change and remember the font.


ΓòÉΓòÉΓòÉ 3.4.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 font menu . On OS/2 V2.0 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.5. Colours ΓòÉΓòÉΓòÉ

The colours of the text, comments etc. may be changed and remembered by using
this window. The following colours may be changed with this dialog box :-

 1. Text - The main text colour.

 2. Highlight - The mouse button 1 isolate keyword.

 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 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.


ΓòÉΓòÉΓòÉ 3.6. 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.7. Window ΓòÉΓòÉΓòÉ

The Window menu may be used to close all child windows or to arrange them so
that the title text is visible, Cascade, or so that a partial view of each
child may be seen, Tile. The Select window option will show the selected
window. {If the window title is selected from the List box then that child
window will become the active/visilble one.}


ΓòÉΓòÉΓòÉ 3.8. Help ΓòÉΓòÉΓòÉ

The Help menu will display the About, box the Help summary window or access the
OS/2 help file ALPHA2.HLP via Extended.


ΓòÉΓòÉΓòÉ 3.8.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 screen

 2. Page_down - scroll down 1 screen

 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
search for this string from the current line +1. 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 Font dialogue box.

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 screen.

F8 will scroll the window down 1/2 a screen.

F12 will reset the Collapse of BEGIN/END pairs etc.

F14 (F2+Shift) will open the Colour dialogue box.

Page_Up will scroll up 1 screen.

Page_Down will scroll down 1 screen.

Home will scroll to the top of the file.

End will scroll to the end of the file.

 - will scroll down one line

 - will scroll up one line

 - will scroll right one column

 - will scroll left one column

The Insert+Ctrl keys will copy the lines highlighted by the button 1 drag area
to the Clipboard.

The Delete+Ctrl keys will suppress the lines highlighted by the button 1 drag
area from the display.

The Delete+Shift keys will restore the lines previously hidden.

The S+Ctrl keys will record and display the programme structure.

The n+Ctrl keys will move to a recorded a 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 key words. Up to 128 entries
may be defined as follows :-

 file_type,key_word,colour,scan_length

and are terminated by .END, invalid entries are ignored. The key words must be
=<12 characters.

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
  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,4h,63.5w,26h) {(0,120,1020,650) - for 8515/8516 screens} is assumed
where w and h are the Default_chr width & height.

If the window is resized then its position 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 ΓòÉΓòÉΓòÉ

Alpha2 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 ALPHA2 /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,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.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

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.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

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.

The colours following WHITE will not be available on VGA screens.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The Help file ALPHA2.HLP must be installed in the HELP path.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

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. 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.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

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.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

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; may also be used.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

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.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

If you wish to access files from the host then you should also install a
programme such as ALMCOPY. 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