WATools Function Reference WATools v1.0 - OS/2 Workstation Automation Tools Written By Russell Gosse, Team OS/2 Email: rgosse@interlog.com These functions are specified as the first parm when calling WAT.CMD. The synatx is: rc = WAT('function','parm','parm'...) or, call WAT 'function','parm','parm'... 'function' = any one of the functions listed below, 'parm',... = are the parms requried by the functions if a parm value is enclosed in square brackets [ ], it is optional. All functions return a value. If that value is not specified below, then refer to WATCODE.TXT for an explaination of all possible return codes (I was just too lazy to add them here!) Sample: /* REXX - WATools Sample */ rc = WAT('init') --> initialize API environment if rc = 0 then do rc = WAT('conn','A') --> connect to CM/2 session A if rc = 0 then do text = WAT('read','5 10',15) --> read 15 bytes of text from col 5 row 10 call WAT 'pfkey','8' --> send PFkey 8 call WAT 'wait' --> wait for host to respond pos = WAT('find','Total = ') --> look for text 'Total = ' text = WAT('read',pos,25) --> read 25 bytes from find postion call WAT 'disc' --> disconnect from CM/2 session end else do say 'Unable to connect to session.' exit end end else say 'Unable to initialize API!' call WAT 'reset' --> reset API environment exit Please Email any ideas for enhancements and I will get them done for you. I already have some new ideas in mind so watch for version 1.1 .... ** FUNCTIONS ** _______________________________________________________________________________ CONN In order to interface with a CM/2 host window, your application must connect to it first. You can only have one active connection at a time. Use the DISC function before connecting to another session. rc = WAT('CONN',sessid) Prerequisite Call: INIT Parms: sessid Single-letter CM/2 session id. that identifies the host session window to connect to. Note: If connected, the CM/2 session window title and the OS/2 task list will be changed to indicate that the session is conected to a WATools application. The DISC function will clear this. I intend to enhance this by allowing you to specify a title. _______________________________________________________________________________ CURSORPOS Sets or retrieves the current cursor postion on the connected session. EHLLAPI functions use offset screen postion values which starts as '1' in the upper left-hand corner of the screen and continues to the bottom right-hand corner. For example, on a 24 x 80 screen, the last screen position would be 1920, row 2, column 1 would be position 81 and so on. At times, I find it easier to use a 'col row' format so I wrote WAT functions to use both formats. This function returns an offset value. rc = WAT('CURSORPOS'[,pos]) Prerequisite Call: CONN Parms: pos If specified, its the offset or 'col row' screen postion to move the cursor to. If you just want to tab across screen fields, see the SEND function. Returns: The offset value of the current cursor postion if the pos parameter is not specified. _______________________________________________________________________________ DISC Disconnects your application from a CM/2 host session window. rc = WAT('DISC') Prerequisite Call: CONN _______________________________________________________________________________ FIND Locates a string of text on the connected session window and returns the offset screen position, if found. This function will only locate case_sensitive ASCII text. It does not handle extended attributes, such as colour. If there is enough demand, I will add this enhancement. rc = WAT('FIND',text[,pos][,dir]) Prerequisite Call: CONN Parms: text Case-sensitive text string to search for, pos Screen position where to start the search from. This can be an offset value, 'col row' value or null. If you do not specifiy this value, the current cursor postion is used. If both pos and dir are null, the entire screen will be searched starting from position '1'. dir By default, the search is done in a forward fashion from the specified position. You can specify 'B' for a backwards search that starts from the last screen position (bottom right-hand corner). Returns: Offset screen postion where the text was found or '0'b(not found). _______________________________________________________________________________ INFO Returns information about the specified session id. rc = WAT('INFO'[,sessid]) Prerequisite Call: INIT Parms: sessid Single-letter CM/2 session id. that identifies the host session window. If not specified, the currently connected session is used. Returns: 'type cols rows' This is a text string containing some basic attributes about the session. It will tell what type of host session it is and the number of rows and columns on the screen: type - can be one of the following: H3 - host 3270 P3 - host 3270 printer H5 - host 5250 P5 - host 5250 printer rows - number of rows on screen cols - number of columns on screen _______________________________________________________________________________ INIT Initializes and loads CM/2 EHLLAPI functions. This should be the first function you call in your application and only needs to be called once. rc = WAT('INIT') _______________________________________________________________________________ LIST Lists all, or specific, active CM/2 sessions. rc = WAT('LIST'[,type]) Prerequisite Call: INIT Parms: type If not specified, all sessions are listed. To list only host sessions, specify 'H'. To only list printer sessions, specify 'P'. Returns: 'x sess1 sess2 ... sessx' This string lists all specified session ids. (single-letter). The first word in the string is a number that indicates the total number of sessions, of this type, found. _______________________________________________________________________________ PFKEY Sends a PFKey keystroke to the connected session. rc = WAT('PFKEY',keynum) Prerequisite Call: CONN Parms: keynum PFkey number (1 - 24) _______________________________________________________________________________ READ Reads a string of text from the connected session. rc = WAT('READ'[,pos,len]) Prerequisite Call: CONN Parms: pos Screen postion to read from. Either an offset value, a 'column row' coordinate or null, len Number of characters (length) to read or null. Returns: 'text' String of characters (ASCII). If no parms are supplied, the entire screen is returned. If only pos is specified, all text from pos to the last screen position is returned. If only len is specified, then the current cursor position is assumed. _______________________________________________________________________________ READROW Reads an entire row from the connected session. rc = WAT('READROW',row) Prerequisite Call: CONN Parms: row Screen row number Returns: 'text' All characters (ASCII) in the specified row. _______________________________________________________________________________ READWORD Reads a word from the specified row. A word is a string of text that is separated from other text by at least one blank. This function could be useful for reading columns of text on a screen. rc = WAT('READWORD',row,word_num) Prerequisite Call: CONN Parms: row Screen row number, word_num Number representing the nth word in the row. Returns: 'word' The word text from the specified row. _______________________________________________________________________________ RESET Resets the EHLLAPI environment (should be last function called) rc = WAT('RESET') _______________________________________________________________________________ SEND Sends a string of text to the connected session. rc = WAT('SEND',string) Prerequisite Call: CONN Parms: string Any mixed-case text, or one of the following: ENTER - sends enter key, HOME - homes the cursor, EOF - erase EOF, PA1 - PA1 key, PA2 - PA2 key, TABF - tab forward, TABB - tab backwards, CLEAR - clear key, END - move to end of field, PRINTPS - screen print. _______________________________________________________________________________ WAIT Waits for system to unlock the session to allow input. This is used to wait for the 'X SYSTEM' to clear after sending a transaction to the Host. Waiting for the Host can be tricky to monitor. Sometimes, it's possible to enter keystrokes but then a response comes from the host unexpectedly. TSO is a good example of this. Whenever you receive a message, the screen clears and the message shows up that ends with a '***'. rc = WAT('WAIT'[,timeout]) Prerequisite Call: CONN Parms: timeout Number of seconds to wait for screen to unlock. The default is 30 seconds. Returns: '0' Session unlocked. Note: Typically, you will want to call this function after any transactions are sent to the Host. _______________________________________________________________________________ WAITFOR Waits for a text string to appear on the screen. rc = WAT('WAITFOR',text[,timeout]) Prerequisite Call: CONN Parms: text Text string to wait for (case-sensitive), timeout Number of seconds to wait for the text to appear. The default is 30 seconds. Returns: '0' Text was found. _______________________________________________________________________________ CONVERTPOS Converts a screen postion value from one format to another. As mentioned before, these routines can use the offset value or the 'col row' value. This function converts from one format to the other. rc = WAT('CONVERTPOS',pos) Prerequisite Call: CONN Parms: pos Offset or 'col row' screen postion 'col row' = string containing screen column and row values which are separated with at least one blank space. Returns: 'pos' The converted postion value. Note: EHLLAPI functions use the absolute, or offset, screen postion. I find it easier, at times, to use the 'col row' format which is why I wrote these WAT functions to accept both types. _______________________________________________________________________________