home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 3 Comm / 03-Comm.zip / tt2man.zip / ttautod.doc < prev    next >
Text File  |  1993-12-13  |  52KB  |  1,368 lines
  1.  
  2.                              TABLE OF CONTENTS                              
  3.  
  4.  
  5.           C. Appendix C - AUTOPILOT Migration From      DOS
  6.             C.1 Overview
  7.             C.2 Support For DOS PC Screen Statements
  8.             C.3 DOS Compatible Statements And Functions
  9.               C.3.1 CLS Statement
  10.               C.3.2 COLOR Statement
  11.               C.3.3 CREATE TEXT_WINDOW Statement
  12.               C.3.4 DISPLAY Statement
  13.               C.3.5 KEYBOARD_INFO Function
  14.               C.3.6 KEYBOARD_POLL Function
  15.               C.3.7 LOCATE PC_CURSOR Statement
  16.               C.3.8 MOUSE_INFO Function
  17.               C.3.9 MOUSE_POLL Function
  18.               C.3.10 ON Statement
  19.               C.3.11 PC_CURSOR_COLUMN Function
  20.               C.3.12 PC_CURSOR_ROW Function
  21.               C.3.13 PC_KEY Function
  22.               C.3.14 PC_SCREEN Function
  23.               C.3.15 PC_SCREEN_CHARATTR Function
  24.               C.3.16 PROMPT Statement
  25.               C.3.17 RESUME Statement
  26.               C.3.18 SET Statement
  27.  
  28.              C. Appendix C - AUTOPILOT Migration From      DOS              
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.                                 C.1 Overview                                
  36.  
  37.  
  38. One of the main design objectives in developing AUTOPILOT for OS/2  was  the
  39. easy migration of AUTOPILOT applications developed under DOS.    Because  of
  40. the differences in the environments, though, this goal  was  not  absolutely
  41. obtained.  Below is a list of some of the considerations regarding this:
  42.  
  43. 1. The OS/2 environment offers  a  graphical,  multi-sessioning  environment
  44.    entirely foreign to standard DOS.  The  AUTOPILOT  DOS  product  contains
  45.    numerous Statements and Functions which:
  46.  
  47.   - deal with the PC Screen as a fixed font, 80 column, 25 row screen
  48.   - sense the keyboard
  49.   - sense the mouse
  50.  
  51.   ALL of these Statements and Functions still function under  OS/2  but  not
  52.   in a manner totally integrated with the new environment.  If you  wish  to
  53.   continue to use these Statements and  Functions,  they  are  described  in
  54.   detail in the next section, Support For DOS AUTOPILOT Statements.
  55.  
  56. 2. ALL  AUTOPILOT  communications  under  OS/2  are  supported  through  the
  57.    EHLLAPI interface.    Therefore,  ALL  communications  Statements  except
  58.    those dealing with the DOS EHLLAPI  environment,  are  no  longer  valid.
  59.    This includes support  for  the  EMULATE  Statement.    To  identify  the
  60.    communications environment under OS/2,  the  CONNECT  Statement  MUST  BE
  61.    used.
  62.  
  63. 3. Since all communications are through EHLLAPI,  the  EXIT  HOLD  Statement
  64.    has no function.
  65.  
  66. 4. The DOS RUN DOS Statement is now a RUN SYSTEM Statement.
  67.  
  68.  
  69.  
  70.  
  71.                   C.2 Support For DOS PC Screen Statements                  
  72.  
  73.  
  74. Since AUTOPILOT was originally developed under PC/DOS, it  contains  a  wide
  75. variety of functions which assume  a  PC/DOS  Screen.    So  as  to  provide
  76. compatibility  and  portability  between  OS/2  and  PC/DOS,  AUTOPILOT
  77. applications are, by default, provided a  Presentation  Manager  window  the
  78. exact size of a PC Screen (80 Columns/25 Rows). A fixed font is utilized  so
  79. that Row/Column coordinates are consistent throughout  the  window.    Also,
  80. where PC/DOS  Screen  field  attributes  are  referenced  in  the  AUTOPILOT
  81. syntax,  AUTOPILOT  automatically  translates  the  OS/2  field  display
  82. attributes to be compatible.
  83.  
  84. Therefore,  the  AUTOPILOT  Statements  And  Functions  described  in  this
  85. appendix, although originally intended for use in  the  PC/DOS  environment,
  86. are perfectly acceptable  and  functional  under  OS/2  without  losing  the
  87. benefits of  multi-tasking  and  aesthetics  provided  by  the  Presentation
  88. Manager.  They are discussed separately from the other AUTOPILOT  Verbs  and
  89. Functions so as to simplify your use of AUTOPILOT in  building  Presentation
  90. Manager Dialog Windows.  The  Dialog  Windows  discussed  in  the  AUTOPILOT
  91. Statement Reference chapter will be used for the  majority  of  applications
  92. you develop for OS/2.
  93.  
  94. The functions available to your AUTOPILOT program for interacting with  OS/2
  95. and the Presentation Manager window in a DOS Compatibility Mode include:
  96.  
  97.  - Creating and supporting a Presentation Manager based text window  with  a
  98.    fixed font which will emulate the PC Screen in the DOS environment.
  99.  
  100.  - Establishing foreground and background colors for the display.
  101.  
  102. The following functions provide information when the  AUTOPILOT  window  has
  103. the FOCUS.
  104.  
  105.  - Prompting for keystrokes or text information from the keyboard.
  106.  
  107.  - Polling the keyboard to see if keystrokes are  available,  thus  allowing
  108.    other processing to occur during keyboard entry.
  109.  
  110.  - Polling the status of the  MOUSE  to  determine  current  MOUSE  position
  111.    (row/column) and the position of the left and right buttons.
  112.  
  113.  
  114.  
  115.  
  116.                 C.3 DOS Compatible Statements And Functions                 
  117.  
  118.  
  119.  
  120. ┌─────────────────────┐
  121. │ C.3.1 CLS Statement │
  122. └─────────────────────┘
  123.  
  124.   Purpose:
  125.  
  126.   Clears the window.
  127.  
  128.   Format:
  129.  
  130.   ┌──────────────────────────────────────────────────────────────────────┐
  131.   │ CLS                                                                  │
  132.   │                                                                      │
  133.   │ CLS [ FROM <row> <col> [TO <row> <col> ] ]                           │
  134.   └──────────────────────────────────────────────────────────────────────┘
  135.  
  136.   Remarks:
  137.  
  138.   The CLS Statement clears the window to the background color  specified  in
  139.   a previous COLOR Statement (see COLOR Statement in this chapter).   If  no
  140.   COLOR Statement has been issued, the default window color is used.
  141.  
  142.   The CLS Statement also returns the cursor  to  the  home  position  (upper
  143.   left-hand corner of the screen).
  144.  
  145.   The CLS Statement with the FROM clause may be used to clear a  portion  of
  146.   the screen. The portion cleared is defined as a rectangle starting at  the
  147.   FROM position and going to the TO position. If  the  TO  position  is  not
  148.   specified, the end of the screen is used (25,80).
  149.  
  150.   Examples:
  151.  
  152.       CLS
  153.  
  154.   The above example clears the entire screen.
  155.  
  156.       CLS FROM 1, 60 TO 5, 80
  157.  
  158.   In the above example of the  CLS  statement  with  the  FROM  clause,  the
  159.   result would be to clear the last 20 columns of the first 5 lines  on  the
  160.   screen.
  161.  
  162.   See Also:
  163.  
  164.     COLOR
  165.     DISPLAY
  166.  
  167. ┌───────────────────────┐
  168. │ C.3.2 COLOR Statement │
  169. └───────────────────────┘
  170.  
  171.   Purpose:
  172.  
  173.   Set the foreground and background colors and optionally modify  the  color
  174.   on a portion of the window.
  175.  
  176.   Format:
  177.  
  178.   ┌──────────────────────────────────────────────────────────────────────┐
  179.   │ COLOR [<foreground> [,<background>]]                                 │
  180.   │    [FROM <row> <col> [TO <row> <col>  ] ]                            │
  181.   └──────────────────────────────────────────────────────────────────────┘
  182.  
  183.   Remarks:
  184.  
  185.   <foreground> and <background> are numbers in  the  range  0  to  15  which
  186.   represent the colors to be used.
  187.  
  188.   When the FROM/TO clause IS NOT specified, the COLOR Statement is  used  to
  189.   control the use of  foreground  and  background  colors  within  the  CLS,
  190.   DISPLAY, and PROMPT Statements.
  191.  
  192.   CLS, DISPLAY, and PROMPT Statements that follow  a  COLOR  Statement  will
  193.   use  the  new  foreground  and  background  setting  until  another  COLOR
  194.   Statement is encountered.
  195.  
  196.   The foreground and background  colors  on  the  current  display  are  not
  197.   affected until a subsequent CLS, DISPLAY, or PROMPT Statement is issued.
  198.  
  199.   When the FROM/TO  clause  IS    specified,  the  color  in  the  rectangle
  200.   specified by the FROM/TO range  is  modified  immediately.    The  FROM/TO
  201.   clause WILL NOT modify the color usage  in  subsequent  CLS,  DISPLAY,  or
  202.   PROMPT Statements.  If the TO clause is not  specified,  the  end  of  the
  203.   window is assumed.
  204.  
  205.   Examples:
  206.  
  207.   Example 1:
  208.  
  209.   All the options on the COLOR Statement  are  optional.  If  they  are  not
  210.   specified, the current color setting is not changed. For example:
  211.  
  212.      COLOR 2,7
  213.           - changes the foreground and background colors
  214.      COLOR 2
  215.           - changes the foreground color only
  216.      COLOR ,7
  217.           - changes the background color only
  218.  
  219.   Example 3:
  220.  
  221.   If the COLOR Statement is specified without any  options,  the  foreground
  222.   and background border colors are set to the default window color.
  223.  
  224.   Example 4:
  225.  
  226.   With a Color Graphics Monitor
  227.  
  228.   With a color graphics monitor adapter the following colors are displayed:
  229.  
  230.                   0     Black    8   Gray                  
  231.                   1     Blue     9   Light Blue            
  232.                   2     Green    10  Light Green           
  233.                   3     Cyan     11  Light Cyan            
  234.                   4     Red      12  Light Red             
  235.                   5     Magenta  13  Light Magenta         
  236.                   6     Brown    14  Yellow                
  237.                   7     White    15  High Intensity White  
  238.  
  239.   See Also:
  240.  
  241.     CLS
  242.  
  243. ┌────────────────────────────────────┐
  244. │ C.3.3 CREATE TEXT_WINDOW Statement │
  245. └────────────────────────────────────┘
  246.  
  247.   Purpose:
  248.  
  249.   The CREATE TEXT_WINDOW Statement  is  used  in  the  OS/2  environment  to
  250.   define a  Presentation  Manager  window  to  display  fixed  font  textual
  251.   information.    This  Statement  is  primarily  used  to  provide  upward
  252.   compatibility for AUTOPILOT applications created under PC/DOS or MS/DOS.
  253.  
  254.   Format:
  255.  
  256.   ┌──────────────────────────────────────────────────────────────────────┐
  257.   │ CREATE TEXT_WINDOW <window-number>                                   │
  258.   │                  [ VISIBLE | INVISIBLE ]                             │
  259.   │                  [ ENABLED | DISABLED ]                              │
  260.   │                  [ MINIMIZED | MAXIMIZED ]                           │
  261.   │                  [ ESCAPE <label> ]                                  │
  262.   │                  [ KEY <keylist> <label> ]                           │
  263.   │                  [ TITLE_BAR <title-string> ]                        │
  264.   │                  [ BORDER <bordertype ]                              │
  265.   │                  [ ICON <iconfilespec> ]                             │
  266.   │                  [ TASK_LIST ]                                       │
  267.   │                  [ SYSTEM_MENU ]                                     │
  268.   │                  [ MINIMIZE_BUTTON ]                                 │
  269.   │                  [ MAXIMIZE_BUTTON ]                                 │
  270.   │                  [ HORIZONTAL_SCROLL_BAR ]                           │
  271.   │                  [ VERTICAL_SCROLL_BAR ]                             │
  272.   │                  [ DEFAULT_COLOR <fgnd> [,] <bkgnd ]                 │
  273.   │                  [ TEXT_SIZE <rows> [TEXT_ROWS    ] [,]              │
  274.   │                              <cols> [TEXT_COLUMNS ] ]                │
  275.   │                                                                      │
  276.   │   [ WINDOW_SIZE <rows> [ { TEXT_ROWS  } ]                            │
  277.   │                        [ { DEVICE_ROWS } ] │                         │
  278.   │                        [ { DIALOG_ROWS } ] [,]                       │
  279.   │                 <cols> [ { TEXT_COLUMNS]  } ]                        │
  280.   │                        [ { DEVICE_COLUMNS } ]                        │
  281.   │                        [ { DIALOG_COLUMNS } ]                        │
  282.   │   [ WINDOW_POSITION [ DEVICE_ROW[S] ] <row> [,]                      │
  283.   │                     [ DEVICE_COLUMN[S] ] <col> ]                     │
  284.   │   [ ACTION <label> ]                                                 │
  285.   │   [ ACTION_BAR_MENU clause ]                                         │
  286.   │   [ FONT clause ]                                                    │
  287.   │ END_CREATE                                                           │
  288.   └──────────────────────────────────────────────────────────────────────┘
  289.  
  290.   Remarks:
  291.  
  292.   The CREATE TEXT_WINDOW Statement is used to define a Presentation  Manager
  293.   text window.    Multiple  CREATE  Statements  can  be  used  in  a  single
  294.   AUTOPILOT program.  To indicate which text window is current, use the  SET
  295.   CURRENT_WINDOW Statement.
  296.  
  297.   <window-number>
  298.           may be either:
  299.  
  300.     1. An integer expression such that 0 < <window-number> < 100.
  301.  
  302.     2. A Symbol set to zero. If this is the case, the symbol will be set  to
  303.        a free window number.
  304.  
  305.   VISIBLE/INVISIBLE
  306.    The initial visibility state of may be set by the  VISIBLE  or  INVISIBLE
  307.    keyword. The default is VISIBLE. The  visibility  state  may  be  changed
  308.    after window creation by using the SHOW TEXT_WINDOW Statement.
  309.  
  310.   ENABLED/DISABLED
  311.    The initial selectability state of the TEXT_WINDOW  may  be  set  by  the
  312.    ENABLED or DISABLED keyword. The default is  ENABLED.  The  selectability
  313.    state  may  be  changed  after  window  creation  by  using  the  ENABLE
  314.    TEXT_WINDOW or  DISABLE  TEXT_WINDOW  Statements.  If  a  TEXT_WINDOW  is
  315.    DISABLED, it will not receive focus.
  316.  
  317.   MINIMIZED/MAXIMIZED
  318.    The initial size of the window may be set by the MINIMIZED  or  MAXIMIZED
  319.    clause.  The default is neither -- the initial size of the window is  set
  320.    by the WINDOW_SIZE clause.  The MINIMIZE or  MAXIMIZE  Statement  can  be
  321.    used after window creation to change this state.
  322.  
  323.   ESCAPE
  324.    The ESCAPE clause may be  used  to  initially  set  the  ESCAPE  handling
  325.    routine. It may be changed after window creation by using the  ON  ESCAPE
  326.    command.
  327.  
  328.   KEY <key<E>list>
  329.    The KEY clause may be used to set KEY trapping handling routines. It  may
  330.    be changed or added  to  after  window  creation  by  using  the  ON  KEY
  331.    command. <keylist> is a list of scan codes for PC keys  which  should  be
  332.    recognized.  By  INCLUDEing  the  file  TT_PCKEY.INC  in  your  AUTOPILOT
  333.    program, you may refer to the  keys  by  name  (i.e.  _F1,  _F12,  etc.).
  334.    <label> is the label of a routine in your AUTOPILOT  program  to  receive
  335.    control when the specified key(s) pressed.
  336.  
  337.   TITLE_BAR
  338.    Adds a title bar to the window. <title-string> is  required  but  may  be
  339.    set to "".  If the TITLE_BAR clause is not included, no  title  bar  will
  340.    be included.
  341.  
  342.   BORDER
  343.    Determines the type of border the window will have. <bordertype> may be:
  344.  
  345.     0  - No border
  346.     1  - Size border
  347.     2  - dialog border
  348.     3  - Standard border
  349.  
  350.    If this clause is not included, the window will have no border.
  351.  
  352.   ICON
  353.    Sets the window's icon to  the  icon  specified  by  <iconfilespec>.  The
  354.    default  directory  for  the  icon  is  set  by  the  ICON_DIRECTORY
  355.    Customization Variable. This  variable  may  be  viewed  or  modified  by
  356.    selecting System Configuration from the Utilities Pull Down Menu  on  any
  357.    Phone Book. If this clause is not specified, the icon will be set to  one
  358.    of the standard OS/2 icons by the window procedure.
  359.  
  360.   MSGLINE
  361.    Sets the windows message line.  The message line  is  where  DISPLAY  and
  362.    PROMPT Statements are directed if no AT clause is specified  (the  entire
  363.    line is erased first). If MSGLINE  is  set  to  zero,  the  displays  and
  364.    prompts start at the position where the last display/prompt ended.
  365.  
  366.   TASK_LIST
  367.    A window may put itself on the OS/2 Task  List  by  using  the  TASK_LIST
  368.    clause.  By default, the window WILL NOT be put on the Task List.
  369.  
  370.   SYSTEM_MENU
  371.   MINIMIZE_BUTTON
  372.   MAXIMIZE_BUTTON
  373.   HORIZONTAL_SCROLL_BAR
  374.   VERTICAL_SCROLL_BAR
  375.    Includes the specified component in the window. If  the  keyword  is  not
  376.    specified, the component is not included.
  377.  
  378.   DEFAULT_COLOR
  379.    Establishes the default color for a window  (i.e.  The  color  that  text
  380.    will appear if there are no COLOR Statements).
  381.    
  382.    In addition, this statement effectively defines the background color  for
  383.    that portion of a window that is displayed  that  exceeds  the  TEXT_SIZE
  384.    area.
  385.    
  386.    If not specified, the default color is black on white (0,15)
  387.  
  388.   TEXT_SIZE
  389.    Defines a text region size.
  390.    
  391.    The text region is the area of the window that can  be  modified  by  the
  392.    DISPLAY, PROMPT, COLOR, etc. Statements.
  393.    
  394.    The  default  and  only  valid  coordinate  types  are  TEXT_ROWS  and
  395.    TEXT_COLUMNS  (see  Coordinate  System  discussed  under  CREATE
  396.    DIALOG_WINDOW).
  397.  
  398.   WINDOW_SIZE
  399.    Defines  the window size
  400.    
  401.    The default  coordinate  type  is  TEXT_ROWS  and  TEXT_COLUMNS.    Valid
  402.    coordinate  types  are  TEXT_ROWS,  TEXT_COLUMNS,  DIALOG_ROWS,
  403.    DIALOG_COLUMNS, DEVICE_ROWS, and DEVICE_COLUMNS  (see  Coordinate  System
  404.    discussed under CREATE DIALOG_WINDOW in the Chapter, AUTOPILOT  Statement
  405.    Reference).
  406.  
  407.   WINDOW_POSITION
  408.    Defines the window position relative to its parent.
  409.    
  410.    The default  and  only  valid  coordinate  types  are  DEVICE_ROW[S]  and
  411.    DEVICE_COLUMN[S]  (see  Coordinate  System  discussed  under  CREATE
  412.    DIALOG_WINDOW in the Chapter, AUTOPILOT Statement Reference).
  413.  
  414.   ACTION
  415.    Allows you to specify a  label  in  your  AUTOPILOT  program  to  receive
  416.    control if one of the following conditions are true:
  417.  
  418.     1. The SYSTEM MENU Item Close is requested.
  419.  
  420.     2. A PULLDOWN is requested (see ACTION_BAR_MENU clause under the  CREATE
  421.        DIALOG_WINDOW Statement) with no associated ACTION.
  422.  
  423.     3. A CHOICE is requested (see ACTION_BAR_MENU clause  under  the  CREATE
  424.        DIALOG_WINDOW  Statement  in  the  Chapter  AUTOPILOT  Statement
  425.        Reference) with no  associated  ACTION  and  no  associated  PULLDOWN
  426.        ACTION.
  427.  
  428.    See the discussion  under  the  CREATE  DIALOG_WINDOW  Statement  in  the
  429.    Chapter, AUTOPILOT Statement Reference on the ACTION_BAR_MENU clause  for
  430.    more information on PULLDOWN and CHOICE ACTIONs.
  431.  
  432.   ACTION_BAR_MENU
  433.    See  the  discussion  on  the  ACTION_BAR_MENU  clause  under  CREATE
  434.    DIALOG_WINDOW in the Chapter,  AUTOPILOT  Statement  Reference  for  more
  435.    information on the format and processing provided.
  436.  
  437.   FONT <font-specification>
  438.    The FONT clause allows you to specify an alternate font  to  be  used  by
  439.    this text window.  By default, AUTOPILOT will use  the  TalkThru  default
  440.    font (currently  the  TalkThru  7x10  fixed  font)  for  any  TEXT_WINDOW
  441.    created.  The format of this clause is:
  442.  
  443.   ┌──────────────────────────────────────────────────────────────────────┐
  444.   │ FONT [ FACENAME = <face> ]                                           │
  445.   │      [ SIZE=<size> ]                                                 │
  446.   │      [ CODEPAGE=<cp> ]                                               │
  447.   │      [ BOLD  ]                                                       │
  448.   │      [ ITALICS ]                                                     │
  449.   │      [ UNDERLINE ]                                                   │
  450.   │      [ STRIKE OUT ]                                                  │
  451.   └──────────────────────────────────────────────────────────────────────┘
  452.  
  453.    FACENAME=<face> selects the font. It  may  be  a  TalkThru  font  or  any
  454.    public fixed  space  font  such  as  Courier  or  System  Monospaced.  If
  455.    FACENAME is not specified it defaults to TalkThru.
  456.  
  457.    SIZE=<size>is used to specify the size of the font. It can  be  specified
  458.    as wXh where w is the  width  in  pels  and  h  is  the  height  in  pels
  459.    (example: SIZE=7x10 or SIZE=8X13). The keywords SMALL, MEDIUM, LARGE  may
  460.    also be used (example SIZE=LARGE). The use of these keywords will  insure
  461.    that the font is about the same size regardless  of  display  resolution.
  462.    The default is SIZE=SMALL.
  463.  
  464.    CODEPAGE=<cp> can be used to select a specific  codepage  for  a  window.
  465.    For example CODEPAGE=850 or CODEPAGE=437. The  default  ,codepage  for  a
  466.    window is the default codepage for the system.
  467.  
  468.    One or more of the attributes BOLD,  ITALICS,  UNDERLINE,  and  STRIKEOUT
  469.    can be used to modify the appearance of the font.  By  default,  none  of
  470.    these attributes are included. (Note:  the  use  of  BOLD  will  slightly
  471.    increase the size of the font).
  472.  
  473.   See Also:
  474.  
  475.     SET DEFAULT_COLOR
  476.  
  477.   Also, see the following statements discussed  in  the  Chapter,  AUTOPILOT
  478.   Statement Reference.
  479.  
  480.     ACTION_WINDOW
  481.     ACTION_TYPE
  482.     ACTION_ID
  483.     ADD TO
  484.     CLOSE
  485.     DISABLE
  486.     ENABLE
  487.     HIDE
  488.     MINIMIZE/MAXIMIZE/RESTORE
  489.     OPEN
  490.     REMOVE FROM
  491.     RESUME ACTION
  492.     SHOW
  493.     SET PULLDOWN
  494.     SET CHOICE
  495.     SET TITLE_BAR
  496.     SET WINDOW_SIZE
  497.     SET WINDOW_POSITION
  498.     SET CURRENT_WINDOW
  499.     WAIT FOR ACTION
  500.  
  501. ┌─────────────────────────┐
  502. │ C.3.4 DISPLAY Statement │
  503. └─────────────────────────┘
  504.  
  505.   Purpose:
  506.  
  507.   Displays information on the window.
  508.  
  509.   Format:
  510.  
  511.   ┌──────────────────────────────────────────────────────────────────────┐
  512.   │ DISPLAY [CHARATTR] <text>                                            │
  513.   │          [AT <row> <col>]                                            │
  514.   │           [FROM <row> <col> [ TO <row>] ]                            │
  515.   │                [, <text>                                             │
  516.   │          [ AT <row> ]                                                │
  517.   │            [ FROM <row> <col> [ TO < row> <col> ] ] ]                │
  518.   └──────────────────────────────────────────────────────────────────────┘
  519.  
  520.   Remarks:
  521.  
  522.   CHARATTR
  523.         is a keyword indicating that <text> is a variable created using  the
  524.         PC_SCREEN  CHARATTR  Function  and  contains  PC  Video  data  for
  525.         redisplay on the window.
  526.  
  527.   <text>
  528.       is a string value that contains the characters to be displayed.
  529.  
  530.   <row>
  531.       is a number in the range 1 to n (where n is 25 or the number of  lines
  532.       indicated in the  CREATE  TEXT_WINDOW  Statement).  It  indicates  the
  533.       window line number where the text is to be displayed.
  534.  
  535.   <col>
  536.       is a number in the range 1 to n (where n is 80 or the number of  lines
  537.       indicated in  the  CREATE  TEXT_WINDOW  Statement.  It  indicates  the
  538.       screen column number where the text is to be displayed.
  539.  
  540.   The value of <text> is displayed on the window.
  541.  
  542.   If the optional AT clause is omitted, the text will be  displayed  at  the
  543.   location specified by MSGLINE. (See the SET Statement).  The  entire  line
  544.   will be cleared prior to displaying the text.  If MSGLINE =  0,  then  the
  545.   display will start where the last DISPLAY or PROMPT ended.
  546.  
  547.   MSGLINE = 0  is  the  default  if  the  window  was  created  with  CREATE
  548.   TEXT_WINDOW, but MSGLINE = 25 is the default for the PC/DOS  compatibility
  549.   window.
  550.  
  551.   If the AT  clause  is  specified,  the  text  will  be  displayed  at  the
  552.   indicated position and the line will be cleared ONLY  for  the  length  of
  553.   <text>.
  554.  
  555.   If the FROM/TO clause is specified, <text> will be displayed in  the  form
  556.   of a rectangle formed by the FROM/TO coordinates.  If  the  TO  clause  is
  557.   not specified, it defaults to the end of the screen. If <text> is not  big
  558.   enough to fill the rectangle, it is replicated; if it is too  big,  it  is
  559.   truncated.
  560.  
  561.   Multiple <text> values can be displayed with  a  single  DISPLAY  verb  by
  562.   separating them by a comma.   This  improves  the  speed  of  the  overall
  563.   display process.
  564.  
  565.   Examples:
  566.  
  567.   Example 1:
  568.  
  569.   This example  displays  "Creating  Extract"  on  line  25.  Prior  to  the
  570.   display, line 25 is erased.
  571.  
  572.       DISPLAY "Creating Extract"
  573.  
  574.   Example 2:
  575.  
  576.   This example displays the contents of  identifier  user_name  at  the  row
  577.   indicated by the value of identifier r_val and column 1.
  578.  
  579.       DISPLAY user_name at r_val , 1
  580.  
  581.   Example 3:
  582.  
  583.   This example displays a rectangle defined by a capital X.   The  rectangle
  584.   will go from row 10 column 40 to row 15 column 50.
  585.  
  586.       DISPLAY "X" FROM 10 40 TO 10 50 ,
  587.       "X" & str_replicate(" ",9) & "X" FROM 11 40 TO 14 50 ,
  588.       "X" FROM 15 40 TO 15 50
  589.  
  590.   Example 4:
  591.  
  592.   This example will save a portion of the window defined  by  the  rectangle
  593.   from row 10, column 40 to row 15, column 50 and redisplay it later in  the
  594.   program.
  595.  
  596.       set t_screen = PC_SCREEN_CHARATTR(10,40,15,50)
  597.           .
  598.           .
  599.           .
  600.     refresh:
  601.       display CHARATTR t_screen FROM 10 , 40 TO 15 ,~5 0
  602.  
  603.   See Also:
  604.  
  605.     CLS
  606.     COLOR
  607.  
  608.     PC_SCREEN
  609.     PC_SCREEN_CHARATTR
  610.  
  611. ┌──────────────────────────────┐
  612. │ C.3.5 KEYBOARD_INFO Function │
  613. └──────────────────────────────┘
  614.  
  615.   Purpose:
  616.  
  617.   To return the current status of the PC keyboard.
  618.  
  619.   Format:
  620.  
  621.   ┌──────────────────────────────────────────────────────────────────────┐
  622.   │ KEYBOARD_INFO(<request>)                                             │
  623.   └──────────────────────────────────────────────────────────────────────┘
  624.  
  625.   Remarks:
  626.  
  627.   Returns a value depending on the <request>.  This function can be used  to
  628.   "POLL" the PC keyboard without having to issue the PROMPT Statement.
  629.  
  630.   The INCLUDE file TT_PCKEY.INC has been provided containing global  equates
  631.   to the possible <request>  values.    Below  is  a  table  indicating  the
  632.   possible <request> values, the global equates and their meanings:
  633.  
  634.   Request  Global Equate  Meaning
  635.   ───────  ─────────────  ──────────────────────────────────────────────────
  636.     0      KBDTYPE        1 - extended  keyboard  is present
  637.                           0 - keyboard is not extended
  638.     1      KBDBIOS        Returns the next  BIOS  scan  code/character  code
  639.                           from  the  keyboard  buffer  (the  keystroke  is
  640.                           removed from the buffer). 
  641.  
  642.                           Will  wait  for  a key to  be  pressed  if  the  
  643.                           keyboard  buffer  is empty.    Usually  used  in  
  644.                           conjunction  with KEYBOARD_POLL
  645.     2      KBDSHIFT       Returns an integer bit mask  that  represents  the
  646.                           current  keyboard  shift  status  as
  647.                           follows:
  648.  
  649.                           Bit 0 = 1 - Right Shift Key pressed
  650.                           Bit 1 = 1 - Left Shift Key pressed
  651.                           Bit 2 = 1 - CTRL Key pressed
  652.                           Bit 3 = 1 - ALT Key pressed
  653.                           Bit 4 = 1 - Scroll Lock locked
  654.                           Bit 5 = 1 - Num Lock locked
  655.                           Bit 6 = 1 - Caps  Lock locked
  656.                           Bit 7 = 1 - Insert locked
  657.  
  658.   WARNING:
  659.        KEYBOARD_INFO and KEYBOARD_POLL will only  work  effectively  if  the
  660.        following two statements are included in your AUTOPILOT program:
  661.        
  662.        ON ESCAPE OFF
  663.        ON KEY OFF
  664.  
  665.   Example:
  666.  
  667.   The following code will check to see if a keystroke is  available  in  the
  668.   buffer and, if present, will accept it and verify that  it  is  the  Enter
  669.   Key, The Escape Key, or a valid capital letter:
  670.  
  671.       include "TT_PCKEY.INC"
  672.               .
  673.       if KEYBOARD_POLL > 0
  674.         begin
  675.           set t_key = KEYBOARD_INFO(KBDBIOS)
  676.           set t_char = str_chr(t_key)
  677.           if t_key <> _ENTER and
  678.           t_key <> _ESC and
  679.           ( t_char < "A" or
  680.           ( t_char > "Z" ) goto bad_key
  681.         end
  682.  
  683.   See Also:
  684.  
  685.     KEYBOARD_POLL
  686.     PROMPT KEY
  687.     STR_CHAR
  688.  
  689. ┌──────────────────────────────┐
  690. │ C.3.6 KEYBOARD_POLL Function │
  691. └──────────────────────────────┘
  692.  
  693.   Purpose:
  694.  
  695.   To return the current status of the keyboard.
  696.  
  697.   Format:
  698.  
  699.   ┌──────────────────────────────────────────────────────────────────────┐
  700.   │ KEYBOARD_POLL                                                        │
  701.   └──────────────────────────────────────────────────────────────────────┘
  702.  
  703.   Remarks:
  704.  
  705.   Returns a zero (0) if there are NO KEYS in the keyboard buffer.  Otherwise
  706.   it returns the key waiting to be read in  BIOS  scan  code/character  code
  707.   format.  The key IS NOT removed from the buffer.
  708.  
  709.   WARNING:
  710.        KEYBOARD_INFO and KEYBOARD_POLL will only  work  effectively  if  the
  711.        following two statements are included in your AUTOPILOT program:
  712.        
  713.        ON ESCAPE OFF
  714.        ON KEY OFF
  715.  
  716.   Example:
  717.  
  718.   The following code will check to see if a keystroke is  available  in  the
  719.   buffer and, if present, will accept it and verify that  it  is  the  Enter
  720.   Key, The Escape Key, or a valid capital letter:
  721.  
  722.       include "TTPCKEY.INC"
  723.             .
  724.       if KEYBOARD_POLL > 0
  725.         begin
  726.           set t_key = KEYBOARD_INFO(KBDBIOS)
  727.           set t_char = str_chr(t_key)
  728.           if t_key <> _ENTER and
  729.           t_key <> _ESC and
  730.           ( t_char < "A" or
  731.           ( t_char > "Z" ) goto bad_key
  732.         end
  733.  
  734.   See Also:
  735.  
  736.     KEYBOARD_INFO
  737.     PROMPT KEY
  738.     STR_CHAR
  739.  
  740. ┌──────────────────────────────────┐
  741. │ C.3.7 LOCATE PC_CURSOR Statement │
  742. └──────────────────────────────────┘
  743.  
  744.   Purpose:
  745.  
  746.   Used to position the PC Cursor on the text window.
  747.  
  748.   Format:
  749.  
  750.   ┌──────────────────────────────────────────────────────────────────────┐
  751.   │ LOCATE PC_CURSOR AT <row> <col>                                      │
  752.   └──────────────────────────────────────────────────────────────────────┘
  753.  
  754.   Remarks:
  755.  
  756.   This will move the PC Cursor to the position indicated by the AT clause.
  757.  
  758. ┌───────────────────────────┐
  759. │ C.3.8 MOUSE_INFO Function │
  760. └───────────────────────────┘
  761.  
  762.   Purpose:
  763.  
  764.   To return current information on the MOUSE.
  765.  
  766.   Format:
  767.  
  768.   ┌──────────────────────────────────────────────────────────────────────┐
  769.   │ MOUSE_INFO(<request>)                                                │
  770.   └──────────────────────────────────────────────────────────────────────┘
  771.  
  772.   Remarks:
  773.  
  774.   Returns a value depending on the <request>.  The INCLUDE File  TTMOUSE.INC
  775.   has been provided containing global  equates  to  the  possible  <request>
  776.   values.
  777.  
  778.   Below is a table indicating the  possible  <request>  values,  the  global
  779.   equates and their meanings:
  780.  
  781.   Request  Global Equate  Meaning
  782.   ───────  ─────────────  ──────────────────────────────────────────────────
  783.     0      MPRESENT       1 - MOUSE driver is loaded on the PC
  784.                           0 - MOUSE driver is not loaded
  785.     1      MSTATUS        Returns the same status as the last MOUSE_POLL
  786.     2      MHORZ          Returns the current mouse column position
  787.     3      MVERT          Returns the current mouse row position
  788.     4      MHORZ_LP       Returns the mouse  column  position  at  the  last
  789.                           left button press
  790.     5      MVERT_LP       Returns the mouse row position at  the  last  left
  791.                           button press
  792.     6      MHORZ_RP       Returns the mouse  column  position  at  the  last
  793.                           right button press
  794.     7      MVERT_RP       Returns the mouse row position at the  last  right
  795.                           button press
  796.     8      MHORZ_LR       Returns the mouse  column  position  at  the  last
  797.                           left button release
  798.     9      MVERT_LR       Returns the mouse row position at  the  last  left
  799.                           button release
  800.     10     MHORZ_RR       Returns the mouse  column  position  at  the  last
  801.                           right button release
  802.     11     MVERT_RR       Returns the mouse row position at the  last  right
  803.                           button release
  804.  
  805.   Examples:
  806.  
  807.   The following example will move the PC Cursor to follow the  MOUSE  Cursor
  808.   from the time the left button is pressed until it is released.
  809.  
  810.       include "TTMOUSE.INC"
  811.           .
  812.           .
  813.       if MOUSE_POLL bitand MLEFT_PRESSED perform L_move:
  814.           .
  815.           .
  816.           .
  817.     L_move:
  818.       while MOUSE_POLL bitand MLEFT_RELEASED = 0
  819.         set t_col = MOUSE_INFO(MHORZ)
  820.         set t_row = MOUSE_INFO(MVERT)
  821.         locate PC_CURSOR AT t_row , t_col
  822.       end_while
  823.       return
  824.  
  825.   See Also:
  826.  
  827.     MOUSE_POLL
  828.  
  829. ┌───────────────────────────┐
  830. │ C.3.9 MOUSE_POLL Function │
  831. └───────────────────────────┘
  832.  
  833.   Purpose:
  834.  
  835.   To return the current status of the MOUSE.
  836.  
  837.   Format:
  838.  
  839.   ┌──────────────────────────────────────────────────────────────────────┐
  840.   │ MOUSE_POLL                                                           │
  841.   └──────────────────────────────────────────────────────────────────────┘
  842.  
  843.   Remarks:
  844.  
  845.   Returns an integer made up of bit flags.  The  INCLUDE  File  TT_MOUSE.INC
  846.   has been provided containing global equates to the bit  flags  for  easier
  847.   use.
  848.  
  849.   Below is a table indicating the  bit  settings,  the  global  equates  and
  850.   their meanings:
  851.  
  852.   Bit  Global Equate    Meaning
  853.   ───  ───────────────  ────────────────────────────────────────────────────
  854.    0   MLEFT_DOWN       1 - left button is down
  855.                         0 - left button is up
  856.    1   MRIGHT_DOWN      1 - right button is down
  857.                         0 - right  button is up
  858.    2   MLEFT_PRESSED    1 - left button has been pressed since the last 
  859.                             MOUSE_POLL
  860.                         0 - left button has not been pressed
  861.    3   MRIGHT_PRESSED   1 - right button has been pressed since the last 
  862.                             MOUSE_POLL
  863.                         0 - right button has not been pressed
  864.    4   MLEFT_RELEASED   1 - left button has been released since the last 
  865.                             MOUSE_POLL
  866.                         0 - left button has not been released
  867.    5   MRIGHT_RELEASED  1 - right button has been released since the last
  868.                             MOUSE_POLL
  869.                         0 - right button has not been released
  870.    6   MPOS_MOVED       1 - MOUSE cursor has moved since the last 
  871.                             MOUSE_POLL
  872.                         0 - MOUSE cursor has not moved 
  873.  
  874.   Examples:
  875.  
  876.   The following example will move the PC Cursor to follow the  MOUSE  Cursor
  877.   from the time the left button is pressed until it is released.
  878.  
  879.       include "TT_MOUSE.INC"
  880.           .
  881.           .
  882.       if MOUSE_POLL bitand MLEFT_PRESSED perform L_move:
  883.           .
  884.           .
  885.           .
  886.     L_move:
  887.       while MOUSE_POLL bitand MLEFT_RELEASED = 0
  888.         set t_col = MOUSE_INFO(MHORZ)
  889.         set t_row = MOUSE_INFO(MVERT)
  890.         locate PC_CURSOR AT t_row , t_col
  891.       end_while
  892.       return
  893.  
  894.   See Also:
  895.  
  896.     MOUSE_INFO
  897.  
  898.  
  899. ┌─────────────────────┐
  900. │ C.3.10 ON Statement │
  901. └─────────────────────┘
  902.  
  903.   Purpose:
  904.  
  905.   The ON Statement provides  event  trapping  for  PC  Keys  when  they  are
  906.   pressed.
  907.  
  908.   Format:
  909.  
  910.   ┌──────────────────────────────────────────────────────────────────────┐
  911.   │ ON { ESCAPE         } <label>                                        │
  912.   │    { KEY <keylist>  }                                                │
  913.   │                                                                      │
  914.   │ ON { ESCAPE          } RESET                                         │
  915.   │    { KEY <keylist>   }                                               │
  916.   │                                                                      │
  917.   │ ON { KEY     } { ON  }                                               │
  918.   │                { OFF }                                               │
  919.   └──────────────────────────────────────────────────────────────────────┘
  920.  
  921.   Remarks:
  922.  
  923.   When the first format of the ON Statement is executed,  trapping  for  the
  924.   specified key is enabled. When the key is pressed, control is  transferred
  925.   to the <label>. The RESUME Statement  may  be  used  to  return  from  the
  926.   trapping routine. See the RESUME Statement.
  927.  
  928.   After a key trap is taken, trapping is  disabled  (like  an  ON  KEY  OFF)
  929.   until a RESUME  Statement  or  an  ON  KEY  ON  is  executed.  This  keeps
  930.   recursive trapping from happening unless you want it to.
  931.  
  932.   If a PROMPT Statement has a KEY clause it takes precedence over an ON  KEY
  933.   trap.
  934.  
  935.   Format 2 may be used to RESET or  clear  a  key  trap.  If  the  condition
  936.   occurs the default action will take place.  The  default  action  for  the
  937.   ESCAPE key is to cancel  the  script  with  an  appropriate  message.  The
  938.   default action for the KEY  condition  is  to  ignore  that  the  key  was
  939.   pressed.
  940.  
  941.   Format 3 with the OFF  option  temporarily  turns  off  trapping.  The  ON
  942.   option turns it back on with the previous traps active.
  943.  
  944.   The ESCAPE condition occurs when execution is interrupted by pressing  the
  945.   ESCAPE key.
  946.  
  947.   The KEY condition  occurs  when  a  key  specified  in  the  <keylist>  is
  948.   pressed. A list of keys sets up the trap. Keys may be added  to  the  list
  949.   with subsequent ON KEY <keylist> commands. Keys are trapped in  the  order
  950.   specified. The keyword ALL may be used as a key, and it refers to all  the
  951.   currently  untrapped  keys.  Key  values  are  actually  numbers  which
  952.   correspond to OS/2's method of identifying keys.  To  simplify  things,  a
  953.   file has been  provided  (TT_PCKEY.INC  in  the  SCRIPT  directory),  that
  954.   defines many of these key values. See this file for further information.
  955.  
  956.   Examples:
  957.  
  958.       INCLUDE "TT_PCKEY.INC" /* SETs some key values */
  959.  
  960.       ON _F1, _F2, _F3 func_hit
  961.  
  962.       PROMPT "Enter Option ==>> " opt(8)
  963.               .
  964.               .
  965.               .
  966.  
  967.     func_hit:
  968.       DISPLAY "FUNCTION KEY 1, 2, or 3 HIT"
  969.       RESUME KEY RETRY
  970.  
  971.   See Also:
  972.  
  973.     PC_KEY
  974.  
  975. ┌──────────────────────────────────┐
  976. │ C.3.11 PC_CURSOR_COLUMN Function │
  977. └──────────────────────────────────┘
  978.  
  979.   Purpose:
  980.  
  981.   Returns the PC cursor column.
  982.  
  983.   Format:
  984.  
  985.   ┌──────────────────────────────────────────────────────────────────────┐
  986.   │ PC_CURSOR_COLUMN                                                     │
  987.   └──────────────────────────────────────────────────────────────────────┘
  988.  
  989.   Remarks:
  990.  
  991.   This function returns the column position of the PC cursor as a number  in
  992.   the range 1 to 80.
  993.  
  994.   See Also:
  995.  
  996.     LOCATE
  997.     PC_CURSOR_ROW
  998.     RUN SYSTEM
  999.  
  1000. ┌───────────────────────────────┐
  1001. │ C.3.12 PC_CURSOR_ROW Function │
  1002. └───────────────────────────────┘
  1003.  
  1004.   Purpose:
  1005.  
  1006.   Returns the PC cursor row.
  1007.  
  1008.   Format:
  1009.  
  1010.   ┌──────────────────────────────────────────────────────────────────────┐
  1011.   │ PC_CURSOR_ROW                                                        │
  1012.   └──────────────────────────────────────────────────────────────────────┘
  1013.  
  1014.   Remarks:
  1015.  
  1016.   This function returns the row position of the PC cursor  as  a  number  in
  1017.   the range 1 to 25.
  1018.  
  1019.   See Also:
  1020.  
  1021.     LOCATE
  1022.     PC_CURSOR_COLUMN
  1023.     RUN SYSTEM
  1024.  
  1025. ┌────────────────────────┐
  1026. │ C.3.13 PC_KEY Function │
  1027. └────────────────────────┘
  1028.  
  1029.   Purpose:
  1030.  
  1031.   This statement returns the last PC key pressed.
  1032.  
  1033.   Format:
  1034.  
  1035.   ┌──────────────────────────────────────────────────────────────────────┐
  1036.   │ PC_KEY                                                               │
  1037.   └──────────────────────────────────────────────────────────────────────┘
  1038.  
  1039.   Remarks:
  1040.  
  1041.   This function is used to return the last PC key pressed which was  trapped
  1042.   via the ON KEY Statement or was hit during a PROMPT Statement.
  1043.  
  1044.   See the ON KEY Statement.
  1045.  
  1046.   Example:
  1047.  
  1048.       INCLUDE "TTPCKEY.INC"
  1049.       PROMPT KEY _F1 , _F2 , _F3 , _ENTER
  1050.       IF PC_KEY = _F1 GOTO select_f1
  1051.  
  1052.   See Also:
  1053.  
  1054.     ON KEY
  1055.     PROMPT KEY
  1056.  
  1057. ┌───────────────────────────┐
  1058. │ C.3.14 PC_SCREEN Function │
  1059. └───────────────────────────┘
  1060.  
  1061.   Purpose:
  1062.  
  1063.   This statement returns a specified portion of the window.
  1064.  
  1065.   Format:
  1066.  
  1067.   ┌──────────────────────────────────────────────────────────────────────┐
  1068.   │ PC_SCREEN[(<s-row>,<s-col>,<e-row>,e-col>>)]                         │
  1069.   └──────────────────────────────────────────────────────────────────────┘
  1070.  
  1071.   Remarks:
  1072.  
  1073.   The characters on the window are returned as  a  string  identifier.  Only
  1074.   text is returned, the attribute bytes are not.
  1075.  
  1076.   <s-row>, <s-col>, <e-row>, and  <e-col>  define  an  optional  rectangular
  1077.   region of the screen to return.
  1078.  
  1079.   Example:
  1080.  
  1081.       set t_text = PC_SCREEN(10,40,15,50)
  1082.  
  1083.   See Also:
  1084.  
  1085.     DISPLAY
  1086.     INSTR
  1087.     PC_SCREEN_CHARATTR
  1088.     STR_MID
  1089.  
  1090. ┌────────────────────────────────────┐
  1091. │ C.3.15 PC_SCREEN_CHARATTR Function │
  1092. └────────────────────────────────────┘
  1093.  
  1094.   Purpose:
  1095.  
  1096.   This statement returns a specified portion of  the  window  including  the
  1097.   attribute bytes.
  1098.  
  1099.   Format:
  1100.  
  1101.   ┌──────────────────────────────────────────────────────────────────────┐
  1102.   │ PC_SCREEN_CHARATTR                                                   │
  1103.   │          [(<s-row>,<s-col ,<e-row>,e-col>)]                          │
  1104.   └──────────────────────────────────────────────────────────────────────┘
  1105.  
  1106.   Remarks:
  1107.  
  1108.   The characters and attribute bytes on the window are returned as a  string
  1109.   identifier.
  1110.  
  1111.   <s-row>, <s-col>, <e-row>, <e-col> define an optional  rectangular  region
  1112.   of the screen to return.
  1113.  
  1114.   This function is normally used with DISPLAY CHARATTR to save  and  restore
  1115.   portions of the window.
  1116.  
  1117.   Example:
  1118.  
  1119.       set t_text = PC_SCREEN_CHARATTR(10,40,15,50)
  1120.             .
  1121.             .
  1122.             .
  1123.     re_disp:
  1124.       display CHARATTR t_text FROM 10 , 40 TO 15 , 50
  1125.  
  1126.   See Also:
  1127.  
  1128.     DISPLAY
  1129.     INSTR
  1130.     PC_SCREEN
  1131.     STR_MID
  1132.  
  1133. ┌─────────────────────────┐
  1134. │ C.3.16 PROMPT Statement │
  1135. └─────────────────────────┘
  1136.  
  1137.   Purpose:
  1138.  
  1139.   The PROMPT Statement receives  input  from  the  keyboard  during  program
  1140.   execution.
  1141.  
  1142.   Format:
  1143.  
  1144.   ┌──────────────────────────────────────────────────────────────────────┐
  1145.   │ PROMPT [ {NOECHO       } ] [ {LEFT } ]                               │
  1146.   │        [ {ECHO <string>} ] [ {RIGHT} ]                               │
  1147.   │                                                                      │
  1148.   │        [ {UPPER} ] [ {TRUNCATE} ] [ REDISPLAY ]                      │
  1149.   │        [ {LOWER} ] [ {PAD   } ]                                      │
  1150.   │                                                                      │
  1151.   │        [ KEY <keylist> ] [ MOUSE_EVENT <event> ]                     │
  1152.   │                                                                      │
  1153.   │        [ MAXWAIT <timeval>  ] [ AUTOSKIP ]                           │
  1154.   │                                                                      │
  1155.   │        [ [<display-string>] <identifier>[(<number>] ]                │
  1156.   │                     [AT <row> <col>]                                 │
  1157.   └──────────────────────────────────────────────────────────────────────┘
  1158.  
  1159.   Remarks:
  1160.  
  1161.   The optional NOECHO  keyword  suppresses  echoing  of  keystrokes  on  the
  1162.   window. The ECHO <string> option allows you to specify a single  character
  1163.   to be echoed as each key is pressed.
  1164.  
  1165.   The optional <display-string> operand simulates a DISPLAY function.
  1166.  
  1167.   The <identifier> is the name  of  the  variable  which  will  receive  the
  1168.   input.    If  there  is  a  value  associated  with  <identifier>,  it  is
  1169.   displayed. Its value may be changed by typing over it.
  1170.  
  1171.   The (<number>) operand limits the character size of the input.  If  it  is
  1172.   not specified, the size of input  is  determined  by  the  length  of  the
  1173.   string  represented  by  <identifier>.  If  <identifier>  has  no  value
  1174.   associated with it, the size of the input is limited by what will  fit  on
  1175.   the line. In all cases, the size of the input will be truncated to  insure
  1176.   that the entry field fits on the line.
  1177.  
  1178.   The LEFT and RIGHT options provide control over the justification  of  the
  1179.   data being entered. For example: PROMPT NOECHO LEFT  USERID(8),  indicates
  1180.   that the data which is being entered into the 8 character variable  userid
  1181.   should be left justified upon completion of the PROMPT Statement.
  1182.  
  1183.   The UPPER and LOWER provides automatic  case  conversion  on  the  entered
  1184.   data.
  1185.  
  1186.   The TRUNCATE and PAD options provide  better  control  over  the  size  of
  1187.   string variables. For example: PROMPT TRUNCATE userid(8),  will  return  a
  1188.   string whose length is equal to the  actual  number  of  characters  which
  1189.   were entered.
  1190.  
  1191.   The REDISPLAY option instructs PROMPT to redisplay the entered data  after
  1192.   ENTER (or any keylist KEY) is pressed. This option is used to display  the
  1193.   changes the PROMPT Statement may have  made  on  the  entered  data  (i.e.
  1194.   UPPER, LOWER, LEFT, RIGHT, TRUNCATE, etc.)
  1195.  
  1196.   The KEY option allows a list of acceptable keys to  be  specified  in  the
  1197.   same manner as the ON KEY Statement. If one of  these  keys  are  pressed,
  1198.   the PROMPT Statement ends and the PC_KEY value is updated. For example:
  1199.  
  1200.       PROMPT KEY _F1, _F2, _F3, MENU_OPTION(1)
  1201.  
  1202.   will accept F1, F2, and F3 as valid keys assuming the  identifiers  _F1  ,
  1203.   _F2, and _F3 were set to valid key values (see the  TTPCKEY.INC  file  and
  1204.   the ON KEY Statement.).
  1205.  
  1206.   The MOUSE_EVENT option allows you to list  a  set  of  MOUSE  events  that
  1207.   might occur which you wish to capture.  The value of <event> is  the  same
  1208.   as the value returned by the MOUSE_POLL function (see MOUSE_POLL for  more
  1209.   information on testing for MOUSE events).
  1210.  
  1211.   The MAXWAIT option allows you to limit the amount of time  that  you  will
  1212.   be delayed at a PROMPT Statement.  <timeval> can be specified in the  same
  1213.   manner as on the WAIT FOR Statement.  When the amount of time has  passed,
  1214.   an appropriate RETURN_CODE is set. If a <timeval> of 0 is  specified,  the
  1215.   PROMPT will wait indefinitely.
  1216.  
  1217.   The AUTOSKIP option will force the  PROMPT  Statement  to  terminate  when
  1218.   either the field is filled with characters (return_code = 4) or  the  left
  1219.   arrow key moves left of the first character of the  field  (return_code  =
  1220.   5).  This information can  be  used  to  simulate  the  AUTOSKIP  facility
  1221.   available on 3270 type terminals.
  1222.  
  1223.   It is also acceptable to use the PROMPT keyword alone as in:
  1224.  
  1225.       PROMPT
  1226.  
  1227.   This will cause the PROMPT Statement to wait for ANY keystroke.  When  any
  1228.   key is pressed, the PROMPT Statement ends and the PC_KEY value is updated.
  1229.  
  1230.   The optional AT clause is treated in the same manner  as  in  the  DISPLAY
  1231.   Statement.
  1232.  
  1233.   The PROMPT command may be terminated  by  pressing  the  ENTER  or  ESCAPE
  1234.   keys. If  the  ESCAPE  key  is  pressed,  the  ESCAPE  condition  will  be
  1235.   triggered and the ON ESCAPE Statement (if any) will be executed  (see  the
  1236.   ON command).
  1237.  
  1238.   The PROMPT Statement sets the following RETURN_CODE values:
  1239.  
  1240.     0
  1241.      - The PROMPT terminated normally (either Enter or Escape were pressed).
  1242.     1
  1243.      - A key from the <keylist> was specified.
  1244.     2
  1245.      - An event indicated on the MOUSE_EVENT clause occurred.
  1246.     3
  1247.      - The <timeval> on the MAXWAIT clause was exceeded.
  1248.     4
  1249.      - The AUTOSKIP clause was specified  and  the  last  character  in  the
  1250.        field was filled.
  1251.     5
  1252.      - The AUTOSKIP clause was specified and the left arrow  key  was  moved
  1253.        to the left of the first character of the field.
  1254.  
  1255.   Examples:
  1256.  
  1257.   Example 1:
  1258.  
  1259.       PROMPT NOECHO "Enter Password " password (8)
  1260.  
  1261.   Example 2:
  1262.  
  1263.       INCLUDE "TTPCKEY.INC"
  1264.  
  1265.       DISPLAY "Press Function Key To Select Option"
  1266.       PROMPT KEY _F1, _F2, _F3
  1267.  
  1268.       IF PC_KEY = _F1 GOTO opt_1
  1269.       IF PC_KEY = _F2 GOTO opt_2
  1270.       IF PC_KEY = _F3 GOTO opt_3
  1271.  
  1272.   Example 3:
  1273.  
  1274.       INCLUDE "TTMOUSE.INC"
  1275.  
  1276.       PROMPT MOUSE_EVENT MLEFT_PRESSED bitand  MRIGHT_PRESSED
  1277.       if return_code = 2
  1278.         begin
  1279.           set t_status = MOUSE_INFO(MSTATUS)
  1280.           if t_status bitand MLEFT_PRESSED goto l_left
  1281.           if t_status bitand MRIGHT_PRESSED goto l_right
  1282.         end
  1283.  
  1284.   See Also:
  1285.  
  1286.     DISPLAY
  1287.     KEYBOARD_INFO
  1288.     KEYBOARD_POLL
  1289.     MOUSE_INFO
  1290.     MOUSE_POLL
  1291.     PC_KEY
  1292.  
  1293. ┌─────────────────────────┐
  1294. │ C.3.17 RESUME Statement │
  1295. └─────────────────────────┘
  1296.  
  1297.   Purpose:
  1298.  
  1299.   The  RESUME  Statement  continues  program  execution  after  an  ON  KEY
  1300.   condition.
  1301.  
  1302.   Format:
  1303.  
  1304.   ┌──────────────────────────────────────────────────────────────────────┐
  1305.   │ RESUME { ESCAPE } { RETRY    }                                       │
  1306.   │        { KEY    } { NEXT     }                                       │
  1307.   │                   {  <Label> }                                       │
  1308.   └──────────────────────────────────────────────────────────────────────┘
  1309.  
  1310.   Remarks:
  1311.  
  1312.   RESUME <condition> RETRY causes  execution  to  resume  at  the  statement
  1313.   which caused the condition to  occur.    RESUME  <condition>  NEXT  causes
  1314.   execution to resume at the statement immediately following the  one  which
  1315.   caused  the  condition  to  occur.  RESUME  <condition>  <label>  causes
  1316.   execution to resume at the specified label.
  1317.  
  1318.   For more information on RESUME and how it relates to ACTION BARS  on  text
  1319.   windows,  refer  to  the  RESUME  Statement  in  the  Chapter,  AUTOPILOT
  1320.   Statement Reference.
  1321.  
  1322.   Examples:
  1323.  
  1324.       RESUME KEY RETRY
  1325.  
  1326.   See Also:
  1327.  
  1328.     ON
  1329.  
  1330. ┌──────────────────────┐
  1331. │ C.3.18 SET Statement │
  1332. └──────────────────────┘
  1333.  
  1334.   Purpose:
  1335.  
  1336.   Assigns default color and message line on text windows.
  1337.  
  1338.   Formats:
  1339.  
  1340.   ┌──────────────────────────────────────────────────────────────────────┐
  1341.   │ SET MSGLINE = <row>                                                  │
  1342.   │                                                                      │
  1343.   │ SET DEFAULT_COLOR <fgnd [,] <bkgnd>                                  │
  1344.   │                                                                      │
  1345.   │ SET FONT [ FACENAME = <face> ]                                       │
  1346.   │          [ SIZE=<size> ]                                             │
  1347.   │          [ CODEPAGE=<cp> ]                                           │
  1348.   │          [ BOLD  ]                                                   │
  1349.   │          [ ITALICS ]                                                 │
  1350.   │          [ UNDERLINE ]                                               │
  1351.   │          [ STRIKE OUT ]                                              │
  1352.   └──────────────────────────────────────────────────────────────────────┘
  1353.  
  1354.   Remarks:
  1355.  
  1356.   MSGLINE is the global row value keyword identifier  used  in  all  DISPLAY
  1357.   and PROMPT activity unless overridden by the  individual  statement  being
  1358.   executed. <row> must be a number from 1 to 25. MSGLINE = 0 is the  default
  1359.   if the window was defined using CREATE TEXT_WINDOW, but MSGLINE  =  25  is
  1360.   the default for the PC/DOS compatibility  window  provided  if  no  CREATE
  1361.   TEXT_WINDOW is issued.
  1362.  
  1363.   DEFAULT_COLOR is used to modify default color used on text windows  create
  1364.   utilizing the CREATE TEXT_WINDOW Statement.
  1365.  
  1366.   See the discussion  on  the  FONT  Clause  under  the  CREATE  TEXT_WINDOW
  1367.   Statement for more information on SET FONT.
  1368.