  Advanced User-RPL guide
  by Justin Dossey
  dossey@ou.edu
  
  Contents
  
Note to all readers: . . . . . . . . . . . . . . . . . . . . .1.0
  
Syntax in this manual: . . . . . . . . . . . . . . . . . . . .2.0
  
BRCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.0
     If-style clauses: . . . . . . . . . . . . . . . . . . . .3.1
          IF..THEN..END structure. . . . . . . . . . . . . . .3.11
          IF..THEN..ELSE..END. . . . . . . . . . . . . . . . .3.12
          IFT structure. . . . . . . . . . . . . . . . . . . .3.13
          IFTE structure . . . . . . . . . . . . . . . . . . .3.14
          Notes on IF style things:. . . . . . . . . . . . . .3.15
     Case-style structures:. . . . . . . . . . . . . . . . . .3.2
          CASE . . . . . . . . . . . . . . . . . . . . . . . .3.21
  
Loop structures: . . . . . . . . . . . . . . . . . . . . . . .4.0
          Table of Loop Structures . . . . . . . . . . . . . .4.1
  
the TEST menu. . . . . . . . . . . . . . . . . . . . . . . . .5.0
          Table of comparators . . . . . . . . . . . . . . . .5.01
     Other stuff:. . . . . . . . . . . . . . . . . . . . . . .5.2
          Comparison between two conditional results:. . . . .5.2
     TYPE. . . . . . . . . . . . . . . . . . . . . . . . . . .5.21
     VTYPE . . . . . . . . . . . . . . . . . . . . . . . . . .5.3
  
Flag stuff . . . . . . . . . . . . . . . . . . . . . . . . . .6.0
          Table of Flag States . . . . . . . . . . . . . . . .6.01
     Other boolean: LININ. . . . . . . . . . . . . . . . . . .6.1
  
The TYPE menu. . . . . . . . . . . . . . . . . . . . . . . . .7.0
     OBJ\->: . . . . . . . . . . . . . . . . . . . . . . . . .7.1
     Type menu command reference . . . . . . . . . . . . . . .7.2
     C\->R and R\->C . . . . . . . . . . . . . . . . . . . . .7.3
     NUM . . . . . . . . . . . . . . . . . . . . . . . . . . .7.4
     DTAG. . . . . . . . . . . . . . . . . . . . . . . . . . .7.5
     EQ\-> . . . . . . . . . . . . . . . . . . . . . . . . . .7.6
  
Input and output-related stuff . . . . . . . . . . . . . . . .8.0
     INFORM. . . . . . . . . . . . . . . . . . . . . . . . . .8.1
     CHOOSE. . . . . . . . . . . . . . . . . . . . . . . . . .8.2
     The INPUT command . . . . . . . . . . . . . . . . . . . .8.3
     PROMPT: Input simplified. . . . . . . . . . . . . . . . .8.4
     DISP FREEZE HALT. . . . . . . . . . . . . . . . . . . . .8.5
     WAIT. . . . . . . . . . . . . . . . . . . . . . . . . . .8.6
     KEY . . . . . . . . . . . . . . . . . . . . . . . . . . .8.7
  
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . .9.0
     DISP. . . . . . . . . . . . . . . . . . . . . . . . . . .9.1
     FREEZE. . . . . . . . . . . . . . . . . . . . . . . . . .9.2
     MSGBOX. . . . . . . . . . . . . . . . . . . . . . . . . .9.3
     BEEP. . . . . . . . . . . . . . . . . . . . . . . . . . .9.4
     PVIEW . . . . . . . . . . . . . . . . . . . . . . . . . .9.5
     TEXT. . . . . . . . . . . . . . . . . . . . . . . . . . .9.6
     CLLCD . . . . . . . . . . . . . . . . . . . . . . . . . .9.7
  
