APPLICATION NOTE #182 USING SAVE/GETS WITH XPL Rev. 01 This application note describes using Save/Gets in your XPL (XyWrite Programming Language) programs to store various kinds of information and to access that information. It also tells you how to load a program to a Save/Get key to make it easy to access. Useful tips to help you use Save/Gets in your programs are also included. Save/Gets are storage areas, or buffers, you can use to save strings or values. XyWrite provides several types of Save/Gets: ordinary, programming, and additional programming. You are probably most familiar with the 36 "ordinary" Save/Gets (A-Z and 0-9), usually accessed with the Alt key. You can also use ordinary Save/Gets in your program. The content of an ordinary Save/Get remains intact until either you overwrite it or you QUIT XyWrite. When you use XPL, there are also one thousand programming Save/Gets, numbered from 00 to 999, which can only be used with an XPL program. You define programming Save/Gets within a program; and their contents can change while the program is running. The Save/Gets you use depend on how long you want the contents to remain intact: * The contents of programming Save/Gets 00-99 vanish at the start of each new program. * The contents of programming Save/Gets 100-999 remain intact until either they are overwritten or you QUIT XyWrite. Additional programming Save/Gets differ from the other types of Save/Gets because they can only be used with the LDPM (Load Program) and the RUN commands. Refer to "Loading a Program to a Key" for information. SAVING INFORMATION TO SAVE/GETS There are three kinds of information you can save in a Save/Get: a numeric expression (value), a literal string of characters, or a program. The kind of information you are saving determines the command you use to save it. Saving an Expression You use the SX (Save Expression) command when you want XyWrite to evaluate a character or series of characters and save the result to a Save/Get. The character(s) can be a number (such as 88), a numeric expression (such as the result of 2 + 2), or a XyWrite variable (such as the current left margin setting). The syntax for the SX command is: sx #,exp where "#" is the number or letter of the Save/Get you want to save the value to. exp is either a number, a numeric expression, or a XyWrite variable you want evaluated. (You use the VA command when you want to save the current value of a XyWrite variable.) XyWrite evaluates the expression, determines a final value from it, and saves the final value to the Save/Get. For example, the following code saves the number 40 to Save/Get 01: <> As a second example, the following code adds 25 and 25 and saves the result, 50, to Save/Get 02: <> (Parentheses are not required around the expression above; however, they make it easier to read.) As a third example, the following code saves the current value of the Left Margin setting to Save/Get 03: <>>> (If the current left margin is set to 10, XyWrite saves the value of 10 to Save/Get 03.) As a fourth example, the following code saves the current filename to Save/Get 04. Although the filename is a character string, the SX command is used because XyWrite must interpret the variable. <>>> Saving a Literal String (SV) The SV (Save String) command saves a literal string to a specified Save/Get. A literal string is any character or series of characters that XyWrite saves exactly as typed, without any interpretation or evaluation. SV does not differentiate between a letter, number or any symbol in the string, but simply dumps the string into the specified Save/Get. The syntax for the SV command is: sv #,string where "#" is the number or letter of the Save/Get you want to save the literal string to and "string" is a literal string. For example, the following code saves the literal string "YES" to Save/Get 99: <> As another example, the following code saves the literal string "(25+25)" to Save/Get 04 and treats it as a literal string, not as a numeric expression: <> As a third example, the following code saves the literal string <> to Save/Get 05. XyWrite saves the six characters as text without any evaluation of the left margin. If the SX command were used instead, the actual value of the current left margin would have been saved. <>>> In Versions 3.54 and above of XyWrite III Plus, you can use the SV command to save a defined block of text to a Save/Get. For example, the following code saves the defined block to Save/Get 06: <> Saving a String as a Subroutine The SU (Save Subroutine) command is similar to SV, but the string is marked as a program. The syntax for the SU command is: su #,string where "#" is the number or letter of the Save/Get you want to save the subroutine to, and "string" is the string you want to save as a program. For example, the following code saves the string "BC saXC"--which executes the Save command--as a subroutine to Save/Get 98: <> If the SV (Save String) command was used in the example instead of the SU command, XyWrite would not execute the functions within the string when the program called for it. Instead, XyWrite would place the characters on the screen as if they were text. ACCESSING OR USING INFORMATION IN A SAVE/GET There are three commands you can use to access information saved in a Save/Get: PV (Put Variable), GT (Get Text), and IS (Insert Save/Get). The syntax for the PV command is: pv # The syntax for the GT command is: gt # The syntax for the IS command is: is # where "#" is the number or letter of the Save/Get you want to access. The command you use depends on two factors. First you decide how you want to use the Save/Get--either displayed on the screen or processed inside an expression. Second you consider the type of contents (numbers or character strings). Displaying the Contents of a Save/Get You use either the PV (Put Variable) or the GT (Get Save/Get) command to display the contents of a Save/Get. The PV command interprets the contents of a specified Save/Get and then inserts the characters, one at a time, at the current cursor location. The GT command is similar to PV, but GT inserts the text of the Save/Get all at once. You can display the contents of a Save/Get either in the text area or on the command line. The command you use depends on where you want to insert the characters. Placing the Contents in the Text Area. You can use either the PV or the GT command to place the contents of a Save/Get in the text area. There are two differences between PV and GT. The first is speed--GT is faster than PV because it puts out the Save/Get all at once; therefore it is especially useful for large blocks of text. PV places the contents on the screen one character at a time, scrolling as it goes. The second difference is cursor position--PV leaves the cursor at the end of the block of text; GT leaves it at the beginning. For example, the following code saves the current value of the left margin to Save/Get 01 and outputs that value at the current cursor location: <>>><> As a second example, the following code saves the literal string "Paul" to Save/Get 08 and outputs the string at the current cursor location: <><> Since GT places the contents on the screen all at once and leaves the cursor at the beginning of the block, it is similar to the @A to @Z and @0 to @9 function calls used by ordinary Save/Gets. (Ordinary Save/Gets leave the cursor at the end of the block.) For example, the following code inserts the contents of Save/Get 98 in the text area at the current cursor location: <> Placing the Contents on the Command Line. You use the PV command to place the contents of a Save/Get on the command line. (Normally, you cannot use the GT command in this case; see Note #1.) For example, the following code includes the contents of Save/Get 00 as an argument of the Search command on the command line:  BC se /<>+25>> As a second example, the following IF expression compares the numeric value of a Save/Get directly to a numeric value. If the numeric value of Save/Get 09 equals 15, execution goes to the label start to continue. <>==15>>>><><> As a third example, the following code compares Save/Gets 09 and 07. If the numeric value of Save/Get 09 is greater than the value of Save/Get 07, the program jumps to the label yes to continue. <>><>>><><> You use IS if the Save/Get contains one or more alphabetic (non-numeric) characters. (See Note #2.) You use the IS command to compare two strings in an IF statement. For example, the following code compares Save/Gets 15 and 25. If the string in Save/Get 15 is the same as the string in Save/Get 25, execution goes to the label next to continue. <>==<>>><><> Note #2 Running Subroutines. If the expression contains any of the following string operators or string functions, you must use the IS command regardless of the contents of the Save Get: + (Concatenation) î (Contains) @UPR @SIZ @CNV For example, if you want to concatenate two numbers, you use the IS command. When you use <, >, ==, and <> to compare two strings, the operators function on the basic alphabetic sort rule (ASCII order). XyWrite compares each pair of letters (one from each string) until it finds a pair that do not match, and then it stops comparing. (This comparison is case-sensitive.) A character is "less than" another character if its ASCII number is lower. Therefore, the string APPLES is less than the string ORANGES, because the ASCII value of uppercase A is less than the ASCII value of uppercase O. However, the string apples is greater than ORANGES, because the ASCII value of lowercase a is greater than the ASCII value of uppercase O. Note #3 Customized Sort Tables. Any customized sort table you have loaded into memory does not affect the comparison of two strings; XyWrite uses only the basic ASCII order sort rule. Loading a Program to a Key Although you can load your XPL programs to ordinary Save/Get keys, additional programming Save/Gets are available, which let you save your ordinary Save/Gets for on-the-fly use. You assign a Save/Get to a key with a two-character instruction representing a function call. Ordinary Save/Gets use an "at" symbol (@) followed by a letter or a number, and are normally mapped to the ALT Table in the keyboard file. Additional programming Save/Gets use an ampersand (&) followed by a letter or number. You can map them to the CTRL table or create a whole new table for them in the keyboard file. To use an additional programming Save/Get, first attach the two-character instruction to a key. For example, the following notation in a keyboard file assigns additional programming Save/Get E to key 18 (E on an IBM keyboard): 18=&E Then, load a program into memory and associate it with that function call. For example, you might write a program to help you print envelopes on your laser printer. To load that program and associate it with a key, the command might be: Type: F5ldpm envelope.pgm,&e Result: Whenever you press the key defined as &E, XyWrite executes the program. You can load programs in your startup file or while you are working. You can also develop several sets of programs to be loaded at appropriate times. Each time you load a program to a key, XyWrite overwrites the previous one. See Chapter 6 of the XyWrite III Plus Reference Guide for more information on customizing your keyboard file. TIPS Here are five useful tips to help you program Save/Gets. 1. When deciding which command to use to save information to a Save/Get, as a general rule use the SX (Save Expression) command when you want XyWrite to evaluate what is saved; use the SV (Save String) command when you want XyWrite to simply save a string of text literally. 2. To place a string or a numeric value that you stored in a Save/Get on the command line, use the PV (Put Value) command. 3. Before you can use either IS (Insert String) or PV (Put Variable) in a program, you must have previously established the Save/Get with SV (Save String) or SX (Save Expression). SV and SX not only save strings and results, they also identify the Save/Gets as valid elements within the program. 4. Use the VA (Value of Variable) command to return the value of any XyWrite default setting (e.g., left margin value) or any environment setting (e.g., current window number). Since the VA command returns a value, you must use the SX (Save Expression) command to store the value to a program Save/Get. The VA command has the following form: va nm where "nm" is the variable. Settings for variables other than defaults are preceded by a dollar sign ($). For example, the following code saves to Save/Get 01 the value of the current tab settings: <>>> As another example, the following code saves to Save/Get 02 the value of the current window number: <>>> Refer to the XyWrite III Plus Reference Guide for more information on VA settings. 5. If XyWrite displays an error when you try to run your program, often it is due to an error in syntax--you used one or more XPL commands improperly. For example, here are four common errors: "COMMAND ENTRY ERROR." You used the SX (Save Expression) command instead of the SV (Save String) command. In general, you use SX when you want XyWrite to evaluate the expression and you use SV when you want XyWrite to save the literal string. "LABEL NOT FOUND." You have either misspelled a label name or used the wrong case. The LB (Label) command must define the same label that is referred to by the GL (Go to Label) command. For example, <> does not jump to <>. "MISMATCHED OPERANDS." You tried to compare a string to a value. In an IF statement, you can compare strings to strings or values to values, but not strings to values. "NEED ID & EXPRESSION." You have an error in syntax either with the SX (Save Expression) command or with the SV (Save String) command.