*-----------------------------* * Reference : TheWizardCorner * Fri Feb 7 15:07:21 1992 *-----------------------------* ----------------------------------------------------------------------------- WARNING !!! ONLY READ IF YOU THINK YOU ARE VERY EXPERIENCED WITH POWERVISOR ! NOTE THAT SINCE POWERVISOR IS STILL IN BETA STATE, THESE VARIABLES AND FIELDS CAN MOVE OR BECOME OBSOLETE. ALWAYS LOOK BACK TO THIS FILE IF YOU HAVE MADE SPECIALIZED SCRIPTS AND YOU HAVE A NEW VERSION OF POWERVISOR! ----------------------------------------------------------------------------- ============================== Introduction ================================== This file contains all information for the experienced script writer. It explains the powerful 'pvcall' command and lists the contents of some internal PowerVisor data structures. With the information contained in this file in combination with the 'Scripts' tutor file you make very powerful scripts. Some examples are given in the 'Source' subdirectory. Note that there are include files (both .h and .i) for all structures given in this file. These include files can be found in the PVDevelop/include/PV subdirectory. For SAS/C users there is also 'PVCallStub.lib'. Using this library you can more easily call the pvcall routines from C. You can find this library in PVDevelop/lib. If you want some examples you can look in the 'Source' subdirectory. This directory contains sources in C and machinelanguage using the PVCallTable and other internal variables. ========================== The 'PVCall' command ============================== The 'pvcall' command can be used to access ²internal variables and to install some extra features. The first argument of 'pvcall' is the number of the function you want to use (see below for a list of all functions). After this number follow the extra arguments (if any). Note that not all 'pvcall' functions are callable from within PowerVisor. Some are only intended to be called from within a ²machinelanguage script. To call a 'pvcall' function from within a machinelanguage script you can use the ¹PVCallTable (offset 34 in the ¹PowerVisor-port). This is a pointer to the table containing all pointers to the 'pvcall' functions. The pointer to the PVCallTable is also automatically available if your machinelanguage routine is executed from within PowerVisor (in register a2) (see the 'Scripts' tutor file for more information about machinelanguage scripts). The ²return value from these functions is always in d0. If a certain pvcall function is only available from machinelanguage an asterix ('*') is put after the number. All functions callable from both machinelanguage and PowerVisor expect their arguments on a commandline. If you want to use any of these functions in machinelanguage you have to build a commandline and provide the pointer to it in a0. Except for the 'InstallCmd' functions ('Pre' command, 'Post' command, 'Quit' command and 'Snap' command) all functions preserve registers d2-d7 and a2-a6. The 'InstalCmd' functions preserve d2-d7 and a3-a6. Number Function ------------------------------------------------------------------------------ 0 Create a new ²PowerVisor function
this is a pointer to a machinelanguage routine. When this routine is called, a0 points to the arguments and a2 points to the 'PVCallTable'. 1 Generate an ¹error 2 Advance ²history buffer one line. Nothing happens if this line is the last. This function updates 252:4 in MainBase. 3 Lower ²history buffer one line. Nothing happens if this line is the first. This function updates 252:4 in MainBase. 4 Get ³current history line and copy to ²stringgadget buffer. The current history line is the line pointed to by 252:4 in MainBase. If 252:4 is 0 the stringgadget buffer is cleared. 5 Refresh the ¹stringgadget. Use this function after you have changed something in the ²stringgadget buffer. 6 Install a 'Pre' command. This is a command that is executed before the commandline is parsed that is just typed in by the user. The command can find the pointer to the commandline in 'ScreenBase' (the stringgagdet buffer) and can make changes. See the 'TechnicalInfo' file for the exact moment of the execution of this command. When you generate an error in the 'Pre' command, you will prevent further execution (The user can override both the 'Pre' and 'Post' commands with the '\' prefix commandline operator). 7* Evaluate an expression. All expression features that PowerVisor supports are supported by this function (even groups). -> -> 8 Remove a variable, special variable, constant or function. Be careful with this command since you can remove internal variables like 'rc', 'mode' and 'error' with this function. Removing these variables will certainly do no good. 9* Parse a string from the commandline. The '\' and '·' (strong quote) operators are supported. Note that you are NOT responsible for freeing the string. The string is automatically added to the autoclear list. This also means that you must copy the string if you want to remember it permanently. -> -> 10 Copy string to the ²stringgadget buffer 11 Add string to the ²history buffer. Note that the PowerVisor history buffer never contains two equal history lines after each other. This function checks if the previous history line is equal to the one you are going to add. If they are equal nothing happens 12 Get address of the ²stringgadget buffer ->
13 Append string to the ²stringgadget buffer 14 ²Skip spaces. This command skips all spaces in a string (',' chars are also considered spaces). -> 15 Set ²cursor position in ¹stringgadget. Use this command to set the cursor position where it must be the next time a 'Scan' is executed. The internal 'Scan' routine is called to get the commandline and for the 'scan' command. 16 Install a 'Post' command. This is a command that is executed after the commandline is parsed and executed that was typed in by the user. 17 Set debug mode for PowerVisor. When debug mode is on, PowerVisor prints each command before it is executed (after alias expansion) and also prints the return code of each command. This is useful for debugging recursive aliases, scripts, macros and other special things. = 0 for no debug, 1 for debugging info 18 Get ²execution level -> 0 = commandline 1 = script 2 = attach (IDC) 3 = 'for' command 4 = 'to' command 5 = 'with' command 6 = 'tg' command 7 = 'on' command 8 = refresh 9 = group command 10 = snap command 11 = intuition handler command 12 = quit handler command 13 = signal handler command 14 = OBSOLETE 15 = called from 'ExecCommand' portprint function 16 = Pre command 17 = Post command 19 OBSOLETE 20 Get ¹mStringInfo. Note that when you change something in this structure, you will probably have to call 'pvcall 52' or 'pv 5' to remake the ¹stringgadget. -> Fields in the StringInfo structure. offs size function ---------------------------------- 0 4 Buffer 4 4 UndoBuffer 8 2 BufferPos 10 2 MaxChars 12 2 DispPos 14 2 UndoPos 16 2 NumChars 18 2 DispCount 20 2 CLeft 22 2 CTop 24 4 LayerPtr 28 4 LongInt 32 4 AltKeyMap 21 Get ²Snap Buffer. This buffer is 120 bytes long. -> 22 Install command before ¹'snap'. Using 'pvcall 21' you can change something in the string that is snapped. If you return 0 from this command the 'snap' will not happen. 23 OBSOLETE 24 ¹Beep