Stack stuff. . . . . . . . . . . . . . . . . . . . . . . . . 10.0
     PICK  . . . . . . . . . . . . . . . . . . . . . . . . . 10.1
     ROLL  . . . . . . . . . . . . . . . . . . . . . . . . . 10.2
     ROLLD . . . . . . . . . . . . . . . . . . . . . . . . . 10.3
     DUPN. . . . . . . . . . . . . . . . . . . . . . . . . . 10.4
     DRPN. . . . . . . . . . . . . . . . . . . . . . . . . . 10.5
     ROT . . . . . . . . . . . . . . . . . . . . . . . . . . 10.6
     SWAP. . . . . . . . . . . . . . . . . . . . . . . . . . 10.7
     DROP. . . . . . . . . . . . . . . . . . . . . . . . . . 10.8
     DUP . . . . . . . . . . . . . . . . . . . . . . . . . . 10.9
     DUP2. . . . . . . . . . . . . . . . . . . . . . . . . . 10.10
     DROP2 . . . . . . . . . . . . . . . . . . . . . . . . . 10.11
  
Closing Note . . . . . . . . . . . . . . . . . . . . . . . . 11.0
  
1.0
Note to all readers:
  
     This guide is for people already familiar with User-RPL to
the extent of the manuals.  Knowledge of programming and program
syntax is assumed.  This is just a listing of all commands and
their usage.
     Also note that I have not read the Advanced User's
Reference.  Everything in this guide is either my direct
knowledge from the SX manual or a paraphrased section of my old
G(x) manual.  
 
2.0
Syntax in this manual:
When I know them, I use the ASCII representations of HP48
characters,  If I don't know them or write something unfamiliar,
use a little common sense and it'll help.  In a lot of syntax
representations, I use things like (test) and (if 1), etc.  This
doesn't mean that I want you to enclose whatever structure in
parentheses--it just means that you need to remove that and
replace it with what you want.  Unless in algebraics or complex
numbers, parentheses will always denote a fill-in.


Some common character substitutions:

Symbol       Meaning
\<< \>>      Program delimiters, CHR(171) and CHR(187)
\->          the arrow, CHR(141)
\q/          the square-root symbol, CHR(131)
\.d          The derivative symbol, CHR(136)
\.lf         newline symbol (CHR)

Without further ado, we begin!
  
Working through the PRG menus...
  
3.0 
BRCH
  
3.1
If-style clauses: 
 
3.11
IF..THEN..END structure
Syntax: \<< . . . IF (test) THEN (if 1) END . . . \>>
The test returns a 1 or 0.  if it's 0 then the program jumps to   
the END.
Example: \<< IF '1+X>0' THEN "Greater" 1 DISP 1 FREEZE END \>>
  
3.12
IF..THEN..ELSE..END
Syntax: \<< . . . IF (test) THEN (if 1) ELSE (if 0) END \>>
A variation on IF/THEN/END.  If 1, jumps to THEN.  if 0, jumps to
ELSE.
Example: \<< IF '1+X>0' THEN "Greater" ELSE "Less than" END 1
DISP 1 FREEZE \>>
  
  
  
3.13
IFT structure
Syntax: \<< . . . (test)  (if 1)  IFT . . . \>>
If the 1 clause is small, preferable to the longer IF/THEN/END
structure.  
Example: \<< '1+X>0'  "Greater"  IFT 1 DISP 1 FREEZE \>>
  
3.14
IFTE structure
Syntax \<< . . . (test)  (if 1)   (if 0)  IFTE . . . \>>
The variation for ELSE of IFT.   
Example: \<< '1+X>0'  "Greater" "Lesser"  IFTE 1 DISP 1 FREEZE
\>>
  
3.15
Notes on IF style things:
IFT and IFTE can also be used algebraically:
'IFT( (test), (if 1) )'
and 
'IFTE( (test), (if 1), (if 0) )'
  
Note on IFT and IFTE: The 1 and 0 clauses can be anything that
doesn't immediately execute upon being put on the stack.  This
includes strings, algebraics, programs, and numbers, but not
commands.  To put a command in the IFT(E) structure, put it in a
list.  Any number of commands
can be accessed this way.
  
All conditional tests can also be done on the stack. Many things
are preferable done on the stack, for that matter.  The above
programs' '1+X>0' can be written as 1 X + 0 > to maintain the RPN
style.  
  
Personal usage:  I very rarely use a full-blown IF/THEN/ELSE/END
structure.  Instead, I look for modularity and similarity in the
clauses.  This speeds up the process and sometimes allows for the
more compact IFT and IFTE functions.  The Example program, were I
to be using it, would be
\<< 1 X + 0 >  "Greater"   "Lesser" IFTE 1 DISP 1 FREEZE \>> .
  
