home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / apmt34.zip / APMTDOC.INF (.txt) < prev    next >
OS/2 Help File  |  1995-06-02  |  54KB  |  2,408 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Product Information ΓòÉΓòÉΓòÉ
  3.  
  4.     Author: Dev Banerjee
  5.  
  6.     (C) Copyright International Business Machines Corporation 1994.
  7.  
  8.     All Rights Reserved
  9.  
  10.  
  11. ΓòÉΓòÉΓòÉ 2. What is APMT? ΓòÉΓòÉΓòÉ
  12.  
  13. APMT is a program package that provides a set of REXX functions. These 
  14. functions can be used to write REXX programs which can drive any PM application 
  15. running in the same PC or in a different PC. Some of the functions query the 
  16. state of the  PM window controls, while others change them. This allows the 
  17. REXX program (hereinafter called APMT client) to act in place of a human 
  18. operator. 
  19.  
  20. An APMT client program does not require any special environment to run under. 
  21. It can be invoked from any OS/2 command line or equivalent. 
  22.  
  23.  
  24. ΓòÉΓòÉΓòÉ 2.1. Uses ΓòÉΓòÉΓòÉ
  25.  
  26. Following are some uses of APMT. 
  27.  
  28.  o As scripts to run automated test programs for PM applications. 
  29.  
  30.    This is the main intended use of the tool. There are programs such as the 
  31.    Cleanroom Certification Assistant which can be used to generate arbitrary 
  32.    test script files. Here the generated script would be a APMT client program 
  33.    which could drive the PM application under test. 
  34.  
  35.    APMT is intended for testing a product based on its specifications, in a way 
  36.    that automated testcases can be generated without requiring a product driver 
  37.    to be available first. 
  38.  
  39.    APMT does not have screen save/compare, or testcase record/playback 
  40.    features. 
  41.  
  42.  o As a driver for programs to be executed on remote machines. 
  43.  
  44.    Another possible use of APMT is to start a program in a remote machine. If 
  45.    that program is a PM application then it can be monitored and driven using 
  46.    APMT functions. 
  47.  
  48.  o As an interface between a REXX program and standard OS/2 Workplace Shell 
  49.    controls. 
  50.  
  51.    APMT can be used to develop simple, but yet effective, programs to 
  52.    manipulate Workplace objects which can help automate routine tasks. 
  53.  
  54.  
  55. ΓòÉΓòÉΓòÉ 3. Installation and use ΓòÉΓòÉΓòÉ
  56.  
  57.  
  58. ΓòÉΓòÉΓòÉ 3.1. Prerequisites ΓòÉΓòÉΓòÉ
  59.  
  60. APMT runs on OS/2 2.x+ and requires REXX to be installed. 
  61.  
  62. If the target application is on a remote machine, both machines need to be 
  63. running OS/2  and be LAN connected. 
  64.  
  65.  
  66. ΓòÉΓòÉΓòÉ 3.2. How to Install ΓòÉΓòÉΓòÉ
  67.  
  68. Installation consists of the following. Note that the files need to be in the 
  69. directories indicated, regardless of whether they are in the current directory, 
  70. in order for APMT to run reliably. 
  71.  
  72.  move   APMTEXT.DLL   to a directory in the LIBPATH
  73.  move   APMTDLL.DLL   to a directory in the LIBPATH
  74.  move   APMOCRW.DLL   to a directory in the LIBPATH
  75.  move   APMNP.DLL     to a directory in the LIBPATH
  76.  move   APMNETB.DLL   to a directory in the LIBPATH * needed only for remote operation
  77.  move   APMT.EXE      to a directory in the PATH
  78.  move   APMNETBL.EXE  to a directory in the PATH    * needed only for remote operation
  79.  move   IBMDABB.CP    to a directory in the DPATH
  80.  
  81.      Note for users of Distributed Applications/2. 
  82.  
  83.      APMT is an application that uses Distributed Applications/2. 
  84.  
  85.      The file IBMDABB.CP contains the connection profiles. 
  86.  
  87.      If you are a user of other Distributed Applications/2 applications, you 
  88.      may want to combine the IBMDABB.CP files for the different applications. 
  89.  
  90.  
  91. ΓòÉΓòÉΓòÉ 4. Limitations ΓòÉΓòÉΓòÉ
  92.  
  93. APMT can only operate on controls using standard PM classes. Therefore if an 
  94. application uses non standard classes then APMT cannot be used for these 
  95. controls. 
  96.  
  97. The standard controls are shipped with OS/2 toolkit. Very often, applications 
  98. modify the controls by subclassing or use their own custom controls. Since the 
  99. interface to these controls are not known to APMT, they cannot be supported. 
  100.  
  101. The APMT client program has limited access to these controls using the MOUSE, 
  102. KEYBOARD, and CLASS_SET_POINTER functions. 
  103.  
  104.  
  105. ΓòÉΓòÉΓòÉ 4.1. Considerations for timing related problems ΓòÉΓòÉΓòÉ
  106.  
  107. Since APMT client will tend to drive the application much faster than a human 
  108. operator, it will be necessary at times to pause so that the selected actions 
  109. are not executed too early. For example, after pressing a button to cancel a 
  110. modal dialog box, it may be necessary to wait before directing any input to the 
  111. parent window to allow time for the dialog box to be dismissed. 
  112.  
  113. Often, it is possible to set up a simple Rexx loop to wait for the desired 
  114. condition before proceeding further. 
  115.  
  116.  The WAIT and SET_TIMEOUT functions, and the retry parameters to the 
  117. SELECT_WINDOW, and SELECT_DIALOG_WINDOW are some of the means to achieve the 
  118. delay. 
  119.  
  120. Also, if the application displays the "wait" pointer, APMT automatically waits 
  121. for it to be cleared before servicing a function. 
  122.  
  123.  
  124. ΓòÉΓòÉΓòÉ 5. APMT client Program Structure ΓòÉΓòÉΓòÉ
  125.  
  126. The APMT client is simply a REXX program using APMT functions and any other 
  127. REXX functions and features. The following is a simple example of the structure 
  128. of an APMT client program. 
  129.  
  130.  o Startup instructions as follows: 
  131.  
  132.          /******************************************************************/
  133.          /* Part 1: common prefix                                          */
  134.          /******************************************************************/
  135.          Trace off
  136.          call APMT_INIT
  137.  
  138.  o Main APMT client instructions, for example: 
  139.  
  140.          /******************************************************************/
  141.          /* Part 2: Program specific instructions                          */
  142.          /******************************************************************/
  143.          rc = SELECT_WINDOW("Icon Editor","10")
  144.          ...
  145.  
  146.  o Terminating instructions, as follows: 
  147.  
  148.          /******************************************************************/
  149.          /* Part 3: common suffix                                          */
  150.          /******************************************************************/
  151.          APMT_CLOSE:
  152.          rc = END_SESSION();
  153.          exit
  154.  
  155.          DropFUNC:      /* function normally not needed */
  156.          call APMTDropFuncs;
  157.          call rxfuncdrop(APMTDropFuncs)
  158.          return
  159.  
  160.          APMT_INIT:
  161.          call rxfuncadd  'APMTLoadFuncs',  'apmtext', 'APMTLoadFuncs'  /* entry points from the DLL    */
  162.          call APMTLoadFuncs;
  163.          rc = INIT_SESSION();
  164.          if rc \= 0
  165.             then do
  166.               say apmtmsg
  167.               exit
  168.               end
  169.          signal on error name  APMT_CLOSE
  170.          if apmtver.client \= apmtver.server then
  171.             say 'WARNING: Version mismatch. Client ='apmtver.client 'Server ='apmtver.server
  172.             else say 'Running APMT version 'apmtver.client
  173.          signal on halt name APMT_CLOSE
  174.          return
  175.  
  176.  
  177.  
  178. ΓòÉΓòÉΓòÉ 5.1. General syntax rules ΓòÉΓòÉΓòÉ
  179.  
  180.  o All APMT client calls are of the same format: 
  181.  
  182.            rc = APMT_CALL(parm1, .. ,parmN)
  183.  
  184.  o All parameters for all functions are restricted to 255 bytes. 
  185.  
  186.  o If a parm is optional, it is indicated in the description of the function. 
  187.    If a required parm is missing REXX will return with 'INCORRECT CALL TO 
  188.    ROUTINE' message. 
  189.  
  190.  o Some functions return data to the APMT client. 
  191.  
  192.  o Three types of data are returned: 
  193.  
  194.     Rexx single variables 
  195.  
  196.     Rexx stem  variables 
  197.  
  198.     OS/2 files 
  199.  
  200.  The type of data to be returned is indicated in the function description. 
  201.  
  202.  
  203.  For these functions, the name of the variable, or file, is always the last 
  204.  parameter of the function. It is safer to provide this name in quotes. 
  205.  
  206.  The value of a stem variable is as updated as follows. If "xxx" is the 
  207.  variable name passed, then on return, xxx.0 contains the number of additional 
  208.  stems. xxx.1, .. xxx.(xxx.0) contain the rest of the stem values. Other stems 
  209.  of xxx are unchanged. 
  210.  
  211.  The value of the variable is set to the null string if the call was 
  212.  unsuccessful with a return code greater than 0. For stem variables, the .0 
  213.  stem is set to null and any other stems are unchanged. 
  214.  
  215.  o Many of the functions require the text of the window control as parameter to 
  216.    identify the window. Except for SELECT_WINDOW and SELECT_DIALOGWINDOW, the 
  217.    text should be exact. The match is case sensitive, and blanks are not 
  218.    ignored. 
  219.  
  220.  o Some functions require the sequence number of the window control as it 
  221.    appear in the selected window to identify it. 
  222.  
  223.  o Controls are assigned sequence numbers according to their appearance in the 
  224.    selected window, from top to bottom and left to right. 
  225.  
  226.  
  227. ΓòÉΓòÉΓòÉ 5.2. Return codes and error messages ΓòÉΓòÉΓòÉ
  228.  
  229. In the description of a APMT function, only the return codes which are unique 
  230. for that function are explained. The common return codes apply to all functions 
  231. and are not repeated. 
  232.  
  233. Return code 0 indicates success. However, for some functions, this simply means 
  234. that the appropriate message was sent to the application. The results of that 
  235. message is not indicated in this return code. 
  236.  
  237. Return code 4 indicates that APMT could not locate the specified control 
  238. window. 
  239.  
  240. Return codes between 5 and 7 indicate a call specific error condition and are 
  241. described in the function description. 
  242.  
  243. Return code 8 indicates an incorrect environment for the call. For example, a 
  244. PUSHBUTTON_CLICK call without a selected window will result in this code. This 
  245. code will also occur if the target application has been terminated or some 
  246. other condition has made the selected window invalid. 
  247.  
  248. Return code 12 indicates that the session is not open. 
  249.  
  250. Return codes 20 or greater indicate a possible bug in APMT. 
  251.  
  252. Syntax and environment setup errors are intercepted by REXX and result in such 
  253. messages as 'ROUTINE NOT FOUND' and 'INCORRECT CALL TO ROUTINE' 
  254.  
  255. APMT sets a rexx variable, APMTMSG, after each function call. If the return 
  256. code from the function is 0, this variable is set to null. If the return code 
  257. is non-zero, this variable contains a message indicating the cause. 
  258.  
  259.  
  260. ΓòÉΓòÉΓòÉ 6. The APMT Functions ΓòÉΓòÉΓòÉ
  261.  
  262. This section describes all the APMT client functions. As the tool evolves, more 
  263. functions will be added or existing functions will be enhanced. 
  264.  
  265.  
  266. ΓòÉΓòÉΓòÉ 6.1. INIT_SESSION ΓòÉΓòÉΓòÉ
  267.  
  268. This function establishes a APMT session. 
  269. Syntax 
  270.  
  271.     rc = INIT_SESSION([app_location])
  272.        where app_location is RMTNETnn, and nn = {01, 02, .. 20}
  273.  
  274. Examples 
  275.  
  276.     rc = INIT_SESSION()
  277.  
  278.     rc = INIT_SESSION("RMTNET01")
  279.  
  280. Description 
  281.  
  282. This function must be the first APMT call before any significant function can 
  283. be called. 
  284.  
  285. The parameter is optional and identifies where the target application resides. 
  286. If it is missing, then it is assumed to be in the same PC. 
  287.  
  288. If it is on a different PC, then the following has to be done prior to this 
  289. call: 
  290.  
  291.  APMT installed on the remote machine. 
  292.  
  293.  The two machines must be on the same LAN. 
  294.  
  295.  Invoke "APMNETBL RMTNETnn" from any OS/2 command line on the remote machine. 
  296.  This function will start an OS/2 session which has no screen i/o. This session 
  297.  should be kept running as long as an APMT session to that machine is needed. 
  298.  
  299.  If you get an error when you run APMNETBL, you also get a NETBIOS return code 
  300.  which indicates the error. Common causes of failure are name RMTNETnn already 
  301.  in use, no NETBIOS sessions available, and network not accessed. 
  302.  
  303.  Note that APMNETBL essentially identifies the remote machine to the LAN, and 
  304.  therefore two distinct invocations cannot use the same nn value 
  305.  simultaneously. 
  306.  
  307.  The invocation parameter for INIT_SESSION should match the parameter to 
  308.  APMNETBL. 
  309.  
  310.  Return Codes 
  311.  
  312.  o 0  - connection successful 
  313.  
  314.  o 8  - connection unsuccessful 
  315.  
  316.  o 12 - too many sessions 
  317.  
  318.  Notes 
  319.  
  320.  If the target is on a different machine, this function may take somewhat 
  321.  longer to complete, perhaps as much as 15 seconds. The result will be that the 
  322.  REXX program will appear slow to start. After the connection is complete, 
  323.  there should not be any additional delay, however, for subsequent actions. 
  324.  
  325.  The session is closed by the END_SESSION call. 
  326.  
  327.  When a session is opened, APMT updates two stem variables APMTVER.CLIENT, and 
  328.  APMTVER.SERVER. These are only needed to ensure that different part of APMT 
  329.  are at the same version level. The client here is the APMT client program, and 
  330.  the server is the part of APMT which drives the target application. It is 
  331.  important that the versions match. 
  332.  
  333.  APMT will support up to 20 sessions at the same time. After a session is 
  334.  opened, all APMT calls are directed to this session, until another session is 
  335.  opened with INIT_SESSION, or SELECT_SESSION is called to switch to another 
  336.  open session. 
  337.  
  338.  
  339. ΓòÉΓòÉΓòÉ 6.2. END_SESSION ΓòÉΓòÉΓòÉ
  340.  
  341. This function ends the currently selected APMT session. 
  342. Syntax 
  343.  
  344.     rc = END_SESSION()
  345.  
  346. Examples 
  347.  
  348.     rc = INIT_SESSION('RMTNET01')
  349.     rc = INIT_SESSION('RMTNET02')
  350.     rc = SELECT_SESSION('RMTNET01')
  351.     ...
  352.     rc = SELECT_SESSION('RMTNET02')
  353.     ...
  354.     rc = SELECT_SESSION('RMTNET01')
  355.     ...
  356.     rc = END_SESSION()          /* closes RMTNET01 */
  357.     rc = SELECT_SESSION('RMTNET02')
  358.     rc = END_SESSION()          /* closes RMTNET02 */
  359.  
  360. Description 
  361.  
  362. This function will close the currently selected session, and on return no 
  363. session remains selected, even if there are open sessions. To select a open 
  364. session at this time, use SELECT_SESSION. 
  365.  
  366. It is recommended that each open session be closed before exiting the APMT 
  367. client program. 
  368. Return Codes 
  369.  
  370.  o 0  - always. 
  371.  
  372.  
  373. ΓòÉΓòÉΓòÉ 6.3. GET_FILE ΓòÉΓòÉΓòÉ
  374.  
  375. Copy the specified file from server machine to the client machine 
  376. Syntax 
  377.  
  378.     rc = GET_FILE(source_file_spec,target_file_spec)
  379.  
  380.  
  381. Examples 
  382.  
  383.        /* Get the config.sys                                */
  384.        rc = GET_FILE("c:\config.sys","d:\temp\config.xxx")
  385.  
  386.  
  387. Description 
  388.  
  389. This call will copy the source file to the client machine. It makes sense only 
  390. if the target application is on a remote machine, but this is not enforced. 
  391.  
  392. The parameters must be a valid file specs. 
  393. Return Codes 
  394.  
  395.  o 6 - The specified file could not be opened 
  396.  
  397.  o 7 - The specified file could not be written to 
  398.  
  399.  
  400. ΓòÉΓòÉΓòÉ 6.4. SELECT_SESSION ΓòÉΓòÉΓòÉ
  401.  
  402. This function selects an open session for subsequent APMT functions. 
  403. Syntax 
  404.  
  405.     rc = SELECT_SESSION(app_location)
  406.        where app_location is RMTNETnn, and nn = {01, 02, .. 20}
  407.  
  408. Examples 
  409.  
  410.     rc = INIT_SESSION('RMTNET01')
  411.     rc = INIT_SESSION('RMTNET02')
  412.     rc = SELECT_SESSION('RMTNET01')
  413.     ...
  414.     rc = SELECT_SESSION('RMTNET02')
  415.     ...
  416.     rc = SELECT_SESSION('RMTNET01')
  417.     ...
  418.     rc = END_SESSION()          /* closes RMTNET01 */
  419.     rc = SELECT_SESSION('RMTNET02')
  420.     rc = END_SESSION()          /* closes RMTNET02 */
  421.  
  422. Description 
  423.  
  424. This function will select the session specified in the parameter, provided it 
  425. is open. 
  426. Return Codes 
  427.  
  428.  o 8  - specified session is not open 
  429.  
  430.  
  431. ΓòÉΓòÉΓòÉ 6.5. START_PROGRAM ΓòÉΓòÉΓòÉ
  432.  
  433. This function may be used to start an OS/2 program. 
  434. Syntax 
  435.  
  436.     rc = START_PROGRAM(pgm_name[,parm_string][,working_dir][,program_title])
  437.  
  438. Examples 
  439.  
  440.     rc = START_PROGRAM("MYAPP.EXE")
  441.  
  442.     rc = START_PROGRAM("MYAPP.EXE","myparm1, myparm2")
  443.  
  444.     rc = START_PROGRAM("MYAPP.EXE","","Y:\TEST")
  445.  
  446. Description 
  447.  
  448. This function will start an OS/2 session with the specified program name and 
  449. pass the specified parameter string to the program. 
  450.  
  451. If the working_dir parameter is specified, the program will be started after 
  452. changing the current directory and disk to the specified working directory. It 
  453. may be necessary to do this for example if the program depends on DLLs to be 
  454. located in the current directory. 
  455.  
  456. If the program_title parameter is specified, and it is a windowed program, then 
  457. the program will be started with its title set to this parameter. However, the 
  458. application may reset it to some other value. 
  459. Return Codes 
  460.  
  461.  o 0  - The program was started 
  462.  
  463.  o 5  - Invalid working directory specified. 
  464.  
  465.  o 6  - The program startup failed. 
  466.  
  467.  Notes 
  468.  
  469.  For the purposes of APMT, the program is expected to be a PM application. 
  470.  However, this function can be used to start non-PM applications also. 
  471.  
  472.  Even though the application is started successfully, its application window 
  473.  may not be ready, and it may be necessary to wait for a subsequent 
  474.  SELECT_WINDOW to be successful. Either the WAIT function or the second 
  475.  parameter of SELECT_WINDOW may be used for this purpose. 
  476.  
  477.  
  478. ΓòÉΓòÉΓòÉ 6.6. SELECT_WINDOW ΓòÉΓòÉΓòÉ
  479.  
  480. This function selects a main application window as the target for subsequent 
  481. actions. 
  482. Syntax 
  483.  
  484.     rc = SELECT_WINDOW(window_title [,number_of_attempts] [,seq_number])
  485.  
  486. Examples 
  487.  
  488.     rc = SELECT_WINDOW("Icon Editor")
  489.     rc = SELECT_WINDOW("Icon Editor", "15")
  490.     rc = SELECT_WINDOW("I*Editor", "15")    /* using wild card character * */
  491.     /* List all the windows on the desktop */
  492.     n = 1
  493.     do while SELECT_WINDOW("*",1,n)  = 0
  494.        rc = QUERY_TITLE("title")
  495.        say 'WINDOW NO. 'n ': 'title
  496.        n = n+1
  497.        end
  498.  
  499. Description 
  500.  
  501. This function locates an application window with the given title and selects it 
  502. for subsequent actions. A window must be selected before any other functions 
  503. can be directed to it. Any previously selected window will be de-selected if 
  504. this call is successful. 
  505.  
  506. The specified title can contain wild card characters * and ?. 
  507.  
  508. The second parameter is an optional timeout value. If the window cannot be 
  509. located then the second parameter indicates how many attempts will be made. 
  510. APMT waits for 100 milliseconds (1/10 sec) before trying again. So, in the 
  511. second example above, at least 1.5 seconds will elapse before the function will 
  512. fail. This value defaults to, and must be at least, 1. If any other value is 
  513. specified, 1 is used. 
  514.  
  515. The third parameter is optional, and defaults to 1. If there are more than one 
  516. window which match the title specification in the first parameter, then 
  517. seq_number can be used to select the desired window. 1 means the topmost window 
  518. on the desktop. 
  519. Notes 
  520.  
  521.  If the specified window is not found, then the currently selected window will 
  522.  remain selected. 
  523.  
  524.  A window on the desktop whose title matches the given window_title, after 
  525.  taking any wild card characters into account, will be selected. To specify 
  526.  prefix only, the window_title must end in a *. 
  527.  
  528.  The match is case sensitive. 
  529.  
  530.  If there is more than one window which matches the title, then APMT will 
  531.  select the topmost window. There is no relationship between the selected 
  532.  window and the application started by START_PROGRAM. 
  533.  
  534.  Specifying "*" as the title will select the active window on the desktop. 
  535.  
  536.  Only one window can be selected at a time. 
  537.  
  538.  APMT will place the mouse pointer at the center of the selected window if this 
  539.  call is successful. 
  540.  
  541.  
  542. ΓòÉΓòÉΓòÉ 6.7. SELECT_WINDOW_BY_HANDLE ΓòÉΓòÉΓòÉ
  543.  
  544. This function selects a window whose handle is specified as the parameter. 
  545. Syntax 
  546.  
  547.     rc = SELECT_WINDOW_BY_HANDLE(window_handle)
  548.  
  549. Examples 
  550.  
  551.     /* Save window handle, and later select it by specifying handle */
  552.     rc = SELECT_WINDOW("CMD.EXE")
  553.     rc = QUERY_WINDOW_HANDLE("savehandle")
  554.     ...
  555.     rc = SELECT_WINDOW_BY_HANDLE(savehandle)
  556.  
  557. Description 
  558.  
  559. This function is similar to SELECT_WINDOW, but it uses the window handle as 
  560. parameter. To get the window handle, use the QUERY_WINDOW_HANDLE function. 
  561. Notes. 
  562.  
  563.  o This function, in conjunction with QUERY_WINDOW_HANDLE, can be used to save 
  564.    and restore window selections. This is helpful when the window title of the 
  565.    selected window changes, or there are multiple windows with the same title, 
  566.    and you need to select the particular window that you had selected before. 
  567.  
  568.  o APMT will not place the mouse pointer at the center of the selected window. 
  569.  
  570.  
  571. ΓòÉΓòÉΓòÉ 6.8. SELECT_DIALOGWINDOW ΓòÉΓòÉΓòÉ
  572.  
  573. This function selects a window on the desktop, which is a dialog box for the 
  574. currently selected window, for subsequent actions. 
  575. Syntax 
  576.  
  577.     rc = SELECT_DIALOGWINDOW(window_title [,number_of_attempts])
  578.  
  579. Examples 
  580.  
  581.     rc = SELECT_DIALOGWINDOW("Device List")
  582.  
  583.     rc = SELECT_DIALOGWINDOW("Device List", "15")
  584.  
  585.     rc = SELECT_DIALOGWINDOW(" ")
  586.  
  587. Description 
  588.  
  589. This function is similar to SELECT_WINDOW, and it selects a window which 
  590. belongs to the same process to which the currently selected window belongs. 
  591. Notes. 
  592.  
  593.  o This call deselects the previously selected window if the dialog window is 
  594.    successful, otherwise the previously selected window remains selected. 
  595.  
  596.  o The matching he desktop whose title matches the given window_title, after 
  597.    taking any wild card characters into account, will be selected. To specify a 
  598.    prefix only, the window_title must end in a *. 
  599.  
  600.    The title may be "*". In this case the topmost window on the desktop is 
  601.    selected (running in the application's process), regardless of its title. 
  602.    This function is useful if the target application displays message boxes 
  603.    which have blank titles or the title is unknown. 
  604.  
  605.    To return to the previous window, use SELECT_WINDOW again. 
  606.  
  607.    The second parameter is optional and has the same meaning as for 
  608.    SELECT_WINDOW. 
  609.  
  610.  o APMT will place the mouse pointer at the center of the selected window if 
  611.    this call is successful. 
  612.  
  613.  
  614. ΓòÉΓòÉΓòÉ 6.9. SELECT_NEW_WINDOW ΓòÉΓòÉΓòÉ
  615.  
  616. This function selects a main application window as the target for subsequent 
  617. actions, which appeared since the last relevant APMT function. 
  618. Syntax 
  619.  
  620.     rc = SELECT_NEW_WINDOW([number_of_attempts])
  621.  
  622. Examples 
  623.  
  624.     rc = PUSHBUTTON_CLICK("Doit")
  625.     rc = SELECT_NEW_WINDOW(50)
  626.     if rc = 0 then do
  627.        rc = QUERY_TITLE('title')
  628.        say 'Window "'title'" showed up'
  629.        end
  630.  
  631. Description 
  632.  
  633. For some functions, APMT captures a list of all windows on the desktop before 
  634. executing the function. Following the function, and before another such 
  635. fucntion, SELECT_NEW_WINDOW can be called to select whatever new window 
  636. appeared since the function. 
  637.  
  638. The number_of_attempts has the same meaning as for SELECT_WINDOW. 
  639. Notes 
  640.  
  641.  If no new window is found, then the currently selected window will remain 
  642.  selected. 
  643.  
  644.  To be selected, the new window must be the topmost window. 
  645.  
  646.  Examples of functions for which a new list is captured by APMT are: SELECT_ 
  647.  functions, button_click functions, menu selection functions, keyboard 
  648.  functions. 
  649.  
  650.  Examples of functions for which a new list is not captured by APMT are: 
  651.  SET_FOCUS, QUERY_ functions, SELECT_NEW_WINDOW, mouse functions. 
  652.  
  653.  
  654. ΓòÉΓòÉΓòÉ 6.10. SELECT_SUBWINDOW ΓòÉΓòÉΓòÉ
  655.  
  656. This function selects a frame window which is a child of the currently selected 
  657. window. 
  658. Syntax 
  659.  
  660.     rc = SELECT_SUBWINDOW(window_title [,number_of_attempts] [,seq_number])
  661.  
  662. Examples 
  663.  
  664.     rc = SELECT_WINDOW(Name)
  665.     do i = 1 to 5
  666.        rc = SELECT_SUBWINDOW("*",1,i)
  667.        if rc = 0 then do
  668.           rc = QUERY_TITLE('title')
  669.           say  "subwindow "i " :" title
  670.           end
  671.        rc = SELECT_WINDOW(Name)
  672.        end
  673.  
  674. Description 
  675.  
  676. This function is provided to list the titles of sub windows in an IPF help 
  677. window, but other uses are possible. 
  678.  
  679. This changes the current window selection. 
  680.  
  681. The parameters are similar to SELECT_WINDOW's. 
  682.  
  683. APMT will NOT place the mouse pointer at the center of the sub window. 
  684.  
  685.  
  686. ΓòÉΓòÉΓòÉ 6.11. SET_FOCUS ΓòÉΓòÉΓòÉ
  687.  
  688. This function makes the selected window the active window. 
  689. Syntax 
  690.  
  691.     rc = SET_FOCUS()
  692.  
  693. Examples 
  694.  
  695.     rc = SET_FOCUS()
  696.  
  697. Description 
  698.  
  699. This function will make the selected window active. 
  700. Return Codes 
  701.  
  702.  o 5  - Current window could not be made active. 
  703.  
  704.  Notes 
  705.  
  706.  There is no need to use this function for subsequent APMT functions. Use this 
  707.  only if you have a special need. 
  708.  
  709.  
  710. ΓòÉΓòÉΓòÉ 6.12. SET_TIMEOUT ΓòÉΓòÉΓòÉ
  711.  
  712. This function sets the default time out for selected APMT functions. 
  713. Syntax 
  714.  
  715.     rc = SET_TIMEOUT(number_of_attempts)
  716.  
  717.  
  718. Examples 
  719.  
  720.     rc = SET_TIMEOUT(200)
  721.  
  722. Description 
  723.  
  724. The parameter is a timeout value. If certain APMT functions, identified below, 
  725. will not work until the application is ready, then APMT will make 
  726. number_of_attempts before giving up. APMT waits for 100 milliseconds (1/10 sec) 
  727. before trying again. 
  728.  
  729. This value defaults to, and must be at least, 1. If any other value is 
  730. specified, 1 is used. 
  731.  
  732. This is a persistent setting, until changed by another SET_TIMEOUT call. 
  733.  
  734. This function is intended to help the APMT client program synchronize with the 
  735. target PM application. For example, if MENU_SELECT is invoked, and the timeout 
  736. is set to 200 then APMT will make up to 200 attempts, if it finds the menu item 
  737. disabled, before giving up. This gives approximately 20 seconds to the 
  738. application to enable the menu item. 
  739.  
  740. The following functions and events are affected by the timeout value. 
  741.  
  742.  o POPUPMENU_QUERY_ALL - Wait for popup menu to appear 
  743.  
  744.  o POPUPMENU_SELECT - Wait for popup menu to appear 
  745.  
  746.  o POPUPMENU_QUERY_STATE - Wait for popup menu to appear 
  747.  
  748.  o SYSMENU_SELECT - Wait for menu item to be enabled 
  749.  
  750.  o MENU_SELECT - Wait for menu item to be enabled 
  751.  
  752.  Notes 
  753.  
  754.  As needs are identified, more functions and events will be added to this list. 
  755.  
  756.  Return Codes 
  757.  
  758.  o 0 - Always. 
  759.  
  760.  
  761. ΓòÉΓòÉΓòÉ 6.13. QUERY_CLIPBOARD_TEXT ΓòÉΓòÉΓòÉ
  762.  
  763. Get the current text in the clipboard 
  764. Syntax 
  765.  
  766.     rc = QUERY_CLIPBOARD_TEXT(stem_variable_name)
  767.  
  768.  
  769. Examples 
  770.  
  771.       rc = QUERY_CLIPBOARD_TEXT("clip_text")
  772.       do i = 1 to clip_text.0
  773.          say clip_text.i
  774.          end
  775.  
  776. Description 
  777.  
  778. This call returns the text in the clipboard in the specified stem variable. 
  779.  
  780. The text in the clipboard is searched for newline characters, and separated 
  781. into lines. Stem 0 contains the number of lines, and the i-th stem contains the 
  782. i-th line. 
  783. Return Codes 
  784.  
  785.  o 4 - No text data in the clipboard. 
  786.  
  787.  o 5 - Could not open the clipboard. 
  788.  
  789.  
  790. ΓòÉΓòÉΓòÉ 6.14. QUERY_PREV_RESPONSETIME ΓòÉΓòÉΓòÉ
  791.  
  792. Query the response time for the previous action, in milliseconds. 
  793. Syntax 
  794.  
  795.     rc = QUERY_PREV_RESPONSETIME(variable_name)
  796.  
  797.  
  798. Examples 
  799.  
  800.        /* Press the PUSHBUTTON "HELP"       */
  801.        rc = PUSHBUTTON_CLICK("HELP")
  802.        /* Wait for a the help window to appear */
  803.        rc = SELECT_WINDOW("Help for*",100)
  804.        /* Display the response time  */
  805.        if rc = 0 then do
  806.           rc = QUERY_PREV_RESPONSETIME("resp")
  807.           say 'The help window took 'resp 'milliseconds to appear'
  808.           end
  809.  
  810. Description 
  811.  
  812. For certain functions, APMT automatically notes the time the command was 
  813. executed. These commands are: PUSHBUTTON_CLICK, START_PROGRAM, MENU_SELECT, and 
  814. KEYBOARD with "ENTER" and "ESC" virtual keys. 
  815.  
  816. If these functions are immediately followed by SELECT_WINDOW, then APMT 
  817. calculates the time elapsed between the previous action and the window's 
  818. appearance on the desktop. 
  819.  
  820. If the next function is QUERY_PREV_RESPONSETIME, then this time elapsed is 
  821. returned in the Rexx variable. 
  822.  
  823. If the conditions are not met, this function will return with rc=5. 
  824. Return Codes 
  825.  
  826.  o 5 - No response time to report. 
  827.  
  828.  
  829. ΓòÉΓòÉΓòÉ 6.15. QUERY_TITLE ΓòÉΓòÉΓòÉ
  830.  
  831. Query the title of the selected window 
  832. Syntax 
  833.  
  834.     rc = QUERY_TITLE(variable_name)
  835.  
  836.  
  837. Examples 
  838.  
  839.        /* Get the full title of the selected window       */
  840.        rc = QUERY_TITLE("title")
  841.        say "title is " title
  842.  
  843. Description 
  844.  
  845. This call returns a variable which contains the full title of the currently 
  846. selected window. 
  847.  
  848.  
  849. ΓòÉΓòÉΓòÉ 6.16. QUERY_WINDOW_HANDLE ΓòÉΓòÉΓòÉ
  850.  
  851. Query the window handle of the selected window. 
  852. Syntax 
  853.  
  854.     rc = QUERY_WINDOW_HANDLE(variable_name)
  855.  
  856.  
  857. Examples 
  858.  
  859.        /* Get the handle  of the selected window */
  860.        rc = QUERY_WINDOW_HANDLE("handle")
  861.        say "handle is " handle
  862.  
  863. Description 
  864.  
  865. This call returns a variable which contains the handle of the currently 
  866. selected window. 
  867.  
  868. This handle is intended to be used with a subsequent SELECT_WINDOW_BY_HANDLE 
  869. function call. 
  870.  
  871.  
  872. ΓòÉΓòÉΓòÉ 6.17. QUERY_WINDOW_POS ΓòÉΓòÉΓòÉ
  873.  
  874. Query the position, size, and presentation flags of the selected window. 
  875. Syntax 
  876.  
  877.     rc = QUERY_WINDOW_POS(stem_variable_name)
  878.  
  879.  
  880. Examples 
  881.  
  882.        /* Get the position of the selected window */
  883.        rc = QUERY_WINDOW_POS("savepos")
  884.  
  885.  
  886. Description 
  887.  
  888. This call returns a stem variable which has exactly 5 values which have the 
  889. information about the selected window's size and position. 
  890.  
  891. These values can be saved, and later used in SET_WINDOW_POS (in the same order) 
  892. to restore the window's position and size. 
  893.  
  894.  
  895. ΓòÉΓòÉΓòÉ 6.18. SET_WINDOW_POS ΓòÉΓòÉΓòÉ
  896.  
  897. Set the position, size, and presentation flags of the selected window. 
  898. Syntax 
  899.  
  900.     rc = SET_WINDOW_POS(x_pos, y_pos, width, height, flags)
  901.     where x_pos, y_pos are the coordinates of the bottom left corner of the
  902.           window relative to the desktop. width and height have the obvious
  903.           meaning. flags are presentation flags for the window.
  904.  
  905.  
  906. Examples 
  907.  
  908.        /* Get the position of the selected window */
  909.        rc = QUERY_WINDOW_POS("pos")
  910.        /* display the window at same location, with dimensions halved */
  911.        rc = SET_WINDOW_POS(pos.1, pos.2, pos.3/2, pos.4/2, pos.5)
  912.  
  913.  
  914. Notes 
  915.  
  916. The parameters are expected to be saved from a previous QUERY_WINDOW_POS call. 
  917. They could have been saved in a file in a previous session. The 5th parameter 
  918. specifies the flags (SWP_ in PM), and can produce unexpected results if set 
  919. arbitrarily. 
  920.  
  921.  
  922. ΓòÉΓòÉΓòÉ 6.19. SAVE_IMAGE ΓòÉΓòÉΓòÉ
  923.  
  924. Save the currently selected window's image in a bitmap file. 
  925. Syntax 
  926.  
  927.     rc = SAVE_IMAGE(file_name)
  928.  
  929.  
  930. Examples 
  931.  
  932.        /* Get the BITMAP image of the selected window       */
  933.        rc = SAVE_IMAGE("current.bmp")
  934.  
  935.  
  936. Description 
  937.  
  938. This call saves the bitmap image of the currently selected window, as a bitmap 
  939. file in the APMT client machine. 
  940.  
  941. The parameter must be a valid file name. 
  942. Notes 
  943.  
  944.  The bitmap is in os/2 1.2 format currently. This may change in the future. 
  945.  
  946.  To view the bitmap, another suitable tool is needed (not provided with APMT). 
  947.  
  948.  Return Codes 
  949.  
  950.  o 5 - The bitmap could not be created. 
  951.  
  952.  o 6 - The specified file could not be opened 
  953.  
  954.  o 7 - The specified file could not be written to 
  955.  
  956.  
  957. ΓòÉΓòÉΓòÉ 6.20. SET_CLIPBOARD_TEXT ΓòÉΓòÉΓòÉ
  958.  
  959. Put the specified text on the clipboard 
  960. Syntax 
  961.  
  962.     rc = SET_CLIPBOARD_TEXT("text")
  963.  
  964.  
  965. Examples 
  966.  
  967.        linefeed = x2c(a)
  968.        rc = SET_CLIPBOARD_TEXT("Line 0"||linefeed||"Line 1")
  969.  
  970. Description 
  971.  
  972. This call empties the clipboard and places the specified text in it. 
  973. Return Codes 
  974.  
  975.  o 4 - Could not write to the clipboard. 
  976.  
  977.  o 5 - Could not open the clipboard. 
  978.  
  979.  
  980. ΓòÉΓòÉΓòÉ 6.21. WAIT ΓòÉΓòÉΓòÉ
  981.  
  982. This function causes a delay for the specified duration. 
  983. Syntax 
  984.  
  985.     rc = WAIT(number_of_milliseconds)
  986.  
  987. Examples 
  988.  
  989.     rc = WAIT("15000")
  990.  
  991.  
  992. Description 
  993.  
  994. This function effectively pauses the REXX program. 
  995.  
  996. The number_of_milliseconds is at least 1. 
  997. Return Codes 
  998.  
  999.  o 0  - always 
  1000.  
  1001.  Notes 
  1002.  
  1003.  The timing is approximate, the real wait time will be slightly higher. 
  1004.  
  1005.  This function simply issues a DosSleep call on behalf of the REXX program. 
  1006.  
  1007.  
  1008. ΓòÉΓòÉΓòÉ 6.22. CHECKBOX_CLICK ΓòÉΓòÉΓòÉ
  1009.  
  1010. This function causes the specified CHECKBOX to be clicked. 
  1011. Syntax 
  1012.  
  1013.     rc = CHECKBOX_CLICK(id[,seq_number])
  1014.          where id is the text of the checkbox,
  1015.          and seq_number is the sequence number of the checkbox with the same id.
  1016.  
  1017. Examples 
  1018.  
  1019.           /* Click the second checkbox labelled 'D' */
  1020.           rc = CHECKBOX_CLICK("D",2)
  1021.  
  1022.           /* Click the first checkbox labelled 'red' */
  1023.           rc = CHECKBOX_CLICK("red")
  1024.  
  1025.  
  1026. Description 
  1027.  
  1028. As a result of this call the specified checkbox may go from checked to 
  1029. unchecked state or vice versa depending on its previous state. In conjunction 
  1030. with the CHECKBOX_QUERY_STATE function, this function can be used to set the 
  1031. desired state. 
  1032.  
  1033. The second parameter is optional and defaults to 1. It is needed only if the 
  1034. window has more than one checkbox with the same id. 
  1035.  
  1036.  
  1037. ΓòÉΓòÉΓòÉ 6.23. CHECKBOX_QUERY_ALL ΓòÉΓòÉΓòÉ
  1038.  
  1039. Return the information on all checkboxes. 
  1040. Syntax 
  1041.  
  1042.     rc =  CHECKBOX_QUERY_ALL(stem_variable_name)
  1043.  
  1044.  
  1045. Examples 
  1046.  
  1047.        /* How many checkboxes?                          */
  1048.        rc = CHECKBOX_QUERY_ALL( "cbox")
  1049.        say "number of checkboxes: " cbox.0
  1050.        do i = 1 to cbox.0
  1051.           say 'checkbox  no 'i 'is: 'cbox.i
  1052.           end
  1053.  
  1054. Description 
  1055.  
  1056. This function returns a stem variable which contains the information on all the 
  1057. checkboxes in the selected window. 
  1058.  
  1059.  
  1060. ΓòÉΓòÉΓòÉ 6.24. CHECKBOX_QUERY_STATE ΓòÉΓòÉΓòÉ
  1061.  
  1062. This function returns the checked, and enabled status of the specified 
  1063. checkbox. 
  1064. Syntax 
  1065.  
  1066.     rc = CHECKBOX_QUERY_STATE(id, stem_variable_name)
  1067.          where id is the text identifying the checkbox.
  1068.  
  1069.  
  1070. Examples 
  1071.  
  1072.        /* Make sure that the drive D is selected, and C is not selected */
  1073.        rc = CHECKBOX_QUERY_STATE("D","state")
  1074.        if rc = 0 then do
  1075.           say 'Check   status: 'state.1
  1076.           say 'Enable  status: 'state.2
  1077.           end
  1078.        if (state.1 = "UNCHECKED") then
  1079.           rc = CHECKBOX_CLICK("D")
  1080.        rc = CHECKBOX_QUERY_STATE("C","state")
  1081.        if (state.1 = "CHECKED") then
  1082.           rc = CHECKBOX_CLICK("C")
  1083.  
  1084. Description 
  1085.  
  1086. This function returns updates the stem variable specified in the last parameter 
  1087. as follows. The .1 stem indicates the checked status and is either "CHECKED" or 
  1088. "UNCHECKED". The .2 stem indicates the enabled status and is either "ENABLED" 
  1089. or "DISABLED". 
  1090.  
  1091.  
  1092. ΓòÉΓòÉΓòÉ 6.25. COMBOBOX_QUERY_ALL_TEXT ΓòÉΓòÉΓòÉ
  1093.  
  1094. Query the text of each item in a combobox. 
  1095. Syntax 
  1096.  
  1097.     rc = COMBOBOX_QUERY_ALL_TEXT(seq_number, stem_variable_name)
  1098.          where seq_number is the sequence number identifying the combobox.
  1099.  
  1100.  
  1101. Examples 
  1102.  
  1103.        /* Look at the items of the second combobox        */
  1104.        rc = COMBOBOX_QUERY_ALL_TEXT("2", "txt")
  1105.        say txt.0 "items found"
  1106.        do i = 1 to txt.0
  1107.           say txt.i
  1108.           end
  1109.  
  1110. Description 
  1111.  
  1112. This call returns a stem variable. The .0 stem contains the number of items in 
  1113. the combobox. The .i stem contains the text of the i-th item. 
  1114.  
  1115.  
  1116. ΓòÉΓòÉΓòÉ 6.26. COMBOBOX_QUERY_TEXT ΓòÉΓòÉΓòÉ
  1117.  
  1118. Query the text of the entryfield in a combobox. 
  1119. Syntax 
  1120.  
  1121.     rc = COMBOBOX_QUERY_TEXT(seq_number, variable_name)
  1122.          where seq_number is the sequence number identifying the combobox.
  1123.  
  1124.  
  1125. Examples 
  1126.  
  1127.        /* Look at the entryfield of the second combobox        */
  1128.        rc = COMBOBOX_QUERY_TEXT("2", "txt")
  1129.        say txt
  1130.  
  1131. Description 
  1132.  
  1133. This call returns a variable whose value is the entryfield of the combobox. 
  1134.  
  1135.  
  1136. ΓòÉΓòÉΓòÉ 6.27. COMBOBOX_SELECTITEM ΓòÉΓòÉΓòÉ
  1137.  
  1138. Select the specified item in a combobox. 
  1139. Syntax 
  1140.  
  1141.     rc = COMBOBOX_QUERY_ALL_TEXT(seq_number, item_number)
  1142.          where seq_number is the sequence number identifying the combobox,
  1143.          and item_number identifies the item.
  1144.  
  1145.  
  1146. Examples 
  1147.  
  1148.        /* Select the third item of the second combobox        */
  1149.        rc =  COMBOBOX_SELECTITEM("2", "3")
  1150.  
  1151. Description 
  1152.  
  1153. This call selects the specified item of the combobox. 
  1154. Return Codes 
  1155.  
  1156.  o 6 - Selection failed. Probably item number is out of range. 
  1157.  
  1158.  
  1159. ΓòÉΓòÉΓòÉ 6.28. COMBOBOX_SET_TEXT ΓòÉΓòÉΓòÉ
  1160.  
  1161. Set the text of the entryfield in a combobox. 
  1162. Syntax 
  1163.  
  1164.     rc = COMBOBOX_SET_TEXT( seq_number, text)
  1165.          where seq_number is the sequence number identifying the combobox,
  1166.          and text is what it should be set to.
  1167.  
  1168.  
  1169. Examples 
  1170.  
  1171.        /* Set the value of the second combobox      */
  1172.        rc = COMBOBOX_SET_TEXT("2", "D:")
  1173.  
  1174. Description 
  1175.  
  1176. This function sets the combobox text as specified if the text matches one of 
  1177. the items. If the specified text matches one of the items in the combobox, that 
  1178. item is selected. 
  1179.  
  1180. The specified text has to match only the prefix of an item. 
  1181. Notes 
  1182.  
  1183.  This is a 'convenience' function. 
  1184.  
  1185.  A better way is to enter the data is to use ENTRYFIELD_SET_FOCUS, followed by 
  1186.  KEYBOARD. 
  1187.  
  1188.  Return Codes 
  1189.  
  1190.  o 5 - The text does not match one of the items. 
  1191.  
  1192.  
  1193. ΓòÉΓòÉΓòÉ 6.29. CONTAINER_DESELECTITEM ΓòÉΓòÉΓòÉ
  1194.  
  1195. Deselect an item in the specified container. 
  1196. Syntax 
  1197.  
  1198.     rc = CONTAINER_DESELECTITEM(seq_number, object_identifier)
  1199.          where seq_number is the sequence number identifying the container,
  1200.          and object_identifier is
  1201.              either the text string identifying the object
  1202.              or #n with n = the object number
  1203.  
  1204.  
  1205. Examples 
  1206.  
  1207.        rc = CONTAINER_DESELECTITEM(1, "Main")
  1208.        rc = CONTAINER_DESELECTITEM(1, "#5")
  1209.  
  1210.  
  1211. Description 
  1212.  
  1213. This function deselects an object whose text has a prefix matching object_text. 
  1214. The match is case sensitive. 
  1215.  
  1216. The object may also be identified with "#" followed by its sequence number in 
  1217. the container. 
  1218. Return Codes 
  1219.  
  1220.  o 5 - No matching object found. 
  1221.  
  1222.  
  1223. ΓòÉΓòÉΓòÉ 6.30. CONTAINER_QUERY_COUNT ΓòÉΓòÉΓòÉ
  1224.  
  1225. Return the number of objects in the specified container. 
  1226. Syntax 
  1227.  
  1228.     rc = CONTAINER_QUERY_COUNT(seq_number, variable_name)
  1229.          where seq_number is the sequence number identifying the CONTAINER.
  1230.  
  1231.  
  1232. Examples 
  1233.  
  1234.        /* How many objects?                              */
  1235.        rc = CONTAINER_QUERY_COUNT("1", "count")
  1236.        say "number of objects in the container: " count
  1237.  
  1238. Description 
  1239.  
  1240. This function returns a variable which contains the number of objects in the 
  1241. container identified by the sequence number in the selected window. 
  1242.  
  1243.  
  1244. ΓòÉΓòÉΓòÉ 6.31. CONTAINER_SELECTITEM ΓòÉΓòÉΓòÉ
  1245.  
  1246. Select (high light) an item in the specified container. 
  1247. Syntax 
  1248.  
  1249.     rc = CONTAINER_SELECTITEM(seq_number, object_identifier)
  1250.          where seq_number is the sequence number identifying the container,
  1251.          and object_identifier is
  1252.              either the text string identifying the object
  1253.              or #n with n = the object number
  1254.  
  1255.  
  1256. Examples 
  1257.  
  1258.        /* Open the object labeled "Main"          */
  1259.        rc = CONTAINER_SELECTITEM(1, "Main")
  1260.        rc = KEYBOARD("ENTER")
  1261.        /* Select the 5th item on the desktop           */
  1262.        rc = SELECT_WINDOW("Desktop")
  1263.        rc = CONTAINER_SELECTITEM(1, "#5")
  1264.  
  1265.  
  1266. Description 
  1267.  
  1268. This function only highlights an object whose text has a prefix matching 
  1269. object_text. The match is case sensitive. 
  1270.  
  1271. The object may also be identified with "#" followed by its sequence number in 
  1272. the container. 
  1273. Return Codes 
  1274.  
  1275.  o 5 - No matching object found. 
  1276.  
  1277.  Notes 
  1278.  
  1279.  The first parameter is expected to be 1 as most windows have only one 
  1280.  container. 
  1281.  
  1282.  Other objects which were previously selected, remain selected. By using 
  1283.  KEYBOARD("\","C"), all the objects may be de-selected. 
  1284.  
  1285.  
  1286. ΓòÉΓòÉΓòÉ 6.32. DESKTOP_LOCK ΓòÉΓòÉΓòÉ
  1287.  
  1288. Lockup the desktop. 
  1289. Syntax 
  1290.  
  1291.     rc = DESKTOP_LOCK()
  1292.  
  1293.  
  1294. Examples 
  1295.  
  1296.        /* Lock up                                        */
  1297.        rc = DESKTOP_LOCK()
  1298.  
  1299. Description 
  1300.  
  1301. This function locks up the desktop. To unlock, use DESKTOP_UNLOCK, or type in 
  1302. the password. 
  1303.  
  1304.  
  1305. ΓòÉΓòÉΓòÉ 6.33. DESKTOP_UNLOCK ΓòÉΓòÉΓòÉ
  1306.  
  1307. unlock the desktop. 
  1308. Syntax 
  1309.  
  1310.     rc = DESKTOP_UNLOCK(password)
  1311.  
  1312.  
  1313. Examples 
  1314.  
  1315.        /* Unlock the desktop                             */
  1316.        password = 'xyzzz'
  1317.        rc = DESKTOP_UNLOCK(password)
  1318.  
  1319. Description 
  1320.  
  1321. This function unlock the desktop. 
  1322. Return Codes 
  1323.  
  1324.  o 4 - Password did not match, or desktop already unlocked. 
  1325.  
  1326.  
  1327. ΓòÉΓòÉΓòÉ 6.34. ENTRYFIELD_HOW_MANY ΓòÉΓòÉΓòÉ
  1328.  
  1329. Return the number of entryfields. 
  1330. Syntax 
  1331.  
  1332.     rc = ENTRYFIELD_HOW_MANY( variable_name)
  1333.  
  1334.  
  1335. Examples 
  1336.  
  1337.        /* How many entryfields?                          */
  1338.        rc = ENTRYFIELD_HOW_MANY( "count")
  1339.        say "number of entryfields: " count
  1340.  
  1341. Description 
  1342.  
  1343. This function returns a variable which contains the number of entryfields in 
  1344. the selected window. 
  1345.  
  1346.  
  1347. ΓòÉΓòÉΓòÉ 6.35. ENTRYFIELD_QUERY_TEXT ΓòÉΓòÉΓòÉ
  1348.  
  1349. Query the text of an entry field. 
  1350. Syntax 
  1351.  
  1352.     rc = ENTRYFIELD_QUERY_TEXT( seq_number, variable_name)
  1353.          where seq_number is the sequence number identifying the entryfield.
  1354.  
  1355.  
  1356. Examples 
  1357.  
  1358.        /* Look at the items of the first entryfield      */
  1359.        rc = ENTRYFIELD_QUERY_TEXT("1", "txt")
  1360.        say txt
  1361.  
  1362. Description 
  1363.  
  1364. This function returns a variable which contains the text of the specified 
  1365. entryfield. 
  1366.  
  1367.  
  1368. ΓòÉΓòÉΓòÉ 6.36. ENTRYFIELD_SET_FOCUS ΓòÉΓòÉΓòÉ
  1369.  
  1370. This function sets the cursor on the specified entry field. 
  1371. Syntax 
  1372.  
  1373.     rc = ENTRYFIELD_SET_FOCUS(seq_number)
  1374.  
  1375. Examples 
  1376.  
  1377.        /* Enter the string text into the second entryfield     */
  1378.        rc = ENTRYFIELD_SET_FOCUS(2)
  1379.        rc = KEYBOARD("HOME");
  1380.        rc = KEYBOARD("DELETE","C");
  1381.        text    = 'PASSWORD'
  1382.        rc = KEYBOARD(text)
  1383.  
  1384. Description 
  1385.  
  1386. This function is used to set the input focus into a entry field. 
  1387. Notes 
  1388.  
  1389.  For the purposes of  this function, the entryfield part of a combobox is 
  1390.  treated like any other entryfield. For example if the window has entryfield 1, 
  1391.  combobox, entryfield 2, this function will treat the combobox as entryfield 2, 
  1392.  and entryfield 2 as entryfield 3. 
  1393.  
  1394.  
  1395. ΓòÉΓòÉΓòÉ 6.37. ENTRYFIELD_SET_TEXT ΓòÉΓòÉΓòÉ
  1396.  
  1397. Set the text of an entry field. 
  1398. Syntax 
  1399.  
  1400.     rc = ENTRYFIELD_SET_TEXT( seq_number, text)
  1401.          where seq_number is the sequence number identifying the entryfield,
  1402.          and text is what it should be set to.
  1403.  
  1404.  
  1405. Examples 
  1406.  
  1407.        /* Set the value of the first entryfield      */
  1408.        rc = ENTRYFIELD_SET_TEXT("1", "MYAPP.EXE")
  1409.  
  1410. Description 
  1411.  
  1412. This function sets the entryfield as specified. APMT will not update the field 
  1413. if it is not input enabled. 
  1414. Notes 
  1415.  
  1416.  This is a 'convenience' function. It may be misused by entering data in a way 
  1417.  not available to the user. For example, if this is used to set the text in a 
  1418.  non-display field (as for passwords), the password may be visible. 
  1419.  
  1420.  A better way is to use ENTRYFIELD_SET_FOCUS, followed by KEYBOARD calls. 
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  Return Codes 
  1426.  
  1427.  o 6 - The field is not enabled. 
  1428.  
  1429.  
  1430. ΓòÉΓòÉΓòÉ 6.38. KEYBOARD ΓòÉΓòÉΓòÉ
  1431.  
  1432. Simulate a keyboard event. 
  1433. Syntax 
  1434.  
  1435.     rc = KEYBOARD( key  [,shift_state])
  1436.  
  1437.  
  1438. Examples 
  1439.  
  1440.         rc = KEYBOARD("O","A")          /* simulate ALT+O       */
  1441.         rc = KEYBOARD("P","SA")         /* simulate ALT+SHIFT+P */
  1442.         rc = KEYBOARD("4","C")          /* simulate CTRL+4      */
  1443.         rc = KEYBOARD("F4","A")         /* simulate ALT+F4      */
  1444.         rc = KEYBOARD("ENTER")          /* simulate ENTER       */
  1445.         rc = KEYBOARD("ENTE")           /* simulate E,N,T,E     */
  1446.         rc = KEYBOARD("F12")            /* simulate F12         */
  1447.         rc = KEYBOARD("F123")           /* simulate F,1,2,3     */
  1448.  
  1449. Description 
  1450.  
  1451. The first parameter identifies either a virtual key or a character string. If 
  1452. the first parameter is not a recognized virtual key, all its characters will be 
  1453. played successively. However, strings that are longer than 30 may be truncated 
  1454. when played by APMT 
  1455.  
  1456. The second  parameter is optional and is a string consisting of one or more of 
  1457. the characters 'A', 'C', or 'S' to indicate ALT, CTRL, and SHIFT states 
  1458. respectively. The order of these characters is irrelevant, and duplicates and 
  1459. other characters are ignored. 
  1460.  
  1461.  The following virtual keys are recognized. These are case sensitive. 
  1462.  
  1463.  o BACKSPACE 
  1464.  
  1465.  o BACKTAB 
  1466.  
  1467.  o DELETE 
  1468.  
  1469.  o DOWN 
  1470.  
  1471.  o END 
  1472.  
  1473.  o ENTER 
  1474.  
  1475.  o ESC 
  1476.  
  1477.  o F1 
  1478.  
  1479.  o F2 
  1480.  
  1481.  o F3 
  1482.  
  1483.  o F4 
  1484.  
  1485.  o F5 
  1486.  
  1487.  o F6 
  1488.  
  1489.  o F7 
  1490.  
  1491.  o F8 
  1492.  
  1493.  o F9 
  1494.  
  1495.  o F10 
  1496.  
  1497.  o F11 
  1498.  
  1499.  o F12 
  1500.  
  1501.  o HOME 
  1502.  
  1503.  o INSERT 
  1504.  
  1505.  o LEFT 
  1506.  
  1507.  o NEWLINE 
  1508.  
  1509.  o PAGEDOWN 
  1510.  
  1511.  o PAGEUP 
  1512.  
  1513.  o RIGHT 
  1514.  
  1515.  o SPACE 
  1516.  
  1517.  o TAB 
  1518.  
  1519.  o UP 
  1520.  
  1521.  Return Codes 
  1522.  
  1523.  o 5  - Current window could not be made active. 
  1524.  
  1525.  Notes 
  1526.  
  1527.  This function determines the keystroke message to be played to the 
  1528.  application. It is not guaranteed that this will have the same effect as a 
  1529.  user's keyboard input, depending on how the application processes keyboard 
  1530.  messages. However, for "normal" applications, this will have the desired 
  1531.  effect. 
  1532.  
  1533.  Before the keystroke is played, the selected window will be brought to focus 
  1534.  if the focus belongs to another window on the desktop. 
  1535.  
  1536.  This function will normally always return code 0. This however does not 
  1537.  necessarily mean that the keystroke had the desired effect. 
  1538.  
  1539.  This function cannot be used to send keystrokes to DOS text windows. 
  1540.  
  1541.  
  1542. ΓòÉΓòÉΓòÉ 6.39. LISTBOX_DESELECTITEM ΓòÉΓòÉΓòÉ
  1543.  
  1544. Deselect the specified item in a multiple selection listbox. 
  1545. Syntax 
  1546.  
  1547.     rc = LISTBOX_DESELECTITEM(seq_number, item_number)
  1548.          where seq_number is the sequence number identifying the listbox,
  1549.          and item_number identifies the item.
  1550.  
  1551.  
  1552. Examples 
  1553.  
  1554.        /* Deselect the third item of the second multiple selection listbox */
  1555.        rc =  LISTBOX_DESELECTITEM("2", "3")
  1556.  
  1557. Description 
  1558.  
  1559. This call deselects the specified item of the listbox. 
  1560. Notes 
  1561.  
  1562.  This function works only on multiple selection listboxes. 
  1563.  
  1564.  Return Codes 
  1565.  
  1566.  o 5 - The listbox is not multiple selection 
  1567.  
  1568.  o 6 - Deselection  failed. Probably item number is out of range 
  1569.  
  1570.  
  1571. ΓòÉΓòÉΓòÉ 6.40. LISTBOX_SELECTITEM ΓòÉΓòÉΓòÉ
  1572.  
  1573. Select the specified item in a listbox. 
  1574. Syntax 
  1575.  
  1576.     rc = LISTBOX_SELECTITEM(seq_number, item_number)
  1577.          where seq_number is the sequence number identifying the listbox,
  1578.          and item_number identifies the item.
  1579.  
  1580.  
  1581. Examples 
  1582.  
  1583.        /* Select the third item of the second listbox */
  1584.        rc =  LISTBOX_SELECTITEM("2", "3")
  1585.  
  1586. Description 
  1587.  
  1588. This call selects the specified item of the listbox, and places the focus on 
  1589. the listbox. 
  1590. Return Codes 
  1591.  
  1592.  o 6 - Selection failed. Probably item number is out of range 
  1593.  
  1594.  
  1595. ΓòÉΓòÉΓòÉ 6.41. LISTBOX_QUERY_COUNT ΓòÉΓòÉΓòÉ
  1596.  
  1597. Return the number of items in a listbox 
  1598. Syntax 
  1599.  
  1600.     rc = LISTBOX_QUERY_COUNT(seq_number, variable_name)
  1601.          where seq_number is the sequence number identifying the listbox.
  1602.  
  1603.  
  1604. Examples 
  1605.  
  1606.        /* How many items in the first listbox? */
  1607.        rc =  LISTBOX_QUERY_COUNT("1", "item_count")
  1608.        say item_count 'items in the listbox'
  1609.  
  1610. Description 
  1611.  
  1612. This call returns the number of items in the listbox. 
  1613.  
  1614.  
  1615. ΓòÉΓòÉΓòÉ 6.42. LISTBOX_QUERY_TEXT ΓòÉΓòÉΓòÉ
  1616.  
  1617. Returns the text of the specified item in the specified listbox. 
  1618. Syntax 
  1619.  
  1620.     rc = LISTBOX_QUERY_TEXT(seq_number, item_number, variable_name)
  1621.          where seq_number is the sequence number identifying the listbox,
  1622.          and item_number identifies the item.
  1623.  
  1624.  
  1625. Examples 
  1626.  
  1627.        /* Get the text of all items in the second listbox */
  1628.        rc =  LISTBOX_QUERY_COUNT(2, "cnt")
  1629.        do i = 1 to cnt
  1630.           rc = LISTBOX_QUERY_TEXT(2,i-1,"text")
  1631.           say "Listbox item 'i 'is: 'text
  1632.           end
  1633.  
  1634. Description 
  1635.  
  1636. This function returns the text of the specified item in the specified listbox. 
  1637. Notes 
  1638.  
  1639.  Sometimes the text of the listbox cannot be queried if the listbox has the 
  1640.  OWNERDRAW style. In such cases the returned string may be null. 
  1641.  
  1642.  item_number is indexed on 0. To query the first item, use 0 etc... 
  1643.  
  1644.  Return Codes 
  1645.  
  1646.  o 6 - Query failed. Probably item number is out of range 
  1647.  
  1648.  
  1649. ΓòÉΓòÉΓòÉ 6.43. MENU_QUERY_ALL ΓòÉΓòÉΓòÉ
  1650.  
  1651. Returns the text of each menu item at the specified level. 
  1652. Syntax 
  1653.  
  1654.     rc =  MENU_QUERY_ALL([level1,] [level2,] [level3,] stem_variable_name)
  1655.          where levels specify the point in the menu hierarchy to list items
  1656.          from.
  1657.  
  1658.  
  1659. Examples 
  1660.  
  1661.        /* Get contents of the action bar */
  1662.        rc =  MENU_QUERY_ALL("actionbar")
  1663.        if rc = 0 then
  1664.           do i = 1 to actionbar.0
  1665.              say 'Action bar item 'i 'is :'actionbar.i
  1666.              end
  1667.        /* Get the contents of the Options action bar item */
  1668.        rc =  MENU_QUERY_ALL("~Options","options")
  1669.        if rc = 0 then
  1670.           do i = 1 to options.0
  1671.              say 'Option choice 'i 'is :'options.i
  1672.              end
  1673.  
  1674.  
  1675. Description 
  1676.  
  1677. This function returns the text of each of the action bar items at the specified 
  1678. level starting from the actionbar. 
  1679. Notes 
  1680.  
  1681.  The returned text for any menu item may contain mnemonic indicators. For 
  1682.  example in the above example, the tilde will appear in front of the mnemonic 
  1683.  character O in Options. 
  1684.  
  1685.  On input, however, the tilde is not necessary, and only the prefix of the 
  1686.  menuitem text needs to be specified. 
  1687.  
  1688.  
  1689. ΓòÉΓòÉΓòÉ 6.44. MENU_QUERY_STATE ΓòÉΓòÉΓòÉ
  1690.  
  1691. Returns information about the state of a menu item at the specified level. 
  1692. Syntax 
  1693.  
  1694.     rc =  MENU_QUERY_STATE([level1,] [level2,] [level3,] stem_variable_name)
  1695.          where levels specify the point in the menu hierarchy.
  1696.  
  1697.  
  1698. Examples 
  1699.  
  1700.        /* Get state of a menuitem in the action bar */
  1701.        rc =  MENU_QUERY_STATE("Options","Centered","state")
  1702.        if rc = 0 then do
  1703.           say 'Check   status: 'state.1
  1704.           say 'Hilite  status: 'state.2
  1705.           say 'Enable  status: 'state.3
  1706.           say 'Valid   status: 'state.4
  1707.           end
  1708.  
  1709.  
  1710. Description 
  1711.  
  1712. This function returns updates the stem variable specified in the last parameter 
  1713. as follows. The .1 stem indicates the checked status and is either "CHECKED" or 
  1714. "UNCHECKED". The .2 stem indicates the hilite status and is either "HILITED" or 
  1715. "UNHILITED". The .3 stem indicates the enabled status and is either "ENABLED" 
  1716. or "DISABLED". "HILITED" or "UNHILITED". The .4 stem indicates the valid status 
  1717. and is either "VALID" or "INVALID". 
  1718.  
  1719.  
  1720. ΓòÉΓòÉΓòÉ 6.45. MENU_SELECT ΓòÉΓòÉΓòÉ
  1721.  
  1722. Selects the specified menu item. 
  1723. Syntax 
  1724.  
  1725.     rc =  MENU_SELECT( level1   [,level2] [,level3] )
  1726.          where levels identify the menu item to be selected.
  1727.  
  1728.  
  1729. Examples 
  1730.  
  1731.        /* Select the File option of the action bar */
  1732.        rc =  MENU_SELECT("F~ile")
  1733.        rc =  MENU_SELECT("File")         /* This will match also    */
  1734.        rc =  MENU_SELECT("Fi")           /* This too                */
  1735.        /* Select the "Grid" choice of the "Options" action bar item */
  1736.        rc =  MENU_SELECT("~Options","G~rid")
  1737.        rc =  MENU_SELECT("Options","Grid")/* This will match also   */
  1738.  
  1739.  
  1740. Description 
  1741.  
  1742. This function selects the specified item at the level specified starting from 
  1743. the actionbar. 
  1744. Notes 
  1745.  
  1746.  The matching is case sensitive, but the tilde is not needed, and only the 
  1747.  prefix needs to be specified. 
  1748.  
  1749.  Return Codes 
  1750.  
  1751.  o 5 - Select failed. Menu item disabled or invalid. 
  1752.  
  1753.  
  1754. ΓòÉΓòÉΓòÉ 6.46. MLE_HOW_MANY ΓòÉΓòÉΓòÉ
  1755.  
  1756. Return the number of multi line entryfields. 
  1757. Syntax 
  1758.  
  1759.     rc = MLE_HOW_MANY( variable_name)
  1760.  
  1761.  
  1762. Examples 
  1763.  
  1764.        /* How many MLE controls                   */
  1765.        rc = MLE_HOW_MANY( "count")
  1766.        say "number of MLE controls: " count
  1767.  
  1768. Description 
  1769.  
  1770. This function returns a variable which contains the number of MLE controls in 
  1771. the selected window. 
  1772.  
  1773.  
  1774. ΓòÉΓòÉΓòÉ 6.47. MLE_QUERY_TEXT ΓòÉΓòÉΓòÉ
  1775.  
  1776. Query the text of an multi line entry field. 
  1777. Syntax 
  1778.  
  1779.     rc =  MLE_QUERY_TEXT(seq_number, variable_name)
  1780.          where seq_number is the sequence number identifying the MLE.
  1781.  
  1782.  
  1783. Examples 
  1784.  
  1785.        /* Look at the items of the second MLE      */
  1786.        rc = MLE_QUERY_TEXT("2", "txt")
  1787.        say txt
  1788.  
  1789. Description 
  1790.  
  1791. This function returns a variable which contains the text of the specified MLE. 
  1792.  
  1793.  
  1794. ΓòÉΓòÉΓòÉ 6.48. MLE_SET_TEXT ΓòÉΓòÉΓòÉ
  1795.  
  1796. Set the text of an MLE field. 
  1797. Syntax 
  1798.  
  1799.     rc = MLE_SET_TEXT( seq_number, text)
  1800.          where seq_number is the sequence number identifying the MLE field,
  1801.          and text is what it should be set to.
  1802.  
  1803.  
  1804. Examples 
  1805.  
  1806.        /* Set the value of the first MLE field      */
  1807.        rc = MLE_SET_TEXT("1", "MYAPP.EXE")
  1808.  
  1809. Description 
  1810.  
  1811. This function sets the MLE field as specified. APMT will not update the field 
  1812. if it is not input enabled. 
  1813. Return Codes 
  1814.  
  1815.  o 6 - The field is not enabled. 
  1816.  
  1817.  
  1818. ΓòÉΓòÉΓòÉ 6.49. NOTEBOOK_PUSHTAB ΓòÉΓòÉΓòÉ
  1819.  
  1820. Simulates clicking on the specified tab of a notebook. 
  1821. Syntax 
  1822.  
  1823.     rc = NOTEBOOK_PUSHTAB(seq_number, id)
  1824.          where seq_number is the sequence number of the notebook,
  1825.          and id is the text of the tab.
  1826.  
  1827.  
  1828. Examples 
  1829.  
  1830.        /* Select the 'Fonts' page */
  1831.        rc = NOTEBOOK_PUSHTAB("1", "Fonts")
  1832.  
  1833. Description 
  1834.  
  1835. This function simulates the clicking on the tab of a notebook page. 
  1836. Return Codes 
  1837.  
  1838.  o 5 - Tab not found. 
  1839.  
  1840.  
  1841. ΓòÉΓòÉΓòÉ 6.50. NOTEBOOK_QUERY_TABS ΓòÉΓòÉΓòÉ
  1842.  
  1843. Return the information on all tabs of a notebook. 
  1844. Syntax 
  1845.  
  1846.     rc = NOTEBOOK_QUERY_TABS(seq_number,stem_variable_name)
  1847.  
  1848. Examples 
  1849.  
  1850.        /* List all the tabs of the notebook       */
  1851.        rc = NOTEBOOK_QUERY_TABS(1,"tabs")
  1852.        say "number of tabs: " tabs.0
  1853.        do i = 1 to tabs.0
  1854.           say 'Tab 'i 'is: 'tabs.i
  1855.           end
  1856.  
  1857. Description 
  1858.  
  1859. This function returns a stem variable which contains the information on all the 
  1860. tabs of the specified notebook. The .0 stem contains the number of tabs, and 
  1861. the .i stem contains the text of the i-th tab. 
  1862.  
  1863.  
  1864. ΓòÉΓòÉΓòÉ 6.51. POPUPMENU_QUERY_ALL ΓòÉΓòÉΓòÉ
  1865.  
  1866. Returns the text of each popup menu item at the specified level. 
  1867. Syntax 
  1868.  
  1869.     rc =  POPUPMENU_QUERY_ALL([level1,] [level2,] [level3,] stem_variable_name)
  1870.          where levels specify the point in the menu hierarchy to list items
  1871.          from.
  1872.  
  1873.  
  1874. Description 
  1875.  
  1876. This function is similar to MENU_QUERY_ALL, except that it operates on a open 
  1877. popup menu. It is assumed that action such SHIFT+F10 has been issued to cause a 
  1878. popup prior to invoking this call. 
  1879.  
  1880.  
  1881. ΓòÉΓòÉΓòÉ 6.52. POPUPMENU_QUERY_STATE ΓòÉΓòÉΓòÉ
  1882.  
  1883. Returns information about the state of a POPUPMENU item at the specified level. 
  1884. Syntax 
  1885.  
  1886.     rc =  POPUPMENU_QUERY_ALL([level1,] [level2,] [level3,] stem_variable_name)
  1887.          where levels specify the point in the POPUPMENU hierarchy.
  1888.  
  1889.  
  1890. Description 
  1891.  
  1892. This function is similar to MENU_QUERY_STATE, except that it operates on a open 
  1893. popup menu. It is assumed that action such SHIFT+F10 has been issued to cause a 
  1894. popup prior to invoking this call. 
  1895.  
  1896.  
  1897. ΓòÉΓòÉΓòÉ 6.53. POPUPMENU_SELECT ΓòÉΓòÉΓòÉ
  1898.  
  1899. Selects the specified menu item from the popup menu window. 
  1900. Syntax 
  1901.  
  1902.     rc =  POPUPMENU_SELECT( level1   [,level2] [,level3] )
  1903.          where levels identify the menu item to be selected.
  1904.  
  1905.  
  1906. Description 
  1907.  
  1908. This function is similar to MENU_SELECT, except that it operates on a open 
  1909. popup menu. It is assumed that action such SHIFT+F10 has been issued to cause a 
  1910. popup prior to invoking this call. 
  1911. Return Codes 
  1912.  
  1913.  o 5 - Popup menu item disabled or invalid. 
  1914.  
  1915.  
  1916. ΓòÉΓòÉΓòÉ 6.54. PUSHBUTTON_CLICK ΓòÉΓòÉΓòÉ
  1917.  
  1918. Simulates clicking of the specified pushbutton. 
  1919. Syntax 
  1920.  
  1921.     rc = PUSHBUTTON_CLICK(id[,seq_number])
  1922.          where id is the text of the checkbox,
  1923.          and seq_number is the sequence number of the pushbutton with the same id.
  1924.  
  1925.  
  1926. Examples 
  1927.  
  1928.        /* Click on Search */
  1929.        rc = PUSHBUTTON_CLICK("Search")
  1930.        /* Click on the third pushbutton with a blank title */
  1931.        rc = PUSHBUTTON_CLICK(" ",3)
  1932.  
  1933. Description 
  1934.  
  1935. This function simulates the clicking on a pushbutton. The seq_number is 
  1936. optional and defaults to 1. It is needed only if the window has more than one 
  1937. pushbutton with the same id. 
  1938.  
  1939.  
  1940. ΓòÉΓòÉΓòÉ 6.55. PUSHBUTTON_QUERY_ALL ΓòÉΓòÉΓòÉ
  1941.  
  1942. Return the information on all pushbuttons. 
  1943. Syntax 
  1944.  
  1945.     rc =  PUSHBUTTON_QUERY_ALL(stem_variable_name)
  1946.  
  1947.  
  1948. Examples 
  1949.  
  1950.        /* How many pushbuttons?                          */
  1951.        rc = PUSHBUTTON_QUERY_ALL( "buttons")
  1952.        say "number of pushbuttons: " buttons.0
  1953.        do i = 1 to buttons.0
  1954.           say 'button no 'i 'is: 'buttons.i
  1955.           end
  1956.  
  1957. Description 
  1958.  
  1959. This function returns a stem variable which contains the information on all the 
  1960. pushbuttons in the selected window. The .0 stem contains the number of 
  1961. pushbuttons, and the .i stem contains the text of the i-th pushbutton. If the 
  1962. pushbutton is disabled, then the text is followed by the word '*DISABLED*'. 
  1963.  
  1964.  
  1965. ΓòÉΓòÉΓòÉ 6.56. RADIOBUTTON_CLICK ΓòÉΓòÉΓòÉ
  1966.  
  1967. This function causes the specified radiobutton to be clicked. 
  1968. Syntax 
  1969.  
  1970.     rc =  RADIOBUTTON_CLICK(id[,seq_number])
  1971.          where id is the text identifying the radiobutton,
  1972.          and seq_number is the sequence number of the radiobutton with the id.
  1973.  
  1974. Examples 
  1975.  
  1976.     /* Click on the radiobutton "red" */
  1977.     rc = RADIOBUTTON_CLICK("red")
  1978.  
  1979.     /* There are three "red" radiobuttons, press the third one  */
  1980.     rc = RADIOBUTTON_CLICK("red",3)
  1981.  
  1982. Description 
  1983.  
  1984. As a result of this call the specified radiobutton will go to selected state. 
  1985.  
  1986. The second parameter is optional and defaults to 1. It is needed only if the 
  1987. window has more than one radiobutton with the same id. 
  1988.  
  1989.  
  1990. ΓòÉΓòÉΓòÉ 6.57. RADIOBUTTON_QUERY_ALL ΓòÉΓòÉΓòÉ
  1991.  
  1992. Return the information on all radiobuttons. 
  1993. Syntax 
  1994.  
  1995.     rc =  RADIOBUTTON_QUERY_ALL(stem_variable_name)
  1996.  
  1997.  
  1998. Examples 
  1999.  
  2000.        /* How many radiobuttons?                          */
  2001.        rc = RADIOBUTTON_QUERY_ALL( "button")
  2002.        say "number of radiobuttons: " button.0
  2003.        do i = 1 to buttons.0
  2004.           say 'radiobutton no 'i 'is: 'button.i
  2005.           end
  2006.  
  2007. Description 
  2008.  
  2009. This function returns a stem variable which contains the information on all the 
  2010. radiobuttons in the selected window. 
  2011.  
  2012.  
  2013. ΓòÉΓòÉΓòÉ 6.58. RADIOBUTTON_QUERY_STATE ΓòÉΓòÉΓòÉ
  2014.  
  2015. Return the checked, and enable status of the specified radiobutton. 
  2016. Syntax 
  2017.  
  2018.     rc = RADIOBUTTON_QUERY_STATE(id, stem_variable_name)
  2019.          where id is the text identifying the radiobutton.
  2020.  
  2021.  
  2022. Examples 
  2023.  
  2024.        /* return the status of the "D" radiobutton */
  2025.        rc = RADIOBUTTON_QUERY_STATE("D","state")
  2026.        if state.1 = 'CHECKED' then say 'selected'
  2027.        if state.2 = 'DISABLED' then say 'disabled'
  2028.  
  2029. Description 
  2030.  
  2031. This function returns updates the stem variable specified in the last parameter 
  2032. as follows. The .1 stem indicates the checked status and is either "CHECKED" or 
  2033. "UNCHECKED". The .2 stem indicates the enabled status and is either "ENABLED" 
  2034. or "DISABLED". 
  2035.  
  2036.  
  2037. ΓòÉΓòÉΓòÉ 6.59. SPINBUTTON_QUERY_LIMITS ΓòÉΓòÉΓòÉ
  2038.  
  2039. Return the limits of the values of the specified spinbutton. 
  2040. Syntax 
  2041.  
  2042.     rc =  SPINBUTTON_QUERY_LIMITS(seq_number, stem_variable_name)
  2043.          where seq_number is the sequence number identifying the SPINBUTTON.
  2044.  
  2045.  
  2046. Examples 
  2047.  
  2048.        /* return the limits of the second spinbutton */
  2049.        rc = SPINBUTTON_QUERY_LIMITS("2","limits")
  2050.        say 'Lower limit is 'limits.1
  2051.        say 'Upper limit is 'limits.2
  2052.  
  2053. Description 
  2054.  
  2055. This function returns the limits of the specified spinbutton. Stem .0 of the 
  2056. returned variable is always 2. Stems .1 and .2 contain the lower and upper 
  2057. limits. 
  2058. Notes 
  2059.  
  2060.  This function does not seem to work under OS/2 2.0, possibly because of a PM 
  2061.  bug. It has been found to work under OS/2 2.1. 
  2062.  
  2063.  Return Codes 
  2064.  
  2065.  o 5 - Limits could not be determined. Spinbutton is probably disabled. 
  2066.  
  2067.  
  2068. ΓòÉΓòÉΓòÉ 6.60. SPINBUTTON_QUERY_TEXT ΓòÉΓòÉΓòÉ
  2069.  
  2070. Query the text of a spinbutton control. 
  2071. Syntax 
  2072.  
  2073.     rc =  SPINBUTTON_QUERY_TEXT(seq_number, variable_name)
  2074.          where seq_number is the sequence number identifying the SPINBUTTON.
  2075.  
  2076.  
  2077. Examples 
  2078.  
  2079.        /* Look at the text of the first SPINBUTTON      */
  2080.        rc = SPINBUTTON_QUERY_TEXT("1", "txt")
  2081.        say txt
  2082.  
  2083. Description 
  2084.  
  2085. This function returns a variable which contains the text of the specified 
  2086. SPINBUTTON. 
  2087.  
  2088.  
  2089. ΓòÉΓòÉΓòÉ 6.61. SPINBUTTON_SPINDOWN ΓòÉΓòÉΓòÉ
  2090.  
  2091. Spin the spinbutton down one unit. 
  2092. Syntax 
  2093.  
  2094.     rc =  SPINBUTTON_SPINDOWN(seq_number)
  2095.          where seq_number is the sequence number identifying the SPINBUTTON.
  2096.  
  2097.  
  2098. Examples 
  2099.  
  2100.        /* Spin down the first spinbutton, and look at the text     */
  2101.        rc =  SPINBUTTON_SPINDOWN("1")
  2102.        rc =  SPINBUTTON_QUERY_TEXT("1", "txt")
  2103.        say txt
  2104.  
  2105. Description 
  2106.  
  2107. This function causes the down button to be clicked. 
  2108. Return Codes 
  2109.  
  2110.  o 5 - Function did not be work. Spinbutton is probably disabled. 
  2111.  
  2112.  
  2113. ΓòÉΓòÉΓòÉ 6.62. SPINBUTTON_SPINUP ΓòÉΓòÉΓòÉ
  2114.  
  2115. Spin the spinbutton up one unit. 
  2116. Syntax 
  2117.  
  2118.     rc =  SPINBUTTON_SPINUP(seq_number)
  2119.          where seq_number is the sequence number identifying the SPINBUTTON.
  2120.  
  2121.  
  2122. Examples 
  2123.  
  2124.        /* Spin up the first spinbutton, and look at the text     */
  2125.        rc =  SPINBUTTON_SPINUP("1")
  2126.        rc =  SPINBUTTON_QUERY_TEXT("1", "txt")
  2127.        say txt
  2128.  
  2129. Description 
  2130.  
  2131. This function causes the up button to be clicked. 
  2132. Return Codes 
  2133.  
  2134.  o 5 - Function did not be work. Spinbutton is probably disabled. 
  2135.  
  2136.  
  2137. ΓòÉΓòÉΓòÉ 6.63. SYSMENU_QUERY_ALL ΓòÉΓòÉΓòÉ
  2138.  
  2139. Returns the text of each sysmenu item at the specified level. 
  2140. Syntax 
  2141.  
  2142.     rc =  SYSMENU_QUERY_ALL([level1,] [level2,] [level3,] stem_variable_name)
  2143.          where levels specify the point in the menu hierarchy to list items
  2144.          from.
  2145.  
  2146.  
  2147. Description 
  2148.  
  2149. This function is similar to MENU_QUERY_ALL, except that it operates on a 
  2150. sysmenu. 
  2151.  
  2152.  
  2153. ΓòÉΓòÉΓòÉ 6.64. SYSMENU_QUERY_STATE ΓòÉΓòÉΓòÉ
  2154.  
  2155. Returns information about the state of a sysmenu item at the specified level. 
  2156. Syntax 
  2157.  
  2158.     rc =  SYSMENU_QUERY_ALL([level1,] [level2,] [level3,] stem_variable_name)
  2159.          where levels specify the point in the sysmenu hierarchy.
  2160.  
  2161.  
  2162. Description 
  2163.  
  2164. This function is similar to MENU_QUERY_STATE, except that it operates on a 
  2165. sysmenu. 
  2166.  
  2167.  
  2168. ΓòÉΓòÉΓòÉ 6.65. SYSMENU_SELECT ΓòÉΓòÉΓòÉ
  2169.  
  2170. Selects the specified menu item from the sysmenu window. 
  2171. Syntax 
  2172.  
  2173.     rc =  SYSMENU_SELECT( level1   [,level2] [,level3] )
  2174.          where levels identify the menu item to be selected.
  2175.  
  2176.  
  2177. Description 
  2178.  
  2179. This function is similar to MENU_SELECT, except that it operates on the 
  2180. sysmenu. 
  2181. Return Codes 
  2182.  
  2183.  o 5 - Sysmenu item disabled or invalid. 
  2184.  
  2185.  
  2186. ΓòÉΓòÉΓòÉ 6.66. TEXT_HOW_MANY ΓòÉΓòÉΓòÉ
  2187.  
  2188. Return the number of static text fields. 
  2189. Syntax 
  2190.  
  2191.     rc = TEXT_HOW_MANY( variable_name)
  2192.  
  2193.  
  2194. Examples 
  2195.  
  2196.        /* How many static text fields?                          */
  2197.        rc = TEXT_HOW_MANY( "count")
  2198.        say "number of static text fields: " count
  2199.  
  2200. Description 
  2201.  
  2202. This function returns a variable which contains the number of static text 
  2203. controls in the selected window. 
  2204.  
  2205.  
  2206. ΓòÉΓòÉΓòÉ 6.67. TEXT_QUERY_TEXT ΓòÉΓòÉΓòÉ
  2207.  
  2208. Query the text of a static text field. 
  2209. Syntax 
  2210.  
  2211.     rc = TEXT_QUERY_TEXT(seq_number, variable_name)
  2212.          where seq_number is the sequence number identifying the static field.
  2213.  
  2214.  
  2215. Examples 
  2216.  
  2217.        /* Get the text of the first static text field      */
  2218.        rc = TEXT_QUERY_TEXT("1", "txt")
  2219.        say txt
  2220.  
  2221. Description 
  2222.  
  2223. This function returns a variable which contains the text of the specified 
  2224. static text field. 
  2225.  
  2226.  
  2227. ΓòÉΓòÉΓòÉ 7. The APMT Mouse Functions ΓòÉΓòÉΓòÉ
  2228.  
  2229. This section describes those functions that are related mouse event simulation. 
  2230.  
  2231. Mouse event simulation is done by first using a function to place the pointer 
  2232. at the desired location, and then calling a function to play a mouse button 
  2233. event. For example, to simulate a drag and drop, at least four calls will be 
  2234. needed - set_pointer, button_down, set_pointer, and button up. 
  2235.  
  2236.  
  2237. ΓòÉΓòÉΓòÉ 7.1. MOUSE ΓòÉΓòÉΓòÉ
  2238.  
  2239. Simulate a mouse action at the current pointer position. 
  2240. Syntax 
  2241.  
  2242.     rc = MOUSE(action, button_identifier)
  2243.          where action defines the mouse action to be simulated, and
  2244.          button_identifier defines which button(s) to use.
  2245.  
  2246.  
  2247. Examples 
  2248.  
  2249.        rc = MOUSE("CLICK","1")        /* click        button 1 */
  2250.        rc = MOUSE("DCLICK","2")       /* double click button 2 */
  2251.        rc = MOUSE("CLICK","12")       /* click button 1,2 together*/
  2252.        rc = MOUSE("CLICK","21")       /* click button 1,2 together*/
  2253.  
  2254. Description 
  2255.  
  2256. This function will simulate the mouse event, without changing the pointer 
  2257. position. 
  2258.  
  2259. The following actions are supported. These are to be specified exactly. 
  2260.  
  2261.  o CLICK 
  2262.  
  2263.  o DCLICK 
  2264.  
  2265.  o DOWN 
  2266.  
  2267.  o UP 
  2268.  
  2269.  Notes 
  2270.  
  2271.  It is expected that the pointer is placed correctly, before invoking this 
  2272.  function. Some functions to set the pointer are described in this section. 
  2273.  
  2274.  Return Codes 
  2275.  
  2276.  o 5 - Invalid parameter 
  2277.  
  2278.  
  2279. ΓòÉΓòÉΓòÉ 7.2. FRAME_SET_POINTER ΓòÉΓòÉΓòÉ
  2280.  
  2281. Position the pointer at a specified position relative to the frame. 
  2282. Syntax 
  2283.  
  2284.     rc = FRAME_SET_POINTER(location [,x][,X][,y][,Y])
  2285.          where location the area of the frame, and the remaining
  2286.          parameters define the position within the frame, in the
  2287.          case when location is inside.
  2288.  
  2289.  
  2290. Examples 
  2291.  
  2292.        rc = FRAME_SET_POINTER("TR")   /* place on upper right corner */
  2293.        rc = FRAME_SET_POINTER("T")    /* place on upper side         */
  2294.        rc = FRAME_SET_POINTER("BL")   /* place on lower left corner  */
  2295.        rc = FRAME_SET_POINTER("M")    /* at midpoint inside the frame */
  2296.        rc = FRAME_SET_POINTER("M",4,10,6,10) /* at pos 4,6 on a 10x10 grid */
  2297.        rc = FRAME_SET_POINTER("M",4,10)      /* at pos 4,1 on a 10x1 grid  */
  2298.  
  2299. Description 
  2300.  
  2301. This function will place the pointer at the specified location. If the first 
  2302. parameter is "M" then additional parameters may be specified as described 
  2303. below, otherwise the additional parameters will be ignored. 
  2304.  
  2305. The following values of the first parameter are supported: 
  2306.  
  2307.  "R"  - RIGHT  side of the frame 
  2308.  
  2309.  "W"  - LEFT  side of the frame 
  2310.  
  2311.  "T"  - TOP   side of the frame 
  2312.  
  2313.  "B"  - BOTTOM side of the frame 
  2314.  
  2315.  "TR" - TOP RIGHT corner of the frame 
  2316.  
  2317.  "TL" - TOP LEFT corner of the frame 
  2318.  
  2319.  "BL" - BOTTOM LEFT corner of the frame 
  2320.  
  2321.  "BR" - BOTTOM RIGHT corner of the frame 
  2322.  
  2323.  "M"  - Inside the frame 
  2324.  
  2325.  The 2nd through 5th parameters, if specified, are used as follows. The frame 
  2326.  window is divided into an imaginary grid of dimension (X,Y). The pointer is 
  2327.  then placed in the middle of the (x,y) cell of this grid. 
  2328.  Notes 
  2329.  
  2330.  If the first parameter is not recognized, "M" is assumed. 
  2331.  
  2332.  
  2333. ΓòÉΓòÉΓòÉ 7.3. CLASS_SET_POINTER ΓòÉΓòÉΓòÉ
  2334.  
  2335. Position the pointer at a specified position in a user defined control. 
  2336. Syntax 
  2337.  
  2338.     rc = CLASS_SET_POINTER(classname [,seq_number][,x][,X][,y][,Y])
  2339.          where classname is the name of a user defined control, and the remaining
  2340.          defines the position within the window.
  2341.  
  2342.  
  2343. Examples 
  2344.  
  2345.        rc = CLASS_SET_POINTER("MyButton") /* place at center of user defined */
  2346.                                           /* button (of class MyButton)      */
  2347.  
  2348. Description 
  2349.  
  2350. This function will place the pointer at the specified location, inside the 
  2351. control window belonging to the class specified in the first parameter. The 
  2352. matching is exact. 
  2353.  
  2354. The 3rd through 6th parameters, if specified, are used as follows. The 
  2355. specified control window is divided into an imaginary grid of dimension (X,Y). 
  2356. The pointer is then placed in the middle of the (x,y) cell of this grid. 
  2357. Notes 
  2358.  
  2359.  To be able to use this function, you have to know the name of the user defined 
  2360.  (non-standard) control. You can use the PMTREE tool to determine this. 
  2361.  
  2362.  You can use this function on standard controls also. For example, use '#3' for 
  2363.  PM standard buttons. See PM toolkit documentation for the classnames of the 
  2364.  standard controls. 
  2365.  
  2366.  
  2367. ΓòÉΓòÉΓòÉ 7.4. CONTAINER_SET_POINTER ΓòÉΓòÉΓòÉ
  2368.  
  2369. Place the pointer on the specified container object. 
  2370. Syntax 
  2371.  
  2372.     rc = CONTAINER_SET_POINTER(seq_number, object_identifier)
  2373.          where seq_number is the sequence number identifying the container,
  2374.          and object_identifier is
  2375.              either the text string identifying the object
  2376.              or #n with n = the object number
  2377.  
  2378.  
  2379. Examples 
  2380.  
  2381.        rc = CONTAINER_SET_POINTER(1, "Main")
  2382.        rc = CONTAINER_SET_POINTER(1, "#5")
  2383.  
  2384.  
  2385. Description 
  2386.  
  2387. This function will first try to place the pointer on the icon rectangle of the 
  2388. selected container object. If unsuccessful, attempt will be made to place the 
  2389. pointer on the text rectangle. 
  2390.  
  2391.  
  2392.  
  2393. Notes 
  2394.  
  2395.  If the object is not visible, attempt will be made to bring the object into 
  2396.  the visible area by scrolling the container. 
  2397.  
  2398.  Return Codes 
  2399.  
  2400.  o 5 - No matching object found. 
  2401.  
  2402.  o 6 - Could not get rectangle of icon or text. 
  2403.  
  2404.  
  2405. ΓòÉΓòÉΓòÉ 8. Acknowledgements ΓòÉΓòÉΓòÉ
  2406.  
  2407. The author thanks Marc Fiammant for providing significant code, and insights 
  2408. for keyboard character simulation.