Monday, April 6, 1992

          This package represents an advance in versatility for the
          TPU text editor.  Its specific ability is to call, on the
          fly, almost *any* RTL routine and return the results as an
          executable TPU statement.

          For example, if you want to get the value of a DCL symbol
          called FOO and put it into the TPU global variable BAR, you
          could execute the following TPU code:

               XX := CALL_USER( 0, 'LIB$GET_SYMBOL "FOO", BAR$');

          If the DCL symbol FOO has the value "Fiddle", then the TPU
          variable XX will contain the string

               BAR := "Fiddle"

          which can be used as a parameter to the TPU statement

               EXECUTE( XX)

          The whole thing can be done in one operation:

               EXECUTE( CALL_USER( 0, 'LIB$GET_SYMBOL "FOO", BAR$'));


          On to the syntax.

          The format for the CALL_USER statement is 

               string-out := CALL_USER( int, string-in);

          Although the integer is supposedly passed by reference, in
          practice it does not seem to come back modified.  So, we
          ignore it and pass a literal zero.  All of the work must be
          done according to the value of string-in.

          String-in is used to specify the shareable image file, the
          routine being called, and the argument list, in the format

               filespec>routine-name arg1, arg2, ...

          We'll examine the components of string-in separately.

            o  "filespec>" refers to the shareable image being
               accessed.  If it is omitted it defaults to "LIBRTL>".

            o  "routine-name" is just what it says.  The routine name
               must be declared UNIVERSAL within the shareable image.

            o  arguments can be of several forms, to indicate longword 
               or string, literals or variables.  

                 - longword literals are just numbers

                 - string literals must be enclosed in double quotes. 
                   Note that within the context of a TPU string, you
                   must either use single quotes to enclose the string
                   ('this is a "quoted" string') or double the double
                   quotes ("this is a ""quoted"" string").

                 - String variables (to be loaded by TPU upon return)
                   must be indicated by the suffix "$".

                 - Longword variables get the suffix "%".

               Variable names passed with suffixes to the callout
               routine will have their suffixes stripped in the return
               string. 

               A comma by itself indicates a null argument.

          Here is a more complete example.

PROCEDURE EVE_DATE
          !
          ! Insert a pretty date into the current buffer.
          !
          LOCAL				DAY,
                                        FULL_DATE,
                                        FULL_MONTH,
                                        MONTHS,
                                        RAW_DATE,
                                        RAW_MONTH
                                        WEEKDAYS;

          MONTHS := CREATE_ARRAY;
          MONTHS{ "JAN"} := "January ";
          MONTHS{ "FEB"} := "February ";
          MONTHS{ "MAR"} := "March ";
          MONTHS{ "APR"} := "April ";
          MONTHS{ "MAY"} := "May ";
          MONTHS{ "JUN"} := "June ";
          MONTHS{ "JUL"} := "July ";
          MONTHS{ "AUG"} := "August ";
          MONTHS{ "SEP"} := "September ";
          MONTHS{ "OCT"} := "October ";
          MONTHS{ "NOV"} := "November ";
          MONTHS{ "DEC"} := "December ";

          WEEKDAYS := CREATE_ARRAY( 7, 0);
          WEEKDAYS{ 0} := "Sunday, ";
          WEEKDAYS{ 1} := "Monday, ";
          WEEKDAYS{ 2} := "Tuesday, ";
          WEEKDAYS{ 3} := "Wednesday, ";
          WEEKDAYS{ 4} := "Thursday, ";
          WEEKDAYS{ 5} := "Friday, ";
          WEEKDAYS{ 6} := "Saturday, ";
          WEEKDAYS{ 7} := "Sunday, ";

          RAW_DATE := FAO( "!%D", 0);
          RAW_MONTH := SUBSTR( RAW_DATE, 4, 3);
          FULL_MONTH := MONTHS{ RAW_MONTH};
          DAY := SUBSTR( RAW_DATE, 1, 2);
          EDIT( DAY, COLLAPSE);
          EXECUTE( CALL_USER( 0, "LIB$DAY_OF_WEEK , TWW_EVE_TEMP%"));
          ! Note the null first argument...      ^^
          WEEKDAY := WEEKDAYS{ TWW_EVE_TEMP};
          FULL_DATE := WEEKDAY
                     + FULL_MONTH
                     + DAY + ", "
                     + SUBSTR( RAW_DATE, 8, 4);
          COPY_TEXT( FULL_DATE);
ENDPROCEDURE;

          To build the TPU$CALLUSER shareable image, execute the
          command procedure BUILD_CALLUSER.COM.  Then, define the
          logical name TPU$CALLUSER to point to the file
          TPU_CALLUSER.EXE, including the full directory spec.

          To build the EVALUATE shareable image, execute the
          command procedure BUILD_EVALUATE.COM.  Then, define the
          logical name TWW_EVALUATE to point to the file
          TPU_EVALUATE.EXE, including the full directory spec.
          Then, you can include code like 

          EXECUTE( CALL_USER( 0,
                   'TWW_EVALUATE>TPU_EVALUATE "5+3", ANSWER$, 0'));

          after which the global TPU variable ANSWER will contain "8".


          FILES IN THIS SAVE SET:

                00README.TXT;2     	This file

                BUILD_CALLER.COM;1 	builds CALLER.EXE for testing
                                        TPU_CALLUSER.EXE without TPU.

                BUILD_CALLUSER.COM;1	rebuild TPU_CALLUSER.EXE

                CALLER.BAS;2       	\_Test TPU_CALLUSER.EXE 
                                   	/ without TPU.

                CALL_DYNAMIC.BAS;3 	called by TPU_CALLUSER

                DESCRIP.MMS;10     	dependency file

                TPU_CALLUSER.BAS;5 	Main part of TPU_CALLUSER
                TPU_CALLUSER.OPT;3 	and its linker options file

                TPU_CALLUSER.EXE;3 	...and the executable