3.2
Case-style structures:
  
3.21
CASE is pretty straightforward, and faster than IF/THEN/ELSE/END
structure when there are a lot
of branches to the structure.  The syntax is as follows:
  
\<< . . . CASE (test 1) THEN (if t1==1) END
               (test 2) THEN (if t2==2) END
     .
     .
     .
     END . . . 
\>>
   
  
4.0
Loop structures:
Loop structures all have simple syntax.  The things that
distinguish them are the counters and the test.   The following
table indexes the style, command, counter, and test.
  
4.01
Table of Loop Structures
  
Command             Style          Counter        Test
START...NEXT        Definite       none           none
START...STEP        Definite       none           none
FOR...NEXT          Definite       after FOR      none
FOR...STEP          Definite       after FOR      none
DO..UNTIL...END     Indefinite     none           at UNTIL
WHILE...REPEAT...END Indefinite    none           at WHILE
  
The difference between NEXT and STEP is in the increment.  NEXT
increments by 1 and STEP increments by the value in stack level
1.  (this can be useful in issuing BREAK-style loop ends on
search loops.)
  
With summations, don't forget about the Sigma for summation
(rshft-TAN).  It tends to be faster than FOR loops.  
  
5.0
the TEST menu
This section is pretty easy for anyone who has had a little math:
another table illustrates the action a command does.  I don't
know the ASCII code for the symbols,
so I'm going to write them exactly as they appear.
  
5.01
Table of comparators
Object       Question: Fill in the blank:(is object in level 2
(blank) level 1?)
==      Equal to
=/=          Not equal to
<       Less than
>       Greater than
<=      Less than or equal to
>=      Greater than or equal to
SAME         The exact same as
  
5.2
Other stuff:
 

5.21
Comparison between two conditional results:

Command      Level 2   Level 1   Result
AND            1         1         1
AND            0         1         0
AND            1         0         0
AND            0         0         0
OR             1         1         1
OR             0         1         1
OR             1         0         1
OR             0         0         0
XOR            1         1         0
XOR            1         0         1
XOR            0         1         1
XOR            0         0         0
 
  
NOT reverses any boolean.  If it's negative or 0, it's a 1.  If
it's anything else, it's a 0.
  
  
  
5.3
TYPE returns the object type.  The types are organized as
follows:
  
Type number       Object
0            Real number
1            Complex number
2            String
3            Real array
4            Complex array
5            List
6            Global name
7            Local name
8            Program
9            Algebraic Object
10           Binary integer
11           Graphics object
12           Tagged object
13           Unit object
14           XLIB name
15           Directory
16           Library
17           Backup object
18           Built-in function
19           Built-in command

There are a total of 29 types, most of which are not too useful
to the User-RPL programmer.  As soon as I find my quick reference
manual, i'll post the rest here.
  
5.4
VTYPE finds the type of object stored in a variable.  That way,
executables can be found.
  
6.0
Flag stuff
  
Flags are boolean references for programmers.  The negatively
numbered flags mostly control system functions, and the user can
have the positively numbered ones.  Use numbers between 1 and 64
and you should be fine.  A set flag is 1 and a clear one is 0. 
therefore, the command reference:
  
6.01
Table of Flag States
  
Command   Flag state     Result
SF        0              1
SF        1              1
CF        1              0              
CF        0              0
FS?       1              1
FS?       0              0
FC?       1              0
FC?       0              1
FS?C      1              1, flag is cleared
FS?C      0              0
FC?C      1              0
FC?C      0              1, flag is cleared

  
  
6.3
Other boolean: LININ
Tests whether the algebraic on level 2 is linear for the variable
on level 1.
  
7.0
The TYPE menu
  
7.1
OBJ\->:
  
Decomposes any object 1 level further into its components.  A
very useful command, and not just in programs.  Some examples:
  
1: { 234 345 546 567 }           (list)
  
OBJ\->  
  
5: 234
4: 345
3: 546
2: 567
1: 4              The depth of the list.
  

[[5 6] [7 8] 9 10]] OBJ\->  (array)
  
5
6
7
8
9
10
{3 2}             the dimensions of the array.
  
