home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / watool10.zip / WAT.DOC < prev   
Text File  |  1995-10-02  |  16KB  |  416 lines
  1. Workstation Automation Tools For OS/2 - WATools v1.0
  2.    A REXX Exec written by Russell Gosse, Team OS/2
  3.    Email: rgosse@interlog.com
  4.  
  5. WATools is a set of functions that can be used in any REXX based automation 
  6. application that requires access to Communications Manager/2 Host session 
  7. windows.  These functions are built on the EHLLAPI REXX functions that come 
  8. with CM/2.  WATools provides an easier method of interfacing with CM/2
  9. host session windows and relieves the Developer of having to learn the EHLLAPI
  10. function calls and their syntax.
  11.  
  12. This version of WATools comes with a set of functions that will handle all of 
  13. the basic read, write and search capabilities required when automating the task
  14. of reading information from host (3270 or 5250) session windows, or sending 
  15. data (keystrokes) to them.
  16.  
  17. As an example of using WATools, I recently wrote an exec that invokes a TSO
  18. clist, responds to all of its prompts, switches to InfoMan, opens a record, 
  19. enters the required fields and then logs off TSO.
  20.  
  21. I hope you find WATools useful.  Please feel free to Email me with your 
  22. comments or suggestions for new enhancements.
  23.  
  24. I'm not responsibe for any damage this REXX exec may cause.  Don't worry, I 
  25. don't delete anything!  You still have to code your own automation application 
  26. but WATools will make it easier for you.
  27.  
  28. Enjoy.
  29.  
  30. Russell Gosse,
  31. Telecommunications Analyst and Member of Team OS/2
  32.  
  33. Where I work, I am responsible for supporting a world-wide VTAM/SNA network and
  34. write automation applications for OS/2 and IBM's Netview.
  35.  
  36. Email:  rgosse@interlog.com
  37.  
  38.  
  39. P.S.  Please excuse my crude documentation and the spelling mistakes that you 
  40.       may find.
  41.  
  42. ______________________________________________________________________________
  43.                        
  44.                          WATools Function Reference
  45. ______________________________________________________________________________
  46.  
  47. These functions are specified as the first parm when calling WAT.CMD.  The 
  48. synatx is:
  49.  
  50.    rc = WAT('function','parm','parm'...) or,
  51.    call WAT 'function','parm','parm'...
  52.  
  53.       'function' = any one of the functions listed below,
  54.       'parm',... = are the parms requried by the functions
  55.  
  56.       if a parm value is enclosed in square brackets [  ], it is optional.
  57.  
  58. All functions return a value.  If that value is not specified below, then refer
  59. to WATCODE.TXT for an explaination of all possible return codes (I was just too
  60. lazy to add them here!)
  61.  
  62.  
  63. A Note About Screen Postions
  64.  
  65.    A host screen is typically 24 lines by 80 columns.  When reading or writing 
  66.    to a host window, you have to specify the screen position.  Two values can 
  67.    be used with WATool functions for specfiying screen postions:  There's the 
  68.    offset value, which starts at '1' from the upper left-hand corner of the
  69.    screen and contiunes down to the bottom right-hand corner at '1920' (24 x 
  70.    80) or you can use the 'column row' format which is a text string containing
  71.    two values separated by at least one blank which represent the screen column
  72.    and row postion, such as '45 8'.  A CONVERTPOS function is provided to
  73.    convert from one format to the other.  You decide which to use!
  74.  
  75.  
  76. Return Codes
  77.  
  78.    Unless specified in the function reference below, every function returns a 
  79.    numeric code.  I chose not list each of the possible codes in every function
  80.    (lazy again) so I've listed them here for you to reference.
  81.  
  82.    '0'   =  Successful
  83.    '-1'  =  No Function Specified
  84.    '-2'  =  Invalid or Missing Parameter
  85.    '-3'  =  Postion Value Is Not Within Screen Size
  86.    '-4'  =  No CM/2 Sessions Active
  87.    '-5'  =  Not Currently Connected To A Session
  88.    '-6'  =  Unknown Function Specified
  89.    '-7'  =  Session Is Already In Use By Another Function
  90.    '-8'  =  Unsupported Function (CM/2)
  91.    '-9'  =  System Error Occurred
  92.    '-10' =  Session Not Found
  93.    '-11' =  Session Is Busy
  94.    '-12' =  Error Occurred While Trying To Send Keystroke
  95.    '-13' =  Bad Mnemonic
  96.    '-14' =  Timeout Occurred
  97.    '-99' =  EHLLAPI Has Not Been Loaded
  98.  
  99.  
  100. Sample Program Using WATool:
  101.  
  102. /* REXX - WATools Sample */
  103.  
  104. rc = WAT('init')                   --> initialize API environment
  105. if rc = 0 then do
  106.    rc = WAT('conn','A')            --> connect to CM/2 session A
  107.    if rc = 0 then do
  108.       text = WAT('read','5 10',15) --> read 15 bytes of text from col 5 row 10
  109.       call WAT 'pfkey','8'         --> send PFkey 8
  110.       call WAT 'wait'              --> wait for host to respond
  111.       pos = WAT('find','Total = ') --> look for text 'Total = '
  112.       text = WAT('read',pos,25)    --> read 25 bytes from find postion
  113.       call WAT 'disc'              --> disconnect from CM/2 session
  114.    end
  115.    else do
  116.       say 'Unable to connect to session.'
  117.       exit
  118.    end
  119. end
  120. else
  121.    say 'Unable to initialize API!'
  122. call WAT 'reset'                   --> reset API environment
  123. exit
  124.  
  125.  
  126. Please Email any ideas for enhancements and I will get them done for you.  I 
  127. already have some new ideas in mind so watch for version 1.1 ....
  128.  
  129.  
  130.  
  131.                               ** FUNCTIONS **
  132.  
  133. _______________________________________________________________________________
  134. CONN           
  135.  
  136.    In order to interface with a CM/2 host window, your application must connect
  137.    to it first.  You can only have one active connection at a time.  Use the 
  138.    DISC function before connecting to another session.
  139.  
  140.    rc = WAT('CONN',sessid)
  141.  
  142.    Prerequisite Call:   INIT
  143.  
  144.    Parms:   sessid      Single-letter CM/2 session id. that identifies the
  145.                         host session window to connect to.
  146.  
  147.    Note:    If connected, the CM/2 session window title and the OS/2 task list 
  148.             will be changed to indicate that the session is conected to a
  149.             WATools application.  The DISC function will clear this.  I intend 
  150.             to enhance this by allowing you to specify a title.
  151.  
  152. _______________________________________________________________________________
  153. CONVERTPOS     
  154.  
  155.    Converts a screen postion value from one format to another.  These routines
  156.    can use the offset value or the 'col row' value.  This function converts
  157.    from one format to the other.
  158.  
  159.    rc = WAT('CONVERTPOS',pos)
  160.  
  161.    Prerequisite Call:   CONN
  162.  
  163.    Parms:   pos         Offset or 'col row' screen postion
  164.                            'col row' =  string containing screen column and row
  165.                            values which are separated with at least one 
  166.                            blank space.
  167.                
  168.    Returns: 'pos'  The converted postion value.
  169.  
  170.    Note:    EHLLAPI functions use the absolute, or offset, screen postion.  I
  171.             find it easier, at times, to use the 'col row' format which is why 
  172.             I wrote these WAT functions to accept both types.
  173.  
  174. _______________________________________________________________________________
  175. CURSORPOS
  176.  
  177.    Sets or retrieves the current cursor postion on the connected session. 
  178.    EHLLAPI functions use offset screen postion values which starts as '1'
  179.    in the upper left-hand corner of the screen and continues to the
  180.    bottom right-hand corner.  For example, on a 24 x 80 screen, the last screen
  181.    position would be 1920, row 2, column 1 would be position 81 and so on.  At
  182.    times, I find it easier to use a 'col row' format so I wrote WAT functions 
  183.    to use both formats.  This function returns an offset value.
  184.  
  185.    rc = WAT('CURSORPOS'[,pos])
  186.  
  187.    Prerequisite Call:   CONN
  188.  
  189.    Parms:   pos         If specified, its the offset or 'col row' screen 
  190.                         postion to move the cursor to.  If you just want to tab
  191.                         across screen fields, see the SEND function.
  192.  
  193.    Returns: The offset value of the current cursor postion if the 
  194.             pos parameter is not specified.
  195.  
  196. _______________________________________________________________________________
  197. DISC           
  198.  
  199.    Disconnects your application from a CM/2 host session window.
  200.  
  201.    rc = WAT('DISC')
  202.  
  203.    Prerequisite Call:    CONN
  204.              
  205. _______________________________________________________________________________
  206. FIND
  207.  
  208.    Locates a string of text on the connected session window and returns 
  209.    the offset screen position, if found.  This function will only locate 
  210.    case_sensitive ASCII text.  It does not handle extended attributes,
  211.    such as colour.  If there is enough demand, I will add this enhancement.
  212.  
  213.    rc = WAT('FIND',text[,pos][,dir])
  214.  
  215.    Prerequisite Call:    CONN
  216.  
  217.    Parms:   text        Case-sensitive text string to search for,
  218.  
  219.             pos         Screen position where to start the search from.  This 
  220.                         can be an offset value, 'col row' value or null.  If 
  221.                         you do not specifiy this value, the current cursor
  222.                         postion is used.  If both pos and dir are null, the
  223.                         entire screen will be searched starting from position
  224.                         '1'.
  225.  
  226.             dir         By default, the search is done in a forward fashion 
  227.                         from the specified position.  You can specify 'B' for a
  228.                         backwards search that starts from the last screen
  229.                         position (bottom right-hand corner).
  230.  
  231.    Returns: Offset screen postion where the text was found or '0'b(not found).
  232.  
  233. _______________________________________________________________________________
  234. INFO
  235.  
  236.    Returns information about the specified session id.
  237.  
  238.    rc = WAT('INFO'[,sessid])
  239.  
  240.    Prerequisite Call:   INIT
  241.  
  242.    Parms:   sessid      Single-letter CM/2 session id. that identifies the
  243.                         host session window.  If not specified, the 
  244.                         currently connected session is used.
  245.  
  246.    Returns: 'type cols rows'  This is a text string containing some basic
  247.                               attributes about the session.  It will tell
  248.                               what type of host session it is and the number
  249.                               of rows and columns on the screen:
  250.  
  251.                   type  -  can be one of the following:
  252.                               H3    -  host 3270
  253.                               P3    -  host 3270 printer
  254.                               H5    -  host 5250
  255.                               P5    -  host 5250 printer
  256.                   rows  -  number of rows on screen
  257.                   cols  -  number of columns on screen
  258.  
  259. _______________________________________________________________________________
  260. INIT
  261.  
  262.    Initializes and loads CM/2 EHLLAPI functions.  This should be the first 
  263.    function you call in your application and only needs to be called once.
  264.  
  265.    rc = WAT('INIT')
  266.  
  267. _______________________________________________________________________________
  268. LIST           
  269.  
  270.    Lists all, or specific, active CM/2 sessions.
  271.  
  272.    rc = WAT('LIST'[,type])
  273.  
  274.    Prerequisite Call:   INIT
  275.  
  276.    Parms:   type        If not specified, all sessions are listed.  To list 
  277.                         only host sessions, specify  'H'.  To only list printer
  278.                         sessions, specify 'P'.
  279.  
  280.    Returns: 'x sess1 sess2 ... sessx'  This string lists all specified 
  281.                                        session ids. (single-letter).  The
  282.                                        first word in the string is a number
  283.                                        that indicates the total number of
  284.                                        sessions, of this type, found.
  285.  
  286. _______________________________________________________________________________               
  287. PFKEY
  288.  
  289.    Sends a PFKey keystroke to the connected session.
  290.  
  291.    rc = WAT('PFKEY',keynum)
  292.  
  293.    Prerequisite Call:   CONN
  294.  
  295.    Parms:   keynum      PFkey number (1 - 24)
  296.  
  297. _______________________________________________________________________________
  298. READ
  299.  
  300.    Reads a string of text from the connected session.
  301.  
  302.    rc = WAT('READ'[,pos,len])
  303.  
  304.    Prerequisite Call:   CONN
  305.  
  306.    Parms:   pos         Screen postion to read from.  Either an offset
  307.                         value, a 'column row' coordinate or null,
  308.  
  309.             len         Number of characters (length) to read or null.
  310.  
  311.    Returns: 'text'  String of characters (ASCII).  If no parms are
  312.                     supplied, the entire screen is returned.  If only pos 
  313.                     is specified, all text from pos to the last screen 
  314.                     position is returned.  If only len is specified, then 
  315.                     the current cursor position is assumed.
  316.  
  317. _______________________________________________________________________________
  318. READROW
  319.  
  320.    Reads an entire row from the connected session.
  321.  
  322.    rc = WAT('READROW',row)
  323.  
  324.    Prerequisite Call:   CONN
  325.  
  326.    Parms:   row         Screen row number
  327.  
  328.    Returns: 'text'  All characters (ASCII) in the specified row.
  329.  
  330. _______________________________________________________________________________
  331. READWORD
  332.  
  333.    Reads a word from the specified row.  A word is a string of text that is 
  334.    separated from other text by at least one blank.  This function could be 
  335.    useful for reading columns of text on a screen.
  336.  
  337.    rc = WAT('READWORD',row,word_num)
  338.  
  339.    Prerequisite Call:   CONN
  340.  
  341.    Parms:   row         Screen row number,
  342.  
  343.             word_num    Number representing the nth word in the row.
  344.  
  345.    Returns: 'word'  The word text from the specified row.
  346.  
  347. _______________________________________________________________________________
  348. RESET          
  349.  
  350.    Resets the EHLLAPI environment (should be last function called)
  351.  
  352.    rc = WAT('RESET')
  353.  
  354. _______________________________________________________________________________
  355. SEND
  356.  
  357.    Sends a string of text to the connected session.
  358.  
  359.    rc = WAT('SEND',string)
  360.  
  361.    Prerequisite Call:   CONN
  362.  
  363.    Parms:   string      Any mixed-case text, or one of the following:
  364.                            ENTER -  sends enter key,
  365.                            HOME  -  homes the cursor,
  366.                            EOF   -  erase EOF,
  367.                            PA1   -  PA1 key,
  368.                            PA2   -  PA2 key,
  369.                            TABF  -  tab forward,
  370.                            TABB  -  tab backwards,
  371.                            CLEAR -  clear key,
  372.                            END   -  move to end of field,
  373.                            PRINTPS  -  screen print.
  374.  
  375. _______________________________________________________________________________
  376. WAIT
  377.  
  378.    Waits for system to unlock the session to allow input.  This is used to wait
  379.    for the 'X SYSTEM' to clear after sending a transaction to the Host. 
  380.    Waiting for the Host can be tricky to monitor.  Sometimes, it's possible to
  381.    enter keystrokes but then a response comes from the host unexpectedly.  TSO
  382.    is a good example of this.  Whenever you receive a message, the screen 
  383.    clears and the message shows up that ends with a '***'.
  384.  
  385.    rc = WAT('WAIT'[,timeout])
  386.  
  387.    Prerequisite Call:   CONN
  388.  
  389.    Parms:   timeout     Number of seconds to wait for screen to unlock.  The
  390.                         default is 30 seconds.
  391.  
  392.    Returns: '0'  Session unlocked.
  393.  
  394.    Note:    Typically, you will want to call this function after any 
  395.             transactions are sent to the Host.
  396.  
  397. _______________________________________________________________________________
  398. WAITFOR
  399.  
  400.    Waits for a text string to appear on the screen.
  401.  
  402.    rc = WAT('WAITFOR',text[,timeout])
  403.  
  404.    Prerequisite Call:   CONN
  405.  
  406.    Parms:   text        Text string to wait for (case-sensitive),
  407.  
  408.             timeout     Number of seconds to wait for the text to appear.
  409.                         The default is 30 seconds.
  410.  
  411.    Returns: '0'  Text was found.
  412.  
  413. _______________________________________________________________________________
  414.  
  415.  
  416.