home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / sigm / sigmv021.ark / ENTRY.DOC < prev    next >
Text File  |  1984-04-29  |  6KB  |  182 lines
  1.             Documentation For Program ENTRY.COM
  2.  
  3.                              by
  4.                       Robert H. Harsch
  5.                      ph: (916) 487-2216
  6.              2362 American River Dr., Suite 311
  7.                    Sacramento, Ca. 95825.
  8.                     All rights reserved.
  9.  
  10.     A utility program to "automatically" insert entry points
  11. into SRC extenstion files for PASCAL/Z programs; thus, making
  12. easier the process of linking seperately compilied external
  13. pascal procedure/functions to main programs.
  14.  
  15. DIRECTIONS FOR USE OF PROGRAM WITH EXAMPLE:
  16.  
  17. 1. Create the main calling program.  For example
  18.    file MAINPRG.PAS:
  19.  
  20.     PROGRAM MAINPRG;
  21.     TYPE
  22.     VECTORTYPE = ARRAY [ 1..10 ] OF INTEGER;
  23.     
  24.     PROCEDURE SUM( VAR RESULT: INTEGER; VAR V: VECTORTYPE);    EXTERNAL; { external procedure reference, functions
  25.             may also be used accordingly }
  26.     VAR
  27.     I, RESULT: INTEGER;
  28.     VEC: VECTORTYPE;
  29.  
  30.     BEGIN { of main program }
  31.     FOR I:= 1 TO 10 DO
  32.         VEC[ I ]:= I; { initialize vector for example }
  33.     SUM(RESULT, VEC); { call external routine }
  34.     WRITELN(RESULT) { prints 55 as the answer }
  35.     END.
  36.  
  37.  
  38.  
  39.  
  40. 2. Create the external routine(s) from the text editor.
  41.    To continue the above example lets say we create
  42.    the file EXTERN.PAS:
  43.  
  44.     PROGRAM EXTERN; { external program procedure }
  45.     TYPE VECTORTYPE = ARRAY [ 1..10 ] OF INTEGER;
  46.     { parameters must be passed through the
  47.       procedure/function heading, not through global
  48.       variables }
  49.     PROCEDURE SUM( VAR RESULT: INTEGER; VAR V: VECTORTYPE);
  50.     VAR I: INTEGER;
  51.             {$i+ see complier directives, puts
  52.                  next line of source into file
  53.                  EXTERN.SRC after compliation }
  54.             {@SUM -- name of external routine }
  55.             {$i- turn off complier directive }
  56.         BEGIN
  57.             RESULT:= 0;
  58.             FOR I:= 1 TO 10 DO
  59.                 RESULT:= RESULT + V[I]
  60.         END; { of procedure sum }
  61.     BEGIN
  62.         { Dummy BEGIN and END exist only
  63.         for syntax purposes of compilation.
  64.         Never a main body of statements to execute. }
  65.     END.
  66.  
  67. 2. Type:
  68.     PASCAL EXTERN
  69.    compliation will proceed normally thus creating
  70.    files EXTERN.SRC, EXTERN.LST, but unfortunatley
  71.    there will be no entry points created for linking
  72.    the procedure heading declaration of the main program
  73.    with the externally called procedure sum.
  74.  
  75. 3. But since we compilied the file with the following inserted 
  76.    before the BEGIN of procedure sum (the entry point):
  77.         {$i+ }
  78.         {@SUM}
  79.         {$i- }
  80.    typing:
  81.     ENTRY EXTERN
  82.   executes the program and copies file EXTERN.SRC into
  83.   EXTERN.ZZZ, and adds the needed entry points into the
  84.   external routine so that assembly and linkage can
  85.   properly take place.
  86.  
  87. 3. Continuing with the example we type:
  88.     ERA EXTERN.SRC
  89.     REN EXTERN.SRC=EXTERN.ZZZ
  90.  
  91. 4. The EXTERN.SRC is now in proper form for assembly
  92.    (to produce EXTERN.REL) and linkage to produce the
  93.    executable COM file.
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100. SUMMARY OF DIRECTIONS USING THE ABOVE EXAMPLE.
  101.  
  102. 1. Create main calling module with declarations, as an example
  103.    here refered to as file MAINPRG.PAS.
  104.  
  105. 2. Create the external module to be called, as an example
  106.    here refered to as file EXTERN.PAS.
  107.  
  108. 3. Insert the following before the BEGIN of procedure sum in
  109.    file EXTERN.PAS:
  110.         {$i+ }
  111.         {@SUM}
  112.         {$i- }
  113.  
  114. 4. Type the following commands while in CP/M monitor or set up
  115.    a SUBMIT file:
  116.    A. Compile main calling program and produce files
  117.       mainprg.rel, mainprg.lst:
  118.         PASCAL MAINPRG
  119.         ASMBL MAIN,MAINPRG/REL
  120.  
  121.    B. Compile the external called program and set up entry
  122.       points, producing files extern.rel, extern.lst:
  123.         PASCAL EXTERN
  124.         ENTRY EXTERN
  125.         ERA EXTERN.SRC
  126.         REN EXTERN.SRC=EXTERN.ZZZ
  127.         ASMBL EMAIN,EXTERN/REL
  128.  
  129.    C. Link the main program with the external program,
  130.       producing the executable file mainprg.com:
  131.         LINK MAINPRG,EXTERN /N:MAINPRG /E
  132.  
  133.    D. Finally, typing the following will execute the program:
  134.         MAINPRG
  135.  
  136.  
  137.  
  138. ALGORITHM FOR ENTRY.COM:
  139.     1. Create an open file name.ZZZ as a file to write to
  140.        (will destroy an existing file name.ZZZ if present).
  141.     2. Open for reading the file name.SRC.
  142.     3. Print to monitor the names of files opened.
  143.     4. Read a line from file name.SRC.
  144.     5. If the line has the string '{@' followed by an 
  145.        identifier (the external procedure name) the
  146.        following two lines are written to file name.ZZZ:
  147.                 ENTRY    identifier
  148.         identifier:
  149.        An identifier is a alphabetic letter (a thru z, or
  150.        A thru Z) followed by zero or more alphanumeric
  151.        characters (a thru z, A thru Z, or 0 thru 9).  If
  152.        the identifier is greater than 6 character, the
  153.        identifier is then truncated to 6 characters and
  154.        convert lower-case characters to upper-case.
  155.         It is wise to make the external procedure name
  156.        (identifier) from one to six characters in length,
  157.        in upper-case, to avoid possible confusion.
  158.            Avoid conflict with labels or external libary
  159.        routines used by the compilier in the assembling 
  160.        process.  (Avoid all labels in the form L<digit(s)>,
  161.        e.g. L99, and labels referenced as external library 
  162.        routines, e.g. DIVD, by file MAIN.SRC).
  163.        The assembler will give you an error diagnostic
  164.        when you have made this mistake.
  165.         The external procedure name should not have the
  166.        the characters '_' or '$' in the identifier, even
  167.        though the compiler permits this the assembler does
  168.        not.  (The assembler will give you an error
  169.        diagnostic).
  170.  
  171.     6. If (4.) true above then print to monitor the
  172.        external procedure/function name.
  173.  
  174.     5. If (4.) above untrue then copy the line from file
  175.        name.SRC to file name.ZZZ.
  176.  
  177.     6. Repeat (2.) thru (5.) above until the label L99 is
  178.        found indicating the main body of program statements
  179.        between BEGIN END have been found, which we do not
  180.        want to copy (assembly with EMAIN will cause
  181.        errors).
  182.