"Hello. 2 3 4 5 6" OBJ\->        (string)
'Hello.'
2
3
4
5
6

                 The string is simply decomposed.
  
LENGTH: 12   OBJ\->         (tagged object)
12
"LENGTH"               Components.
 
1_m OBJ\->        (unit object)
  
1
1_m               Components.
  
The converse is usually true for \->ARRY, \->LIST, \->STR,
\->TAG, and \->UNIT .
A note: with \->STR, all spaces are eliminated.  You have to
insert them when building the string.
I'll just put up a table illustrating their parts and results:
  
7.2
Type menu command reference
  
Command      Parameters                 result
\->ARR       { (rows) (columns) }       rowsXcolumns array
\->LIST      { (depth) }                list of (depth)
\->STR       any object                 string of object on 1 
\->TAG       (number),"(tag)"           tagged object 
\->UNIT      (number), 1_(unit)         unit object
     

7.3
C\->R and R\->C.  Stands for COMPLEX TO REAL and REAL to COMPLEX,
respectively.  Usage is simple:  
(1,2) C\->R gives
  1
  2
  
and 
  1
  2
R\->C gives
 (1,2)
  
7.4
NUM returns the number for a character in the HP table.  CHR
returns the character given the number. 
  
"a" NUM  returns 97.  
97 CHR returns "a".
  
7.5
DTAG removes the tag from a tagged object. The same as OBJ\->
DROP.  
LENGTH: 45 
DTAG
gives
45
  
7.6
EQ\->  breaks an equation into its left and right sides.
  
'45*x+2+y=34*x^3+2' 
EQ\-> 
gives
'45*x+2+y'
'34*x^3+2'
  
  
8.0
Input and output-related stuff
  
Everyone needs to take in info and put out info in a program
sometime or another.   It's simple: not all the info a prog needs
can be taken off the stack every time, and output is much more
readable when it is displayed properly.  Because of this, HP has
some very useful input- and output-related stuff.  We'll start
with input stuff.  
  
  Due to the usefulness of  the functions, i'm going into some
detail.
  

8.1
INFORM: the much-questioned function.  How does it work?  What is
it good for?  How can I use it?  This is in the FAQ, but it will
also be covered here.
  
When in normal mode, right-shifted any menu generally pulls up a
graphical interface.  Pretty, useful for someone unfamiliar with
the calc's operation.  
  
The syntax for INFORM is complicated, as its interface is
actually quite complicated.  It would have been easier to write
programs that prompted the user for the info bit by bit or with a
PROMPT, but someone wanted all the info on 1 or 2 screens--hence
the creation of this nifty new command.  
  
Based on a posting on HPCVBBS by Cary McCallister.  Revised by
Joe Horn.  Re-formatted by Andre Schoorl.
  
  
INFORM - Create a Custom Input Form
  
INPUT:
  
  
    5: "title"
    4: { fields }
    3: <format>
    2: { reset_values }
    1: { initial_values }
  
  

OUTPUT:
  
  
     Either: 2: { new_values }
             1: 1
     or:     1: 0
  
  
PURPOSE:
   INFORM creates full-screen custom input forms, similar to
             those of the built-in applications.
  
