15503 15524══abort()Purpose: Terminate the editing session abnormally.──────────Syntax: void abort([int code])──────────Description: abort() immediately terminates the editing session, returning control to the operating system. Any edits not previously saved are lost. In addition, no "clean-up" is attempted and therefore no temporary files are deleted. The code argument determines what exit code is returned to the operating system. Values for code of 255 and greater return an exit code of 255. If the code is not supplied, an exit code of three is used.──────────Value returned: abort() returns no value since it never returns.──────────Compatibility: This function is similar to the ANSI C abort() function except that the exit code may be specified.══adjust_window() PELPurpose: Resize window using cursor keys.──────────Syntax: void adjust_window()──────────Description: The adjust_window() function allows adjusting the size of the current window with cursor keys rather than with a mouse. A help message is printed in the dialog window. The user indicates acceptance of the new window size by pressing [Enter] or returns the window to its unmodified size by pressing [Esc].──────────Value returned: No useful value is returned by this function.══add_compiler() PELPurpose: ──────────Syntax: void add_compiler(str ext_list, str cmd_line [, str err_name ])──────────Description: The add_compiler() function adds support for a compiler for which support is not built-in. If the need for the added compiler is on-going, the add_compiler() call should be placed in the configuration file or local_setup() function so that this information will be retained from one editor session to the next. The first argument, ext_list, is a list of the filename extensions used by the new compiler. Elements of the list may be separated by spaces or commas. The principle extension appears first in this list. Other extensions in the list signify header files or other "include" files that are not normally named on the compiler command line. The second argument, cmd_line, is used to define the command line normally used for compiling these files. Remember that this command line is presented to the user for editing just before execution, so it is not necessary that this command line fit all anticipated situations. Several built-in macros have been defined for use in the cmd_line string. These allow you to refer to the source file name and parts of the source file name in general terms. These macros are as follows: Macro Replacement value ----- ---------------------------- $< complete name of the source file. $r root (basename) of the source file. $e extension of source file, excluding "." $p drive and path of source file (ends in "\") The optional third argument, err_name, determines which predefined rule set to use in interpreting the error listing file and names the file in which any errors generated during a compile will be captured. If this argument is omitted or null, the generic rule set is used and the source file's extension is used as the error file's basename (root). The correct rule set allows the editor to place the cursor at the offending position in the proper source file. The defined rule sets are identified by labels which may be used as the err_name argument. These include: "generic", "pel", "TurboC", "Clipper", and "none". Character case is not significant when specifying these strings. If the err_name argument does not match one of these labels, the generic rules are used and the err_name string is used only as a basename for the error listing file. The "generic" rule set accommodates the error listing format used by Microsoft compilers, Lattice C, Borland Turbo Pascal, and many others. The "pel" rule set is designed for use with the SPE function library source files. "TurboC" identifies the rules for use with Borland's Turbo C and "Clipper" identifies the dBase dialect error format rules. If no rule set is to be used, the label "none" is used. In this case, captured errors are displayed in a window rather than at their position within the source file. Compiler support added with the add_compiler() function takes precedence over rules previously defined for the specified extension. For example, there is built-in support for files with the extension ".C". If you specify the .C extension in the ext_list argument to an add_compiler() call, the built-in rules for that extension are superseded.──────────Value returned: No useful value is returned by this function.══ai() PELPurpose: Turns auto-indent feature on or off.──────────Syntax: void ai([int on])──────────Description: The ai() function is a tersely named synonym for toggle_auto_indent(), suitable for executing through the PolyAWK interpreter ([F10]). If the on argument is zero, the auto-indent feature is turned off, otherwise it is turned on. If the argument is omitted this function toggles the current state of auto-indent mode.──────────Value returned: No useful value is returned by this function.══and()Purpose: Performs a bit-wise AND on two numbers.──────────Syntax: int and(int num1, int num2)──────────Description: The and() function compares the bits of the num1 and num2 arguments and derives a third value from them. The argument values remain unchanged. This function operates on 32 bit values. If the arguments are not 32 bit numbers, they are converted to this form for the purpose of this function.──────────Value returned: Each bit in the value returned by the and() function is SET ( 1 ) if the corresponding bits in both arguments are set. Otherwise, the bit is RESET ( 0 ).══append_to_scrap()Purpose: Add text to the current contents of the scrap buffer.──────────Syntax: int append_to_scrap()──────────Description: If a block or region of text has been selected, the append_to_scrap() function will copy the text in that block into the scrap buffer. If no block of text has been defined, the character at the cursor is appended to the scrap buffer. In any case, the text appended to the scrap buffer is not deleted from its original location in the edit buffer. Any previous contents of the scrap buffer are preserved. This function allows you to accumulate text in the scrap buffer which may later be inserted elsewhere in the buffer with the insert_scrap() function.──────────Value returned: When successful, the append_to_scrap() function returns a non-zero value (TRUE). If for any reason the function can not be completed, a zero (FALSE) value will be returned.══ARGC AWKPurpose: Stores the number of arguments in SPE's invocation──────────Type: int ARGC──────────Description: On start-up, SPE sets this variable to the number of parameters specified on the command line when the editor was invoked. This value represents the number of elements of the ARGV array and is always at least one, since the SPE invocation name itself is counted. The value of ARGC may be modified by the startup() function, but this should only be done to reflect parallel changes to the ARGV array.══argcount()Purpose: Reports the number of arguments passed to the current function.──────────Syntax: int argcount()──────────Description: The argcount() function tells how many arguments were actually passed to the function currently executing. This function enhances the ability to write PEL functions that can accept a variable number of arguments. If arguments are omitted when calling a function the values the function receives for these arguments will be 0 or an empty string. In some cases it is useful to distinguish an omitted argument from one that was supplied as one of these values. The argcount function provides a method of doing this.──────────Value returned: The value returned by the argcount() function is the number of arguments supplied in the function call to the current function.══ARGV AWKPurpose: Stores the command line used to invoke SPE.──────────Type: array ARGV──────────Description: The AWK array ARGV contains all of the elements of the command line used to invoke the current session of SPE. Elements are separated on the basis of whitespace. It may be examined or modified at any time. Each element of the array is a series of characters in the original command line which were surrounded by whitespace. If ARGV is modified by the startup() function, the modified ARGV will be processed as if it had been entered on the DOS command line. When received from DOS, ARGV will contain a total of up to 128 significant characters. It may, however, be safely modified to be much larger, if desired. When this array is modified, however, it is advisable to modify the ARGC variable to reflect the new number of arguments. The first element of this array is the editor invocation name.──────────Example: ARGV[0] == "p"══ascii_keymap read-onlyPurpose: Predefined keyboard of just the ASCII character keys.──────────Type: keymapid ascii_keymap──────────Description: The ascii_keymap variable stores the id of a keymap which has only the keys corresponding to ASCII values defined. In this keymap, keys which return an ASCII value (1 to 255) are bound to the insert_key() function. That is, they insert that character in the buffer. This is the extent of the key definitions. Key sequences such as [Alt][X] or [F1] will have no corresponding function with this keyboard definition. The [Ctrl][Break] key, however, functions independently of any keymap and is therefore always defined. This variable is primarily used when creating a new keymap. Used as an argument to the create_keymap() function, ascii_keymap provides a method of initializing a new keymap to a minimally useful definition. You may then build upon this definition as you please. This variable serves as a constant value and may not be modified by the user.──────────See also: factory_keymap, empty_keymap══assign_key()Purpose: Assigns a function to a keystroke.──────────Syntax: int assign_key(str key, str function_call)──────────Description: The assign_key() function records a key assignment in the current keymap. The key argument gives the name of the key, to which a function is to be assigned, in string form. Within the key string, keystrokes may be represented numerically or as descriptive strings called keynames. The simpler method is to specify the keystroke by keyname, however, there are circumstances where this method is not specific enough. For example, you may wish to assign a function to the plus key on the numeric keypad but not to the plus key on the main keyboard. In this case the key must be specified in a numeric string representing its scan code in addition to the ASCII value (key id). When specifying a keystroke by numeric string, the number is preceded by a pound symbol, #. Decimal values must be used. Hexadecimal representations are not acceptable in this context. The number may be the character's ASCII value or, when you need to be more explicit, the character's key id. A table containing the commonly used key ids appears in the "Keymapping" chapter of the Functions by Category manual. Keys that can be represented by a single character may be referenced by placing that character in the string. A few characters are used for special purposes and must be preceded by a backslash when used to represent themselves. These characters include the pound symbol, #, and angle brackets, <>. They must be represented in this manner: \#, \< and \>. Keys such as Tab, Esc and F1 whose names require more than one character to describe must be enclosed in angle brackets, <>, as follows: <Tab>, <Esc> and <F1>. When a keystroke involves more than one key pressed simultaneously both key names are placed within the angle brackets. These keynames must be separated by a single dash; a space or underscore is not acceptable. A list of these keynames appears in the "Keymapping" chapter of the Functions by Category manual. You need only specify enough of each keyname to distinguish it from other possible names. For example, <sh-ho> and <Shift-Home> are equivalent. The keyname and numeric methods of specifying keystrokes may be inter-mixed within the key string, as demonstrated in the following example: #3a<tab> This example describes the keystrokes [Ctrl][C],[a],[Tab]. The function_call argument usually gives a string containing the just the name of a function to be assigned to the key. It may, however, contain a function name and arguments or an assignment to a variable. Here is a typical example of an assign_key() function assignment: assign_key("<Alt-F10>","displayDate") When specifying arguments to a function within the function_call string, parentheses and commas are not used. The name of the function and each of the arguments are separated by spaces only: assign_key("<Ctrl-U>","restore_position 1") Calling this same function from within source code would use the form restore_position(1). This is incorrect form for assigning to a key, however. Here is an example of the function_call argument containing a variable assignment: assign_key("<Alt-L>","message_level = 3")──────────Value returned: No useful value is returned by this function.══assign_mouse_buttons() PELPurpose: Assigns mouse functions to pseudo-scan codes.──────────Syntax: void assign_mouse_buttons()──────────Description: The assign_mouse_buttons() function assigns the standard mouse functions to their appropriate pseudo-scan codes. Since pressing a mouse button does not generate a scan code like pressing a keyboard key does, SPE input routines simulate these codes. Functions are assigned to various mouse actions including pressing or releasing any of three keys, clicking the key, and double clicking the key. An interval of time is used to differentiate between press, click and double click. This interval is specified by the mouse_click_speed variable. More information about how mouse support has been implemented read the description of the "Mouse Package" in Appendix B of the Functions by Category manual.──────────Value returned: No useful value is returned by this function.──────────See also: mouse_click_speed══atoi()Purpose: Convert an ASCII string to an integer.──────────Syntax: int atoi(str s [, int radix])──────────Description: The atoi() function converts the s string argument into an integer. The numeric portion of the s string may be any value that may be represented by a 32 bit signed integer (-2,147,483,646 to 2,147,483,647). By default, the number contained in the string is assumed to be in decimal notation. Other notations must be explicitly named by the radix argument. The values for the radix argument must be in the range of 2 to 16. Specify 2 for binary, 8 for octal, 10 for decimal or 16 for hexadecimal. The string may contain non-numeric characters, but these must follow the numeric portion of the string. Otherwise the numeric portion will not be converted.──────────Value returned: The value returned by the atoi() function is the integer equivalent of the numeric portion of the string. A zero value is returned if any non-numeric character precedes the numeric portion of the string. This includes leading whitespace. If radix is not one of the allowed values, it is considered an error, and a zero value is returned.──────────Example: testInt = atoi("329 programmers") The value of testInt is then 329.══attach_event_handler()Purpose: Associates a function with an event.──────────Syntax: int attach_event_handler(int event, funcid id)──────────Description: The attach_event_handler() function designates a function to be executed whenever the event identified by the event argument occurs. The event argument specifies the event by number and the id argument provides the function's numeric id. A listing of the event numbers follows: 0 Reserved, internal use. 1-8 User definable 9 Emulation Changed 10 Idle Time 11 Ctrl-Break 12 Invalid Prompt Character 13 Unassigned Key 14 New Edit File 15 New Current Buffer 16 New Current Window 17 Help Invoked 18 Idle Threshold 19 Exiting Editor 20 Temporary Space Overflow 21 Edit File Saved 22 Key Pressed 23 First Modification 24 New Screen Size 26 Display Update 27 Process complete (OS/2) 28 Left Button Depressed 29 Right Button Depressed 30 Middle Button Depressed 31 Left Button Released 32 Right Button Released 33 Middle Button Released 34 Left Button Clicked Once 35 Right Button Clicked Once 36 Middle Button Clicked Once 37 Left Button Clicked Twice 38 Right Button Clicked Twice 39 Middle Button Clicked Twice 40 insert_key() executed 41 insert_string() executed 42 delete_chars() executed 43 insert_newline() executed 44 system() call completed 45 executing function changed by compile. 46 current buffer about to be deleted. More information on these events may be found in the "Event Handling" chapter of the Functions by Category manual. The association created by this function is not exclusive. Other functions may also be associated with the event and other events may cause the indicated function to be executed. The functions attached to an event are executed in the reverse order from which they were attached.──────────Value returned: Upon successful completion, the attach_event_handler() function returns a non-zero (TRUE) value. If the event argument is not a valid event or the id argument is not a defined function id, the function will fail. A value of zero (FALSE) is then returned.══attach_window_buffer()Purpose: attaches an existing buffer to an existing window.──────────Syntax: int attach_window_buffer(winid window, bufid buffer)──────────Description: The attach_window_buffer() function connects a previously created buffer to a previously created window. The contents of the buffer may then be viewed through the associated window. The window and buffer arguments are the numeric ids returned by the functions used to create the edit buffer and window respectively. Attaching a window to a buffer breaks any previous association the window had with another buffer. A buffer, however, may have numerous windows attached to it. The buffer's association with other windows therefore remains unchanged. If attach_window_buffer() is used to attach a buffer other than the currently active buffer to the current window, the buffer becomes the current buffer. The act of attaching of a window to a buffer does not in itself make the contents of the window visible nor does the window automatically become the current window. The window may be hidden "under" another window. In this case it will not become visible until it is made the current window or the obscuring window is moved or closed.──────────Value returned: Upon successful completion, attach_window_buffer() returns a non-zero value (TRUE), otherwise a zero value (FALSE) is returned.──────────See also: edit_file(), create_buffer(), create_window()══autosave() PELPurpose: Toggles the auto-save feature on or off.──────────Syntax: void autosave([int atime [, int ftime]])──────────Description: The autosave() function toggles the use of SPE's auto-save feature. A message is then displayed indicating if the feature has been turned on or off. The auto-save feature automatically saves a buffer to disk after a specified period of keyboard inactivity. The period of inactivity is specified in seconds and is determined by the setting of the autosave_time variable. The optional time argument may be used to set autosave_time at the same time as toggling on the autosave() feature. The ftime argument indicates the number of seconds between forced saves. That is, saves which occur without regard to keyboard activity. This "forced saves" interval may be specified when toggling on autosave(), or by setting the autosave_force_time variable. Either way, the interval is specified in seconds. Calling autosave() with an argument of 0 always turns off the auto-save feature regardless of its previous setting. Non- zero values for this argument always turn it on. The buffer is not saved under the filename associated with the buffer ( buffer_filename ) since this would make it less convenient to abandon changes. Instead, the filename under which it is saved is derived from buffer_filename by making the third character of the extension a "!". If the extension has less than two characters (e.g., ".C"), the extension is filled with underscores (e.g., ".C_!"). Thus, the auto-save file is stored in the same directory as the buffer's filename. If this extension presents a problem, you may modify the function library source code, found in AUTOSAVE.PEL, to assign a different extension to auto-save files. Files created by the auto-save function are deleted when the editor is exited normally. If power is lost or abort() is used to terminate the edit session these files are not deleted.──────────Value returned: No useful value is returned by this function.══autosave_force_time PELPurpose: Sets the time interval between auto- saves.──────────Type: int autosave_force_time──────────Description: The autosave_force_time variable contains the number of seconds between auto-saves, without regard to keyboard activity. This value is only meaningful if the auto-save feature has been turned on. The default value for this variable is 0 seconds, which has the effect of disabling forced saves.──────────See also: autosave(), autosave_time══autosave_time PELPurpose: Sets the idle time interval for auto- save.──────────Type: int autosave_time──────────Description: The autosave_time variable contains the number of seconds that the keyboard must be idle before the auto-save feature saves the file. This value is only meaningful if the auto-save feature has been turned on. The default value for this variable is 15 seconds.──────────See also: autosave(), autosave_force_time══background_charPurpose: Defines character seen on screen outside of windows.──────────Type: int background_char──────────Description: The background_char variable contains the value of the character to be displayed on the screen where no window is present. The default character is a partially filled in block whose value is 177. This variable is an integer rather than a string since the value assigned to this variable is not normally a typeable character.══backspace()Purpose: Delete character preceding the cursor.──────────Syntax: int backspace()──────────Description: The effect of the backspace() function is dependent upon the value on the buffer_flags variable. If insert mode is in effect, this function deletes the character preceding the current cursor position. The contents of the line to the right of the deleted character and the cursor are shifted to the left. If the buffer_flags variable specifies overtype mode, the backspace() function replaces the character preceding the current cursor position with a single space. The contents of the line to the right of the cursor does not move unless the character deleted is a tab. However, the cursor does shift to the left. When in insert mode, backspace() deletes the end-of-line marker on the preceding line when the cursor is at the beginning of the line. This has the effect of appending the current line onto the preceding line. In overtype mode, backspace() will not delete the new line. Instead, when the cursor is at the beginning of the line beep() is called. If backspace() is called when the cursor is at the beginning of the buffer, the beep() function is executed and no other action is taken. When the cursor is positioned beyond the end of the line (VIRTUAL SPACE enabled), executing the backspace() function performs a back-tab. That is, the cursor is moved to the closest tab setting to the left of its current position.──────────Value returned: The backspace() function returns a non-zero value (TRUE) upon successful completion. If the cursor is not moved, a value of zero (FALSE) is returned.──────────See also: buffer_eol_string, buffer_flags══backup_directoryPurpose: Names the directory in which back-up files are stored.──────────Type: str backup_directory──────────Description: The name of the directory in which back-up files are made is stored in the backup_directory variable. The backup_directory may be on any valid drive and directory in your system. It may also be specified in relative terms such as "." to indicate the current directory or "..\backup" indicating the backup subdirectory off of the current directory's parent directory. By default this variable is an empty string. Whenever this string is empty, backups will be made in a default directory. SPE will attempt to save backups in a directory named \SPE\BACKUP on the current drive. If this directory does not exist, the editor will attempt to create it. If unable to create this directory, for example on a network drive, the directory in which the file originated is used for backups. You may specify that backups be made in the same directory where the file originated. This is done by giving backup_directory the value "*", a single asterisk. See backup_file_ext for an explanation of the filename extension that is applied to back-up files.══backup_file_ext Purpose: Names extension applied to backup files.──────────Type: str backup_file_ext ──────────Description: The backup_file_ext variable specifies the extension with which backup files are identified. This variable may optionally contain a leading dot or period. The default value of this variable is an empty string, which implies that the extension is not changed. A single asterisk, "*", may also be used to signify that the extension is not changed. The variable backup_directory determines where the backup file will be created. If the backup directory may be specified as or through error become the same directory as the file being edited. When this occurs and no backup_file_ext has been specified, the extension ".BAK" is used to avoid overwriting the original file.══backup_file() PELPurpose: Makes backup copies of files, when enabled.──────────Syntax: int backup_file(str fname)──────────Description: The backup_file() function saves a backup of file named by fname in the directory described by the backup_directory variable. If file backups have not been enabled ( toggle_file_backup() ), no backup is made. The extension applied to the backup file is controlled by the backup_file_ext variable. This function is used as part of the save process in the emulation packages. The making of backup copies may then be toggled on and off through the toggle_file_backup() function. This function renames (moves) the fname file to the file in the backup directory. This has the effect of removing the original file. For this reason backup_file() should only be performed if the original file will immediately be restored by a save. The best form for using this function is as follows: function save_me() { if ( buffer_is_modified() ) { backup_file( buffer_filename ) write_buffer() } }──────────Value returned: This function returns FALSE ( 0 ) if an error occurs. It otherwise returns TRUE ( 1 ).──────────See also: toggle_file_backup()══beep()Purpose: Emits a short tone from the speaker.──────────Syntax: void beep()──────────Description: The beep() function outputs a brief note from the speaker. If this sound does not meet with your approval or you wish to define a series of different sounds, you may write your own using the play() function.──────────Value returned: No value is returned from this function.══bp()Purpose: Set breakpoint for debugging.──────────Syntax: funcid bp(str func_name)──────────Description: The bp() function sets a breakpoint at the PEL function described by the func_name argument. When that function is called, the Extension Language Debugger will pop- up, displaying the source code currently executing. The user may then query data and step through the function. This is the same debugger described under the debug() function. Setting a breakpoint with bp() and then causing the editor to reach that breakpoint is the standard method of invoking the debugger. The editor will reach that breakpoint when the function is called. You may call the function by pressing a key to which that function has been assigned or by issuing the function call through the interpreter ([F10] in most emulations).──────────Value returned: The bp() function returns the numerical function id of the function described by the func_name argument. If the argument does not describe a valid function, a zero (FALSE) value is returned.══braces() PELPurpose: Find unmatched curly braces.──────────Syntax: void braces()──────────Description: The braces() function scans the current buffer for unmatched braces, "{" and "}". If one or more opening braces have no match, the cursor is positioned at the last location where braces appear to be balanced. If there is a closing brace with no corresponding opening brace, this is reported but the cursor is not moved. If all braces are balanced a message to that effect is displayed in the dialog box.──────────Value returned: No useful value is returned by this function.══brief() PELPurpose: Makes SPE operate similarly to the BRIEF╘ editor.──────────Syntax: void brief()──────────Description: The brief() function executes a setup and installs a special keyboard definition that causes SPE to operate like the popular BRIEF╘ editor. This is one of the "emulation packages" provided with the Sage Professional Editor. For a list of differences between SPE's BRIEF╘ emulation and the BRIEF╘ editor see Appendix B of the User's Manual.──────────Value returned: No useful value is returned by this function.══buffer_eof_string bufferPurpose: Tells whether Ctrl-Z character gets special treatment.──────────Type: str buffer_eof_string──────────Description: Each edit buffer has a buffer_eof_string variable associated with it. This variable is for use when creating or editing a file which should or already does use a Ctrl-Z character (1AH) to mark the End-Of-File (EOF). Alternately, the EOF is determined by the file size recorded by the operating system. The permissible settings for this variable are either an empty string or a string containing only a Ctrl-Z. When this variable is a Ctrl-Z rather than an empty string, the associated buffer receives special treatment when the file is read or written. Examples: buffer_eof_string = "\x1a" buffer_eof_string = chr(0x1a) When reading, data is read from the file into the buffer only until a Ctrl-Z character (ASCII decimal value 26) is read. The Ctrl-Z is not placed in the buffer and the rest of the file is ignored. When writing the file, the contents of the buffer are written to disk with a Ctrl-Z character appended to the end. When this variable is an empty string the entire file, based on the size recorded by DOS, is read into the buffer. No special treatment is given to Ctrl-Z. This variable may be modified at any time after the buffer has been created. However, the associated buffer must be the currently active buffer at the time it is modified. Since create_buffer() and therefore edit_file() create the buffer and read in the file as a single action you cannot affect the reading of the file by modifying this variable. To recognize Ctrl-Z in a new buffer the default_buffer_eof_string must be set accordingly. The default value for this variable is taken from the default_buffer_eof_string variable at the time the buffer is created.══buffer_eol_string read-only, bufferPurpose: Designates the end-of-line character sequence.──────────Type: str buffer_eol_string──────────Description: Each edit buffer has a buffer_eol_string variable associated with it. The value of this variable is set to the value of the default_buffer_eol_string variable at the time the buffer is created. The character or characters contained in the buffer_eol_string are used by SPE as the line termination sequence or end-of- line marker (EOL). When the insert_newline() function is called this string is inserted in the text and the cursor moves to column 0 of the next line. The insert_newline() function is normally associated with the [Enter] or [Return] key. The value of buffer_eol_string may not be modified by the user. You may influence its value, however, by changing the value of the default_buffer_eol_string variable. The value of buffer_eol_string is inherited from this variable at the time the buffer is created. The end of line string may be any one or two character sequence. If two characters are used they may not be the same character. Typical values for this variable include: a carriage return and line feed combination, just a line feed or just a carriage return. See the description of the default_buffer_eol_string variable for a description of this variable's default value.──────────See also: insert_newline(), default_eol_string══buffer_filename bufferPurpose: Stores the name of the buffer's corresponding disk file.──────────Type: str buffer_filename──────────Description: Each edit buffer has a buffer_filename variable associated with it. The variable buffer_filename contains the name of the file, including complete path, to which the edited buffer is intended to be saved. When the buffer is created, this variable is set to the value of the buffer_original_filename variable (input filename). A user written function that modifies this variable need not supply the entire path to the filename stored in buffer_filename. the editor will fill in the missing elements with the default drive and directory, as required. If this variable contains an invalid drive or directory, an error is generated when an attempt is made to save the buffer to disk.──────────See also: buffer_original_filename══buffer_flags bufferPurpose: Stores a number of buffer attributes as flags.──────────Type: int buffer_flags──────────Description: Each buffer has a buffer_flags variable associated with it. The least significant 16 bits of the buffer_flags variable describe the state of various attributes of the buffer. Individual bits of buffer_flags are used by the editor to signify if the buffer has been modified since the last save, whether buffer may be modified and so on. The buffer_flags variable takes its initial value from the default_buffer_flags at the time the buffer is created. A number of descriptive identifiers have been defined in the standard library files to facilitate testing and modifying these bits. These identifiers and their numeric values are given below. Those bits which may not be modified by the user are noted as read-only (r/o): BUFFER_SYSTEM (r/o) 0x0001 (bit 0) BUFFER_POSITION_IS_VIRTUAL (r/o) 0x0002 (bit 1) (reserved)(r/o) 0x0004 (bit 2) (reserved)(r/o) 0x0008 (bit 3) BUFFER_READ_ONLY 0x0010 (bit 4) BUFFER_AUTOSAVE_MODIFIED 0x0020 (bit 5) BUFFER_MODIFIED 0x0040 (bit 6) BUFFER_OVERTYPE_MODE 0x0080 (bit 7) BUFFER_EXPAND_TABS 0x0100 (bit 8) BUFFER_WP_ENABLED 0x0200 (bit 9) BUFFER_REAL_SPACE_ONLY 0x0400 (bit 10) BUFFER_SNAP_TO_EOL 0x0800 (bit 11) BUFFER_NO_UNDO (r/o) 0x1000 (bit 12) BUFFER_TABS_TO_SPACES 0x2000 (bit 13) BUFFER_WHOLE_LINES 0x4000 (bit 14) (reserved) (r/o) 0x8000 (bit 15) When the bit corresponding to each of these attributes is set ( 1 ), that parameter is turned on. Otherwise, the attribute is off ( 0 ). Read-Only Bits The first four bits in this list are read- only. You may consult the setting of these bits but you may not alter their state after the buffer is created. You may however control the value of these bits at the time the buffer is created. See create_buffer() for a description of how this is done. Descriptions of these four bits follow: The first of these four read-only bits is BUFFER_SYSTEM. It identifies buffers that have been created for system use. The contents of system buffers are not intended for editing and are not normally meaningful to the user. This bit may only be modified by the system. The second bit is BUFFER_POSITION_IS_VIRTUAL. This bit tells the editor that the cursor is currently located in VIRTUAL SPACE. VIRTUAL SPACE is described in the "Motion" section of the Functions by Category manual. Read/Write Bits The BUFFER_READ_ONLY bit tells whether the file originally read into the buffer had a read-only file attribute. When the editor detects that the file is read-only, it sets this bit. DOS will prevent SPE from overwriting the file until the file attribute is changed. If you change the DOS file attribute (see filemode()) during editing you may modify this bit to reflect that change. Skipping the BUFFER_AUTOSAVE_MODIFIED bit for a moment, the BUFFER_MODIFIED bit identifies whether or not the buffer has been edited since the last save. Resetting this bit to 0 allows exiting without being prompted to save changes even if the buffer has been modified. Returning to BUFFER_AUTOSAVE_MODIFIED, this bit serves a similar, almost duplicate purpose to the BUFFER_MODIFIED bit just described. The difference is that BUFFER_AUTOSAVE_MODIFIED is used by the auto-save feature. Auto-save, whose use is optional, automatically saves a file to disk after a specified period of keyboard inactivity. This bit allows auto-save to determine if the file has been modified since the last auto-save or normal save operation. When the BUFFER_OVERTYPE_MODE bit is 0, the editor is in the insert mode of operation. New characters typed are inserted at the cursor position. If BUFFER_OVERTYPE_MODE is on, characters typed overwrite the characters at the cursor. This bit is consulted by the insert_key() and backspace() functions and determines their effect. When the BUFFER_EXPAND_TABS bit is set ( 1 ), tabs are converted to spaces when writing the file. Changing the setting of this bit has no immediate effect, however. When the BUFFER_WP_ENABLED bit is on, word- wrap features are applied to the current paragraph of the buffer. As text is added or deleted from the paragraph, the lines of text are reformatted as necessary to conform to word processing margins (see wp_left_margin and wp_right_margin below). The bits BUFFER_REAL_SPACE_ONLY and BUFFER_SNAP_TO_EOL define cursor actions with regard to areas of the window that do not represent a character in the buffer. These areas are referred to as VIRTUAL SPACE. The BUFFER_REAL_SPACE_ONLY bit determines if the cursor may enter these areas, while the SNAP_EOL bit defines how characters typed in this area are handled. When BUFFER_REAL_SPACE_ONLY is set ( 1 ) the cursor will not enter VIRTUAL SPACE and BUFFER_SNAP_TO_EOL has no meaning. When the BUFFER_REAL_SPACE_ONLY bit is 0, the cursor may enter VIRTUAL SPACE. The actions of the cursor when typing in VIRTUAL SPACE then depends on the status of BUFFER_SNAP_TO_EOL. When this bit is reset ( 0 ) characters typed in VIRTUAL SPACE cause the old end- of-line to be moved to the right of the characters entered. Any necessary intervening spaces and tabs are added. When BUFFER_SNAP_TO_EOL is set, typing in VIRTUAL SPACE causes the cursor to move to the end of the existing line or the beginning of the tab before edits are performed. The next of these bits is BUFFER_NO_UNDO. When a buffer is created with this bit set to 1, SPE will not maintain a history of what has been modified in the file. This means that the undo and redo features will have no effect for this buffer. Normally this is only desirable for system buffers and other buffers used for temporary storage. This bit of buffer_flags is read- only. The corresponding bit of the default_buffer_flags, from which buffer_flags takes its value, may be set by the user. A buffer with no undo history may be created by modifying default_buffer_flags and then creating the buffer. This bit may not be modified after creation. A bit of the buffer_flags variable will cause tabs to be converted to the appropriate number of spaces as they are entered into the buffer. The bit has been identified with the label BUFFER_TABS_TO_SPACES. When the BUFFER_WHOLE_LINES bit (0x4000) is set, a newline is appended to the end of the file if not already present. This bit is not set by default. The other 16 bits of buffer_flags are available for definition and use by user functions.══buffer_is_modified() PELPurpose: Tells if contents of buffer have changed.──────────Syntax: int buffer_is_modified()──────────Description: The buffer_is_modified() function reports whether the contents of the current buffer have been changed since the last save operation. This is done by examining the buffer's buffer_flags variable.──────────Value returned: This function returns TRUE ( 1 ) if the current buffer has been modified. Otherwise, it returns FALSE ( 0 ).══buffer_keymap bufferPurpose: Identifies keymap that locally overlays current default.──────────Type: keymapid buffer_keymap──────────Description: Each buffer has a buffer_keymap variable associated with it. The buffer_keymap contains the keymap id of a keyboard definition intended to replace a portion or all of the current_keymap definition. This local keyboard definition will only apply to the buffer in which the assignment is made. Any keystrokes which have not been defined by the local keyboard definition will be handled by the keymap described by the current_keymap variable.══buffer_last_line read-only, bufferPurpose: Stores the number of lines currently in the buffer.──────────Type: int buffer_last_line──────────Description: The buffer_last_line variable indicates the size of the buffer in lines. This variable may be used to move directly to positions relative to the end of the buffer or to determine when you have reached the end of the buffer. This count includes the last line of the buffer even if it has not been terminated with an end-of-line sequence. When this value is initially calculated for large files, there can be a noticeable delay. For this reason the value is not calculated until this variable is first used or interrogated. Once the value has been calculated, it is kept updated and is then available without delay.──────────See also: current_line, buffer_size,buffer_offset, goto_buffer_offset()══buffer_line_exists()Purpose: Tells if a line exists in buffer.──────────Syntax: int buffer_line_exists(int linenum)──────────Description: The buffer_line_exists() function reports whether a specified line exists in the current buffer. The linenum argument specifies the line about which the inquiry is being made.──────────Value returned: If the line exists, a non-zero (TRUE) value is returned. Otherwise, zero (FALSE) is returned.══buffer_list() PELPurpose: Shows summary of defined buffers.──────────Syntax: void buffer_list([int sys])──────────Description: The buffer_list() function pops up a list of active buffers. Buffers that are write-protected have "(R/O)" appearing after the buffer name. You may then select and change the default buffer, save or delete a buffer. A usage message appears in the dialog window. If the sys argument is supplied and is non-zero, system buffers will also be included in this list.──────────Value returned: No useful value is returned by this function.══buffer_name bufferPurpose: Provides an identifying label for the current buffer.──────────Type: str buffer_name──────────Description: Each edit buffer has a buffer_name variable associated with it. buffer_name is a string used as a label for the associated buffer. This label is displayed as a title within the window border. It is also possible to search for buffers with a certain buffer_name, using the next_buffer() and prev_buffer() functions. buffer_name may be up to 12 characters, including a period, following largely the same requirements as the operating system imposes on filenames. If more than eight characters are given, a period will be inserted in the string in at the ninth position. If a dot is used in the label, it may be followed by a maximum of three characters. By default, this string is set to the base or root name of the variable buffer_filename when the buffer is created or when the name of the associated file is changed. Changing this string value does not effect the value of buffer_filename, however. Contrast with current_buffer.══buffer_offset read-only, bufferPurpose: Tells number of characters preceding current position.──────────Type: int buffer_offset──────────Description: Each edit buffer has a buffer_offset variable associated with it. The buffer_offset variable stores the number of characters between the current position in the buffer and the beginning of the buffer. Tabs count as only one character in this calculation. This variable is Read-Only and may not be modified by the user or user written functions. The initial value of this variable is zero.──────────See also: current_line, buffer_last_line,buffer_size, goto_buffer_offset()══buffer_original_filename read-only, bufferPurpose: Stores the name of the file originally read into buffer.──────────Type: str buffer_original_filename──────────Description: Each edit buffer has a buffer_original_filename variable associated with it. The variable buffer_original_filename contains the name of the file, including complete path, from which data was first read into the buffer. The value of this variable is set by the editor system at the time that the buffer is created and may not later be changed by the user.──────────See also: buffer_filename══buffer_size bufferPurpose: Tells the size of the buffer contents in characters.──────────Type: int buffer_size──────────Description: Each edit buffer has a buffer_size variable associated with it. The buffer_size variable stores the number of characters currently occupying the buffer. Tabs are counted as a single character. The value of buffer_size may vary from the size of the file on disk if alterations such as tab expansion have been made. When the Ctrl-Z character is being treated as the end of file it is not included in this count. Unlike the variable buffer_last_line, there is never a delay in calculating this value regardless of the size of the file.──────────See also: buffer_eof_string, buffer_offset, goto_buffer_offset(), buffer_last_line══buffer_tabs bufferPurpose: Contains the locations where tab stops are found.──────────Type: str buffer_tabs──────────Description: Each edit buffer has a buffer_tabs variable associated with it. This string stores a list of column numbers, in ascending order, at which tab stops are placed. The maximum column number which may be specified in this string is 128. References to higher column numbers will cause the editor to ignore the buffer_tabs variable and use the previous value instead. The interval between the last two tab stops on this list is used to define additional tab stops for columns beyond those listed. For example, if the buffer_tabs string were as follows: "5 9" tab stops will be found at every fourth column regardless of how long the line is. This variable takes its initial value from the global variable default_buffer_tabs at the time the buffer is created.══buffer_views()Purpose: Tells number of windows that view a buffer.──────────Syntax: int buffer_views([bufid buffer])──────────Description: The buffer_views() function identifies the number of windows that are presently attached to a buffer. The buffer that is the subject of this inquiry is indicated by the buffer argument. If this argument is omitted, the function reports the number of windows attached to the current buffer.──────────Value returned: The value returned by the buffer_views() function is the number of windows associated with the specified buffer. This number includes any windows not currently visible on the screen.══buffers_modified read-onlyPurpose: Tells number of edit buffers which have been altered.──────────Type: int buffers_modified──────────Description: The buffers_modified variable stores the number of buffers containing edits which have not been saved to disk file. When this variable has a zero value it may be considered safe to exit the editor without saving. This variable may only be modified by the system.══buildpath()Purpose: Creates an absolute path from a partial or relative one.──────────Syntax: str buildpath(str path)──────────Description: The buildpath() function constructs an explicitly defined path from the partial or relative path supplied in the path argument. For example, if you are currently logged to drive C: and your current working directory is \BIN\POLY the following results may be obtained: fullpath = buildpath("TEST") then fullpath == "c:\bin\poly\test" evaluates to TRUE. The buildpath() function also expands directories referenced as ".." or ".". This function may also be used to convert paths containing forward slashes or mixed forward and backslashes to all backslashes. This is particularly useful when comparing paths.──────────Value returned: The value returned by the buildpath() function is the string containing the explicit, fully expanded path.══bury_window()Purpose: Send window to the bottom of the list.──────────Syntax: void bury_window([winid window])──────────Description: The bury_window() function puts the window named by the window argument at the end of the window list. The window argument is a window id number assigned by the editor system when the window was created. Any other windows on the screen will appear to overlay the specified window. If the window argument is omitted, the currently active window is sent to the bottom of the list. When this happens, the window at the top of the list ( one not overlaid by other windows ) becomes the active window. As always, when the active window is changed, the buffer attached to the window made current is then the active buffer.──────────Value returned: No useful value is returned by the bury_window() function.══calc() PELPurpose: Invokes the calculator desktop tool.──────────Syntax: void calc()──────────Description: The calc() function causes a handy calculator to be displayed. It can be used to perform hexadecimal, octal and decimal calculations. Use the mouse to press on the keys or type them from the keyboard. When done, press [Esc] to send away the calculator.──────────Value returned: No useful value is returned by this function.══capitalize() PELPurpose: Makes first letter of words in block upper-case.──────────Syntax: void capitalize()──────────Description: The capitalize() function converts the first character of each word in the selected block of text to upper-case. If no block has been selected, only the word at the cursor is converted. In this case, if the cursor is in the middle of a word the character under the cursor is made upper-case.──────────Value returned: No useful value is returned by this function.══change_output_name()Purpose: Obtains new filename for buffer by prompting.──────────Syntax: void change_output_name()──────────Description: The change_output_name() function prompts the user for a new output filename. This name is then assigned to the current buffer's buffer_name and buffer_filename variables. This function does not immediately cause the buffer to be saved under the new filename. When next the changes in the buffer is saved to disk, they will be saved in a file by this name.──────────Value returned: No useful value is returned by this function.══chdir()Purpose: Set the default directory.──────────Syntax: int chdir(str path)──────────Description: chdir() changes the current working directory to the directory contained in the path argument. The function will fail if path does not specify an existing directory. The path argument may contain a drive element. When path contains a drive element, that drive becomes the default drive. When using this function to change drives you must specify the drive letter followed by a colon as a minimum. When the path argument is a literal string rather than a variable, it must be enclosed in double quotes. Backslashes or forward- slashes may be used as path separators. Keep in mind that backslashes must be quoted with a second backslash in PolyAWK source code.──────────Value returned: When chdir() is successful a non-zero value is returned. A returned value of zero indicates failure.──────────Compatibility: chdir() differs from like-named C function supported by major compilers in that the default drive may be changed with this function. Return values also differ.──────────Example: chdir("b:\\test")══chr()Purpose: Makes a one character string from an ASCII value.──────────Syntax: str chr(int num)──────────Description: The chr() function creates a new string containing a single character. The character contained in the string is the character equivalent of the value in the num argument. Values for num may be from 0 to 255. If any other value is supplied, only the lowest byte is considered.──────────Value returned: The value returned by the chr() function is the new one character string.══cindex()Purpose: Reports position of the first occurrence of a character.──────────Syntax: int cindex(str s, str c)──────────Description: The cindex() function searches the s string argument for occurrences of the character or characters in the c argument. The function then reports the position in the s string at which the character first occurred. More than one character may be supplied in the c argument. When this is done, the position of whichever character of c occurs in s first is reported. This function differs from index() in that it considers c as a series of characters rather than as a sub-string.──────────Value returned: The value returned by the cindex() function is the ordinal position of the "found" character within the string. If no matches were found, or if one of the arguments is an empty string, the function returns a zero value.══clear_keymap()Purpose: Deletes all key assignments from a keymap definition.──────────Syntax: int clear_keymap([keymapid keymap])──────────Description: The clear_keymap() function removes all key assignments from the keyboard definition described by the keymap argument. The keymap argument is the numeric id associated with a previously defined keyboard definition. If the keymap argument is omitted, the keymap currently in use is initialized. For this reason, some care should be exercised when using the clear_keymap() function. There is one key function which is always defined: the [Ctrl][Break] key combination. This key combination allows an orderly exit from the editor.──────────Value returned: This function returns a non-zero (TRUE) value unless an invalid keymap argument is supplied. In the latter case, the clear_keymap() function returns a zero (FALSE) value.══clock()Purpose: Displays time and date in dialog window.──────────Syntax: void clock([int on])──────────Description: The clock() function turns on or off the display of a clock in the dialog window. This usually means that the clock will be displayed in the lower right corner of the screen. If the on argument is omitted, the clock is toggled to its opposite condition. If the on argument is specified, a zero value will turn the clock off, while other values will turn it on.──────────Value returned: No useful value is returned by this function.══collapse_window()Purpose: Reduce a window to an icon.──────────Syntax: void collapse_window([winid window])──────────Description: The collapse_window() function reduces the size of the window identified by the window argument to the "icon" state. If no window argument is specified, the current window is assumed. If the window is already an icon, the state is not changed. The icon state is one of four states a window may occupy: invisible, icon, normal or zoomed. When the window is zoomed, it takes up the entire screen. In the normal state, the window occupies the dimensions originally reflected by the window_height and window_width variables. When in the icon state, the window occupies a few columns of a single line, with a mnemonic displayed in the block. In the invisible state the window does not appear on the screen.──────────Value returned: No useful value is returned by the collapse_window() function.──────────See also: expand_window(), hide_window(),restore_window()══color_...Purpose: Defines the various colors used by the system.──────────Type: int color_border int color_errors int color_highlight int color_linenumbers int color_messages int color_text int color_title int color_warnings──────────Description: The system-wide and window-specific variables listed above define the colors to be used for various aspects of the SPE's appearance. Of these variables several are system-wide, while the rest may be defined differently for each window in use. Each of these variables describes a complete color attribute: both foreground and background. The system-wide colors are as follows: color_background is the attribute used for the background outside of defined windows. color_errors is the attribute used for error messages. Similarly, color_messages and color_warnings are the attributes given to informative and warning messages, respectively. The color_background variable is also used to turn blinking off or on in a system wide fashion. It is described separately for this reason. The colors which may be set independently for each window are as follows: color_border is the attribute to be used for the window's border characters. color_linenumbers is the attribute for the line numbers appearing to the right of each line of text, when this feature is enabled. color_text is the attribute given to the buffer text shown in the window. The color of the title bar, tab ruler and any scroll bars are determined by the value of the color_title variable. The color_highlight attribute is used to identify text that is part of a marked block or region. The initial values for the window-specific variables are obtained from the like-named default_... variables at the time the window is created. If these variables are modified after the window has been created, a call to the display_redraw() function is required to ensure consistent appearance. Permissible values for color_... variables are shown in a table in the "Windowing" section of the Functions by Category manual.──────────See also: color_background══color_backgroundPurpose: Defines attribute used outside of windows.──────────Type: int color_background──────────Description: This primary purpose of the color_background variable is to define the colors used for foreground and background outside of edit and dialog windows. The color values available and their meaning are described in the "Windowing" section of the Functions by Category manual. A secondary purpose of this variable is to signal whether or not blinking text is to be used. Ordinarily, one bit of the attribute byte is used to indicate that the text associated with that attribute should blink. If blinking is turned off, this bit may be used as an intensity bit. This means that all 16 of the colors available for foreground are also available for background, rather than the usual 8 colors. You may then use pink or white and so on as your background color in your system-wide or window-specific color selections. The least significant byte of this variable contains the desired attribute. Bit 0 of the next byte signals whether blinking should be turned off or on. If the bit is on blinking will be turned off. If the bit is off blinking is turned on. If you wish to turn blinking off you add 256 to the attribute value you have selected for the background and assign it to color_background. For most people this is most easily done using hexadecimal notation. Suppose you have selected the value 0xC0 for the background color. To turn blinking off you simply add a 1 to the left of the number. In this case you would assign the value 0x1C0 to color_background. Here are a few more examples: Blink on Blink off Gray on black 0x07 0x107 White on blue 0x1F 0x11F Blinking black on gray 0xF0 N/A Black on white N/A 0x1F0──────────See also: color_...══compile_buffer()Purpose: ──────────Syntax: void compile_buffer()──────────Description: The compile_buffer() function attempts to compile the current buffer using rules associated with the file type. The current buffer is saved to disk to ensure that the file the compiler works on reflects all changes. The buffer's filename extension is scrutinized to determine which compiler will be used and then that compiler is called. SPE has a number of built-in rules that determine what command line is issued for a file bearing a certain extension. If the built-in rules do not suit your particular situation, you may use the add_compiler() function to extend or modify the built-in rules.──────────Value returned: No useful value is returned by this function.──────────See also: add_compiler(), display_errors(),goto_next_error()══compress() PELPurpose: Deletes multiple occurrences of a character.──────────Syntax: str compress(str s [, str t])──────────Description: The compress() function creates a new string from the s argument. The new string is the same as the argument except that all occurrences of the characters in the t argument are reduced to a single occurrence of the first character of t. Sequential occurrences of one or more of the characters of t, regardless of order, are likewise compressed to one occurrence of the t argument's first character. This function is intended primarily as a method of "collapsing" white space. For this reason, if the t argument is not specified, this function will compress occurrences of tabs and spaces into single occurrences of spaces. This action is the same as if the string " \t" (space followed by tab) were provided as the t argument.──────────Value returned: The value returned by the compress() function is the newly compressed string.──────────Examples: compress("THIS that") returns: "THIS that" compress("EDCBA","ABCDE") returns: "A"══confirm()Purpose: Prompts user and obtains a response.──────────Syntax: str confirm(str prompt, str responses)──────────Description: The confirm() function displays the message provided in the prompt argument. It then reads the keyboard until one of the characters in the responses string is typed or the user hits the escape key. When a character other than escape or the specified responses is typed, the function replies with a beep(). The confirm() function treats the characters in the responses argument in a case-sensitive fashion. This means that if both "Y" and "y" are acceptable responses, both characters must be included in the string.──────────Value returned: The value returned by the confirm() function is either a string containing the response accepted or an empty string if the user pressed escape.══copy_to_scrap()Purpose: Copy a portion of current buffer to scrap buffer.──────────Syntax: int copy_to_scrap()──────────Description: The copy_to_scrap() function copies a character or region of text from the current buffer to the scrap buffer. Unlike the append_to_scrap() function, copy_to_scrap() overwrites the previous contents of the scrap buffer. If no block of text has been defined, the character at the cursor is copied to the scrap buffer.──────────Value returned: When successful, the copy_to_scrap() function returns a non-zero value (TRUE). If for any reason the function can not be completed, a zero (FALSE) value will be returned.──────────See also: delete_to_scrap(), append_to_scrap()══copy_to_scrap_key()Purpose: Copy or append portion of buffer to scrap.──────────Syntax: void copy_to_scrap_key([int append])──────────Description: The copy_to_scrap_key() function is an enhanced version of the copy_to_scrap() function intended for assignment to a keystroke. It differs from the copy_to_scrap() function in that it will either append or copy the current selection to scrap and display a status message. If the append argument is present and non- null the selection is appended to current contents of scrap. Otherwise scrap is overwritten.──────────Value returned: No useful value is returned by this function.══create_buffer()Purpose: Creates a new buffer attached to a disk file.──────────Syntax: bufid create_buffer(str name, str file [, int b_flags])──────────Description: The create_buffer() function creates a new buffer and initializes the associated variables to the current editor system defaults. The file to which it is attached is then read into the buffer. The value of the name argument is assigned to the buffer's buffer_name variable. The argument file is used as the initial value for both the buffer_filename and buffer_original_filename variables. The newly created buffer is inserted into the buffers list in the position immediately following the currently active buffer. It may be made the currently active buffer by assigning it to the current window or through a call to the next_buffer() function. If the file to be attached to the new buffer is already attached to an existing buffer, the user is notified and permission to proceed is obtained before creating the buffer. It is possible to have two writable buffers simultaneously attached to the same file. In this situation edits made in one buffer are not reflected in the other. Operating in this manner is fraught with pitfalls. As a consequence, it is preferable to open another window onto the original buffer. However, if you find it desirable to have the same file in two separate buffers you may do this by making one of the buffers a system buffer. This requirement assures that the system buffer will not accidently be written to disk by write_all_buffers() or similar function. It must be explicitly written to disk. Normally, various buffer attributes are inherited from default_buffer_flags. This value is then stored in the buffer's buffers_flags variable. If the b_flags argument is supplied, however, the value of that argument is used for buffer_flags instead of using default_buffer_flags. This is useful when you wish to create a buffer with other than the usual attribute flags. This is the accepted method of creating a system buffer or buffer with no undo-redo capability. See the description of buffer_flags for a description of the attributes controlled by the b_flags argument. System buffers system buffers need not be associated with any file. For this reason, the file argument may be specified as "", an empty string, when creating a system buffer. The higher level function edit_file(), which calls this routine, may be used as an alternative to this function.──────────Value returned: create_buffer() returns the numeric id that the editor system has given to the newly created buffer. This id should be stored for later use but never modified. If the function fails, usually due to an invalid file argument, a zero value is returned. The function will also fail if the named file is already open as a result of a call to fopen().──────────See also: buffer_filename, buffer_original_filename, attach_window_buffer(), edit_file()══create_factory_window() PELPurpose: Creates a new window for system use.──────────Syntax: winid create_factory_window([int x, y, wide, high [, flags]])──────────Description: The create_factory_window() function creates a new window and initializes the associated variables to the system internal defaults. The window is placed at the location defined by the x, y, wide and high arguments. The x and y arguments indicate the column and line offset at which SPE will locate the upper left corner of the window. The wide and high arguments indicate the number of columns and lines the window will occupy. If any or all of these arguments is omitted the largest possible window is created. This means that the window occupies the entire screen except for a single line at the top or bottom for a dialog window, if defined. The variables associated with the new window are initialized to internal defaults whenever reasonable. The function will not, for example, select colors that will make the window effectively invisible against its background. The value of the corresponding default_... variables are ignored. If, however, the optional flags argument is supplied, the window's window_flags variable is initialized to that value rather than the internal value. This is useful if the window to be used as a system window. See the description of the default_window_flags variable for details of the flags argument. The Zoom Status Field of the flags argument is always ignored. The newly created window is inserted into the windows list in the position immediately following the currently active window. It is not automatically made current nor is it attached to any buffer. The function attach_window_buffer() is provided to define associations between windows and buffers.──────────Value returned: create_factory_window() returns the numeric id that the editor system has given to the newly created window. This id should be stored for later use but never modified. If the function fails a zero value is returned.──────────See also: edit_file(), create_window(),attach_window_buffer()══create_keymap()Purpose: Creates new keymap in preparation for customization.──────────Syntax: keymapid create_keymap([keymapid keymap])──────────Description: The create_keymap() function produces a new keymap that may then be customized. The new keymap is initialized to the values of the keymap described by the keymap argument. If the keymap argument is missing, the empty_keymap is used. If an invalid argument is specified, the function will fail.──────────Value returned: The value returned by create_keymap() is the id assigned to the new keymap by the system. A return value of zero indicates that the function has failed.──────────See also: current_keymap delete_keymap()══create_mark()Purpose: Place a bookmark at a specified buffer location.──────────Syntax: markid create_mark(markid num [, int line, int col])──────────Description: The create_mark() function places a bookmark at the buffer location specified by the line and col arguments. If these arguments are not supplied, the current line and column position are used. Values less than one for the col and line arguments are treated as a value of one. A value for line higher than the number of lines in the buffer is converted to the number of the last line in the buffer. However, if the col value is higher than the number of columns in the indicated line, the marker is placed beyond the end of the line. The num argument to this function is a bookmark id number. This bookmark id may be either an unused id number or the id of a bookmark already in use. A bookmark id of less than 1 will cause this function to fail. If the num id represents a bookmark already in use, the bookmark is reassigned to the location specified.──────────Value returned: The value returned by the create_mark() function is the numeric id placed at the specified location.══create_medium_window()Purpose: Creates quarter screen window at mid- screen.──────────Syntax: winid create_medium_window()──────────Description: The create_medium_window() function creates a window in middle of screen that occupies a quarter of the screen area. Such windows are useful as pop-up windows or in situations where it is expected that the window will immediately require moving or resizing.──────────Value returned: On success, this function returns the id of the window created. On failure, it returns zero.══create_temp_name()Purpose: Creates a string containing a unique filename.──────────Syntax: str create_temp_name([int min_size])──────────Description: The create_temp_name() function creates a unique filename, using the path named by the TMP or TEMP environment variable. This function provides the filename, including drive and path elements, in string form. While this function does create the file, it does nothing to ensure that the file will automatically be deleted. The optional min_size argument allows you to specify the anticipated file size in advance. Given this information, the function will ensure that the path selected for the file has adequate storage space available for the file. The min_size argument represents the minimum file size in bytes.──────────Value returned: The value returned by the create_temp_name() function is the newly created string containing the filename. If all of the directories designated for temporary files are full, the function will fail and return an empty string.══create_tiled_window() PELPurpose: Splits the current window into two windows.──────────Syntax: void create_tiled_window(pct [, vert])──────────Description: The create_tiled_window() function creates adjacent or "tiled" windows by splitting the current window into two separate windows. The two windows occupy the screen area formerly occupied by the window that was split. Both windows then view the current buffer. The pct argument specifies what percent of the original window will continue to be allocated to that window. The balance is allocated to the new window. The default action is to split the window horizontally. When split horizontally, the new window, the lower window, becomes current. The vert argument is used to split the window vertically. If the vert argument is supplied and is a value other than zero, windows are tiled vertically. The old window is then on the left and the window on the right is current.──────────Value returned: No useful value is returned by this function.──────────See also: delete_tiled_window() current_window══create_window()Purpose: Creates a new window at named coordinates.──────────Syntax: winid create_window([int x, y, wide, high [, flags]])──────────Description: The create_window() function creates a new window and initializes the associated variables to the current editor system defaults. The window is placed at the location defined by the x, y, wide and high arguments. The x and y arguments indicate the column and line offset at which SPE will locate the upper left corner of the window. The wide and high arguments indicate the number of columns and lines the window will occupy. If any or all of these arguments is omitted the largest possible window is created. This means that the window occupies the entire screen except for a single line at the top or bottom for a dialog window, if defined. The variables associated with the new window are initialized to the value of the corresponding default_... variables. If, however, the optional flags argument is supplied, the window's window_flags variable is initialized to that value rather than the value of default_window_flags. This is useful if the window to be created is an exception to the normal configuration. See the description of the default_window_flags variable for details of the flags argument. The Zoom Status Field of the flags argument is always ignored. This function is generally used only when you are able to supply the dimensions of the window. The make_window() function, however, creates a window and then allows the user to set the dimensions of the window manually, using arrow keys. The newly created window is inserted into the windows list in the position immediately following the currently active window. It is not automatically made current nor is it attached to any buffer. The function attach_window_buffer() is provided to define associations between windows and buffers.──────────Value returned: create_window() returns the numeric id that the editor system has given to the newly created window. This id should be stored for later use but never modified. If the function fails a zero value is returned.──────────See also: create_buffer(), attach_window_buffer(), create_factory_window() edit_file(), create_tiled_window() delete_window()══ctime() AWKPurpose: Supplies the time and date in string form.──────────Syntax: str ctime([int time])──────────Description: The ctime() function interprets the date stored in the time argument into a character string. If the time argument is omitted the string contains the current date and time. The coding of the time argument is described in detail in the description of the filetime() function. The character string takes the following form: week_day month day hh:mm:ss year week_day is the first three characters of the day of the week and month is the first three letters of the month. day represents the day of the month. This is followed by the time of day, given in 24 hour format, and the year. For example: Wed Jul 05 15:03:22 1989──────────Value returned: The value returned by the ctime() function is the string containing the date and time.──────────Compatibility: This function is quite similar to the ctime() function supported by major C compilers except that the string returned does not contain a new-line sequence.══current_bufferPurpose: Identifies the currently active edit buffer.──────────Type: bufid current_buffer──────────Description: The buffer id for the currently active buffer is stored in current_buffer. This variable may be read, used in comparisons and may be assigned any valid buffer id. Care should be taken in making assignments to current_buffer, however, since changing the current buffer changes the buffer associated with the current window.──────────See also: create_buffer(), delete_buffer(), attach_window_buffer()══current_column bufferPurpose: Stores the column number of the current position.──────────Type: int current_column──────────Description: Each edit buffer has a current_column variable associated with it. The column number of the current position in the active buffer is stored in the variable current_column. The column count begins with column 1, which is the first column represented at the far left of the edit window before scrolling. This is not a screen coordinate but rather a buffer location. When this value is modified by the user, the cursor moves to the column indicated by the new value.──────────See also: current_line_offset══current_command read-onlyPurpose: Stores the id of the most recently invoked function.──────────Type: funcid current_command──────────Description: The current_command variable contains the function id of the function that was most recently executed from the keyboard. This includes any functions which have been assigned to keys. This variable does not necessarily reflect the function currently being executed. The function id stored in current_command may be converted to a string containing the name of the function. This is done through use of the function_name() function. This variable may only be modified by the system.──────────See also: function_caller(), prev_command══current_key read-onlyPurpose: Stores most recent keystroke received from keyboard.──────────Type: int current_key──────────Description: The current_key variable contains the value of the most recent key combination entered by the user. If the key pressed was an ordinary character, its ASCII value will be found in the least significant byte and the scan code is in the high byte of current_key. If, however, the key returned an extended code, the least significant byte will be null and the code will be in the second byte of current_key.══current_keymapPurpose: Stores the id of the keymap presently in use.──────────Type: keymapid current_keymap──────────Description: The current_keymap variable contains the keymap id of the keyboard definition currently in use. This is the keymap in effect regardless of which buffer is currently being edited. The keymap currently in use may be changed by assigning a new value to this variable. If an invalid keymap id is assigned to current_keymap, the assignment will have no effect. The actual key assignments in effect may also be influenced by another keymap which overlays the one indicated by this variable. These keymaps used as overlays are local in that they only apply to a specific buffer. The buffer_keymap variable indicates when a keymap has been overlaid by another. During the construction of a new keymap it is common to assign an blank keyboard definition (empty_keymap) to current_keymap and then add key assignments. If, however, the editor is allowed to proceed using an empty keymap the editor will become unusable. The only recourse under such circumstances is to press [Ctrl][Break] and exit the editor by aborting.══current_line bufferPurpose: Stores the line number of the current position.──────────Type: int current_line──────────Description: Each edit buffer has a current_line variable associated with it. The line number of the current position in the active buffer is stored in the variable current_line. The line count begins with line 1, which is the first line of the buffer. This is not a screen coordinate but rather a buffer location. When this value is modified by the user, the cursor moves to the column indicated by the new value. Negative values assigned to current_line will be treated as 1.══current_line_length read-only, bufferPurpose: Stores the length of the current line in characters.──────────Type: int current_line_length──────────Description: The current_line_length variable stores the number of characters in the current line. In this count tabs count only as a single character. The number of columns occupied by the line will depend upon how many tabs the line contains.──────────See also: current_line_width══current_line_offset read-only, bufferPurpose: Stores the character offset of the current line position.──────────Type: int current_line_offset──────────Description: Each edit buffer has a current_line_offset variable associated with it. The number of characters preceding the current position in the line is stored in the variable current_line_offset. When the cursor is in column one this value will therefore be zero. This value may not be modified by the user or user written functions. The variable current_column may be used to change the position in the line.──────────See also: current_column══current_line_width read-only, bufferPurpose: Stores the length of the current line in columns.──────────Type: int current_line_width──────────Description: The current_line_width variable stores the number of columns the current line occupies, based on current settings. This is not a count of characters in the current line. The number of characters in the line will depend upon how many columns are occupied by tabs.──────────See also: current_line_length══current_windowPurpose: Stores the id number of the current window.──────────Type: winid current_window──────────Description: The current_window variable contains the id number of the currently active window. The window id is the number assigned to the window by the system at the time of its creation with the create_window() function. This variable may be read, used in comparisons and may be assigned any valid window id. Keep in mind that in making assignments to current_window that buffer associated with the window you make current will become current. For this reason changing the value of current_window usually results in a new value for current_buffer as well.──────────See also: create_window(), delete_window(),attach_window_buffer()══cursor_normalPurpose: Store the shape of the normal editing cursor.──────────Type: int cursor_normal──────────Description: The shape of the normal (insert mode) cursor is stored in the least significant two bytes or the variable cursor_normal. This variable may be set by the user. The high byte contains the number of the beginning scan line and the low byte contains the number or the ending scan line. This variable should be set with care since the number of scan lines may vary from one video adapter to another. Many random values will make the cursor disappear. The default value for monochrome systems and all OS/2 systems is 0C0DH. The default value for MS-DOS color systems is 0507H.──────────See also: cursor_overtype,cursor_virtual_overtype, cursor_virtual.══cursor_overtypePurpose: Store the cursor shape used in overtype mode.──────────Type: int cursor_overtype──────────Description: The shape of the cursor displayed when in the overtype editing mode is stored in the least significant two bytes or the variable cursor_overtype. The storage format used is the same as in the description of cursor_normal. The default value for monochrome systems and all OS/2 systems is 010DH. The default value for MS-DOS color systems is 0007H.──────────See also: cursor_virtual,cursor_virtual_overtype, cursor_normal══cursor_virtualPurpose: Store shape of the cursor used when in VIRTUAL SPACE.──────────Type: int cursor_virtual──────────Description: The shape of the cursor displayed when it is positioned outside the buffer's existing line boundaries or in space resulting from tabs (VIRTUAL SPACE) is stored in the variable cursor_virtual. This information occupies the least significant two bytes of this four byte variable. The storage format used is the same as in the description of cursor_normal. The default value for monochrome systems and all OS/2 systems is 070DH. The default value for MS-DOS color systems is 0407H.──────────See also: cursor_overtype,cursor_virtual_overtype cursor_normal.══cursor_virtual_overtypePurpose: Store shape of the cursor used when in VIRTUAL SPACE.──────────Type: int cursor_virtual_overtype──────────Description: The cursor_virtual_overtype variable stores the cursor shape displayed when it is positioned in VIRTUAL SPACE and overtype mode is in effect. VIRTUAL SPACE is the area outside the buffer's existing line boundaries and the area created by tabs. The cursor shape information occupies the least significant two bytes of this four byte variable. The storage format used is the same as described in cursor_normal. The default value for monochrome systems and all OS/2 systems is 0107H. The default value for MS-DOS color systems is 0003H.──────────See also: cursor_overtype, cursor_normal,cursor_virtual.══cut() PELPurpose: Copy text to the scrap buffer and then delete it.──────────Syntax: int cut()──────────Description: The cut() function copies a block of text to the scrap buffer in the same manner as the copy_to_scrap() function, described above. If no block has been defined the line containing the cursor is copied to the scrap buffer. With no block defined the character at the cursor position is copied. After this is done, however, the cut() function deletes the copied text from its original location in the edit buffer. The text may then be re-inserted elsewhere in the buffer through use of the insert_scrap() or paste() function. This function has the effect of removing any selection marker (anchor) that was used to mark the block to be deleted. If any previous selections were made, the most recent selection becomes active. This function is synonymous with the delete_to_scrap() function.──────────Value returned: When successful, the cut() function returns a non-zero value (TRUE). If for any reason the function can not be completed, a zero (FALSE) value will be returned.══debug() PELPurpose: Invokes the debugging package.──────────Syntax: void debug()──────────Description: The debug() function provides a convenient method of finding out what the extension language functions you have written are doing when they aren't doing what you expected. This function uses a number of low-level functions to allow you to set break points, step through your code, and trace into functions or step over them. The command set used is a subset of that used by Microsoft's CodeView Debugger. These commands are listed below. Case is not significant in these commands, however, case is always significant in function names. They must be accurately specified when used as an argument to a command: General Commands [Enter] Execute command on current line of Command window [Ctrl][PgUp] Go to top of buffer [Ctrl][PgDn] Go to bottom of buffer [Ctrl][T] Shrink currentwindow [Ctrl][G] Grow current window EXIT or Q Exit debugger H Display Help message K Show function call stack V <file> View a file @ Redraw the display #<columns> Set tabs . Go to current program location(line to execute) ?<expression> Display or set data Run Commands This group of commands cause the subject code to be partially executed or executed continuously. E Execute (trace into) until key is pressed. G [<function>] Go or go to <function> P [<count>] Step over one or <count> time(s) T [<count>] Trace into one or <count> time(s) Breakpoints A breakpoint is a place in the program where execution automatically stops. The <id> in the formats below represent a PEL function name. A * refers to all defined breakpoints. Setting a breakpoint at a specific line rather than a function must be done using the [F9] key. The debugger only works on PEL source code. If you attempt to set a breakpoint on a primitive (built-in function) rather than a PEL function you will receive an error message. BC [<id> or *] Clear breakpoint BD [<id> or *] Disable breakpoint BE [<id> or *] Enable breakpoint BP [<id>] Set breakpoint BL List breakpoints Function Keys Some commonly used and simple commands have been assigned to function keys. [F1] Display help message [F4] Toggle between editor and debugger screen [F5] Go [F6] Change current window [F8] Trace into function [F9] Set breakpoint at current line [F10] Step over function Searching and Options Searching commands enable the user to find a string in the file displayed in the Source View window. Execution is not effected. Window switching or "flipping" is when the editor screen is restored before each command is executed. /[<string>] Search again or search for string O List all option settings OR[+|-] Enable/disable/show status Regex searching OC[+|-] Enable/disable/show status Case sensitive searching OF[+|-] Enable/disable/show status Window switching The most convenient way to start a debugging session is not to call the debug() function at all. Instead, you use the bp() function to set a breakpoint (stopping place) on the function you are interested in and then let the debugger pop up automatically when you reach that function. For example, you might want to debug a function new_backspace() which has been assigned to execute when the backspace key is pressed. You could begin the debugging session by pressing [F10] (or other key to which invoke_function() has been assigned) and then entering the following command to the interpreter: bp new_backspace When next you press the backspace key, the debugger window pops up on the right-hand side of the screen. If the function you are debugging is not assigned to a key, you may reach the defined breakpoint by invoking that function through the PEL interpreter: new_backspace The Debugger window is actually two windows: a Source View window and a Command window. The line of PEL source code that is about to be executed is highlighted in the Source View window. You instruct the Debugger how to proceed through the command window. You may treat the Debugger windows as a unit or resize or separate the windows using standard mouse commands. You may select the Source View window and scroll through the source file to see the context of the line to be executed. If you type characters while the Source View window is selected, you will not alter the source file or its appearance. These characters will appear as commands in the Debugger's Command window. The cursor, however, remains in the Source View window. There are a number of Debugger commands that may be executed by either typing a command in the command window or by pressing a function key. It is often preferable to use the function keys whenever possible. One benefit is that fewer keystrokes are required, but the primary benefit is that the more complex commands that must be entered in the Command window are not scrolled away by the single character commands. The reason you will want to keep these commands handy is that commands can be repeated by moving the cursor to the line containing the desired command and pressing [Enter].──────────Value returned: No useful value is returned by this function.══default_...Purpose: Defines initial value of window or buffer variable.──────────Type: str default_buffer_eof_string str default_buffer_eol_string int default_buffer_flags str default_buffer_tabs int default_color_border int default_color_highlight int default_color_linenumbers int default_color_text int default_color_title str default_linenumber_format int default_scroll_context_bottom int default_scroll_context_left int default_scroll_context_right int default_scroll_context_top int default_scroll_means_pan int default_scroll_unit_horizontal int default_scroll_unit_vertical str default_visible_end_buffer str default_visible_newlines str default_visible_spaces str default_visible_tabs str default_visible_virtual_lines str default_visible_virtual_spaces int default_window_flags int default_window_page_offset int default_window_page_overlap int default_wp_left_margin int default_wp_right_margin──────────Description: Each buffer or window has a series of variables associated with it. These are variables that may require different values for different buffers. For example, one buffer may require tab stops at every four columns while another requires them at every eight. This series of variables obtain their initial value from another global set of variables at the time the buffer or window is created. These special variables are the default_... series of variables. The global variable corresponding to the buffer or window variable has the same name as the buffer or window variable but prefixed by default_. The value of the global variable is copied into like-named variable at the time the buffer is created. This local variable is then an attribute of the buffer or window. For example, each buffer has a buffer_tabs variable associated with it. Each buffer_tabs variable derives its initial value from the single global variable named default_buffer_tabs. After the buffer has been created, the buffer_tabs variable may be accessed or changed whenever that buffer is current. The value of the variable default_buffer_tabs may be changed at any time, but the new value is only used by buffers subsequently created. The default values for the default_... buffer variables are as follows: default_buffer_eof_string "" default_buffer_eol_string "\r\n" default_buffer_flags 0 default_buffer_tabs "9 17" default_wp_left_margin 1 default_wp_right_margin 77 The default values for the default_... window variables are as follows: default_color_border DOS default_color_highlight Reverse default_color_linenumbers Yellow on Black default_color_text DOS default_color_title Reverse default_linenumber_format "" default_scroll_means_pan 1 default_visible_end_buffer "" default_visible_newlines "" default_visible_spaces " " default_visible_tabs " " default_visible_virtual_lines "" default_visible_virtual_spaces " " default_scroll_context_bottom 0 default_scroll_context_left 0 default_scroll_context_right 0 default_scroll_context_top 0 default_scroll_unit_horizontal 1 default_scroll_unit_vertical 1 default_window_flags 0x1091 default_window_page_offset 0 default_window_page_overlap 1══delete_all_marks()Purpose: Undefine all bookmarks previously defined.──────────Syntax: int delete_all_marks()──────────Description: The delete_all_marks() function provides a method of "starting from scratch" with no defined bookmarks. This function disposes of all bookmarks regardless of their origin or purpose. It is considered good programming practice to ensure that no region of text is currently selected before executing this function.──────────Value returned: The value returned by the delete_all_marks() function is the number of marks removed.══delete_buffer()Purpose: Disposes of a previously created edit buffer.──────────Syntax: int delete_buffer([bufid buffer])──────────Description: The delete_buffer() function removes the buffer identified by the buffer argument from the editor system. The buffer argument is the numeric id returned by the function used to create the buffer. If the buffer argument is not supplied, the current buffer is deleted. Whenever the current buffer is deleted the next buffer in the buffer list becomes current. If a window was attached to the deleted buffer, the window is reassigned to the next buffer in the buffers list. When deleting both the current buffer and the current window the buffer should be deleted first. If the window is deleted first the current buffer will change, often resulting in the wrong buffer being deleted. If there are no more buffers in the buffers list, the buffer may be deleted but the editor will create a new empty one in its place. Any windows assigned to the last buffer are reassigned to the new buffer. This new buffer will receive the name "Scratch" and it's buffer_flags variable will be set to indicate that it is a system buffer and is not writable. SPE uses this same default buffer when the editor is invoked without indicating a file to be edited.──────────Value returned: When successful, delete_buffer() returns a non zero or TRUE value. Upon failure, this function returns zero (FALSE).══delete_buffer_key()Purpose: Removes buffer, does not make system buffer current.──────────Syntax: void delete_buffer_key()──────────Description: Like delete_buffer(), the delete_buffer_key() function deletes current buffer. However, if the next buffer in the buffer list is a system buffer, delete_buffer_key() does not allow it to become the current buffer as the delete_buffer() function would. Instead, this function makes the next normal buffer current. If there is no other normal buffer, the "Scratch" buffer is created. This behavior makes delete_buffer_key() more suitable for assignment to a key than its relative, delete_buffer().──────────Value returned: No useful value is returned by this function.══delete_chars()Purpose: Delete text from the current edit buffer.──────────Syntax: int delete_chars([int num])──────────Description: The delete_chars() function removes characters from the current buffer. The number of characters to delete is specified by the num argument. If the num argument is not supplied the function deletes the selected block of text if one has been marked. Otherwise this function deletes a single character.──────────Value returned: The delete_chars() function returns a non- zero value (TRUE) upon successful completion. If there are no characters for the delete function to remove, the function will return a zero value (FALSE).══delete_event()Purpose: Removes association between an event and a function.──────────Syntax: int delete_event(int event, funcid id)──────────Description: The delete_event() function breaks the association between the event indicated by the event argument and the function specified by id. After executing delete_event(), the named function will not be executed automatically when the event is triggered. Other functions associated with the event will still be executed.──────────Value returned: Upon successful completion, the delete_event() function returns a non-zero (TRUE) value. If the event argument is not a valid event or the id argument is not a function id associated with that event, the function will fail. A value of zero (FALSE) is then returned.══delete_keymap()Purpose: Deletes a keyboard definition from the system.──────────Syntax: int delete_keymap(keymapid keymap)──────────Description: The delete_keymap() function disposes of a keymap definition and undefines the associated id. This function may not be performed on the keymap currently in use. This function should be used with discretion since its use can result in references to non-existent keyboard definitions on the keymap stack.──────────Value returned: The value returned by the delete_keymap() function is non-zero (TRUE) upon successful completion. A return value of zero or FALSE indicates that the function has failed.══delete_line()Purpose: Remove the current line from the edit buffer.──────────Syntax: int delete_line()──────────Description: The delete_line() function removes the line in which the cursor appears from the buffer. The cursor line and column positions are not changed by executing this function.──────────Value returned: Upon successful completion, the delete_line() function returns a non-zero value (TRUE). If the cursor is at the end of the buffer, on a line containing no text or newline, the function will fail, returning a zero value (FALSE).══delete_mark()Purpose: Dispose of a specified bookmark.──────────Syntax: markid delete_mark(markid mark)──────────Description: The delete_mark() function disposes of the bookmark associated with the bookmark id contained in the mark argument. Any attempt to remove bookmark 0, the current cursor position, with this function will have no effect. This function should not be used to dispose of selection bookmarks created with the drop_anchor() function.──────────Value returned: The value returned by the delete_mark() function is the numeric id of the bookmark which has been removed. If the function fails, a zero value is returned.══delete_tiled_window() PELPurpose: Deletes a window and allocates its space to a neighbor.──────────Syntax: int delete_tiled_window([winid win])──────────Description: Tiled windows are created by splitting existing windows either horizontally or vertically. The resulting series of windows with contiguous borders look something like an arrangement of ceramic tiles; hence they are called tiled windows. Tiled windows are the most convenient type of window when you do not wish to use a mouse. When using a mouse, overlapping windows are usually preferred. The delete_tiled_windows() function deletes the window specified by the win argument. If no argument is specified the current window is deleted. After deleting the window, delete_tiled_window() resizes a contiguous window so that it occupies the portion of the screen previously occupied by the deleted window. If there is no window sharing a border with the window to be deleted, the window is deleted but the portion of the screen occupied by that window is not reallocated.──────────Value returned: Upon successful completion, delete_tiled_windows() returns a non-zero (TRUE) value. If the function fails, a zero (FALSE) value is returned.──────────See also: delete_window(), delete_buffer()══delete_to_eol()Purpose: Delete from the cursor position to the end of the line.──────────Syntax: int delete_to_eol()──────────Description: The delete_to_eol() function deletes all text from the cursor position to the end of the line. This includes any character under the cursor position. The end-of-line sequence is not deleted.──────────Value returned: The value returned by delete_to_eol() is non-zero (TRUE) unless there were no characters to delete, in which case a zero value (FALSE) is returned.──────────See also: buffer_eol_string, delete_chars()══delete_to_scrap() PELPurpose: Copy text to the scrap buffer and then delete it.──────────Syntax: int delete_to_scrap()──────────Description: The delete_to_scrap() function copies a block of text to the scrap buffer in the same manner as the copy_to_scrap() function, described above. When no block has been defined the character at the cursor position is copied. After this is done, however, the delete_to_scrap() function deletes the copied text from its original location in the edit buffer. The text may then be re- inserted elsewhere in the buffer through use of the insert_scrap() function. This function has the effect of removing any selection marker (anchor) that was used to mark the block to be deleted. If any previous selections were made, the most recent selection becomes active. For those who are familiar with the concepts of "cut and paste", this function is analogous to "cut". The insert_scrap() function serves as a "paste" feature.──────────Value returned: When successful, the delete_to_scrap() function returns a non-zero value (TRUE). If for any reason the function can not be completed, a zero (FALSE) value will be returned.══delete_window()Purpose: Dispose of a window.──────────Syntax: void delete_window([winid window])──────────Description: The delete_window() function discards the window described by the window argument. The window argument is a window id number assigned by the editor system when the window was created. If the window argument is omitted, the current window is deleted. The window id of the deleted window is no longer valid. Caution should be exercised when deleting active windows and buffers. When the active window is deleted, the next window in the window list and its buffer become active. When deleting both the current buffer and the current window the buffer should be deleted first. If the window is deleted first the current buffer will change, often resulting in the wrong buffer being deleted. Unlike buffers, you may delete the last window. You will then have very little to look at.──────────Value returned: No useful value is returned by the delete_window() function.══delete_window_and_buffer()Purpose: Deletes a window and its associated buffer.──────────Syntax: void delete_window_and_buffer([winid win])──────────Description: The delete_window_and_buffer() function deletes the current buffer and window or, if a window is specified as an argument, deletes the specified window and associated buffer. The function is useful for assignment to a key, and also avoids the pitfall of deleting the wrong buffer when the window is deleted first.──────────Value returned: No useful value is returned by this function.══delete_window_key()Purpose: Delete window; make normal window current.──────────Syntax: void delete_window_key()──────────Description: Like delete_window(), the delete_window_key() function deletes current window. However, if the next window in the window list is a system window, delete_window_key() does not allow it to become the current window as the delete_window() function would. Instead, this function makes the next normal window current. If there is no other normal window, no windows are displayed. This behavior makes delete_window_key() more suitable for assignment to a key than its relative, delete_window().──────────Value returned: No useful value is returned by this function.══delete_word()Purpose: Delete word or words following cursor.──────────Syntax: void delete_word([int n])──────────Description: The delete_word() function deletes from current position to the next word. The number of words to be deleted may be specified as the n argument. A word is defined as a series of non-whitespace characters surrounded by whitespace. Whitespace includes spaces, tabs, newlines, beginning and end of buffer.──────────Value returned: No useful value is returned by this function.══dialog_windowPurpose: Indicates which window is to be used for dialog.──────────Type: winid dialog_window──────────Description: The dialog_window variable may contain the window id of a window to be used for messages and prompting. The window id is the value returned from the create_window() function when the window was created. If the value of dialog_window does not represent a valid window id, the system will temporarily "pop-up" windows as needed to serve these purposes. The default value for this variable is 0, which is an invalid window id.══disk_free()Purpose: Reports storage space available on a drive.──────────Syntax: int disk_free([str drive or int drive])──────────Description: If the drive argument is present, disk_free() reports the amount of free disk space for the drive specified in that argument. The drive argument may be a string whose first character is the letter of the drive of interest. The rest of the string is ignored. Alternately, drive may be a drive number, where drive A: is 0, drive B: is 1 and so on. If drive is not supplied, disk_free() reports the amount of free disk space for the default drive.──────────Value returned: The number of bytes of free disk space is returned on successful completion. A value of zero is returned if the function has failed. To distinguish between a disk-full condition and an invalid drive specification (or other error) it is necessary to consult the errno variable. If this variable is zero, the disk is full. Non-zero values for errno indicate that the function failed.══display_ascii_table()Purpose: Invokes ASCII table desktop tool.──────────Syntax: void display_ascii_table()──────────Description: The display_ascii_table() function displays an ASCII reference chart on the screen. The up and down arrows and page-up and page-down keys may be used to page through the chart. Pressing the "I" key allows inserting a character by supplying its decimal value. When done, the chart is sent away by pressing [Esc].──────────Value returned: No useful value is returned by this function.══display_errors()Purpose: Displays compile errors for current buffer.──────────Syntax: void display_errors()──────────Description: The display_errors() function pops up the error listing file for the current buffer in a window. The error listing file is the file containing error messages output by the compiler during the last compile of the current buffer's file type. If there were no errors during the last compile, the error listing file will not exist and a message to that effect will be displayed. If the rules for parsing the displayed error messages are known to the editor, you may highlight an error of interest and then move to the offending location in the source file by pressing [Enter]. There are several rule sets for error parsing known to SPE. You may define which rule set is used for a given file type with the add_compiler() function. The default rule sets, however, will work with the most common compilers without modification.──────────Value returned: No useful value is returned by this function.══display_filename()Purpose: Display buffer's filename as reminder.──────────Syntax: void display_filename()──────────Description: The display_filename() shows the output filename associated with the current buffer in the dialog window. It is largely intended for use after operations that change the current buffer or its filename.──────────Value returned: No useful value is returned by this function.══display_height read-onlyPurpose: Stores the display's height in lines.──────────Type: int display_height──────────Description: The display_height variable contains the number of lines that are currently displayed. This variable is maintained by the system and may not be modified by the user.══display_mode()Purpose: Change display mode settings.──────────Syntax: int display_mode([int h [, w [, pg [, addr [, mode]]]]])──────────Description: The display_mode() function sets the parameters of the current video display mode. It has two primary uses. The first use is in allowing SPE to make use of non- standard video adapters. This requires a certain amount of technical information provided by the manufacturer of the adapter. The second use for this function is to change display modes without exiting the editor. The h and w arguments are the number of lines and columns of text, respectively, that are to be displayed. The pg argument specifies the number of display pages the video card can hold. The addr is the starting address of the contiguous pages of video memory (take care when specifying this one). The mode argument is a number, usually specific to video adapter installed, instructs the video BIOS what mode to use. Users familiar with the technical aspects of their machines may be able to obtain unusual modes by supplying the proper value for this argument. The pg, addr and mode arguments have no effect under OS/2. Each of the arguments to display_mode() is optional. In addition, if the value for a parameter is unknown or does not require change, a zero value may be specified for that argument. This allows you to take a conservative approach to changing the video settings; this is the approach we recommend. Here are a few examples from common usage: display_mode(43,0,0,0) Sets EGAs to 43 line mode. display_mode(50) Sets VGAs to 50 line mode. display_mode(0,132) Sets EGAs, VGAs to 132 column mode. CGA Users: If you need to suppress snow you must not use this function to tell the editor that you have more than one video page. Always specify the number of video pages as one.──────────Value returned: The value returned by the display_mode() function is the current video mode. This may be used to detect monochrome monitors. Under OS/2 this function always returns 3.══display_redraw()Purpose: Redraw the entire visible screen.──────────Syntax: void display_redraw()──────────Description: The display_redraw() function re-draws the display screen including the contents of all visible windows. This function is useful when you have run a program that fails to properly restore the screen. It is also useful to call display_redraw() when you make a mess of the display with printf().──────────Value returned: No useful value is returned by the display_redraw() function.──────────See also: display_update()══display_suppress_snowPurpose: Determines method of writing to the screen.──────────Type: int display_suppress_snow──────────Description: When the display_suppress_snow variable is set to a non-zero value, writing to screen memory is done only during horizontal retrace, to avoid the appearance of "snow" on the screen. This is normally only necessary when an older CGA video card is in use. If the value of display_suppress_snow is zero, writing to screen memory is done without delay. This is the default method of operation. SPE is normally able to detect the presence of a CGA adapter and sets this variable accordingly. If your CGA is not susceptible to snow you will want to set this variable to zero.══display_update()Purpose: Update the visible screen with recent changes.──────────Syntax: void display_update()──────────Description: The display_update() function updates the display screen to reflect recent changes. This differs from the display_redraw() function in that only changes are sent to the screen. In most cases only a small portion of the screen is re-drawn. Since updating the screen tends to slow the functioning of SPE, updating the screen is only done at intervals. In addition, the display screen is usually not updated while a PolyAWK function is executing. In writing a function, you may wish to ensure that the display reflects recent changes at some point in the function. For example, if you change buffers and then use getkey() to obtain input, you will need to call display_update() for the users to see that the current buffer has changed. Just as flushing a file buffer ensures that the file is up to date, display_update() ensures that the screen reflects all changes. The changes that are updated are changes to the contents of buffers and all other visible contents of the display screen. User written programs are not required to call this function. All changes to screen contents will be reflected in the normal course of editor operations.──────────Value returned: No useful value is returned by the display_update() function.══display_width read-onlyPurpose: Stores the display's width in columns.──────────Type: int display_width──────────Description: The display_width variable contains the number of columns are currently displayed. This variable is maintained by the system and may not be modified by the user.══distance_between_marks()Purpose: Tells number of characters between specified marks.──────────Syntax: int distance_between_marks(int mark1, int mark2)──────────Description: This function is used to discover the number of characters in a block or region defined by the arguments. Arguments mark1 and mark2 are both any previously defined bookmarks. These bookmarks are specified by the id assigned to them at the time they were created. They may be supplied in any order, regardless of which occurs first in the buffer. The distance measured includes one of the bookmarks but not both.──────────Value returned: The value returned by the distance_between_marks() function is the number of bytes between the two specified marks. Tabs count only as a single character. The value returned will be zero if either of the bookmarks referenced as arguments is not defined.══distance_next_tab read-onlyPurpose: Indicates the number of columns to next tab stop.──────────Type: int distance_next_tab──────────Description: Each edit buffer has a distance_next_tab variable associated with it. The number stored in distance_next_tab represents the column number of the current position subtracted from the column number of the tab stop to the right. This gives the number of columns which must be transited to reach the next tab stop. This value is updated by the system and may not be modified by the user.══distance_prev_tab read-onlyPurpose: Indicates the number of columns to previous tab stop.──────────Type: int distance_prev_tab──────────Description: Each edit buffer has a distance_prev_tab variable associated with it. The number stored in distance_prev_tab represents the column number of the tab stop to the left subtracted from the column number of the current position. This gives the number of columns which must be transited to reach the previous tab stop. This value is updated by the system and may not be modified by the user.══distance_to_window_...() PELPurpose: Store distances from cursor to window extremities.──────────Syntax: int distance_to_window_bottom() int distance_to_window_left() int distance_to_window_right() int distance_to_window_top()──────────Description: The several distance_to_window_...() functions provide the distance in columns or lines between the current cursor position and various window limits.──────────Value returned: The distance_to_window_...() series of functions returns a value equal to the number of left()/right()/up()/down() cursor motions necessary to move to the indicated window extremity.══done()Purpose: Exit the editor normally.──────────Syntax: void done()──────────Description: The done() function provides an orderly exit from the Sage Professional Editor. It prompts before exiting if any buffers are modified. At that time it offers the options of exiting without saving, cancelling the exit or writing all modified buffers.──────────Value returned: No useful value is returned by this function.══dos_date()Purpose: Converts encoded date into corresponding date string.──────────Syntax: str dos_date([int datenum])──────────Description: The dos_date() function converts the date encoded in the datenum argument into a discernable string. This string follows the form: MM/DD/YY. When the datenum argument is omitted, the string produced contains the current date.──────────Value returned: The value returned by the dos_date() function is the new string containing the date. If the datenum argument indicates a date prior to January 1, 1980 the function will return an empty string.══dos_drive()Purpose: Obtain or set the current drive.──────────Syntax: str dos_drive([str id or int id])──────────Description: dos_drive() has two modes of operation. The mode selected depends on whether the id argument has been supplied. If id is present, the drive it specifies becomes the current default drive. In this mode, id may be any string whose first character is the letter of the drive which is to become the default. The rest of the string is ignored. Alternately, id may be a drive number, where drive A: is 0, drive B: is 1 and so on. If id is not supplied, dos_drive() is treated as an inquiry as to which drive is the current default.──────────Value returned: On success, dos_drive() returns a new string. This string contains the letter of the drive which is the current default followed by a colon. This string reflects the new default drive, if any has been requested. On failure, an empty string is returned.══dos_time()Purpose: Converts encoded time into time string.──────────Syntax: str dos_time([int timenum])──────────Description: The dos_time() function converts the time encoded in the timenum argument into a discernable string. This string follows the form: HH:MM:SS. If the datenum argument is omitted, the string produced contains the current time.──────────Value returned: The value returned by the dos_time() function is the new string containing the time. If a negative value is supplied as an argument, the function will return an empty string.══dos_verify_state()Purpose: Obtain or set the verify flag.──────────Syntax: int dos_verify_state([int state])──────────Description: When the DOS verify flag is on, writes to disk are immediately re-read to ensure that the correct data has been written. The dos_verify_state() function may be used to check and set the status of this flag. The state argument, if supplied, may be either zero or non-zero. The value of 0 indicates that the verify flag is to be turned off, while any other value indicates that it is to be turned on. If the state argument is omitted, the function is treated as an inquiry only and the verify flag is not modified.──────────Value returned: dos_verify_state() returns the status of the verify flag in effect at the time this function was called. This function cannot fail.══dos_window()Purpose: Run a command in a window.──────────Syntax: int dos_window([str command])──────────Description: The dos_window() function is like the system() function in that it allows you to execute a DOS command without leaving SPE. However, output appears in the current window rather than printing the output on a cleared screen. There are some limitations on the use of this function, however, which are discussed below. The command to be executed is specified by the command argument. If this argument is omitted the command interpreter described by the COMSPEC environment variable is invoked. By default this command interpreter is COMMAND.COM. In this case you must type EXIT┐ to return to SPE. Example: dos_window("dir") The output from this command may be redirected to a file, however, the output will continue to appear on the screen. In addition, if the redirected output exceeds 16K characters, only the last 16K are saved in the file. Example: dos_window(">out") This example invokes the command interpreter and redirects all output to a file named OUT. The current window may be an icon or otherwise too small to display the output from the command. In this case the screen is cleared and the output is displayed there unless it has been redirected. Some cosmetic aspects of the output are determined by the cursor location within the window when dos_window() is called. If the cursor is in the upper left corner of the window the screen will be cleared before output begins. Otherwise output will appear at the cursor location overwriting any text already visible there. The contents of the buffer, however, is not overwritten. Some cautions must be observed in using this functions: 1) Do not run programs such as MODE that reset the display mode. 2) Do not use this function if you have any programs installed that boost the speed of output to the screen. This includes any or the SCREEN BOOST programs included in the PolyBoost package and other programs that take over interrupts 10H or 29H.──────────Value returned: The value returned by the dos_window() function is the error code returned by the command executed.──────────See also: system()══down()Purpose: Move the cursor by lines toward the bottom of buffer.──────────Syntax: int down([int lines])──────────Description: The down() function advances the cursor the number of lines found in the lines argument. If the lines argument is not supplied, 1 line is assumed. Negative values for lines are allowed and result in the cursor moving in the opposite direction. In other words, calling down() with -3 as the argument is the as calling up() with 3 as the argument. The column position of the cursor resulting from a call to down() may be affected by the buffer_flags variable described above. If movement into VIRTUAL SPACE is allowed, the cursor always maintains the same column position at its new line location. If movements into VIRTUAL SPACE are disallowed the column position may change. When the down() function would position the cursor beyond the end-of-line, it moves to the nearest column on the new line location which contains a character. If down() moves the cursor into a tab, the cursor always moves to the beginning of the tab. If there are fewer lines remaining between the cursor position and the end of the buffer than the lines argument specifies, the cursor is moved to the last line of the buffer. A short beep is issued from the speaker if there are no lines between the cursor and the end of the buffer.──────────Value returned: The down() function returns a non-zero (TRUE) value to indicate that the cursor has been moved. If the cursor does not move as a result of this function, a zero or FALSE value is returned.══drop_anchor()Purpose: Place a selection mark at the current position.──────────Syntax: int drop_anchor([int typ [, markid id1 [, markid id2]]])──────────Description: The drop_anchor() function selects a block of text. The boundaries of the selected text are defined by the bookmark arguments id1 and id2. The position of id2 then becomes the current cursor position. A last-in, first-out stack of bookmarks placed with drop_anchor() is maintained. The most recent selection mark is removed through a call to the function raise_anchor(). When this is done, the defined block becomes the text between the current cursor position and the bookmark which preceded it on the stack. If the id2 bookmark is not supplied, the text between id1 and the current position is selected. If neither of the bookmark arguments are supplied, the mark is placed at the current position. The selection type is determined by the typ argument. The possible values for the type argument are the same as those used by the region_type() function. If all arguments are omitted a type 1 bookmark is placed at the current position. If id2 does not name a valid bookmark, text is marked from id1 to the current cursor position. If id1 is not a valid bookmark, however, the function fails.──────────Value returned: The value returned by the drop_anchor() function is non-zero (TRUE) on success. If an error occurs the function returns zero (FALSE).══dtree()Purpose: Select file from subdirectory tree.──────────Syntax: dtree([str path])──────────Description: The dtree() function generates a tree diagram of all the directories below the path specified in the argument. If the argument is omitted, the tree descends from the root of the current drive. The mouse or arrow keys may be used to select a directory within the diagram. Once a directory has been selected, it may be made the current directory or a directory listing may be displayed. Pressing [Enter] or [Tab] will both allow you to view the contents of the selected subdirectory. Pressing [Enter], however, will at the same time make the directory current. Single clicking or pressing [Tab] on a directory produces a listing of that directory without making it current. The listing contains files names, size and the time and date for each file. After the directory listing is displayed, a file may be selected for editing by pressing [Enter] or clicking on the file with the left mouse button.──────────Value returned: No useful value is returned by this function.══ec([int on]) PELPurpose: Turns code processing features on or off.──────────Syntax: void ec([int on])──────────Description: The ec() function is a terse synonym for toggle_electric(), suitable for executing through the PolyAWK interpreter ( [F10] ). It is used to turn the Code Processing features of the Sage Professional Editor on or off. If no on argument is supplied, Code Processing is toggled to its opposite condition. If the on argument is supplied, a zero value turns Code Processing off, while other values turn it on. Code Processing features include programming templates and construct matching features. The Code Processing Package, also called the electric package is described in the "Extension Language Packages" appendix to this manual.──────────Value returned: No useful value is returned by this function.══edit_file()Purpose: Opens a new buffer and assigns it to current window.──────────Syntax: bufid edit_file([str file])──────────Description: The edit_file() function creates a new buffer using the create_buffer() function and then assigns it to the currently active window with the attach_window_buffer() function. The file argument contains the name of the file from which data is read into the new buffer. This filename therefore becomes the value assigned to the buffer_filename and the buffer_original_filename for the new buffer. If this argument is omitted, the user is prompted for this value. The file argument is also used to define the value of the buffer_name. The buffer_name will be the same as buffer_original_filename except that it will contain no path element. Since edit_file() assigns the buffer it creates to the current window, the new buffer is always the currently active buffer upon completion of the function. To return to the buffer that was active prior to the call to edit_file(), execute the prev_buffer() function. It is possible to edit the same file in two different buffers, though this is not advisable. See create_buffer() above for a more complete discussion of this topic.──────────Value returned: edit_file() returns the numeric id that the editor system has given to the newly created buffer. This id should be stored for later use but never modified. If the function fails, usually due to an invalid file argument, a zero value is returned.══edit_file_key() PELPurpose: Enhanced function to open new buffer.──────────Syntax: void edit_file_key()──────────Description: Like edit_file(), the edit_file_key() function prompts for the name of new file to edit. It provides some additional assistance in selecting the new file: It has a history mechanism that displays the names of files previously selected when up or down arrows are pressed. It also will display a list of files matching a specified pattern when [Tab] is pressed (rather than [Enter]). A file may then be selected from the list. This function is used whenever reasonable in the emulation modes provided.──────────Value returned: No useful value is returned by this function.══editor_path()Purpose: Tells where the SPE Home Directory is.──────────Syntax: str editor_path()──────────Description: The editor_path() function reports the directory in which the Sage Professional Editor has been installed. This is generally referred to as the SPE Home Directory, which usually contains the SPE executables, configuration file and function library.──────────Value returned: The editor_path() function returns a string containing the path where the SAGEEDIT environment variable points. If the SAGEEDIT variable has not been defined, an empty string is returned.══emm_availablePurpose: Tells whether to use Expanded memory for swapping.──────────Type: int emm_available──────────Description: This variable instructs the editor to take advantage of EMS memory if a driver is installed. The default setting is off (0). When this variable is set to on (non-zero), the editor will make use of EMS as a swap area before using temporary disk storage. This variable is provided to allow you to reserve EMS memory for debuggers, and other utilities that may require EMS.══empty_keymap read-onlyPurpose: Stores id of keyboard definition with no assignments.──────────Type: keymapid empty_keymap──────────Description: The empty_keymap variable stores the keymap id number of a predefined keymap which contains no functions assigned to any of the keys. Typing exit commands or even simple characters is ineffective with this keyboard definition. The [Ctrl][Break] key, however, functions independently of any keymap and is therefore always defined. This variable is primarily used when creating a new keymap. Used as an argument to the create_keymap() function, empty_keymap provides a method of building a keymap from scratch. There are other predefined keymaps that allow you to build upon or modify a more substantial keyboard definition. This variable serves as a constant value and may not be modified by the user.──────────See also: factory_keymap, ascii_keymap══emulation_modePurpose: Stores name of emulation in use.──────────Type: str emulation_mode──────────Description: This variable is set by the various emulation modes to contain the name of the mode currently in use.══ENV AWKPurpose: Stores the values of environment variables.──────────Type: array ENV──────────Description: The ENV variable is an AWK array containing the values found in the DOS environment when the editor was invoked. The ENV variable takes advantage of AWK's ability to use strings as subscripts. The variable name is used as a subscript to access the value associated with that variable. For example, if the environment variable TMP has been set to the value C:\TEMP the value of ENV["TMP"] will also be C:\TEMP. Values in the ENV array may be changed or added in like manner through assignment. For example: ENV["INCLUDE"] = "c:\include" This new value for the environment variable is then in effect during the remainder of the editing process, unless changed.══errno read-onlyPurpose: Stores error code from last DOS operation.──────────Type: int errno──────────Description: The exit code returned by the last DOS command executed by SPE is stored in the variable errno. Consult this variable when a DOS or OS/2 operation indicates an error has occurred. This variable may not be modified by the user; only by the system.──────────See also: fread(), fwrite().══error()Purpose: Displays formatted output in the Dialog window.──────────Syntax: void error(str fmt [, any args,...])──────────Description: The error() function prints a formatted message to the Dialog window and aborts the PEL program currently processing. If no dialog window has been defined, a window pops up to display the message. In this case SPE pauses for a key to be typed before closing the window. The output from this function is suppressed if the variable message_level is 3. The extension language program, however, aborts regardless of how message_level is set. The fmt and args arguments follow the argument form of the fprintf() function.──────────Value returned: No useful value is returned by this function.──────────See also: message_level══execute_event_handler()Purpose: Executes the functions associated with an event.──────────Syntax: int execute_event_handler(int event)──────────Description: The execute_event_handler() function causes all of the functions associated with an event to be executed just as if the event had occurred. The event to be triggered is indicated by the event argument.──────────Value returned: Upon successful completion, the execute_event_handler() function returns a non-zero (TRUE) value. If the event argument is not a valid event, the function will fail. A value of zero (FALSE) is then returned.══execute_function()Purpose: Calls a function with a string containing its invocation.──────────Syntax: any execute_function(str function_call)──────────Description: The execute_function() function provides access to the PolyAWK interpreter for calling a function or making assignments to variables. This allows user programs to obtain a function call or variable assignment interactively from the user. The assignment or function and arguments then need not be known to the program. Only constant values may be assigned to variables using this method. There are a number of caveats and limitations when executing functions in this manner: Instead of placing parentheses around the arguments to the function whitespace is used. A space between the function name and the first argument is sufficient. All arguments to the function are determined by whitespace. This may not be circumvented by the use of quotes. As an example, consider the string below: message "hi there" If this string is supplied as an argument to execute_function() it is interpreted as follows: Call the function named message() with the two arguments. The first argument is "hi and the second argument is there". The arguments to a function executed in this manner are treated as constants -- not variables. If you include a variable as an argument it is treated as a string constant; no value is substituted.──────────Value returned: The value returned by the execute_function() function is the value returned to it by the function it executes. If the function_call string contain an invalid or mal-formed invocation, this function will fail and return a zero value.══execute_key_action() PELPurpose: Perform the function associated with a key.──────────Syntax: any execute_key_action(str keys)──────────Description: The execute_key_action() function executes the function associated with the keystroke described by keys as if it had been typed in from the keyboard. The keys argument gives the name of the keystroke in string form. A table containing the allowable key-name strings appears in the "Keymapping" chapter of the Functions by Category manual.──────────Value returned: This function's return value may be either a string or an integer, depending on the value returned by the function that it executes. If an invalid argument is supplied, the return value will be an empty string. If, however, a valid key-name string is supplied but no function is associated with that keystroke, the string value "undefined" is returned.══expand_window()Purpose: Enlarge a window to fill the screen.──────────Syntax: void expand_window([winid window])──────────Description: The expand_window() function enlarges the size of the window identified by the window argument to the "zoomed" state. If no window argument is specified, the current window is assumed. If the window is already zoomed, the state is not changed. The zoomed or full-screen state is one of four states a window may occupy: invisible, icon, normal or zoomed. When the window is zoomed, it takes up the entire screen. In the normal state, the window occupies the dimensions originally reflected by the window_height and window_width variables. When in the icon state, the window occupies a few columns of a single line, with a mnemonic displayed in the block. In the invisible state the window does not appear on the screen.──────────Value returned: No useful value is returned by the expand_window() function.──────────See also: collapse_window(), hide_window(),restore_window()══factory_keymap read-onlyPurpose: Predefined keyboard of standard SPE keys.──────────Type: keymapid factory_keymap──────────Description: The factory_keymap variable stores the id of a keymap containing the minimal Sage Professional Editor key assignments. This is the keymap that is put in effect when operating SPE without its function library. Do not confuse this keymap with the keymap defined in the native() function. The factory keymap contains the assignments in ascii_keymap and the following: KEY FUNCTION --------- ------------------ [Alt][E] edit_file() [Alt][U] undo() [Alt][W] write_buffer() [Alt][Q] quit() [Alt][X] quit() [Bksp] backspace() [Delete] delete_chars() [Alt][D] delete_line() [Enter] insert_newline() [Ctrl][Enter] open_line() [Alt][Minus] prev_buffer() [Alt][N] next_buffer() [Keypad +] copy_to_scrap() [Insert] insert_scrap() [Up] up() [Down] down() [Left] left() [Right] right() [PgUp] page_up() [PgDn] page_down() [Home] goto_bol() [End] goto_eol() [Ctrl][PgUp] goto_buffer_top() [Ctrl][PgDn] goto_buffer_bottom() Note that the key assignments do not rely upon any functions written in PEL. These assignments use the bare, unenhanced primitives. In that way, the keymap will work even if the function library cannot be found. This variable is primarily used when creating a new keymap. Used as an argument to the create_keymap() function, factory_keymap provides a method of initializing a new keymap to the standard definition. You may then modify its definition to suit. factory_keymap is a constant value and may not be modified by the user.══fclose()Purpose: Close the file associated with a handle.──────────Syntax: int fclose(fileid handle)──────────Description: fclose() closes the file indicated by the handle argument. The handle argument must be a file handle created with fopen().──────────Value returned: fclose() returns a non-zero (TRUE) value if successful. Upon failure, zero or FALSE is returned.──────────Compatibility: Return values differ from those of the like-named C function supported by major compilers.══fgetc()Purpose: Gets a character from a file.──────────Syntax: int fgetc(fileid file)──────────Description: The fgetc() function reads the next character from the file described by the file argument. This function allows reading the contents of a file into a string or other variable rather than into a buffer.──────────Value returned: The value returned by fgetc() is an integer corresponding to the value of the character read from the file. When successful, this value will not be a negative number. If this function encounters the end of file or an error occurs a -1 value is returned and the errno variable is set. If errno is zero, the end of file was encountered. When errno is other than zero an I/O error has occurred. This function will fail on files that have been opened in Create/Truncate (Write Only) mode.══filecopy()Purpose: File copying utility.──────────Syntax: int filecopy(str old, str new)──────────Description: The filecopy() function makes a duplicate of the file described by the old argument under the name or path location indicated in the new argument. The arguments taken by filecopy() may contain drive specifiers. If an argument contains no path element the current working directory is assumed. If the file named in the new argument already exists, it is overwritten. If the file described by the old argument cannot be opened or read the new file is not created or overwritten. The new file is marked with the current date and time. When the new or old argument is expressed as a constant, it must be enclosed in double quotes. Backslashes or forward- slashes may be used as path separators. Keep in mind that backslashes must be quoted with a second backslash in PolyAWK source code.──────────Value returned: Upon successful completion, filecopy() returns TRUE (non-zero). On failure, it returns FALSE (zero).══filemode()Purpose: Obtain or set the attributes of a file if it exists.──────────Syntax: int filemode([str name [, int mode]])──────────Description: The filemode() function may be used to determine if a file exists and, if it exists, may be used to check or set the DOS file attributes of that file. When the mode argument is present, filemode() modifies the permission settings associated with the file indicated by the name argument. The name argument is a filename and optional path element. The path element may include a drive specification. If name contains no path element, the default drive and directory are assumed. If the name argument is not supplied, this function obtains the file attributes of the file which was the subject of last call to findfirst() or findnext(). If neither of these functions has been called during the current editor session, it is treated as an error. The new attribute settings are determined by which bits of the mode argument are set. Interpretation of the mode bits is performed as follows: Bit 0 (mode = 1) Read-only Bit 1 (mode = 2) Hidden Bit 2 (mode = 4) System Bit 5 (mode = 32) Archive The above attributes may be combined by either supplying each of the desired values separated by the OR operator ( | ), or by adding the appropriate values together. Only the least significant eight bits of mode are considered. If the mode argument is absent, this function is treated as an inquiry only. File attributes are not modified. filemode() may be used in this manner to determine if a file is present on disk.──────────Value returned: Upon successful completion, filemode() returns the attributes of the file at the time the function was called. If the file represented by the name argument does not exist or some other error occurs a value of -1 will be returned. Interpretation of the value returned is the same as the mode argument described above. All bits not in the least significant byte should be ignored since these are used to distinguish between a file attribute mask of 0 and a failure.──────────Compatibility: This function serves a similar purpose to the chmod() or access() functions supported by major C compilers. However, it differs from the PolyAWK filemode() function in arguments and return value.══filemove()Purpose: File moving utility──────────Syntax: int filemove(str old, str new)──────────Description: filemove() copies the file described by the old argument to the name or path location indicated in the new argument. The original file is then deleted. The arguments taken by filemove() may contain drive specifiers. If an argument contains no path element the current working directory is assumed. The filename must be explicitly named in both the old and new arguments. If the file named in the new argument already exists, it is not overwritten. If the file described by the old argument cannot be opened, read or deleted the new file is not created or overwritten. The new file is marked with the current time and date. When the new or old argument is expressed as a constant, it must be enclosed in double quotes. Backslashes, forward- slashes or doubled backslashes may be used as path separators.──────────Value returned: Upon successful completion, filemove() returns a non-zero (TRUE) value. On failure, it returns zero or FALSE. Consult errno to determine the source of the error.══filesize()Purpose: Determine the size of a file.──────────Syntax: int filesize([str name])──────────Description: filesize() is used to determine the amount of storage occupied by the file indicated in the name argument. The name argument is a filename and optional path element. The path element may include a drive specification. If name contains no path element, the default drive and directory are assumed. If the name argument is not supplied, this function obtains the file size of the file which was the subject of last call to findfirst() or findnext(). If neither of these functions has been called during the current editor session, it is treated as an error.──────────Value returned: When successfully completed, the value returned by filesize() is the number of bytes occupied by the file. If the file does not exist or another error occurs, the value returned is -1.──────────Compatibility: This function is common to SPE and PolyAWK.══filetime()Purpose: Obtain or set the timestamp associated with a file.──────────Syntax: int filetime([str file [, int timestamp]])──────────Description: When the timestamp argument is supplied, filetime() sets the time and date of the file described in the file argument to the value of timestamp. The file argument is a string containing a filename. This filename may not contain wildcard characters. Optionally, file may also contain a path element including drive specifier. If file does not contain a path element, the default drive and directory are assumed. If the file argument is not supplied, this function obtains the timestamp of the file which was the subject of last call to findfirst() or findnext(). If neither of these functions has been called during the current editor session, it is treated as an error. The value supplied in the timestamp argument represents the time and date of the file in seconds since 00:00:00 January 1, 1970. If timestamp is 0, the file will be set to the current system date and time. When timestamp is omitted, the function is treated as an inquiry only. The timestamp on the file is not modified.──────────Value returned: Upon successful completion, filetime() returns the date and time of the file in effect when the function was called. If an error occurs, a value of zero is returned.──────────Compatibility: This function is common to SPE and PolyAWK.══filter() PELPurpose: Processes a portion of a buffer through a command.──────────Syntax: int filter(str command)──────────Description: The filter() function runs a portion of the current buffer through the command specified by the command argument. The filter specified by the command argument must be a program that takes its input from the standard input device and sends the results to the standard output device. If a marked block of text has been defined, the text in that block is processed through the indicated command. If no marked block exists, the entire buffer is processed. After the text has been processed, the resulting text is read into the buffer as a replacement for the marked block or buffer contents.──────────Value returned: The value returned by the filter() function is the exit code returned by the filter subprocess. This usually means a return value of 0 signifies success.══findfirst()Purpose: Begin a directory search.──────────Syntax: str findfirst(str pattern [, int attr])──────────Description: findfirst() searches the directory for the first file, if any, matching the pattern argument. The match may be further qualified by the file attribute described by the attr argument. The pattern argument is a filename which may contain standard DOS wildcard characters, * and ?, as described in the "Filename Matching" section of "Settling In" chapter of the User's Manual. It may also have a path element including drive specifier. If pattern contains no path element, the default drive and directory are assumed. * Although a path may be specified as part of the pattern argument, this function returns only filenames, not paths. The search may be further limited or expanded by supplying the attr argument. This argument describes the file attributes that the directory entry must match. If this argument is not supplied, normal, read-only and files with the archive bit set will match. The values allowed for attr are those that may be represented by a single byte. A number of descriptive identifiers have been defined in the standard library files for your use. These identifiers and their numeric values are given below: _READ_ONLY 0x01 _HIDDEN 0x02 _SYSTEM 0x04 _VOL_ID 0x08 _SUBDIR 0x10 _ARCHIVE 0x20 _NORMAL 0x40 Any combination of the above values may be specified as the attr argument. For instance, either of the examples below matches with files that have the Archive or Read-Only bits set: findfirst("*.*",_ARCHIVE + _READ_ONLY) findfirst("*.*",0x21) If you omit any of the library function files from a customized configuration of the editor, the identifiers list above may become unavailable. If so, you will have to define similar variables yourself or use the numeric equivalent.──────────Value returned: Returns a string containing the filename found. The string returned does not contain any path element. If no matching file is found or some other error occurs, an empty string is returned. If an empty string is returned and errno is zero, no matching file was found. Otherwise, some other error occurred.──────────Compatibility: This function is somewhat similar to the findfirst() or _dos_findfirst() function supported by some C compilers. The value corresponding to the _NORMAL label has been changed to allow searches that do not implicitly include these files.══findnext()Purpose: Continue a directory search.──────────Syntax: str findnext()──────────Description: Subsequent to a call to findfirst(), the findnext() function is used to find the next file matching the pattern argument used in findfirst().──────────Value returned: Returns a string containing the filename found. The string returned does not contain any path element. If no further matching file is found or some other error occurs, an empty string is returned. If an empty string is returned and errno is zero, no matching file was found. Otherwise, some other error occurred.──────────Compatibility: This function is somewhat similar to the findnext() or _dos_findnext() function supported by some C compilers.══flush_keyboard()Purpose: Discards keyboard input currently waiting to be read.──────────Syntax: int flush_keyboard()──────────Description: The flush_keyboard() function empties the keyboard buffer of all pending input. This is often desirable before prompted input, to ensure that perceived input is in response to the prompt.──────────Value returned: The value returned by the flush_keyboard() function is non-zero (TRUE) if there were characters pending in the keyboard buffer. If there were no characters pending, the function returns a zero (FALSE) value.══fopen()Purpose: Open a file for processing.──────────Syntax: fileid fopen(str file, int mode)──────────Description: The fopen() function opens the file indicated by the file argument in the manner indicated by the mode argument. The file argument may contain a path element, including drive specifier, as well as the required filename. One of the permissions indicated below may be specified by mode: 0 Read only permission. 1 Create/Truncate (Write Only). 2 Read and Write permission. (When used with fseek() allows appending.)──────────Value returned: fopen() returns the file handle of the file it has opened, upon successful completion. Zero may be a valid file handle. On error, this function returns a value of -1. Further information may be available by examining the errno variable.──────────Compatibility: Similar to the fopen() function supported by major C compilers. Return values and modes available are somewhat different.══fprintf()Purpose: Writes a formatted string to a device.──────────Syntax: void fprintf(fileid handle, str fmt [, any args,...])──────────Description: The fprintf() function formats a string, as indicated by the fmt and args arguments and writes it on the device indicated by the handle argument. The handle argument must be a file id returned by the fopen() function. The fmt string argument may contain both text to be printed literally and format control characters. Format control characters specify how the args arguments are to be formatted and included in the output string. Format control characters are preceded by the percent ( % ) symbol. The recognized format control characters and their meanings are given below: c An ASCII character. d ld An integer (decimal notation). o An unsigned integer (octal notation). s A string x An unsigned integer (hex. notation). X An unsigned integer (hex. upper case letters). Since the % indicates that a format control character follows, %% must be used to represent a single percent symbol in the fmt string. There may be an intervening number, dash or a dot (followed by a number) between the % symbol and its format control character. The number indicates the reserved width of the field. The field is padded until it is this width. If the number contains a leading zero, the field is padded with zeros. Otherwise the field is padded with spaces. The intervening dash ( - ) indicates that the expression is to be left justified within the field. In the absence of the dash, the field will be right justified. The dot ( . ) is used to specify the maximum string width. The number following the dot represents the maximum length of the string expression to be included. If the expression is longer than the specified maximum, the remainder is truncated.──────────Value returned: No useful value is returned by this function.══fputc()Purpose: Puts a character in a file.──────────Syntax: void fputc(int ch, fileid file)──────────Description: The fputc() function writes a character to the file described by the file argument. The integer argument, ch, contains the value of the character. This function uses fprintf() to achieve this result.──────────Value returned: No useful value is returned by this function.══frame_window()Purpose: Define or alter the dimensions of a window.──────────Syntax: void frame_window([int x, y, wide, high [, winid win]])──────────Description: The frame_window() function allows you to define the size and location of a window. The window to be framed is designated by the win argument. The win argument must be a window previously created by a call to create_window() or edit_file(). If this argument is omitted, the dimensions of the current window are redefined. The location and size of the window are defined by the x, y, wide and high arguments. The x and y arguments indicate the column and line offset at which SPE will locate the upper left corner of the window. The wide and high arguments indicate the number of columns and lines the window will occupy. If these arguments are not supplied, the user is allowed to adjust the window manually using the arrow keys. If the x or y argument specifies a position off screen, the value is set to the limit of that screen dimension. When the value of the wide or high argument would cause the window to extend off screen, the values of the x and y arguments are reduced to allow the window to fit. If this is not possible, the window is truncated to fit the screen.──────────Value returned: No useful value is returned by the frame_window() function.══fread()Purpose: Read a portion of a file into the active buffer.──────────Syntax: int fread(fileid handle, markid mark, int len)──────────Description: The fread() function reads the number of characters indicated by the len argument from the file specified by handle. This data is then inserted into the active buffer at the location indicated by the mark argument. The file handle supplied in the argument handle must have been previously created by the fopen() function. The mark argument is the number of a previously defined editor bookmark in the active buffer. Bookmark 0 is always defined as the current cursor position in that buffer. The len number of bytes to read is limited to 8100 bytes per read.──────────Value returned: Upon success, fread() returns the number of bytes read. If the handle or mark argument is invalid or if the file has been opened in a mode that does not permit reading this function will return -1. When the value returned is less than len, the end of the file has been reached or a media failure has occurred. If a media failure is suspected, errno may then be consulted for additional information.──────────Compatibility: This function differs from the ANSI C fread() function in its return values and the destination of the data read.══FS AWKPurpose: Identifies the default AWK input field separator.──────────Type: str FS──────────Description: The FS variable is used by the AWK split() function. It defines what character or characters the split() function uses as a default field separator. The initial value for this variable is " ", a single space.──────────See also: split()══fseek()Purpose: Move the file pointer.──────────Syntax: int fseek(fileid handle, int offset, int flag)──────────Description: The fseek() function sets the pointer associated with a file to a new location. The file pointer to be moved is the pointer associated with the handle argument. It is moved to the position indicated by the flag argument plus offset bytes. You may determine the current position using the ftell() function The permissible values for flag and their meaning are as follows: 0 The beginning of the file. 1 The file pointer's current position. 2 The end of the file.──────────Value returned: On successful completion, fseek() returns the file pointer offset. When seeking to the beginning of a file the return value will be zero. If an error occurs, a value of -1 is returned.──────────Compatibility: This function is similar to the like-named function supported by major C compilers except as to return values.──────────See also: ftell()══ftell()Purpose: Reports current position of file pointer.──────────Syntax: int ftell(fileid handle)──────────Description: ftell() obtains the current position of the file pointer associated with the file indicated by the handle argument.──────────Value returned: ftell() returns the file pointer position in number of bytes from the beginning of the file, when successful. When the file pointer is at the beginning of the file this value will be zero. On error, ftell() returns -1. To differentiate an error from the beginning of the file, consult the errno variable. If the file pointer is pointing to the beginning of the file, ftell() will return zero and errno will also be zero. If errno is a non-zero value, an error has occurred.──────────Compatibility: This function is similar to the ftell() function supported by major C compilers except as to the value returned on error.══function_binding()Purpose: Reports what keys a function is bound to.──────────Syntax: str function_binding(funcid func [, keymapid keymap])──────────Description: The function_binding() function tells the key or keystroke combination to which the function described by the func argument is bound. If func is bound to more than one keystroke, all of the associated keystrokes are reported. The keymap argument may be used to specify the keymap to which the query is to apply. If keymap is not supplied, the query applies to the current keymap.──────────Value returned: The value returned by function_binding() is a string containing the keystrokes associated with the function. The keystrokes take the form of the key id (scan code and ASCII value) in decimal notation preceded by a pound sign ( # ): "#123#432#45565" The example above shows a keystroke sequence of three key ids. The function is assigned to this combination of keys. If the function has been assigned to more than one keystroke combination, each keystroke combination is separated from the one preceding by a space: "#123#432#45565 #4543 #23423" This second example shows three different key sequences that may be used to execute the function. The first key sequence involves three separate key ids.══function_caller()Purpose: Reports the name of the calling function.──────────Syntax: str function_caller()──────────Description: The function_caller() function tells which function, by name, called the function currently executing. It is primarily used to select between courses of action, often depending on whether the function was invoked from the keyboard or not.──────────Value returned: The value returned by function_caller() is a string containing the name of the invoking function. If the function was called from the keyboard it returns the string "Keyboard". If called by an internal primitive rather than a PEL function, the string returned is "Primitive".══function_id()Purpose: Reports the id associated with a function name.──────────Syntax: funcid function_id(str function)──────────Description: The function_id() function provides a method of discovering the numeric id associated with a function. The function is specified by named in the function argument. In addition, this function provides access to an advanced SPE programming feature called "anonymous functions". These are transient functions that provide a programming short-cut. These functions do not appear in the source code as functions. They are essentially other existing functions called with a defined set of constant arguments. You might write a function to create a certain size window in the following conventional manner: function my_window() { create_window(5,5,20,70) } You may alternately use function_id() to obtain the function id of such a function without ever writing it: fid = function_id("create_window 5 5 20 70") This is the method used internally for several features, including assigning to keys functions that require arguments. This use of function_id() sometimes requires supplying additional arguments to function_id(). This is freely allowed. The above example could also be written: fid = function_id("create_window",5,5,20,70)──────────Value returned: The value returned by the function_id() function is the corresponding function id if the function has been defined. Otherwise, the function returns a zero value.══function_name()Purpose: Reports the name associated with a function id.──────────Syntax: str function_name(funcid id)──────────Description: The function_name() function provides a method of discovering the name of a function associated with a numeric function id. The function id is specified in the id argument.──────────Value returned: The value returned by the function_name() function is a string containing the name of the function if it has been defined. Otherwise, the function returns an empty string.══fwrite()Purpose: Write a block of text to a file.──────────Syntax: int fwrite(fileid handle, markid mark, int len)──────────Description: The fwrite() function writes the number of characters indicated by the len argument to the file specified by handle from the active buffer. The beginning of the data to be written is indicated by the mark argument. The write operation begins at the position indicated by the file pointer associated with handle. The file handle supplied in the argument handle must have been previously created by the fopen() function. The mark argument is the number of a previously defined editor bookmark in the active buffer. Bookmark 0 is always defined as the current cursor position in that buffer. If you wish to truncate a file at its current position, supply a value of 0 as the len argument to this function. When writing a highlighted block of text, write_marked_block() is the appropriate function to use. When writing all text between two bookmarks, the distance_between_marks() function may be used to provide the len value.──────────Value returned: Upon success, fwrite() returns the number of bytes actually written. If the handle or mark argument is invalid or if the file has been opened in a mode that does not permit writing this function will return - 1. Anytime the value returned is less than len, an error has occurred. errno may then be consulted to determine the source of the error.──────────Compatibility: This function differs from the fwrite() function supported by major C compilers in its return values and the origin of the data written.──────────See also: write_marked_block()══getchar()Purpose: Read an ASCII character from the keyboard.──────────Syntax: int getchar()──────────Description: The getchar() function waits for a character to be received from the keyboard and then returns its ASCII value or scan code.──────────Value returned: If the key pressed has an ASCII value, that value will be returned. If the value returned is zero, a non-ASCII key has been pressed. In this case, calling getchar() again will obtain the scan code.──────────Example: function read_key() { local inchar inchar = getchar() if (inchar == 0 && keyboard_input_pending) inchar = shiftl(getchar(),8) return inchar } This example returns the input; either ASCII value or scan code.──────────See also: getkey(), keyboard_input_pending══getcwd()Purpose: Obtain the current working directory of a drive.──────────Syntax: str getcwd([str drive or int drive])──────────Description: If the drive argument is present, getcwd() reports the current working directory, including full path name, for the drive specified in that argument. The drive argument may be a string whose first character is the letter of the drive of interest. The rest of the string is ignored. Alternately, drive may be a drive number, where drive A: is 0, drive B: is 1 and so on. If drive is not supplied, getcwd() reports the current working directory for the default drive.──────────Value returned: On success, getcwd() returns a new string. This string contains the full path name of the current working directory, including drive specifier. The string always ends with a backslash and may be up to 129 characters long. On failure, an empty string is returned.──────────Compatibility: getcwd() differs from the getcwd() function supported by major C compilers. The getcwd() C function only returns the current working directory of the default drive, whereas getcwd() may be used to obtain the current working directory of any valid drive. The arguments required by these two functions are also different.══getkey()Purpose: Get a character and scan code from the keyboard.──────────Syntax: int getkey()──────────Description: The getkey() waits for a key to be pressed. It then returns the key's ASCII value, if any, and its scan code.──────────Value returned: The getkey() function returns the ASCII value of the key pressed in the least significant (low order) byte. If there is no ASCII equivalent, this byte will be 0. The second byte will contain the scan code.──────────See also: getchar(), keyboard_input_pending══goto_bol()Purpose: Moves the cursor to the beginning of the current line.──────────Syntax: int goto_bol()──────────Description: the goto_bol() function moves the cursor to the beginning of the line it currently occupies.──────────Value returned: The value returned by the goto_bol() function is non-zero (TRUE) if the cursor was moved. If the cursor was already at the beginning of the line a zero (FALSE) value is returned.══goto_bookmark()Purpose: Moves to non-local bookmarks.──────────Syntax: void goto_bookmark([int n])──────────Description: The goto_bookmark() function is an enhanced version of the goto_mark() function. The function goto_mark() requires that the mark be defined in the current buffer. If the function place_bookmark() is used to define the bookmark, goto_bookmark() can move to it regardless of the buffer in which it was defined. In addition, this function prompts for the mark number if not supplied. This function is limited to the ten bookmarks 1 through 10.──────────Value returned: No useful value is returned by this function.══goto_bookmark_key() PELPurpose: Move to single bookmark or prompt if more than one.──────────Syntax: void goto_bookmark_key()──────────Description: The goto_bookmark_key() function is an enhanced version of goto_bookmark(). If only one bookmark is defined, the cursor is moved without prompting. If more than one bookmark is defined, the available bookmark values are displayed on the prompt line.──────────Value returned: No useful value is returned by this function.══goto_buffer_bottom()Purpose: Moves the cursor to the end of the current buffer.──────────Syntax: int goto_buffer_bottom()──────────Description: The goto_buffer_bottom() function moves the cursor to the position immediately following the last character in the current buffer.──────────Value returned: The goto_buffer_bottom() function returns a non-zero (TRUE) value to indicate that the cursor has been moved. If the cursor does not move as a result of this function, a zero or FALSE value is returned.══goto_buffer_offset()Purpose: Move the cursor to a specified buffer position.──────────Syntax: void goto_buffer_offset(int num)──────────Description: The goto_buffer_offset() function places the cursor at the position in the buffer dictated by the num argument. The num argument represents the number of characters which are to precede the cursor at its new position. If num specifies an offset greater than the contents of the buffer, the cursor position is moved to the end of the buffer. Negative values for num move the cursor to the beginning of the buffer.──────────Value returned: No useful value is returned by this function.──────────See also: buffer_offset, buffer_size,buffer_last_line══goto_buffer_top()Purpose: Moves the cursor to the beginning of the buffer.──────────Syntax: int goto_buffer_top()──────────Description: The goto_buffer_top() function moves the cursor to the first character in the current buffer regardless of its previous location.──────────Value returned: The goto_buffer_top() function returns a non-zero (TRUE) value if the cursor was moved. A zero or FALSE value is returned if the cursor was already at the beginning of the buffer.══goto_eol()Purpose: Moves the cursor to the end of the current line.──────────Syntax: int goto_eol()──────────Description: The function goto_eol() moves the cursor to the end of the current line.──────────Value returned: The goto_eol() function returns a non-zero (TRUE) value to indicate that the cursor has been moved. If the cursor does not move as a result of this function, a zero or FALSE value is returned.══goto_line() PELPurpose: Go to the first column of a line specified by number.──────────Syntax: void goto_line(int num)──────────Description: The goto_line() function moves the cursor to the first column of the line indicated by the num argument. The num argument must specify an integer with a positive value corresponding to an existing line of text. A number higher than any existing line moves the cursor to the last line in the buffer. If zero or a negative value is specified for num, the cursor is moved to the beginning of the buffer.──────────Value returned: No useful value is returned by this function.══goto_line_key() PELPurpose: Prompts for and moves to a specified line.──────────Syntax: void goto_line_key()──────────Description: The goto_line_key() function is a close relative of the goto_line() function, suitable for assigning to a key. It prompts for the buffer line number where you wish to place the cursor and then goes there.──────────Value returned: No useful value is returned by this function.══goto_line_or_mark() PELPurpose: Prompts for line or mark number.──────────Syntax: void goto_line_or_mark()──────────Description: The goto_line_or_mark() function prompts for a line number at which to place the cursor, but allows entering a mark number instead, if preceded by "Mark #". This makes it unnecessary to have separate key assignments for each of these requirements.──────────Value returned: No useful value is returned by this function.══goto_mark()Purpose: Move cursor to position indicated by a bookmark.──────────Syntax: int goto_mark(int num)──────────Description: The goto_mark() function moves the cursor to the column position at the bookmark indicated by the num argument. The num argument is a numeric id given to a bookmark when it was created. If num is not a valid bookmark, the cursor is not moved. This function may be used to move to the next bookmark in the buffer by using the next_mark() function as the argument.──────────Value returned: The value returned by goto_mark() is non- zero (TRUE) if the named mark has been previously defined. If the mark has not been defined the value returned is zero (FALSE).══goto_next_error()Purpose: Move cursor to position of next compile error.──────────Syntax: void goto_next_error()──────────Description: The goto_next_error() function allows the user to move sequentially in the source code from one compile error to the next. On the first call to goto_next_error(), after a compile, the function determines from the name of the current buffer the name of the file in which error messages have been captured. It then locates and displays the position in the source code of the first error listed in that file. The associated error message is displayed in the dialog window. On subsequent calls to goto_next_error(), the next message in the error listing file is read, the cursor is positioned at the proper place in the appropriate file, and again the error message is displayed in the dialog window. If there are no known rules for parsing the error messages associated with the current buffer, this function cannot succeed. A message to that effect is then displayed. Several sets of error parsing rules which may be associated with filename extensions. This may be done using the add_compiler() function.──────────Value returned: No useful value is returned by this function.══goto_next_tab()Purpose: Move the cursor to the next tab stop position.──────────Syntax: int goto_next_tab()──────────Description: The goto_next_tab() function moves the cursor to the tab stop immediately following its current position. If the buffer_flags variable allows movements into VIRTUAL SPACE, the tab stop may be beyond the end of the current line of text. If movements into VIRTUAL SPACE are not allowed, the cursor will move to the first tab stop on the following line, when the current line does not extend to the next tab stop. If the cursor is already past the last tab stop in the buffer, a short beep is emitted from the speaker and the cursor is not moved.──────────Value returned: The function goto_next_tab() returns the number of columns the cursor moved in order to reach the next tab stop. If the cursor does not move, the value returned is zero.──────────See also: goto_prev_tab()══goto_old_line()Purpose: Go to line when only its original line number is known.──────────Syntax: int goto_old_line(int num)──────────Description: The function goto_old_line() moves the cursor to the new location of the line denoted by the num argument. As with goto_line(), the cursor moves to the first column of that line. The num argument is the number of the line at which the desired text was found originally, or following the most recent save. When a buffer is saved, information about the previous locations of lines is lost. If the line referred to by num has been deleted, the cursor moves to the location from which the line was deleted.──────────Value returned: The goto_old_line() function returns a non- zero (TRUE) value if the cursor is moved as a result of calling this function. Otherwise the function returns zero (FALSE).══goto_pos()Purpose: Move to a specific line and column within the buffer.──────────Syntax: int goto_pos(int line, int column)──────────Description: The goto_pos() function moves the cursor to the buffer line and column number indicated in the arguments. If the value of the line argument exceeds the number of lines in the buffer, the cursor is placed on the last line. When movements into VIRTUAL SPACE are not allowed, two special conditions apply: If the value of the column argument exceeds the number of columns in the line, the cursor is placed at the end of the line. In addition, if the column location specified would place the cursor in the middle of a tab, the cursor is instead positioned at the beginning of a tab. When movements into VIRTUAL SPACE are permitted, the cursor is placed at the indicated column, regardless. A zero value may be used for either argument and has special meaning. When a zero value is supplied as an argument, it specifies that the current line or column number is to be preserved; depending on which argument is so specified. If the line number specified is out of range, the editor will go to the last line of the file. If already on the last line, it will go to the end of the line. The following are two examples from common usage: goto_pos(0,1) This example moves the cursor to the first column of the line it presently occupies. goto_pos(1,0) This example moves the cursor to the first line of the buffer, but the column it occupies is unchanged. If a negative value is supplied as an argument to this function, it is treated as a value of 1.──────────Value returned: This function returns TRUE (a non-zero value) if the cursor moved. It returns FALSE (zero) if the cursor did not move.══goto_prev_tab()Purpose: Move the cursor to the previous tab stop position.──────────Syntax: int goto_prev_tab()──────────Description: The goto_prev_tab() function moves the cursor to the tab stop immediately preceding its current position. The cursor will move to the last tab stop within the preceding line, when the current line does not contain a previous tab stop. If the cursor already precedes the first tab stop in the buffer, a short beep is emitted from the speaker and the cursor is not moved.──────────Value returned: The function goto_prev_tab() returns the number of columns the cursor moved in order to reach the previous tab stop. If the cursor does not move, the value returned is zero (FALSE).──────────See also: goto_next_tab()══goto_window_bottom() PELPurpose: Moves cursor to the text in the last line of the window.──────────Syntax: void goto_window_bottom()──────────Description: The goto_window_bottom() function moves the cursor to the last visible line in the current window. The column position is maintained when possible. When movements into VIRTUAL SPACE are not permitted the cursor may be required to move left to the nearest real character.──────────Value returned: No useful value is returned by goto_window_bottom().══goto_window_left() PELPurpose: Moves cursor to text at the left edge of the window.──────────Syntax: void goto_window_left()──────────Description: The goto_window_left() function moves the cursor to the first position at the left edge or border of the window. The cursor does not change lines and text is not scrolled. When movements into VIRTUAL SPACE are not permitted, the cursor may be required to move away from the edge of the window to the nearest real character.──────────Value returned: No useful value is returned by goto_window_left().══goto_window_middle() PELPurpose: Moves cursor to text in the middle line of the window.──────────Syntax: void goto_window_middle()──────────Description: The goto_window_middle() function moves the cursor to the middle most line visible in the current window. The column position is maintained when possible. When movements into VIRTUAL SPACE are not permitted the cursor may be required to move left to the nearest real character.──────────Value returned: No useful value is returned by goto_window_middle().══goto_window_right() PELPurpose: Moves cursor to text at the left edge of the window.──────────Syntax: void goto_window_right()──────────Description: The goto_window_right() function moves the cursor to the last position at the right edge or border of the window. The cursor does not change lines and text is not scrolled. When movements into VIRTUAL SPACE are not permitted the cursor may be required to move away from the edge of the window to the nearest real character.──────────Value returned: No useful value is returned by goto_window_right().══goto_window_top() PELPurpose: Moves cursor to the text in the first line of the window.──────────Syntax: void goto_window_top()──────────Description: The goto_window_top() function moves the cursor to the first visible line in the current window. The column position is maintained when possible. When movements into VIRTUAL SPACE are not permitted the cursor may be required to move left to the nearest real character.──────────Value returned: No useful value is returned by goto_window_top().══grep() PELPurpose: Locate lines containing a string.──────────Syntax: void grep(str strpat)──────────Description: The grep() function searches through the current buffer for lines containing the string specified by the strpat argument. Lines containing matches are displayed in the form of a menu, allowing the user to select a line of interest with the arrow keys or mouse. The user may then move to that line by pressing [Enter].──────────Value returned: No useful value is returned by this function.══gsub() AWKPurpose: Replace occurrences of a substring with another.──────────Syntax: int gsub(str regex, str repl, str s)──────────Description: The gsub() function substitutes the specified replacement string, repl, for substrings matching the regex argument within the string S. The regex argument is a regular expression. The special characters that may be used in the regex argument are those described in the "Regular Expressions" chapter of the User's Manual. These characters may be used without regard to the state of the search_flags variable. The scope of the match is always maximal.──────────Value returned: The value returned by the gsub() variable is the number of replacements made. If any of the arguments is an empty string, the function will return an empty string.──────────See also: sub()══help()Purpose: Display the help menu or help text.──────────Syntax: void help([str keyword])──────────Description: The help() function is used either to invoke the help menu or obtain descriptive text about a specified topic. If no argument is supplied, the help master menu is displayed. The key assignment [Alt][H] normally displays this help menu. This menu can provide information about various editor tasks and even execute many of those tasks. You may move through this menu and its sub-menus by pressing the arrow keys or by pressing the letter shown in uppercase in the desired topic name. If the keyword argument is given and this string matches a keyword known to the help function, the associated help text is displayed in a pop-up window. You may scroll through the help text as you would any SPE window. When [Esc] is pressed the pop-up help window is sent away. Displays a help message for the given name argument.──────────Value returned: No useful value is returned by this function.══hide_window()Purpose: Remove a window from the screen.──────────Syntax: void hide_window([winid window])──────────Description: The hide_window() function changes the state of a window to "invisible". If no window argument is specified, the current window is assumed. If the window is already invisible the state is not changed. The window is still defined but does not appear on the screen. The window may be made visible again through the use of the restore_window() function. The invisible state is one of four states a window may occupy: invisible, icon, normal or zoomed. When the window is zoomed, it takes up the entire screen. In the normal state, the window occupies the dimensions originally reflected by the window_height and window_width variables. When in the icon state, the window occupies a few columns of a single line, with a mnemonic displayed in the block. In the invisible state the window does not appear on the screen. However, the window's position and shape variables will reflect the same values as when the window is in its normal state.──────────Value returned: No useful value is returned by the hide_window() function.──────────See also: expand_window(), collapse_window(),restore_window()══highlight_screen()Purpose: Change the attribute of an area of text on the screen.──────────Syntax: void highlight_screen(int x, y, wide, high, attr)──────────Description: The highlight_screen() function changes the text attribute of a specified area of the screen. The area whose attribute is to be changed or highlighted need not appear within any window. The x and y arguments to this function are the screen column and line offsets. These two arguments indicate where highlighting begins. The wide and high arguments define the number of columns and lines that are to be highlighted. These arguments will normally be at least 1. The attr argument is the attribute to be given to the text in the described area. Permissible attribute values and their meanings are shown in a table in the "Windowing" section of the Functions by Category manual.──────────Value returned: This function returns no useful value.──────────See also: highlight_window(), read_window(),write_window()══highlight_window()Purpose: Change the attribute of an area of text in a window.──────────Syntax: void highlight_window(int x, y, wide, high, attr [, winid win])──────────Description: The highlight_window() function changes the text attribute of a specified area of a window. The text whose attribute will change or be highlighted is assumed to be in the current window unless the optional win argument is supplied. The x and y arguments to this function are column and line offsets from the beginning of text in the window. These two arguments indicate where highlighting begins. The variables window_text_x0 and window_text_y0 describe the location where text begins in the window. The wide and high arguments define the number of columns and lines that are to be highlighted. These arguments will normally be at least 1. The attr argument is the attribute to be given to the text in the described area. Permissible attribute values and their meanings are shown in a table in the "Windowing" section of the Functions by Category manual.──────────Value returned: This function returns no useful value.──────────See also: highlight_screen(), read_window(),write_window()══idle_thresholdPurpose: Sets length of inactivity which triggers an event.──────────Type: int idle_threshold──────────Description: The value stored in the idle_threshold variable is the number of seconds that may elapse without keyboard activity before the idle event is triggered. This threshold is reached when the idle_time variable is the same or greater than idle_threshold. The default value for this variable is large enough that the idle event is effectively turned off.══idle_timePurpose: Tells the number of seconds since the last keystroke.──────────Type: int idle_time──────────Description: The variable idle_time stores the elapsed time in seconds since the last input was received from the keyboard. This variable may be modified in order to hasten or delay reaching the idle event threshold, defined by the idle_threshold variable.══indent_columns()Purpose: Indent lines by adding whitespace to the left of text.──────────Syntax: int indent_columns([int num])──────────Description: The indent_columns() function shifts a line or lines of text to the right by inserting whitespace preceding the left end of text. If no marked block of text has been defined, whitespace is added to the current line only. If a block has been defined, each line of text in the block is indented. The cursor position is changed as a result of this function if it is located within the indented text. If a column marked block of text has been defined, whitespace is added to each line immediately to the left of the column at which the block begins. When other types of blocks exist, whitespace is added to the beginning of each line in the block. The number of spaces added to each line is determined by the value of the num argument. If the num argument is omitted, a value of 1 is assumed for that argument.──────────Value returned: This function returns a non-zero value (TRUE) when successfully completed. A zero value (FALSE) is returned if an invalid value is supplied for the num argument.══indent_tabs()Purpose: Indent lines by adding tabs to the left of text.──────────Syntax: int indent_tabs([int num])──────────Description: The indent_tabs() function indents a line or lines of text by inserting a specified number of tabs preceding the left end of text. If no marked block of text has been defined, tabs are added to the current line only. If a block has been defined, each line of text in the block is indented by adding tabs. The cursor position is changed as a result of this function if it is located within the indented text. If a column marked block of text has been defined, whitespace is added to each line immediately to the left of the column at which the block begins. When other types of blocks exist, whitespace is added to the beginning of each line in the block. The number of tabs added to each line is determined by the value of the num argument. If the num argument is omitted, a value of 1 is assumed for that argument.──────────Value returned: This function returns a non-zero value (TRUE) when successfully completed. A zero value (FALSE) is returned if an invalid value is supplied for the num argument.══index()Purpose: Reports position of the first occurrence of a sub-string.──────────Syntax: int index(str s, str sub)──────────Description: The index() function searches the s string argument for the first occurrence of the sub-string in the sub argument. The function then reports the position in the s string at which the sub-string occurred. This function differs from cindex() in that it considers sub as a sub-string rather than a series of characters.──────────Value returned: The value returned by the index() function is the ordinal position at which the sub- string begins. If no matches were found, or if one of the arguments was not a valid string, the function returns a zero value.══insert_key()Purpose: Insert the character associated with a key into buffer.──────────Syntax: int insert_key([int char])──────────Description: The insert_key() function inserts the character, whose ASCII value is specified by the char argument, into the buffer at the cursor position. If the char argument is not supplied, the ASCII value of the most recently pressed key is inserted. The current position in the buffer is incremented to account for this addition. The char argument may also be a key id obtained from a function such as getkey(). Only the ASCII portion of the key id, which also contains the scan code, is used. The scan code is ignored. If there is no ASCII value to use an error occurs. Most ordinary keyboard keys will call this function to insert the character corresponding to the key pressed. If word- wrap features are enabled, text that exceeds the margin defined by wp_right_margin will be word-wrapped to the following line.──────────Value returned: This function returns a non-zero or TRUE value unless the buffer_flags variable is set to disallow edits to the buffer. In this case a zero or FALSE value is returned.──────────See also: delete_chars(), buffer_flags,insert_string()══insert_newline()Purpose: Insert end-of-line marker and move cursor to next line.──────────Syntax: int insert_newline()──────────Description: The insert_newline() function inserts an end-of-line sequence (buffer_eol_string) into the buffer at the current cursor position, and returns the cursor to the beginning of the new line. This function may also perform additional duties if the buffer_flags variable indicate they are required. When the WP_ENABLED bit of the buffer_flags is set, the insert_newline() function honors the left-hand margin defined by the wp_left_margin variable. After the end-of- line marker has been inserted, whitespace is added to the new line up to the column position contained in wp_left_margin.──────────Value returned: This function will return a non-zero value except when the buffer_flags variable indicates that the buffer may not be modified. Under these circumstances, the function returns zero.──────────See also: buffer_eol_string, buffer_flags,toggle_auto_indent══insert_scrap()Purpose: Insert contents of scrap buffer at cursor position.──────────Syntax: int insert_scrap()──────────Description: The insert_scrap() function inserts the contents of the scrap buffer into the current buffer. When no block of text has been selected the text is inserted at the beginning of the line containing the cursor. Otherwise, the text is inserted at the current cursor position. After the insertion, the cursor is positioned at the end of the inserted text. The contents of the scrap buffer are not modified or lost. For those who are familiar with the concepts of "cut and paste", the delete_to_scrap() function is analogous to "cut". This function serves as a "paste" feature.──────────Value returned: When successful, the insert_scrap() function returns a non-zero value (TRUE). If for any reason the function can not be completed, a zero (FALSE) value will be returned.══insert_string()Purpose: Insert a string into current buffer at cursor position.──────────Syntax: str insert_string(str string)──────────Description: The insert_string() function incorporates a string specified by the string argument into the current buffer at the current cursor position. After the insertion, the cursor is positioned at the end of the inserted string. The included string may contain new lines and tabs, as desired. New lines found in the string are converted to conform to the buffer_eol_string currently in effect. The primary use of this function is to insert boilerplate text into the buffer. For example, this function might be used to add text specific to a certain programming language, such as control structures.──────────Value returned: This function returns the inserted string or an empty string if the supplied string was empty.══int_to_key()Purpose: Interprets a keycode into the key's name-string.──────────Syntax: str int_to_key(int char)──────────Description: The int_to_key() function provides the key- name string corresponding to the key described by the char argument. The char argument is a keycode value such as that returned by the getkey() or getchar() keyboard input functions.──────────Value returned: The value returned by the int_to_key() function is the key's descriptive string. A table containing the key-name strings used by this function appears in the "Keymapping" chapter of the Functions by Category manual. Passing an invalid argument to this function will result in an empty string being returned.══invoke_function() PELPurpose: Send a query or request to PEL interpreter.──────────Syntax: void invoke_function()──────────Description: The invoke_function() function, normally assigned to [F10], adds functionality to execute_function(). It prompts for a string which is to be sent to the PEL interpreter for processing. In addition to the capabilities of execute_function(), it allows setting and querying of global and local values, and recognizes several functions that require special treatment. Global variables may be set at the invoke_function() prompt using the following format: var_name = constant Variables local to a module are set in a similar manner except that the variable name must be preceded by the module name and a colon: filename:var_name = constant Similarly, local functions may be executed using the following form: filename:func_name The value of variables and return values of functions may be obtained by placing a question mark at the beginning of command. For example: ?brief.pel:my_margin The functions to which invoke_function() gives special treatment are system(), dos_window(), filter() and other similar functions. The argument string supplied to these functions requires some preprocessing. Other functions will have their argument strings separated into arguments strictly on the basis of whitespace with little or no preprocessing of special characters.──────────Value returned: No useful value is returned by this function. The function responds to queries by displaying a message in the dialog window.══is_system_window() PELPurpose: Tells if current window is for system use.──────────Syntax: int is_system_window()──────────Description: The is_system_window() function reports whether the current window has been defined as a system window. It is useful when creating a function that performs a task that should not be applied to system windows.──────────Value returned: Returns TRUE if the current window is a system window, else FALSE.══isalnum()Purpose: Tells if characters are in the alpha- numeric set.──────────Syntax: int isalnum(str s)──────────Description: The isalnum() function tests the characters in the s argument string to determine if they are alpha-numeric characters. Alpha- numeric characters include upper-case characters (A - Z), lower-case characters (a - z) and numeric characters (0 - 9).──────────Value returned: When all the characters in the argument string are within the definition of alpha- numeric characters, the isalnum() function returns a non-zero value (TRUE). If any of the characters are other than alpha- numeric, the function returns zero (FALSE).══isalpha()Purpose: Tells if characters are in the alphabetical set.──────────Syntax: int isalpha(str s)──────────Description: The isalpha() function tests the characters in the s argument string to determine if they characters of the alphabet. This includes upper-case characters (A - Z) and lower-case characters (a - z).──────────Value returned: When all the characters in the argument string are letters in (A - Z) or (a - z), the isalpha() function returns a non-zero value. If any of the characters are not letters of the alphabet, the function returns zero.══isascii()Purpose: Tells if characters are in the ASCII set.──────────Syntax: int isascii(str s)──────────Description: The isascii() function tests the characters in the s argument string to determine if the character corresponds to an ASCII value. This includes characters with values from 0 to 127.──────────Value returned: When all the characters in the argument string have a corresponding ASCII value, the isascii() function returns a non-zero value. If any of the characters are not ASCII, the function returns zero.══iscntrl()Purpose: Tells if characters are in the control character set.──────────Syntax: int iscntrl(str s)──────────Description: The iscntrl() function tests the characters in the s argument string to determine if their value corresponds to a control character. Control characters are those with an ASCII value between 0 and 31, and 127, the delete character.──────────Value returned: When all the characters in the argument string are control characters, the iscntrl() function returns a non-zero value. If any of the characters is not a control character, the function returns zero.══isdigit()Purpose: Tells if characters represent numbers.──────────Syntax: int isdigit(str s)──────────Description: The isdigit() function tests the characters in the s argument string to determine if they are an ASCII representation of a digit. A character is deemed to be a digit if it is in the set of 0 to 9.──────────Value returned: When all the characters in the argument string are digits, the isdigit() function returns a non-zero value. If any of the characters does not represent a numeral, the function returns zero.══isgraph()Purpose: Tells if characters have visible printing representation.──────────Syntax: int isgraph(str s)──────────Description: The isgraph() function tests the characters in the s argument string to determine if they are printing characters. The isgraph() function does not consider the space a printing character, as the isprint() function does. A character is deemed graphic if its ASCII value is within the range of 33 to 126.──────────Value returned: When all the characters in the argument string are printable, the isgraph() function returns a non-zero value. If any of the characters is non-printable or is a space, the function returns zero.══islower()Purpose: Tells if characters are lower-case letters.──────────Syntax: int islower(str s)──────────Description: The islower() function tests the characters in the s argument string to determine if they are lower-case letters. The characters a to z are considered lower- case.──────────Value returned: When all the characters in the argument string are lower-case, the islower() function returns a non-zero value. If the string contains any characters that are not lower-case, the function returns zero.══isprint()Purpose: Tells if characters have printable representation.──────────Syntax: int isprint(str s)──────────Description: The isprint() function tests the characters in the s argument string to determine if they are printing characters. The isprint() function considers the space a printing character, whereas the isgraph() function does not. A character is deemed printable if its ASCII value is within the range of 32 to 126.──────────Value returned: When all the characters in the argument string are printable, the isprint() function returns a non-zero value. If the string contains any characters that are not printable, the function returns zero.══ispunct()Purpose: Tells if characters represent punctuation.──────────Syntax: int ispunct(str s)──────────Description: The ispunct() function tests the characters in the s argument string to determine if they are punctuation. A character is deemed to be punctuation if its ASCII value falls in any of the following ranges: 33 - 47, 58 - 64, 91 - 96, 123 - 126.──────────Value returned: When all the characters in the argument string are punctuation, the ispunct() function returns a non-zero value. If any of the characters does not represent punctuation, the function returns zero.══isspace()Purpose: Tells if characters are white-space.──────────Syntax: int isspace(str s)──────────Description: The isspace() function tests the characters in the s argument string to determine if they are white-space characters. White- space characters are defined as space, tab, carriage return, line feed, form feed and vertical tab. The ASCII values of these characters are described by the set 9 to 13 and 32.──────────Value returned: When all the characters in the argument string are white-space, the isspace() function returns a non-zero value. If any of the characters does not represent white- space, the function returns zero.══isupper()Purpose: Tells if characters are lower-case letters.──────────Syntax: int isupper(str s)──────────Description: The isupper() function tests the characters in the s argument string to determine if they are upper-case letters. The characters A to Z are considered upper- case.──────────Value returned: When all the characters in the argument string are upper-case, the isupper() function returns a non-zero value. If the string contains any characters that are not upper-case, the function returns zero.══isxdigit()Purpose: Tells if characters represent hexadecimal numbers.──────────Syntax: int isxdigit(str s)──────────Description: The isxdigit() function tests the characters in the s argument string to determine if they are an ASCII representation of a hexadecimal digit. A character is deemed to be a hexadecimal digit if it is in the set of 0 to 9 and either A to F or a to f.──────────Value returned: When all the characters in the argument string are hexadecimal digits, the isxdigit() function returns a non-zero value. If any of the characters does not represent a hexadecimal number, the function returns zero.══key_to_int()Purpose: Tells the keycode associated with a key's name.──────────Syntax: int key_to_int(str key)──────────Description: The key_to_int() function provides the scan code and any ASCII equivalent for the key described by the key argument. The key argument is string containing the name of a key. A table containing the key-name strings used by this function appears in the "Keymapping" chapter of the Functions by Category manual.──────────Value returned: The value returned by the key_to_int() function is in the same format as that returned by the getkey() function. The least significant (lowest) byte contains the ASCII value of the key and the next byte contains the scan code. Passing an invalid argument to this function will result in a zero value returned.══keyboard_flags read-onlyPurpose: Stores the keyboard status byte.──────────Type: int keyboard_flags──────────Description: The keyboard_flags variable is a copy of the current DOS "keyboard status byte." The first eight bits of this variable (numbered from 0 to 7) are used as flags to indicate the status of various shift and toggle keys. When the bit is set (when it has a 1 value), the key is pressed or the toggle is on. When the bit is zero, the key has not been pressed, or the toggle is off. The table below shows which key or toggle is associated with each of these bits: Bit 0 Right shift key (01H) Bit 1 Left shift key (02H) Bit 2 Control key (04H) Bit 3 Alt key (08H) Bit 4 Scroll lock toggle(10H) Bit 5 Num lock toggle (20H) Bit 6 Caps lock toggle (40H) Bit 7 Insert toggle (80H) Bits 0 through 3 of this variable are set by the system and may not be modified by the user or user programs. Bits 4 through 7 may be interrogated or changed by the user. This allows the user to change the setting of these toggle keys.══keyboard_input_pendingPurpose: Indicates that a keystroke is waiting to be read.──────────Type: int keyboard_input_pending──────────Description: This variable is set to a non-zero (TRUE) value when one or more characters of keyboard input are waiting to be processed. When the keyboard buffer is empty, the keyboard_input_pending variable is set to zero (FALSE). Pending characters may be read with either the getchar() or getkey() functions. This variable is set by the system and may not be modified by the user.──────────See also: getchar(), getkey()══keyboard_speed()Purpose: Set the rate at which depressed keys repeat.──────────Syntax: void keyboard_speed(int repeat, int delay)──────────Description: The keyboard_speed() function sets the typematic repeat rate and initial delay before repeat. This function only works with keyboards that have a programmable repeat rate, such as AT class and enhanced keyboards. The repeat argument is an integer from 0 to 1000 specifying the number of times per second a key repeats when continuously depressed. The default repeat rate is 1000 repetitions per second. The delay argument is an integer from 250 to 1000 indicating in milliseconds how long the key must be depressed before it begins to repeat. The default delay is equivalent to a value of 250 or a quarter second delay. The delay settings allowed by the keyboard are not graded in milliseconds. When the keyboard does not support the specified delay, the closest allowable setting is adopted.──────────Value returned: No useful value is returned by this function.══keymap_binding()Purpose: Reports the name of the function assigned to a key.──────────Syntax: str keymap_binding(str keys [, keymapid keymap])──────────Description: The keymap_binding() function reports what function is associated with the keystroke or keystrokes described by the keys argument. The keys argument describes the keystrokes in string form. These descriptive strings are called key-name strings. A table containing the allowable key-name strings appears in the "Keymapping" chapter of the Functions by Category manual. The keymap argument may be used optionally to specify that the inquiry applies to a keyboard definition other than the one currently in use. If the keymap argument is omitted, the assignment reported applies to the current keymap or the local keymap assignment, if any.──────────Value returned: The string returned by this function upon successful completion contains the name of the function that will be executed when the described keystroke is executed. However, since complex keystrokes may be described by the keys argument, this does not always mean that the function has been assigned to that specific keystroke. A clarifying example follows: name = keymap_binding("<Ctrl-E>A") We will imagine that the example above has resulted in the variable name being assigned the value "exit_abort". This result could mean that exit_abort has been assigned to the key sequence [Ctrl][E] followed by [A]. However, it might also mean that exit_abort has been assigned to [Ctrl][E] and that no special assignment was made to [Ctrl][E],[A]. In the latter case, the exit_abort function would nonetheless be executed if you press [Ctrl][E],[A]. The [A] might be a character intended to be processed by the exit_abort function. An empty string is returned if the keymap has no function assigned to the specified key or if the key combination is not recognized.══larger_window()Purpose: Changes window to the next "larger" state.──────────Syntax: void larger_window()──────────Description: The larger_window() function expands the current window to normal size if it is an icon or full-screen if it is normal sized. If the window is already full-screen this function has no effect.──────────Value returned: No useful value is returned by this function.══last_message read-onlyPurpose: Contains the last displayed warning or error message.──────────Type: str last_message──────────Description: The last_message variable contains the text of the last message printed to the screen with the error(), warning(), or message() function. This allows the user to re- display the message or write a function that examines its contents. This variable is set by the system and may not be modified by the user.══learn_key()Purpose: Records keystrokes for assignment to a key.──────────Syntax: void learn_key()──────────Description: The learn_key() function is an extension of the record() and playback() functions allowing keystroke recordings to be assigned to a specific key. This allows more than one series of keystrokes to be defined at a time. When learn_key() is invoked, it requests the key combination to which the recording is to be assigned and then recording begins. The recording sequence is terminated by pressing again the key to which the recording is to be assigned.──────────Value returned: No useful value is returned by this function.══left()Purpose: Move cursor to the left on the line.──────────Syntax: int left([int positions])──────────Description: the left() function moves the cursor to the left by the number of positions specified by the positions argument. If the positions argument is omitted, a value of one is assumed. Depending on the value of the buffer_flags variable, positions are interpreted as either columns or characters. If movements into VIRTUAL SPACE are allowed, the positions argument is interpreted as columns. When movements into VIRTUAL SPACE are disallowed, positions means characters; excluding end-of-line sequences. If the value of positions is greater than the number of columns or characters between the cursor and the beginning of the line, the cursor moves only to the beginning of the line. Negative values for positions are allowed and result in the cursor moving in the opposite direction. In other words, calling left() with -3 as the argument is the as calling right() with 3 as the argument.──────────Value returned: The left() function returns the actual number of columns or characters traversed. This will be the same number as the positions argument, except when there are too few columns or characters between the cursor position and the beginning of the buffer to execute the move completely.──────────See also: prev_char()══length()Purpose: Tells the length of a specified string.──────────Syntax: int length(str s)──────────Description: The length() function reports the length of the s argument string.──────────Value returned: The value returned by length() is the number of characters in the string. If the s argument does not represent a defined string, the length will be reported as 0.──────────Compatibility: This function is used in the same manner as the like-named AWK function.══linenumber_format windowPurpose: Determines if and how line numbers are displayed.──────────Type: str linenumber_format──────────Description: Each window has a linenumber_format variable associated with it. The linenumber_format variable stores a format string used in displaying line numbers. The rules for interpreting the format string are largely a subset of those used by fprintf(). This string, after formatting, is displayed to the left of each line of text. This string may be empty, in which case line numbers are turned off. When line numbers are to be displayed this string will follow the form below: [leading_text]%[[0]n]c[trailing_text] Where leading_text and trailing_text are strings you wish to have precede and follow each line number, n is the number of columns allotted to line numbers and c is a format character indicating the numeric base to be used. The leading_text may not contain a percent sign. Values allowed for n are 1 to 9. If the line number would occupy more than the specified number of columns the most significant digits are not displayed. The optional 0 preceding n specifies that the number is left-filled with zeros rather than spaces. Values for c are shown below: b binary notation d decimal notation o octal notation x hexadecimal notation X hexadecimal, letters are upper case The format string will normally contain a percent sign, a number, a format character and a character to separate line numbers from the beginning of text. An example is shown below: linenumber_format = "%4d:" This variable takes its initial value at the time the window is created from the variable default_linenumber_format. The initial value of that variable is "". Invalid formats are treated the same as "".──────────See also: color_linenumbers══lines_between_marks()Purpose: Tells the number of lines between two bookmarks.──────────Syntax: int lines_between_marks(int mark1, int mark2)──────────Description: The lines_between_marks() function reports the number of lines between the bookmarks specified by the mark1 and mark2 arguments. The order in which these two arguments are specified is not significant. The function determines the line numbers in which mark1 and mark2 occur. The number of lines between the two bookmarks is then arrived at through subtracting one line number from the other.──────────Value returned: The value returned by lines_between_marks() is a positive integer representing the number of lines between the two indicated bookmarks. If the bookmarks are on the same line or one of the arguments does not represent a valid bookmark, the function returns zero. The mark_defined() function may be used to determine if a bookmark is valid.══list_vertical() PELPurpose: Makes a vertical list of substrings.──────────Syntax: str list_vertical(str list, int x, y, wide, high)──────────Description: The list_vertical() function takes a series of substrings supplied in the list argument and creates a vertical list in the form of a pop-up menu. The substrings in list are separated by a newline ("\n"). The arguments x and y position the upper left corner while high and wide determine the size of the pop-up window. The desired substring may be selected by moving the highlight with the arrow keys. The item is then accepted by pressing [Enter] or rejected by pressing [Esc]. This function uses menu_vertical().──────────Value returned: Returns the substring selected, or an empty string if [Esc] is pressed.══local_setup() PELPurpose: Builds in your personal preferences.──────────Syntax: void local_setup()──────────Description: The local_setup() function is called as part of the editor initialization process. Specifically, it is called by the startup() function. It is intended as a receptacle for functions that install or establish your personal operating preferences. For your convenience, numerous function calls have been entered as comments within this function. This enables you to review many of the more popular options. You may make those you desire to use operational by removing the pound sign ( # ) which precedes the desired option. The options selected in the local_setup() function may be overridden by options selected within the SAGEEDIT.CFG configuration file. This configuration file may be used to serve a purpose similar to local_setup(), but the less information contained in the configuration file the faster the editor will load. It is therefore preferable to make permanent changes to the editor's setup by way of local_setup().──────────Value returned: No useful value is returned by this function.══lower() PELPurpose: Converts characters in a block to lower-case.──────────Syntax: void lower()──────────Description: The lower() function converts all upper- case letters in a selected block of text to lower-case. If no block has been selected the character at the cursor is converted. Numbers punctuation and white-space in the block are not modified by this function.──────────Value returned: No useful value is returned by this function.──────────See also: tolower()══ltrim() PELPurpose: Deletes specified characters from beginning of line.──────────Syntax: str ltrim(str s [, str t])──────────Description: The ltrim() function creates a new string from the s argument, in which the characters in the t argument have been stripped from the left side of the string. The new string will not begin with any of the characters specified by t. If the t argument is omitted, all white- space will be stripped from the left end of the line. For the purpose of this function, white-space is defined as spaces and tabs.──────────Value returned: The value returned by the ltrim() function is the newly created string.══make_window() PELPurpose: Create a window with interactive sizing.──────────Syntax: void make_window()──────────Description: The make_window() function obtains the dimensions of a window to be created and then calls the create_window() function using the values received. If the user has a mouse and it has been enabled, the user indicates the size and location of the window with the mouse. Otherwise a window is displayed and the user is allowed to adjust the dimensions using the arrow keys. This function is intended to be assigned to a key.──────────Value returned: No useful value is returned by this function.══mark_column()Purpose: Reports the column in which a given bookmark occurs.──────────Syntax: int mark_column([markid num])──────────Description: The mark_column() function reports the column number in which the bookmark identified by the num argument may be found. This function will fail if num is not a valid bookmark id. If the num argument is omitted, the function returns the column of the selection mark.──────────Value returned: Upon success, mark_column() returns the line number associated with the indicated bookmark. Otherwise, a zero value is returned.══mark_defined()Purpose: Test to determine if a certain bookmark is in use.──────────Syntax: int mark_defined(markid num)──────────Description: The mark_defined() function reports whether or not the bookmark indicated by num is currently in use in the current buffer.──────────Value returned: If the bookmark is in use, mark_defined() returns a non-zero value. If the bookmark has not been defined, or has been defined in another buffer, a value of zero is returned.══mark_line()Purpose: Reports the line in which a given bookmark occurs.──────────Syntax: int mark_line([markid num])──────────Description: The mark_line() function reports the line number in which the bookmark identified by the num argument may be found. This function will fail if num is not a valid bookmark id. If the num argument is omitted, the function returns the line number of the selection mark.──────────Value returned: Upon success, mark_line() returns the line number associated with the indicated bookmark. Otherwise, a zero value is returned.══mark_paragraph() PELPurpose: Selects the paragraph in which the cursor is found.──────────Syntax: int mark_paragraph()──────────Description: The mark_paragraph() function drops a selection bookmark at the end of a paragraph and then moves the cursor to the to the beginning of the paragraph. The paragraph is highlighted as a result. For these purposes a paragraph is defined as any line or lines of text preceded by a blank line or the beginning of the buffer and followed by a blank line or the end of the buffer. If the cursor is not located within a paragraph, the paragraph immediately following the cursor location is selected. If there are only blank lines between the cursor position and the end of the buffer, no selection is made.──────────Value returned: The value returned by this function is non- zero (TRUE) on success, and zero (FALSE) if an error occurs.══marked_region_size()Purpose: Tells size of selected block.──────────Syntax: int marked_region_size()──────────Description: The marked_region_size() function reports the size of the block currently highlighted.──────────Value returned: If the block is of type NORMAL_SELECTION, LINE_SELECTION, or INCLUSIVE_SELECTION, the return value is equal to the number of characters included in the block. This count includes newlines. If the currently marked region is of type COLUMN_SELECTION, the return value is the area of the block in text cells. In this case, if the block contains VIRTUAL SPACE the return value is not equal to the number of characters in the block. It is the number of columns occupied by the selection. If no marked region exists, the return value is zero.══marks_in_buffer()Purpose: Counts the number of bookmarks in use for a buffer.──────────Syntax: int marks_in_buffer([bufid buffer])──────────Description: The marks_in_buffer() function reports the number of marks in use for the buffer indicated by the buffer argument. The buffer argument is a buffer id returned by the function used to create the buffer. If this argument is omitted or is zero, the current buffer is assumed. This count includes any marks in use by the system through functions as well as user- defined bookmarks. Bookmark 0, which is always the current position, however, is never included in this count.──────────Value returned: The value returned by marks_in_buffer() is the number of marks in use for the buffer indicated. If the specified buffer does not exist, the function fails and a zero value is returned.──────────See also: marks_used══marks_used read-onlyPurpose: Stores the number of marks in use by user and system.──────────Type: int marks_used──────────Description: This variable stores the number of bookmarks currently in use by the system, through library functions, and the user for all buffers. The actual number of bookmarks available to the user is somewhat less, however, since a number of additional bookmarks may be required by library functions. When possible, it is best to leave five bookmarks, times the number of buffers in use, available to library functions. This value is updated by the system and may not be modified by user functions.──────────See also: marks_in_buffer()══match()Purpose: Tells position of first occurrence of matching string.──────────Syntax: int match(str s, str regex)──────────Description: The match() function searches the s argument for the first occurrence of text matching the regex argument. The function then reports the position in the s string at which the match occurred. The regex argument is a regular expression, using the special characters defined for regular expressions. These characters are described in the "Regular Expressions" chapter of the User's Manual. The special meaning of these characters is in effect without regard to the state of the search_flags variable. The scope of the match is always maximal.──────────Value returned: The value returned by the match() function is the ordinal position at which the matching text begins. If no matches were found, or if one of the arguments was not a valid string, the function returns a zero value.══MEMAVAIL AWKPurpose: Stores the amount of heap memory available.──────────Type: int MEMAVAIL──────────Description: The MEMAVAIL variable contains the amount, in bytes, of dynamic heap memory that is available at any given time. This variable may not be modified by the user; only by the system.══menu_vertical()Purpose: Treats a buffer as a menu.──────────Syntax: void menu_vertical(bufid buf, int x, y, wide, high)──────────Description: The menu_vertical() function takes the buffer, described by the buf argument and displays it as a menu. The buffer is to contain descriptive strings (one per line), which become menu items. The arguments x and y position the upper left corner while high and wide determine the size of the menu window. The desired menu item may be selected by moving the highlight with the arrow keys. The item is then accepted by pressing [Enter] or rejected by pressing [Esc].──────────Value returned: The menu_vertical() function returns the string selected, or an empty string if the function is cancelled by pressing [Esc].══message()Purpose: Displays formatted output in the Dialog window.──────────Syntax: void message(str fmt [, any args,...])──────────Description: The message() function prints a formatted message to the Dialog window. If no dialog window has been defined, a window pops up to display the message. In this case SPE pauses for a key to be typed before closing the window. The output from this function is suppressed if the variable message_level is greater than 0. This function is primarily used to display informative messages, such as a message telling the user that a task has been completed. The fmt and args arguments follow the argument specifications of the fprintf() function.──────────Value returned: No useful value is returned by this function.──────────See also: message_level══message_levelPurpose: Indicates to what degree of messages should be displayed.──────────Type: int message_level──────────Description: The message_level variable allows the user to limit, to varying degrees, messages from the editor system or macros. These are the messages displayed by the functions message(), warning(), notify() and error() as well as internal messages. They appear in the Dialog Window which is usually a pop-up window or the bottom line of the screen. The useful values for this variable are shown below, along with their meaning: 0 All messages are displayed. 1 Suppress message() output. 2 Display only warnings and errors. 3 No messages displayed. If other values are assigned to this variable, all messages will be printed. The default value for this variable is 1.──────────See also: message(), notify(), warning(),error()══mkdir()Purpose: Create a new directory.──────────Syntax: int mkdir(str dir)──────────Description: mkdir() makes a new directory according to the path and directory name given in the dir argument.──────────Value returned: If successful, mkdir() returns a non-zero value. If an error occurs, a value of zero is returned. When a zero is returned, the errno will provide further information about the error. If a directory or file by the name found in dir already exists, errno or if some other error has occurred, errno will be non-zero.──────────Compatibility: This function is similar to the like-named function supported by major C compilers except as to return values.══mouse_available read-onlyPurpose: Tells if a mouse is attached.──────────Type: int mouse_available──────────Description: The mouse_available variable indicates whether or not the editor detected a Microsoft compatible mouse driver on start- up. If a mouse is later attached or removed, the value of this variable will not be changed. When the value of this variable is zero (FALSE), a mouse was not found. In this case, a mouse cursor will not appear and mouse events will never occur. When a mouse was found on start-up mouse_available will be a non-zero value. A non-zero value for the mouse_enabled variable is also required before SPE will display and use the mouse. The value of this variable may not be modified by the user.══mouse_buttons read-onlyPurpose: Indicates which mouse buttons are currently pressed.──────────Type: int mouse_buttons──────────Description: The mouse_buttons variable indicates which, if any, buttons of the mouse are being depressed at any given time according to which bits of the value are set. The first three bits of the mouse_buttons variable represent each of the three buttons with which a mouse might be equipped. Since many mice have only two buttons, the first two bits represent the left and right mouse buttons. The third bit represents the middle mouse button, if any. When the corresponding key is depressed the bit is set to 1. When the button is released, the bit is reset to 0. The value of this variable may not be modified by user-written programs.══mouse_click_speedPurpose: Sets the interval for multiple mouse button clicks.──────────Type: int mouse_click_speed──────────Description: The mouse_click_speed variable provides SPE with a basis for distinguishing between a mouse button being pressed, released, clicked or double clicked. When, after a period of inactivity, a mouse button is pressed a timer is started. The amount of mouse button activity which occurs while the timer is running determines whether the activity is interpreted as a press, release, click or double click. The mouse_click_speed variable determines how long in milliseconds the timer runs. If only a single mouse event occurs while the timer is running the event is interpreted as either a press or a release. If the mouse is both pressed and released during the interval it is considered a click. If the mouse button is pressed twice during the interval it is a double click. The values that may be assigned to this variable are in the range of 0 to 1500. The default value for this variable is 100 milliseconds. This default was selected as the optimum for the type of mouse commands supported (presses, releases and clicks). If double click commands are added, you may wish to consider increasing this value to 200.══mouse_confirm() PELPurpose: Respond to a prompt with the mouse.──────────Syntax: mouse_confirm( str prompt, str responses )──────────Description: This function is identical in its use to the confirm() function except that it allows the user to select a response using a mouse, if certain rules are followed. The mouse_confirm() call below: mouse_confirm("Exiting: Save or Abandon?","SsAa") produces the prompt "Exiting: Save or Abandon?" in a dialog window. It then allows the responses "S" or "A" in either upper or lower case. If the user chooses to respond with the mouse rather than typing in these characters, the user may Left-Click on either the word "Save" or the word "Abandon". The function looks for an upper-case letter at or preceding the position where the mouse was clicked and assumes that as a response. If the function encounters a colon before it finds an upper-case letter it gives up. The upper-case letter need not be the first letter of the word, but the user must click on or to the right of that character.──────────Value returned: This function returns the character selected.══mouse_cursor_maskPurpose: Determines characteristics of mouse cursor.──────────Type: int mouse_cursor_mask──────────Description: The value of the mouse_cursor_mask variable determines the color and other characteristics of the mouse cursor. The default value, which is 7700H, uses the compliment of the attribute that was originally displayed at the mouse position. The original character is also displayed. An XOR operation is performed on the character-attribute word with mouse_cursor_mask to determine cursor characteristics. This variable works in conjunction with the mouse_display_mask to determine the characteristics of the mouse cursor. The character-attribute word is ANDed with mouse_display_mask before mouse_cursor_mask is used.══mouse_display_maskPurpose: Determines characteristics of mouse display.──────────Type: int mouse_display_mask──────────Description: The value of the mouse_display_mask variable determines the blink, intensity and other characteristics of how the mouse cursor is displayed. The default value, which is 77FFH, displays the character that was originally displayed at the mouse position, rather than replacing it with a special mouse character. It also disables blinking and high intensity. An AND operation is performed on the character and attribute word with mouse_display_mask to determine display characteristics. The appearance of the mouse cursor is also dependent upon the value of mouse_cursor_mask, with which the character and attribute are XORed.══mouse_display_xPurpose: Tells which text column the mouse cursor occupies.──────────Type: int mouse_display_x──────────Description: The mouse_display_x variable stores the current screen column occupied by the mouse. This count begins with column 0 at the left edge of the display. together with mouse_display_y, this variable defines the current mouse position. Assigning a value to this variable changes the horizontal position of the mouse cursor.══mouse_display_yPurpose: Tells which text line the mouse cursor occupies.──────────Type: int mouse_display_y──────────Description: The mouse_display_y variable stores the current screen line occupied by the mouse. This count begins with line 0 at the top of the display. Together with mouse_display_x, this variable defines the current mouse position. Assigning a value to this variable changes the vertical position of the mouse cursor.══mouse_enabledPurpose: Tells whether a mouse is to be used.──────────Type: int mouse_enabled──────────Description: The mouse_enabled variable indicates whether a mouse should be used, if present. When this variable is set to a zero value (FALSE), no mouse cursor will appear and no mouse events will occur. When mouse_enabled is a non-zero value (TRUE), a mouse will be used if one is installed. The mouse_available variable is used to determine if a mouse is installed.══mouse_event_xPurpose: Stores column offset of mouse when last clicked.──────────Type: int mouse_event_x──────────Description: The mouse_event_x variable contains the column offset of the mouse cursor at the time the last "mouse event" occurred. A mouse event is a mouse button press or release. Together with mouse_event_y, this variable allows you to determine at what the mouse was pointing when one or more of the mouse keys were used. Keep in mind that screen positions differ from buffer positions in that the former are offset, and therefore zero origin, while the latter count begins with one. This variable represents a screen position. The value of this variable is updated whenever a mouse event occurs. The various SPE mouse events are described in the "User Interface" chapter of the Functions by Category manual.══mouse_event_yPurpose: Stores line offset of mouse when last clicked.──────────Type: int mouse_event_y──────────Description: The mouse_event_y variable contains the line offset of the mouse cursor at the time the last mouse event occurred. Together with mouse_event_x, this variable allows you to determine at what the mouse was pointing when one or more of the mouse keys were used. Keep in mind that screen positions differ from buffer positions in that the former are offset, and therefore zero origin, while the latter count begins with one. This variable represents a screen position. The value of this variable is updated whenever a mouse event occurs. The various SPE mouse events are described in the "User Interface" chapter of the Functions by Category manual.══mouse_selection_typePurpose: Determines type of block created by mouse.──────────Type: int mouse_selection_type──────────Description: The mouse_selection_type variable determines the type of selection or marked block that is created with the mouse. By default it is set to NORMAL_SELECTION, which will not include the character at the cursor position. It may be set to INCLUSIVE_SELECTION which will include the character at the cursor.══move_window()Purpose: Relocates a window without changing its size.──────────Syntax: void move_window(int col, int line [, winid window])──────────Description: The move_window() function moves the upper left corner of window described by the window argument to the screen coordinates indicated by the col and line arguments. The dimensions of the window are not changed. Window movement is restricted to the limits of the screen. If the coordinated specified would place any portion of the window off-screen, the window is placed at the position closest to the specified position that allows all of the window to be seen. If the window argument is not supplied, the function acts on the current window.──────────Value returned: No useful value is returned by the move_window() function.══msword() PELPurpose: Makes SPE operate similarly to the WORD╘ editor.──────────Syntax: void word()──────────Description: The msword() function executes a setup and installs a special keyboard definition that causes SPE to operate like the popular Word╘ word processor from Microsoft. This is one of the "emulation packages" provided with the Sage Professional Editor. Since the Sage Professional Editor is not a word processor there are differences inherent in the way SPE performs tasks and the way Microsoft Word performs similar tasks. Therefore, a complete emulation of Microsoft Word is not attempted. For a list of differences between SPE's Word╘ emulation and the Word╘ editor see Appendix B of the User's Manual.──────────Value returned: No useful value is returned by this function.══native() PELPurpose: Installs the SPE native keyboard definition.──────────Syntax: void native()──────────Description: The native() function executes a setup and installs the factory keyboard definition. This is one of the "emulation packages" provided with the Sage Professional Editor. Other keyboard definitions are described in the Appendices to the User's Manual.──────────Value returned: No useful value is returned by this function.══new_edit_file()Purpose: Performs extension dependent tasks upon load.──────────Syntax: void new_edit_file()──────────Description: The new_edit_file() function is an event handler designed to perform filename extension dependent tasks when a new file is read in for editing. It attempts to execute a user-written function whose name is based on the filename extension of the new file. The name of the function is the same as filename extension prefixed with an underscore. For example, if a file with the extension .COB is loaded, new_edit_file() attempts to execute a function called _cob. If the extension is .C it executes a function named _c. This function must be installed with the attach_event_handler() function before it will be effective.──────────Value returned: No useful value is returned by this function.══next_buffer()Purpose: Make a subsequent buffer on the list the current buffer.──────────Syntax: bufid next_buffer([str pattern [, int include_sys]])──────────Description: The next_buffer() function may be used in two ways, depending on whether the pattern argument is supplied. In either case, next_buffer() is used to change the currently active buffer. When the pattern argument is not present, next_buffer() may be used to increment forward through the buffers list. When pattern is supplied, next_buffer() will jump forward in the buffers list to a buffer whose buffer_name matches the pattern argument. The pattern argument may contain wildcard characters as described in the "Filename Matching" section of "Settling In" chapter of the User's Manual. Either of the following examples may be used to increment through the list of user buffers: next_buffer() next_buffer("") If the pattern argument has been specified, you may optionally supply the include_sys argument also. This argument is used to tell next_buffer() to include system buffers in the buffers list. Normally, there is no need to access system buffers since they are created and maintained for the use of SPE. If you find the need, however, you may access system buffers by supplying a non-zero value as the include_sys argument. You may then increment through the buffers list until you locate the system buffer of interest. The following example increments through the list of all buffers: next_buffer("",1) The current buffer is the last to be compared to the pattern argument.──────────Value returned: This function returns the numeric id of the buffer it makes current. This function cannot fail. If either pattern does not match any subsequent buffers or there is only one buffer in the list the current buffer remains current. In this case the id of the current buffer is returned.──────────See also: prev_buffer()══next_char()Purpose: Move cursor to a subsequent character in the buffer.──────────Syntax: int next_char([int chars])──────────Description: the next_char() function moves the cursor forward in the buffer by the number of characters specified by the chars argument. The end-of-line sequence is always treated as a single character. If the chars argument is omitted, a value of one is assumed. Negative values for chars are allowed and result in the cursor moving in the opposite direction. In other words, calling next_char() with -3 as the argument is the as calling prev_char() with 3 as the argument. This function is identical to the right()function described below, except that it never causes the cursor to enter VIRTUAL SPACE regardless of the setting of the buffer_flags variable.──────────Value returned: The next_char() function returns the actual number of characters traversed. This will be the same number as the chars argument, except when there are too few columns or characters between the cursor position and the end of the buffer to execute the move completely.──────────See also: right()══next_line() PELPurpose: Moves cursor to the start of text on subsequent line.──────────Syntax: void next_line()──────────Description: The next_line() function moves the cursor to the subsequent line in the buffer. If there is any text on the line the cursor is placed on the first character of this text. Otherwise, the cursor is placed at the end of the line.──────────Value returned: No useful value is returned by this function.══next_mark()Purpose: Move cursor to the next bookmark in current buffer.──────────Syntax: int next_mark()──────────Description: The next_mark() function moves the cursor to the position of the first bookmark subsequent to the current position in the buffer. If there are no subsequent bookmarks in the buffer, the cursor is not moved.──────────Value returned: This function returns the bookmark id at which the cursor was placed, upon successful completion. Otherwise, a zero value is returned.══next_sentence()Purpose: Moves the cursor to beginning of next sentence.──────────Syntax: void next_sentence([int n])──────────Description: The next_sentence() function advances the cursor to the first non-whitespace character following a period and one or more spaces. The n argument may be used to indicate motions of more than one sentence.──────────Value returned: No useful value is returned by this function.══next_window()Purpose: Make subsequent window in list the current window.──────────Syntax: winid next_window([str pattern [,int include_sys]])──────────Description: The next_window() function may be used in two ways, depending on whether a pattern is supplied. In either case, next_window() is used to change the currently active window. When the pattern argument is not present or is an empty string, next_window() may be used to increment forward through the windows list. When a pattern is specified, next_window() will look forward through the windows list for a window whose associated window_name matches the pattern argument. The pattern argument may contain wildcard characters as described in the "Filename Matching" section of "Settling In" chapter of the User's Manual. If the pattern argument has been specified, you may optionally supply the include_sys argument also. This argument is used to tell next_window() not to skip system windows in moving through the windows list. Normally, there is no need to access system windows unless you are writing a menuing routine. If you find the need, however, you may access system windows by supplying a non-zero value as the include_sys argument. You may then increment through the windows list until you locate the system window of interest. The following example increments through the list of all windows: next_window("",1) The current window is the last to be compared to the pattern argument.──────────Value returned: This function always returns the numeric id of the current window (current_window) as it exists after the operation. If the function fails, either because pattern does not match any subsequent window buffers or there fewer than two windows in the list, the current window does not change.══next_word() PELPurpose: Moves cursor to the first character of following word.──────────Syntax: int next_word([int count [, str regex]])──────────Description: The next_word() function moves the cursor to the first character of a word following the current position in the buffer. The number of words the cursor moves forward is determined by the value of the count argument. If this argument is not supplied the cursor moves forward one word. The regex argument is a string containing a regular expression. This string defines what constitutes a word. If this argument is omitted, a word is defined as non- whitespace characters following one or more characters of whitespace (spaces or tabs).──────────Value returned: The value returned by next_word() is non- zero (TRUE) if the cursor moved. Otherwise a zero (FALSE) value is returned.══nop()Purpose: Provides a method of assigning no task to a table entry.──────────Syntax: void nop()──────────Description: The nop() function does nothing. It does this as quickly and quietly as possible. This function is primarily used for assignment to keys in a keymap or other table where a function must be specified but no action is desired. For example, when the nop() function has been assigned to a key, nothing happens when that key is depressed.──────────Value returned: No value is returned by this function.══not()Purpose: Performs a bit-wise NOT on a number.──────────Syntax: int not(int num)──────────Description: The not() function derives a value from the num argument that is its compliment. The argument value remains unchanged. This function operates on a 32 bit value argument. If the argument is not a 32 bit number, it is converted to this form for the purpose of this function.──────────Value returned: Each bit in the value returned by the not() function is SET ( 1 ) only if the corresponding bit in the argument is not set. Otherwise, the bit is RESET ( 0 ).══notify()Purpose: Alerts user to a condition and allows response.──────────Syntax: void notify(str fmt [, any args,...])──────────Description: The notify() function prints a formatted message to the Dialog window. If no dialog window has been defined, a window pops up to display the message. In this case SPE pauses for a key to be typed before closing the window. The output from this function is suppressed if the variable message_level is greater than 1. This function is primarily used for responses to queries and to notify the user of additional actions to take. The messages printed by notify() normally need to be seen by the user. The fmt and args arguments follow the argument specifications of the fprintf() function.──────────Value returned: No useful value is returned by this function.──────────See also: message_level, message(), warning(),error()══OFS AWKPurpose: Identifies the AWK output field separator.──────────Type: str OFS──────────Description: The OFS variable is used by the AWK print() function. It defines what character or characters the print() function places between the expressions it prints. The initial value for this variable is " ", a single space.══open_line()Purpose: Inserts a new line following the current line.──────────Syntax: int open_line()──────────Description: The open_line() function opens a new line immediately below the current one and positions the cursor at the beginning of that line. The effect of this function is always the same as moving the cursor to the end of the current line and executing a insert_newline(). The insert_newline() function is normally assigned to the [Enter] key unless auto-indent is on.──────────Value returned: The value returned by open_line() is non- zero (TRUE) upon success. If the buffer is not editable the function will fail and return zero or FALSE.══or()Purpose: Performs a bit-wise OR on two numbers.──────────Syntax: int or(int num1, int num2)──────────Description: The or() function compares the bits of the num1 and num2 arguments and derives a third value from them. The argument values remain unchanged. This function operates on 32 bit values. If the arguments are not 32 bit numbers, they are converted to this form for the purpose of this function.──────────Value returned: Each bit in the value returned by the or() function is SET ( 1 ) if the corresponding bit in either argument is set. Otherwise, the bit is RESET ( 0 ).══ord()Purpose: Casts a one character string as an integer value.──────────Syntax: int ord(str s)──────────Description: The ord() function reports the ASCII value of the character in the s string argument. If the string argument contains more than one character, only the first character will be considered.──────────Value returned: The value returned by the ord() function is the ASCII value corresponding to the first character of the s argument. If the string is empty or has not been defined, the function will return a zero value.══organize_buffers()Purpose: Displays an icon for each buffer defined.──────────Syntax: void organize_buffers()──────────Description: The organize_buffers() function defines a window for each buffer in use and then displays them in rows as icons. This can be useful when working with a large number of buffers.──────────Value returned: No useful value is returned by this function.══organize_windows()Purpose: Displays all defined windows as icons.──────────Syntax: void organize_windows()──────────Description: The organize_windows() function displays all defined windows in rows as icons. This can be useful when working with a large number of windows.──────────Value returned: No useful value is returned by this function.══ORS AWKPurpose: Identifies the AWK output record separator.──────────Type: str ORS──────────Description: The ORS variable is used by the AWK print() function. It defines what character or characters print() outputs at the end of the expressions printed. The initial value of this variable is "\n", a new-line sequence.══os_namePurpose: Stores name of the operating system in use.──────────Type: str os_name──────────Description: The string variable os_name is set to either "DOS" or "OS/2" depending on the operating system you are using. This enables user-written programs to take actions that are conditional upon the operating system present. Note that the value will be "DOS" when run in OS/2's DOS- compatibility box. This variable is set by editor system and may not be modified by the user or user- written macros.══outdent_columns()Purpose: Un-indent lines by deleting whitespace at left of text.──────────Syntax: int outdent_columns([int num])──────────Description: The outdent_columns() function shifts text a specified number of columns to the left. This is done by removing spaces or tabs from the whitespace preceding text in a line or lines of text. The cursor moves with the text to maintain its relative position. If a column marked block of text has been defined, whitespace is removed from each line immediately to the left of the column at which the block begins. When other types of blocks exist, whitespace is removed from the beginning of each line in the block. The number of columns to shift each line is determined by the value of the num argument. If the num argument is omitted, a value of 1 is assumed for that argument.──────────Value returned: This function returns a non-zero value (TRUE) when successfully completed. A zero value (FALSE) is returned if there is no whitespace to the left of text or an invalid value is supplied for the num argument.══outdent_tabs()Purpose: Un-indent lines a specified number of tab stops.──────────Syntax: int outdent_tabs([int num])──────────Description: The outdent_tabs() function shifts text a specified number of tab stops to the left. This is done by removing spaces or tabs from the whitespace preceding text in a line or lines of text. The cursor moves with the text to maintain its relative position. If a column marked block of text has been defined, whitespace is removed from each line immediately to the left of the column at which the block begins. When other types of blocks exist, whitespace is removed from the beginning of each line in the block. The number of tabs stops to shift each line is determined by the value of the num argument. If the num argument is omitted, a value of 1 is assumed for that argument.──────────Value returned: This function returns a non-zero value (TRUE) when successfully completed. A zero value (FALSE) is returned if there is no whitespace to the left of text or an invalid value is supplied for the num argument.══page_down()Purpose: Move the cursor ahead in the buffer one page.──────────Syntax: int page_down([int pan])──────────Description: The page_down() function advances the cursor position within the buffer by a page. A page is defined as the number of lines of text in the window, less the value of the window_page_overlap variable. If there is less than a page between the cursor position and the end of the buffer, the last line of text is scrolled up to the cursor position. The cursor may either scroll or pan as a result of the page_down() function. When panning, the cursor attempts to maintain its position relative the window regardless of the motion of text. When scrolling, it attempts to maintain its position within the buffer. You may dictate whether this function causes the cursor to scroll or pan by supplying the pan argument. When pan is zero the cursor will scroll. Other values for pan will cause the cursor to pan. If you do not supply the pan argument, cursor action is determined by the condition of the scroll_means_pan variable.──────────Value returned: The value returned by the page_down() functions is the number of lines actually scrolled. If the cursor was already on the last line of the buffer, a zero is returned.══page_up()Purpose: Move the cursor backward in the buffer one page.──────────Syntax: int page_up([int pan])──────────Description: The page_up() function moves the cursor position backward within the buffer by a page. A page is defined as the number of lines of text in the window, less the value of the window_page_overlap variable. If there is less that a page of text between the current cursor position and the beginning of the buffer, the cursor moves to the first line of text in the buffer. The cursor may either scroll or pan as a result of the page_up() function. When panning, the cursor attempts to maintain its position relative the window regardless of the motion of text. When scrolling, it attempts to maintain its position within the buffer. You may dictate whether this function causes the cursor to scroll or pan by supplying the pan argument. When pan is zero the cursor will scroll. Other values for pan will cause the cursor to pan. If you do not supply the pan argument, cursor action is determined by the condition of the scroll_means_pan variable.──────────Value returned: The value returned by the page_up() functions is the number of lines actually scrolled. If the cursor was already on the first line of the buffer, a zero is returned.══paste() PELPurpose: Insert contents of scrap buffer at cursor position.──────────Syntax: int paste()──────────Description: The paste() function inserts the contents of the scrap buffer into the current buffer. When no block of text has been selected, the text is inserted at the beginning of the line containing the cursor. Otherwise, the text is inserted at the current cursor position. The cursor position is maintained throughout this function; it does not follow the text on which it was previously located. The contents of the scrap buffer are not modified or lost. This function is synonymous with the function insert_scrap().──────────Value returned: When successful, the paste() function returns a non-zero value (TRUE). If for any reason the function can not be completed, a zero (FALSE) value will be returned.══path_ext()Purpose: Extract the filename extension from a string.──────────Syntax: str path_ext(str s)──────────Description: The path_ext() function creates a new string containing the filename extension found in the s argument. The new string begins with the dot found in the argument. The string following the dot will be a maximum of three characters.──────────Value returned: The value returned by the path_ext() argument is the newly created string. If the string does not contain a dot, or period, the string returned will be empty. If the argument string is undefined, an empty string will be returned.══path_fname()Purpose: Extract a filename from a string.──────────Syntax: str path_fname(str s)──────────Description: The path_fname() function creates a string from the s argument. The s argument contains a filename and often a path element. This function locates the filename within the string and copies it, less any extension, into the new string.──────────Value returned: The value returned by the path_fname() function is the newly created string. If the argument provided does not contain a filename and does not end with a path delimiter ( / or \ ), the last element of the path is returned. If the argument is not a defined string, an empty string is returned.══pause_on_errorPurpose: Dictates whether or not to pause between messages.──────────Type: int pause_on_error──────────Description: When the pause_on_error variable is a non- zero value, the editor will pause after each error or warning message until some input is received from the keyboard. By default, an enter key symbol ( ┐ ) is displayed following the message to indicate that the editor is awaiting user input. After receiving input, the next message, if any, is displayed. When this variable is set to zero, messages are displayed as fast as they are generated. In some instances, this will not provide sufficient time for messages to be read.══pe()Purpose: Toggles pausing between messages.──────────Syntax: void pe([int on])──────────Description: pe() is a tersely named function to modify the pause_on_error variable, suitable for executing through the PEL interpreter ([F10]). When the on argument is omitted, this function toggles pausing between error messages to its opposite condition. When the argument is supplied, a zero value turns pausing off, while other values turn pausing on.──────────Value returned: No useful value is returned by this function.══pick_unused_mark()Purpose: Select a bookmark number not currently in use.──────────Syntax: int pick_unused_mark()──────────Description: The pick_unused_mark() function selects a bookmark number not currently in use. It does not create a bookmark but merely supplies a number. This function is useful as an argument to several bookmark functions when you do not want to redefine an existing bookmark.──────────Value returned: The pick_unused_mark() function returns the lowest bookmark number not in use. If all bookmarks are in use a zero value is returned.══place_bookmark()Purpose: Mark a location and buffer for later reference.──────────Syntax: void place_bookmark([int n])──────────Description: The place_bookmark() function drops a bookmark at the current location and remembers which buffer it is in. You may then return to the bookmark from any buffer using the goto_bookmark() function. The function will prompt for a bookmark number if not supplied and will suggest the next unused bookmark number. This function is limited to the 10 bookmarks from 1 to 10.──────────Value returned: No useful value is returned by this function.══play()Purpose: Play music from the speaker.──────────Syntax: void play(str string)──────────Description: The play() function produces musical notes to be emitted from the speaker, based on instructions contained in the string argument. The instructions in the string must conform to a special "Play" language. This language is similar to that used by the Microsoft Basic PLAY statement, and is described below. The play() function is capable of playing 84 different notes, comprising 7 octaves. These notes may be specified by number ( 1- 84 ) or by octave and letter ( A-G ). Octaves are numbered from 0 to 6. In addition, duration and tempo may also be indicated. Specifying Notes -- Notes may be specified by placing some combination of the letters A through G into the s argument or by inserting the letter N immediately followed by the note number. Note letters A to G may be followed by either # or + to indicate sharp, or by - to indicate flat. Note numbers range from 1 to 84, with 1 representing the lowest note and 84 representing the highest. Octaves -- When specifying notes by letter, stating the octave is usually desirable. Initially, the octave is set by inserting the letter o in the play string followed immediately by the octave number ( 0-6 ). Later in the string you may wish to change octaves by inserting another o instruction, or by using the < or > instruction. The < and > instructions shift the octave down and up respectively for the notes that follow. These instructions shift the effective octave a single octave per instruction and have no effect if the shift would advance the octave higher than 6 or lower than 0. Rests -- Rests may be played by specifying note 0 in conjunction with the N instruction ( N0 ), or by using the pause instruction. The pause instruction is the letter P followed by a number in the range of 1 to 64 to specify the length of the pause ( e.g., P2 ). A value of 1 signifies a rest equivalent to a whole note, 4 a quarter note, 8 an eighth note and so on. The higher the number, the shorter the rest. Duration and Tempo -- Just as the length of a pause may be set, the duration and tempo of notes may also be specified. The L instruction determines the relative length of each note that follows it. It is immediately followed by a number indicating the value of the notes ( e.g., L4 ). This number is in the same range and has the same meaning as the number following the pause instruction, described above. A dot placed after the note letter has the same effect on duration as a dot placed after a note in a musical score: the duration of the note is increased by half. The actual time allotted to notes is determined by the tempo instruction. The tempo instruction takes the form of a T followed by a number. The number specifies the number of quarter notes per minute. If the T instruction is not specified, a value of 120 quarter notes per minute is used. A range of values from 32 to 255 may be specified. Style -- The musical style of the notes may also be set, which also affects the duration. The style instruction is the letter M followed by either an N, L or S for Normal Legato or Staccato, respectively. The default setting is equivalent to MN, which causes notes to be sustained for seven eighths of the interval indicated by the length ( L ) instruction. The ML instruction causes notes to be sustained for the full interval, and MS instruction for three fourths the interval. __________________________________________ A-G Notes within the current octave. Nn Note n within the range 1 to 84. N0 Rest. #,+ Note postfix modifiers indicating sharp. - Note postfix modifier indicating flat. < Set octave one octave lower. > Set octave one octave higher. On Set octave to octave n in range 0 to 6. Pn Pause for n interval in range 1 to 64. Ln Sustain notes for n interval in range 1 to 64. . Note Postfix modifier indicating dotted note. Tn Set tempo to n quarter notes per minute. MN Set style to Normal (sustain 7/8ths interval). ML Set style to Legato (sustain entire interval). MN Set style to Staccato (sustain 3/4ths interval).──────────Value returned: No useful value is returned by this function.══playback()Purpose: Reissue a series of previously recorded keystrokes.──────────Syntax: int playback([str recording [, keymapid keymap]])──────────Description: The playback() function issues the keystrokes contained in the recording argument. If this argument is not supplied, playback() replays the keystrokes in the last string recorded. These keystrokes have the effect of being entered using the keyboard definition indicated by the keymap argument. If the keymap argument is not specified, the keystrokes are issued through the keymap currently in effect.──────────Value returned: The value returned by the playback() function is non-zero (TRUE) on successful completion. The function will fail if a function assigned to one of the keystrokes issued cannot be successfully completed. It will also fail if there is an invalid keystroke contained in the recording argument. Upon failure, the function returns a zero (FALSE) value.══pop_dir()Purpose: Makes previously stored directory current.──────────Syntax: void pop_dir()──────────Description: The pop_dir() function restores as the current working directory a path that was previously saved on a stack. The push_dir() function is used to store the current working directory on this stack.──────────Value returned: No useful value is returned by this function.══pop_keymap() PELPurpose: Restore the most recently saved keyboard definition.──────────Syntax: int pop_keymap()──────────Description: The pop_keymap() function restores a keymap previously saved with the push_keymap() function. The keymap on the stack which was most recently saved is removed from the stack and made the current keymap.──────────Value returned: The pop_keymap() function returns a non- zero (TRUE) value. If there are no keymaps remaining on the stack, the function will return a zero (FALSE) value.══prefix()Purpose: Obtain a sub-string from the beginning of a string.──────────Syntax: str prefix(str s, int num)──────────Description: The prefix() function creates a new string which is a sub-string of the s argument. The sub-string is copied from the beginning of the string argument. The number of characters copied into the new string is determined by the value of the num argument.──────────Value returned: The value returned by the prefix() function is the newly created string. If the num argument is greater than the length of the string, the entire string is returned. If the supplied string is empty, an empty string is returned.══prev_buffer()Purpose: Make a preceding buffer on the list the current buffer.──────────Syntax: bufid prev_buffer([str pattern [, int include_sys]])──────────Description: The prev_buffer() function may be used in two ways, depending on whether the pattern argument is supplied. In either case, prev_buffer() is used to change the currently active buffer. When the pattern argument is not present, prev_buffer() may be used to increment backward through the buffers list. When pattern is supplied, prev_buffer() will jump backwards in the buffers list to a buffer whose buffer_name matches the pattern argument. The pattern argument may contain wildcard characters as described in the "Filename Matching" section of "Settling In" chapter of the User's Manual. If the pattern argument has been specified, you may optionally supply the include_sys argument also. This argument is used to tell prev_buffer() to include system buffers in the buffers list. Normally, there is no need to access system buffers since they are created and maintained for the use of SPE. If you find the need, however, you may access system buffers by supplying a non-zero value as the include_sys argument. You may then increment through the buffers list until you locate the system buffer of interest. The current buffer is the last to be compared to the pattern argument.──────────Value returned: This function returns the numeric id of the buffer it makes current. This function cannot fail. If either pattern does not match any subsequent buffers or there is only one buffer in the list the current buffer remains current. In this case the id of the current buffer is returned.──────────See also: next_buffer()══prev_char()Purpose: Move cursor to a previous character in the buffer.──────────Syntax: int prev_char([int chars])──────────Description: The prev_char() function moves the cursor backward in the buffer by the number of characters specified by the chars argument. The end-of-line sequence always counts as a single character. If the chars argument is omitted, a value of one is assumed. Negative values for chars are allowed and result in the cursor moving in the opposite direction. In other words, calling prev_char() with -3 as the argument is the as calling next_char() with 3 as the argument. This function is identical to the left() function, except that it never causes the cursor to enter VIRTUAL SPACE regardless of the setting of the buffer_flags variable.──────────Value returned: The prev_char() function returns the actual number of characters traversed. This will be the same number as the chars argument, except when there are too few columns or characters between the cursor position and the beginning of the buffer to execute the move completely.──────────See also: left()══prev_command read-onlyPurpose: Stores the id of the previously executed function.──────────Type: funcid prev_command──────────Description: The prev_command variable contains the function id of the function executed from the keyboard immediately preceding the current. This includes any functions which have been assigned to keys. The function id stored in prev_command may be converted to a string containing the name of the function. This is done through use of the function_name() function. This variable may only be modified by the system.──────────See also: function_caller(), current_command()══prev_key read-onlyPurpose: Stores the keystroke preceding most recently received.──────────Type: int prev_key──────────Description: The prev_key variable contains the value of key combination that preceded the keystroke most recently entered by the user. If the key pressed was an ordinary character, its ASCII value will be found in the least significant byte of prev_key. If, however, the key returned an extended code, the least significant byte will be null and the code will be in the second byte of prev_key.══prev_line() PELPurpose: Moves cursor to the start of text on previous line.──────────Syntax: void prev_line()──────────Description: The prev_line() function moves the cursor to the previous line in the buffer. If there is any text on the line the cursor is placed on the first character of this text. Otherwise, the cursor is placed at the end of the line.──────────Value returned: No useful value is returned by this function.══prev_mark()Purpose: Move cursor to a previous bookmark in current buffer.──────────Syntax: int prev_mark()──────────Description: The prev_mark() function moves the cursor to the position of the previous bookmark nearest to the current position in the buffer. If there are no previous bookmarks in the buffer, the cursor is not moved.──────────Value returned: This function returns the bookmark id at which the cursor was placed, upon successful completion. Otherwise, a zero value is returned.══prev_sentence() PELPurpose: Moves cursor to beginning of previous sentence.──────────Syntax: void prev_sentence([int n])──────────Description: The prev_sentence() function moves the cursor backward to the first non-whitespace character following a period and one or more spaces. The n argument may be used to indicate motions of more than one sentence.──────────Value returned: No useful value is returned by this function.══prev_window()Purpose: Make preceding window on list the current window.──────────Syntax: winid prev_window([str pattern [, int include_sys]])──────────Description: The prev_window() function may be used in two ways, depending on whether the pattern argument is supplied. In either case, prev_window() is used to change the currently active window. When the pattern argument is not present, prev_window() may be used to increment backward through the windows list. When pattern is supplied, prev_window() will jump backwards in the windows list to a window whose buffer_name matches the pattern argument. The pattern argument may contain wildcard characters as described in the "Filename Matching" section of "Settling In" chapter of the User's Manual. If the pattern argument has been specified, you may optionally supply the include_sys argument also. This argument is used to tell prev_window() not to skip system windows in moving through the windows list. Normally, there is no need to access system windows unless you are writing a menuing routine. If you find the need, however, you may access system windows by supplying a non-zero value as the include_sys argument. You may then increment through the windows list until you locate the system window of interest. The following example increments through the list of all windows: prev_window("",1) The current window is the last to be compared to the pattern argument.──────────Value returned: This function always returns the numeric id of the current window (current_window) as it exists after the operation. If the function fails, either because pattern does not match any subsequent window buffers or there fewer than two windows in the list, the current window does not change.══prev_word() PELPurpose: Moves cursor to the first character of previous word.──────────Syntax: int prev_word([int count [, str regex]])──────────Description: The prev_word() function moves the cursor to the first character of a word preceding the current position in the buffer. When the cursor is located within a word, the prev_word() function moves it to the beginning of that word. The number of words the cursor moves backward is determined by the value of the count argument. If this argument is not supplied the cursor moves backward one word. The regex argument is a string containing a regular expression. This string defines what constitutes a word. If this argument is omitted, a word is defined as non- whitespace characters following one or more characters of whitespace (spaces or tabs).──────────Value returned: The value returned by prev_word() is non- zero (TRUE) if the cursor moved. Otherwise a zero (FALSE) value is returned.══print() AWKPurpose: Send text to the standard output device a la AWK.──────────Syntax: void print(any expr [, any expr...])──────────Description: The print() function is an AWK statement. The default action for print is to send the string equivalent of any expressions given as arguments to the Standard Output Device. The output always ends with a new-line sequence. EXAMPLE print("All is well.") Using print() in this manner usually has the effect of making a mess of SPE's display.──────────Value returned: No useful value is returned by this function.══print_buffer() PELPurpose: Output a block of text to the standard line printer.──────────Syntax: void print_buffer()──────────Description: The print_buffer() function prints a marked block of text, or the entire active file buffer if no block is marked, to the stdprn device. Tabs are expanded, before printing, in accordance with the current setting of the buffer_tabs editor variable.──────────Value returned: If a printer error occurs the executing macro is terminated. There is therefore no point in testing the return value of print_buffer().══print_devicePurpose: Stores device or file name used for printing.──────────Type: str print_device──────────Description: The print_device string names the device to which the print_buffer() function will write. Its default value is "prn". It may be set to such values as "lpt2" or "myfile.txt" as desired.══print_version() PELPurpose: Shows what version of SPE is in use.──────────Syntax: void print_version()──────────Description: The print_version() function displays the SPE version number in the dialog window.──────────Value returned: No useful value is returned by this function.══printf()Purpose: Writes a formatted string to stdout device.──────────Syntax: void printf(str fmt [, any args,...])──────────Description: The printf() function formats a string, as indicated by the fmt and args arguments and writes it on the device indicated by the stdout variable. The default action for this function is to print the string on the screen at the current cursor position. Though the buffer text on the screen is overwritten, the actual contents of the buffer is not modified. Since the resulting screen appearance is rarely satisfactory, it is best to redirect this output to a file. The output string may be written to a file in one of two ways: using DOS redirection at the time the editor is invoked, or by assigning the return value of a call to the fopen() function to stdout. The fmt and args arguments follow the argument specifications of the fprintf() function.──────────Value returned: No useful value is returned by this function.══process_begin()Purpose: Initiate a nested editing process.──────────Syntax: any process_begin()──────────Description: The process_begin() function begins a new editing process from within the current editing process. The new process inherits the keymap definition in effect when the new process is begun. All of the definitions and buffers defined in the parent editing process are available in the new process. This new process continues until process_end() is called. This function is particularly useful for invoking menuing routines and pop-up utilities. It simplifies the writing of such functions by relieving the writer of the need to insert numerous exit points in the function. Instead, the process_end() function may be assigned to a specific keystroke, and the new process continues until that key sequence is entered.──────────Value returned: The value returned by this function is determined by the process_end() function which terminates it. The return value is passed as an argument to the process_end() function.══process_command_line() PELPurpose: Interprets SPE command line arguments and options.──────────Syntax: void process_command_line()──────────Description: The process_command_line() function performs the start-up task of interpreting flags and filenames specified on the command line. The interpretation and handling of the command line may be modified by changing this function. The function is supplied in the file NUCLEUS.PEL. This function is called by startup().──────────Value returned: No useful value is returned by this function.══process_end()Purpose: Terminate a nested editing process.──────────Syntax: void process_end([any value])──────────Description: The process_end() function causes the current editing process to terminate. If the editing process is nested within another process, control is returned to the previous process. If there is no previous editing process, the exit() function is called. The process, begun with process_begin() is terminated using the value argument as its return value.──────────Value returned: No value is returned from this function since it does not itself return.══process_nesting_limitPurpose: Limits the number of recursive editing processes.──────────Type: int process_nesting_limit──────────Description: The process_nesting_limit variable determines the maximum number of times that the process_begin() function may be called without corresponding calls to process_end(). The process_begin() function is used for menuing and other activities which require a specialized keyboard or whose point of termination is indeterminate. These processes continue until a call to process_end() is encountered, which ends the most recently invoked process. This variable may be set to any reasonable value by the user, but is intended to avoid "runaway recursion". The default value for process_nesting_limit is 10. If an attempt is made to begin a new process that would exceed the stated limit, an error message is displayed instead. NOTE: The Sage Professional Editor uses process_begin() during initialization. This means that the number of processes available to the user will be process_nesting_limit minus one.──────────See also: process_begin(), process_end().══prompt()Purpose: Presents a string for editing.──────────Syntax: str prompt(str message [, str default])──────────Description: The prompt() function requests a string value from the user. An initial value for this string may be supplied in the default argument. The message string describes the input requested and is displayed in the dialog window. This function is useful in obtaining values for assignment to editor string variables, and also string arguments to functions. It may be used to obtain a directory to use or for inputting any string. When editing an initial value, the first key struck by the user determines if the string is to be edited or replaced. If the key struck represents a character, the string is re-initialized and that character becomes the sole contents of the string. If instead the key struck is a cursor key [Home], [End] or [Bksp] the initial string is retained for editing. The [Enter] key ends the editing process and sends away the dialog window.──────────Value returned: The value returned by the prompt() function is the string specified by the user.══prompt_history()Purpose: Prompt for string; remember previous strings.──────────Syntax: str prompt_history(str index, str message, str default)──────────Description: Like prompt(), this function prompts for string input, but pressing the up and down arrow keys allows it to recall previous responses. The index argument is user- defined string with which previous responses are associated. For example, previous search string entries that were associated with the index string SEARCH are available whenever SEARCH is specified again. This history is not retained between editor sessions.──────────Value returned: The prompt_history() function returns the string entered as a response.══prompt_responsePurpose: Stores input from user.──────────Type: str prompt_response──────────Description: The prompt_response variable is used by library functions that prompt the user for input. These functions treat the contents of prompt_response as user input. Through the use of an Event, the contents of this variable may be modified as the user is being prompted. For example, pressing the up arrow when prompted could be made to cause the result of a previous prompt to be assigned to prompt_response. The prompting function could then receive this as input from the user. See the "Event Handling" chapter of the Functions by Category manual for details of event handling.══push_dir()Purpose: Saves the current directory and logs to new one.──────────Syntax: void push_dir(str new_cwd)──────────Description: The push_dir() function records the current working directory on a "stack" and makes the directory named in the new_cwd argument current. The pop_dir() function is used to restore the directory most recently saved on the stack.──────────Value returned: No useful value is returned by this function.══push_keymap() PELPurpose: Saves a keymap on the stack, makes another current.──────────Syntax: int push_keymap([keymapid keymap])──────────Description: The push_keymap() function saves the current keyboard definition on the stack it shares with the pop_keymap() function. It then makes the keymap described by the keymap argument the new current keymap. If the keymap argument does not represent a valid keymap, this function does nothing but return an error. If the keymap argument is omitted the current keyboard definition remains the same. However, that keymap's id has been saved on the stack for later restoration.──────────Value returned: Upon successful completion, the push_keymap() function returns a non-zero (TRUE) value. On error this function returns a zero (FALSE) value.══pvcs()Purpose: Toggles PVCS support features.──────────Syntax: void pvcs([int level])──────────Description: The pvcs() function is a more tersely named synonym of the toggle_pvcs() function. It controls the level of automatic PVCS (Polytron Version Control System) support provided by SPE. The following values have been defined for the level argument: PVCS_DISABLED 0 PVCS_ENABLE_GETS 1 PVCS_ENABLE_EMPTY_GETS 2 PVCS_ENABLE_GETS + PVCS_ENABLE_EMPTY_GETS 3 PVCS_DISABLED (0) means that no automatic PVCS support is desired. PVCS_ENABLE_GETS (1) indicates that if the user attempts to load a read-only file the user is given the opportunity to retrieve a writable copy of the file from its PVCS archive (logfile). PVCS_ENABLE_EMPTY_GETS indicates that if the user attempts to load a non-existent file the user is given the opportunity to retrieve the file from its PVCS logfile. The PVCS_ENABLE_GETS and PVCS_ENABLE_EMPTY_GETS values may be combined (3) to prompt the user for retrieval of the file if it either doesn't exist or it is read-only.──────────Value returned: No useful value is returned by this function.══pvcs_menu() PELPurpose: Displays a menu of PVCS commands.──────────Syntax: void pvcs_menu()──────────Description: The pvcs_menu() function displays a list of PVCS commands that are known to SPE. The executables to operate these commands are not supplied with SPE and they must be on the PATH or in the current directory in order to be used. Whenever possible, SPE adds intelligence to these commands. For example, the VDIFF command assumes that you want to compare the file corresponding to the current buffer to the tip revision in its logfile. You are given the opportunity to edit the command before it is executed, however. The other PVCS commands make similar assumptions and may be similarly edited.──────────Value returned: No useful value is returned by this function.══quit()Purpose: Exits the editor in an orderly fashion.──────────Syntax: void quit([int code [, int save]])──────────Description: The quit() function provides a method of exiting the editor with any necessary clean-up. The save argument, if supplied, controls the disposition of modified buffers upon exit. If the save argument is present, the user is not prompted to save modified buffers. Instead, save answers the question that would otherwise be posed by the prompt. When save is FALSE (0), buffers are abandoned without saving. When save is non-zero (TRUE), modified buffers are saved to disk. If save is omitted, the user is prompted to save when modified buffers exist. The code argument is the value to be passed to the exit() function upon termination of the edit session.──────────Value returned: This function does not return a value.══quote_regex() PELPurpose: Converts possible metacharacters to literals.──────────Syntax: str quote_regex(str s)──────────Description: The quote_regex() function creates a new string based on the one provided in the s argument. The new string is identical to the argument except that a backslash precedes each character that has special meaning in regular expressions. These characters, called metacharacters, are described in the "Regular Expressions" chapter of the User's Manual. The preceding backslash ensures that these characters will not be given special meaning. This function is useful when you wish to search for an ordinary string which is to used as part of a larger regular expression.──────────Value returned: The value returned by the quote_regex() function is the newly created string.══raise_anchor()Purpose: Remove the most recently placed selection marker.──────────Syntax: int raise_anchor()──────────Description: The raise_anchor() function removes the last bookmark placed by the drop_anchor() or toggle_anchor() function. This has the effect of changing the boundaries of the marked region. This function shares a last-in, first-out stack of bookmarks with the drop_anchor() function. The raise_anchor() function removes the most recently placed selection mark from this stack and disposes of it. As a result, the defined block becomes the text between the current cursor position and the preceded bookmark on the stack. If, after the most recently defined bookmark has been removed, there are no previous bookmarks remaining, there will be no marked region of text. If there is no bookmark on the stack when raise_anchor() is called, the function will fail.──────────Value returned: Upon successful completion, raise_anchor() returns a non-zero value (TRUE). If the function fails, a zero value (FALSE) is returned.══raise_window()Purpose: Promote a window to the top of the list.──────────Syntax: void raise_window([winid window])──────────Description: The raise_window() function promotes the window named by the window argument to the top of the window list. The window argument is a window id number assigned by the editor system when the window was created. If this argument is omitted, the current window is raised. Any other overlapping windows on the screen will appear overlaid by this window. As always, when the active window is changed, the buffer attached to the window made current is then the active buffer.──────────Value returned: No useful value is returned by the raise_window() function.══read_buffer()Purpose: read a portion of the buffer into a string.──────────Syntax: str read_buffer([int len])──────────Description: The read_buffer() function creates a string from the text in the current line of the current buffer. If the len argument is omitted the text from the cursor position to the end of the line is read. If the len argument is supplied, it specifies the number of characters to be read. Positive values for len read the characters at and following the cursor position while negative numbers read characters preceding the cursor. Under no conditions are characters beyond the beginning or the end of the current line read into the string. The end-of-line sequence will not be copied into the string.──────────Value returned: If the cursor is located beyond the last character of the line when this function is called an empty string is returned. Otherwise, the resulting string is returned.══read_file()Purpose: Read a file into the current position of current buffer.──────────Syntax: int read_file(str file)──────────Description: The read_file() function opens the file described by the file argument and reads the contents into the currently active buffer at the current cursor location. The file argument contains a filename and, optionally, a path element including drive specifier. If file contains no path element the default drive and directory are assumed. When read_file() is completed the cursor is positioned at the end of the text that was read. SPE treats this as a single operation. You may therefore obtain the condition existing before the call to read_file() with a single undo command.──────────Value returned: The value returned by read_file() on successful completion is the number of bytes read into the buffer.══read_file_key()Purpose: Enhanced function to insert file.──────────Syntax: void read_file_key()──────────Description: Like the read_file() function, read_file_key() prompts for a filename and then reads that file into the buffer at the current position. In addition, It provides some assistance in selecting the file for reading: It has a history mechanism that displays the names of files previously selected when up or down arrows are pressed. It also will display a list of files matching a specified pattern when [Tab] is pressed (rather than [Enter]). A file may then be selected from the list.──────────Value returned: No useful value is returned by this function.══read_window()Purpose: Read a string from a window location.──────────Syntax: str read_window(int chars [, winid win])──────────Description: The read_window() function reads a string from video memory at window coordinates specified by a special "cursor". This low- level function is for use in constructing menus, primarily by experienced users. The chars argument indicates the number of character to be read. The optional win argument determines from which window the string will be read. If the win argument is not specified the string is read from the current window. This function reads the string from the screen rather than a buffer. For this reason a buffer need not be attached to the window to use this function. The coordinates from which the string is read are determined by an imaginary cursor. This cursor is used only by the write_window() and read_window() functions. The location of this cursor is set by modifying the window's window_cursor_x and window_cursor_y variables. The cursor position is automatically positioned at the end of the string after a string has been read.──────────Value returned: The value returned by the read_window() is the string read from the window.──────────See also: set_text_region(), window_cursor_x,window_cursor_y══record()Purpose: Store keystrokes in a string for later replay.──────────Syntax: str record([int flag])──────────Description: The record() function is used to turn on and also to turn off the recording of keystrokes as they are entered from the keyboard. The flag argument is used to indicate whether recording is to be turned on or off. When flag is 1, recording is turned on. When flag is 0, recording is turned off. If this argument is omitted, recording will be toggled: if it is on, it will be turned off; if it is off, it will be turned on. If recording is explicitly turned on when it is already on, the recording process is re-initialized and previously recorded keystrokes are abandoned. Turning recording off when it is already off has no effect. There are a few key sequences that can't be recorded, such as [Ctrl][Break] and [Ctrl][Alt][Del]. The rule governing what can be recorded and what cannot is as follows: If it can't be detected with the getkey() function it can't be recorded. A table of the recognized key sequences is given in the "Console I/O" chapter of the Functions by Category manual.──────────Value returned: When record() turns recording off, a string is always returned. The string contains ASCII values corresponding to the keys that have been typed. Each keycode is represented by two character sequences. The string may be empty, if no valid keystrokes are typed. When recording is turned on, an empty string is returned.══redo()Purpose: Undoes the effects of a previous undo().──────────Syntax: int redo([int index])──────────Description: The redo() function restores the current buffer to a state prior to an undo() function call. If the index argument is not specified, redo() reverses the effects of the most recent undo(). The index argument is a buffer operation number. When specified, redo() restores the buffer to its condition when this operation number was the most recent edit. The current operation number may be obtained and recorded for later use by calling the undo_index() function. In order to be able to redo() an undo() there must be no intervening edit operations. This function is particularly useful when "undoing" a series of edits. If one or more desired edits are inadvertently undone, they may be "redone" through the use of this function. A series of undo() calls may be reversed by successive calls to the redo() function.──────────Value returned: The value returned by the redo() function is non-zero (TRUE) if the edit operation is successfully redone. A zero value (FALSE) is returned if there was nothing to redo or if an error prevented the operation from being redone.──────────See also: undo()══region_type()Purpose: Reports status of currently marked region.──────────Syntax: int region_type()──────────Description: The region_type() function identifies whether or not there is currently a marked region of text. If there is a marked region of text, region_type() indicates which of four types the currently marked block represents.──────────Value returned: The possible values returned by region_type(), along and their meanings are listed below: 0 No region is currently marked. 1 A region of sequential characters has been defined. (NON-INCLUSIVE) 2 A region of text within column boundaries has been defined. (INCLUSIVE) 3 A region of sequential lines has been defined. (INCLUSIVE) 4 A region of sequential characters has been defined. (INCLUSIVE) Marked regions, with the exception of type 1, are "inclusive." Inclusive means the character highlighted by the cursor is included in the block. Non-inclusive blocks do not include the character at the cursor.══rename()Purpose: Change the name of a file or series of files.──────────Syntax: int rename(str old, str new)──────────Description: The rename() function changes the names of files matching the file specification in the old argument to match the pattern indicated by new. The old and new arguments may not contain wildcard characters. If the new file specification contains a drive specifier, it must match that given in old.──────────Value returned: When successful, rename() returns a non- zero value. If an error occurs, a zero value is returned.──────────Compatibility: rename() differs from the ANSI C function of the same name in that return values are different.══repeat_key_action()Purpose: Repeats the key action that follows.──────────Syntax: void repeat_key_action()──────────Description: The repeat_key_action() function prompts the user for a number of repetitions and then waits for the user to press a key. It then repeats the action associated with that key the specified number of times. The action to be repeated may be anything from repeatedly inserting a character into the buffer to paging down a specified number of times.──────────Value returned: No useful value is returned by this function.══replace()Purpose: Unadorned text pattern replacement function.──────────Syntax: int replace(str pattern, str replacement, int flags)──────────Description: The replace() function examines the current buffer for one or more occurrences of text matching the pattern argument. The pattern may be a regular expression or a simple string to match, depending upon the value of the flags argument. The matching text is replaced with the contents of the replacement string. The direction of search and other searching parameters are also controlled by the flags argument. The position of the cursor at the end of the search portion of the operation may be controlled through regular expressions, but by default is placed at the beginning of the matching text. The values allowed for flags are those that may be represented by a single byte. Each bit of the flags byte sets a searching parameter. The search_flags variable is normally used as the flags argument if the search parameters currently in use are acceptable. A complete description of the meaning given to the bits of flag may be found under search_flags. The replacement operation is repeated as dictated by the variable search_count. If search_count is 1 or 0 the replacement is carried out once. If search_count is greater than 1 the operation is repeated that number of times or until it is unsuccessful. In any case, the value of search_count is reset to 0 upon completion.──────────Value returned: The value returned by replace() is the number of replacements made. If no matches are found, a zero value is returned.══replace_again() PELPurpose: Repeats a previous replace without further prompting.──────────Syntax: int replace_again()──────────Description: The replace_again() function continues a replace operation for the next occurrence of matching text. It uses the variables search_replacement, search_pattern and search_flags as parameters to the operation without prompting. These variables usually reflect the parameters of any previous replace operation but may be modified by user-written programs. This replace function does not restore the cursor to its original position after the replacement, but rather leaves the cursor at the position where the match occurred.──────────Value returned: The value returned by the replace_again() function is non-zero (TRUE) if a match was found. If not, a value of zero (FALSE) is returned.══replace_backward() PELPurpose: Prompts for parameters, replaces backward in buffer.──────────Syntax: int replace_backward([str pattern [, str replacement]])──────────Description: The replace_backward() function is designed to be assigned to a key. When no arguments are supplied or if the arguments are empty strings, it prompts the user for the search pattern and the replacement string. If there have been any previous search or replacement operations, the patterns used in those operations are presented to the user for editing. If an argument other than an empty string is supplied the user is not prompted for that argument. If both arguments are supplied and neither is an empty string, no prompting occurs. If only one argument is supplied, it is assumed to be the pattern argument. Whether or not arguments are supplied, parameter settings from the prior search or replace are used. If there were no such prior operations, the settings found in search_flags are used. This replace function restores the cursor to its original position after the replacement rather than leaving the cursor at the position where the match occurred. This function resets the SEARCH_FORWARD bit of the search_flags variable. Thus it always searches the buffer for matches beginning with the text preceding the cursor position.──────────Value returned: The value returned by the replace_backward() function is non-zero (TRUE) if a match was found. If not, a value of zero (FALSE) is returned.══replace_forward() PELPurpose: Prompts for parameters, replaces backward in buffer.──────────Syntax: int replace_forward([str pattern [, str replacement]])──────────Description: The replace_forward() function is designed to be assigned to a key. When no arguments are supplied or if the arguments are empty strings, it prompts the user for the search pattern and the replacement string. If there have been any previous search or replacement operations, the patterns used in those operations are presented to the user for editing. If an argument other than an empty string is supplied the user is not prompted for that argument. If both arguments are supplied and neither is an empty string, no prompting occurs. If only one argument is supplied, it is assumed to be the pattern argument. Whether or not arguments are supplied, parameter settings from the prior search or replace are used. If there were no such prior operations, the settings found in search_flags are used. This replace function restores the cursor to its original position after the replacement rather than leaving the cursor at the position where the match occurred. This function sets the SEARCH_FORWARD bit of the search_flags variable. Thus it always searches the buffer for matches beginning with the text following the cursor position.──────────Value returned: The value returned by the replace_forward() function is non-zero (TRUE) if a match was found. If not, a value of zero (FALSE) is returned.══replace_string_lengthPurpose: Indicates the length of text replacing the search pattern.──────────Type: int replace_string_length──────────Description: The replace_string_length variable contains the length of the replacement string resulting from the most recent replace operation. This value is primarily useful when regular expression searches result in strings of uncertain length. If you wish to manipulate the resulting text, the length of the resulting string may be necessary. This variable differs from the search_string_length variable in that search_string_length is the length of the matching string before replacement. The variable replace_string_length is the length after replacement.──────────See also: search_string_length══reset_keymap()Purpose: Redefines the current keymap to operate like another.──────────Syntax: int reset_keymap([keymapid keymap])──────────Description: The reset_keymap() function redefines the current keymap to be a copy of the keyboard definition described by the keymap argument. The keymap argument is the numeric id associated with a previously defined keyboard definition. If keymap is omitted, the keyboard is re- initialized to the assignments of the system default keyboard (factory_keymap). If keymap is supplied but does not represent a valid keyboard, this function will fail.──────────Value returned: The reset_keymap() function returns a non- zero (TRUE) value upon successful completion. If the function fails, a zero (FALSE) value is returned.══resize_all_windows()Purpose: Resize existing windows to fit screen.──────────Syntax: void resize_all_windows([int was_high, was_wide, is_high, is_wide])──────────Description: The resize_all_windows() changes the size of all normal windows to fit a screen of new screen size. In this case normal windows includes all windows that are not icons, full screen or system windows. Icons, however, are repositioned and the dialog window is resized. The was_high and was_wide arguments are the number of lines and number of columns the screen contained before resizing, respectively. Similarly, the is_high and is_wide arguments are the number of lines and columns the screen contains after resizing. Since this function cannot resize windows beyond the screen limits in effect at the time it is called, the order in which you change the screen size and call this function is significant. When changing from or to a screen size that is the same or larger in both dimensions (e.g., 25 line to 50 line or 43 line to 25 line), resize_all_windows() should be called when the screen is at its larger state. For example, it should be called before changing from 50 line mode to 25 line mode, but called after changing from 25 line mode to 43 lines. When changing from modes where one is not clearly larger than the other, such as 50 lines by 80 columns to 25 lines by 132 columns, it may be necessary to adjust some windows by hand.──────────Value returned: No useful value is returned by this function.══restore_position()Purpose: Move to a previously saved position in the buffer.──────────Syntax: int restore_position([int go_there])──────────Description: The restore_position() function "pops" the most recently saved buffer position from the position stack it shares with the save_position() function. The stack operates on a last-in, first-out basis. If the go_there argument represents a non-zero value the cursor moves to the saved position. If the go_there argument is omitted or is zero, the saved position is removed from the stack and not used.──────────Value returned: This function returns no useful value.──────────See also: save_position()══restore_window()Purpose: Returns a window to its normal size.──────────Syntax: void restore_window([winid window])──────────Description: The restore_window() function returns a window to its normal size regardless of its current state. If no window argument is specified, the current window is assumed. If the window is already at its normal size, the state is not changed. The normal state is one of four states a window may occupy: invisible, icon, normal or zoomed. When the window is zoomed, it takes up the entire screen. In the normal state, the window occupies the dimensions originally reflected by the window_height and window_width variables. When in the icon state, the window occupies a few columns of a single line, with a mnemonic displayed in the block. In the invisible state the window does not appear on the screen.──────────Value returned: No useful value is returned by the restore_window() function.══reverse() PELPurpose: Converts lower case to upper and upper to lower.──────────Syntax: void reverse()──────────Description: The reverse() function reverses the case of the selected portion of the buffer. Any character which was lower case is converted to upper and any upper case character becomes lower. If no selection mark has been defined the case of the character under the cursor is reversed. The VI emulation package uses this function to allow converting a specified number of characters.──────────Value returned: No useful value is returned by this function.══right()Purpose: Move cursor to the right on the line.──────────Syntax: int right([int positions])──────────Description: The right() function moves the cursor to the right by the number of positions specified by the positions argument. If the positions argument is omitted, a value of one is assumed. Depending on the value of the buffer_flags variable, positions are interpreted as either columns or characters. If movements into VIRTUAL SPACE are allowed, the positions argument is interpreted as columns. The right() function always moves the cursor to the right the number of characters indicated. It does not move the cursor to the following line. When movements into VIRTUAL SPACE are disallowed, positions means characters; excluding end-of-line sequences. The right() function then follows the text in the buffer. If the value of positions is greater than the number of columns or characters between the cursor and the end- of-line, the cursor is moved to the beginning of text in the following line. The cursor is then moved to the right any additional positions. Negative values for positions are allowed and result in the cursor moving in the opposite direction. In other words, calling right() with -3 as the argument is the as calling left() with 3 as the argument.──────────Value returned: The right() function returns the actual number of columns or characters traversed. This will be the same number as the positions argument, except when movements into VIRTUAL SPACE are disabled and there are too few characters between the cursor position and the end of the buffer to execute the move completely.──────────See also: next_char()══rindex()Purpose: Reports position of the last occurrence of a sub-string.──────────Syntax: int rindex(str s, str sub)──────────Description: The rindex() function searches the s string argument for the right-most occurrence of the sub-string in the sub argument. The function then reports the position in the s string at which the sub-string occurred.──────────Value returned: The value returned by the rindex() function is the ordinal position at which the sub- string begins. If no matches were found, or if one of the arguments was not a valid string, the function returns a zero value.══RLENGTHPurpose: Stores length of a string match resulting from match()──────────Type: int RLENGTH──────────Description: After each use of the match() function the variable RLENGTH is set to the length of the text matching the pattern specified in match(). If there was no match found, the variable is set to zero.══rmdir()Purpose: Delete a file directory.──────────Syntax: int rmdir(str dir)──────────Description: The rmdir() function removes the directory indicated by the dir argument. The dir argument may contain a path element, including a drive specifier. If no path element is supplied, the current working directory is assumed to be the parent directory of the directory to be deleted. To succeed, the directory indicated by dir must not contain any files and must not be the current working directory. Attempts to delete the root directory will also fail.──────────Value returned: If the directory is successfully removed, the rmdir() returns a non-zero value. If it fails, a zero value is returned. Consult the errno to determine the nature of the failure.──────────Compatibility: This function is similar to the like-named function supported by major C compilers, except as to return codes.══routines()Purpose: Makes menu of subroutines found in the current buffer.──────────Syntax: void routines()──────────Description: The routines() function scans the current buffer for subroutines (functions) and places them in a menu-like list. The arrow keys or mouse may then be used to select a subroutine of interest. The user may then move directly to that subroutine by pressing [Enter]. * This function operates on .PEL and .C files only.──────────Value returned:══RSTARTPurpose: Stores the position of the match resulting from match()──────────Type: int RSTART──────────Description: After each use of the match() function the variable RSTART is set to the starting position of the text matching the pattern specified in match(). For example, if the match begins with the fifth character the value of RSTART will be 5. If there was no match found, the variable is set to zero.══save_position()Purpose: Note the current buffer position in special stack.──────────Syntax: int save_position()──────────Description: The save_position() function stores the current position within the buffer on the position stack it shares with the restore_position() function. The stack operates on a last-in, first-out basis. This differs from the drop_anchor() function primarily in that no block of text is highlighted.──────────Value returned: No useful value is returned by this function.══save_state PELPurpose: Tells whether the editor state should be saved on exit.──────────Type: int save_state──────────Description: The save_state variable dictates whether or not SPE will save certain information about its status in the configuration file when exiting. This information may then be used later to restore the state which existed at exit. The file in which this information is saved is named SAGEEDIT.CFG. It resides in the SPE Home Directory. Among the status information that can be stored in the configuration file are details about each buffer that has been defined and the search and replace patterns. The buffer information which can be stored in the file includes: the buffer name, the filename associated with the buffer, the buffer flags, the current line and column position within the buffer and the tab settings. By default, save_state is set to a zero (FALSE) value. When this variable is zero, status information is not saved on exit and any status information previously stored is not used. If no file is specified for editing when you invoke SPE and save_state is TRUE, the editor will define each of the buffers described in the configuration file. In addition, state values stored in the configuration file are assigned to the appropriate SPE variables. The result is a state very similar to the one which existed when you last exited SPE. If a file to edit is specified on the command line the status information is not used regardless of the condition of the save_state variable.══scroll_context_bottomPurpose: Scrolling margin honored by cursor at screen bottom.──────────Type: int scroll_context_bottom──────────Description: Each window has a scroll_context_bottom variable associated with it. The value stored in scroll_context_bottom is used to determine when to scroll the contents of the edit window upward. The editor will keep at least this number of lines between the cursor and the bottom border of the window. When actions would otherwise place the cursor less than the number of lines indicated by scroll_context_bottom from the border, the window is scrolled to compensate. This is used to provide a definable amount of context around the area where text modifications are taking place. The scroll_context_bottom variable takes its initial value from the default_scroll_context_bottom at the time the window is created. Assigning a value less than zero to this variable is treated the same as zero.──────────See also: scroll_context_left,scroll_context_right, scroll_context_top.══scroll_context_leftPurpose: Scrolling margin honored by cursor at screen left.──────────Type: int scroll_context_left──────────Description: Each window has a scroll_context_left variable associated with it. The value stored in scroll_context_left is used to determine when to scroll the contents of the edit window to the right. The editor will attempt to keep at least this number of columns between the cursor and the left border of the window. When actions would otherwise place the cursor less than the number of columns indicated by scroll_context_left from the border, the window is scrolled to compensate. The exception to this action is when the text is already scrolled all the way to the right. In this case, the cursor may be moved to the edge of the window. This is used to provide a definable amount of context around the area where text modifications are taking place. The scroll_context_left variable takes its initial value from the default_scroll_context_left at the time the window is created. Assigning a value less than zero to this variable is treated the same as zero.──────────See also: scroll_context_bottom,scroll_context_right, scroll_context_top══scroll_context_rightPurpose: Scrolling margin honored by cursor at screen right.──────────Type: int scroll_context_right──────────Description: Each window has a scroll_context_right variable associated with it. The value stored in scroll_context_right is used to determine when to scroll the contents of the edit window to the left. The editor will keep at least this number of columns between the cursor and the right border of the window. When actions would otherwise place the cursor less than the number of columns indicated by scroll_context_right from the border, the window is scrolled to compensate. This is used to provide a definable amount of context around the area where text modifications are taking place. The scroll_context_right variable takes its initial value from the default_scroll_context_right at the time the window is created. Assigning a value less than zero to this variable is treated the same as zero.──────────See also: scroll_context_left,scroll_context_bottom, scroll_context_top══scroll_context_topPurpose: Scrolling margin honored by cursor at screen top.──────────Type: int scroll_context_top──────────Description: Each window has a scroll_context_top variable associated with it. The value stored in scroll_context_top is used to determine when to scroll the contents of the edit window down. The editor will keep at least this number of lines between the cursor and the top border of the window. When actions would otherwise place the cursor less than the number of columns indicated by scroll_context_top from the border, the window is scrolled to compensate. The exception to this action is when the text is already scrolled to the top of the buffer. In this case, the cursor may be moved to the top edge of the window. This variable is used to provide a defined amount of context around the area where text modifications are taking place. The scroll_context_top variable takes its initial value from the default_scroll_context_top at the time the window is created. Assigning a value less than zero to this variable is treated the same as zero.──────────See also: scroll_context_left,scroll_context_bottom, scroll_context_right.══scroll_down_1()Purpose: Scroll one line toward the end of the buffer.──────────Syntax: void scroll_down_1()──────────Description: The scroll_down_1() function scrolls the text in the current window toward the end of the buffer by one line. This has the effect of making the text in the window appear to move up.──────────Value returned: No useful value is returned by this function.══scroll_down_half()Purpose: Scrolls toward end of buffer by half a window.──────────Syntax: void scroll_down_half()──────────Description: The scroll_down_half() function scrolls the text in the current window toward the end of the buffer by a number of lines equivalent to half the window height. This has the effect of making the text in the window appear to move up.──────────Value returned: No useful value is returned by this function.══scroll_horizontal()Purpose: Move text right or left while cursor maintains position.──────────Syntax: int scroll_horizontal([int offset [, int pan]])──────────Description: The scroll_horizontal() function scrolls the text in the current window by the number of columns indicated by the offset argument. Positive values for offset allow viewing text off-window to the right while negative values make text toward the beginning of the line visible. If the offset argument is omitted the text is scrolled one column right. The cursor may either scroll or pan as a result of the scroll_horizontal() function. When panning, the cursor attempts to maintain its position relative the window regardless of the motion of text. When scrolling, it attempts to maintain its position within the buffer. You may determine whether this function causes the cursor to scroll or pan by supplying the pan argument. When pan is zero the cursor will scroll. Other values for pan will cause the cursor to pan. If you do not supply the pan argument, cursor action is determined by the condition of the scroll_means_pan variable. The maximum number of columns text may be scrolled to the right is equal to the number of visible columns in the current line. The maximum number of columns text may be scrolled to the left is equal to the number of off-window columns to the left of the window.──────────Value returned: scroll_horizontal() returns the number of columns scrolled (negative or positive). This is normally the same value as the offset argument, unless offset was greater than allowable limits. In that case, the maximum number of columns to scroll is returned.──────────See also: scroll_means_pan, scroll_vertical(),buffer_flags══scroll_left_1()Purpose: Scroll toward start of line by one column.──────────Syntax: void scroll_left_1()──────────Description: The scroll_left_1() function scrolls the text in the current window toward the beginning of the line by one column. This has the effect of making the text in the window appear to move to the right.──────────Value returned: No useful value is returned by this function.══scroll_means_panPurpose: Indicates whether movements apply to cursor or text.──────────Type: int scroll_means_pan──────────Description: Each window has a scroll_means_pan variable associated with it. When this variable is set to zero, cursor and other operations generally have the effect of moving the cursor in relationship to the window. When scroll_means_pan is other than zero, the position of the cursor within the window is preserved. The text in the window moves to compensate. Typing with the editor in this mode may remind you of how the typing ball on many typewriters stays in one place while the carriage moves by. Scrolling text up and down, on the other hand, may remind you of an airplane simulator. Another way of looking at it is as follows: When scroll_means_pan is 0, SPE attempts to preserve the cursor position relative to its location in the buffer. When scroll_means_pan is 1, SPE preserves the cursor position relative to the window. The scroll_means_pan variable takes its initial value from the default_scroll_means_pan at the time the window is created. The Scroll Lock key is used by the higher level scroll functions to complement the value of scroll_means_pan. This has the effect of reversing the sense of scroll_means_pan. When Scroll Lock is toggled on, functions that use scroll_means_pan will complement its value before using it. When Scroll Lock is off the uncomplemented value is used.──────────See also: scroll_horizontal(),scroll_vertical(), page_up(), page_down()══scroll_or_pan()Purpose: Tells condition of Scroll Lock key.──────────Syntax: int scroll_or_pan()──────────Description: The scroll_or_pan() function reports the condition of the Scroll Lock key. This value may be used for assignment to the scroll_means_pan variable.──────────Value returned: The value returned by the scroll_or_pan() function is zero (FALSE) if the Scroll Lock key is toggled off. If the Scroll Lock key is toggled on the function returns TRUE (1).══scroll_right_1()Purpose: Scroll toward end of line by one column.──────────Syntax: void scroll_right_1()──────────Description: The scroll_right_1() function scrolls the text in the current window toward the end of current line by one column. This has the effect of making the text in the window appear to move to the left.──────────Value returned: No useful value is returned by this function.══scroll_unit_horizontalPurpose: Stores number of columns in horizontal scrolling unit.──────────Type: int scroll_unit_horizontal──────────Description: Each window has a scroll_unit_horizontal variable associated with it. The scroll_unit_horizontal variable defines the number of columns in the normal scrolling unit for horizontal movement. This variable comes into play when cursor motion causes the contents of a window to be scrolled horizontally. The default value for this variable is usually 1. This means that when cursor movement causes the text in a window is scrolled to the left or right, one off- window column of text appears in the window. This is the method of operation most users will find familiar. When higher values are assigned to scroll_unit_horizontal, more than one off- window column of text becomes visible during a single scroll. This has the effect of reducing the number of times the text needs to be scrolled. As a result, continued cursor movements may often be executed more quickly. The size of the scrolling unit does not change the way the cursor moves through the text. In the following example, imagine that the scroll_unit_horizontal variable is set to 5. (To keep things simple we will also assume that scroll_context_right is set to its default value, zero.) The cursor is positioned at the right edge of the window on the letter "G", which happen to be the first letter of the word "GetShape". When the cursor-right key is pressed, five off-window columns of text are scrolled into the window. Now, only the final "pe" of "GetShape" is not visible. The cursor, however, is no longer at the right edge of the window. The cursor has moved from the first character of "GetShape" to the second. This leaves four columns between the cursor and the window edge. The scroll_unit_horizontal variable takes its initial value from the default_scroll_unit_horizontal at the time the window is created. Values of less than 1 are interpreted as 1. Values greater than the window width are interpreted as the width of the window.──────────See also: scroll_unit_vertical.══scroll_unit_verticalPurpose: Stores the number of lines in vertical scrolling unit.──────────Type: int scroll_unit_vertical──────────Description: Each window has a scroll_unit_vertical variable associated with it. the scroll_unit_vertical variable defines the number of lines in the normal scrolling unit for vertical movement. This variable comes into play when cursor motion causes the contents of a window to be scrolled vertically. The default value for this variable is usually 1. This means that when, as the result of cursor movement the text in a window is scrolled up or down, one off- window line of text appears in the window. This is the method of operation most users will find familiar. When higher values are assigned to scroll_unit_vertical, more than one off- window line of text becomes visible during a single scroll. This has the effect of reducing the number of times the text needs to be scrolled. As a result, continuing cursor movements may often be executed more quickly. The size of the scrolling unit does not change the way the cursor moves through the text. Though several new lines are made to appear on the screen at once, the up and down cursor keys will always move the cursor to the adjacent line of text. The scroll_unit_vertical variable takes its initial value from the default_scroll_unit_vertical at the time the window is created. Values of less than 1 are interpreted as 1. Values greater than the window height are interpreted as the height of the window.──────────See also: scroll_unit_horizontal.══scroll_up_1()Purpose: Scrolls toward start of buffer by one line.──────────Syntax: void scroll_up_1()──────────Description: The scroll_up_1() function scrolls the text in the current window toward the beginning of the buffer by one line. This has the effect of making the text in the window appear to move down.──────────Value returned: No useful value is returned by this function.══scroll_up_half()Purpose: Scrolls toward start of buffer by half a window.──────────Syntax: void scroll_up_half()──────────Description: The scroll_up_half() function scrolls the text in the current window toward the beginning of the buffer by a number of lines equivalent to half the window height. This has the effect of making the text in the window appear to move down.──────────Value returned: No useful value is returned by this function.══scroll_vertical()Purpose: Move text up or down while cursor maintains position.──────────Syntax: int scroll_vertical([int offset [, int pan]])──────────Description: The scroll_vertical() function scrolls the text in the current window by the number of lines indicated in the offset argument. Positive values for offset scroll text down while negative values scroll toward the beginning of the buffer. If the offset argument is omitted the text is scrolled one line down. If there are less than offset lines between the cursor position and the applicable buffer limit, the cursor is moved to the first or last line of the buffer. The cursor may either scroll or pan as a result of the scroll_vertical() function. When panning, the cursor attempts to maintain its position relative the window regardless of the motion of text. When scrolling, it attempts to maintain its position within the buffer. You may dictate whether this function causes the cursor to scroll or pan by supplying the pan argument. When pan is zero the cursor will scroll. Other values for pan will cause the cursor to pan. If you do not supply the pan argument, cursor action is determined by the condition of the scroll_means_pan variable.──────────Value returned: scroll_vertical() returns the number of lines scrolled (negative or positive). This is normally the same value as the offset argument, unless offset was greater than allowable limits. In that case, the maximum number of lines to scroll is returned.══scroll_window_bottom() PELPurpose: Scroll cursor line to position relative to window bottom──────────Syntax: void scroll_window_bottom([int offset])──────────Description: The scroll_window_bottom() function scrolls the line containing the cursor to a position offset lines from the bottom of the window. If the offset argument is omitted or is a value less than 0, the cursor line becomes the bottom line in the window. The operation of this function is affected by the state of the scroll_means_pan variable and the scroll lock key. Refer to the description of the variable scroll_means_pan for an explanation.──────────Value returned: No useful value is returned by this function.══scroll_window_middle() PELPurpose: Scroll cursor line to position relative to window center.──────────Syntax: void scroll_window_middle([int offset])──────────Description: The scroll_window_middle() function scrolls the line containing the cursor to a position offset lines from the center of the window. Positive values for offset place the line below the center of the window, while negative values place it above the center. If the offset argument is omitted or is 0, the cursor line becomes the center line of the window. The operation of this function is affected by the state of the scroll_means_pan variable and the scroll lock key. Refer to the description of the variable scroll_means_pan for an explanation.──────────Value returned: No useful value is returned by this function.══scroll_window_top() PELPurpose: Scroll cursor line to position relative window top──────────Syntax: void scroll_window_top([int offset])──────────Description: The scroll_window_top() function scrolls the line containing the cursor to a position offset lines from the top of the window. If the offset argument is omitted or is a value less than 0, the cursor line becomes the top line in the window. The operation of this function is affected by the state of the scroll_means_pan variable and the scroll lock key. Refer to the description of the variable scroll_means_pan for an explanation.──────────Value returned: No useful value is returned by this function.══search()Purpose: Unadorned text pattern matching function.──────────Syntax: int search(str pattern, int flags)──────────Description: The search() function examines the current buffer for one or more occurrences of text matching the pattern argument. The pattern may be a regular expression or a simple string to match, depending upon the condition of the flags variable. The direction of search and other searching parameters are also controlled by the flags argument. The position of the cursor at the end of the search may be controlled through regular expressions, but by default is placed at the beginning of the matching text. The values allowed for flags are those that may be represented by a single byte. Each bit of the flags byte sets a searching parameter. The search_flags variable is normally used as the flags argument if the search parameters currently in use are acceptable. A complete description of the meaning given to the bits of flag may be found under search_flags. The search operation is repeated as dictated by the variable search_count. If search_count is 1 or 0 the search is carried out once. If search_count is greater than 1 the operation is repeated that number of times or until it is unsuccessful. In any case, the value of search_count is reset to 0 upon completion.──────────Value returned: The value returned by search() is the number of matches found. This will normally be one. If no matches are found, a zero value is returned.══search_again() PELPurpose: Repeats a previous search without further prompting.──────────Syntax: int search_again()──────────Description: The search_again() function continues a search for the next occurrence of matching text. It uses the variables search_pattern and search_flags as parameters to the operation without prompting. These variables usually reflect the parameters of any previous search operation but may be modified by user-written programs.──────────Value returned: The value returned by the search_again() function is non-zero (TRUE) if a match was found. If not, a value of zero (FALSE) is returned.══search_backward() PELPurpose: Prompts for parameters, searches backward in buffer.──────────Syntax: int search_backward([str pattern])──────────Description: The search_backward() function is designed to be assigned to a key. It prompts the user for the search string when the pattern argument is not specified. If there have been any previous searches, the search string used in the preceding search is presented to the user for editing. If the pattern string is supplied no prompting occurs. In either case, the function then searches the buffer for matches beginning with the text preceding the cursor position. The search parameter settings from the prior search are also used. If there was no prior search, the settings found in search_flags are used. This function resets the SEARCH_FORWARD bit of the search_flags variable.──────────Value returned: The value returned by the search_backward() function is non-zero (TRUE) if a match was found. If not, a value of zero (FALSE) is returned.══search_countPurpose: Defines how many repetitions of a search are desired.──────────Type: int search_count──────────Description: The search_count variable sets the maximum number of search or replace operations to be performed. The current search or replace operation is repeated until the number of repetitions specified by search_count have been performed or until no further matches are found. The default value for this variable is zero. When a search is executed with search_count set to zero, the search will be executed for one repetition. Most search and replace functions decrement this variable as search and replace operations are performed. This continues until search_count is zero or the search/replace is completed. The functions then reset this variable to zero.══search_cursor_offsetPurpose: Stores distance from cursor to beginning of match.──────────Type: int search_cursor_offset──────────Description: The search_cursor_offset variable provides information about where the cursor was positioned following a regular expressions search. This variable contains the number of characters between the cursor position and the beginning of matching text. This variable will be set to zero unless the most recent search or replace operation was a search using regular expressions. In addition, a cursor location must have been specified in the pattern. This variable is most useful when you are building a function to automate some editing operation. It enables you to locate the beginning of matching text even if you specified that SPE place the cursor after a matching group of text. See the "Regular Expressions" chapter of the User's Manual for a description of regular expressions and specifying cursor location.══search_flags PELPurpose: Dictates many of the standard searching parameters.──────────Type: int search_flags──────────Description: The first seven bits of the search_flags variable are used by SPE's standard search and replace function to determine various searching parameters. A number of descriptive identifiers have been defined in the standard function files. These identifiers and their numeric values are given below: SEARCH_MAXIMAL_MATCH 0x01 (bit 0) 1 SEARCH_BLOCK 0x02 (bit 1) 2 SEARCH_FORWARD 0x04 (bit 2) 4 SEARCH_WRAPS 0x08 (bit 3) 8 SEARCH_REGEX 0x10 (bit 4) 16 SEARCH_IGNORE_CASE 0x20 (bit 5) 32 SEARCH_ADVANCE 0x40 (bit 6) 64 SEARCH_ONCE_PER_LINE 0x2000 (bit 14) 8192 When the bit corresponding to each of these parameters is set ( 1 ), that parameter is turned on. Otherwise, the parameter is turned off. The SEARCH_MAXIMAL_MATCH bit determines whether SPE will attempt to match the smallest string matching a given pattern or the largest. This bit is only used if SEARCH_REGEX has been enabled. Under many conditions, it will not matter whether the maximal or minimal match is used; in either case the same string will be matched. However, if part or all of the pattern may occur nested within or contiguous to text which also matches the pattern, this parameter will effect the outcome of the search. The SEARCH_BLOCK bit determines whether searches are limited to the marked block or region, when one is defined. When the SEARCH_FORWARD bit is set, any search or replace operations performed will search from the current cursor position toward the end of the buffer. Otherwise, the search proceeds toward the beginning of the buffer. When the SEARCH_WRAPS bit is set, search and replace operations are applied to the entire buffer regardless of the location of the cursor. This search is carried out by first searching from the cursor position to the buffer extremity indicated by the SEARCH_FORWARD bit. The search then continues from the opposite buffer extremity to the cursor position. For example, a search from the cursor position to the end of the buffer is continued from the beginning of the buffer to the cursor position. As with all searches, the search may be terminated earlier if the search is not global and a match is found prior to searching the entire buffer. When this bit is zero the search continues only until the buffer extremity is reached. When the SEARCH_REGEX bit is set, the string supplied to a search or replace function is considered a regular expression. Regular expressions are described in detail in the User's Manual, in the chapter "Regular Expressions". When this variable is set to zero, the search pattern is treated as a simple string. The SEARCH_IGNORE_CASE bit determines whether search and replace operation will make a distinction between upper and lower case characters. If the bit is zero, the characters of text must have the same case as the supplied search pattern in order to be considered a match. Otherwise, character case is not considered when determining if matching text has been found. The SEARCH_ADVANCE tells the search function that a match was previously found. This enables the function to avoid matching the same text again. When this bit is set, the search begins one character beyond the cursor in the direction of search. When set, the SEARCH_ONCE_PER_LINE bit will cause global replacement operations to be limited to one replacement per line. The default value for this variable is 23, which sets maximal match, search block, search forward and use of regular expressions. Keep in mind, however, that various emulations may alter this setting.══search_forward() PELPurpose: Prompts for parameters and searches forward in buffer.──────────Syntax: int search_forward([str pattern])──────────Description: The search_forward() function is designed to be assigned to a key. It prompts the user for the search string when the pattern argument is not specified. If there have been any previous searches, the search string used in the preceding search is presented to the user for editing. If the pattern string is supplied no prompting occurs. In either case, the function then searches the buffer for matches beginning with the text following the cursor position. The search parameter settings from the prior search are also used. If there was no prior search, the settings found in search_flags ere used. This function sets the SEARCH_FORWARD bit of the search_flags variable.──────────Value returned: The value returned by the search_forward() function is non-zero (TRUE) if a match was found. If not, a value of zero (FALSE) is returned.══search_i() PELPurpose: Searches for matching text as each character is typed.──────────Syntax: void search_i()──────────Description: The search_i() function performs an incremental search in the current buffer. In this case, the term incremental means that the search is performed as each character of the search string is typed in interactively. This ensures that the minimum number of keystrokes are typed to obtain the desired match. This type of search will be familiar to users of the EMACS editor. For others, a simple example illustrates the use of this function. You have a file containing the following words: fast after ftime With the cursor at the beginning of the file, you invoke the search_i() function. The function prompts you for the search string. To search for the word "ftime" you would begin by typing the letter "f". Without waiting for further input, the function begins searching for this letter. The cursor immediately moves to the first letter of the word "fast". As you type the second letter, "t", the cursor moves to the first occurrence of the letters "ft" which is in the word "after". As soon as you type the third letter, "i", the cursor moves to the beginning of the word "ftime". Since this word is the subject of your search, no further typing is required. You then press the escape key to terminate search_i().──────────Value returned: No useful value is returned by this function.══search_pattern PELPurpose: Stores the matching pattern used during a search.──────────Type: str search_pattern──────────Description: The search_pattern variable contains the pattern used during directional search and replace functions for matching. The directional search and replace functions are as follows: search_forward() search_backward() replace_forward() replace_backward() If there have been any previous search/replace operations using these functions, the search_pattern string will contain the pattern used in the last of these operations. This variable is not modified by the functions search() and replace(). This pattern may be either a regular expression or an ordinary string. The initial value for this variable is an empty string.══search_replacement PELPurpose: Stores the replacement text used by replace operations.──────────Type: str search_replacement──────────Description: The search_replacement variable contains the text which is intended to replace the text matching the pattern of a directional replace functions for matching. The directional replace functions are as follows: replace_forward() replace_backward() If there have been any previous replace operations using these functions, the search_replacement string will contain the pattern used in the last of these operations. This variable is not modified by the function replace(). The initial value for this variable is an empty string.══search_string_lengthPurpose: Indicates the length of text matching the search pattern.──────────Type: int search_string_length──────────Description: The search_string_length variable contains the length of the string matching the most recent search/replace operation. This value is primarily useful in writing functions that wish to manipulate the text matching a regular expression. If the last search/replace operation was not successful, this variable will be set to zero. This variable differs from the replace_string_length variable in that replace_string_length is the length of the string resulting from a replacement. The variable search_string_length is the length before replacement.──────────See also: replace_string_length══set_column_mark()Purpose: Begins a column selection at the current position.──────────Syntax: void set_column_mark()──────────Description: The set_column_mark() function begins the selection of a region of text within column boundaries. Column marking is region type 2. See the description of the region_type() function for a discussion of the region types available.──────────Value returned: No useful value is returned by this function.══set_exclusive_mark()Purpose: Begins an exclusive selection at the current position.──────────Syntax: void set_exclusive_mark()──────────Description: The set_exclusive_mark() function begins the selection of a region of sequential characters which excludes the character at the cursor. Exclusive marking is region type 1. See the description of the region_type() function for a discussion of the region types available.──────────Value returned: No useful value is returned by this function.══set_inclusive_mark()Purpose: Begins an inclusive selection at the current position.──────────Syntax: void set_inclusive_mark()──────────Description: The set_inclusive_mark() function begins the selection of a region of sequential characters that includes the character at the cursor. Inclusive marking is region type 4. See the description of the region_type() function for a discussion of the region types available.──────────Value returned: No useful value is returned by this function.══set_line_mark()Purpose: Begins a line selection at the current position.──────────Syntax: void set_line_mark()──────────Description: The set_line_mark() function begins the selection of a region of sequential lines. This is region type 3. See the description of the region_type() function for a discussion of the region types available.──────────Value returned: No useful value is returned by this function.══set_flag_bits() PELPurpose: Modify a bit or bits in a flag variable.──────────Syntax: int set_flag_bits(int flag, int mask, int value)──────────Description: The set_flag_bits() function simplifies the task of changing some bits of a flag variable while leaving others unchanged. Flag variables include buffer_flags, window_flags and their corresponding default_... variables. In addition, the search_flags variable falls in this category. The flag argument is the flag variable or value you wish to modify. The mask argument indicates which bits are to be modified and which may be preserved. The value argument contains the new value for the bits to be changed. The bits of mask that are SET ( 1 ) are those that are allowed to change. The bits of mask that are RESET ( 0 ) will be "masked off" and will not change. The mask and value arguments are normally descriptive labels corresponding to the mask and value desired. These labels may be obtained from the description of the variable you are modifying.──────────Value returned: The value returned by the set_flag_bits() function is the new value of the flag variable. Since the flag argument itself is not modified, this value must be assigned to the flag variable in order to change its value.──────────Example: window_flags=set_flag_bits(window_flags,WIN DOW_CHARS,WINDOW_HEX)══set_text_region()Purpose: Sets a text I/O region within a window.──────────Syntax: void set_text_region(int x, y, wide, high [, winid win])──────────Description: The set_text_region() function restricts window input/output to the region defined by its arguments. Ordinarily, the text I/O region for a window is defined by the borders and line numbers, if any. The room left inside the window is by default the I/O region. The size of this region is described by the variables window_text_x0, window_text_y0, window_text_height and window_text_width. This function allows the I/O region to be reduced further. The restricted I/O region only affects the window for which it is defined. The appearance of buffer text and reading or writing text in the window is confined to the I/O region. This is primarily useful in creating menus and other low- level tasks usually confined to advanced users. The x and y arguments to this function are column and line offsets from the upper left corner of the window. These two arguments indicate where the I/O region begins. The wide and high arguments define the number of columns and lines that the I/O region will occupy. The optional win argument may be used to specify a window other than the current window in which to restrict output. When a restricted I/O region has been defined in a window, resizing the window will cause the I/O region to return to the default.──────────Value returned: No useful value is returned by this function.──────────See also: highlight_window(), window_cursor_x,window_cursor_y══shiftl()Purpose: Shifts the bits of a number to the left.──────────Syntax: int shiftl(int num, int count)──────────Description: The shiftl() function derives a new value from the num argument by shifting its bits to the left. The number of positions the bits of num are shifted is indicated by the count argument. Bits that are shifted beyond the most significant position, bit 31, are lost.──────────Value returned: The value returned by shiftl() is the new value derived by shifting the bits of the num argument.══shiftr()Purpose: Shifts the bits of a number to the right.──────────Syntax: int shiftr(int num, int count)──────────Description: The shiftr() function derives a new value from the num argument by shifting its bits to the right. The number of positions the bits of num are shifted is indicated by the count argument. Bits that are shifted beyond the least significant position, bit 0, are lost.──────────Value returned: The value returned by shiftr() is the new value derived by shifting the bits of the num argument.══skip_whitespace() PELPurpose: Move cursor to beginning of text on current line.──────────Syntax: void skip_whitespace()──────────Description: The skip_whitespace() function moves the cursor to the first character on the current line that is not a whitespace character (space or tab). The function is not affected by the position of the cursor within the line prior to invoking skip_whitespace(). If the line contains only whitespace the cursor moves to the end of the line.──────────Value returned: No useful value is returned by this function.══smaller_window()Purpose: Changes current window to next smaller state.──────────Syntax: void smaller_window()──────────Description: The smaller_window() function reduces current window to normal size if it is full-screen, or to icon if normal sized. The function does nothing if the window is already an icon.──────────Value returned: No useful value is returned by this function.══source_file_name()Purpose: Tells what PEL file contains named function.──────────Syntax: str source_file_name(funcid func)──────────Description: The source_file_name() function reports in what PEL source file a function was defined when the SPE function library was last defined. The subject function is indicated by the func argument. This argument is a numeric function id, such as that obtained from function_id().──────────Value returned: This function returns a string containing the name of the PEL source file. If the function id specified is not known, an empty string is returned.══split()Purpose: Create an array from a string.──────────Syntax: int split(str st, array arr [, str fs])──────────Description: The split() function makes an AWK array by breaking up the st argument into fields. Each of these fields then becomes an element of the array arr. Each element of the array is sequentially subscripted with numeric strings. The fs argument specifies a field separator, which character or characters determines where one field ends and the next begins. If the argument is omitted, the value of the FS variable will be used as a separator. By default, FS is a space. EXAMPLE split("11:53:45",timeArr,":") In the resulting array, timeArr[1] == "11" timeArr[2] == "53" timeArr[3] == "45"──────────Value returned: The value returned by split() is the number of elements added to the array.══split_window_horizontal()Purpose: Split the current window horizontally.──────────Syntax: void split_window_horizontal([int high])──────────Description: The split_window_horizontal() function divides the current window horizontally into two windows. The high argument specifies the number of lines to be reserved for the current window. The remainder of the lines currently allocated to the window will be given to the new window. If the high argument is omitted, this function splits the current window in half.──────────Value returned: No useful value is returned by this function.══split_window_vertical()Purpose: Split the current window vertically.──────────Syntax: void split_window_vertical([int wide])──────────Description: The split_window_vertical() function divides the current window vertically into two windows. The wide argument specifies the number of columns to be reserved for the current window. The remainder currently allocated to the window will be given to the new window. If the wide argument is omitted, this function splits the current window in half.──────────Value returned: No useful value is returned by this function.══sprintf()Purpose: Creates a formatted string.──────────Syntax: str sprintf(str fmt [, any args,...])──────────Description: The sprintf() function creates a string, formatted as indicated by the fmt and args arguments. The fmt string argument may contain both text to be printed literally and format control characters. Format control characters specify how the args arguments are to be formatted and included in the output string. These format control characters are described under the fprintf() function.──────────Value returned: The sprintf() function returns the newly created string on successful completion. Upon failure, normally due to incorrectly formed arguments, the function returns an empty string.══startup() PELPurpose: Controls editor initialization process.──────────Syntax: void startup()──────────Description: The startup() function performs a number of tasks associated with initialization of the editor. Among these tasks are: reading and processing the configuration file, performing "local" setup, interpreting the command line and assigning an initial emulation mode (not necessarily in that order). This is done primarily by calling other initialization functions described elsewhere in this manual: process_command_line() and local_setup(). The startup() function is found in the supplied source file STARTUP.PEL.──────────Value returned: No useful value is returned by this function.══stdauxPurpose: Provides access to standard auxiliary device.──────────Type: fileid stdaux──────────Description: The file handle stdaux allows access to the DOS standard auxiliary device. Initially stdaux is COM1, however, it may be redirected. Redirecting or even closing stdaux will not effect the general operation of the editor.══stderrPurpose: Provides access to standard error device.──────────Type: fileid stderr──────────Description: The file handle stderr allows access to the DOS standard error device. Initially stderr is the monitor, however, it may be redirected. Redirecting or even closing stderr will not effect the general operation of the editor.══stdinPurpose: Provides access to standard input device.──────────Type: fileid stdin──────────Description: The file handle stdin allows access to the DOS standard input device. Initially stdin is the keyboard, however, it may be redirected. Redirecting or even closing stdin will not effect the general operation of the editor.══stdoutPurpose: Provides access to standard output device.──────────Type: fileid stdout──────────Description: The file handle stdout allows access to the DOS standard output device. Initially stdout is the monitor, however, it may be redirected. Redirecting or even closing stdout will not effect the general operation of the editor.══stdprnPurpose: Provides access to standard line printer.──────────Type: fileid stdprn──────────Description: The file handle stdprn allows access to the DOS standard printer device. Initially stdprn is LPT1, however, it may be redirected. Redirecting or even closing stdprn will not effect the general operation of the editor.══strmax()Purpose: Returns the string with the highest lexical value.──────────Syntax: str strmax(str s1 [, str s2 ...])──────────Description: The strmax() function creates a new string that is a copy of the argument string having the greatest lexical value. This function is useful primarily in sorting. The following examples will clarify: strmax("cat","dog") returns "dog". strmax("xxxx","XXXX") returns "xxxx". strmax("20","100") returns "20". strmax("AAA","AAAA") returns "AAAA".──────────Value returned: Upon successful completion, strmax() returns the new string.══strmin()Purpose: Returns the string with the lowest lexical value.──────────Syntax: str strmin(str s1 [, str s2 ...])──────────Description: The strmin() function creates a new string that is a copy of the argument string having the lowest lexical value. This function is primarily useful in sorting. For examples see the strmax() function above. In each case strmin() would return the opposite argument to that returned by strmax().──────────Value returned: Upon successful completion, strmin() returns the new string.══strrepeat() PELPurpose: Makes a string by concatenating repetitions of another.──────────Syntax: str strrepeat(str s, int num)──────────Description: The strrepeat() function creates a new string containing repetitions of the string indicated by the s argument. The number of repetitions contained in the new string is determined by the value of the num argument.──────────Value returned: The value returned by the strrepeat() function is the newly defined string.══sub()Purpose: Replace first occurrence of a substring with another──────────Syntax: int sub(str regex, str repl, str s)──────────Description: The sub() function substitutes the specified replacement string, repl, for the left-most substring matching the regex argument within string S. The regex argument is a regular expression. The special characters that may be used in the regex argument are those defined for regular expressions. These characters are described in the "Regular Expressions" chapter of the User's Manual. The special meaning of these characters may be used without regard to the state of the search_flags variable. The scope of the match is always maximal.──────────Value returned: The value returned by the sub() variable is one (TRUE) if a match was found. The function returns zero (FALSE) if no match was found.══SUBSEP AWKPurpose: Sets string used to simulate multidimensional arrays.──────────Type: str SUBSEP──────────Description: Standard AWK does not support multidimensional arrays but allows simulating them. When you assign values to an array using multiple subscripts, such as arr[i,j], AWK concatenates the j elements of i into a single string. The elements are separated by the SUBSEP string. The split() function may then be used to access individual components. The initial value for this variable is "\x1C".══substr()Purpose: Create a new string from a portion of another string.──────────Syntax: str substr(str s, int pos [, int count])──────────Description: The substr() function creates a string by making a copy of a portion of the s argument. Characters are copied into the new string starting with the character indicated by the pos argument. The pos argument describes the ordinal position of the starting character within the string. The count argument tells the number of characters to be copied. If this number exceeds the number of characters available for copying, all available characters are copied into the new string. If the count argument is omitted, the remainder of the string is copied beginning at the pos position.──────────Value returned: Upon successful completion, the substr() function returns the newly created string. If an empty string or negative number has been provided as an argument, the function returns an empty string.══suffix()Purpose: Creates a string from the tail of another string.──────────Syntax: str suffix(str s, int count)──────────Description: The suffix() function creates a string by making a copy of a portion of the s argument. The number of characters copied into the new string is indicated by the count argument. Count characters are copied from the end of the s string to the new string.──────────Value returned: Upon successful completion, the suffix() function returns the newly created string. If an empty string or negative number has been provided as an argument, the function returns an empty string.══swap_marks()Purpose: Exchange the locations of two bookmarks in the buffer.──────────Syntax: int swap_marks([markid mark1, [markid mark2]])──────────Description: The swap_marks() function swaps the locations of the bookmarks represented by arguments mark1 and mark2. If no arguments to this function are supplied, then it is assumed that the mark defining the currently marked region of text is to be swapped with the current cursor position. When used in this manner, the function will fail if no region of text has been defined. If the mark1 argument is supplied but mark2 is not, bookmark 0 is the assumed value of mark2. The current position, which is always bookmark 0, may thus be exchanged with any bookmark using this function. This is particularly useful when you wish to change the location at which a marked block begins but maintain the current position as the end of the block. If either of the arguments names or assumes a non-existent bookmark, the function will fail.──────────Value returned: On successful completion, swap_marks() returns a non-zero value (TRUE). Upon failure a zero value (FALSE) is returned.══swap_programPurpose: Tells whether to maximize memory for DOS command──────────Type: int swap_program──────────Description: The swap_program variable indicates whether or not the memory used by SPE should be swapped to disk during the system() function. When this variable is a non-zero value (TRUE), swapping occurs. If the swap_program variable is zero (FALSE) SPE will not swap memory to disk. The default value for this variable is non-zero (TRUE). When memory is swapped to disk SPE retains less than 4K of memory. This is essential in order to use many memory hungry compilers from within the editor. There may be a short pause while memory is swapped.──────────See also: system()══symbol_match()Purpose: List functions and variables matching a string.──────────Syntax: array symbol_match(str symbol_name [, int match_type])──────────Description: The symbol_match() function compiles a list of functions or variables whose names begin with the string named by the symbol_name argument. For example, the function call below returns a list of all functions and variables that begin with the string "toggle_": func_list = symbol_match("toggle_") By default, the function lists all functions and variables that match the string, both primitives (builtins) and those defined in PEL. The list may be narrowed or widened to include local functions and variables by specifying the optional match_type argument. The accepted values for match_type are as follows: Hex value Type included ----------- --------------------- 0x1 primitive functions 0x2 primitive variables 0x4 global functions 0x8 global variables 0x10 local functions 0x20 local variables These values may be combined to receive a list containing symbols of more than one type. For example, a value of 0x3F may be used to include all types of symbols in the list.──────────Value returned: This function returns an array of strings containing the matching symbols. Elements which represent local functions or variables take the form filename:symbol_name.══system()Purpose: Allows command execution without exiting to DOS.──────────Syntax: int system([[@]str command [, int shell_parse]])──────────Description: The system() function generates a sub- process in which the command contained in the command argument is executed through the command processor. Control returns to the editor as soon as the command has been completed. If no arguments are supplied, the command processor is invoked and the DOS prompt appears. In this case, control does not return to the editor until the EXIT command is typed from the command line. If a command argument has been supplied, the message "Press any key to continue..." appears when the command has run its course. Under OS/2, an @ modifier may be placed at the beginning of the command to be executed. Commands marked in this manner will be executed as OS/2 background tasks. When the system() function is called, the DOS screen is normally restored in preparation for output from the command. This may be avoided by redirecting all output and input within the command. SPE then will not clear the screen if in scanning the command it detects output and error redirection ( >&filename ). If the shell_parse argument is supplied and is non-zero, SPE will not scan the command and will always restore the DOS screen. The amount of memory available to the command executed by system() is determined by the state of the swap_program variable. When swap_program is zero, the editor releases all of the memory it has allocated (Heap) except for the memory occupied by the program itself. When swap_program is non-zero, SPE also writes as much program memory to disk as possible (all but approximately 4K).──────────Value returned: The value returned by the system() function is the DOS exit code resulting from the command. If the command could not be executed, the function returns a value of - 1.──────────See also: swap_program dos_window()══system_key()Purpose: Prompts user for operating system command.──────────Syntax: void system_key()──────────Description: The system_key() function prompts the user for a command and sends it to the operating system for execution. If the command fails, a warning giving the error code is displayed in the dialog box. This function is intended for processing single commands without "shelling out". If it is necessary to execute a series of commands, the system() function may be preferable.──────────Value returned: No useful value is returned by this function.══tabs() PELPurpose: Allows defining tab stops interactively.──────────Syntax: void tabs()──────────Description: The tabs() function prompts the user for a new string value to be assigned to the buffer_tabs variable. The old value of buffer_tabs is presented to the user for editing. A short name has been assigned to this function to facilitate its execution from the keyboard. This is done through execute_function(), which is normally assigned to a key.──────────Value returned: No useful value is returned by this function.══temp_pathPurpose: Names directories where temporary files are made.──────────Type: str temp_path──────────Description: The temp_path variable contains the name of the directory where the editor creates temporary files, when necessary. The initial value for this variable is taken from two environment variables. If a TMP environment variable has been defined, the directory it names becomes the first directory in the temp_path list. If an environment variable named TEMP has been defined, the directory named by that variable is added to temp_path. Normally the user concatenates other directory names onto the temp_path variable without removing existing directory names.══time()Purpose: Creates an encoded time value from elements.──────────Syntax: int time([int yr [,mo [,day [,hr [,min [,sec]]]]]])──────────Description: The time() function assembles the components of a date, specified as arguments to the function, into a timestamp integer. The components that may be specified are year, month, day, hour, minute and second. The values allowed for these arguments are as follows: The yr argument may be any value from 1980 onward. The mo argument may be in the range from 1 to 12. The day argument may be from 1 to 31. The hr argument may be from 0 to 23. The min and sec arguments may each be from 0 to 59. Each of the arguments to this function may optionally be omitted in order from the least significant to the most significant. If an argument is omitted, the lowest allowable value for that argument is used. If all arguments are omitted, however, the function is treated as a current time inquiry.──────────Value returned: The value returned by time() is the number of seconds since 00:00:00 GMT, January 1, 1970.══toggle_anchor()Purpose: Toggle placement of selection mark at current position.──────────Syntax: int toggle_anchor([int type])──────────Description: The toggle_anchor() function places a selection bookmark of the type described in the type argument at the current position if no block is already marked in the current buffer. If a selection marker of any type already exists in the buffer, it is removed. The possible values for the type argument are the same as those used by the region_type() function described above. If the type argument is omitted, the normal, type 1, bookmark is assumed. If a new bookmark is placed, the new bookmark defines a marked block or region of text as described in the description of drop_anchor().──────────Value returned: The value returned by the toggle_anchor() function is non-zero (TRUE) if a bookmark was created and zero (FALSE) if a bookmark was removed.──────────See also: drop_anchor(), raise_anchor(),region_type()══toggle_auto_indent() PELPurpose: Toggles the auto-indent feature on or off.──────────Syntax: void toggle_auto_indent([int force])──────────Description: The toggle_auto_indent() function toggles the state of SPE's auto-indent feature. This function therefore affects the action of the [Enter] key. When auto-indent is on, a special function is assigned to the [Enter] and [Ctrl][Enter] keys. These functions copy a like amount of whitespace preceding the text on the previous line to new lines. If the previous line does not contain any printable characters, nothing is copied to the new line. When auto-indent is off, the function usually assigned to the [Enter] key, insert_newline(), merely begins a new line by inserting the new line sequence. The optional force argument allows you to force the auto-indent feature to the condition you desire. If the force argument is non-zero (TRUE), auto-indent is turned on regardless of its previous condition. If force is zero, this feature is always turned off. Auto-indent has some similarities to the word processing margin maintained when word processing is in effect. These two modes are completely independent, however. You should select either auto-indent or word processing but not both. By default, auto-indent is off. It may, however, be turned on by the emulation mode you have selected. This function has a synonym, ai(). A very short name has been selected for this synonym to facilitate its execution interactively. This is done through execute_function(), which in standard keymaps is available by pressing the [F10] key.──────────Value returned: No useful value is returned by this function.──────────See also: buffer_flags, insert_newline()══toggle_borders()Purpose: Toggles the window outline on or off.──────────Syntax: void toggle_borders([int on])──────────Description: The toggle_borders() function turns on or off display of borders for the current window. When the on argument is zero, this feature is turned off. Other values for on turn it on. When the on argument is omitted the feature is toggled to its opposite condition.──────────Value returned: No useful value is returned by this function.══toggle_dialog()Purpose: Turns on or off use of a message window.──────────Syntax: void toggle_dialog([int on])──────────Description: The toggle_dialog() function turns on or off use of a dialog window for messages.. When the on argument is zero, this feature is turned off. Other values for on turn it on. When the on argument is omitted, the feature is toggled to its opposite condition.──────────Value returned: No useful value is returned by this function.══toggle_display()Purpose: Turns on or off 43/50 line mode.──────────Syntax: void toggle_display([int on])──────────Description: The toggle_display() function turns on or off 43/50-line mode display. When the on argument is zero, this feature is turned off. Other values for on turn it on. When the on argument is omitted the feature is toggled to its opposite condition.──────────Value returned: No useful value is returned by this function.══toggle_drawing() PELPurpose: Turns on or off line drawing mode.──────────Syntax: void toggle_drawing([int style])──────────Description: The toggle_drawing() function turns on or off the use of line drawing in the current buffer. Line drawing is performed with shifted- arrow keys or, when numlock is on, keypad arrow keys. The style argument determines which set (1 through 4) of line-draw characters will be used. If the style argument is zero, line drawing is turned off. If the style argument is omitted, line drawing is toggled on or off. If toggled on in this manner, the line-draw character set used is style 1. The line- draw styles are defined below: 1 All lines are single lines. 2 Vertical lines are single, horizontal lines are double. 3 Vertical lines are double, horizontal lines are single. 4 All lines are double lines.──────────Value returned: No useful value is returned by this function.══toggle_electric() PELPurpose: Toggles code processing on or off.──────────Syntax: void toggle_electric([int force])──────────Description: The toggle_electric() function toggles the state of SPE's code processing package, sometimes called the "electric" package. This package provides assistance with programming-language-specific tasks. These tasks include construct template and pair matching. The optional force argument allows you to force the code processing to the condition you desire. If the force argument is non- zero (TRUE), this feature is turned on regardless of its previous condition. If force is zero, this feature is always turned off. By default, code processing package is off. It may, however, be turned on by the emulation mode you have selected. The code processing package is described more fully in Appendix B of the Functions by Category manual. This function has a synonym, ec(). A very short name has been selected for this synonym to facilitate its execution interactively. This is done through execute_function(), which in standard keymaps is available by pressing the [F10] key.──────────Value returned: No useful value is returned by this function.══toggle_file_backup() PELPurpose: Toggles creation of backup files.──────────Syntax: void toggle_file_backup([int on])──────────Description: The toggle_file_backup() function turns on or off backup file processing. When the on argument is zero, this feature is turned off. Other values for on turn it on. When the on argument is omitted, the feature is toggled to its opposite condition. The location where backup files are created is determined by the backup_directory variable. The extension applied to the backup file is set by the backup_file_ext variable. When these two variables are set to their default values, backups will be made under the original filename in a directory named \SPE\BACKUP on the current drive.──────────Value returned: No useful value is returned by this function.══toggle_file_locking()Purpose: Toggles use of semaphore to ensure exclusive access.──────────Syntax: void toggle_file_locking([int on])──────────Description: The toggle_file_locking() function enables, disables or toggles the file locking feature. This feature creates a special semaphore file in the directory where each of the files are that have been loaded for editing. If the semaphore file already exists, SPE assumes the file is locked by another user or editor session and the file is loaded as Read-Only. The name of the semaphore file is the same as that of the file to be edited, except that the third character of the extension is an ampersand, "&". Extensions containing two or less characters are padded with underscores.──────────Value returned: No useful value is returned by this function.══toggle_insert_mode()Purpose: Toggles between insert and overtype modes.──────────Syntax: void toggle_insert_mode([int on])──────────Description: The toggle_insert_mode() function turns on or off insert mode. When the on argument is zero, this feature is turned off. Other values for on turn it on. When the on argument is omitted the feature is toggled to its opposite condition.──────────Value returned: No useful value is returned by this function.══toggle_linenumbers()Purpose: Turns on or off display of line numbers.──────────Syntax: void toggle_linenumbers([int on])──────────Description: The toggle_linenumbers() function turns on or off the display of line numbers in the current window. When the on argument is zero, this feature is turned off. Other values for on turn it on. When the on argument is omitted the feature is toggled to its opposite condition.──────────Value returned: No useful value is returned by this function.══toggle_pause() PELPurpose: Toggles pausing on errors.──────────Syntax: void toggle_pause([int force])──────────Description: The toggle_pause() function toggles the state of the pause_on_error variable. Toggling pausing on ensures that each warning, error, or informative message may be read before another is displayed. The toggle_pause() function is particularly useful when you are testing user-written functions that display a series of debugging messages. The optional force argument allows you to force the pausing feature to the condition you desire. If the force argument is non- zero (TRUE), auto-indent is turned on regardless of its previous condition. If force is zero (FALSE), this feature is always turned off. A synonym has been defined for this function, pe(). This synonym has a very short name in order to facilitate its execution interactively. This is done through execute_function(), which is available through the [F10] function in standard keymaps. By default, pausing is off.──────────Value returned: No useful value is returned by this function.══toggle_pvcs()Purpose: Toggles PVCS support features.──────────Syntax: void toggle_pvcs([int level])──────────Description: The toggle_pvcs() function controls the level of automatic PVCS (Polytron Version Control System) support provided by SPE. The following values have been defined for the level argument: PVCS_DISABLED 0 PVCS_ENABLE_GETS 1 PVCS_ENABLE_EMPTY_GETS 2 PVCS_ENABLE_GETS + PVCS_ENABLE_EMPTY_GETS 3 PVCS_DISABLED (0) means that no automatic PVCS support is desired. PVCS_ENABLE_GETS (1) indicates that if the user attempts to load a read-only file the user is given the opportunity to retrieve a writable copy of the file from its PVCS archive (logfile). PVCS_ENABLE_EMPTY_GETS indicates that if the user attempts to load a non-existent file the user is given the opportunity to retrieve the file from its PVCS logfile. The PVCS_ENABLE_GETS and PVCS_ENABLE_EMPTY_GETS values may be combined (3) to prompt the user for retrieval of the file if it either doesn't exist or it is read-only. A more tersely named synonym for this function is the pvcs() function.──────────Value returned: No useful value is returned by this function.══toggle_search_block()Purpose: Toggles limiting searches to a marked block.──────────Syntax: void toggle_search_block([int on])──────────Description: The toggle_search_block() function turns on or off confining searches to a marked block. When the on argument is zero, this feature is turned off. Other values for on turn it on. When the on argument is omitted the feature is toggled to its opposite condition.──────────Value returned: No useful value is returned by this function.══toggle_search_case()Purpose: turns on or off case insensitivity in searches.──────────Syntax: void toggle_search_case([int on])──────────Description: The toggle_search_case() function turns on or off case insensitivity in searches. When the on argument is zero, searches are case sensitive. Other values for on causes searches to match text regardless of the case used. When the on argument is omitted the feature is toggled to its opposite condition.──────────Value returned: No useful value is returned by this function.══toggle_search_forward()Purpose: Toggles direction of searches.──────────Syntax: void toggle_search_forward([int on])──────────Description: The toggle_search_forward() function turns searching in a forward direction on or off. When the on argument is zero, searches commence backward relative to the cursor position. Other values for on cause searches to continue forward from the cursor. When the on argument is omitted the feature is toggled to its opposite condition.──────────Value returned: No useful value is returned by this function.══toggle_search_regex()Purpose: Turn on or off use of regular expressions.──────────Syntax: void toggle_search_regex([int on])──────────Description: The toggle_search_regex() function turns on or off the use of regular expressions in searching. When the on argument is zero, search patterns are treated as ordinary strings. Other values for on cause special meaning to be given to regular expression patterns. When the on argument is omitted the feature is toggled to its opposite condition. Regular Expressions are discussed in the "Regular Expressions" chapter of the User's Manual.──────────Value returned: No useful value is returned by this function.══toggle_tabs_to_spaces()Purpose: Turns on or off tab interpretation.──────────Syntax: void toggle_tabs_to_spaces([int on])──────────Description: The toggle_tabs_to_spaces() function turns on or off the interpretation of tabs as spaces. When the on argument is zero, tab characters are inserted into the buffer when requested. Other values for on cause spaces to be inserted into the buffer rather than the tab character. The line is filled with spaces to the next tab stop. When the on argument is omitted the feature is toggled to its opposite condition. This function accomplishes its task by modifying a bit of the buffer_flags variable. This variable may also be modified directly.──────────Value returned: No useful value is returned by this function.══toggle_wp() PELPurpose: Toggles word processing mode.──────────Syntax: void toggle_wp([int force])──────────Description: The toggle_wp() function toggles the use of SPE's word processing features. This is done by changing the WP_ENABLED bit of the buffer_flags variable. When the WP_ENABLED bit is on, word-wrap features are applied to the current paragraph of the buffer. As text is added or deleted from the paragraph, the lines of text are reformatted as necessary to conform to word processing margins (see wp_left_margin and wp_right_margin). When reformatting a line of text results in no changes to that line, the editor assumes that the rest of the paragraph is already in proper format. When word processing is on and a new line is added to the buffer the entire contents of the word processing margin on the preceding line is copied to the beginning of the new line. This is particularly useful when you wish to have each line begin with comment characters or some special character sequence. The optional force argument allows you to force the word-processing feature to the condition you desire. If the force argument is non-zero (TRUE), auto-indent is turned on regardless of its previous condition. If force is zero (FALSE), this feature is always turned off. The Auto-indent feature of SPE is somewhat similar to the word processing margin. These two modes are completely independent, however. You should select either auto- indent or word processing but not both. The synonym wp() has been defined for this function. The very short name chosen for this synonym facilitates its execution interactively. This is done through execute_function(), which is available in standard keymaps through pressing the [F10] key. By default, word processing is off. The subject of word processing is discussed in greater detail in the "Word Processing" chapter of the Functions by Category manual.──────────Value returned: No useful value is returned by this function.══tolower()Purpose: Converts all letters in a string to lower-case.──────────Syntax: str tolower(str s)──────────Description: The tolower() function creates a new string from the s argument in which all upper-case letters have been converted to lower-case. The numbers punctuation and white-space in the string are not modified by this function.──────────Value returned: The value returned by the tolower() function is the newly created string. If the argument represents an empty string, the function will return an empty string.══toreverse() PELPurpose: Reverses the case of characters in a string.──────────Syntax: str toreverse(str string)──────────Description: The toreverse() function creates a string in which the upper case characters in the string argument are converted to lower case and the lower case characters to upper case. This means that characters in the range "a".."z" become the corresponding character in the range "A".."Z" and vice versa.──────────Value returned: The value returned by the toreverse() function is the newly created string containing the converted characters.──────────See also: reverse()══toupper()Purpose: Converts all letters in a string to upper-case.──────────Syntax: str toupper(str s)──────────Description: The toupper() function creates a new string from the s argument in which all lower-case letters have been converted to upper-case. The numbers punctuation and white-space in the string are not modified by this function.──────────Value returned: The value returned by the toupper() function is the newly created string. If the argument represents an empty string, the function will return an empty string.══trans() PELPurpose: Translates characters in one string to those in another.──────────Syntax: str trans(str s, str tr, str repl)──────────Description: The trans() function creates a new string, translating individual characters of one string to those found in another. For those familiar with the UNIX╘ operating environment, this function works similarly to the "tr" command found in that environment. Each character in the s argument is compared to the characters in tr. If a character in s matches the character at position n of tr, it is replaced by character n of repl. If the tr string is longer than the repl string, there will be some characters in tr that have no corresponding character in the repl argument. In these cases, the character in tr is deleted from the s string when creating the new string.──────────Value returned: The value returned by the trans() function is the newly created string. If the first or second argument supplied to this function is an empty string, the function will fail and an empty string is returned.══transfer()Purpose: Transfer text to the current buffer from another buffer.──────────Syntax: int transfer(bufid s_buf, int al, int bl [, int cl, int dl])──────────Description: The transfer() function copies a block from the buffer indicated by the s_buff argument into the currently active buffer at the cursor position. The block of text to be copied may be specified in either of two ways. Depending on the method selected, either two or four additional arguments are required to define the block. If the block of text to transfer has been enclosed within bookmarks, you need only specify the number of those bookmarks. These bookmarks are specified in the al and bl arguments. Alternately, you may specify the block of text by line and column numbers. In this latter case, you must give the beginning line and then the beginning column in al and bl respectively. These two coordinates are followed by the ending line in the cl argument and finally the ending column in dl. The ending line and column define the last character which is to be copied. If using the line and column method of defining the block to transfer, keep in mind that line and column numbering begins with 1.──────────Value returned: The transfer() function returns the number of characters copied, upon successful completion. Upon error, a zero value is returned and a message indicating the source of the error is displayed. A block is never zero characters.══trim() PELPurpose: Deletes specified characters from end of line.──────────Syntax: str trim(str s [, str t])──────────Description: The trim() function creates a new string from the s argument, in which the characters in the t argument have been stripped from the right side of the string. The new string will not end with any of the characters specified by t. If the t argument is omitted, all white- space will be stripped from the right end of the line. For the purpose of this function, white-space is defined as spaces and tabs.──────────Value returned: The value returned by the trim() function is the newly created string. If any of the arguments do not represent a defined string, the function will return an empty string.══typeof()Purpose: Reports the data type of a variable in string form.──────────Syntax: str typeof(any arg)──────────Description: The typeof() function tells the type or class of variable that has been provided as the arg argument to the function. This enables a program to test a variable before passing it to a function requiring a specific type of argument.──────────Value returned: The value returned by the typeof() function is one of the following descriptive strings: "int" A signed integer using <= 32 bits. "string" A string of up to 8000 characters. "regular expression" A string; may contain meta chars. "array" Variable w/subscripted elements. "fileid" A file handle/descriptor. "bufid" A buffer identification number. "keymapid" A keymap identification number. "winid" A window identification number. "functionid" A function identification number. "uninitialized"A variable not yet assigned a type. When tested for type, markids are identified as integers. This allows a mark id to be more readily compared to an integer.══undo()Purpose: Reverses the effects of a previous edit operation.──────────Syntax: int undo([int index])──────────Description: The undo() function restores the current buffer to its condition previous to one or a series of recent edit or motion operations. If the index argument is not specified, undo() reverses the effects of the most recent edit. Each operation on a buffer is assigned a sequential operation number. The index argument is one of these buffer operation numbers. undo() uses this argument to reverse the effects of all edits with operation numbers subsequent to index. The current operation number may be obtained and recorded for later use by calling the undo_index() function. A series of edit operations or commands may also be reversed by successive calls to the undo() function. If a desired edit operation is inadvertently undone, the redo() function allows reversing the effect of an undo(). Operations which may be undone are stored, as they are executed, on an "undo/redo stack". Each buffer has its own undo stack. For each call to the undo() function, the most recent operation on the stack is reversed and the current operation number for that buffer is decremented. The operation that was undone is not lost, however, and is performed again if redo() is called before further editing. Whenever editing commences again the contents of the stack beyond the current operation are lost.──────────Value returned: The value returned by the undo() function is non-zero (TRUE) if the edit operation is successfully undone. A zero value (FALSE) is returned if there was nothing to undo or if an error prevented an operation from being undone.──────────See also: redo(), undo_index()══undo_index() PELPurpose: Reports current operation number of undo/redo stack.──────────Syntax: int undo_index()──────────Description: The undo_index() function returns a value that the undo() or redo() function can use to restore the current state of the buffer after additional edits have been made. Each operation on a buffer is assigned a sequential operation number. This function returns the number of the operation most recently performed. When supplied as an argument to the undo() function, undo() reverses the effects of all edits with operation numbers subsequent to this value. After a series of undo() calls, the redo() function can re-perform the series of operations up to this value. An example will clarify the use of these operation numbers: You type the letters "a", "b" and "c" into a new, empty buffer. This represents three different edit operations. Let us number them 1, 2, and 3. You are not sure of the next letters you are about to type and you think you may wish to return to the current state of the buffer if things don't work out. You therefore execute the undo_index() function and store away the value it gives you, which is the number 3. Next you type the letters "x", "y" and "z". We number these operations 4, 5, and 6. Already you are dissatisfied with the direction things are taking, so you call the undo() function, supplying the value you received from undo_index() as an argument. Before doing so, however, you execute undo_index() and store away the value ( 6 ) that it returns. Soon the contents of the buffer is again the letters "a", "b" and "c". Remorse motivates you to execute the redo() function, using the value from the second execution of undo_index() as an argument. The contents of the buffer is then "abcxyz".──────────Value returned: The undo_index() function returns the number of the operation most recently performed in the current buffer.══ungetkey()Purpose: Return a character to the keyboard buffer.──────────Syntax: int ungetkey(int char)──────────Description: The ungetkey() function pushes the character indicated by the char argument back into the keyboard buffer. This character will be the next character available for later reading. This may be a character read by either the getchar() or the getkey() function. In the case of extended keycodes, two characters will actually be returned to the buffer. Unlike the similar DOS function, more than one character may be un-read between reads.──────────Value returned: The value returned, upon successful completion, is the ASCII value of the character re-inserted into the keyboard buffer. This will be a value identical to the char argument.══unlink()Purpose: Delete a file.──────────Syntax: int unlink(str path)──────────Description: unlink() removes the file indicated by path. The path argument must contain an explicit filename; no wildcard characters are allowed. It may also contain a path element, including drive specifier. If path contains no path element, the current drive and directory are assumed. When the path argument is expressed as a constant, it must be enclosed in double quotes. Backslashes, forward-slashes or doubled backslashes may be used as path separators.──────────Value returned: If the file indicated by path does not exist, or if permission to delete the file is not obtained, a value of zero is returned. Non-zero values indicate the function was successfully completed.──────────Compatibility: This function is identical to the ANSI C remove() and the UNIX╘ unlink() except as to return values.══up()Purpose: Move the cursor by lines toward the top of the buffer.──────────Syntax: int up([int lines])──────────Description: The up() function moves the cursor the number of lines found in the lines argument toward the beginning of the buffer. If the lines argument is not supplied, one line is assumed. Negative values for lines are allowed and result in the cursor moving in the opposite direction. In other words, calling up() with -3 as the argument is the as calling down() with 3 as the argument. The column position of the cursor resulting from a call to up() may be affected by the buffer_flags variable described above. If movement into VIRTUAL SPACE is allowed, the cursor always maintains the same column position at its new line location. If movements into VIRTUAL SPACE are disallowed, the column position may change. When the up() function would position the cursor beyond the end-of-line, it moves to the nearest column on the new line location which contains a character. If up() moves the cursor into a tab, the cursor always moves to the beginning of the tab. If there are fewer lines remaining between the cursor position and the beginning of the buffer than the lines argument specifies, the cursor is moved to the first line of the buffer. A short beep is then issued from the speaker.──────────Value returned: The up() function returns the actual number of lines traversed. This will be the same number as the lines argument, except when there are too few lines between the cursor position and the beginning of the buffer to execute the move completely.══upper() PELPurpose: Converts characters in a block to upper-case.──────────Syntax: void upper()──────────Description: The upper() function converts all lower- case letters in a selected block of text to upper-case. If no block has been selected the character at the cursor is converted. Numbers punctuation and white-space in the block are not modified by this function.──────────Value returned: No useful value is returned by this function.──────────See also: toupper()══versionPurpose: Stores the release version number of the editor.──────────Type: str version──────────Description: The version constant contains the release version number of the Sage Professional Editor executable currently in use. Consulting this variable enables the user or user written function to determine what features are available. This constant may not be modified.══vi() PELPurpose: Makes SPE operate similarly to Unix╘ VI editor.──────────Syntax: void vi()──────────Description: The vi() function executes a setup and installs a special keyboard definition that causes the Sage Professional Editor to approximate the operation of popular Unix╘ editor, VI. This is one of the "emulation packages" provided with SPE. Because of certain inherent differences in the way SPE performs tasks and the way VI performs similar tasks, this function does not attempt a complete emulation of VI. For a list of differences between SPE's VI emulation and the VI editor see Appendix B of the User's Manual.──────────Value returned: No useful value is returned by this function.══visible_end_buffer windowPurpose: Designates string representing the end of buffer.──────────Type: str visible_end_buffer──────────Description: Each window has a visible_end_buffer variable associated with it. The visible_end_buffer variable is a string to be displayed demonstrating the location of the end of the buffer. This string is not saved in the file, but only appears on screen. Usually this string is a single character such as "\x04", which is a diamond. This variable takes its initial value from the global variable default_visible_end_buffer at the time the buffer is created.══visible_newlines windowPurpose: Defines string displayed to indicate end of line.──────────Type: str visible_newlines──────────Description: Each window has a visible_newlines variable associated with it. The visible_newlines variable is a string displayed at the end of each line. By default, this string is empty, which means that the end of the line is not visibly marked. In any case, this string is not stored in the file, but only appears on the screen. If it is desirable to see where each line ends, a single character or string of characters may be assigned to this variable. These characters then appear immediately to the left of the last character on the line. Typical values for this variable include the following: "\x11" ( a triangle pointing left ), "\x11\xd9", ( a triangle followed by a corner ), "\x14" ( a paragraph symbol ). This variable takes its initial value from the global variable default_visible_newlines at the time the buffer is created.══visible_spaces windowPurpose: Defines appearance of a space on- screen.──────────Type: str visible_spaces──────────Description: Each window has a visible_spaces variable associated with it. The visible_spaces variable is a one character string that is displayed wherever a space character occurs in the buffer. The string may contain more than one character but only the first character is used. By default, this string contains a space, which means that spaces represent themselves. Changing this string, however, does not change the text stored in the file or the contents of the buffer. Only the appearance on the screen is affected. If it is desirable for spaces to have a graphical representation, a single character or string of characters may be assigned to this variable. Normally, only one character is assigned to this string. A typical value for this string, other than its default value, is "\xfa", which appears as a small dot. This variable takes its initial value from the global variable default_visible_spaces at the time the buffer is created.══visible_tabs windowPurpose: Defines appearance of a tab on-screen.──────────Type: str visible_tabs──────────Description: Each window has a visible_tabs variable associated with it. The visible_tabs variable is a string displayed wherever a tab character occurs in the buffer. By default, this string contains a tab, which means that tabs represent themselves. Changing this string, however, does not change the text stored in the file or the contents of the buffer. Only the appearance on the screen is affected. If it is desirable for tabs to have a graphical representation, a single character or string of characters may be assigned to this variable. Normally, only one character is assigned to this string. A typical value for this string, other than its default value, is "\x1a", which appears an arrow pointing to the right. This variable takes its initial value from the global variable default_visible_tabs at the time the buffer is created.══visible_virtual_lines windowPurpose: Defines appearance of lines beyond end of buffer──────────Type: str visible_virtual_lines──────────Description: Each window has a visible_virtual_lines variable associated with it. The visible_virtual_lines variable is a string displayed on screen lines that are beyond the end of the buffer. By default, this string is empty, which means that these lines are not visibly marked. In any case, this string is not stored in the file, but only appears on the screen. If it is desirable a visual cue to indicate lines not contained in the buffer, a single character or string of characters may be assigned to this variable. A typical value for this variable is "~". This variable takes its initial value from the global variable default_visible_virtual_lines at the time the buffer is created.══visible_virtual_spaces windowPurpose: Defines appearance of virtual spaces on-screen.──────────Type: str visible_virtual_spaces──────────Description: Each window has a visible_virtual_spaces variable associated with it. The visible_virtual_spaces variable is a string displayed wherever virtual spaces occur in the window. By default, this string contains a space. This means that virtual spaces have the same appearance as "real" spaces. Changing this string does not change the text stored in the file or the contents of the buffer. Only the appearance on the screen is affected. Virtual spaces may be given a special graphical representation by assigning a single character or string of characters to this variable. Normally, only one character is assigned to this string. A typical value for this variable is "\xb0", which appears as a partially filled block. This variable takes its initial value from the global variable default_visible_virtual_spaces at the time the buffer is created.══warning()Purpose: Displays formatted output in the Dialog window.──────────Syntax: void warning(str fmt [, any args,...])──────────Description: The warning() function prints a formatted message to the Dialog window. If no dialog window has been defined, a window pops up to display the message. In this case SPE pauses for a key to be typed before closing the window. The output from this function is suppressed if the variable message_level is 3. This function is primarily used to display messages that indicate a possible or impending error. The fmt and args arguments follow the argument specifications of the fprintf() function.──────────Value returned: No useful value is returned by this function.──────────See also: message_level══window_border_contains()Purpose: Tells if coordinates are at a window's border.──────────Syntax: int window_border_contains(int x, int y [, winid win])──────────Description: The window_border_contains() function tests whether or not a screen location is part of a window's border. The win argument dictates the window whose border is to be tested. If this argument is not supplied, the test operates on the current window. The x argument is the screen column number and the y argument is the line number. Screen coordinate counts begin with 0.──────────Value returned: The value returned by this function will be non-zero (TRUE) if the window is displaying a border and any portion of it is at the specified screen location. If the window has no border or the border does not occur at the coordinates specified by x and y the function returns zero (FALSE).══window_containing()Purpose: Tells which window occupies a specified location.──────────Syntax: winid window_containing(int x, int y)──────────Description: The window_containing() function reports which window is visible at the screen coordinates named by the x and y arguments. The x argument is the column offset and the y argument is the line offset.──────────Value returned: The value returned by the window_containing() function is the numeric id of the window at the specified screen coordinates. If there is no window at these coordinates, the function returns zero.══window_contains()Purpose: Tells if a location is within a certain window.──────────Syntax: int window_contains(int x, int y [, winid window])──────────Description: The window_contains() function determines if a specified screen location falls within the defined boundaries of a window. The window argument is a window id previously assigned through a call to either the create_window() function. It indicates the window whose boundaries are to be tested. If the window argument is not supplied, the test operates on the current window. The x argument is the screen column offset and the y argument is the line offset. These numbers may be treated as Line and column numbers whose count begin with 0.──────────Value returned: The value returned by the window_contains() function is non-zero (TRUE) if it falls within the limits defined by the variables window_x0, window_y0, window_width and window_height. These dimensions will include the window's border, if any. The window need not be the active or upper-most window on the screen for toe coordinates to be considered within its boundaries. If the specified screen coordinates do not fall within the boundaries of the window, a zero value (FALSE) is returned.══window_cursor_x windowPurpose: Sets the column location of a direct read/write cursor.──────────Type: int window_cursor_x──────────Description: Each window has a window_cursor_x variable associated with it. Together with window_cursor_y, the window_cursor_x variable determines the coordinates from which strings may be read or written with the low-level functions read_window() and write_window(). These two coordinates define the location of an "non-buffer" cursor that operates independently of the cursor used in editing. The non-buffer cursor is visible only when the current window has no buffer attached. Typically such a window is being used as a menu. The window_cursor_x variable contains the number of columns from the beginning of text in the window at which reading or writing begins. The cursor position count begins with the left-most text column as 0; that is, it is zero origin. Setting these variables has no affect on the current buffer position. This imaginary cursor position is automatically incremented after reading or writing a string to the end of the string.──────────See also: write_window(), read_window(),highlight_window()══window_cursor_y windowPurpose: Sets the line location of a direct read/write cursor.──────────Type: int window_cursor_y──────────Description: Each window has a window_cursor_y variable associated with it. Together with window_cursor_x, the window_cursor_y variable determines the coordinates from which strings may be read or written with the low-level functions read_window() and write_window(). These two coordinates define the location of a "non-buffer" cursor. The window_cursor_y variable contains the number of lines from the beginning of text in the window at which reading or writing begins. This cursor position count begins with the upper-most text line as 0; that is, it is zero origin. Setting these variables has no affect on the current buffer position. This imaginary cursor position is automatically incremented after reading or writing a string to the end of the string.──────────See also: write_window(), read_window(),highlight_window()══window_first read-only, windowPurpose: Stores line number of the first line of text in a window.──────────Type: int window_first──────────Description: Each window has a window_first variable associated with it. The window_first variable contains the number of the first visible buffer line in the window.══window_flags windowPurpose: Stores a number of window attributes as flags.──────────Type: int window_flags──────────Description: Each window has a window_flags variable associated with it. The least significant 16 bits of the window_flags variable describe the state of various attributes of the window. Individual bits of window_flags are used by SPE to signify if the window has borders, whether the window takes up the full screen or is an icon and so on. The most significant 16 bits of window_flags are available for definition and use by user functions. The initial settings of this variable are obtained from the variable default_window_flags at the time the window is created. Therefore this description of window_flags also applies to the variable default_window_flags. The window_flags variable is comprised of a number of subfields and TRUE/FALSE or ON/OFF flags. Here is a listing of the bits of window_flags and their significance: Bit # Field Mask Zoom Status Field (r/o) 0-1 WINDOW_ZOOM System Window Flag 2 WINDOW_SYSTEM Reserved 3 Border/Scroll Bar Field 4-7 WINDOW_BORDERS Reserved 8-11 Title Bar Position 12-13 WINDOW_TITLE Tab Ruler Flag 14 WINDOW_RULER Reserved (r/o) 15 You may elect to completely change the value of window_flags or modify just one field of this variable. When assigning a new value to window_flags select one value for each field from the tables below, add them together and assign the result to window_flags. Note that no value need be specified for the Zoom Status Field since the field is read only and will not be modified by this operation. When modifying one element of window_flags while preserving the rest, use the set_flag_bits() function to perform the bit manipulation for you. You will need to supply to set_flag_bits() the appropriate field mask from the table above and the desired field value from the tables below. A series of descriptive labels representing field masks and field values have been defined for your use. The values associated with these labels are defined in the source file WINDOWS.PEL. Only the descriptive labels are listed in the tables. Zoom Status Field The Zoom Status Field is comprised of the first two bits of the window flags variable. This tells whether the window is reduced to an icon, normal size or expanded to fill the entire screen. This field may be examined but not modified. To determine a window's zoom status, you may perform an and() on window_flags and WINDOW_ZOOM. For example, and(window_flags,WINDOW_ZOOM) places the window status into the status variable. The possible resulting values and their meaning are shown below: 0 The window is an icon. 1 The window is its normal size. 2 The window is expanded. 3 The window is invisible (not just covered). The condition of the window is not changed through the Zoom Status Field, but rather through the use of the expand_window(), restore_window() and collapse_window() functions. System Window Flag The System Window Flag identifies whether or not a window is a system window. System windows differ from ordinary windows in that the functions that move sequentially through the window list (next_window(), prev_window()) skip over system windows by default. After the System Window Flag is a bit reserved for future use. Border/Scroll Bar Field Bits 4 through 7 make up the Border/Scroll Bar field. The value in this field determines whether the window will have borders and if and where scroll bars will be placed. When one or more scroll bars are enabled borders are automatically enabled. For a more complete description of these features, see the "Windowing" chapter of the Functions by Category manual and the "Using a Mouse" chapter of the User's Manual. The possible combinations and their field values appear below: Features Field Value No border or Scroll Bars WINDOW_NOBORDER Border but no Scroll Bars WINDOW_BORDER Vert. Scroll Bar on right WINDOW_SB_RIGHT Vert. Scroll Bar on left WINDOW_SB_LEFT Horiz. Scroll Bar on bottom WINDOW_SB_BELOW Scroll Bars right & bottom WINDOW_SB_RIGHTB Scroll Bars left & bottom WINDOW_SB_LEFTB Title Bar Position Field The next two bits determine the location of the window's title bar. You may use this field to select a title bar across the top of the window, across the bottom or no title bar at all. You may not have the title bar across the bottom if you have also selected to have a title bar at the top or a scroll bar at the bottom. Title Bar Location Above window text WINDOW_TITLEA Below window text WINDOW_TITLEB No Title Bar WINDOW_NOTITLE Tab Ruler Flag The Tab Ruler Flag turns on or off the tab ruler which shows tab positions at the top of the window. The field value and mask are both WINDOW_RULER. Other Useful Labels WINDOW_STANDARD(0x1091) title, border w/scroll bar right WINDOW_PLAIN(0x1081) title and plain border──────────See also: linenumber_format, next_window(),create_window()══window_height read-only, windowPurpose: Tells over-all height of the current window in lines.──────────Type: int window_height──────────Description: Each window has a window_height variable associated with it. The window_height variable indicates how many lines are occupied by the window. If borders, rulers or titles are enabled, line occupied by these features are included in this measurement. Along with the window_width variable, this variable defines the over-all dimensions of the window. This variable is read-only and may not be modified by the user or user- written functions.──────────See Also: window_x0, window_y0,window_text_height══window_margin read-only, windowPurpose: Tells the number of columns off-screen to the left.──────────Type: int window_margin──────────Description: Each window has a window_margin variable associated with it. The window_margin variable indicates how many columns of text have scrolled out-of-sight to the left. When the beginning of lines are visible window_margin will be zero.══window_name windowPurpose: Stores a name for display in a window's title bar.────────── Declared as: str window_name──────────Description: Each window has a window_name variable associated with it. The window_name variable stores a string to be displayed in the title bar of the associated window. The title bar is the top border of the window. If this variable is empty, the associated buffer's buffer_name variable is used. If buffer_name is also empty, no name is displayed.══window_page_offsetPurpose: Cursor line position used when window is re-drawn.──────────Type: int window_page_offset──────────Description: Each window has a window_page_offset variable associated with it. This variable indicates the line, relative to the center, on which the cursor is placed after large vertical movements within the buffer. Such movements include jumps to distant line numbers, jumps to buffer extremities and other motions which completely change the contents of the window. The number contained in window_page_offset represents the number of lines from the center line of the window to the line which contains the cursor. Negative numbers indicate a line above the center while positive numbers position the cursor on a line below the center. For example, if the value of window_page_offset is -3 the editor will position the cursor three lines above the center line of the window. The value 12 will position the cursor twelve lines below the center line, if the window extends down that far. If the value for window_page_offset would place the cursor outside the limits of the window, the cursor is placed on the last or first line of the window, depending on whether the value is positive or negative. The cursor column position is determined by the type of motion command executed and the condition of the scroll_means_pan variable. Usually this means that the cursor will attempt to retains the same column position it occupied before the move. The initial setting of this variable is obtained from the variable default_window_page_offset at the time the window is created.──────────Examples: window_page_offset = -999 # cursor at top window_page_offset = 0 # cursor at center window_page_offset = 999 # cursor at bottom══window_page_overlapPurpose: Defines how many lines are retained after paging.──────────Type: int window_page_overlap──────────Description: Each window has a window_page_overlap variable associated with it. The window_page_overlap variable stores the number of previously visible lines that remain visible after a page_up() or page_down() is executed. These "page" functions scroll the contents of the window the window height less the amount of this variable. The initial setting of this variable is obtained from the variable default_window_page_overlap at the time the window is created.──────────See also: page_down(), page_up()══window_text_height read-only, windowPurpose: Tells how many lines of text a window may contain.──────────Type: int window_text_height──────────Description: Each window has a window_text_height variable associated with it. The window_text_height variable indicates how many lines of text may be shown in the window. Borders, rulers and titles, if any, are not included in this measurement. Along with the window_text_width variable, this variable may be used to determine the dimensions of the text in the window. This variable is read-only and is modified by the function set_text_region().══window_text_width read-only, windowPurpose: Tells how many columns of text a window contains.──────────Type: int window_text_width──────────Description: Each window has a window_text_width variable associated with it. The window_text_width variable indicates how many columns of text can appear in the window. Borders are not included in this measurement. In addition, displaying line numbers reduces this measure. Along with the window_text_height variable, this variable may be used to determine the dimensions of the text in the window. This variable is read-only and is modified by the function set_text_region().══window_text_x0 read-only, windowPurpose: Tells the column offset of text in the window.──────────Type: int window_text_x0──────────Description: Each window has a window_text_x0 variable associated with it. The window_text_x0 variable tells the number of columns in the window precede the window's text area. Window borders and line numbers are not counted as window text. Together with window_text_y0, this variable defines the location of the upper left-hand corner of the text area of the window. This variable is read-only and is modified by the function set_text_region().══window_text_y0 read-only, windowPurpose: Tells the line offset of text in the window.──────────Type: int window_text_y0──────────Description: Each window has a window_text_y0 variable associated with it. The window_text_y0 variable tells how many lines in the window precede the text area of the window. This measure includes any window border, tab ruler or title that appears above the text. Together with window_text_x0, this variable defines the location of the upper left-hand corner of the text area of the window. This variable is read-only and is modified by the function set_text_region().══window_valid()Purpose: Tells whether a window is currently defined.──────────Syntax: int window_valid([winid win])──────────Description: The window_valid() function reports whether the window id indicated by win argument is defined. If the argument is omitted, the function tests the window id named by the current_window variable.──────────Value returned: The value returned by this function is TRUE (non-zero) if the window is valid. Otherwise, the function returns FALSE (zero).══window_width read-only, windowPurpose: Tells how many columns the current window contains.──────────Type: int window_width──────────Description: Each window has a window_width variable associated with it. The window_width variable indicates how many columns of text are occupied by the window. Any borders surrounding the window are included in this measurement. Along with the window_height variable, this variable may be used to determine the dimensions of the window. This variable is read-only and may not be modified by the user or user-written macros. The width of a window must be modified using the frame_window() function.══window_x0 read-only, windowPurpose: Tells the column offset of the window.──────────Type: int window_x0──────────Description: Each window has a window_x0 variable associated with it. The window_x0 variable tells the number of columns to the left of the window on the screen. Together with window_y0, this variable defines the location of the upper left-hand corner of the window. This variable is read-only and may not be modified by the user or user written functions. To change the position of the window, use the frame_window() or move_window() function.──────────See also: frame_window(), move_window()══window_y0 read-only, windowPurpose: Tells the line offset of the window.──────────Type: int window_y0──────────Description: Each window has a window_y0 variable associated with it. The window_y0 variable tells the number of lines that precede the window on the screen. Together with window_x0, this variable defines the location of the upper left-hand corner of the window. This variable is read-only and may not be modified by the user or user written functions. To change the position of the window, use the frame_window() or move_window() function.──────────See also: frame_window(), move_window()══wordstar() PELPurpose: Makes SPE operate similarly to WordStar╘ editor.──────────Syntax: void wordstar()──────────Description: The wordstar() function executes a setup and installs a special keyboard definition that causes the Sage Professional Editor to approximate the operation of the popular editor from MicroPro, WordStar╘. This is one of the "emulation packages" provided with SPE. Because of certain inherent differences in the way SPE performs tasks and the way WordStar performs similar tasks, this function does not attempt a complete emulation of WordStar. For a list of differences between SPE's WordStar emulation and the WordStar editor see Appendix B of the User's Manual.──────────Value returned: No useful value is returned by this function.══wp()Purpose: Toggles word processing mode.──────────Syntax: void wp([int on])──────────Description: The wp() function toggles the use of SPE's word processing features. This tersely named synonym for toggle_wp() is suitable for executing through the PEL interpreter ( [F10] ). When the on argument is zero, this feature is turned off. Other values for on turn it on. When the on argument is omitted the feature is toggled to its opposite condition.──────────Value returned: No useful value is returned by this function.══wp_left_margin bufferPurpose: Sets left margin for use when word- wrap enabled.──────────Type: int wp_left_margin──────────Description: Each edit buffer has a wp_left_margin variable associated with it. When this variable is set to a value greater than zero, this value defines the buffer column number which is to be preceded by a margin. The columns to the left of the named column are maintained as a margin by word- processing functions while text to the right of this margin is subject to wrapping and adjustment. Text may be forcibly inserted in these margins, but if this is done, the text is treated as part of the margin on subsequent reformatting. In other words, the text in the margin is not moved along with the rest of the text in the paragraph. Changing the value of this variable when word-wrap is enabled causes the entire paragraph to be reformatted to conform to the new value. This variable takes its initial value from the global variable default_wp_left_margin at the time the buffer is created. Word-processing is enabled with the wp() function. Word-wrap and word processing features of SPE are discussed in greater detail in the "Word Processing" chapter of the Functions by Category manual.──────────See also: buffer_flags, wp_right_margin, wp()══wp_right_margin bufferPurpose: Sets right margin for use when word- wrap is enabled.──────────Type: int wp_right_margin──────────Description: Each edit buffer has a wp_right_margin variable associated with it. This variable represents the column number beyond which text is not allowed to extend when word- processing is enabled. Text extending beyond this limit is word-wrapped to the next line. Word-processing is enabled with the wp() function. This variable takes its initial value from the global variable default_wp_right_margin at the time the buffer is created. Word-wrap and word processing features of SPE are discussed in greater detail in the "Word Processing" chapter of the Functions by Category manual.──────────See also: buffer_flags, wp_left_margin══wrap_paragraph()Purpose: Reformat a paragraph to conform to margins.──────────Syntax: int wrap_paragraph()──────────Description: The wrap_paragraph() function fills and wraps text in the current paragraph in units of words. When completed, the text in the paragraph conforms to the limits defined by the wp_left_margin and wp_right_margin variables. If a marked block has been defined, the text is reformatted from the beginning of the marked block to the end of the last line containing marked text. If column marking is used, the wp_left_margin and wp_right_margin variables will be set to the column boundaries used. Only text to the right of the wp_left_margin will be formatted. If text exists in the left-hand margin, its position will not be altered. New lines may be created as the result of wrapping text. When this happens, the whitespace or text occurring in the left margin of the preceding line is duplicated at the beginning of the new line. Word-wrap and word processing features of SPE are discussed in greater detail in the "Word Processing" chapter of the Functions by Category manual.──────────Value returned: This function returns a non-zero value upon successful completion. If an error occurs, a zero value is returned.══write_all_buffers() PELPurpose: Save the edits in modified buffers to their disk files.──────────Syntax: int write_all_buffers()──────────Description: The write_all_buffers() function attempts to save all buffers containing unsaved edits to their corresponding files. Buffers whose buffer_flags variable indicates they are not writable will not be saved. If a disk-write error occurs in the course of this function, the editor will continue to attempt to save the remaining buffers after error recovery.──────────Value returned: No useful value is returned by this function.──────────See also: buffers_modified buffer_flags.══write_block_key()Purpose: Write block to specified file.──────────Syntax: void write_block_key()──────────Description: The write_block_key() function writes a marked block or, if no block is marked, the entire buffer to a file. The name of the tile to be written is obtained by prompting.──────────Value returned: No useful value is returned by this function.══write_buffer()Purpose: Writes the contents of the current buffer to disk.──────────Syntax: int write_buffer([str filename])──────────Description: The write_buffer() function writes the contents of the currently active edit buffer to a file. The file to which the buffer is written is named by the filename argument. This argument may include a complete path element including drive. If the filename argument is omitted, the buffer is written to the file indicated by its buffer_filename variable. However, supplying a filename argument does not change the name of the buffer or the buffer's default output filename. No check is made to determine if the buffer has actually been modified.──────────Value returned: The value returned by write_buffer() is the number of bytes written on successful completion. If the buffer_flags variable indicates that writing the file is not allowed or if a write-error occurs this function returns a zero value. A message indicating the source of the error is then displayed.══write_marked_block()Purpose: Write the marked block of text to a named file.──────────Syntax: int write_marked_block(str name)──────────Description: The write_marked_block() function saves the marked block of text in the current buffer to the file described in the name argument. The name argument is a filename and optional path element. If this argument contains no path element the default drive and directory are assumed. If the file designated by name already exists, it is overwritten without warning. Supplying a name argument does not change the name of the buffer or the buffer's default output filename. The current buffer must contain a marked block of text for this function to succeed. If the BUFFER_EXPAND_TABS bit is set in the buffer_flags variable, tabs are expanded on output.──────────Value returned: Upon successful completion the value returned by write_marked_block() is the number of characters written to file. If an error occurs, a zero value is returned. A marked block can never contain zero characters. If no block in the current buffer has been marked a message to that effect is displayed. Consult the errno variable to determine the cause of other errors.══write_window()Purpose: Write a string in a window.──────────Syntax: void write_window(str text [, winid win])──────────Description: The write_window() function writes a string to the window coordinates specified by a special "cursor". This low-level function is for use in constructing menus, primarily by experienced users. The text argument contains the string to be written and the optional win argument identifies the window in which it is to be written. If the win argument is not supplied the text string is written to the current window. This function is designed to be used on windows that have no buffer attached. If this function is used in conjunction with a window that does have a buffer attached, the normal window updating will overwrite any changes made by this function. The coordinates to which the string is written are determined by an imaginary cursor. This cursor is used only by the write_window() and read_window() functions. The location of this cursor is set by modifying the window's window_cursor_x and window_cursor_y variables. This cursor position is automatically positioned at the end of the string after a string has been written. The string is always confined to the text area or I/O region of the window. Strings that would otherwise exceed the limits of this region are wrapped to the following line.──────────Value returned: No useful value is returned by this function.──────────See also: set_text_region(), window_cursor_x,window_cursor_y══wsearch()Purpose: Text pattern matching across buffers.──────────Syntax: int wsearch(str pattern, int flags)──────────Description: The wsearch() function examines all edit buffers for one or more occurrences of text matching the pattern argument. It is similar to the search() function, which searches only the current buffer. The pattern may be a regular expression or a simple string to match, depending upon the condition of the flags variable. The direction of search and other searching parameters are also controlled by the flags argument. The position of the cursor at the end of the search may be controlled through regular expressions, but by default is placed at the beginning of the matching text. The values allowed for flags are those that may be represented by a single byte. Each bit of the flags byte sets a searching parameter. The search_flags variable is normally used as the flags argument if the search parameters currently in use are acceptable. A complete description of the meaning given to the bits of flag may be found under search_flags. The search operation is repeated as dictated by the variable search_count. If search_count is 1 or 0 the search is carried out once. If search_count is greater than 1 the operation is repeated that number of times or until it is unsuccessful. In any case, the value of search_count is reset to 0 upon completion.──────────Value returned: The value returned by wsearch() is the number of matches found. This will normally be one. If no matches are found, a zero value is returned.══wsearch_again()Purpose: Repeats a previous search across buffers without prompting.──────────Syntax: int wsearch_again()──────────Description: The wsearch_again() function continues a search for the next occurrence of matching text. This function is similar to the search_again() function, which searches only the current buffer. It uses the variables search_pattern and search_flags as parameters to the operation without prompting. These variables usually reflect the parameters of any previous search operation but may be modified by user- written programs.──────────Value returned: The value returned by the wsearch_again() function is non-zero (TRUE) if a match was found. If not, a value of zero (FALSE) is returned══xor()Purpose: Performs a bit-wise OR on two numbers.──────────Syntax: int xor(int num1, int num2)──────────Description: The xor() function compares the bits of the num1 and num2 arguments and derives a third value from them. The argument values remain unchanged. This function operates on 32 bit values. If the arguments are not 32 bit numbers, they are converted to this form for the purpose of this function.──────────Value returned: Each bit in the value returned by the xor() function is SET ( 1 ) if the corresponding bit in one (and only one) of the arguments is set. If the corresponding bit is set in both or neither of the arguments is set, the bit is RESET ( 0 ).
