OS/2 Shareware BBS: 3 Comm

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 3 Comm / 03-Comm.zip / tt2man.zip / ttauto.doc < prev next >

Wrap

Text File | 1993-12-13 | 306KB | 8,117 lines

TABLE OF CONTENTS 12. AUTOPILOT Statement Reference 12.1 ACTION_ID Function 12.2 ACTION_INFO Function 12.3 ACTION_OBJECT Function 12.4 ACTION_TYPE Function 12.5 ACTION_WINDOW Function 12.6 ADD TO Statement 12.7 ASC Function 12.8 ATTRIBUTE Function 12.9 BEEP Statement 12.10 CARRIER Statement 12.11 CHECK Statement 12.12 CLOSE Statement 12.13 CLS HOST Statement 12.14 CONNECT and JUMP Statements 12.15 COPY_FROM_HOST Statement 12.16 COPY_TO_HOST Statement 12.17 CREATE DDE_LINK Statement (Client) 12.18 CREATE DDE_LINK Statement (Server) 12.19 CREATE DIALOG_WINDOW Statement 12.19.1 ACTION_BAR_MENU Clause 12.19.2 CHECK_BOX Clause 12.19.3 COMBINATION_BOX Clause 12.19.4 ENTRY_FIELD Clause 12.19.5 GROUP_BOX Clause 12.19.6 ICON_FIELD Clause 12.19.7 LIST_BOX Clause 12.19.8 MULTILINE_ENTRY_FIELD Clause 12.19.9 PUSH_BUTTON Clause 12.19.10 RADIO_BUTTON Clause 12.19.11 TEXT_FIELD Clause 12.20 CREATE SESSION_MONITOR Statement 12.20.1 TEXT_WATCH Clause 12.20.2 HOST_KEY_WATCH Clause 12.21 DDE_EXECUTE Statement (Client) 12.22 DDE_POKE Statement (Client) 12.23 DDE_REQUEST Statement (Client) 12.24 DDE_UPDATE Statement (Server) 12.25 DECLARE FUNCTION Statement 12.26 DESELECT Statement 12.27 DESTROY Statement 12.28 DIAL Statement 12.29 DIM Statement 12.30 DIR Statement 12.31 DISABLE Statement 12.32 DISABLE Statement (DDE Client) 12.33 DISABLE Statement (DDE Server) 12.34 DISCONNECT Statement 12.35 DISK_INFO Function 12.36 ENABLE Statement 12.37 ENABLE Statement (DDE Client) 12.38 ENABLE Statement (DDE Server) 12.39 EOF Function 12.40 EXIT Statement 12.41 FILE_ACCESS Function 12.42 FILE_TRANSFER_STATUS Function 12.43 FOUND Function 12.44 FOUND_COLUMN Function 12.45 FOUND_ROW Function 12.46 GLOBAL Statement 12.47 GOTO Statement 12.48 HANG_UP Statement 12.49 HIDE Statement 12.50 HOST_CURSOR_COLUMN Function 12.51 HOST_CURSOR_ROW Function 12.52 IF Statement 12.53 INCLUDE Statement 12.54 INSTR Function 12.55 IS_CHECKED Function 12.56 IS_DISABLED Function 12.57 JUMP Statement 12.58 LEN Function 12.59 LOCATE HOST_CURSOR Statement 12.60 LOOK Statement 12.61 MESSAGE_BOX Function 12.62 MINIMIZE, MAXIMIZE, and RESTORE Statements 12.63 NUMBER_OF_LINES Function 12.64 ON Statement 12.65 OPEN Statement 12.66 OPEN Statement (DDE Client) 12.67 OPEN Statement (DDE Server) 12.68 OPEN_FLAG Function 12.69 PERFORM Statement 12.70 QUIET Function 12.71 READ Statement 12.72 READ_POSITION Function 12.73 RECEIVE_FILE Statement 12.74 RELEASE Statement 12.75 REMOVE FROM Statement 12.76 RESERVE Statement 12.77 RESUME Statement 12.78 RETURN Statement 12.79 ROUND Statement 12.80 RUN Statement 12.81 SCREEN Function 12.82 SCRIPT_INFO Function 12.83 SEARCH_ARRAY Statement 12.84 SELECT Statement 12.85 SELECTED_LINE Function 12.86 SEND Statement 12.87 SEND_FILE Statement 12.88 SET Statement 12.89 SET_ARRAY Statement 12.90 SHOW Statement 12.91 SIGNAL Statement 12.92 SORT Statement 12.93 STORE Statement 12.94 STR_CHR Function 12.95 STR_CURRDIR Function 12.96 STR_CURRDISK Function 12.97 STR_DATE Function 12.98 STR_DELETE Function 12.99 STR_ENVIRONMENT Function 12.100 STR_FILEPATH Function 12.101 STR_JLEFT Function 12.102 STR_JRIGHT Function 12.103 STR_LEFT Function 12.104 STR_LOWER Function 12.105 STR_MID Function 12.106 STR_PAD Function 12.107 STR_REPLICATE Function 12.108 STR_RETRIEVE Function 12.109 STR_RIGHT Function 12.110 STR_TIME Function 12.111 STR_TRANSLATE Function 12.112 STR_TRUNCATE Function 12.113 STR_UPPER Function 12.114 STR_VAL Function 12.115 SWAP Statement 12.116 TEXT_OF Function 12.117 UNCHECK Statement 12.118 VAL Function 12.119 WAIT Statement 12.120 WHILE Statement 12.121 WINDOW_HANDLE Function 12.122 WRITE Statement 12.123 WRITE_POSITION Function 12. AUTOPILOT Statement Reference This section contains the syntax of all Statements and Functions available within the AUTOPILOT Language. 12.1 ACTION_ID Function Purpose: Returns the Reference Number of the dialog window, session monitor, or DDE item which triggered this ACTION. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ACTION_ID │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function is used in routines that are triggered by ACTION clauses. It returns the ID number of the window, monitor, or DDE item which triggered the current ACTION. The ID returned depends on the type of ACTION. For example, when a menu choice is made on a dialog, ACTION_ID returns the ID number that was specified in the AS clause of the ACTION_BAR_MENU CHOICE item. The following table indicates what ID is return for various types of ACTION (Action Types are listed by the number that is returned by the ACTION_TYPE function). Action Type ID Returned ─────────── ─────────────────────────────────────────────────────────────── 1 Selected Action Bar menu item. 2 Close requested from the System Menu. 5 Radio Button,, Check Box,, or Push Button control that was pressed. 6 Entry Field or Multiline Entry Field control that changed value. 7 A List Box or Combination Box control that changed value. 8 List Box or Combination Box control that was double clicked. 9 TEXT_WATCH whose text was found was found. 10 HOT_KEY_WATCH whose key was pressed . 11 TOPIC conversation was initiated with. 12 TOPIC conversation was terminated. 13 HOT_LINK data item was received for. 14 WARM_LINK notification was received for. 15 EXPORT_ITEM that client started a HOT_LINK/WARM_LINK for. 16 EXPORT_ITEM that client ended a HOT_LINK /WARM_LINK with. 17 EXPORT_ITEM that Poke data was received for. 18 EXPORT_ITEM that a Request was received for. 19 EXPORT_COMMAND that an Execute was received for. Example: SET x = ACTION_ID See Also: ACTION_TYPE ACTION_WINDOW ACTION_OBJECT 12.2 ACTION_INFO Function Purpose: Returns various types of information relating to the event that triggered the current ACTION. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ACTION_INFO(info) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function is used in routines that are triggered by ACTION events. It returns various types of information related to the current ACTION. The argument info is a number that determines what type of information is returned. (Note that some types of information (info = 1,2 or 3) can be returned with other functions.) info=1 info=2 info=3 info=4 info=5 (action_type) (action_object) (action_id) ─────────────── ─────────────── ─────────────── ─────────────── ─────────────── 1 Dialog Window Action Bar Action Bar menu ID Pulldown or item selected Choice ID 2 Close requested Dialog Window from System ID Menu 5 Radio Button, Dialog Window Radio Button, Check Box, or ID Check Box, or Push Button Push Button ID pressed 6 Dialog Window Entry Field or Entry Field or ID Multiline Entry Multiline Entry Field ID Field changed 7 Dialog Window List Box or List Box or ID Combination Box Combination Box ID changed 8 Dialog Window List Box or List Box or ID Combination Box Combination Box ID double clicked 9 Session Monitor Text Watch ID Text in Text ID Watch found 10 session_monitor Host Key Watch ID Key in Host Key Watch pressed 11 dde_link Topic ID DDE conversation initiated 12 dde_link Topic ID DDE conversation terminated 13 dde_link Hot Link ID Hot Link data item received 14 dde_link Warm Link ID Warm Link data item changed 15 dde_link Export Item ID Item Name Client started a Hot Link or Warm Link 16 dde_link Export Item ID Item Name Client terminated a Hot Link or Warm Link 17 dde_link Export Item ID Item Name Poked data Poke data item received 18 dde_link Export Item ID Item Name Request item received 19 dde_link Export Command Command Data Execute command ID received 12.3 ACTION_OBJECT Function Purpose: Returns the id number of the window, session monitor, of DDE link that triggered an ACTION. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ACTION_OBJECT │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function is used in routines that are triggered by ACTION clauses. It returns the number of the DIALOG_WINDOW, TEXT_WINDOW, SESSION_MONITOR, or DDE_LINK that triggered the current ACTION. In conjunction with ACTION_TYPE and ACTION_ID, this function allows a common routine to handle a variety of actions by allowing you to query the item that has been selected. Example: SET x = ACTION_OBJECT See Also: ACTION_TYPE ACTION_ID 12.4 ACTION_TYPE Function Purpose: Returns an indication of what caused the ACTION specified for a window, session monitor, or DDE item. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ACTION_TYPE │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function is used in routines that are triggered by ACTION clauses. It indicates the reason why a window, session monitor, or DDE item triggered the current ACTION. Returns Source Cause ─────── ───────────────── ──────────────────────────────────────────────── 1 Dialog Action Bar menu item selected. 2 Dialog Close requested from the System Menu. 5 Dialog A Radio Button,, Check Box,, or Push Button control was pressed. 6 Dialog An Entry Field or Multiline Entry Field control changed value. 7 Dialog A List Box or Combination Box control changed value. 8 Dialog A mouse double click has been sensed on a List Box or Combination Box control. 9 Session Monitor The text specified in a TEXT_WATCH clause was found. 10 Session Monitor The key specified in a HOT_KEY_WATCH clause was pressed. 11 DDE (Server only) A DDE conversation was initiated by a Client application. 12 DDE A DDE conversation was terminated by the other application. 13 DDE (Client only) A HOT_LINK data item was received. 14 DDE (Client only) A WARM_LINK notification was received. 15 DDE (Server only) A Client started a HOT_LINK or WARM_LINK. 16 DDE (Server only) A Client terminated a HOT_LINK or WARM_LINK. 17 DDE (Server only) A Poke data item was received. 18 DDE (Server only) A Request item was received. 19 DDE (Server only) An Execute command was received. Example: IF ACTION_TYPE = 1 GOTO do_actionbar IF ACTION_TYPE = 2 GOTO do_sysmenu See Also: ACTION_ID ACTION_OBJECT 12.5 ACTION_WINDOW Function Purpose: Returns the window number of the window that triggered an ACTION. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ACTION_WINDOW │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function is used with Action Bar Menus created with the ACTION_BAR_MENU clause in the CREATE TEXT_WINDOW Statement. It is used in routines that are triggered by ACTIONs indicated for PULLDOWN menus to return the <window-number> specified on the CREATE DIALOG_WINDOW Statement. In conjunction with ACTION_TYPE and ACTION_ID, this function allows a common routine to handle a variety of Action Bars and Action Bar Items by allowing you to query the item that has been selected. Example: SET x = ACTION_WINDOW See Also: ACTION_TYPE ACTION_ID 12.6 ADD TO Statement Purpose: This statement is used to add various items to window objects, session monitors and DDE LINK objects. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ Dialog Windows: │ │ │ │ ADD TO DIALOG_WINDOW (winid) │ │ [ TITLE_BAR <title-string> ] │ │ [ SYSTEM_MENU ] │ │ [ MINIMIZE_BUTTON ] │ │ [ MAXIMIZE_BUTTON ] │ │ [ TASK_LIST ] │ │ [ ACTION_BAR_MENU clause ] │ │ [ TEXT_FIELD clause ] │ │ [ ENTRY_FIELD clause ] │ │ [ MULTILINE_ENTRY_FIE LD clause ] │ │ [ PUSH_BUTTON clause ] │ │ [ RADIO_BUTTON clause ] │ │ [ CHECK_BOX clause ] │ │ [ LIST_BOX clause ] │ │ [ COMBINATION_BOX clause ] │ │ [ GROUP_BOX clause ] │ │ [ ICON_FIELD clause ] ... │ │ │ │ ADD TO { LIST_BOX(id) } │ │ { COMBINATION_B OX(id) } │ │ [ IN DIALOG_WINDOW (winid) ] │ │ LINES {<string-expression> } [SELECTED] [AT <pos> ] │ │ {<array range> } ... │ │ │ │ ADD TO MULTILINE_ENTRY_FIELD (id) │ │ [ IN DIALOG_WINDOW (winid) ] │ │ LINES {<string-expression> } [AT <pos> ] ... │ │ {<array range> } │ │ │ │ ADD TO ACTION_BAR_MENU [ {IN DIALOG_WINDOW (winid)} ] │ │ [ {IN TEXT_WINDOW(winid) } ] │ │ PULLDOWN clause [ BEFORE PULLDOWN (id) ] │ │ [ AFTER PULLDOWN(id) ] │ │ [ CHOICE clause [ SEPARATOR clause ...] ... │ │ │ │ ADD TO PULLDOWN(id) [ {IN DIALOG_WINDOW (winid)} ] │ │ [ {IN TEXT_WINDOW(winid) } ] │ │ {CHOICE claus } [BEFORE {CHOICE(id) } ] ... │ │ {SEPARATOR clause } [AFTER {SEPARATOR(id)} ] │ └──────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────┐ │ Text Windows: │ │ │ │ ADD TO TEXT_WINDOW (winid) │ │ [ TITLE_BAR <title-string> ] │ │ [ SYSTEM_MENU ] │ │ [ MINIMIZE_BUT TON ] │ │ [ MAXIMIZE_BUTTON ] │ │ [ HORIZONTAL_SCROLL_BAR ] │ │ [ VERTICAL_SCRO LL_BAR ] │ │ [ TASK_LIST ] │ │ [ ACTION_BAR_MENU clause ] ... │ └──────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────┐ │ Session Monitors: │ │ │ │ ADD TO SESSION_MONITOR (monitorid) │ │ [ TEXT_WATCH text │ │ [ ENABLED|DISABLED ] │ │ [ AT | FROM | TO clause(s) ] │ │ [ ACTION label ] │ │ [ AS id ] ] ... │ │ [ HOST_KEY_WATCH key │ │ [ ENABLED|DISABLED ] │ │ [ ACTION label ] │ │ [ AS id ] │ └──────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────┐ │ DDE Links: │ │ │ │ Format 1: │ │ ADD TO DDE_LINK(linkid ) │ │ [ TOPIC clause-n ] ... │ │ │ │ Topic clause for ADD TO DDE_LINK (Client): │ │ │ │ TOPIC topicname [ ACTION label ] [ ENABLED|DISABLED ] │ │ [ AS id ] [ HOT_LINK|WARM_LINK clause-n ] ... │ │ │ │ Topic clause for ADD TO DDE_LINK(Server): │ │ │ │ TOPIC topicname [ ACTION label ] [ ENABLED|DISABLED ] │ │ [ AS id ] [ EXPORT_ITEM|EXPORT_COMMAND clause ] ... │ │ │ │ Format 2: │ │ ADD TO TOPIC(id ) [ IN DDE_LINK(linkid ) ] │ │ [ HOT_LINK|WARM_LINK clause-n ]... │ │ │ │ Format 3: │ │ ADD TO TOPIC(id) [ IN DDE_LINK(linkid ) ] │ │ [ EXPORT_ITEM|EXPORT_COMMAND clause ] ... │ └──────────────────────────────────────────────────────────────────────┘ Remarks: For Dialog And Text Window Items: Items added after a window has been OPENed will appear immediately with the following exception: dialog controls that are added to an OPENed DIALOG_WINDOW will not appear unless the window is CLOSEd and reOPENed. Refer to the CREATE DIALOG_WINDOW for the formats of the individual clauses used in this Statement. For more information on CREATE TEXT_WINDOW, refer to the Appendix, Migration From DOS. For Session Monitor Items: monitorid must be the id of a session monitor object created by CREATE SESSION_MONITOR. The TEXT_WATCH clause is specified in the same format as in the CREATE SESSION_MONITOR statement. TEXT_WATCH can be added to a session monitor that is opened or closed. The HOST_KEY_WATCH clause is specified in the same format as in the CREATE SESSION_MONITOR statement. HOST_KEY_WATCH can be added to a session monitor that is opened or closed. For DDE_LINK Objects: Format 1 adds a TOPIC definition (with associated entries) to a DDE_LINK object. The TOPIC is not opened. Format 2 adds HOT_LINK and/or WARM_LINK items to a TOPIC definition. If the TOPIC is opened and enabled, an advise transaction will be generated for all enabled HOT_LINK and WARM_LINK items that are added. Format 3 adds EXPORT_ITEM and/or EXPORT_COMMAND entries to a TOPIC definition. If the TOPIC is enabled, the server script will accept poke, request, and advise transactions for the EXPORT_ITEM entry and execute transactions for the EXPORT_COMMAND entries. DDE_LINK Examples: ADD TO DDE_LINK(1) TOPIC "sheet1" AS 1 ADD TO TOPIC(1) HOT_LINK "R1C1" INTO myvar ACTION myrtn AS 1 See Also: CREATE DIALOG_WINDOW CREATE SESSION_MONITOR REMOVE FROM 12.7 ASC Function Purpose: Returns the ASCII code of a character. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ASC(<string>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function will return the ASCII code for the first character in a string. Example: SET x = ASC("ABC") In this example, "x" would be equal to 65. See Also: STR_VAL 12.8 ATTRIBUTE Function Purpose: Test host screen attribute. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ATTRIBUTE AT <row> , <col> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function returns the attribute associated with the host screen position indicated by the AT clause. The actual value returned by this function is dependent on the type of emulation being done. This value may be easily tested using the IS and ISNOT operators which are defined in this manual. ATTRIBUTE test values for AUTOPILOT supported emulation types are defined in the file TT3278.INC. The appropriate file may be INCLUDEd in the program prior to testing the ATTRIBUTEs. Example: INCLUDE "TT3278.INC" (statement-1) (statement-2) (statement-n) IF ATTRIBUTE AT 10 , 5 IS _BRIGHT GOTO label In this example, _BRIGHT is defined in TT3278.INC and if the ATTRIBUTE at row 10, column 5 is what corresponds to the defined _BRIGHT then the GOTO is executed. 12.9 BEEP Statement Purpose: Beeps the speaker. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ BEEP [frequency,time] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The BEEP Statement sounds the PC speaker at the indicated frequency for the specified period of time. If frequency and time are not specified, 1024 Hz for 1/10 second is used. Remarks: IF ERR 3 BEEP In this example, the program checks to see if ERR is greater than 3. If it is, the computer beeps. 12.10 CARRIER Statement Purpose: Tests the presence of the Carrier Detect signal. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ CARRIER │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function tests the presence of the carrier detect signal in asynchronous communications. It returns a 1 (true) if the carrier is present (i.e. a call is in progress) and a 0 (false) if the carrier is not present (i.e. the call is disconnected). The CARRIER function always returns a 1 (true) if the emulation type is not asynchronous. Example: IF NOT CARRIER DISPLAY "The telephone connection has been disconnected" See Also: DIAL HANG_UP 12.11 CHECK Statement Purpose: The CHECK Statement allows the script to place a check mark in front of a menu CHOICE or to "check" a RADIO_BUTTON or CHECK_BOX dialog control. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ CHECK {RADIO_BUTTON (id) } │ │ {CHECK_BOX(id) } │ │ [ IN DIALOG_WINDOW (winid) ] │ │ │ │ CHECK {CHOICE (id) } [ {IN DIALOG_WINDOW (winid)} ] │ │ [ {IN TEXT_WINDOW } ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: If a RADIO_BUTTON or CHECK_BOX is CHECKed, the result of the IS_CHECKED Function will be 1 (TRUE). See Also: IS_CHECKED UNCHECK 12.12 CLOSE Statement Purpose: Concludes I/O to a file or device, closes dialog and text windows created with the CREATE Statement and Session Monitors created with the CREATE SESSION_MONITOR Statement. It also ends a conversations created with a CREATE DDE_LINK Statement. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ File Processing: │ │ CLOSE <filenum> │ │ │ │ Dialog Windows: │ │ CLOSE DIALOG_WINDOW <window_number> │ │ │ │ Text Windows: │ │ CLOSE TEXT_WINDOW <window_number> │ │ │ │ Session Monitors: │ │ CLOSE SESSION_MONITOR (monitorid) │ │ │ │ DDE Links: │ │ Format 1: │ │ CLOSE TOPIC(id ) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 2: │ │ CLOSE DDE_LINK(linkid) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <filenum> is the number used on the OPEN Statement. The association between a particular file and its file number stops when the CLOSE Statement is executed. When a file opened for OUTPUT or APPEND is CLOSEd, an End Of File Mark IS NOT written. <window_number> is the real number or identifier used in the CREATE TEXT_WINDOW or CREATE DIALOG_WINDOW Statement. For more information on text windows, refer to the Appendix, Migration From DOS. monitorid must be the id of a session monitor object created by CREATE SESSION_MONITOR. A session monitor is not active after it has been closed. CLOSE TOPIC(id ) ends a conversation with a DDE server for the TOPIC specified. This format is only valid for DDE clients. CLOSE DDE_LINK(linkid ) ends a conversation with ALL TOPICs in a DDE_LINK definition. This format is valid for DDE clients and servers. If issued on a DDE server, the server will no longer respond to client requests to start conversations. Example (File Close): OPEN "inpfile.ext" FOR INPUT AS infile OPEN "outfile.ext" FOR OUTPUT AS outfile loop: READ LINE infile var IF EOF(infile) GOTO end WRITE LINE outfile var GOTO loop end: CLOSE infile CLOSE outfile This example would copy the text file "inpfile.ext" to the file "outfile.ext". Note that if outfile was not CLOSED an end of file mark would not have been written. Example (Dialog Close): create dialog_window my_dialog . . . end_create . open DIALOG_WINDOW my_dialog . . close DIALOG_WINDOW my_dialog Example (DDE_LINK): CLOSE TOPIC(1) CLOSE TOPIC(1) IN DDE_LINK(2) CLOSE DDE_LINK(1) See Also: EOF OPEN OPEN_FLAG READ WRITE CREATE DIALOG_WINDOW CREATE TEXT_WINDOW CREATE DDE_LINK 12.13 CLS HOST Statement Purpose: Clears the buffer associated with the current asynchronous host screen. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ CLS HOST │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The CLS HOST Statement is for asynchronous communications only. It clears the Host Screen buffer and positions the cursor at row 1, column 1. Data is then displayed from that point. CLS HOST may be used with any type of asynchronous communications. However, if the data is not being displayed in a TTY-like fashion (no screen positioning sequences other than CR and LF), care must be taken since hosts tend to build the next screen based on what it thinks is already being displayed. CLS HOST is generally used to simplify WAIT and LOOK FORs during TTY like prompting sequences where the changes in the screen after each prompt already appear on the screen. 12.14 CONNECT and JUMP Statements Purpose: Direct subsequent program statements to interact with a specified session. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ CONNECT TO SESSION <session> │ │ │ │ JUMP TO SESSION <session> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <session> is a single letter EHLLAPI session-id or the 2 to 8 character EHLLAPI session-name of the session to receive control CONNECT and JUMP direct subsequent program statements to interact with a specified session. ALL subsequent communications commands (SEND, WAIT FOR, SCREEN, etc.) will be directed to this session. Only one EHLLAPI session may be CONNECT'ed at any one time. When CONNECT is used, the connection to the requested SESSION occurs internally and the AUTOPILOT application continues as the active window. If JUMP is used, the connection to the requested SESSION occurs physically and the specified session becomes the active one. If the CONNECT or JUMP Statement is successful, the RETURN_CODE is set to 0. If the CONNECT is unsuccessful, the RETURN_CODE is set to 1. For example, the RETURN_CODE would be set to 1 if an attempt to CONNECT TO SESSION "C" were issued and a session "C" did not exist. It is recommended that you ALWAYS test RETURN_CODE after returning from a CONNECT or JUMP Statement. WARNING: In order for CONNECT or JUMP to function properly by specifying session-id for a TalkThru session, the TalkThru session must have been loaded for EHLLAPI Support. For more information on what this means and how it is accomplished, refer to the Chapter, EHLLAPI Support. If you specify the longer session-name, this restriction is not valid. Example: The following segment of code will CONNECT to host session-id A, send a LOGON sequence and then JUMP to the session. connect to SESSION "A" send "logon userid/password" , enter wait for "Ready;" jump to SESSION "A" 12.15 COPY_FROM_HOST Statement Purpose: Copies a portion of the HOST screen into an identifier. May also be used to copy a multiple line rectangular portion of the HOST screen into an array. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ COPY_FROM_HOST [ FROM row,col ] [ TO row,col ] │ │ INTO identifier [ format options ] [, ...] │ │ │ │ COPY_FROM_HOST [ FROM row,col ] [TO row,col ] │ │ INTO array [ array range ] [ format options ] │ │ [, ...] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The optional FROM row,col and TO row,col clauses specify the rectangular portion of the HOST screen to copy. If FROM... is not specified, the copy will start from row 1 column 1. If TO... is not specified the COPY will end at the last character position on the screen. identifier is the name of the identifier that receives the copied portion of the screen as a string. If the copy operation spans more than one row, the strings are concatenated together. array is the name of an array that receives the copied portion of the screen as a series of strings--one string per row copied. Each string is copied into a separate array element. array range optionally specifies a starting and/or ending point in the destination array when copying one or more lines: The range specification is in the format: ( [ FROM indices ] [ TO indices ] ) If FROM is not included, strings are copied into the first array element. If TO is not included strings are copied up to the last array element. format options are optional keywords that specify automatic formatting of the string. They may include one or more of the following: TRUNCATE Truncate trailing spaces UPPER or LOWER Convert case LEFT or RIGHT Left or Right Justify More than 1 copy operation can be specified within a single COPY_FROM_HOST statement. Combining copies into one can significantly increase the speed of the copies. Examples: ; Copy the entire screen into an identifier x COPY_FROM_HOST INTO x ; Copy columns 10 through 20 from each row into an ; array and convert to upper case DIM array[24] COPY_FROM_HOST FROM 1,10 TO 24,20 INTO array UPPER ;Perform multiple copy operations within 1 statement: COPY_FROM_HOST FROM 2,5 TO 2,20 INTO a , FROM 4,20 TO 4,50 INTO b , FROM 12,15 TO 12,80 INTO c 12.16 COPY_TO_HOST Statement Purpose: Sends a string of characters to the specified row and column of the current host screen. May also be used to copy multiple strings from an array to the host in a single operation. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ COPY_TO_HOST string [ AT row, col ] │ │ [ NORESTORE ] [ USING keylist ] │ │ │ │ COPY_TO_HOST array [ array range ] [ AT row,col ] │ │ [ NORESTORE ] [ USING keylist ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: string is an expression that consists of the characters to be copied to the current host session. array is the name of an array that contains one or more strings to be copied to the current host session. array range optionally specifies a starting and/or ending point in the source array when copying one or more lines: The range specification is in the format: ( [ FROM indices ] [ TO indices ] ) If FROM is not included, strings are copied from the first array element. If TO is not included strings are copied up to the last array element. AT row,col optionally specifies a row and column to begin copying string at. If an array is specified as the source, the AT clause can be used to specify the row and column of the first string copied. NORESTORE can be used to inhibit the default action of restoring the cursor at the original cursor position when the copy is finished. This can significantly improve performance. It is ignored for non-TalkThru sessions. USING keylist can optionally be specified to list the key(s) to be sent after each string is copied. When copying multiple fields from an array, the USING statement would be used to list the key(s) necessary to navigate to the next field. If not specified, the cursor will be positioned to the next row in the same column as the start of the previous field. Examples: ;Copy a single field at the current cursor position COPY_TO_HOST "userid" ;Copy a single field at a specific cursor position ;and don't restore the cursor to its original position COPY_TO_HOST "userid" AT 2,1 NORESTORE ;Copy several fields at one time using TAB to go from ;1 field to the next DIM array(5) = "Fld 1" , "Fld 2" , "Fld 3" , "Fld 4" , "Fld 5" COPY_TO_HOST array FROM 1 TO 3 AT 2 , 10 USIN G TAB 12.17 CREATE DDE_LINK Statement (Client) Purpose: Defines a link between a DDE client (AUTOPILOT) and a DDE Server (some other application, possibly AUTOPILOT). Used in conjunction with OPEN, CLOSE, DESTROY to establish a DDE conversation. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ CREATE DDE_LINK linkid │ │ CLIENT application │ │ [ ACTION label ] │ │ [ TOPIC clause-n ] │ │ END_CREATE │ │ │ │ Topic clause for CREATE DDE_LINK: │ │ │ │ TOPIC topicname [ ACTION label ] [ ENABLED|DISABLED ] │ │ [ AS id ] │ │ [ HOT_LINK itemname INTO variable [ ACTION label ] │ │ [ ENABLED|DISABLED ] [ AS id ] ] ... │ │ [ WARM_LINK itemname [ ACTION label ] │ │ [ ENABLED|DISABLED ] [ AS id ] ]... │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement defines a DDE link between a client (the AUTOPILOT script) and a DDE server. A definition merely defines the components of a link -- it does not actually initiate a conversation (see OPEN DDE_LINK). The linkid argument may be either: o An integer expression between 1 and 30. o An identifier set to zero. If this is the case, the identifier will be set to an unused link id. The CLIENT clause indicates that this DDE_LINK is to act as a DDE client. The Application argument specifies the name of the desired server application you wish to converse with. It is required and may occur only once in each DDE_LINK definition. The ACTION label clause allows you to specify a label in your AUTOPILOT program to receive control if one of the following events occur: o A DDE conversation is ended by the server. o A HOT_LINK or WARM_LINK item with no associated ACTION routine is updated by the server. The TOPIC clause defines a desired topic for a DDE conversation and any HOT_LINKS or WARM_LINKS associated with that topic. A DDE_LINK may have more than TOPIC clause. The HOT_LINK clause defines a 'hot' advise link for the item named by itemname. Whenever the data associated with the HOT_LINK is changed, the data is sent to the client by the server. When this data is received it is placed in the variable specified by the INTO clause (if any). An ACTION is triggered an control is passed to the highest priority specified ACTION routine (HOT_LINK,TOPIC,DDE_LINK). The WARM_LINK clause defines a 'warm' advise link for the item named by itemname. Whenever the data associated with the WARM_LINK is changed, notification is sent to the client by the server, an ACTION is triggered, and control is passed to the highest priority specified ACTION routine (WARM_LINK,TOPIC,DDE_LINK). 12.18 CREATE DDE_LINK Statement (Server) Purpose: Defines a link between a DDE Server (AUTOPILOT) and a DDE Client (some other application, possibly AUTOPILOT). Used to prepare the AUTOPILOT script to act as a DDE server to one or more clients. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ CREATE DDE_LINK linkid │ │ SERVER application │ │ [ ACTION label ] │ │ [ TOPIC clause-n ] │ │ END_CREATE │ │ │ │ Topic clause for CREATE DDE_LINK: │ │ │ │ TOPIC topicname [ ACTION label ] [ ENABLED|DISABLED ] │ │ [ AS id ] │ │ [ EXPORT_ITEM itemname [ FROM|INTO ] variable │ │ [ ACTION label ] [ ENABLED|DISABLED ] [ AS id ] ] ... │ │ [ EXPORT_COMMAND command-str [ ACTION label ] │ │ [ ENABLED|DISABLED ] [ AS id ] ] ... │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement defines a DDE link between a server (the AUTOPILOT script) and a DDE client. A definition merely defines the components of a link -- it does not actually ready the script to participate in a conversation (see OPEN DDE_LINK). The linkid argument may be either: o An integer expression between 1 and 30. o An identifier set to zero. If this is the case, the identifier will be set to an unused link id. The SERVER clause indicates that this DDE_LINK is to act as a DDE server. The application argument specifies the name of the application. Client programs will use this name when they try to establish a conversation with the server. It is required and may occur only once in each DDE_LINK definition. The ACTION label clause allows you to specify a label in your AUTOPILOT program to receive control if one of the following events occur: o A DDE conversation is started by the client for a TOPIC that does not have an ACTION routine. o A conversation is ended by the client for a TOPIC that does not have an ACTION routine. o A REQUEST, POKE, START ADVISE, or STOP ADVISE transaction is received for an item defined in an EXPORT_ITEM clause that does not have an ACTION routine o An execute transaction is received for a command defined in an EXPORT_COMMAND clause that does not have ACTION routine. The TOPIC clause defines a desired topic for a DDE conversation and any EXPORT_ITEM and/or EXPORT_COMMAND entries associated with that topic. A DDE_LINK may have more than one TOPIC clause. The EXPORT_ITEM clause defines an item that is available for poke, request, and advise transactions. The item name is specified as a string expression. It is required. The item name is not case sensitive and may contain wildcard characters (see below). If an EXPORT_ITEM is disabled, no poke, request, or advise transactions will be allowed. When a poke, request, or advise transaction is received for an EXPORT_ITEM, an ACTION is triggered and control is passed to the routine specified in the ACTION clause. If no ACTION clause is specified the TOPIC's (or, if none, DDE_LINK's) ACTION routine will receive control. ACTION_OBJECT (and ACTION_INFO(1)) will return the DDE_LINK number. ACTION_ID (and ACTION_INFO(2)) will return the EXPORT_ITEM id. ACTION_INFO(4) may be used to determine the actual item name specified by the client (this is useful if wildcards were used in the EXPORT_ITEM name). The transaction can be rejected by using a non-zero return code in the RESUME ACTION statement. When a poke transaction is received for an item that matches an EXPORT_ITEM entry a Poke ACTION is triggered (ACTION_TYPE=17). The optional INTO clause specifies a variable that will receive the data . In addition, the data can be retrieved in the ACTION routine via ACTION_INFO(5). When a Request transaction is received, a Request ACTION is triggered (ACTION_TYPE=18). The data returned to client is specified by the last DDE_UPDATE statement issued for this item prior to the RESUME ACTION statement. If there is no ACTION routine, the value of the last DDE_UPDATE will be returned immediately. When a Start Advise transaction is received, an ACTION is triggered (ACTION_TYPE=15). If the advise link is accepted (default, unless a non-zero return code is specified in the RESUME ACTION statement), data will be sent to the client whenever the export item is updated with the DDE_UPDATE statement. When a Stop Advise transaction is received, an ACTION is triggered (ACTION_TYPE=16). Data will no longer be sent to the client when the value of the EXPORT_ITEM is changed via the DDE_UPDATE statement. The EXPORT_COMMAND clause defines a command that is available for client execute transactions. The command is specified as a string expression. It is required. The command is not case sensitive and may contain wildcard characters (see below). If an EXPORT_COMMAND is disabled, execute ACTIONs will be triggered. When an execute transaction is received for an EXPORT_COMMAND, an ACTION is triggered and control is passed to the routine specified in the ACTION clause. If no ACTION clause is specified, the TOPIC's (or, if none, the DDE_LINK's) ACTION routine will receive control. ACTION_OBJECT (and ACTION_INFO(1)) will return the DDE_LINK number. ACTION_ID (and ACTION_INFO(2)) will return the EXPORT_COMMAND id. ACTION_INFO(5) may be used to determine the actual command issued by the client (this is useful if wildcards were used in the EXPORT_COMMAND). The transaction can be rejected by using a non-zero return code in the RESUME ACTION statement. As previously stated, a wildcard pattern may used in EXPORT_ITEM and EXPORT_COMMAND names. This is useful in instances where there are a large number of possible items and commands that the server would like to accept but would rather not define an explicit entry for each one. The wildcard pattern characters used are the same as can be specified in AUTOPILOTs WAIT statement: ? - matches any character s* - matches zero or more occurrences of character 's' s+ - matches one or more occurrences of character 's' \? - used to match a '?' \* - used to match a '*' \+ - used to match a '+' For example, if a script maintained a table of say, 100 rows and 20 columns and wanted to allow DDE clients to establish links with various cells in that table it could specify an EXPORT_ITEM entry for each of the 2000 items in the table. A better way would be to specify a single EXPORT_ITEM with an item name containing wildcards: EXPORT_ITEM "ROW?+ COL?+" ACTION myactrtn AS 100 The item name "R?+C?+" would match any client request with a name that had 'ROW ', followed by 1 or more characters, followed by 'COL ' followed by one or more characters. For example, "ROW 1 COL 2" and "Row 25 Col 100" are valid and "10 Col 5" and "Row 5 Col" are not. In our example, the ACTION routine 'myactrtn' could use ACTION_INFO(4) to retrieve the item name issued by the client an extract the row and column number (Since "Row xyz Col #$@" would also match the wildcard item name, the server script needs to do some validation--it can use a non-zero return code on the RESUME ACTION statement to reject a transaction). When using wildcard matches for items that need to respond to Request and Advise transactions, the script should add an explicit EXPORT_ITEM (via the ADD statement) for the actual item name specified by the client (you can use ACTION_INFO(4) to get the actual item name. Once the EXPORT_ITEM is added, you can use DDE_UPDATE to update the value of the EXPORT_ITEM. The following code fragment show how an ACTION routine might add an EXPORT_ITEM (if it wasn't already added) and then update the item's value. IF ACTION_TYPE = 18 BEGIN IF TEXT_OF(EXPORT_ITEM(id))= "" BEGIN ADD TO TOPIC(1) EXPORT_ITEM ACTION_INFO(4) ACTION link_wildcard AS id END DDE_UPDATE EXPORT_ITEM(id) WITH item(id) END 12.19 CREATE DIALOG_WINDOW Statement Purpose: This statement will define a Presentation Manager dialog to contain any number of a variety of dialog controls. Used in conjunction with OPEN DIALOG_WINDOW, CLOSE DIALOG_WINDOW and DESTROY DIALOG_WINDOW to allow AUTOPILOT programs to define and manipulate there own Presentation Manager dialogs. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ CREATE DIALOG_WINDOW <winid> │ │ [ VISIBLE | INVISIBLE ] │ │ [ ENABLED | DISABLED ] │ │ [ MINIMIZED | MAXIMIZED ] │ │ [ TITLE_BAR <title-string> ] │ │ [ BORDER TYPE <border-type> ] │ │ [ ICON <iconfilespec> ] │ │ [ TASK_LIST ] │ │ [ SYSTEM_MENU ] │ │ [ MAXIMIZE_BUTTON ] │ │ [ MINIMIZE_BUTTON ] │ │ [ WINDOW_SIZE < rows> [ { TEXT_ROWS } ] │ │ [ { DEVICE_ROWS } ] │ │ [ { DIALOG_ROWS } ] ] [,] │ │ <cols> [ { TEXT_COLUMNS } ] │ │ [ { DEVICE_COLUMNS } ] │ │ [ { DIALOG_COLUMNS } ] ] │ │ [WINDOW_POSITION [ DEVICE_ROWS ] <rows>[,] │ │ [ DEVICE_COLUMNS ] <cols>] │ │ [ ACTION <label> ] │ │ [ ACTION_BAR_MENU clause ] │ │ [ TEXT_FIELD clause ] │ │ [ ENTRY_FIELD clause ] │ │ [ MULTILINE_ENTRY_FIELD clause ] │ │ [ PUSH_BUTTON clause ] │ │ [ RADIO_BUTTON clause ] │ │ [ CHECK_BOX clause ] │ │ [ LIST_BOX clause ] │ │ [ COMBINATION_BOX clause ] │ │ [ GROUP_BOX clause ] │ │ [ ICON_FIELD clause ] │ │ END_CREATE │ └──────────────────────────────────────────────────────────────────────┘ Remarks: CREATE DIALOG_WINDOW is used to create standard OS/2 dialog windows. Multiple CREATE DIALOG_WINDOW Statements can be used in a single AUTOPILOT program. To indicate which dialog is current, use the SET CURRENT_WINDOW Statement. <winid> may be either: 1. An integer expression such that 0 < <winid> < 100. 2. An identifier set to zero. If this is the case, the identifier will be set to the window id assigned to this dialog. This is the recommended approach. The initial visibility state of a dialog may be set by the VISIBLE or INVISIBLE keyword. The default is VISIBLE. The visibility state may be changed after dialog creation by using the SHOW DIALOG_WINDOW Statement. The initial selectability state of the DIALOG_WINDOW may be set by the ENABLED or DISABLED keyword. The default is ENABLED. The selectability state may be changed after dialog creation by using the ENABLE DIALOG_WINDOW or DISABLE DIALOG_WINDOW Statements. If a DIALOG_WINDOW is DISABLED, it will not receive focus. MINIMIZED/MAXIMIZED The initial size state of the window may be set by the MINIMIZED or MAXIMIZED clause. The default is neither -- the initial size of the window is set by the WINDOW_SIZE clause. The MINIMIZE or MAXIMIZE Statement can be used after dialog creation to change this state. TITLE_BAR Adds a title bar to the dialog. <title-string> is required but may be set to "". If this clause is not included, no title bar will be included. BORDER Determines the type of border the dialog will have. <bordertype> may be: 0 - no border 1 - size border 2 - dialog border 3 - standard border If this clause is not included, the window will have no border. ICON Sets the dialog's icon to the icon specified by <iconfilespec>. The default directory for the icon is set by the ICON_DIRECTORY Customization Variable (this variable can be viewed or changed by selecting the System Configuration dialog on the Utilities pull down menu on any Phone Book). If this clause is not specified, the icon will be set to one of the standard OS/2 icons by the dialog procedure. TASK_LIST A dialog may put itself on the OS/2 Task List by using the TASK_LIST clause. By default, the window WILL NOT be put on the Task List. SYSTEM_MENU MINIMIZE_BUTTON MAXIMIZE_BUTTON Includes the specified component in the dialog. If the keyword is not specified the component is not included. WINDOW_SIZE Defines the dialog size The default coordinate type is DIALOG_ROWS and DIALOG_COLUMNS. Valid coordinate types are TEXT_ROWS, TEXT_COLUMNS, DIALOG_ROWS, DIALOG_COLUMNS, DEVICE_ROWS, and DEVICE_COLUMNS (see Coordinate System discussed below). WINDOW_POSITION Defines the dialog position relative to its parent. The default and only valid coordinate types are DEVICE_ROW[S] and DEVICE_COLUMN[S] (see Coordinate System discussed below). ACTION Allows you to specify a label in your AUTOPILOT program to receive control if one of the following conditions are true: 1. The SYSTEM MENU Item Close is requested. 2. A PULLDOWN is requested (see ACTION_BAR_MENU below) with no associated ACTION. 3. A CHOICE is requested (see ACTION_BAR_MENU below) with no associated ACTION and no associated PULLDOWN ACTION. 4. A dialog control is activated and no ACTION clause was specified. See the discussion under the ACTION_BAR_MENU clause for more information on PULLDOWN and CHOICE ACTIONs. A discussion on the ACTION_BAR_MENU clause and all dialog control clauses are discussed after the Coordinate System. Coordinate System: The following system is used to determine coordinates on the TEXT_SIZE, WINDOW_SIZE and WINDOW_POSITION clauses. The Coordinate System is based on a grid where Y is the Vertical Axis and X is the Horizontal Axis. 1. The origin (0,0) is the top left corner. 2. By default, Y is specified first. 3. The values may be separated by a comma: AT 20 , 5 4. There are several different units that a coordinate specification may be expressed in: DEVICE - essentially Pels TEXT - text character position DIALOG - related to the size of the window or dialog's character set The following keywords are used in size specifications: DEVICE_ROWS DEVICE_COLUMNS TEXT_ROWS TEXT_COLUMNS DIALOG_ROWS DIALOG_COLUMNS The following keywords are used in position specifications: DEVICE_ROW DEVICE_COLUMN TEXT_ROW TEXT_COLUMN DIALOG_ROW DIALOG_COLUMN ┌────────────────────────────────┐ │ 12.19.1 ACTION_BAR_MENU Clause │ └────────────────────────────────┘ Purpose: The ACTION_BAR_MENU clause allows you to create action bar menus and to define the ACTIONs to occur when they are selected. It can be specified in a CREATE DIALOG_WINDOW, CREATE TEXT_WINDOW, ADD TO DIALOG_WINDOW, or ADD TO TEXT_WINDOW Statement. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ACTION_BAR_MENU [ [ ACTION ] <label> ] │ │ [ ENABED|DISABLED ] │ │ PULLDOWN <text> [ [ ACTION ] <label> ] ] │ │ [ ENABLED|DISABLED ] [AS <refno>] │ │ CHOICE <text> [ [ ACTION ] <label> ] ] │ │ [ ENABLED|DISABLED ] │ │ [ CHECKED|UNCHECKED ] [AS <refno > ] │ │ SEPARATOR [ AS <refno> ] │ │ │ │ PULLDOWN <text> [ [ ACTION ] <label> ] ] │ │ [ ENABLED|DISABLED ] [AS <refno> ] │ │ CHOICE <text> [ [ ACTION ] <label> ] ] │ │ [ ENABLED|DISABLED ] │ │ [ CHECKED|UNCHECKED ] [AS <refno> ] │ │ SEPARATOR [ AS <refno> ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Action bar menus consist of 1 or more PULLDOWN menus. Each PULLDOWN menu consists of all the CHOICEs and SEPARATORs that follow it until the next PULLDOWN Statement is encountered or the ACTION_BAR_MENU clause ends. A PULLDOWN without any subsequent CHOICEs or SEPARATORs will not display a menu when selected but will instead act as if it was a CHOICE item. The <text> of a PULLDOWN will appear on the action bar menu. If a tilde (~) appears in the text, the character following the tilde will form a mnemonic in association with the ALT Key that can be used to display the PULLDOWN directly from the keyboard (called an Accelerator): PULLDOWN "~File" AS 100 In the preceding example, pressing ALT/F will display the File pull down menu. The <text> on the CHOICE clause appears on the associated PULLDOWN menu. If a tilde (~) appears in the text, it will establish an Accelerator Key exactly as with the PULLDOWN. Embedding a Tab (tilde followed by capital i - ~I) in the <text> will cause the text to the right of the tab to be displayed on the right side of the CHOICE. A PULLDOWN or CHOICE may be ENABLE'd or DISABLE'd. If DISABLE'd, they will appear "grayed out" and may not be selected. By default, they are ENABLE'd. If a PULLDOWN is DISABLE'd, all CHOICES are, by default, DISABLE'd. If a CHOICE is CHECKED, a small check mark will appear next to <text>. The default is UNCHECKED. CHOICES may be CHECKED and UNCHECKED dynamically by using the CHECK and UNCHECK Statements. The AS <refno> clause is optional and allows you to assign a Reference Number to an ACTION_BAR_ITEM, PULLDOWN, or CHOICE. This Reference Number can be referred to in other Statements (i.e. ENABLE/DISABLE, SET PULL_DOWN, SET CHOICE). Valid reference numbers are in the range of 1 to 10000. The ACTION clause allows you to specify the <label> in this AUTOPILOT program to receive control when this PULLDOWN or CHOICE is selected. If ACTION is specified on the PULLDOWN clause, it will only be triggered if there are NO associated CHOICEs. The ACTION associated with the ACTION_BAR_MENU only receives control when a CHOICE is selected that contains NO ACTION or when a PULLDOWN is selected which has no CHOICEs or ACTIONs. When routines identified by an ACTION clause receive control, the entire action bar menu is DISABLE'd (grayed out) until a RESUME ACTION or ENABLE ACTION_BAR_MENU Statement is issued. Since you probably wish to complete a selected item prior to allowing more action bar menu items to be selected, it is normally recommended that you do not ENABLE the action bar menu until you wish to RESUME normal processing. See the RESUME and ENABLE Statements for more information on format. Multiple ACTION clauses may indicate the same <label> in the AUTOPILOT program. If a common routine wishes to identify which CHOICE triggered it, it may use the ACTION_WINDOW, ACTION_TYPE and ACTION_ID Functions. See the discussion of these Functions for more information. A SEPARATOR is simply a horizontal line that is used to break up a PULLDOWN menu. It cannot be selected, ENABLE'd, DISABLE'd, CHECKED, or UNCHECKED. ┌──────────────────────────┐ │ 12.19.2 CHECK_BOX Clause │ └──────────────────────────┘ Purpose: A CHECK_BOX is a small square with associated text to the right. It is used to select zero or more items from a list. When the box or string is clicked, by clicking on it with the mouse or pressing the spacebar when it is active, the check box changes state from CHECKed to UNCHECKed or from UNCHECKed to CHECKed. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ CHECK_BOX <text> │ │ [ VISIBLE | INVISIBLE ] │ │ [ ENABLED | DISABLED ] │ │ [ CHECKED | UNCHECKED ] │ │ [ SIZE <rowsize> , <colsize> ] │ │ [ AT <rowpos> , <colpos> ] │ │ [ ACTION <label> ] │ │ [ AS <refno> ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <text> sets the initial text of the CHECK_BOX. It is required. It may be changed after dialog create by using the SET CHECK_BOX Statement. The initial visibility state of may be set by the VISIBLE or INVISIBLE keyword. The default is VISIBLE. The visibility state may be changed after dialog creation by using the SHOW CHECK_BOX or HIDE CHECK_BOX Statements. The initial selectability state of the CHECK_BOX may be set by the ENABLED or DISABLED keyword. The default is ENABLED. The selectability state may be changed after dialog creation by using the ENABLE CHECK_BOX or DISABLE CHECK_BOX Statements. If a CHECK_BOX is DISABLED it is displayed in halftone and cannot be clicked. The initial checked state may be set by using the CHECKED or UNCHECKED keywords. The default is UNCHECKED. The checked state may be changed after dialog creation by using the CHECK CHECK_BOX or UNCHECK CHECK_BOX Statements. The current check state may be determined by the IS_CHECKED Function. The size of the CHECK_BOX is defined in the SIZE clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. If no SIZE clause is specified the SIZE will default to the minimum size to display <text>. The standard height for a CHECK_BOX is 10 DIALOG_ROWS. The width is dependant on the contents of <text>. The position of the CHECK_BOX is defined in the AT clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The position is relative to the top left corner of the DIALOG_WINDOW and specifies the top left corner of the CHECK_BOX. The ACTION clause allows you to specify a <label> that will receive control after a CHECK_BOX has been pressed. If the action is triggered, ACTION_WINDOW will be set to the window number specified in the CREATE DIALOG_WINDOW Statement, ACTION_ID will be set to the CHECK BOX's reference number (see AS clause) and ACTION_TYPE will be set to 5. The AS clause allows a specific reference number to be assigned to the CHECK_BOX. If not specified, the reference number 1 is assigned to the first CHECK_BOX on the screen that doesn't have an AS clause, the number 2 is assigned to the second, 3 to the third and so on. If the contents of the AS clause is an identifier that has a numeric value of 0, the identifier will be set to the assigned reference number. The <text> associated with a CHECK_BOX may be determined using the TEXT_OF Function. ┌────────────────────────────────┐ │ 12.19.3 COMBINATION_BOX Clause │ └────────────────────────────────┘ Purpose: A COMBINATION_BOX combines the capabilities of both an ENTRY_FIELD and a LIST_BOX. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ COMBINATION_BOX [<text>] │ │ [ VISIBLE | INVISIBLE ] │ │ [ ENABLED | DISABLED ] │ │ [ DROP_DOWN | DROP_DOWN_LIST ] │ │ [ LINES ... , ... ] │ │ [ USING <sortstr> ] │ │ [ SIZE <rowsize> , <colsize> ] │ │ [ ACTION <label> ] │ │ [ AT <rowpos> , <colpos> ] │ │ [ AS <refno> ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The optional <text> clause may be used to specify the initial text of the entry field portion of the COMBINATION_BOX. If not specified it defaults to the SELECTED item. The initial visibility state of a COMBINATION_BOX may be set by the VISIBLE or INVISIBLE keyword. The default is VISIBLE. The visibility state may be changed after dialog creation by using the SHOW COMBINATION_BOX or HIDE COMBINATION_BOX Statements. The initial selectability state of the COMBINATION_BOX may be set by the ENABLED or DISABLED keyword. The default is ENABLED. The selectability state may be changed after dialog creation by using the ENABLE COMBINATION_BOX or DISABLE COMBINATION_BOX Statements. If a COMBINATION_BOX is DISABLED the selection cannot be changed. The default COMBINATION_BOX style shows a list box/entry field pair such that both are always visible. The DROP_DOWN style works like the default style except that the list box portion is hidden until the user clicks on the prompt box to display it. It can be selected by including the DROP_DOWN keyword. The DROP_DOWN_LIST style is a variation on the DROP_DOWN style where the entry field can only have selections that are specified in the list box. The initial contents of the list box portion is set by the optional LINES (or LINE) clause. The LINES clause consists of 1 or more comma separated string expressions and or array ranges: ┌──────────────────────────────────────────────────────────────────────┐ │ LINES {string [ SELECTED ] } [, ...] │ │ {array [ FROM dim1 [ ,dim2 ] ...] │ │ [ TO dim1 [,dim2 ] ...] } │ └──────────────────────────────────────────────────────────────────────┘ The keyword SELECTED may be associated with a particular string specification to select that line. The SELECT and DESELECT Statements may be used after dialog creation to change the selection. The SELECTED_LINE Function may be used to determine which line is selected. The USING clause uses a subset of the SORT USING options. This allows you to explicitly specify the order items will be placed in the list box portion of the COMBINATION_BOX. The valid options are 'T1' (ASCII collating sequence),'T2' (dictionary order i.e. case insensitive), 'T3' (numeric), 'A' (ascending), and 'D' (descending). See the SORT Statement for more details. The size of the COMBINATION_BOX is defined in the SIZE clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The ACTION clause allows you to specify a <label> that will receive control after an element has been selected or deselected in the COMBINATION BOX has been pressed. If the action is triggered, ACTION_WINDOW will be set to the window number specified in the CREATE DIALOG_WINDOW Statement, ACTION_ID will be set to the COMBINATION BOX's reference number (see AS clause) and ACTION_TYPE will be set to 7. The ACTION will also be triggered if the MOUSE is Double Clicked over an item. In this case, ACTION_TYPE will be set to 8. The position of the COMBINATION_BOX is defined in the AT clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The position is relative to the top left corner of the DIALOG_WINDOW and refers to the top left of the COMBINATION_BOX. The AS clause allows a specific reference number to be assigned to the COMBINATION_BOX. If not specified, the reference number 1 is assigned to the first COMBINATION_BOX on the screen that doesn't have an AS clause, the number 2 is assigned to the second, 3 to the third and so on. If the contents of the AS clause is an identifier that has a numeric value of 0, the identifier will be set to the assigned reference number. The contents of the COMBINATION_BOX may be determined by using the TEXT_OF Function. ┌────────────────────────────┐ │ 12.19.4 ENTRY_FIELD Clause │ └────────────────────────────┘ Purpose: An ENTRY_FIELD is a rectangular area of the dialog that displays a single line of text that the user can edit. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ENTRY_FIELD <text> │ │ [ VISIBLE | INVISIBLE ] │ │ [ ENABLED | DISABLED ] │ │ [ TEXT_SIZE < maxchars> ] │ │ [ ALIGN_LEFT | ALIGN_CENTER | ALIGN_RIGHT ] │ │ [ AUTOSKIP ] │ │ [ NOECHO ] │ │ [ READ_ONLY ] │ │ [ BORDER 0 | 1 ] │ │ [ SIZE <rowsize> , <colsize> ] │ │ [ AT <rowpos> , <colpos> ] │ │ [ ACTION <label ] │ │ [ AS <refno> ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The initial value of a field is set by <text>. This field is required but may be set to "" or " ". The maximum number of characters that may be entered into an ENTRY_FIELD is determined by the TEXT_SIZE clause. By default, TEXT_SIZE is 32. The entered text can be automatically aligned and justified within the ENTRY_FIELD by specifying ALIGN_LEFT, ALIGN_CENTER, or ALIGN_RIGHT. The default is ALIGN_LEFT. The initial visibility state of the text may be set by the VISIBLE or INVISIBLE keyword. The default is VISIBLE. The visibility state may be changed after dialog creation by using the SHOW ENTRY_FIELD or HIDE ENTRY_FIELD Statements. The initial selectability state of the ENTRY_FIELD may be set by the ENABLED or DISABLED keyword. The default is ENABLED. The selectability state may be changed after dialog creation by using the ENABLE ENTRY_FIELD or DISABLE ENTRY_FIELD Statements. If an ENTRY_FIELD is DISABLED it cannot be modified by the user or accessed from the keyboard or by the mouse. If AUTOSKIP is specified, keyboard focus will automatically go to the next field in the dialog after TEXT_SIZE characters have been entered. The default is NO AUTOSKIP. If the READ_ONLY keyword is specified, the ENTRY_FIELD cannot be modified by the user. If NOECHO is specified, characters will be displayed as asterisk This is commonly used for password fields. The BORDER clause defines the type of border that is drawn around the ENTRY_FIELD. 0 specifies no border and 1 specifies a thin line border. The default is BORDER 1. The size of the ENTRY_FIELD is defined in the SIZE clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. If no SIZE clause is specified the SIZE will default to the size needed to display <text> plus room for about 4 more characters. The standard height for an entry field is 8 DIALOG_ROWS. If the field is not large enough to display the entered text (up to TEXT_SIZE characters) the field will automatically scroll. Note that the SIZE specification does not include the border i.e. a border will be drawn around the field whose height and width is defined by SIZE. The position of the ENTRY_FIELD is defined in the AT clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The position is relative to the top left corner of the DIALOG_WINDOW. The position refers to top left corner of the field's text, not its border. For example, an entry field with a border would be aligned with a text field on the same row. The ACTION clause allows you to specify a <label> that will receive control after a field has been modified and the keyboard focus has moved to another field. If the action is triggered, ACTION_WINDOW will be set to the <winid> specified in the CREATE DIALOG_WINDOW Statement, ACTION_ID will be set to the ENTRY_FIELD's reference number (see AS clause) and ACTION_TYPE will be set to 6 (field changed). The AS clause allows a specific reference number to be assigned to the ENTRY_FIELD. If not specified, the reference number 1 is assigned to the first ENTRY_FIELD on the screen that doesn't have an AS clause, the number 2 is assigned to the second, 3 to the third and so on. If the contents of the AS clause is an identifier that has a numeric value of 0, the identifier will be set to the assigned reference number. The contents of an ENTRY_FIELD may be determined using the TEXT_OF Function. ┌──────────────────────────┐ │ 12.19.5 GROUP_BOX Clause │ └──────────────────────────┘ Purpose: A GROUP_BOX is a box that has an identifying text string in its upper left corner. GROUP_BOXES are used to collect a group of RADIO_BUTTONS or other dialog controls visually into a single unit. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ GROUP_BOX <text> │ │ [ VISIBLE | INVISIBLE ] │ │ [ SIZE <rowsize> , <colsize> ] │ │ [ AT <rowpos> , <colpos> ] │ │ [ AS <refno> ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The optional <text> clause may be used to specify the initial text displayed on the top of the GROUP_BOX. The initial visibility state of a GROUP_BOX may be set by the VISIBLE or INVISIBLE keyword. The default is VISIBLE. The visibility state may be changed after dialog creation by using the SHOW GROUP_BOX or HIDE GROUP_BOX Statements. The size of the GROUP_BOX is defined with the SIZE clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The position of the GROUP_BOX is defined with the AT clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The position is relative to the top left corner of the DIALOG_WINDOW and refers to the top left of the GROUP_BOX. The AS clause allows a specific reference number to be assigned to the GROUP_BOX. If not specified, the reference number 1 is assigned to the first GROUP_BOX on the screen that doesn't have an AS clause, the number 2 is assigned to the second, 3 to the third and so on. If the contents of the AS clause is an identifier that has a numeric value of 0, the identifier will be set to the assigned reference number. ┌───────────────────────────┐ │ 12.19.6 ICON_FIELD Clause │ └───────────────────────────┘ Purpose: An ICON_FIELD is used to include an ICON in the DIALOG_WINDOW. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ICON_FIELD <iconname> │ │ [ VISIBLE | INVISIBLE ] │ │ [ AT <rowpos> , <colpos> ] │ │ [ AS <refno> ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <iconname> is the name of the icon to be displayed on the dialog. If it is not the fully qualified name, the default directory for the icon is set by the ICON_DIRECTORY Customization Variable. This variable can be viewed or modified by requesting System Configuration from the Utilities Pull Down Menu on any Phone Book. The initial visibility state of an ICON_FIELD may be set by the VISIBLE or INVISIBLE keyword. The default is VISIBLE. The visibility state may be changed after dialog creation by using the SHOW ICON_FIELD or HIDE ICON_FIELD Statements. The position of the ICON_FIELD is defined in the AT clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The position is relative to the top left corner of the DIALOG_WINDOW and refers to the top left of the ICON_FIELD. The AS clause allows a specific reference number to be assigned to the ICON_FIELD. If not specified, the reference number 1 is assigned to the first ICON_FIELD on the screen that doesn't have an AS clause, the number 2 is assigned to the second, 3 to the third and so on. If the contents of the AS clause is an identifier that has a numeric value of 0, the identifier will be set to the assigned reference number. ┌─────────────────────────┐ │ 12.19.7 LIST_BOX Clause │ └─────────────────────────┘ Purpose: A LIST_BOX is a rectangular box that contains a scrollable list of choices from which users can select one or multiple (MULTIPLE_SELECTION) choices from. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ LIST_BOX <text> │ │ [ VISIBLE | INVISIBLE ] │ │ [ ENABLED | DISABLED ] │ │ [ USING < sortstr> ] │ │ [ LINES ... , ... ] │ │ [ HORIZONTAL_SCROLL_BAR ] │ │ [ MULTIPLE_SELECTION ] │ │ [ SIZE <rowsize> , <colsize> ] │ │ [ ACTION <label> ] │ │ [ AT < rowpos> , <colpos> ] │ │ [ AS <refno> ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The initial visibility state of the LIST_BOX may be set by the VISIBLE or INVISIBLE keyword. The default is VISIBLE. The visibility state may be changed after dialog creation by using the SHOW LIST_BOX or HIDE LIST_BOX Statements. The initial selectability state of the LIST_BOX may be set by the ENABLED or DISABLED keyword. The default is ENABLED. The selectability state may be changed after dialog creation by using the ENABLE LIST_BOX or DISABLE LIST_BOX Statements. If a LIST_BOX is DISABLED the selection cannot be changed. The USING clause uses a subset of the SORT USING options. This allows you to explicitly specify the order items will be placed in the LIST_BOX. The valid options are 'T1' (ASCII collating sequence), 'T2' (dictionary order i.e. case insensitive), 'T3' (numeric), 'A' (ascending), and 'D' (descending). See the SORT Statement for more details. The initial contents of a LIST_BOX is set by the optional LINES (or LINE) clause. The LINES clause consists of 1 or more comma separated string expressions and or array ranges: ┌──────────────────────────────────────────────────────────────────────┐ │ LINES {string [ SELECTED ] } [, ...] │ │ {array [ FROM dim1 [ ,dim2 ] ...] │ │ [ TO dim1 [,dim2 ] ...] } │ └──────────────────────────────────────────────────────────────────────┘ The keyword SELECTED may be associated with a particular string specification to select that line. The SELECT and DESELECT Statements may be used after dialog creation to change the selection. The SELECTED_LINE Function may be used to determine which line or lines are selected. A horizontal scroll bar may be included in the LIST_BOX if the HORIZONTAL_SCROLL_BAR keyword is specified. By default only 1 item may be selected at a time. Multiple selections may be made if the MULTIPLE_SELECTION keyword is specified. The size of the LIST_BOX is defined in the SIZE clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The ACTION clause allows you to specify a <label> that will receive control after an element has been selected or deselected in the LIST BOX has been pressed. If the action is triggered, ACTION_WINDOW will be set to the window number specified in the CREATE DIALOG_WINDOW Statement, ACTION_ID will be set to the LIST BOX's reference number (see AS clause) and ACTION_TYPE will be set to 7. The ACTION will also be triggered if the MOUSE is Double Clicked over an element. In this case, ACTION_TYPE will be set to 8. The position of the LIST_BOX is defined in the AT clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The position is relative to the top left corner of the DIALOG_WINDOW and refers to the top left of the LIST_BOX. The AS clause allows a specific reference number to be assigned to the LIST_BOX. If not specified, the reference number 1 is assigned to the first LIST_BOX on the screen that doesn't have an AS clause, the number 2 is assigned to the second, 3 to the third and so on. If the contents of the AS clause is an identifier that has a numeric value of 0, the identifier will be set to the assigned reference number. ┌──────────────────────────────────────┐ │ 12.19.8 MULTILINE_ENTRY_FIELD Clause │ └──────────────────────────────────────┘ Purpose: A MULTILINE_ENTRY_FIELD is a rectangular area of the dialog that displays multiple lines of text that the user can edit. Scroll bars appear if requested. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ MULTILINE_ENTRY_FIELD │ │ [ LINES <list-of-lines> ] │ │ [ VISIBLE | INVISIBLE ] │ │ [ ENABLED | DISAB LED ] │ │ [ TEXT_SIZE <maxchars> ] │ │ [ WORD_WRAP ] │ │ [ READ_ONLY ] │ │ [ HORIZONTAL_SCROLL_BAR ] │ │ [ VERTICAL_SCROLL_BAR ] │ │ [ BORDER 0 | 1 ] │ │ [ SIZE <rowsize> , <colsize> ] │ │ [ AT < rowpos> , <colpos> ] │ │ [ ACTION <label ] │ │ [ AS <refno> ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks The initial contents is set by the optional LINES (or LINE) clause. The LINES clause consists of 1 or more comma separated string expressions and or array ranges: ┌──────────────────────────────────────────────────────────────────────┐ │ LINES {string } [, ...] │ │ {array [ FROM dim1 [ ,dim2 ] ...] │ │ [ TO dim1 [,dim2 ] ...] } │ └──────────────────────────────────────────────────────────────────────┘ The maximum number of characters that may be entered into a MULTILINE_ENTRY_FIELD is determined by the TEXT_SIZE clause. By default, TEXT_SIZE is unlimited. The initial visibility state of the field may be set by the VISIBLE or INVISIBLE keyword. The default is VISIBLE. The visibility state may be changed after dialog creation by using the SHOW MULTILINE_ENTRY_FIELD or HIDE MULTILINE_ENTRY_FIELD Statements. The initial selectability state of the MULTILINE_ENTRY_FIELD may be set by the ENABLED or DISABLED keyword. The default is ENABLED. The selectability state may be changed after dialog creation by using the ENABLE MULTILINE_ENTRY_FIELD or DISABLE MULTILINE_ENTRY_FIELD Statements. If a MULTILINE_ENTRY_FIELD is DISABLED it cannot be modified by the user or accessed from the keyboard or by the mouse. If the READ_ONLY keyword is specified, the ENTRY_FIELD cannot be modified by the user. This feature can be used to create scrollable text windows for tutorial or help information. The BORDER clause defines the type of border that is drawn around the MULTILINE_ENTRY_FIELD. 0 specifies no border and 1 specifies a thin line border. The default is BORDER 1. Horizontal and or vertical scroll bars may be included by specifying the HORIZONTAL_SCROLL_BAR and VERTICAL_SCROLL_BAR keywords. If the HORIZONTAL_SCROLL_BAR keyword is not specified, the characters that can be entered onto a line in the field is limited by the field width. If it is included, the number of characters that can be entered on a single line is limited only by TEXT_SIZE. If the VERTICAL_SCROLL_BAR keyword is not specified, the number of lines that can be entered is limited by the field height. If included, the number of lines that can be entered is limited only by TEXT_SIZE. The size of the MULTILINE_ENTRY_FIELD is defined in the SIZE clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The standard height for a multiline entry field is 8 DIALOG_ROWS per text row displayed. The position of the MULTILINE_ENTRY_FIELD is defined in the AT clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The position is Relative to the top left corner of the DIALOG_WINDOW. The position refers to top left of field's text, not its border. The ACTION clause allows you to specify a <label> that will receive control after a field has been modified and the keyboard focus has moved to another field. If the action is triggered, ACTION_WINDOW will be set to the window number specified in the CREATE DIALOG_WINDOW Statement, ACTION_ID will be set to the MULTILINE_ENTRY_FIELD's reference number (see AS clause) and ACTION_TYPE will be set to 6 (field changed). The AS clause allows a specific reference number to be assigned to the MULTILINE_ENTRY_FIELD. If not specified, the reference number 1 is assigned to the first MULTILINE_ENTRY_FIELD on the screen that doesn't have an AS clause, the number 2 is assigned to the second, 3 to the third and so on. If the contents of the AS clause is an identifier that has a numeric value of 0, the identifier will be set to the assigned reference number. The contents of a MULTILINE_ENTRY_FIELD may be determined using the TEXT_OF Function. ┌────────────────────────────┐ │ 12.19.9 PUSH_BUTTON Clause │ └────────────────────────────┘ Purpose: A PUSH_BUTTON is a box that contains a string. When a PUSH_BUTTON is pushed, by clicking the mouse on it or by pressing the spacebar when it is active, an action is triggered. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ PUSH_BUTTON <text> │ │ [ VISIBLE | INVISIBLE ] │ │ [ ENABLED | DISABLED ] │ │ [ BORDER 0 | 1 ] │ │ [ ENTER ] │ │ [ ESCAPE ] │ │ [ SIZE <rowsize> , <colsize> ] │ │ [ AT <rowpos> , <colpos> ] │ │ [ ACTION <label> ] │ │ [ AS <refno> ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <text> sets the initial text of the PUSH_BUTTON. It is required. It may be changed after dialog creation by using the SET PUSH_BUTTON Statement. The initial visibility state of the button may be set by the VISIBLE or INVISIBLE keyword. The default is VISIBLE. The visibility state may be changed after dialog creation by using the SHOW PUSH_BUTTON or HIDE PUSH_BUTTON Statements. The initial selectability state of the PUSH_BUTTON may be set by the ENABLED or DISABLED keyword. The default is ENABLED. The selectability state may be changed after dialog creation by using the ENABLE PUSH_BUTTON or DISABLE PUSH_BUTTON Statements. If a PUSH_BUTTON is DISABLED it is displayed in halftone and cannot be pushed. The BORDER clause defines the type of border that is drawn around the PUSH_BUTTON. 0 specifies no border. The default is BORDER 1. The ENTER keyword causes the PUSH_BUTTON's ACTION to be triggered if the ENTER key is pressed and focus is on a non PUSH_BUTTON control. This is normally used to establish a default PUSH_BUTTON. There should only be one PUSH_BUTTON with the ENTER keyword per dialog. The ESCAPE keyword causes the PUSH_BUTTON's ACTION to be triggered if the ESCAPE key is pressed. This is normally used in association with a "Cancel" PUSH_BUTTON. There should only by one PUSH_BUTTON with the ESCAPE keyword per dialog. The size of the PUSH_BUTTON is defined in the SIZE clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. If no SIZE clause is specified the SIZE will default to a size sufficient to display <text>. The standard height for a PUSH_BUTTON is 13 DIALOG_ROWS. The width is dependant on the contents of <text>. The position of the PUSH_BUTTON is defined in the AT clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The position is relative to the top left corner of the DIALOG_WINDOW and specifies the top left corner of the PUSH_BUTTON. The ACTION clause allows you to specify a <label> that will receive control after a PUSH_BUTTON has been pressed. If the action is triggered, ACTION_WINDOW will be set to the window number specified in the CREATE DIALOG_WINDOW statement, ACTION_ID will be set to the PUSH_BUTTON's reference number (see AS clause) and ACTION_TYPE will be set to 5 (button pressed). If no ACTION clause is specified in the PUSH_BUTTON definition, the ACTION associated with the dialog window will be triggered, if any. When a PUSH_BUTTON ACTION is triggered, the DIALOG_WINDOW is disabled until a RESUME ACTION Statement is executed (You can issue an ENABLE DIALOG_WINDOW Statement to enable the window prior to the RESUME). The AS clause allows a specific reference number to be assigned to the PUSH_BUTTON. If not specified, the reference number 1 is assigned to the first PUSH_BUTTON on the screen that doesn't have an AS clause, the number 2 is assigned to the second, 3 to the third and so on. If the contents of the AS clause is an identifier that has a numeric value of 0, the identifier will be set to the assigned reference number. The contents of a PUSH_BUTTON may be determined using the TEXT_OF Function. ┌──────────────────────────────┐ │ 12.19.10 RADIO_BUTTON Clause │ └──────────────────────────────┘ Purpose: A RADIO_BUTTON is a small circle with associated text to the right. It is used to select a single item from a list. When clicked it checks itself and automatically unchecks all other radio buttons with the same group (a group is a set of contiguous RADIO_BUTTONS). Format: ┌──────────────────────────────────────────────────────────────────────┐ │ RADIO_BUTTON <text> │ │ [ VISIBLE | INVISIBLE ] │ │ [ ENABLED | DISABLED ] │ │ [ CHECKED | UNCHECKED ] │ │ [ SIZE <rowsize> , <colsize> ] │ │ [ AT <rowpos> , <colpos> ] │ │ [ ACTION <label> ] │ │ [ AS <refno> ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <text> sets the initial text of the RADIO_BUTTON. It is required. It may be changed after dialog create by using the SET RADIO_BUTTON Statement. The initial visibility state of the button may be set by the VISIBLE or INVISIBLE keyword. The default is VISIBLE. The visibility state may be changed after dialog creation by using the SHOW RADIO_BUTTON or HIDE RADIO_BUTTON Statements. The initial selectability state of the RADIO_BUTTON may be set by the ENABLED or DISABLED keyword. The default is ENABLED. The selectability state may be changed after dialog creation by using the ENABLE RADIO_BUTTON or DISABLE RADIO_BUTTON Statements. If a RADIO_BUTTON is DISABLED it is displayed in halftone and cannot be clicked. The initial checked state may be set by using the CHECK or UNCHECK keywords. The default is UNCHECKed. The CHECKed state may be changed after dialog creation by using the CHECK RADIO_BUTTON or UNCHECK RADIO_BUTTON Statements. The current check state may be determined by the IS_CHECKED Function. The size of the RADIO_BUTTON is defined in the SIZE clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. If no SIZE clause is specified the SIZE will default to the minimum size to display <text>. The standard height for a RADIO_BUTTON is 10 DIALOG_ROWS. The width is dependant on the contents of <text>. The position of the RADIO_BUTTON is defined in the AT clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The position is relative to the top left corner of the DIALOG_WINDOW and specifies the top left corner of the RADIO_BUTTON. The ACTION clause allows you to specify a <label> that will receive control after a RADIO_BUTTON has been pressed. If the action is triggered, ACTION_WINDOW will be set to the window number specified in the CREATE DIALOG_WINDOW statement, ACTION_ID will be set to the PUSH_BUTTON's reference number (see AS clause) and ACTION_TYPE will be set to 5 (button pressed). The AS clause allows a specific reference number to be assigned to the RADIO_BUTTON. If not specified, the reference number 1 is assigned to the first RADIO_BUTTON on the screen that doesn't have an AS clause, the number 2 is assigned to the second, 3 to the third and so on. If the contents of the AS clause is an identifier that has a numeric value of 0, the identifier will be set to the assigned reference number. The <text> associated with a RADIO_BUTTON may be determined using the TEXT_OF Function. ┌────────────────────────────┐ │ 12.19.11 TEXT_FIELD Clause │ └────────────────────────────┘ Purpose: The TEXT_FIELD clause describes text that appears within a DIALOG_WINDOW. It may be specified in the CREATE DIALOG_WINDOW or ADD TO DIALOG_WINDOW Statements. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ TEXT_FIELD <text> │ │ [ VISIBLE | INVISIBLE ] │ │ [ ENABLED | DISABLED ] │ │ [ ALIGN_TOP | ALIGN_VCENTER | ALIGN_BOTTOM ] │ │ [ ALIGN_LEFT | ALIGN_CENTER | ALIGN_RIGHT ] │ │ [ WORD_WRAP ] │ │ [ SIZE <rowsize> , <colsize> ] │ │ [ AT <rowpos> , <colpos> ] │ │ [ AS <refno> ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <text> sets the initial text of the TEXT_FIELD. It is required. It may be changed after dialog create by using the SET TEXT_FIELD Statement. The initial visibility state of the text may be set by the VISIBLE or INVISIBLE keyword. The default is VISIBLE. The visibility state may be changed after dialog creation by using the SHOW TEXT_FIELD or HIDE TEXT_FIELD Statements. The initial selectability state of the TEXT_FIELD may be set by the ENABLED or DISABLED keyword. The default is ENABLED. The selectability state may be changed after dialog creation by using the ENABLE TEXT_FIELD or DISABLE TEXT_FIELD Statements. If a TEXT_FIELD is DISABLED it is displayed in halftone. The size of the TEXT_FIELD is defined in the SIZE clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. If no SIZE clause is specified the size will default to the minimum size needed to display <text>. The standard height for a single line of text is 8 DIALOG_ROWS. The width is dependant on the contents of <text>. For most uses the SIZE clause does not have to be specified. The position of the TEXT_FIELD is defined in the AT clause. The default units are DIALOG_ROWS and DIALOG_COLUMNS. The position is relative to the top left corner of the DIALOG_WINDOW. The text can be automatically aligned and justified within the TEXT_FIELD by specifying ALIGN_TOP, ALIGN_VCENTER, ALIGN_BOTTOM and/or ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT. The defaults are ALIGN_TOP and ALIGN_LEFT. Text can be automatically word-wrapped within a multiline TEXT_FIELD by including the WORD_WRAP keyword (only valid for ALIGN_TOP/ALIGN_LEFT fields). The AS clause allows a specific reference number to be assigned to the TEXT_FIELD. If not specified, the reference number 1 is assigned to the first TEXT_FIELD on the screen that doesn't have an AS clause, the number 2 is assigned to the second, 3 to the third and so on. If the contents of the AS clause is an identifier that has a numeric value of 0, the identifier will be set to the assigned reference number. The contents of a TEXT_FIELD may be determined using the TEXT_OF Function. 12.20 CREATE SESSION_MONITOR Statement Purpose: Creates a SESSION_MONITOR object definition. A SESSION_MONITOR object can be used to simultaneously monitor multiple host sessions for the occurrence of text strings, keystrokes, and other events. These events will trigger ACTIONs that cause the AUTOPILOT script to interrupt the statement being executed and begin execution at a defined routine. CREATE SESSION_MONITOR is used to define an object that monitors a host session for the occurrence of one or more of the following events: TEXT_WATCH Looks for the occurrence of a text string on host screen. HOST_KEY_WATCH Waits for the occurrence of a keystroke entered in the host session. When you define an event, you can specify a routine to receive control when they occur. You can also define a default routine that receives control when an event occurs that does not have a specific routine defined for it. OPEN and CLOSE are used to start and stop session monitors defined with the CREATE SESSION_MONITOR statement. Multiple monitors can be OPEN'd at one time (only one per session id). Monitors can be OPEN'd and CLOSE'd as many times as desired. If you wish to eliminate a monitor completely (and thus free its id), use the DESTROY SESSION_MONITOR statement. When a monitored event occurs, an action is generated and the appropriate AUTOPILOT routine receives control. At this point the session monitor is temporarily disabled (to avoid recursive events). When the routine wishes to return to the mainline logic of the AUTOPILOT program it utilizes the RESUME ACTION statement. The RESUME action statement automatically reenables the session monitor. You may issue an ENABLE prior to the RESUME to enable the session monitor. Also, if you issue a DISABLE prior to the RESUME, the resume will not enable the monitor. When a TEXT_WATCH event is generated, if the routine does not do something to clear the condition (i.e. change the screen so that the text is no longer there), the routine should disable the text watch prior to doing a resume so that another action is not immediately generated. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ CREATE SESSION_MONITOR id │ │ [ SESSION sessid ] │ │ [ ACTION label ] │ │ [ ENABLED|DISABLED ] │ │ [ TEXT_WATCH clause ]... │ │ [ HOST_KEY_WATCH clause ] ... │ │ END_CREATE │ └──────────────────────────────────────────────────────────────────────┘ Remarks: id may be either: 1. An integer expression such that 0 < id < 32. 2. An identifier set to zero. If this is the case, the identifier will be set to a monitor id automatically assigned to this monitor. sessid is the single letter EHLLAPI session-id or the 2 to 8 character EHLLAPI session-name of the session to monitor. label is a label in your AUTOPILOT program that receives control if a monitor item (ex: TEXT_WATCH) with no ACTION clause of its own is triggered. ENABLED and DISABLED may used to specify the initial state of a SESSION_MONITOR. The TEXT_WATCH clause defines a monitor item that is triggered when a particular text string appears on the host. It is documented below. There may be more than one TEXT_WATCH in a single SESSION_MONITOR. The HOST_KEY_WATCH clause defines a monitor item that is triggered when a key is pressed in the host session. It is documented below. There may be more than one HOST_KEY_WATCH in a single SESSION_MONITOR. A SESSION_MONITOR is not active until it is opened. See OPEN SESSION_MONITOR. Examples: CREATE SESSION_MONITOR sessmon TEXT_WATCH "HOLDING" AT 24,60 ACTION do_holding TEXT_WATCH "LOGOFF AT ??:??:??" ACTION did_logoff HOST_KEY_WATCH "PF3" ACTION did_PF3 END_CREATE ┌───────────────────────────┐ │ 12.20.1 TEXT_WATCH Clause │ └───────────────────────────┘ Purpose: Defines a monitor item that is triggered when a particular text string appears on the host. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ TEXT_WATCH string │ │ [ AT row,col ] | [ [ FROM row,col ] [ TO row,col ] ] │ │ [ ENABLED|DISABLED ] │ │ [ ACTION label ] │ │ [ AS id ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The occurrence of string on the host triggers an action. string can do a pattern search in the same manner as the WAIT statement. AT/FROM/TO can be used to limit the area on the host screen that is searched. ENABLED and DISABLED may used to specify the initial state of a text watch item. label is a label in your AUTOPILOT program that receives control if string is found on the host screen. id may be either: 1. An integer expression such that 0 < id < 10000. 2. An identifier set to zero. If this is the case, the identifier will be set to an id automatically assigned to this item. ┌───────────────────────────────┐ │ 12.20.2 HOST_KEY_WATCH Clause │ └───────────────────────────────┘ Purpose: Defines a monitor item that is triggered when a particular key is pressed in a host session. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ HOST_KEY_WATCH key │ │ [ ENABLED|DISABLED ] │ │ [ ACTION label ] │ │ [ AS id ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: When key is pressed in the host session an action is triggered. key may be one of the following: 1. One of the AUTOPILOT defined key names such as PF1 or ENTER. 2. A string that is equal to one of the AUTOPILOT defined key names or one of the names in the Associated Host Key field in the keyboard definition for a particular keystroke. For example: PF1, ENTER, KEYPAD_0. 3. A single character string such as "A" or "B". 4. An HLLAPI mnemonic such as "@Aa" (ALT+A) or "@S1" for Shift+F1. For TalkThru sessions, a key name is defined via its entry in the session's keyboard definition (SETTINGS/KEYBOARD). This is the name that is used to both send and trap the key. A key is named first by the contents of the Associated Host Key field. This field contains a host protocol style name such as PF1, ENTER, or DELETE_LINE. If this Associated Host Key field is empty, the key cannot be trapped. For example to intercept a key that is defined as ... PC Key Host Key Assigned Action ALT,1 PF1 ESC,1,CR you would use PF1 (not "@A1"). If the key was defined without a host key name as ... PC Key Host Key Assigned Action ALT,1 ESC,1,CR you would not be able to intercept it. If a key is not defined at all, you cannot trap it unless it is a single character in combination with shift/alt/ctrl, such as alt+a. You could not intercept a key such AS <F1> or <ENTER> unless it was defined. To intercept this type of undefined keys, use its ASCII or HLLAPI mnemonic value in a string. For example use "@Aa" for <alt+a>. If you wish to intercept a key, its generally best to define it and use a host key name. You can also use the UNASSIGNED command if you don't want the key to actually send anything when pressed. For example the following key definition could be used to allow an AUTOPILOT program to be notified when SHIFT+F1 was pressed: PC Key Host Key Assigned Action SHIFT,F1 UK1 UNASSIGNED The HOST_KEY_WATCH clause used would look something like this: HOST_KEY_WATCH UK1 ACTION sf1_pressed The Host Key name UK1 was chosen rather arbitrarily--a host key name is really just a label that AUTOPILOT (and HLLAPI) use to refer to a key--it has no other significance. When a key is intercepted, it is NOT sent to the host. If you wish to send it, you should do so in your ACTION routine. AUTOPILOT uses the Keystroke Intercept facility of HLLAPI to monitor keystrokes. When using AUTOPILOT to monitor keystrokes in a 3rd party program (such as Communications Manager), restrictions on undefined keystrokes may differ. ENABLED and DISABLED may be used to specify the initial state of a key watch item. label is a label in your AUTOPILOT program that receives control the key is pressed. id may be either: 1. An integer expression such that 0 id 10000. 2. An identifier set to zero. If this is the case, the identifier will be set to an id automatically assigned See Also: CREATE/DESTROY OPEN/CLOSE ENABLE/DISABLE ADD/DELETE SET TEXT_OF IS_DISABLED 12.21 DDE_EXECUTE Statement (Client) Purpose: Sends a command to a DDE server. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DDE_EXECUTE TOPIC(id) [ IN DDE_LINK(linkid ) ] │ │ command │ │ [ ,command... ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement instructs the DDE server to execute the command specified by command. A server application will document the commands that it will respond to. The IN DDE_LINK clause in required only if there is more than one DDE_LINK defined and it is not the current default. Examples: DDE_EXECUTE TOPIC(1) "[NEW(1)]" 12.22 DDE_POKE Statement (Client) Purpose: Sends unsolicited data to a DDE server. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DDE_POKE TOPIC(id) [ IN DDE_LINK(linkid) ] │ │ itemname WITH value [, itemname WITH value... ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement sends the data, specified by value , to the DDE server. itemname is the name of the item which will receive the data in the server application. A server application will document the format of the itemname. The IN DDE_LINK clause is required only if there is more than one DDE_LINK defined and it is not the current default. Examples: DDE_POKE TOPIC(1) "R1C1" WITH "123.50" 12.23 DDE_REQUEST Statement (Client) Purpose: Receives data from a DDE server. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DDE_REQUEST TOPIC(id) [ IN DDE_LINK(linkid) ] │ │ itemname INTO variable [ ,itemname INTO variable ... ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement receives data from the DDE server item itemname. The INTO variable clause specifies the AUTOPILOT variable that will receive the data. A server application will document the format of the item name. The IN DDE_LINK clause in required only if there is more than one DDE_LINK defined and it is not the current default. Examples: DDE_REQUEST TOPIC (1) "R1C1" INTO myvar 12.24 DDE_UPDATE Statement (Server) Purpose: Update the value of a server's EXPORT_ITEM entry. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DDE_UPDATE EXPORT_ITEM(id) [ IN DDE_LINK(linkid) ] │ │ WITH value │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement updates the value of a server's EXPORT_ITEM entry. The data will be sent to each client that has established a HOT_LINK with this item. Notification will be sent to each client that has established a WARM_LINK with this item. The data will also be used to respond to subsequent REQUEST transactions from clients. The IN DDE_LINK clause is required only if there is more than one DDE_LINK and it is not the current default. Examples: DDE_UPDATE EXPORT_ITEM(1) WITH "123.50" 12.25 DECLARE FUNCTION Statement Purpose: This statement is used to support the ability to call functions available in Dynamic Link Libraries (DLLs). Before using this function, refer to the section, Calling DLL Functions Directly in the chapter, AUTOPILOT Statements By Category for more information on how this is used. Before a DLL function can be called from AUTOPILOT it must be declared. Declaring a function provides the necessary information to allow AUTOPILOT to call the function. Once declared, DLL functions can be used exactly like other functions in a script. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DECLARE FUNCTION function-name[ (parameter-list) ] │ │ LIBRARY_NAME libname │ │ [ FUNCTION_NAME procname ] │ │ [ RETURN_TYPE type ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: function-name is the name of the function as it will be referenced in the script. The name follows the same naming rules as that of any script identifier (first letter alphabetic, first eight characters significant). parameter-list specifies the number and data type of parameters that the function uses. If the function does not need any parameters, the clause does not need to be specified. The syntax for a parameter-list is: ( iden-1 [ AS type ] , iden-2 [ AS type ] , ... iden-n [ AS type ] ) iden-n is simply any identifier name. It serves no purpose other than to indicate the presence of a required function parameter. type is a string expression that specifies the data format of the parameter. Unlike AUTOPILOT functions, DLL functions require parmaters to be in a specific format. Parameter data types will be discussed below under Parameter Data Types. LIBRARY_NAME libname specifies the name of the DLL library where the function resides. It is required. FUNCTION_NAME procname specifies the name of the function as it appears in the DLL. It is optional and defaults to the first 8 characters of function-name. RETURN_TYPE type specifies the data type of the value that function returns. It is optional. If the DECLARE FUNCTION Statement is successful, return_code is set to zero. If the function or DLL could not be loaded, return_code is set to a non-zero value that corresponds to the OS/2 DOS error codes. Parameter Data Types: Normally, in AUTOPILOT, you do not have to be concerned with the internal data format of an identifier or expression -- AUTOPILOT will convert the value to the correct format as needed. However, a DLL function is written in a language such as C or Pascal. These languages require that parameters match the data type expected by the function being called. The AS type Clause in the parameter list specification tells AUTOPILOT what type of format is expected by the DLL function. type is a string expression that describes the data format. The following table relates C data types with the corresponding AUTOPILOT type: 'C' type AUTOPILOT type ────────────────── ───────────────────── int (16 or 32 bit) "int" short (16 bit) "short" long (32 bit) "long" unsigned short "ushort" unsigned long "ulong" float Unsupported double Unsupported char * "string" or "pstring" int * "pint" short * "pshort" long * "plong" unsigned short * "pushort" unsigned long * <%4><T>"pulong<%0>" If a type is not specified, it defaults to "int". When calling a function, the parameter may be an expression such as 'x + 5' if the parameter type is not a 'pointer type' ("int", "short" "long", "ushort", "ulong", "string"). If the parameter type is a 'pointer type' ("pstring", "pint", "pshort", "plong", "pushort", "pulong") the parameter must be a single identifier. AUTOPILOT will handle all the necessary conversions. "string" and "pstring" both correspond to the C data type of char *. Use "string" if the parameter is not modified (or if you are not interested in retaining the value of modified data). By using "string" you can specify the parameter as an expression such as "Hello World" or (x+5)/7. Use "pstring" if the function will modify the data and if you want to access this modified data. When you use "pstring" the parameter in the function call must be a single identifier. When using "string" or "pstring" as a parameter type you MUST make sure that data returned in the string does not exceed the length of the original string. You can use the STR_REPLICATE Function to 'allocate' a string of the desired length. Note that 'int' is 32 bits for OS/2. More information on Rules For Specifying Functions are listed in the section, Calling DLL Functions Directly in the chapter, AUTOPILOT Statements By Category. Return Data Types: All functions are assumed to return a value. By default this value is assumed to be an 'int' (see Parameter Data Types above). If the function returns something other than an 'int', the RETURN_TYPE Clause in the DECLARE FUNCTION Statement should be specified with the appropriate type. A function may return a value in any of the formats listed in Parameter Data Types except for 'string' and 'pstring'. If a function wishes to return string data it must do so as a function parameter not as a return value. See Also: WINDOW HANDLE 12.26 DESELECT Statement Purpose: The DESELECT Statement allows the script to deselect a line from within a LIST_BOX or COMBINATION_BOX dialog control. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DESELECT {LIST_BOX(id) } │ │ {COMBINATION_BOX(id) } │ │ [ IN DIALOG_WINDOW (winid) ] │ │ LINE <num> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: If an item is DESELECTed, it's number WILL NOT be returned by the SELECTED_LINE Function. See Also: SELECT IS_CHECKED 12.27 DESTROY Statement Purpose: Destroys AUTOPILOT window objects, session monitors and DDE_LINK objects. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DESTROY DIALOG_WINDOW <window-number> │ │ │ │ DESTROY TEXT_WINDOW <window-number> │ │ │ │ DESTROY SESSION_MONITOR (monitorid) │ │ │ │ DESTROY DDE_LINK(linkid ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Removes a dialog, text window, session monitor, or DDE_LINK created using the CREATE Statement. Example: destroy DIALOG_WINDOW my_window DESTROY DDE_LINK(1) See Also: CREATE 12.28 DIAL Statement Purpose: Dials a TalkThru asynchronous session. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DIAL │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The DIAL Statement causes TalkThru to perform the dial sequence as specified in the Phone Book Entry Definition (these can be modified by requesting Connection from any Settings pull down menu). If Connection Type is specified as Auto, DIAL dials the number that is specified. If the Connection Type is Direct, only a physical connection is made with no dial sequence. This statement is valid only during asynch communications and, as with all communications activities, a valid CONNECT must have been previously issued. Example: DIAL This example would dial the telephone number specified in the Phone Book Entry Definition. See Also: HANG_UP 12.29 DIM Statement Purpose: Defines an array. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DIM identifier (n1 [,n2 [,n3]]) [= <value>,<value> ...] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The DIM Statement is used to define an array variable. The n parameters are used to define the maximum size of the array, with as many as three dimensions supported. Array elements, by default, are initialized to zero. Arrays may be redimensioned by executing another DIM Statement. This also resets all of the array elements to zero. The array may be initialized to values other than zero by specifying an equal sign followed by a group of comma separated values. This first element in the array is set equal to the first value, the second element is set to the second value and so on. If the list of values ends before all the array elements are initialized, the remaining elements are set to zero. When multi-dimensional arrays are initialized, the rightmost subscript is varied fastest. Examples: DIM A(10) SET i = 1 WHILE i <= 10 SET A(i) = "Element "&i SET i = i + 1 END_WHILE DIM array(3) SET array(1) = "ELEMENT 1" SET array(2) = "ELEMENT 2" SET array(3) = "ELEMENT 3" DIM array(3) = "ELEMENT 1" , "ELEMENT 2" , "ELEMENT 3" See Also: SET 12.30 DIR Statement Purpose: Provides access to directory information. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DIR {<fname>} [INTO <identifier>] [USING<attr>] │ │ { NEXT } [AS <format>] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The DIR Statement searches a directory for entries that match the specified file name or file name pattern. The DIR <fname> format is the minimum required to execute DIR. By specifying a fully qualified <fname>, this simple form can be used to determine a files existence (by testing return_code - 0 = File Not Found 1 = File Found) without identifying a target identifier to contain the name. If the INTO <identifier> clause is used in the first execution of DIR, then successive executions of the DIR NEXT format locates additional matching files. The number of matching files returned can be determined by examining RETURN_CODE. Examples: <fname>is a string specifying the drive, path, and name of the desired file. The drive and path can be omitted, in which case the current directory will be searched. The "*" and "?" characters may be used for pattern matching in the name portion. INTO <identifier> refers to the variable that will receive the results of the search. If it is not an array, it will be set to the file name of the matching file. In the example DIR "C:\*.*" INTO table the identifier table would be set to the first matching file name, say "COMMAND.COM". If the next statement was: DIR NEXT INTO table the identifier table would be set to the next matching file which may be "CONFIG.SYS". If the identifier is a 1 dimensional array, each element in the array (up to the number of matches) will be set to the file name of a matching file. In the example DIM table(3) DIR "C:\*.*" INTO table the array table might be set as follows: table(1) = COMMAND.COM table(2) = CONFIG.SYS table(3) = AUTOEXEC.BAT If the next statement was DIR NEXT INTO table the array table would be filled with the next 3 matching files. If the identifier is a 2 dimensional array, additional file information is returned. For the purposes of this explanation, the second dimension of the array is referred to as the number of columns. To obtain more than just file name information, the array would be defined as: DIM table(x,y) where: <x> is the maximum number of file names to be obtained and y is a number from 1 to 4 indicating the number of columns of information desired. The columns returned by the DIR Statement are set as follows (up to the number of columns requested): Column 1 -- File Name Column 2 -- File Attribute Column 3 -- File Size Column 4 -- File Time File Attribute refers to the type of file returned. See the USING option specified below. File Time is returned as a numeric value that represents the files DOS date and time stamp. It can be converted to a string by the STR_DATE and STR_TIME functions. The USING attr argument specifies which file types are to be included in the search. It is not valid in the DIR NEXT format. The attr is an integer value with bits set as follows: Bit 1 -- Include Hidden Files Bit 2 -- Include System Files Bit 3 -- Find Only the Volume Label Bit 4 -- Include Directory Files By default, the search will include only Normal Files (attr = 0). The following example would return DIRECTORY entries. DIR "C:\*.*" INTO dirname USING ^h10 NOTE: The file TT_DIR.INC sets identifier names to the bit settings necessary for the DIR Statement. INCLUDing TT_DIR.INC will greatly facilitate effective use if DIR. TT_DIR.INC can be found in the directory identified by the SCRIPT_DIRECTORY parameter in the TALKTHRU.DEF Customization File. The AS <format> option may be used to specify alternate directory formats. Normally, the DIR Statement returns the file name in the format NNNNNNNN.EEE. <format> is specified as an integer value, each value representing a different format type. The available formats can best be presented as an example. Assume the DIR Statement found the files TALKTHRU.BAT, 512 bytes created on 6-1-86 at 2:10 A.M., and DOC.WP, 15800 bytes created on 12-15-86 at 12:25 P.M.. The AS <format> option would operate as follows: position =>> 1 2 3 0 0 0 <format> 0 TALKTHRU.BAT DOC.WP 1 TALKTHRU BAT DOC WP 2 TALKTHRU BAT 6-01-86 2:10a DOC WP 12-15-86 12:25p 3 TALKTHRU BAT 512 6-01-86 2:10a DOC WP 15800 12-15-86 12:25p NOTE: AS 0 is the default format and is used if the AS option is not specified. Format 2 is the same format as displayed by TalkThru in file selection panels, and format 3 is the same format as displayed by the DOS DIR command. See Also: DIM 12.31 DISABLE Statement Purpose: The DISABLE statement allows the script to change the selectability state of a window, menu item, dialog item or session monitor. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DISABLE {TEXT_WINDOW(winid) } │ │ {DIALOG_WINDOW(winid) } │ │ │ │ DISABLE ACTION_BAR_MENU [ IN DIALOG_WINDOW (winid) ] │ │ [ IN TEXT_WINDOW(WINID) ] │ │ │ │ DISABLE {PULLDOWN(id) } [ IN DIALOG_WINDOW(winid) ] │ │ {CHOICE(id) } [ IN TEXT_WINDOW(winid) ] │ │ │ │ DISABLE {TEXT_FIELD(id) } │ │ {ENTRY_FIELD(id) } │ │ {PUSH_BUTTON(id) } │ │ {RADIO_BUTTON(id) } │ │ {CHECK_BOX(id) } │ │ {LIST_BOX (id) } │ │ {COMBINATION_BOX(id) } │ │ {GROUP_BOX(id) } │ │ {ICON_FIELD(id) } │ │ {MULTILINE_ENTRY_FIELD(id) } │ │ [ IN DIALOG_WINDOW(winid) ] │ │ │ │ DISABLE SESSION_MONITOR(monitorid) │ │ │ │ DISABLE TEXT_WATCH(id) [ IN SESSION_MONITOR(monitorid) ] │ │ │ │ DISABLE HOST_KEY_WATCH(id) │ │ [ IN SESSION_MONITOR(monitorid) ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: When a dialog or text window item is DISABLEd, it cannot by selected or modified by the user. menu items and dialog controls are also usually displayed in halftone when DISABLEd. For more information on text windows, refer to the Appendix, Migration From DOS. When a session monitor is disabled, no monitoring occurs and no actions will be generated for any item within the monitor. When a watch is disabled, no monitoring occurs and no actions will be generated for that specific item. Other monitoring (if any) still occurs. If the IN SESSION_MONITOR clause is not specified, the current session monitor will be used (the last monitor created or one set by the SET CURRENT_MONITOR statement). See Also: ENABLE IS_DISABLED 12.32 DISABLE Statement (DDE Client) Purpose: Changes the state of a Client's DDE item from ENABLED to DISABLED. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ Format 1: │ │ │ │ DISABLE HOT_LINK(id ) [ IN DDE_LINK(linkid) ] │ │ DISABLE WARM_LINK(id ) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 2: │ │ │ │ DISABLE TOPIC(id ) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 3: │ │ │ │ DISABLE DDE_LINK(linkid) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Format 1 changes the state of a HOT_LINK or WARM_LINK item to DISABLED. If the TOPIC the link is associated with is opened, an unadvise transaction will be generated for the link item. When the value of the item changes an ACTION will NOT be triggered and the associated variable (HOT_LINK items only) will NOT be updated. Format 2 changes the state of a TOPIC to DISABLED. If the TOPIC the link is associated with is opened, an unadvise transaction will be generated for all active HOT_LINK and WARM_LINK link items. In addition, a DISABLED TOPIC's ACTION routine will not receive any ACTIONs. Format 3 changes the state of a DDE_LINK to DISABLED. An unadvise transaction will be generated for all active HOT_LINK and WARM_LINK items that are associated with an opened TOPIC. In addition, a DISABLED DDE_LINK's ACTION routine will not receive any ACTIONS. Examples: DISABLE HOT_LINK(2) IN DDE_LINK(1) DISABLE TOPIC(1) DISABLE DDE_LINK(1) 12.33 DISABLE Statement (DDE Server) Purpose: Changes the state of a Server's DDE item from ENABLED to DISABLED. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ Format 1: │ │ │ │ DISABLE EXPORT_ITEM(id) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 2: │ │ │ │ DISABLE EXPORT_COMMAND(id) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 3: │ │ │ │ DISABLE TOPIC(id) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 4: │ │ │ │ DISABLE DDE_LINK(linkid) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Format 1 changes the state of an EXPORT_ITEM entry to DISABLED. The server script will NOT accept poke, request, and advise transactions for the EXPORT_ITEM entry. Format 2 changes the state of an EXPORT_COMMAND entry to DISABLED. The server script will NOT accept execute transactions for the EXPORT_COMMAND entry. Format 3 changes the state of a TOPIC to DISABLED. The server script will NOT accept poke, request, and advise transactions for any of the TOPIC's EXPORT_ITEM entries or execute transaction for any of the TOPIC's EXPORT_COMMAND entries. In addition, clients will be NOT allowed to initiate a conversation with the TOPIC. Format 4 changes the state of a DDE_LINK to DISABLED. The server script will NOT accept poke, request, and advise transactions for all of the DDE_LINK's EXPORT_ITEM entries or execute transactions for any of the DDE_LINK's EXPORT_COMMAND entries. In addition, clients will NOT be allowed to initiate conversations with all of the DDE_LINKs TOPICs. Examples: DISABLE EXPORT_ITEM(2) IN DDE_LINK(1) DISABLE TOPIC(1) DISABLE DDE_LINK(1) 12.34 DISCONNECT Statement Purpose: Drops the logical connection between the script and the last connected session. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DISCONNECT │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The DISCONNECT Statement will disconnect the currently CONNECT'ed session from the script. AUTOPILOT will automatically DISCONNECT upon exiting. It is not necessary to DISCONNECT when switching from one session to another while within the script. DISCONNECT DOES NOT hang up the phone on a TalkThru session, nor does it make the session GO AWAY. See Also: CONNECT 12.35 DISK_INFO Function Purpose: To return various disk related information. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ DISK_INFO(<drive>,<request>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <drive> a single character indicating the letter of the drive to be checked (i.e. A, B, C, D) <request> the number 1 or the number 2 indicating the request type from the table below: request Returns 0 - <drive> is ready 1 1 - <drive> letter is invalid 2 - <drive> is not ready 2 the amount of free disk space on <drive> in bytes See Also: DIR STR_CURRDIR STR_CURRDISK 12.36 ENABLE Statement Purpose: The ENABLE Statement allows the script to change the selectability state of a window, menu item, dialog item, or session monitor. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ENABLE {TEXT_WINDOW}(winid) } │ │ {DIALOG_WINDOW(winid) } │ │ │ │ ENABLE ACTION_BAR_MENU [ IN DIALOG_WINDOW(winid) ] │ │ [ IN TEXT_WINDOW (winid) ] │ │ │ │ ENABLE {PULLDOWN (id) } [ IN DIALOG_WINDOW (winid) ] │ │ {CHOICE(id) } [ IN TEXT_WINDOW(winid) ] │ │ │ │ ENABLE {TEXT_FIELD(id) } │ │ {ENTRY_FIELD(id) } │ │ {PUSH_BUTTON(id) } │ │ {RADIO_BUTTON(id) } │ │ {CHECK_BOX(id) } │ │ {LIST_BOX(id) } │ │ {COMBINATION_BOX(id) } │ │ {GROUP_BOX(id) } │ │ {ICON_FIELD(id) } │ │ {MULTILINE_ENTRY_FIELD(id) } │ │ [ IN DIALOG_WINDOW(winid) ] │ │ │ │ ENABLE SESSION_MONITOR(monitorid) │ │ │ │ ENABLE TEXT_WATCH(id) [ IN SESSION_MONITOR(monitorid) ] │ │ │ │ ENABLE HOST_KEY_WATCH(id) │ │ [ IN SESSION_MONITOR(monitorid) ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: When a dialog or text window item is ENABLEd, it can by selected and modified by the user. For more information on text windows, refer to the Appendix, Migration From DOS. If the IN SESSION_MONITOR clause is not specified, the current session monitor will be used (the last monitor created or one set by the SET CURRENT_MONITOR statement). See Also: DISABLE IS_DISABLED 12.37 ENABLE Statement (DDE Client) Purpose: Changes the state of a Client's DDE item from DISABLED to ENABLED. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ Format 1: │ │ │ │ ENABLE HOT_LINK(id) [ IN DDE_LINK(linkid) ] │ │ ENABLE WARM_LINK(id ) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 2: │ │ │ │ ENABLE TOPIC(id) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 3: │ │ │ │ ENABLE DDE_LINK(link id) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Format 1 changes the state of a HOT_LINK or WARM_LINK item to ENABLED. If the TOPIC the link is associated with is opened and enabled, an advise transaction will be generated for the link item. When the value of the item changes, an ACTION will be triggered and the associated variable (HOT_LINK items only) will be updated. Format 2 changes the state of a TOPIC to ENABLED. If the TOPIC the link is associated with is opened, an advise transaction will be generated for all enabled HOT_LINK and WARM_LINK link items. When the value of the link item changes, an ACTION will be triggered and the associated variable (HOT_LINK items only) will be updated. An ENABLED TOPIC also allows the TOPIC's ACTION routine to receive appropriate ACTIONs. Format 3 changes the state of a DDE_LINK to ENABLED. An advise transaction will be generated for all enabled HOT_LINK and WARM_LINK items that are associated with an opened enabled TOPIC. An ENABLED DDE_LINK also allows the DDE_LINK's ACTION routine to receive appropriate ACTIONs. Examples: ENABLE HOT_LINK(2) IN DDE_LINK(1) ENABLE TOPIC(1) ENABLE DDE_LINK(1) 12.38 ENABLE Statement (DDE Server) Purpose: Changes the state of a Server's DDE item from DISABLED to ENABLED. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ Format 1: │ │ │ │ ENABLE EXPORT_ITEM(id) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 2: │ │ │ │ ENABLE EXPORT_COMMAND(id) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 3: │ │ │ │ ENABLE TOPIC(id) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 4: │ │ │ │ ENABLE DDE_LINK(linkid) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Format 1 changes the state of an EXPORT_ITEM entry to ENABLED. If the TOPIC the link is associated with is opened and enabled, the server script will accept poke, request, and advise transactions for the EXPORT_ITEM entry. Format 2 changes the state of an EXPORT_COMMAND entry to ENABLED. If the TOPIC the link is associated with is opened and enabled, the server script will accept execute transactions for the EXPORT_COMMAND entry. Format 3 changes the state of a TOPIC to ENABLED. The server script will accept poke, request, and advise transactions for all of the TOPIC's enabled EXPORT_ITEM entries and execute transactions for all of the TOPIC's EXPORT_COMMAND entries. In addition, clients will be allowed to initiate a conversation with the TOPIC. Format 4 changes the state of a DDE_LINK to ENABLED. The server script will accept poke, request, and advise transactions for all of the DDE_LINK's enabled EXPORT_ITEM entries and execute transactions for all of the DDE_LINK's EXPORT_COMMAND entries. In addition, clients will be allowed to initiate conversations with all of the DDE_LINKs enabled TOPICs. Examples: ENABLE EXPORT_ITEM(2) IN DDE_LINK(1) ENABLE TOPIC(1) ENABLE DDE_LINK(1) 12.39 EOF Function Purpose: Tests for an end of file condition. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ EOF(<filenum>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: EOF returns 1 (true) if end of file has been reached on the specified <filenum>. A 0 (false) is returned if end of file has not been reached. Examples: OPEN "anyfile.ext" FOR INPUT AS filenum loop: READ LINE filenum var IF EOF(filenum) GOTO end DISPLAY var GOTO loop This example would read and display data from "anyfile.ext" until end of file is reached. See Also: CLOSE OPEN OPEN_FLAG READ WRITE 12.40 EXIT Statement Purpose: Terminates the running AUTOPILOT script. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ EXIT [ABORT] [KEEP] [<retcode>] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: [ABORT] causes termination of all AUTOPILOT processing irrespective of the execution level depth. [KEEP] may be used if performance dictates that it is desirable to keep a subroutine script resident in memory so as to eliminate the need to reload it when it is next invoked. <retcode> is a number that represents the return code of the script. It will be passed to the next highest level script as a return code. This return code may be examined within the calling script via RETURN_CODE [see the IF Statement] or by CMD files. If the return code is to be examined from within a BAT file it is recommended that the range be limited to 1 to 255. The keywords ABORT and KEEP may appear in any order. If <retcode> is specified it must be the last parameter. Examples: EXIT EXIT ABORT rcode EXIT KEEP The first example would exit the current script, returning to the calling script or program. A default return code of 0 would be returned. The second example would exit the script program and return to the calling program regardless of the level of the current script. The return code would be set to rcode. The third example would exit the script program and the terminal emulator that called it (if any). The return code would be set to 255. The last example would exit the script subroutine but keep it in memory. See Also: RETURN_CODE 12.41 FILE_ACCESS Function Purpose: To determine whether the specified file can be accessed in a specific "mode". Format: ┌──────────────────────────────────────────────────────────────────────┐ │ FILE_ACCESS(<filespec>,<mode>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <filespec> the fully qualified file specification of the file you wish to have checked <mode> the mode in which you wish to access the file. <mode> must be specified as a number with one of the following values: 0 - check for existence only 2 - check for write permission 4 - check for read permission 6 - check for read and write permission The value returned will be one of the following: 0 - file exists and is accessible in the given mode 1 - file does not exist 2 - file exists but is not accessible in the given mode Examples: set t_status = FILE_ACCESS("C:\AUTOEXEC.BAT",2) if t_status = 0 goto do_open This example would test whether an AUTOEXEC.BAT file was available on the "C" drive and whether it can be written to. If the response is 0, a branch will occur to process the file. See Also: CLOSE DIR DISK_INFO OPEN 12.42 FILE_TRANSFER_STATUS Function Purpose: The FILE_TRANSFER_STATUS Function is used with the SEND_FILE and RECEIVE_FILE Functions to determine the current status of the file transfer operation when NOWAIT was specified. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ FILE_TRANSFER_STATUS │ └──────────────────────────────────────────────────────────────────────┘ Remarks: When the NOWAIT option is used on the SEND_FILE and RECEIVE_FILE Statements, the AUTOPILOT program is allowed to continue processing while the file transfer operation proceeds. The FILE_TRANSFER_STATUS Function allows the AUTOPILOT program to obtain the ongoing status of these file transfers. The following values are returned by FILE_TRANSFER_STATUS: 0 - Successful completion 1 - Not connected 2 - The file could not be opened. 3 - Syntax error within <file-transfer-command> or <file-transfer-type> 4 - File transfer failed 5 - File transfer was canceled 10 - File transfer is running 11 - File transfer waiting to start Examples: Send a file to another PC using XMODEM and continue processing. SEND_FILE NOWAIT "data.prn" USING "XMODEM" ... continue processing ... WAIT UNTIL FILE_TRANSFER_STATUS < 10 ; Wait until its done 12.43 FOUND Function Purpose: Returns the result of the last LOOK or WAIT Statement. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ FOUND │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The result of the last LOOK Statement is returned as a number. FOUND returns TRUE (not zero) if the LOOK Statement was successful. A FALSE (zero) is returned if the LOOK Statement was unsuccessful. If the last LOOK Statement had multiple search strings, FOUND will return a value that indicates which search string was found. Examples: LOOK FOR "VM READ" IF FOUND GOTO ready In the above example if "VM READ" was found on the screen, FOUND would return a 1 (true) and the GOTO ready statement would be executed. LOOK FOR "CP READ", "VM READ" IF FOUND = 0 GOTO not_fnd IF FOUND = 1 GOTO cp_rd IF FOUND = 2 GOTO vm_rd In the above example, if "VM READ" was on the screen, FOUND would return a 2 and if "CP READ" was on the screen FOUND would return a 1. See Also: GOTO DEPENDING_ON LOOK FOR WAIT FOR 12.44 FOUND_COLUMN Function Purpose: This function will return the screen column position of the last successful WAIT FOR or LOOK FOR Statement. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ FOUND_COLUMN │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The result of using this function will give you the exact column of where the LOOK FOR or WAIT FOR Statement was found. Example: LOOK FOR "CP READ" SET c = FOUND_COLUMN In this example if "CP READ" was found in its normal position on a VM/CMS screen, FOUND_COLUMN would set "c" to 64. See Also: FOUND FOUND_ROW LOOK FOR WAIT FOR 12.45 FOUND_ROW Function Purpose: This function will return the screen row position of the last successful WAIT FOR or LOOK FOR Statement. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ FOUND_ROW │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The result of using this function will give you the row where the LOOK FOR or WAIT FOR Statement was found. Example: LOOK FOR "CP READ" SET r = FOUND_ROW In this example if "CP READ" was found on the screen, FOUND_ROW would set "r" to 24. See Also: FOUND FOUND_COLUMN LOOK FOR WAIT FOR 12.46 GLOBAL Statement Purpose: The GLOBAL Statement allows variables in one script to be accessed by a subroutine script. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ GLOBAL identifier-1 [= value] [, identifier-2 [= value] ...] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: By declaring an identifier GLOBAL in a script, the identifier may be accessed and modified by any subroutine scripts. Examples: The following statements are equivalent: GLOBAL X, Y SET X = "DOG" SET Y = "CAT" GLOBAL X = "DOG" , Y = "CAT" In the above example, the variables X and Y may be examined and modified by a subroutine script. See Also: SET 12.47 GOTO Statement Purpose: The GOTO Statement causes execution control to skip to an identified point in the AUTOPILOT text. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ GOTO <label> │ │ │ │ GOTO DEPENDING ON <number> <label-1> │ │ [ , <Label-2> . . . │ │ [ , <label-n> ] ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The GOTO Statement causes the script to continue at the first executable statement encountered after <label>. For the GOTO with a DEPENDING_ON clause, a branch is taken to the label based on the value of the number. If <number> equals "1" then a branch to <label-1> is taken. If <number> equals "2" then a branch to <label-2> is taken, etc. If there is no corresponding <label> for the value of <number> or if <number> is equal to "0", then the next statement after the GOTO is executed. Examples: Format 1: GOTO loop Format 2: get_option: PROMPT "Enter Option ==>>" opt(1) AT 1,1 GOTO DEPENDING_ON opt opt1_rtn, opt2_rtn, opt3_rtn BEEP DISPLAY "Invalid Option" GOTO get_option See Also: PERFORM IF 12.48 HANG_UP Statement Purpose: The HANG_UP Statement causes the telephone connection to be disconnected. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ HANG_UP │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The HANG_UP Statement is valid only during asynchronous communications. When the HANG_UP Statement is executed, the HANG_UP string definition in the Terminal definition file (if any) will be sent and the call will be disconnected. The current emulation definition is still in effect and other host connectivity statements (SEND, WAIT, etc.) may be used. See Also: DIAL 12.49 HIDE Statement Purpose: The HIDE Statement can be used to change the visibility state of a window or dialog control to invisible. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ HIDE {TEXT_WINDOW(winid) } │ │ {DIALOG_WINDOW(winid) } │ │ │ │ HIDE {TEXT_FIELD(id) } │ │ {ENTRY_FIELD(id) } │ │ {PUSH_BUTTON(id) } │ │ {RADIO_BUTTON(id) } │ │ {CHECK_BOX(id) } │ │ {LIST_BOX(id) } │ │ {COMBINATION_BOX(id) } │ │ {GROUP_BOX(id) } │ │ {ICON_FIELD(id) } │ │ {MULTILINE_ENTRY_FIELD(id) } │ │ [ IN DIALOG_WINDOW(winid) ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The HIDE Statement is the reverse of the SHOW Statement. For more information on text windows, refer to the Appendix, Migration From DOS. See Also: CREATE DIALOG_WINDOW CREATE TEXT_WINDOW SHOW 12.50 HOST_CURSOR_COLUMN Function Purpose: This function returns the host cursor column position. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ HOST_CURSOR_COLUMN │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function will return the current column position of the Host cursor. See Also: HOST_CURSOR_ROW See Also: SCREEN 12.51 HOST_CURSOR_ROW Function Purpose: This function returns the host cursor row position. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ HOST_CURSOR_ROW │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function will return the current row position of the Host cursor. See Also: HOST_CURSOR_COLUMN SCREEN 12.52 IF Statement Purpose: The IF Statement makes a decision regarding script execution based on the results of a comparison. Formats: ┌──────────────────────────────────────────────────────────────────────┐ │ IF <condition> <statement-1> [ELSE<statement-2>] │ │ │ │ IF<condition> │ │ BEGIN │ │ <statement-1> ....<statement-2>... │ │ <statement-n> │ │ END │ │ [ ELSE │ │ BEGIN │ │ <statement-3> . . . <statement-4> . . . │ │ <statement-m> │ │ END ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <statement> may be any AUTOPILOT Statement except another IF or WAIT Statement. <condition> may be any valid AUTOPILOT condition test. In format 1, if the condition is true <statement-1> is executed. If there is an ELSE clause, <statement-2> is skipped. If the condition is false, <statement-1> is skipped. If there is an ELSE clause, <statement-2> is executed. When using the ELSE clause and "compound" AUTOPILOT statements, use format 2 of ELSE described below. If the simple format of ELSE is used, the second part of the "compound" statement will be executed whether or not the IF condition is true. Examples of compound statements within AUTOPILOT are: First Part Second Part ----------------- ----------- IF <condition> <statement> WAIT FOR <string> AFTER If the string on the right side of a comparison is character and the string on the left is numeric, the string will be converted to numeric before the comparison. If the string cannot be converted to numeric (it contains non-numeric characters), if will be converted to the number 0. This can cause unexpected results. Because of the problem indicated above, format 2 is the recommended approach. In format 2, if the condition is true, <statement-1> thru <statement-n> is executed. If there is an ELSE clause, <statement-3> thru <statement-m> is skipped. If the condition is false, <statement-1> thru <statement-n> is skipped. If there is an ELSE clause, <statement-2> thru <statement-m> is executed. In format 2, if statements may be nested. Examples: IF counter = 10 EXIT 4 IF reply = "NO" GOTO dontdoit RUN SCRIPT "any.scr" IF RETURN_CODE = 17 SIGNAL TIMEOUT LOOK FOR any_string IF NOT FOUND GOTO anylabel IF NOT FOUND GOTO label1 ELSE GOTO label2 IF X = 1 AND Y = 1 BEGIN DISPLAY "Equal to 1" BEEP GOTO label1 END ELSE GOTO label2 See Also: BEGIN END GOTO WHILE 12.53 INCLUDE Statement Purpose: This statement allows for the merging of script source statements. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ INCLUDE "script_file_name" │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement is used to merge source statements from one script file into another script at the time it is loaded into memory. Unless a fully qualified file specification is provided, the INCLUDE File must be present either: - in the same directory as the requesting script - in the directory pointed to by the SCRIPT_DIRECTORY Customization Variable See Also: RUN SCRIPT 12.54 INSTR Function Purpose: This function is used to search for an occurrence of one string within another string. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ INSTR(n,string-1,string-2) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement will search for the first occurrence of string-2 within string-1 starting at offset n and returns the position at which the match is found. If no match is found, the function returns a 0. A "wild card" search is performed in the same manner as the WAIT FOR and LOOK FOR commands. Examples: INSTR (1,"ABCDEFGHI", "DEF") INSTR (2,"DEFDEFDEF", "DEF") INSTR (1,"DEFDEFDEF", "ABC") In the first example, the operation will return a code of 4. In the second example, the operation will return a code of 4. In the third example, the operation will return a code of 0. See Also: STR_MID 12.55 IS_CHECKED Function Purpose: The IS_CHECKED Function is used to determine the CHECKed state of a dialog control or menu item. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ IS_CHECKED( {RADIO_BUTTON(id) } │ │ {CHECK_BOX(id) } │ │ [ IN DIALOG_WINDOW(winid) ] ) │ │ │ │ IS_CHECKED( {CHOICE(id) } [ IN DIALOG_WINDOW(winid) ] │ │ [ IN TEXT_WINDOW(winid) ] ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: It returns 1 (TRUE) if the item is CHECKed or 0 (FALSE) if it is not CHECKed. For more information on text windows, refer to the Appendix, Migration From DOS. See Also: CHECK UNCHECK 12.56 IS_DISABLED Function Purpose: The IS_DISABLED Function is used to determine the selectability state of a dialog or menu item. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ IS_DISABLED( {TEXT_FIELD(id) } │ │ {ENTRY_FIELD(id) } │ │ {PUSH_BUTTON(id) } │ │ {RADIO_BUTTON(id) } │ │ {CHECK_BOX(id) } │ │ {LIST_BOX(id) } │ │ {COMBINATION_BOX(id) } │ │ {GROUP_BOX(id) } │ │ {ICON_FIELD(id) } │ │ {MULTILINE_ENTRY_FIELD(id) } │ │ [ IN DIALOG_WINDOW(winid) ] ) │ │ │ │ │ │ IS_DISABLED( {CHOICE(id) } [IN DIALOG_WINDOW(winid) ] │ │ {PULLDOWN(id)} [IN TEXT_WINDOW(winid) ] ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: It returns 1 (TRUE) if the item is DISABLEd or 0 (FALSE) if it is ENABLEd. For more information on text windows, refer to the Appendix, Migration From DOS. See Also: DISABLE ENABLE 12.57 JUMP Statement Purpose: Directs subsequent script statements to interact with the specified EHLLAPI Session and makes that session the active window. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ JUMP TO SESSION <session> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <session> is a single letter EHLLAPI session-id or the 2 to 8 character EHLLAPI session-name of the session to receive control WARNING: In order for JUMP to function properly by specifying session-id for a TalkThru session, the TalkThru session must have been loaded for EHLLAPI Support. For more information on what this means and how it is accomplished, refer to the Chapter, EHLLAPI Support. If you specify the longer session-name, this restriction is not valid. Remarks: See description of CONNECT and JUMP Statements. See Also: CONNECT 12.58 LEN Function Purpose: Returns the number of characters in a string. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ LEN(<string>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <string> is any string. The number of characters in <string>, including blanks, is returned. Example: SET a = LEN("ANY STRING") This example would set a equal to the number 10. 12.59 LOCATE HOST_CURSOR Statement Purpose: Used to position the Host Cursor. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ LOCATE HOST_CURSOR AT <row> <col> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This will position the host cursor through a series of Up, Down, Left and Right cursor movement keys to the position on the Host Screen indicated by the <row> and <col> coordinates. 12.60 LOOK Statement Purpose: Searches the host screen for the specified string pattern. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ LOOK FOR <string> [AT <row> <col>] │ │ [,<string-n> [AT <row> <col>] ] │ │ │ │ LOOK FOR <string> [FROM <row> <col> ] │ │ [TO <row> <col> ] │ │ [,<string-n> [FROM <row> <col> ] │ │ [TO <row> <col> ] ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <string> is a search pattern specified in a character string form where: ? matches any character s* matches zero or more occurrences of character (s) s+ matches 1 or more occurrence of character (s) A leading backslash may be used to match one of the special characters ?, *, or +. The AT clause limits the search area to the specified row and column values. The FROM and TO clauses allow you to specify a row/ column range to be searched. If neither the AT or FROM/TO clauses are specified, the entire screen will be searched. If multiple strings are supplied, the screen will be searched for a match with each of the strings in the order specified. LOOK will return the number of the string found in the FOUND Function. If the first string was found, the FOUND function would return a 1; if the third string was found the FOUND function would return a 3. If none of the strings were found, the FOUND function would return a 0. This facility can be used in conjunction with the DEPENDING ON form of GOTO Statement to branch to any one of several routines based on the text string located. Specifying multiple text strings is significantly quicker than utilizing multiple LOOK Statements. Examples: Format 1: LOOK FOR "TalkThru" LOOK FOR "LOGOFF AT ??:??:??" LOOK FOR "VM READ" AT 24, 60 IF FOUND goto any_label Format 2: LOOK FOR "VM/CMS ONLINE" , "CP READ" "LOGOFF AT" IF FOUND = 0 GOTO fnd_error GOTO DEPENDING_ON FOUND fnd_logo, fnd_cpread, fnd_logoff In this example, the value of FOUND is set to the corresponding occurrence of the string which was found. See Also: FOUND FOUND_COLUMN FOUND_ROW WAIT FOR 12.61 MESSAGE_BOX Function Purpose: The MESSAGE_BOX Function displays a standard OS/2 message box, waits for user response and returns the selected button. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ MESSAGE_BOX( <title> , │ │ <message , │ │ <buttons-type> , │ │ <dflt-button> , │ │ <icon-type ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <title> Message-box window title. Title is automatically centered. <message> The text of the message to be displayed in the message-box window. Text is automatically word-wrapped. A CR or LF may be imbedded in the text (use ^M or ^J) to force line breaks. <buttons-type> a number that indicates what type of buttons should be displayed in the message-box window. Values may be: 1 - OK pushbutton 2 - OK and CANCEL pushbuttons 3 - YES and NO pushbuttons 4 - YES, NO and CANCEL pushbuttons 5 - ENTER pushbutton 6 - ENTER and CANCEL pushbuttons 7 - CANCEL pushbutton 8 - RETRY and CANCEL pushbuttons 9 - ABORT, RETRY and IGNORE pushbuttons <dflt-button> a number which indicates which button should be the default. May be 1,2, or 3 (for first, second, or third button). <icon-type> a number that indicates which of the standard icons should be displayed in the message box. Values may be: 0 - No icon 1 - Query icon (question mark) 2 - Warning icon (exclamation mark) 3 - Information icon (upside down exclamation mark) 4 - Error icon (Stop sign) The function returns a number that indicates which button was pressed. The values are: 0 - CANCEL 1 - OK 2 - ENTER 3 - YES 4 - NO 5 - ABORT 6 - RETRY 7 - IGNORE 12.62 MINIMIZE, MAXIMIZE, and RESTORE Statements Purpose: These Statements execute the specified function against a text window or dialog. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ MINIMIZE {TEXT_WINDOW(winid) } │ │ {DIALOG_WINDOW(winid) } │ │ │ │ MAXIMIZE {TEXT_WINDOW(winid) } │ │ {DIALOG_WINDOW(winid) } │ │ │ │ RESTORE {TEXT_WINDOW (winid) } │ │ {DIALOG_WINDOW(winid) } │ └──────────────────────────────────────────────────────────────────────┘ Remarks: For more information on text windows, refer to the Appendix, Migration From DOS. See Also: CREATE TEXT_WINDOW CREATE DIALOG_WINDOW 12.63 NUMBER_OF_LINES Function Purpose: The NUMBER_OF_LINES Function returns the number of lines in LIST_BOXes, COMBINATION_BOXes and MULTILINE_ENTRY_FIELDs. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ NUMBER_OF_LINES ( {LIST_BOX(id) } │ │ {COMBINATION_BOX(id) } │ │ {MULTILINE_ENTRY_FIELD(id) } │ │ [ IN DIALOG_WINDOW (winid) ] ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: See Also: ADD TO SELECTED_LINE SET TEXT_OF 12.64 ON Statement Purpose: The ON Statement provides event trapping for timeout conditions on the WAIT FOR Statement. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ON { TIMEOUT } { <label> } │ │ │ │ ON { TIMEOUT } { RESET } │ └──────────────────────────────────────────────────────────────────────┘ Remarks: When the first format of the ON Statement is executed, <label> will receive control if a WAIT FOR Statement has been issued without the AFTER <timeval> clause and the SET MAXWAIT <timeval> has been exceeded. The RESUME Statement may be used to return from the trapping routine. See the RESUME Statement. Format 2 may be used to RESET or clear the TIMEOUT trap. If a TIMEOUT occurs, the script will be canceled with an appropriate message. Examples: set maxwait = 30 seconds on timeout timeout_rtn wait for "CP READ" timeout_rtn: display "A Timeout Condition Has Occurred - Terminating With Error" prompt exit -1 See Also: MAXWAIT 12.65 OPEN Statement Purpose: Allows I/O to a file or device, activates a dialog or text window created using the CREATE Statement or activates a session monitor created using the CREATE SESSION_MONITOR Statement. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ OPEN <filespec> FOR {OUTPUT } AS <filenum> │ │ {INPUT } │ │ {APPEND } │ │ {INPUT OUTPUT } │ │ {INPUT APPEND } │ │ │ │ OPEN TEXT_WINDOW <window_number> │ │ │ │ OPEN DIALOG_WINDOW <window_number> │ │ │ │ OPEN SESSION_MONITOR <monitorid> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <filespec> is a string value containing a valid OS/2 file specification. OUTPUT specifies sequential output mode. INPUT specifies sequential input mode. APPEND specifies sequential output mode where all subsequent writes will be at the end of file. INPUT OUTPUT opens file for both reading and writing; creates the file first if it does not exist. INPUT APPEND opens the file for both reading and writing; creates the file first if it does not exist. <filenum> is a number whose value is between 1 and 8. 0 is also valid if <filenum> is an identifier. This number is associated with the file for as long as it is open. It is used by other statements to refer to the file. If <filenum> is an identifier and equal to zero, it will assigned the next valid file number. The default directory for all files OPENed is the one specified by the DATA_DIRECTORY parameter in the TALKTHRU.DEF Customization File. If the file cannot be opened, an error will occur and the script will be canceled. <window_number> is the real number or identifier used in the CREATE TEXT_WINDOW or CREATE DIALOG_WINDOW Statement. For more information on text windows refer to the Appendix, Migration From DOS. monitorid must be the id of a session monitor object created by CREATE SESSION_MONITOR. A session monitor is not active until it is opened. Example (File Open): OPEN "inpfile.ext" FOR INPUT AS infile IF NOT OPEN_FLAG(infile) GOTO not_open OPEN "outfile.ext" FOR OUTPUT as outfile loop: READ LINE infile var IF EOF(infile) GOTO end WRITE LINE outfile var GOTO loop . end: CLOSE infile CLOSE outfile This example would copy the text file "inpfile.ext" to the file "outfile.ext". Note that it is not necessary to initialize infile and outfile because all identifiers are automatically initialized to zero and the open statement would then assign the next valid file number. Example (window Open): set my_window = 0 create TEXT_WINDOW my_window . . . end_create open TEXT_WINDOW my_window Example (dialog Open): set my_dialog = 0 create DIALOG_WINDOW my_dialog . . . end_create open DIALOG_WINDOW my_dialog See Also: CLOSE EOF OPEN_FLAG READ WRITE CREATE_TEXT_WINDOW CREATE_DIALOG_WINDOW DESTROY 12.66 OPEN Statement (DDE Client) Purpose: Initiates a conversation with a DDE server. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ Format 1: │ │ │ │ OPEN TOPIC(id) [ IN DDE_LINK(linkid) ] │ │ │ │ Format 2: │ │ │ │ OPEN DDE_LINK(linkid) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement initiates a conversation with a DDE server for the specified TOPIC (format 1) or for all TOPICs in a DDE_LINK definition (format 2). If a conversation was successfully started on the desired topic(s), RETURN_CODE is set to 0, otherwise it is set to 1. A particular topic can also be tested to see if it is open by using the IS_OPENED function. The IN DDE_LINK clause in required only if there is more than one DDE_LINK defined and it is not the current default. Examples: OPEN TOPIC(1) OPEN TOPIC(1) IN DDE_LINK(2) OPEN DDE_LINK(1) 12.67 OPEN Statement (DDE Server) Purpose: Prepares an AUTOPILOT script to act a DDE server. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ OPEN DDE_LINK(linkid) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement prepares the script to act as a DDE server for the 'Application' and 'Topics' defined in the specified DDE_LINK. No conversations are started -- the server waits for a client to initiate a conversation. When a client initiates a conversation with the server, the ACTION routine defined in the TOPIC clause receives control. If there is no ACTION routine in the TOPIC clause the DDE_LINK ACTION routine (if any) receives control. Examples: OPEN DDE_LINK(serverid) 12.68 OPEN_FLAG Function Purpose: Test to see if a specified file is open. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ OPEN_FLAG (<filenum>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Tests to see if a specified file is open. If it is, it returns a "1" (TRUE) or if it is closed, it returns a "0" (FALSE). Example: OPEN <filename> for input as 1 IF OPEN_FLAG(1) = 0 BEGIN DISPLAY "File cannot be opened" EXIT ABORT END See Also: CLOSE EOF OPEN 12.69 PERFORM Statement Purpose: The PERFORM Statement transfers control to the specified subroutine in the AUTOPILOT text. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ PERFORM <label> │ │ │ │ PERFORMDEPENDING_ON <number> <label-1>, │ │ <label-2>, │ │ . │ │ . │ │ . │ │ <label-n> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The PERFORM Statement causes the script to continue at the first executable statement encountered after <label>. When a RETURN Statement is encountered control will be returned to the next sequential instruction after the PERFORM Statement. Format 2 allows a branch to be taken to the label based on the value of the number. If <number> equals "1" then a branch to <label-1> is taken. If <number> equals "2" then a branch to <label-2> is taken, etc. If there is no corresponding <label> for the next value of <number> or if <number> is equal to "0", then the next statement after the PERFORM is executed. Examples: Format 1: PERFORM cleanup: Format 2: get_option: PROMPT "Enter Option ==>>" opt(1) AT 1, 1 PERFORM DEPENDING_ON opt opt1_rtn, opt2_rtn, opt3_rtn BEEP DISPLAY "Invalid Option" GOTO get_option See Also: RETURN 12.70 QUIET Function Purpose: The QUIET function will determine if changes took place on the host during the specified time frame. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ QUIET (<timeval>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: [ SECONDS ] (<timeval> = <number> [ MINUTES ] ) [ HOURS ] This function will determine if changes took place on the host screen during a specified time period. This statement will return a "1" (TRUE) if no changes took place, and a "0" (FALSE) if a change took place. A change is defined in an asynchronous environment as any characters being received from the host. In a 3270 environment a change is defined as any change on the host screen or if the status is not ready (X SYSTEM, etc.). When a change occurs, the function returns immediately with a value of "0" (false). Otherwise it will wait up to the specified amount of time and return with a value of "1" (true). Examples: WAIT UNTIL QUIET(10 SECONDS) AFTER 60 SECONDS GOTO error_exit WAIT UNTIL NOT QUIET(5 SECONDS) See Also: WAIT UNTIL 12.71 READ Statement Purpose: Reads data from a file and assigns them to script variables. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ [ {CSV } ] │ │ READ [ {LINE } ] <filenum> <identifier-1> │ │ [ {BUFFER} ] [ FOR <maxsize> ] │ │ [ AT <offset> [,<origin> ] ] │ │ │ │ [, <identifier-2> │ │ [ FOR <maxsize> ] │ │ [ AT <offset> [,<origin ] ] │ │ [, . . . ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: CSV an keyword indicating that the data contains Comma Separated Values and multiple values may occur per file record (this is the default) LINE a keyword indicating that the individual records in the file are separated by carriage returns BUFFER a keyword indicating that the data is to be read randomly <filenum> is the number used when the file was opened. <identifier-n> is the name of a variable that will have a data item assigned to it. FOR <maxsize> limits the amount of data that can be read into an identifier. Used mainly with READ BUFFER. AT <offset> <origin> specifies a new position for the "read pointer" If identifier is the name of an array and the file has been opened for input, then the file is read into the array. For example, if the array were defined as: DIM records(20) and the following read command was issued: READ LINE in_file records the first 20 records of in_file will be read into the array records. Also, the keyword identifier return_code will be set to the number of records read. Subsequent reads of in_file will read the next 20 records into the array records until EOF is reached. NOTE: Reading records into an array is significantly faster than reading them a record at a time. If nothing is specified or if the CSV keyword is specified, the data items are assumed to be comma separated. In this format, leading spaces, tabs, carriage returns, and line feeds are ignored. The first character that is not a space, tab, carriage return, or line feed is assumed to be the start of the data item. If this first character is a quotation mark, the data item will consist of all characters between the first quotation mark and the last. If the data item contains a quotation mark as a character, it must appear as two quotation marks (just like string constants in a script). If the first character of a string is not a quotation mark, the data item is assumed to end when a comma, tab, space, carriage return, or line feed is encountered. If the LINE keyword is specified, all characters are read until a carriage return is encountered. The characters are assigned to <identifier-1>. It then skips over the carriage return/line feed sequence. The next READ LINE Statement would read all the characters up to the next carriage return. If more than 1 identifier is used in a READ LINE Statement, each 1 line of characters will be assigned to each identifier. If the BUFFER keyword is specified, a specific number of bytes may be read from a file without regard to delimiters such as CRLF (as in READ LINE) or commas (as in READ CSV). READ BUFFER could also be used to read binary data since it ignores the hex 1A End-Of-File mark. READ BUFFER and write BUFFER can also be used to save window images (see the PC_SCREEN function with the CHARATTR option). The FOR <maxsize> clause is normally used with the READ BUFFER Statement, but can be used with READ CSV and READ LINE as well. If it is not specified (the normal case), the maximum size for data read is set to the maximum AUTOPILOT string size (4k). If the end of file is reached, the identifiers are set to a NULL string (length of zero). All READ types allow data to be accessed "randomly" (via the AT clause) so that data may be read from any position in the file in any order. To understand random file I/O, it may help to understand the concept of a "read pointer". The "read pointer" always points to the part of the file that will be read in the next READ Statement. When the file is opened, the read pointer is initialized to point to the first byte in the file. As data is read by ensuing sequential READ Statements, the "read pointer" is increased by the number of bytes read. The AT <offset> [,<origin>] clause allows you to reposition the "read pointer": <offset> is the number of bytes from <origin> <origin> is a constant that defines the initial position: 0 - beginning of the file (default) 1 - current position of the "read pointer" 2 - end of file As with normal sequential reads, after a READ Statement with the AT clause is executed, the "read pointer" is increased by the number of bytes read. NOTE: If file has CR and LF at the end of each record, these will be counted as characters READ. NOTE: To READ from end-of-data-set backwards, you must use a negative number. Examples: Assume a properly opened file contains the following 2 lines of data: 12.34,ANY STRING "A QUOTED STRING" READ filenum a1,b1 READ filenum c1,d1,e1 This example would set identifier a1 to 12.34, b1 to ANY, c1 to STRING, and d1 to A QUOTED STRING. Identifier e1 would be set to NULL since end of file was reached. READ LINE filenum a2 READ LINE filenum b2 In this example, identifier a2 would be set to 12.34,ANY STRING and b2 would be set to "A QUOTED STRING". Note that identifier a2 would contain the comma and identifier b2 would contain the quotation marks because the entire line is read in. Read 100 bytes from a file starting at byte position 500: READ BUFFER xbuff FOR 100 AT 500 Read the last 2 bytes in a file: READ BUFFER xbuff FOR 2 AT 2,2 See Also: CLOSE DIM OPEN READ_POSITION WRITE 12.72 READ_POSITION Function Purpose: To obtain the current "read pointer". Format: ┌──────────────────────────────────────────────────────────────────────┐ │ READ_POSITION(<filenum>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Returns the current position of the "read pointer" for the file indicated by filenum. See the READ Statement for more information on the "read pointer". Examples: set t_pointer = READ_POSITION(in_file) See Also: READ WRITE WRITE_POSITION 12.73 RECEIVE_FILE Statement Purpose: The RECEIVE_FILE Statement allows you to invoke file transfer Receive File requests directly from AUTOPILOT. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ RECEIVE_FILE [NOWAIT] <file-transfer-command> │ │ USING <file-transfer-type> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The string expression <file-transfer-command> indicates which file(s)are to be transferred. Certain options may also be specified here. The exact format is dependent on the type of file transfer: XMODEM/YMODEM/KERMIT file specification of the file to RECEIVE. IND$FILE the IND$FILE command line. For example, the following would be specified to RECEIVE the CMS file TEST FILE A onto the C disk. C:\TEST.TXT TEST FILE A (ASCII CRLF The string expression <file-transfer-type> determines which file transfer protocol to use. It may be one of the following: XMODEM = Use XMODEM CRC protocol XMODEM_CRC = Use XMODEM CRC protocol XMODEM_CHECKSUM = Use XMODEM CHECKSUM protocol XMODEM_1K = Use XMODEM 1K protocol XMODEM_1K_G = Use XMODEM 1K G protocol YMODEM = Use YMODEM protocol YMODEM_G = Use YMODEM G protocol ZMODEM = Use ZMODEM protocol KERMIT = Use KERMIT SEND/RECEIVE protocol IND$FILE = Use IBM IND$FILE (SEND/RECEIVE) protocol ASCII = Use Ascii protocol CIS_B = Use Compuserve B or B+ protocol The default location for files on the PC is in the directory specified by the DATA_DIRECTORY Customization Variable. To view or modify this variable, select System Configuration from the Utilities pull down menu on any Phone Book. The RECEIVE_FILE command, by default, will wait for the transfer to complete before returning. Upon completion, RETURN_CODE will be set to one of the following values: 0 - Successful completion 1 - Not connected 2 - The file could not be opened. 3 - Syntax error within <file-transfer-command> or <file-transfer-type> 4 - File transfer failed 5 - File transfer was canceled If the NOWAIT option is specified, the RECEIVE_FILE Statement will return immediately after starting the transfer. Other script commands can be executed while the transfer runs (the script may also be exited). The status of the file transfer may be determined via the FILE_TRANSFER_STATUS Function. Refer to this Function for a list of the values returned. Examples: Download a file from a BBS using XMODEM: RECEIVE_FILE "arc.exe" USING "XMODEM" IF RETURN_CODE <> 0 BEGIN DISPLAY "Error" BEEP GOTO ... END See Also SEND_FILE FILE_TRANSFER_STATUS 12.74 RELEASE Statement Purpose: This statement will unlock the current host session. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ RELEASE │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement will unlock the current session from a previously RESERVEd session. Users will then be allowed to key into the current session. See Also: RESERVE 12.75 REMOVE FROM Statement Purpose: The REMOVE FROM Statement is used to remove various items from text windows, dialogs, session monitors and DDE_LINK objects. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ Dialog Windows: │ │ │ │ REMOVE FROM DIALOG_WINDOW(winid) │ │ {TITLE_BAR } │ │ {SYSTEM_MENU } │ │ {MINIMIZE_BUTTON } │ │ {MAXIMIZE_BUTTON } │ │ {TASK_LIST _ } │ │ {ACTION_BAR_MENU } ... │ │ │ │ REMOVE FROM ACTION_BAR_MENU │ │ [ IN DIALOG_WINDOW(winid) ] │ │ [ IN TEXT_WINDOW(winid) ] │ │ PULLDOWN(id) │ │ │ │ REMOVE FROM PULLDOWN(id) │ │ [ IN DIALOG_WINDOW(winid) ] │ │ [ IN TEXT_WINDOW(winid) ] │ │ {CHOICE(id) } │ │ {SEPARATOR(id) } │ │ │ │ REMOVE FROM {LIST_BOX(id) } │ │ {COMBINATION_BOX(id) } │ │ {MULTILINE_ENTRY_FIELD(id) } │ │ [ IN DIALOG_WINDOW(winid) ] │ │ LINES <pos1 [ TO <pos2> ] │ │ │ │ REMOVE FROM DIALOG_WINDOW(winid) │ │ { TEXT_FIELD(id) } │ │ { ENTRY_FIELD(id) } │ │ { MULTILINE_ENTRY_FIELD(id) } │ │ { PUSH_BUTTON(id) } │ │ { RADIO_BUTTON(id) } │ │ { CHECK_BOX(id) } │ │ { LIST_BOX(id) } │ │ { COMBINATION_BOX(id) } │ │ { GROUP_BOX(id) } │ │ { ICON_FIELD(id) } │ └──────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────┐ │ Text Windows: │ │ │ │ REMOVE FROM TEXT_WINDOW(winid) │ │ {TITLE_BAR } │ │ {SYSTEM_MENU } │ │ {MINIMIZE_BUTTON } │ │ {MAXIMIZE_BUTTON } │ │ {HORIZONTAL_SCROLL_BAR } │ │ {VERTICAL_SCROLL_BAR } │ │ {TASK_LIST } │ │ {ACTION_BAR_MENU } ... │ └──────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────┐ │ Session Monitors: │ │ │ │ REMOVE FROM SESSION_MONITOR (monitorid) │ │ [ TEXT_WATCH(id) ]... │ │ [ HOST_KEY_WATCH(id) ]... │ │ │ └──────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────┐ │ DDE Links: │ │ │ │ Format 1: │ │ REMOVE FROM DDE_LINK(linkid) │ │ [ TOPIC (id) ]... │ │ │ │ Format 2: │ │ REMOVE FROM TOPIC(id ) [ IN DDE_LINK(linkid) ] │ │ [ HOT_LINK (id) [ WARM_LINK (id) ] ] │ │ │ │ Format 3: │ │ REMOVE FROM TOPIC(id ) [ IN DDE_LINK(linkid) ] │ │ [ EXPORT_ITEM (id) ]... │ │ [ EXPORT_COMMAND (id) ]... │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Dialog Window Formats: When you use the REMOVE FROM DIALOG_WINDOW format, you must CLOSE and reOPEN the dialog before the control will be removed. Text Window Formats: For more information on text windows, refer to the Appendix, Migration From DOS. Session Monitor Formats: When you use the REMOVE FROM SESSION_MONITOR format, monitorid must be the id of a session monitor object created by CREATE SESSION_MONITOR and id is the id of a watch item previously defined in the session monitor object by CREATE or ADD TO. DDE Link Formats: When you use the REMOVE FROM DDE_LINK(linkid ) format, it removes a TOPIC definition (with associated HOT_LINKS and WARM_LINKS) from a DDE_LINK object. The TOPIC is closed before it is removed. The second format removes HOT_LINK and/or WARM_LINK items from a TOPIC definition. If the TOPIC is opened and enabled, an unadvise transaction will be generated for all enabled HOT_LINK and WARM_LINK link items that are removed. The third format removes EXPORT_ITEM and/or EXPORT_COMMAND entries from a TOPIC definition. Examples: REMOVE FROM DDE_LINK(1) TOPIC (2) ADD TO TOPIC(1) HOT_LINK (1) HOT_LINK (2) See Also: ADD TO 12.76 RESERVE Statement Purpose: This statement locks the current host session to prevent all user keyed input. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ RESERVE │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function can be used to prevent the user from keying into a selected session. SENDs may be executed while a session is RESERVEd. Multiple sessions can be locked. You may not lock a workstation control session. The presentation space remains locked until a RELEASE is issued. See Also: RELEASE 12.77 RESUME Statement Purpose: The RESUME Statement continues program execution after an ON condition, an action bar menu CHOICE, or a dialog control ACTION routine has been performed. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ RESUME {TIMEOUT } { RETRY } │ │ {ACTION } { NEXT } <code> │ │ { <label> } │ └──────────────────────────────────────────────────────────────────────┘ Remarks: RESUME <condition> RETRY causes execution to resume at the statement which caused the condition to occur. RESUME <condition> NEXT causes execution to resume at the statement immediately following the one which caused the condition to occur. RESUME <condition> <label> causes execution to resume at the specified label. RESUME ACTION is used for action bar menu CHOICEs and dialog control ACTIONs. If the routine received control from an action bar menu, RETRY will ENABLE the action bar menu that was DISABLED when the routine was triggered. With action bar menus and dialog controls, if a WAIT FOR ACTION was specified, RESUME ACTION RETRY would be used to return to it. For more information using RESUME with text windows, refer to the Appendix, Migration From DOS. The <code> value may be specified only for RESUME ACTION and only with DDE. The code entered will be returned to the DDE requester as a return code. Examples: RESUME TIMEOUT RETRY See Also: ON SIGNAL WAIT FOR ACTION 12.78 RETURN Statement Purpose: To return from a subroutine initiated by a perform. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ RETURN │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The RETURN Statement causes the AUTOPILOT program to branch back to the statement following the most recent PERFORM Statement. If there is no active perform, the RETURN Statement is ignored. See Also: PERFORM 12.79 ROUND Statement Purpose: Returns a number, rounded to a specified number of places. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ ROUND(a,dec) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The ROUND function rounds off the number a to dec decimal places. Examples: ROUND(123.456,2) returns 123.46 ROUND(123.456,0) returns 123 ROUND(123.456,4) returns 123.456 12.80 RUN Statement Purpose: Execute an OS/2 command or another script. Formats: ┌──────────────────────────────────────────────────────────────────────┐ │ RUN SCRIPT <filespec> │ │ [ USING <string-1> [ , <string-n> ] ] │ │ │ │ RUN SYSTEM <cmd-name> │ │ [ USING <string-1> [ , <string-n> ] ] │ │ [ NOWAIT ] │ │ │ │ RUN PROGRAM <program-name> │ │ [ USING <string-1> [ , <string-n> ] ] │ │ [ WINDOW_SIZE <rows> [ DEVICE_ROWS ] [,] │ │ <cols> [ DEVICE_COLUMNS ] ] │ │ [ WINDOW_POSITION [ DEVICE_ROW ] <row> [,] │ │ [ DEVICE_COLUMN ] <col> ] │ │ [ NOWAIT ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Format 1: When AUTOPILOT runs a script it uses the following search algorithm to find the script file: o If the script file specification includes a directory, the script file must reside in that directory -- no other directories will be searched. o If the script file specification does not include a directory, directories are searched in the following order: 1. The directory of the parent script (this only applies to scripts that where called from another script). 2. The directory specified by the SCRIPT_DIRECTORY Customization Variable. If the optional USING clause is specified, <string-1> thru <string-n> may be referenced in the called script positionally as %1 thru %n. The %n variables are local, that is, any change to a %n variable will not effect the value of <string-n> in the calling script. When control returns from the called script (via the EXIT Statement), the statement following the RUN Statement will be executed. The return code from the called script (set via the EXIT Statement), can be examined via the global variable RETURN_CODE. Formats 2 And 3: DOS programs CANNOT be run utilizing any format of RUN. There are essentially three types of programs that can be run using RUN SYSTEM and RUN PROGRAM: 1. Presentation Manager programs that can run in a PM window (i.e. TalkThru or the System Editor) 2. window compatible programs that can run in either a VIO window or as a full-screen application (i.e. the OS/2 Command Interpreter) 3. programs that can run only as full screen applications Format 2 of the RUN Statement invokes the program or CMD file specified in <cmd-name> as if it was entered in response to the OS/2 prompt utilizing CMD.EXE to run it. If the optional USING clause is specified, <string-1> thru <string-n> are appended to <string> to form a single command string. Format 3 of the RUN Statement will invoke the referenced program directly without loading a secondary copy of CMD.EXE. This format is faster and uses less memory than RUN SYSTEM but may not be used for CMD files. When a program is executed in this manner, the RETURN_CODE may be examined within the script. <program-name> should include an extension (.EXE) since the path is searched. If the optional USING clause is specified, <string-1> thru <string-n> are appended to <string> to form a single command string. The optional WINDOW_SIZE and WINDOW_POSITION clauses allow you to establish the size of the initial window of the application you want to run. These clauses work within the following guidelines: 1. Full screen only applications ignore these clauses as they can only run as a full screen. 2. Window compatible applications can run either as a full screen or as a VIO window. If WINDOW_SIZE and WINDOW_POSITION are NOT specified, the application will run as a full screen. If WINDOW_SIZE and/or WINDOW_POSITION ARE specified, the application will run in a VIO window. If WINDOW_SIZE is not specified, the size will be half the height of the desktop and half the width. If WINDOW_POSITION is not specified, the window will be centered. 3. Presentation Manager programs can only run in a PM window. WINDOW_SIZE and/or WINDOW_POSITION clauses may be specified to give the application its initial window size (default size and position is the same as above). However, most PM applications will ignore the specified initial size and position and will place and size the window itself. The NOWAIT clause causes AUTOPILOT to invoke the application and continue immediately -- it does not wait for the application to complete. If NOWAIT is NOT specified, AUTOPILOT will wait for the application to end. If the AUTOPILOT program is canceled while an application invoked via RUN without NOWAIT is still running, the application is also canceled. If an AUTOPILOT program ends while a NOWAIT application is still running, the application continues to run. Examples: RUN SCRIPT "script2.scr" RUN SCRIPT "a:\scrdir\another.scr" RUN SCRIPT script_iden USING "any string", any_iden, 123.45 RUN SYSTEM "prog1 a:file.ext -a" RUN PROGRAM "prog1.exe" USING "a:file.ext" , "-a" RUN SYSTEM "DIR A:\" See Also: EXIT RETURN_CODE 12.81 SCREEN Function Purpose: Returns a string consisting of the characters on the HOST screen. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ SCREEN │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The characters on the HOST screen (except the status line) are returned as a string. Attributes and NULL characters on the screen are changed to spaces. Examples: SET a = SCREEN SET b = STR_LEFT(a,80) This example would set b equal to line 1 of the HOST screen. DISPLAY STR_LEFT(SCREEN, 80); This example would display line 1 of the HOST screen. See Also: INSTR LOOK FOR WAIT FOR 12.82 SCRIPT_INFO Function Purpose: Return various types of script information. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ SCRIPT_INFO (type) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: SCRIPT_INFO is used to obtain different types of information related to the current AUTOPILOT session. Type Information Returned 1 the full file name of the current script is returned. 2 the full file name of the script that called the current script is returned. If the current script was not called by another script (i.e. its the main script),, a null string is returned. See Also: RUN SCRIPT 12.83 SEARCH_ARRAY Statement Purpose: The SEARCH_ARRAY Statement is used to quickly search the elements of an array for a specific value. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ SEARCH_ARRAY arrayname │ │ [ ( [FROM dim, ... ] [TO dim,...] ) ] │ │ FOR <value> │ │ [ USING search-options ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: arrayname - may be a 1,2, or 3 dimensional array value - may be any string or numeric expression. FROM - optional clause defaults to the first element in the array TO - optional clause defaults to the last element in the array USING - optional clause specifies search options that are a subset of the options specified in the USING clause of the SORT statement This statement searches the elements of an array for a specific value. If no range is specified all the elements are searched. If a range is set than all the elements within the range are searched. The FROM clause defines the starting indices and the TO clause defines the ending indices. Each index is never varied outside of the defined range (See SET_ARRAY). If the value is found RETURN_CODE is set to 0. If it is not found RETURN_CODE is set to 1. The indices of the found item can be retrieved from the Function ARRAY_INDEX. For example: DIM myarray(10,5) SEARCH_ARRAY myarray (FROM 2,3 TO 5,4) FOR "A string" IF RETURN_CODE = 1 BEGIN DISPLAY "NOT FOUND" EXIT END SET s = myarray(ARRAY_INDEX(1),ARRAY_INDEX(2)) Elements (2,3), (2,4), (3,3), (3,4), (4,3), (4,4), (5,3), and (5,4) would all be set to 0. All other elements would remain unchanged. If no USING clause is specified the type of comparison done (string vs. numeric) is determined by the type of the expression specified in the FOR clause. The USING clause uses a subset of the SORT USING options. This allows you to explicitly specify the type of search (numeric or string) rather than rely on the type of expression specified in the FOR clause. It also lets you do case insensitive searches. The valid options are 'T1', 'T2', and 'T3'. 'On' may also be included. See the SORT option for more details. See Also: SET ARRAY 12.84 SELECT Statement Purpose: The SELECT Statement allows the script to select a line from within a LIST_BOX or COMBINATION_BOX dialog control. Remarks: ┌──────────────────────────────────────────────────────────────────────┐ │ SELECT {LIST_BOX(id) } │ │ {COMBINATION_BOX(id) } │ │ [ IN DIALOG_WINDOW (winid) ] │ │ LINE <num> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: When an item is SELECTed, a reverse video Selector Bar will appear over it and it's number will be returned through the SELECTED_LINE Function. Unless the item is a MULTIPLE_SELECTION LIST_BOX, selecting 1 line automatically deselects the current selection. See Also: DESELECT SELECTED_LINE 12.85 SELECTED_LINE Function Purpose: This function returns the line number of the selected item in a LIST_BOX or COMBINATION_BOX. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ SELECTED_LINE ( {LIST_BOX(id) } │ │ {COMBINATION_BOX(id) } │ │ [ IN DIALOG_WINDOW(winid) ] │ │ [ ,<start lineno> ] ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: If no lines are selected, 0 is returned. The optional <startlineno> parameter is used in MULTIPLE_SELECTION LIST_BOXes. If included, the Function returns the next selected line starting with and including <startlineno>. If not included, the first selected line number is returned. See Also: SELECT DESELECT TEXT_OF 12.86 SEND Statement Purpose: Transmits character and/or control key sequences to the HOST. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ SEND {<string> } [{<string> }] │ │ {<key> } [,{<key> }] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Characters and control keys are sent to the host as if they were entered at the terminal. An attempt to send characters to protected screen positions may cause the terminal keyboard to lock. All subsequent characters and control keys within the SEND Statement will be ignored. The SEND statement will not be executed until the terminal is in a ready state. A list of the valid 3270 <key> names is provided under Definition Of Terms in the AUTOPILOT Language Overview chapter in this manual. Examples: SEND "logon ", USERID, " ", PASSWORD, ENTER SEND TAB, TAB, TAB, "X", TAB, "X", PF9 SEND " B", ENTER See Also: LOOK FOR QUIET WAIT FOR 12.87 SEND_FILE Statement Purpose: The SEND_FILE Statement allows you to invoke file transfer Send File requests directly from AUTOPILOT. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ SEND_FILE [NOWAIT] <file-transfer-command> │ │ USING <file-transfer-type> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The string expression <file-transfer-command> indicates which file(s)are to be transferred. Certain options may also be specified here. The exact format is dependent on the type of file transfer: XMODEM/YMODEM/KERMIT file specification of the file to SEND. IND$FILE the IND$FILE command line. For example, the following would be specified to SEND the PC file C:\TEST.TXT to a CMS system. C:\TEST.TXT TEST FILE A (ASCII CRLF The string expression <file-transfer-type> determines which file transfer protocol to use. It may be one of the following: ASCII = Use Ascii protocol CIS_B = Use Compuserv B or B+ XMODEM = Use XMODEM CRC protocol XMODEM_CRC = Use XMODEM CRC protocol XMODEM_CHECKSUM = Use XMODEM CHECKSUM protocol XMODEM_1K = Use XMODEM 1K protocol XMODEM_1K_G = User XMODEM 1K G protocol YMODEM = Use YMODEM protocol YMODEM_G = Use YMODEM G protocol ZMODEM = Use ZMODEM protocol KERMIT = Use KERMIT SEND/RECEIVE protocol IND$FILE = Use IBM IND$FILE (SEND/RECEIVE) protocol The default location for files on the PC is in the directory specified by the DATA_DIRECTORY Customization Variable. To view or modify this variable, select System Configuration from the Utilities pull down menu on any Phone Book. The SEND_FILE command, by default, will wait for the transfer to complete before returning. Upon completion, RETURN_CODE will be set to one of the following values: 0 - Successful completion 1 - Not connected 2 - The file could not be opened. 3 - Syntax error within <file-transfer-command> or <file-transfer-type> 4 - File transfer failed 5 - File transfer was canceled If the NOWAIT option is specified, the SEND_FILE Statement will return immediately after starting the transfer. Other script commands can be executed while the transfer runs (the script may also be exited). The status of the file transfer may be determined via the FILE_TRANSFER_STATUS Function. Refer to this Function for a list of the values returned. Examples: Send a file to another PC using XMODEM and continue processing: SEND_FILE NOWAIT "data.prn" USING "XMODEM" ... processing ... WAIT UNTIL FILE_TRANSFER_STATUS < 10 ; Wait until its done See Also: RECEIVE_FILE FILE_TRANSFER_STATUS 12.88 SET Statement Purpose: Assigns values to either AUTOPILOT reserved or user specified variable fields. It is also used to modify text window, dialogs and session monitor objects. Formats: ┌──────────────────────────────────────────────────────────────────────┐ │ SET <identifier> = {<number>} [<operator> <number> ] │ │ {<string> } [<operator> <string>] │ │ │ │ SET MAXWAIT = <timeval> │ │ │ │ { <SECOND(S)> } │ │ SET MAXWAIT = <number> { <MINUTE(S)> } │ │ { <HOUR(S)> } │ │ │ │ SET facility>-trace facility>TRACE {ON } │ │ {OFF } │ │ │ │ SET TRACE_DELAY = <number> │ │ │ │ SET CAPTURE {ON } [ <filename> ] │ │ {OFF } │ │ │ │ SET KEEP {ON } │ │ {OFF} │ │ │ │ SET NUMERIC_PRECISION = <precision> │ │ SET NUMERIC_FORMAT = <value> │ │ │ │ SET SEND_MNEMONIC {ON } │ │ {OFF} │ │ │ │ SET TITLE_BAR <title-string> │ │ WINDOW_SIZE <rows> [ { TEXT_ROWS } ] │ │ [ { DEVICE_ROWS } ] [ , ] │ │ <cols> [ { TEXT_COLUMNS } ] │ │ [ { DEVICE_COLUMNS } ] │ │ WINDOW_POSITION [ DEVICE_ROW[S] ] <rows> │ │ [ DEVICE_COLUMN[S] ] <cols> [ , ] │ │ │ │ SET CURRENT_WINDOW = <window-number> │ │ │ │ SET { PULLDOWN } <refno = { <text> } │ │ { CHOICE } { ACTION <label> } │ │ │ │ SET {TEXT_FIELD(id) } │ │ {ENTRY_FIELD(id) } │ │ {MULTILINE_ENTRY_FIELD(id) } │ │ {PUSH_BUTTON(id) } │ │ {RADIO_BUTTON(id) } │ │ {CHECK_BOX(id) } │ │ {LIST_BOX(id) } │ │ {COMBINATION_BOX(id) } │ │ {GROUP_BOX(id) } │ │ {ICON_FIELD(id) _} │ │ [ IN DIALOG_WINDOW(winid) ] = │ │ { <text-string> } │ │ { ACTION <label> } │ │ { SIZE <rowsize> ,_<co lsize> } │ │ { AT <rowpos> , <colpos> } │ │ │ │ SET ACTION [ IN DIALOG_WINDOW (winid) ] = <label> │ │ │ │ SET SESSION │ │ [ IN SESSION_MONITOR(monitorid ) ] [ = ] sessid │ │ │ │ SET TEXT_WATCH(id) │ │ [ IN SESSION_MONITOR(monitorid) ] [ = ] string │ │ [ AT | FROM | TO clause(s) ] │ │ [ ACTION label ] │ │ │ │ SET HOST_KEY_WATCH(id) │ │ [ IN SESSION_MONITOR(monitorid) ] [ = ] key │ │ [ ACTION label ] │ │ │ │ SET SEND_WAIT_TYPE = type │ └──────────────────────────────────────────────────────────────────────┘ Remarks: SET <identifier> is the most frequently used format. It is used to assign the result of an expression to the specified identifier. The remainder of the formats are used to assign values to AUTOPILOT reserved values. MAXWAIT is the global timeout keyword identifier whose value will be used in all screen WAIT operations unless an overriding value is encoded on the specific WAIT Statement being executed. <timeval> is a number followed by the time measurement (SECONDS, MINUTES, or HOURS). The default value for MAXWAIT is 60 SECONDS. MSGLINE is the global row value keyword identifier used in all DISPLAY and PROMPT activity unless overridden by the individual statement being executed. <row> must be a number from 1 to 25. MSGLINE = 0 is the default if the window was defined using CREATE TEXT_WINDOW, but MSGLINE = 25 is the default for the PC/DOS compatibility window provided if no CREATE TEXT_WINDOW is issued. The SET TRACE ON/OFF Statement may be used to display the script keyword, line number, and source file name as each statement is executed within the script. SET TRACE_DELAY Statement may be used to specify an amount of time to pause between the execution of each script statement so the effect will look as if the script has been slowed down to permit easier observation of a trace process. This statement works in conjunction with the SET TRACE Statement. SET CAPTURE ON/OFF is used to control the capturing of asynchronous data to a file (only supported during asynchronous terminal emulation). All captured data is placed into a file. If the <filename> option is not specified, the name used is generated and it is placed in the directory specified by the DATA_DIRECTORY Customization Variable (usually C:\TALKTHRU\DATA). If the <filename> option is specified, it must be the fully qualified name of the file to receive the data. The SET KEEP ON/OFF Statement is used to change the default KEEP option for the EXIT Statement. Normally an EXIT Statement without the KEEP option will release the script from memory. By executing a SET KEEP ON all EXIT Statements will keep the script in memory even if the EXIT Statement is specified without the KEEP option. See the EXIT Statement for more information regarding the KEEP option. SET NUMERIC_PRECISION and NUMERIC_FORMAT are used to control the format that numbers take when converted to strings (such as when they are displayed). NUMERIC_PRECISION and NUMERIC_FORMAT have no effect on the precision of calculations, they only affect the conversion of numbers to strings. The precision value on NUMERIC_PRECISION is equal to the maximum number of digits after the decimal point that will be displayed. The <value> on NUMERIC_FORMAT can be: 1 ==>> Do not display trailing zeros after the decimal 2 ==>> Display training zeros after the decimal SET SEND_MNEMONIC ON allows keystroke mnemonics to be sent via the SEND Statement during EHLLAPI emulation. SET SEND_MNEMONIC OFF causes AUTOPILOT to treat the @ character as an @, not as the start of a keystroke mnemonic. The default setting is OFF. Below is a table containing the valid mnemonics that can be sent with SEND_MNEMONIC ON: A-Alt I-Insert Q-Finish(Quit) B-Backtab J-Jump R-Reset C-Clear K-Copy S-Shift D-Delete Char L-Left Cursor Move T-Tab E-Enter M-Enlarge(Magnify) U-Up Cursor Move F-Erase Eof N-New Line V-Down Cursor Move G-Not Used O-Not Used W->>Y-Not Used H-Help P-Print Z-Right Cursor Move 0 Home 7 PF7 e PF14 l PF21 1 PF1 8 PF8 f PF15 m PF22 2 PF2 9 PF9 g PF16 n PF23 3 PF3 a PF10 h PF17 o PF24 4 PF4 b PF11 i PF18 x PA1 5 PF5 c PF12 j PF19 y PA2 6 PF6 d PF13 k PF20 z PA3 The SET TITLE_BAR, DEFAULT_COLOR, WINDOW_SIZE, and WINDOW_POSITION Statements are used to modify information specified in the CREATE TEXT_WINDOW Statement. See this statement for more information on meaning and format. The SET CURRENT_WINDOW Statement is used to indicate which window defined in the CREATE TEXT_WINDOW Statements is to receive subsequent DISPLAY, PROMPT, COLOR, CLS, etc. Statements. <window-number> is the real number or identifier used in the CREATE Statement. The SET PULLDOWN/CHOICE formats allow you to dynamically modify the <text> or ACTION associated with a PULLDOWN or CHOICE Action Bar Menu item. Refer to the CREATE Statement for more information on PULLDOWN and CHOICE. WARNING: If multiple windows are being supported in an AUTOPILOT program, the desired window must be the CURRENT_WINDOW for all window Statements and Functions to work. See the SET CURRENT_WINDOW Statement for more information on how this is done. The SET dialog-control ... formats are used to dynamically modify the following information regarding the specified dialog control: <text-string> The associated text string. This IS ONLY VALID for dialog controls which have associated text strings. If the text associated with a dialog control refers to an ICON_FIELD the text string refers to the name of the icon file. ACTION The associated ACTION. This IS ONLY VALID for dialog controls which have an associated ACTION. SIZE The size of the control. The size can be specified in any of the ways indicated on the related clause in the CREATE DIALOG_WINDOW Statement. AT The position of the control. The position can be specified in any of the ways indicated on the related clause in the CREATE DIALOG_WINDOW Statement. The SET ACTION clause allows you to specify or modify the default action to occur if: o System Menu Close was requested o a PULLDOWN or CHOICE is requested with no associated ACTION o a dialog control (i.e. PUSH_BUTTON) is activated with no associated ACTION The SET SESSION formats allows you to modify the EHLLAPI session id (<sessid>) being monitored by the specified session monitor. The SET TEXT_WATCH formats allow you to modify the specifics of a TEXT_WATCH clause in a session monitor. The SET HOST_KEY_WATCH formats allow you to modify the specifics of a HOST_KEY_WATCH clause in a session monitor. If the IN SESSION_MONITOR clause is not specified, the current session monitor will be used (the last monitor created or one set by the SET CURRENT_MONITOR statement). SET SEND_WAIT_TYPE statement tells AUTOPILOT when to wait for the keyboard to be ready when doing a SEND statement.. The value of type may be: type Remarks ──── ────────────────────────────────────────────────────────────────────── 1 Wait until keyboard ready before doing a SEND only for the first SEND following a WAIT FOR (default). 2 Wait until keyboard ready before sending the first item in each SEND statement. 3 Do not wait until keyboard ready before doing a SEND. NOTE: 'Wait for keyboard ready' takes about 1/2 of a second for TalkThru sessions so performance can be improved by using type = 1 or 3. Also note that prior to release 2.1, type = 2 was the default (and there was no way to change it). Examples: SET MAXWAIT = 30 SECONDS SET x = 1 SET y = x + 1 SET s = STR_LEFT(t,y) SET TRACE ON SET TRACE_DELAY = 2 seconds SET DISPLAY ON DIAL /* Dial the phone */ WAIT FOR "CONNECT" /* Wait for connection */ LOOK FOR "CONNECT 1200" /* 1200 baud number? */ 10 IF FOUND /* yes -- change baud rate */ See Also: GLOBAL STORE 12.89 SET_ARRAY Statement Purpose: 1. To quickly set the elements of an array to a specific value. 2. To set a range of one array equal to a range of another array. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ SET_ARRAY arrayname │ │ [ ( [ FROM dim,... ] [ TO dim,... ] ) ] = value │ │ │ │ SET_ARRAY arrayname │ │ [ ( [ FROM dim,... ] [ TO dim,... ] ) ] │ │ = arrayname [ ( [ FROM dim,... ] [ TO dim,... ] ) ] │ └──────────────────────────────────────────────────────────────────────┘ where: arrayname - may be a 1,2, or 3 dimensional array value - may be any string or numeric expression. FROM - optional clause defaults to the first element in the array TO - optional clause defaults to the last element in the array Remarks: Format 1 sets the elements of an array to a specified value. If no range is specified all the elements are set to the value. If a range is set then all the elements within the range are set. The FROM clause defines the starting indices and the TO clause defines the ending indices. Each index is never varied outside of the defined range. In the following example ... DIM myarray(10,5) SET_ARRAY myarray(FROM 2,3 TO 5,4) = 0 Elements (2,3), (2,4), (3,3), (3,4), (4,3), (4,4), (5,3), and (5,4) would all be set to 0. All other elements would remain unchanged. Format 2 sets the elements of one array to the elements of another array. In the following example: DIM myarray1(10,5) DIM myarray2(10,5) SET_ARRAY myarray1 = myarray2 The array 'myarray1' is set equal to the array 'myarray2'. If the range of the source array is smaller than the destination array, the settings are repeated. For example: DIM myarray1(10,5) DIM myarray2(6,5) SET_ARRAY myarray1 = myarray2 Elements 1,1 through 6,5 of myarray1 are set equal to the array myarray2. Elements 7,1 through 10,5 of myarray1 are set equal to elements 1,1 through 4,5 of myarray2. The FROM and TO clauses may be used to specify specific ranges. Also note that the arrays do not have to have the same amount of dimensions. For example: DIM myarray1(5,6) DIM myarray2(4) = "DOG", "CAT", "TIGER", "LION" SET_ARRAY myarray1(FROM 2,2 TO 4,4) = myarray2 FROM 1 TO 3 Array myarray1 would look like this: 0 0 0 0 0 0 0 DOG CAT TIGER 0 0 0 DOG CAT TIGER 0 0 0 DOG CAT TIGER 0 0 0 0 0 0 0 0 See Also: SEARCH_ARRAY 12.90 SHOW Statement Purpose: The SHOW Statement can be used to change the visibility state of a window or dialog item to visible. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ SHOW {DIALOG_WINDOW(winid) } │ │ {TEXT_WINDOW(winid) } │ │ │ │ SHOW {TEXT_FIELD(id) } │ │ {ENTRY_FIELD(id) } │ │ {PUSH_BUTTON(id) } │ │ {RADIO_BUTTON(id) } │ │ {CHECK_BOX(id) } │ │ {LIST_BOX(id) } │ │ {COMBINATION_BOX(id) } │ │ {GROUP_BOX(id) } │ │ {ICON_FIELD(id) } │ │ {MULTILINE_ENTRY_FIELD(id) } │ │ [ IN DIALOG_WINDOW(winid) ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: A window or dialog is specified to be invisible by using the INVISIBLE clause in the CREATE TEXT_WINDOW and CREATE DIALOG_WINDOW Statements or by using the HIDE Statement. See Also: CREATE DIALOG_WINDOW CREATE TEXT_WINDOW HIDE 12.91 SIGNAL Statement Purpose: Triggers a predefined condition. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ SIGNAL {TIMEOUT } │ │ {ESCAPE } │ └──────────────────────────────────────────────────────────────────────┘ Remarks: If a condition is triggered and trapping is enabled (see the ON Statement), control is transferred to the appropriate routine, otherwise the script is canceled. Example: WAIT FOR "TalkThru" AFTER 90 SECONDS SIGNAL TIMEOUT See Also: ON RESUME 12.92 SORT Statement Purpose: Sort an array. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ SORT array [ FROM start_row ] [ TO end_row ] │ │ [ USING option-str ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: SORT is used to rearrange the elements in an array into a specified order. One and two dimensional arrays may be sorted on up to 8 "sort keys" in ascending or descending order. For the purposes of SORT an array can be thought of as a table made up of horizontal rows and vertical columns. The first dimension in the array's DIM Statement specifies the number of rows in the array. The second dimension specifies the number of columns. A one dimensional array has one column. SORT rearranges rows -- the columns remain intact. The primary-sort-column is the column that SORT uses to determine the new order for the rows. Rows are rearranged so that the values in the primary-sort-column appear in either ascending or descending order. Up to 7 additional columns may be selected as secondary-sort-columns. They are used to break ties that occur when two or more records have the same entries in the primary-sort-column. SORT rearranges all the rows in an array within a range specified by the FROM and TO keywords. Rows outside of this range are not disturbed. If the FROM clause is omitted, the sort starts from the first row. If the TO clause is omitted the sort ends with the last row. The USING option-str clause determines the method in which the array will be sorted. The option-str is a string value that consists of a series of sort options. The sort options are specified as follows: Sort Option Name Meaning ─────────── ───────────── ──────────────────────────────────────────────── Cn Column Select Specifies that column "n" should be used as a sort key. The remaining sort options apply to this column until a new Cn option is specified. If option-str does not start with a Cn option,, column 1 will be used. Up to 8 columns may be specified in a sort. A Ascending Sort is in ascending order for the specified column. This is the default. D Descending Sort is in descending order for the specified column. T1 ASCII Sort is done using the ASCII collating order. If an element in an array is a number it is converted to a string for the purposes of the sort. T2 Dictionary Specifies that upper and lower case is ignored during the sort. If an element in an array is a number it is converted to a string for the purposes of the sort. T3 Numeric Sort in numeric order. If an element in the array is a string it is converted to a number for the purposes of the sort. On Offset n Specifies that the comparison of each item to be sorted should begin at character position "n". The default is 1. This only applies to ASCII and Dictionary sorts. Examples: Given the following array: DIM array[3,3] = "apple", "cat", 2 "orange", "dog", 2 "grape", "bird", 3.2 Sort the array in ascending order on column 1: AUTOPILOT code Returns: SORT array "apple", "cat", 2 "grape", "bird", 3.2 "orange", "dog", 2 Sort the array in ascending order on column 2: AUTOPILOT code Returns: SORT array USING "C2" "grape", "bird", 3.2 "apple", "cat", 2 "orange", "dog", 2 Sort the array in descending order, using a numeric sort, on column 3. For items with the same column three value, sort in descending order on column 2. AUTOPILOT code Returns: SORT array USING "C3T3DC2D" "grape", "bird", 3.2 "orange", "dog", 2 "apple", "cat", 2 See Also: DIM 12.93 STORE Statement Purpose: This statement will store data in the TalkThru default area in memory. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STORE <string-1> AS <string-2> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This statement stores <string-1> of data in the TalkThru default area in memory as the variable name <string-2>. It can be used to modify TalkThru defaults or as a general method of storing things for an entire TalkThru session. The same thing can be done from a menu or file selection screen via the .VSET command. The function STR_RETRIEVE can be used to find a value in the default area. Examples: The following example would modify the default DATA_DIRECTORY: STORE "C:\TALKTHRU\DATA" AS "DATA_DIRECTORY" The following syntax prompts for a password if one is not already set. SET password = STR_RETRIEVE("DATA_PASSWORD") IF NOT password BEGIN PROMPT "Enter Password " password(8) STORE password AS "DATA_PASSWORD" END SEND password, ENTER See Also: SET 12.94 STR_CHR Function Purpose: Converts an ASCII code to its character equivalent. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_CHR(<num>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This is used to convert an ASCII code to its character equivalent. Should be in the range from 1 to 255. Example: set x = STR_CHR(65) In this example, 'x' would be set to "A". 12.95 STR_CURRDIR Function Purpose: Get the current OS/2 Directory. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_CURRDIR │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Returns the OS/2 current directory. Leading and trailing backslashes are not included. Example: If the current drive/directory is C:\WP STR_CURRDIR returns "C:\WP" If the current drive/directory is C:\WP\DOC STR_CURRDIR returns "C:\WP\DOC" If the current drive/directory is C:\ (root directory) STR_CURRDIR returns "" (null string) See Also: SWAP 12.96 STR_CURRDISK Function Purpose: Get the current OS/2 Drive. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_CURRDISK │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Returns a 1 character string containing the current drive letter. Example: If the current drive/directory is C:\WP set x = STR_CURRDISK returns "C" See Also: SWAP 12.97 STR_DATE Function Purpose: Converts date information into various formats. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_DATE(n) │ │ │ │ or │ │ │ │ STR_DATE(n,datetime) │ │ │ │ where: n = 1 ==>> yymmdd │ │ 2 ==>> mm/dd/yy │ │ 3 ==>> mm-dd-yy │ │ 4 ==>> MMM dd, YYYY │ │ 5 ==>> Mm...m dd, YYYY │ │ 6 ==>> dd MMM YY │ │ 7 ==>> dd MMM YYYY │ │ │ │ datetime ==>> timestamp returned by DIR Statement. │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Format 1 is used to return the system date in the format specified. Format 2 has been added primarily to support conversion of the date value returned by the DIR Statement. See Also: STR_TIME 12.98 STR_DELETE Function Purpose: Deletes characters from a string Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_DELETE( source_str , start_num , len_num ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: STR_DELETE is used to delete len_num characters starting at position start_num in string source_str. Example: STR_DELETE("ABCDE",1,1) ; returns "BCDE" STR_DELETE("ABCDE",2,2) ; returns "ADE" STR_DELETE("ABCDE",5,1) ; returns "ABCD" STR_DELETE("ABCDE",1,6) ; returns "" 12.99 STR_ENVIRONMENT Function Purpose: Obtains a variable from the OS/2 environment area. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_ENVIRONMENT("name") │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function searches the OS/2 environment area for an entry in the form: name=var where name is the string value passed to the function. If such an entry exists, the function returns the string value var. If no entry exists, var is set to "" (null string).This can be used to obtain information loaded through the CONFIG.SYS File. WARNING: STR_ENVIRONMENT is case sensitive. Be sure that "name" is in the same case as the variable in the environment area. Example: STR_ENVIRONMENT("PATH") /* returns "C:\TALKTHRU\PROGRAMS;C:\OS/2" */ 12.100 STR_FILEPATH Function Purpose: Returns a component of a file path. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_FILEPATH (path_str, type) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: STR_FILEPATH is used to extract the selected components of a file path string. type refers to the component to be extracted. Values of type are: Type Description ──── ────────────────────────────────────────────────────────────────────── 1 Returns the drive letter followed by a colon if a drive is specified in path_str. 2 Returns the path of subdirectories,, if any,, including the trailing slash. 3 Returns the base file name without any extension. 4 Returns the file name extension,, if any,, including the leading period. A null string is returned if the chosen component is not in path-str. Examples: SET my_path = "C:\TALKTHRU\SCRIPTS\TEST.SCR" STR_FILEPATH(my_path,1) ; Returns "C:" STR_FILEPATH(my_path,2) ; Returns "\TALKTHRU\SCRIPTS\" STR_FILEPATH(my_path,3) ; Returns "TEST" STR_FILEPATH(my_path,4) ; Returns ".SCR" 12.101 STR_JLEFT Function Purpose: Left justifies a string. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_JLEFT(<string>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function is used to return a left justified string value. Example: STR_JLEFT(" XYZ ") ; returns "XYZ " 12.102 STR_JRIGHT Function Purpose: Right justifies a string. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_RIGHT(<string>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function is used to return a right justified string value. Example: STR_JRIGHT(" XYZ ") ; returns " XYZ" 12.103 STR_LEFT Function Purpose: Returns the leftmost n characters of a string. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_LEFT(<string>,<number>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <string> is any string. <number> is a number that specifies the number of characters which are to be in the result. If <number> is greater than the number of characters in <string>, the entire string is returned. If <number> <= 0, the null string (length zero) is returned. Examples: SET a = "ANY STRING" SET b = STR_LEFT(a,3) This example would set b to equal the string "ANY". SET num = 7 DISPLAY STR_LEFT("TEXT TO BE DISPLAYED", num) This example would display "TEXT TO" on the screen. See Also: STR_MID STR_RIGHT 12.104 STR_LOWER Function Purpose: Converts upper case characters to lower case characters. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_LOWER(<string>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function is used to return a string with all alphabetic characters in lower case. See Also: STR_UPPER 12.105 STR_MID Function Purpose: Returns the requested part of a string. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_MID(<string>,<n>,<m>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <string> is any string. <n> is a number that specifies the position of the starting character that is to be returned. <m> is a number that specifies the number of characters which are to be in the result. The function returns a string of length <m> characters from <string> beginning with the <n>th character. If <m> is greater than the number of characters left in <string>, the rightmost characters beginning with the <n>th character are returned. If <m> <= 0 or <n> > the length of <string>, the null string (length zero) is returned. Examples: SET a = "ANY STRING" SET b = STR_MID(a,5,3) This example would set b to equal the string "STR". SET num = 7 DISPLAY STR_MID("TEXT TO BE DISPLAYED", 5, num) This example would display " TO BE " on the screen. See Also: STR_LEFT STR_RIGHT 12.106 STR_PAD Function Purpose: Returns a string padded with a specific character. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_PAD(<string-1>,<string-2>,<n> [,<type-num>] ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <string-1> is padded with the first character of <string-2> up to a length of <n>. Padding is determined by the optional parameter type-num. type-num has the following meanings: 1 ==>> Pad on the right 2 ==>> Pad on the left 3 ==>> Pad on both sides, thus centering string-1 The default type-num is 1. If n is less than the length of string-1, no padding will occur. Examples: STR_PAD("ABCDE", " ", 10) ; returns "ABCDE " STR_PAD("ABCDE", " ", 3) ; returns "ABCDE" STR_PAD("ABCDE", "XYZ", 7) ; returns "ABCDEXX" STR_PAD("ABCDE", "X", 11 , 1) ; returns "ABCDEXXXXXXX" STR_PAD("ABCDE", "X", 11 , 2) ; returns "XXXXXXABCDE" STR_PAD("ABCDE", "X", 11 , 3) ; returns "XXXABCDEXXX" See Also: STR_REPLICATE STR_TRUNCATE 12.107 STR_REPLICATE Function Purpose: To create large string patterns. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_REPLICATE(<string>, <n> ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Returns <string> replicated <n> times. Examples: STR_REPLICATE("*", 10) ; returns "**********" STR_REPLICATE("ABC", 3) ; returns "ABCABCABC" See Also: STR_PAD 12.108 STR_RETRIEVE Function Purpose: Returns the value of a keyword within the TalkThru Customization File. Refer to the Chapter, The TalkThru Customization File for more information on Customization Variables and how they are updated. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_RETRIEVE(<string>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <string> is equal to a keyword in the TalkThru Customization File. If <string> is found in the Customization File, the characters to the right of the equals sign in the Customization File are returned. If <string> is not found, the null string (length zero) is returned. This function can be used in conjunction with the STORE Statement as a message passing facility. In searching for <string> within the Customization File, case is insignificant. NOTE: The Customization File is loaded into memory when TalkThru is executed. IF you make a change to the Customization File, you must exit TalkThru and then reenter before the change will take place. Examples: Assume the TalkThru Customization File had this line in it ... DATA_DIRECTORY=C:\TALKTHRU\DATA This example would set x to equal the string "C:\TALKTHRU\DATA". SET x = STR_RETRIEVE("DATA_DIRECTORY") See Also: STORE 12.109 STR_RIGHT Function Purpose: Returns the rightmost n characters of a string. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_RIGHT(<string>,<number>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: <string> is any string. <number> is a number that specifies the number of characters which are to be in the result. If <number> is greater than the number of characters in <string>, the entire string is returned. If <number> <= 0, the null string (length zero) is returned. Examples: SET a = "ANY STRING" SET b = STR_RIGHT(a,3) This example would set b to equal the string "ING". SET num = 9 DISPLAY STR_RIGHT("TEXT TO BE DISPLAYED", num) This example would display "DISPLAYED" on the screen. See Also: STR_LEFT STR_MID 12.110 STR_TIME Function Purpose: Converts time information into various formats. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_TIME(n) │ │ │ │ or │ │ │ │ STR_TIME(n,datetime) │ │ │ │ where : n = 1 ==>> hhmmss │ │ 2 ==>> hh:mm:ss │ │ 3 ==>> hhmmssdd │ │ 4 ==>> hh:mm:ss.dd │ │ 5 ==>> hh:mm │ │ 6 ==>> h:mm:ss pp │ │ 7 ==>> hh:mm pp │ │ │ │ datetime ==>> timestamp returned by DIR Statement. │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Format 1 is used to return the system time in the format specified. Format 2 has been added primarily to support conversion of the time value returned by the DIR Statement. See Also: STR_DATE 12.111 STR_TRANSLATE Function Purpose: Returns a string with specified characters translated. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_TRANSLATE(<string-1> , <string-2> , <string-3> ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Every character in string-2 that is found in string-1 is translated to the corresponding character in string-3. The STR_TRANSLATE Function is case sensitive. Examples: STR_TRANSLATE("Hello","abcde","12345") ; returns "H5llo" STR_TRANSLATE("Hello","lh","XY") ; returns "HeXXo" 12.112 STR_TRUNCATE Function Purpose: This function will truncate trailing spaces. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_TRUNCATE(<string>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Returns the value of <string> without any trailing spaces. Examples: STR_TRUNCATE(" XYZ ") ; returns " XYZ" See Also: STR_PAD 12.113 STR_UPPER Function Purpose: Converts lower case characters to upper case characters. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_UPPER(<string>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: This function is used to return a string with all alphabetic characters in upper case. See Also: STR_LOWER 12.114 STR_VAL Function Purpose: Converts a number to a string. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ STR_VAL(<value> [,radix] ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: STR_VAL converts the number value to a string. The optional argument radix specifies the base of value. The default radix is 10. If specified, radix must be in the range 2-36. If radix is 10 (the default) and value is negative, the first character of the stored string is the minus sign. Examples: STR_VAL(10) returns "10" STR_VAL(10,2) returns "1010" 12.115 SWAP Statement Purpose: Switches the values of two variables. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ SWAP <variable-1> [,] <variable-2> │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The value of <variable-2> is assigned to <variable-1> and the value of <variable-1> is assigned to <variable-2>. SWAP A,B is equivalent to: SET C = A SET A = B SET B = C except that SWAP is much faster. Example: IF array(i) < array(i+1) SWAP array(i) , array(i+1) 12.116 TEXT_OF Function Purpose: The TEXT_OF Function returns the text associated with a dialog control or menu item. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ TEXT_OF ( {TEXT_FIELD(id) } │ │ {ENTRY_FIELD(id) } │ │ {PUSH_BUTTON(id) } │ │ {RADIO_BUTTON(id) } │ │ {CHECK_BOX(id) } │ │ {GROUP_BOX(id) } │ │ [ IN DIALOG_WINDOW(winid) ] ) │ │ │ │ TEXT_OF ( {LIST_BOX(id) } │ │ {COMBINATION_BOX(id) } │ │ {MULTILINE_ENTRY_FIELD(id) } │ │ [ IN DIALOG_WINDOW(winid) ] │ │ [ ,<lineno> ] ) │ │ │ │ TEXT_OF ( {CHOICE(id) } [IN DIALOG_WINDOW(winid) ] │ │ {PULLDOWN(id) } [IN TEXT_WINDOW(winid) ] ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: The optional <lineno> parameter is used for LIST_BOXes, COMBINATION_BOXes and MULTILINE_ENTRY_FIELDs to return a specific line. The default is line 1 for LIST_BOXes and MULTILINE_ENTRY_FIELDs. The default for COMBINATION_BOXes is to return the text in the entry field portion of the COMBINATION_BOX (lineno = 0 will also do this). See Also: CREATE TEXT_WINDOW CREATE DIALOG_WINDOW SELECTED_LINE 12.117 UNCHECK Statement Purpose: The UNCHECK Statement allows the script to remove a check mark from in front of a menu CHOICE or to "uncheck" a RADIO_BUTTON or CHECK_BOX dialog control. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ UNCHECK {RADIO_BUTTON(id) } │ │ {CHECK_BOX(id) } │ │ [ IN DIALOG_WINDOW(winid) ] │ │ │ │ UNCHECK {CHOICE(id) } [ IN DIALOG_WINDOW(winid) ] │ │ [ IN TEXT_WINDOW(winid) ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: If a RADIO_BUTTON or CHECK_BOX is UNCHECKed, the result of the IS_CHECKED Function will be false. See Also: CHECK IS_CHECKED 12.118 VAL Function Purpose: Converts a string to a number. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ VAL(<string> [,radix] ) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: VAL converts the string to a number. The optional argument radix specifies the base of string. The default radix is 10. If specified, it must be in the range 2-36. NOTE: Since AUTOPILOT automatically converts strings to numbers as needed, the primary use of this function is for working with bases other than 10. Example: VAL(10) returns "10" VAL("1010",2) returns "10" 12.119 WAIT Statement Purpose: Causes the scripting process to pause until a specified event has occurred. Formats: ┌──────────────────────────────────────────────────────────────────────┐ │ WAIT <timeval> │ │ │ │ WAIT FOR <string> [AT <row> <col> ] │ │ [, <string-n> [AT <row> <col> ] ] │ │ [ AFTER {TIMEOUT }<statement>] │ │ [ { timeval } ] │ │ │ │ WAIT FOR <string> [ FROM <row> <col> ] │ │ [ TO <row> <col> ] │ │ [, <string-n> [ FROM <row> <col> ] ] │ │ [ TO <row> <col> ] ] │ │ [ AFTER { TIMEOUT } <statement> ] │ │ [ {<timeval>} ] │ │ │ │ WAIT FOR ACTION │ │ [ AFTER <timeval> <statement> ] │ │ │ │ WAIT UNTIL <condition> │ │ [ AFTER { TIMEOUT } <statement> ] │ │ [ {<timeval>} ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: [ {SECOND(S) } ] <timeval> = <number> [ {MINUTE(S) } ] [ { HOUR(S) } ] Format 1 causes script execution to halt for the specified time interval. Formats 2 and 3 causes script execution to halt until the specified string pattern appears on the screen. The pattern is specified in a character string form where: ? - matches any character s* - matches zero or more occurrences of character(s) s+ - matches 1 or more occurrence of character(s) A leading backslash may be used to match one of the special characters ?, *, or +. If multiple strings are supplied, the screen will be searched for a match with each of the strings in the order specified. WAIT will return the number of the string found in the FOUND Function. If the first string was found, the FOUND function would return a 1; if the third string was found the FOUND function would return a 3. If none of the strings were found, the FOUND function would return a 0. The AT clause limits the search area to the specified row and column values. The FROM and TO clauses allow you to specify a row/ column range to be searched. If neither the AT or FROM/TO clauses are specified, the entire screen will be searched. The screen will be searched continually for a match for the time specified in the AFTER clause. If the keyword TIMEOUT is used or if the AFTER clause is not specified; the screen will be searched for a match for the time indicated by the MAXWAIT value (see the SET Statement). If the string is not found on the screen within the appropriate time limit, the <statement> indicated in the AFTER clause will be executed. If the AFTER clause is not specified the ON TIMEOUT Statement will be executed (see the ON Statement). Format 4 (ACTION) waits until a selection is made from the Action Bar Menu. Action Bar Menus are defined using the ACTION_BAR_MENU clause on the CREATE TEXT_WINDOW Statement. Since this format causes the AUTOPILOT program to pause until an Action Bar Menu item is selected, it is normally used when you wish to drive your application from the Action Bar Menu. WAIT FOR ACTION has no MAXWAIT and will wait forever if no selections are made. WARNING: If multiple windows are being supported in an AUTOPILOT program, the desired window must be the CURRENT_WINDOW for all window Statements and Functions to work. See the SET CURRENT_WINDOW Statement for more information on how this is done. Format 5 uses the WAIT Statement with the UNTIL clause. This format of the WAIT Statement will wait until <condition> is TRUE (non-zero). Examples: WAIT 25.5 SECONDS WAIT FOR "TalkThru" AFTER 30 SECONDS GOTO END WAIT FOR "LOGOFF AT ??:??:??" WAIT FOR "VM READ" AT 24, 60 AFTER time_iden PERFORM any_rtn: WAIT FOR ACTION AFTER 20 MINUTES GOTO idle_rtn WAIT UNTIL QUIET(10 SECONDS) AFTER 2 MINUTES GOTO error_exit WAIT FOR "VM/CMS" , "MVS/TSO" PERFORM DEPENDING_ON FOUND vm_rtn , mvs_rtn See Also: QUIET 12.120 WHILE Statement Purpose: This function allows scripting loop control. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ WHILE <expression> │ │ │ │ <statement-1> │ │ │ │ CONTINUE_WHILE │ │ │ │ <statement-2> │ │ │ │ BREAK_WHILE │ │ │ │ <statement- n> │ │ │ │ END_WHILE │ │ │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Used to support script loop control. As long as the expression following the WHILE Statement remains true, the statements between it and an END_WHILE Statement will be executed. Nested WHILEs are supported. The BREAK_WHILE Statement causes termination of the smallest enclosing WHILE. Control passes to the statement following the END_WHILE. The CONTINUE_WHILE Statement causes control to pass to the smallest enclosing WHILE where the <expression> is evaluated again. Examples: set i = 0 WHILE i < 10 DISPLAY "Value of i = "&i set i = i + 1 END_WHILE WHILE i < 10 DISPLAY "Value of i = "&i PERFORM get_j if j = 1 BREAK_WHILE if i = 5 begin display "Mid Point" CONTINUE_WHILE end set i = i + 1 END_WHILE See Also: BREAK_WHILE END_WHILE 12.121 WINDOW_HANDLE Function Purpose: This function is used to support the ability to call functions available in Dynamic Link Libraries (DLLs). Before using this function, refer to the section, Calling DLL Functions Directly in the chapter, AUTOPILOT Statements By Category for more information on how this is used. This function allows you to retrieve the window handle of a dialog or control so that you may pass it on to a DLL function. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ WINDOW_HANDLE ( { TEXT_WINDOW(winid) } ) │ │ { DIALOG_WINDOW(winid) } │ │ │ │ WINDOW_HANDLE ( { TEXT_FIELD(id) } ) │ │ { ENTRY_FIELD(id) } │ │ { PUSH_BUTTON(id) } │ │ { RADIO_BUTTON(id) } │ │ { CHECK_BOX(id) } │ │ { LIST_BOX(id) } │ │ { COMBINATION_BOX(id) } │ │ { GROUP_BOX(id) } │ │ { ICON_FIELD(id) } │ │ { MULTILINE_ENTRY_FIELD(id) } │ │ [ IN DIALOG_WINDOW(id) ] │ └──────────────────────────────────────────────────────────────────────┘ NOTE: When passing a window handle to a DLL function, it should be declared as 'ushort' for Windows and 'ulong' for OS/2. See Also: DECLARE FUNCTION Statement 12.122 WRITE Statement Purpose: Writes data to a file. Format: ┌──────────────────────────────────────────────────────────────────────┐ │ {CSV } │ │ WRITE {LINE } <filenum> <identifier-1> │ │ {BUFFER } [ FOR <maxsize> ] │ │ [ AT <offset> [,<origin> ] ] │ │ │ │ [, <identifier-2> │ │ [ FOR <maxsize> ] │ │ [ AT <offset> [,<origin> ] ] │ │ │ │ [, . . . ] │ └──────────────────────────────────────────────────────────────────────┘ Remarks: CSV a keyword indicating that the data is to be written in as Comma Separated Values (this is the default) LINE a keyword indicating that the values are to be written followed by a carriage return BUFFER a keyword indicating that the data is to be written randomly <filenum> is the number used when the file was opened. <identifier-n> is the data item which is to be written to the file. It may be a string or a number. FOR <maxsize> limits the amount of data that will be written. Used mainly with WRITE BUFFER. AT <offset><origin> specifies a new position for the "write pointer" The file must be opened for OUTPUT or APPEND. If no keyword is specified or if the CSV keyword is specified, the data items will be written in comma separated format. Numeric items are converted to a string value and written without quotation marks. String items are written with leading and trailing quotation marks. Imbedded quotes are handled correctly. If the LINE keyword is specified, all characters in value-1 are written. A carriage return/line feed is written at the end of the WRITE Statement in both formats. If the BUFFER keyword is specified, a specific number of bytes may be written to the file without additions such as CRLF (as in WRITE LINE) or commas (as in WRITE CSV). WRITE BUFFER could also be used to write binary data since it does not write the hex 1A End-Of-File mark. READ BUFFER and WRITE BUFFER can also be used to save window images (see the PC_SCREEN function with the CHARATTR option). The FOR <maxsize> clause is normally used with the WRITE BUFFER Statement. All WRITE types allow data to be accessed "randomly" (via the AT clause) so that data may be written to any position in the file in any order. This is valid for files opened as OUTPUT or INPUT OUTPUT (files opened APPEND or INPUT APPEND always direct all writes to the end of the file). To understand random file I/O, it may help to understand the concept of a "write pointer". The "write pointer" always points to the part of the file that will be written to in the next WRITE Statement. When the file is opened for OUTPUT, the "write pointer" is initialized to point to the first byte in the file. As data is read by ensuing sequential WRITE Statements, the "write pointer" is increased by the number of bytes written. The AT <offset> [,<origin>] clause allows you to reposition the "write pointer": <offset> is the number of bytes from <origin> <origin> is a constant that defines the initial position: 0 - beginning of the file (default) 1 - current position of the "write pointer" 2 - end of file As with normal sequential writes, after a READ Statement with the AT clause is executed, the "write pointer" is increased by the number of bytes read. Examples: SET a1 = "ANY STRING" SET b1 = 45.6 WRITE filenum 12.3,STR_LEFT(a1,3),b1 WRITE filenum a1 WRITE LINE filenum "STRING CONSTANT" WRITE LINE filenum a1 WRITE LINE filenum b1 This example would write the following lines to a file. 12.3,"ANY",45.6 "ANY STRING" STRING CONSTANT ANY STRING 45.6 Write 100 bytes to a file starting at byte position 500: WRITE BUFFER xbuff FOR 100 AT 500 Write over the last 2 bytes in a file: WRITE BUFFER xbuff FOR 2 AT 2,2 See Also: CLOSE OPEN READ WRITE_POSITION 12.123 WRITE_POSITION Function Purpose: To obtain the current "write pointer". Format: ┌──────────────────────────────────────────────────────────────────────┐ │ WRITE_POSITION(<filenum>) │ └──────────────────────────────────────────────────────────────────────┘ Remarks: Returns the current position of the "write pointer" for the file indicated by filenum. See the WRITE Statement for more information on the "write pointer". Examples: set t_pointer = WRITE_POSITION(out_file See Also: READ_POSITION