ARGUMENTS:
  
     title
          Is displayed in font 1 (small) at the top centre of the
          screen.  It may contain any number of characters,
          including 0, but, at most, 31 characters will be
          displayed. Strings longer than 31 character will be
          truncated to 30 characters and displayed with a   
     trailing ellipsis.  Line feed characters are displayed
          as boxes.
     { fields }
          Is a list of the form { field1 field2 ... fieldn }
          where each field is any one of these forms:
  
  
          1.    "label"
          2.    { "label" "help" }
          3.    { "label" "help" type1 type2 ... typen }
          4.    { }
  
  The "label" is a string of arbitrary text from 0 to 26 char-
   acters long (longer strings will be truncated to 25 charac-
   ters with a trailing ellipsis).  The "help" is displayed
   immediately above the menu area as a helpful prompt for the
   user.  The object type specifications list the one or more
   object types allowed in the field, in the form the TYPE com-
   mand returns.  If unspecified, the default help text is blank
   and the field will accept all object types.  If a field spec-
   ification is an empty list, no field is produced; instead,
   the field to the immediate left (if any) is expanded to fill
   the omitted field's space.  This allows further customization
   of form layout; for example, to have two fields in one row
   and three fields in the next.
   
     <format>
          May be any one of the following objects:
  
          1.    { }
          2.    columns
          3.    { columns }
          4.    { columns widths }
  
  
   Where <columns> is the number of columns that the display
   will be divided into e.g., if <columns> is 2 and there are
   two fields, they will be displayed side by side rather than
   one above the other.  <widths> is the tab width between the
   left edge of each title and its field; this makes vertical
   alignment of fields possible.  Titles longer than one tab
   width will cause the tab to be repeated automatically.  If
   unspecified, the default column count is one and the default
   tab stop width is three.
  
     { reset_values }
   Is a list of values one per input field which replace the
   values of all fields when the {RESET} key is pressed and
   "Reset all" is selected.  This list must either be empty
   or have exactly one item per field corresponding to the {
   fields } list above.  If empty, then all fields are deemed
   unspecified (i.e., blank).  Each reset value must match
   the type require by the form field. Selected fields may be
   marked as unspecified by using NOVAL as the reset value.
  
             
     { initial_values }
   is a list of values one per input field which specify the
   start-up values of all fields when the INFORM command is
   invoked. This list must either be empty or have exactly
   one item per field corresponding to the { fields } list
   above.  If empty, then all fields are deemed unspecified
   (i.e., blank).  Each initial value must match the type
   require by the form field.  Selected fields may be marked
   as unspecified by using NOVAL as the initial value.
  
RESULTS:
   INFORM returns the new field values { new_values } as a list
   to level 2 and the real value 1 to level 1 if the user
   completes the input form by pressing {OK} or ENTER.  The list
   will contain one item per field.  Each item will either be
   the last input value for the corresponding field, or NOVAL if
   the field was unspecified.
  
   INFORM returns the real value 0 to level 1 if the user
   terminates the input form by pressing {CANCL} or CANCEL.
REMARKS:
   NOVAL is basically a command (an XLIB name) that does nothing
   when evaluated. It can, however, be compared via ==, SAME and
   POS.
  
  Example program:
  \<< 'Value Table" 
     {    
          { "Min:" "Minimum for Table"  0 1 } 
          { "Max:" "Maximum for Table" 0 1 }
          { "Step:" "Increment Value" 0 1 }
          { "Var:" "Variable" 6 }            
          { "Expr:" "Expression" 0 1 9 } { }
     }
     2
     {  -10 10 1 'X' NOVAL }
     {  -10 10 1 'X' EQ }
     INFORM
  { TABLE } IFT               @ TABLE is a separate program to
                              @ take the values from the list
                              @ generated by INFORM and make a
                              @ table of values.
  \>>
  
  
Personal note:
INFORM is one of the few commands not explained in my old GX
manual.  Therefore, I am drawing all knowledge of this command
from the stack.  In my humble opinion, this is a useless command. 
I can't stand it.  I have never used it because I prefer the
stack.  (a usage note can always be in an IFERR structure)



8.2
CHOOSE - Create a User-Defined Choose-Box
  
     INPUT:
          3: "title"
          2: { items }
          1: <initial_item_number>
  
  
     OUTPUT:
          Either:   2: { chosen_item }
                    1: 1
          or:       1: 0
  
  
PURPOSE:
CHOOSE creates a user-defined "choose-box": a displayed box
containing items from which the user can choose one.
  
CHOOSE displays a standard choose box (normal, not maximized;
single-pick, not multi-pick) with an optional title line.
  
ARGUMENTS:
  
  title
     If any, is displayed in font 1 (small) in the top centre
     of the box.  It may contain any number of characters,
     including 0, but, at most, 22 characters will be
     displayed. Strings longer than 22 character will be
     truncated to 21 characters and displayed with a trailing
     ellipsis.  Line feed characters are displayed as boxes.
     If there are more than four items such that the scroll
     arrows are displayed, the maximum number of title
     characters is reduced to 21.  The title text is displayed
     in the title area in character font 1 (the menu font).  If
     the title string is empty, no title area will be created
     in the choose box, and the whole box will be devoted to
     the items.
  
