Using Abel's Call User Functions Jef Kennedy 24-Feb-87 VAXTPU is a powerful editing language, but alone is not capable of performing many functions. There is, however, a method to access these otherwise inaccessible functions; through the CALL_USER interface. Abel takes advantage of CALL_USER. This document shows you how you can use CALL_USER in your own routines. For information regarding the mechanics of using the CALL_USER command in VAXTPU, check the VAXTPU Reference Manual. Format of the CALL_USER built-in -------------------------------- Remember from the VAXTPU Reference Manual's description of CALL_USER... FORMAT string2 := CALL_USER (integer, string1) PARAMETERS integer -- The integer that is passed to the user-written program by reference string1 -- The string that is passed to the user-written program by descriptor Abel uses the integer to tell the CALL_USER program what to do. There are variables predefined in Abel that represent these integer values (the actual numeric values are not important to us). Different functions will use string1 and string2 in different ways. Abel CALL_USER Functions ------------------------ Following is a list of the function codes that may be used in integer, and how they use string1 and string2: Basic Functions --------------- Function Description (use of string1 and string2) -------- ---------------------------------------- CU$ECHO This will echo string1 to string2; functionally it doesn't do much but provides a test to make sure CALL_USER is set up properly. CU$ERROR This forces execution of the ON_ERROR routine in the procedure if there is one; it does not use string1 or string2. Sort Functions -------------- CU$INIT_SORT Initializes key for sorting (sorting position = 1, key length = 132; does not use string1 or string2. A call to this routine is mandatory before any sorting can be done. CU$SORT_POSITION Identifies the starting position of the sort key. A call to this routine is optional. CU$SORT_LENGTH Identifies the length of the sorting key. A call to this routine is optional. CU$SORT_ORDER Identifies the sort order. A call to this routine is optional. CU$BEGIN_SORT CU$RELEASE_REC CU$SORT_MERGE CU$RETURN_REC CU$END_SORT Floating Point Math Functions ----------------------------- CU$CLEAR Clears the accumulator of any previous value if none is specified in string1, or sets the accumulator to the value in string1; returns the current value of the accumulator in string2. CU$ADD Adds the value in string1 to the current contents of the accumulator; returns the new value of the accumulator in string2. CU$SUBTRACT Subtracts the value in string1 from the current contents of the accumulator; returns the new value of the accumulator in string2. CU$MULTIPLY Multiplies the value in string1 to the current contents of the accumulator; returns the new value of the accumulator in string2. CU$DIVIDE Divides the value in string1 into the current contents of the accumulator; returns the new value of the accumulator in string2. CU$SQRT Take the square root of the current contents of the accumulator; string1 is not used; returns the new value of the accumulator in string2. CU$EQUALS Returns the current contents of the accumulator in string2 with the number of decimal places defined by string1. From the _VAX/VMS_Volume_3B_, _VAXTPU_Reference_ (Digital Equipment Corporation, April 1986) CALL_USER This built-in allows you to call a program written in another language from within VAXTPU. The CALL_USER parameters are passed to the external routine exactly as you enter them; VAXTPU does not process the parameters in any way. The integer is passed by reference, and string1 is passed by descriptor. String2 is the value returned by the external program. FORMAT string2 := CALL_USER (integer, string1) PARAMETERS integer -- The integer that is passed to the user-written program by reference string1 -- The string that is passed to the user-written program by descriptor In addition to returning a value (string2) to CALL_USER, the external program returns a status code that tells whether the program executed successfully. You can trap this status code in an ON_ERROR statement. An even numbered status code (low bit in R0 clear) will cause the ON_ERROR statement to be executed. To use the CALL_USER built-in, follow these steps: . Write a program in whatever language you choose. The program must be a global routine called TPU$CALLUSER. . Compile the program. . Link the program with an options file to create a shareable image. . Define the lofical name TPU$CALLUSER to point to your routine. . Invoke VAXTPU. . From within a VAXTPU session, call your external program to perform its function by specifying the CALL_USER built-in with the appropriate parameters. If you have linked your program properly and if you have defined the logical name TPU$CALLUSER to point to your program, the CALL_USER built-in will pass the parameters you give it to the proper routine.