{ items }
     Is a list of arbitrary objects.  Each item occupies one
     line in the choose box and is displayed in its command
     line form.  Only the first 14 characters of the displayed
     object will be shown (13 if the scroll arrows are
     present).  If an item contains more than 14 (13)
     characters, it will be truncated to 13 (12) and the final
     character will be replaced by an ellipsis.  If every item
     is a list of exactly two objects, the first object will be
     displayed and the second returned if the item is selected.
     If the number of items exceeds 4 with a title and 5
     without, scroll arrows will be displayed, and moving the
     highlight past the top or bottom of the box will scroll
     through the undisplayed items.
  
<initial_item_number>
     Specifies the initial field to be highlighted when the
     display first comes up (ordinarily 1).  A value of 0
     indicates that no field is to be highlighted and that the
     {CANCL} key is to be omitted from the menu, making the
     choose box act as an informational display without user
     selection.
  
RESULTS:
     CHOOSE returns the chosen item (or the second object in a
     two-element item list) and the real number 1 if the user
     completes the choose box by pressing {OK} or ENTER.  CHOOSE
     returns the real number 0 if the user terminates the choose
     box by pressing {CANCL} or CANCEL.
  
Example Program:
\<<
"Pick Your Poison"
{  "Arsenic" "Cyanide" "Hemlock" "Microsoft" }
4
CHOOSE 
{ OBJ\-> } IFT           @ Each choice is actually a program with
                         @ that name
\>>
  
  
8.3
The INPUT command:
Perhaps the most useful of the interactive programming commands,
INPUT halts program execution for data, not allowing the user to
access the stack, and continues upon the user's
pressing ENTER.  
Syntax:
\<< . . . "(Command to user)" "(Prompt)" INPUT OBJ\-> . . . \>>
-or-
\<< . . . "(Command to user)" { "(Prompt)" (cursor position)
(options) } INPUT OBJ\-> . . . \>>
INPUT, by default, reads data into a string.  That way, errors
can be avoided.  The OBJ\-> simply turns them into their native
state, usually real or algebraic.  The second syntax is more
complex.  It performs basically the same function, with the
added capability of cursor placement and options.  The options
are ALG, alpha, or V.  (alpha is the alpha symbol,alpha-rshft-a). 
ALG activates Algebraic mode.  This means that the +/- key puts
out a + or a -, not NEG, etc.  You still have to put the
algebraic delimeters Alpha means "turn alpha-lock ON!" to the
calculator.  The V option checks for Valid input.  This is useful
anytime you need to be sure input is a valid object or sequence
of objects for your program.  V automatically loops back to the
prompt after issuing an "Invalid Syntax" message to the user.  
On the cursor position--it can be a single number, such as 2, to
specify horizontal cursor position.  However, you can prompt for
two variables at a time with INPUT, whereupon it's nice to
have a horizontal and vertical coordinate.  To do this, use a
list. of coordinates, organized { (line#)(horiz#) } .   Also, a
-1 can be used as the cursor position to specify the cursor as
the replace cursor--data is overwritten.
Examples:
Simple usage of INPUT to find hypotneuse of 45-45-90 triangle
\<< "Input side" "" INPUT OBJ\-> 2 \q/ * \>>
Advanced usage to find derivative always for X of an equation:
\<< "Enter Equation" { "''"ALG V 2 } INPUT OBJ\-> 'X' \.d \>>
Advanced usage to find derivative for any variable of an
equation:
\<< "Enter Eq, Var" { "EQ1: ' ' \.lf  VAR1: ' ' " ALG V { 1 7 } }
INPUT OBJ\-> SWAP DROP OBJ\-> OBJ\-> DROP SWAP \.d  \>>
Note the extended stack manipulation required in this last
example to obtain necessary information from input.  This is
because I didn't use a "recommended" user interface.  HP
recommends that we use  :label: tags, empty strings, and
@commments@ for input--all these don't affect the data.  
Personal note:  Of all the data-in structures, I use INPUT the
most.  I use it in its simplest form the most because it requires
no stack attacks and minimal typing.  INPUT is fast and discreet,
and ENTER ends it.  Very convenient.
  
  
  
8.4
PROMPT: Input simplified
PROMPT is basically INPUT plus stack.  It displays a text string
and lets you do what you want until you think you've answered the
question.  Then you press CONT (lshift-ON) and it continues the
program.  PROMPT would probably be great if CONT weren't such a
pain.  I always feel like I have to tell the user to press CONT
when finished, even when I'm the only user. 
Syntax: "(command string)" PROMPT
Example:
\<< "Input your age \.lf and press CONT." PROMPT "You were born "
SWAP + " years ago." + 1 DISP 1 FREEZE \>>
  
8.5
DISP FREEZE HALT-- the one-up from PROMPT
DISP FREEZE HALT differs from PROMPT in that the displayed string
remains at the top of the display until CONT is pressed.  
Syntax: (line) DISP (area) FREEZE HALT
The PROMPT example in DISP FREEZE HALT style:
\<< "Input your age \.lf and press CONT." 1 DISP 1 FREEZE HALT 
"You were born " SWAP + "years ago" + 1 DISP 1 FREEZE \>>
For more info on DISP and FREEZE, refer to section 4, output.
  
8.6
WAIT-- a way to wait for single-key input
You can make WAIT stop a program for a given number of seconds,
or until a key is pressed. 
There are several ways to call WAIT, with different meanings.  
Syntax:  (number) WAIT
To stop and not change the display, use 0 as the number.
To stop and display the current menu, use -1 as the number.
To stop for an amount of time, use any positive number as the
number.  After a key is pressed, WAIT returns the key's
identification code--following the same chart as the
USER keys.  In a WAIT, the alpha and shift keys don't get
counted.
  
8.7
KEY-- WAIT's brother
KEY returns the last key pressed, regardless of whether it's
alpha or a shift or whatever.  If no key is pressed in its
preceding wait time, it puts a 0 on the stack.  If one is
pressed, it returns the location of the key (in the USER format)
to level 2 and a 1 to level 1.  This way, an indefinite loop
can wait for key input--certain key input.  
Syntax is simple:  KEY. 
Example: \<< DO UNTIL KEY END 52 SAME "Yes!" IFT 1 DISP \>>
  
9.0
Output
The GX's OUT menu is rather cluttered.  The novice user sees
PVIEW, TEXT, CLLCD on the left--
commands that are much less useful to the average non-graphical
user than the ones on the right-
-DISP, FREEZE, and MSGBOX.  I like to believe that BEEP is hidden
in the NXT menu because it's so annoying.  
Because it's easier to start with DISP, FREEZE, and MSGBOX, I
will.
First, a note about the display.  There are really two displays
on the HP48, as you probably know--the text display and the
graphics display.  The graphics display has no set rows and
columns other than the pixels.  The text display has seven lines
and, usually, 22 characters.  Because of the lower number of
places on the text display, it's easier to deal with for many
people than the graphic display.
  
  
  
9.1
DISP
DISP is simple.  It displays the string in level 2 on the line
number in level 1.  
Syntax: (number) DISP
Example: \<< "hello." 1 DISP \>>
  
If you tried that, you didn't see the message.  That's because it
got covered up by the updating screen.  That's why we have
FREEZE.
  

9.2
FREEZE--companion to DISP
FREEZE keeps an area in the LCD from being updated.  It works
from a code for areas of the
screen.  They are as follows:
  
Number  Area
1       Status area (top)
2       Stack and command line (middle)
3       Status and stack/command line (middle and top)
4       Menu (very bottom)
5       Menu and status area (very bottom and top)
6       Menu and stack/command line (bottom and middle)
7       Whole display

Syntax is similar to DISP.  It takes the number code from level
1.
Example:  \<< "hello." 1 DISP 1 FREEZE \>>
  
9.3
MSGBOX
A new (G series) command, MSGBOX is for avoiding display
headaches.  It takes a string and puts it in a box --3d over the
stack, and lets the user press {OK} when ready.  MSGBOX is pretty
friendly to strings--it tries to only break them at spaces--but
it's not perfect.  
  
9.4
BEEP
BEEP just beeps.  It takes frequency and duration from the stack
and, if the proper flag is true, beeps.  It beeps loudly on G's. 
It's annoying.
Syntax: (freq) (time) BEEP
Example: \<< 800 .5 BEEP \>>
  
Now for the others.  
A note on graphics--I'm not going to teach you graphics.  If
you've read this far just so you can learn graphics, i'm sorry. 
You can learn graphics (and a lot more) from a book called
"Graphics on the HP48G/GX" by R. Ray Depew.  I don't know him and
i'm not promoting his book, but (surprise, surprise) you can
learn graphics in that book.  
  
9.5
PVIEW
Takes the coordinates of the upper-left corner of the display and
shows it.  
Syntax : { #(xcoord) #(ycoord) } PVIEW
Example:  \<< { #0d #0d } PVIEW \>>
  
9.6
TEXT
A simple command--takes no arguments or anything.  Just returns
to the text display.
  
  
9.7
CLLCD clears the screen.  Useful before DISP.  Does not clear the
actual stack or PICT, just the
LCD.  Takes no arguments. 
  
10.0
Stack stuff
In a program, stack commands prove some of the most useful for
data manipulation. I blatantly
pull this from Michael Heinz's article "The Interactive Stack"
from issue 1, no. 1 of the HP48
Newsletter, with some editations suggested by Joe K. Horn.
  
10.1 
PICK 
 
Pick will copy the current stack item and place that copy at the
bottom of the stack.
For example, enter the numbers one through six onto the stack.
(You can do this by typing 1 ENTER 2 ENTER 3 ENTER 4 ENTER 5
ENTER 6 ENTER or by typing the numbers 1 2 3 4 5 6, separated by
spaces, and pressing ENTER once.)
      Now, press 3 for the third stack level. Press PICK. Now the
stack reads
      1 2 3 4 5 6 4.  
  Syntax: (level) PICK
  
  10.2
  ROLL 
  
      Roll will "roll" the stack items so that the current item
is moved to the bottom. For example, clear the stack, then type 1
2 3 4 5 6 ENTER. (Make sure to press SPC between each number.)
Now press 4, for the 4th stack level. Press ROLL. The stack
should now read 1 2 4 5 6 3.
  Syntax: (level) ROLL
  
  10.3
  ROLLD 
  
Rolld rolls the stack in the opposite direction from Roll. In
other words, it will move the bottom of the stack to the current
item, while moving the current item and everything else down one
place. To use the previous example; clear the stack and type
1 2 3 4 5 6 ENTER, pressing SPC between each number. Now press 4,
for the fourth stack level.. Press ROLLD. The stack will now read
1 2 6 3 4 5.
Syntax: (level) ROLLD
 
 
10.4
DUPN 
This key makes a copy of the entire stack, up to the item you
have selected, and places that copy at the bottom of the stack.
To continue using our example, place the numbers 1 2 3 4 5 6 on
the stack, then press 3, for the third down levels of the stack.
Press DUPN. The stack will now contain 1 2 3 4 5 6 4 5 6. 
  Syntax: (level) DUPN
  
10.5
DRPN 
  
Drpn is an abbreviation for "Drop N items". To use it, select the
level (from here down), then press DRPN. The selected item, and
everything after it, will be erased. For example: if you put the
numbers 1 2 3 4 5 6 on the stack, then press 4 and DRPN, the
stack will read 1 2.
Syntax: (level) DRPN
  
10.6
KEEP 
  
KEEP drops everything *above* the selected stack item, keeping it
*and everything below it* intact.  I think of it as the flip side
of DROPN. (-jkh)
Syntax: (level) KEEP
--end of selection from Michael Heinz's article
  
10.7 
ROT
ROT handles the bottom 3 levels of the stack.  It is just like a
3 ROLLD, but faster.  In fact, try to use ROT whenever possible
instead of 3 ROLLD.  
Syntax: ROT
  
10.8
SWAP
SWAP puts the item on level 2 on 1 and 1 on 2.  A very useful
function.
Syntax: SWAP
  
10.9
DROP
Removes level 1's data and pushes level 2 to 1, 3 to 2, and so
on.
  
10.10
DUP
Duplicates the item on level 1, pushes everything up to make room
for the new item.
  
10.11 
DUP2
Duplicates items on level 2 and 1, in order.  
  
10.12
DROP2
Drops items 1 and 2.
  
  
11.0
Closing Note
Well, here marks the end of version 0.10 of the Unofficial
User-RPL Programmer's Guide.  Email questions, comments, flames,
and corrections to dossey@ou.edu or president@whitehouse.gov
(I think you'll get a more satisfying result from the former,
though.)
  
Hope this helps!
  
