home *** CD-ROM | disk | FTP | other *** search
/ HomeWare 14 / HOMEWARE14.bin / comms / icom0425.arj / SCRIPT.DOC < prev    next >
Text File  |  1994-04-25  |  597KB  |  15,163 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                   Intellicomm (TM)
  7.                                        v2.01
  8.        Copyright (C) 1991-1994 Liberation Enterprises.  All rights reserved.
  9.        ---------------------------------------------------------------------
  10.                      INTELLICOMM SCRIPT LANGUAGE DOCUMENTATION
  11.        ---------------------------------------------------------------------
  12.  
  13.      This document should be used only after you have read the script intro-
  14.      duction in SCRTUTOR.DOC (included with Intellicomm).  If you haven't,
  15.      please start there first.
  16.  
  17.      It is very important that you read the 'introduction' sections in both
  18.      the SCRIPT COMMANDS AT A GLANCE and DETAILED COMMAND SUMMARIES sections. 
  19.      After you read the introductions, you'll have no trouble understanding
  20.      this documentation.  If you skip the introductions you may have a LOT of
  21.      trouble.
  22.  
  23.                                  TABLE OF CONTENTS
  24.  
  25.  
  26.      1.  SCRIPT COMMANDS AT A GLANCE . . . . . . . . . . . . . . . . . . .   1
  27.          1.1  Introduction . . . . . . . . . . . . . . . . . . . . . . . .   1
  28.          1.2  Video (Screen) and Cursor Commands . . . . . . . . . . . . .   1
  29.          1.3  Menu Handling  . . . . . . . . . . . . . . . . . . . . . . .   3
  30.          1.4  Keyboard Input and Output  . . . . . . . . . . . . . . . . .   4
  31.          1.5  Communications . . . . . . . . . . . . . . . . . . . . . . .   5
  32.          1.6  Icom Information / Script Variables  . . . . . . . . . . . .   8
  33.          1.7  Text (String) Handling . . . . . . . . . . . . . . . . . . .   9
  34.          1.8  Math Commands  . . . . . . . . . . . . . . . . . . . . . .    10
  35.          1.9  DOS and File Input/Output Commands . . . . . . . . . . . .    11
  36.          1.10  Date and Time . . . . . . . . . . . . . . . . . . . . . .    13
  37.          1.11  Script Flow / Decision-Making . . . . . . . . . . . . . .    13
  38.          1.12  Other Useful Commands . . . . . . . . . . . . . . . . . .    14
  39.          1.13  File Tagger Commands (Advanced use only)  . . . . . . . .    15
  40.  
  41.      2.  USING THE DETAILED COMMAND SUMMARIES  . . . . . . . . . . . . .    20
  42.          2.1  COMMAND Description  . . . . . . . . . . . . . . . . . . .    20
  43.          2.2  SUMMARY Description  . . . . . . . . . . . . . . . . . . .    20
  44.               2.2.1  How to Specify Parameters (21)
  45.          2.3  ERRORLEVEL Description . . . . . . . . . . . . . . . . . .    22
  46.  
  47.      3.  DETAILED COMMAND SUMMARY  . . . . . . . . . . . . . . . . . . .    24
  48.          ADD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    24
  49.          ADDSLASH  . . . . . . . . . . . . . . . . . . . . . . . . . . .    24
  50.          ALARM . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    24
  51.          AND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    25
  52.          APPEND  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    26
  53.          APPENDS . . . . . . . . . . . . . . . . . . . . . . . . . . . .    27
  54.          APPENDSNC . . . . . . . . . . . . . . . . . . . . . . . . . . .    27
  55.          ASSIGN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    28
  56.          BEEP  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    29
  57.          BOX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    30
  58.          BOXGETS . . . . . . . . . . . . . . . . . . . . . . . . . . . .    31
  59.          CADDREC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    34
  60.          CAPCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . .    35
  61.          CAPPAUSE  . . . . . . . . . . . . . . . . . . . . . . . . . . .    36
  62.          CAPSTAMP  . . . . . . . . . . . . . . . . . . . . . . . . . . .    36
  63.          CAPPUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . .    37
  64.  
  65.  
  66.  
  67.  
  68.      Intellicomm v2.01               SCRIPT.DOC                             ii
  69.      
  70.      
  71.  
  72.          CAPPOP  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    37
  73.          CAPTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . .    38
  74.          CCLEARBUF . . . . . . . . . . . . . . . . . . . . . . . . . . .    40
  75.          CCLEARDESC  . . . . . . . . . . . . . . . . . . . . . . . . . .    40
  76.          CCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    41
  77.          CDATE2DATE  . . . . . . . . . . . . . . . . . . . . . . . . . .    41
  78.          CDATEDIFF . . . . . . . . . . . . . . . . . . . . . . . . . . .    42
  79.          CDELREC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    43
  80.          CEDITREC  . . . . . . . . . . . . . . . . . . . . . . . . . . .    44
  81.          CEMPTY  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    45
  82.          CEXPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . .    45
  83.          CFLUSH  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    47
  84.          CFORMATDESC . . . . . . . . . . . . . . . . . . . . . . . . . .    47
  85.          CGETC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    48
  86.          CGETDESC  . . . . . . . . . . . . . . . . . . . . . . . . . . .    50
  87.          CGETREC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    51
  88.          CGETS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    52
  89.          CHAT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    52
  90.          CHECKVERSION  . . . . . . . . . . . . . . . . . . . . . . . . .    53
  91.          CHDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    54
  92.          CIMPORTNEW  . . . . . . . . . . . . . . . . . . . . . . . . . .    54
  93.          CIMPORTTEXT . . . . . . . . . . . . . . . . . . . . . . . . . .    55
  94.          CLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    56
  95.          CNOTEREC  . . . . . . . . . . . . . . . . . . . . . . . . . . .    56
  96.          COPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    57
  97.          COPY  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    59
  98.          CPACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    60
  99.          CPURGE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    60
  100.          CPUTDESC  . . . . . . . . . . . . . . . . . . . . . . . . . . .    61
  101.          CPUTREC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    63
  102.          CSAVEBMARK  . . . . . . . . . . . . . . . . . . . . . . . . . .    63
  103.          CSAVEVDATE  . . . . . . . . . . . . . . . . . . . . . . . . . .    64
  104.          CSEEK . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    64
  105.          CSETSORT  . . . . . . . . . . . . . . . . . . . . . . . . . . .    65
  106.          CTAGALL . . . . . . . . . . . . . . . . . . . . . . . . . . . .    66
  107.          CTAGREC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    66
  108.          CTELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    68
  109.          CURSORLARGE . . . . . . . . . . . . . . . . . . . . . . . . . .    69
  110.          CURSORSMALL . . . . . . . . . . . . . . . . . . . . . . . . . .    69
  111.          CURSOROFF . . . . . . . . . . . . . . . . . . . . . . . . . . .    69
  112.          CURSORON  . . . . . . . . . . . . . . . . . . . . . . . . . . .    69
  113.          CURSORPOP . . . . . . . . . . . . . . . . . . . . . . . . . . .    70
  114.          CURSORPUSH  . . . . . . . . . . . . . . . . . . . . . . . . . .    70
  115.          DATE2CDATE  . . . . . . . . . . . . . . . . . . . . . . . . . .    71
  116.          DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    71
  117.          DEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    72
  118.          DELAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    73
  119.          DELAYNC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    73
  120.          DEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    74
  121.          DELETE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    74
  122.          DIAL  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    75
  123.          DIREXIST  . . . . . . . . . . . . . . . . . . . . . . . . . . .    77
  124.          DISKFIND  . . . . . . . . . . . . . . . . . . . . . . . . . . .    77
  125.          DISKFREE  . . . . . . . . . . . . . . . . . . . . . . . . . . .    78
  126.          DIV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    79
  127.          DOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    79
  128.          DOWNLOAD  . . . . . . . . . . . . . . . . . . . . . . . . . . .    80
  129.          EDIT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    81
  130.  
  131.  
  132.  
  133.  
  134.      Intellicomm v2.01               SCRIPT.DOC                            iii
  135.      
  136.      
  137.  
  138.          ERASELINE . . . . . . . . . . . . . . . . . . . . . . . . . . .    82
  139.          EXEC  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    83
  140.          EXIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    85
  141.          EXIT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    86
  142.          FCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    86
  143.          FFLUSH  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    87
  144.          FGETC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    87
  145.          FILEMAN . . . . . . . . . . . . . . . . . . . . . . . . . . . .    89
  146.          FILESIZE  . . . . . . . . . . . . . . . . . . . . . . . . . . .    89
  147.          FINDFIRST . . . . . . . . . . . . . . . . . . . . . . . . . . .    90
  148.          FINDNEXT  . . . . . . . . . . . . . . . . . . . . . . . . . . .    91
  149.          FNSTRIP . . . . . . . . . . . . . . . . . . . . . . . . . . . .    92
  150.          FOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    93
  151.          FPUTC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    96
  152.          FPUTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    96
  153.          FPUTSNC . . . . . . . . . . . . . . . . . . . . . . . . . . . .    97
  154.          FSEEK . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    97
  155.          FTELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    99
  156.          GETENV  . . . . . . . . . . . . . . . . . . . . . . . . . . . .    99
  157.          GETFNAME  . . . . . . . . . . . . . . . . . . . . . . . . . . .   100
  158.          GETS  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   101
  159.          GETSXY  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   101
  160.          GOSUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   103
  161.          RETURN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   103
  162.          GOTO  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   104
  163.          GOTOXY  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   105
  164.          HANGUP  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   105
  165.          HELP  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   106
  166.          HELPFIND  . . . . . . . . . . . . . . . . . . . . . . . . . . .   107
  167.          IF  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   107
  168.           ELSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   107
  169.           ENDIF  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   107
  170.          INC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   111
  171.          INITMODEM . . . . . . . . . . . . . . . . . . . . . . . . . . .   111
  172.          INKEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   112
  173.          INKEYT  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   112
  174.          INKEYW  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   112
  175.          KBFLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . .   114
  176.          LIST  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   115
  177.          LOADBIF . . . . . . . . . . . . . . . . . . . . . . . . . . . .   116
  178.          LOADINI . . . . . . . . . . . . . . . . . . . . . . . . . . . .   116
  179.          LOCATEFILE  . . . . . . . . . . . . . . . . . . . . . . . . . .   117
  180.          LOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   117
  181.          LOGCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   118
  182.          MENUBAR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   118
  183.          MENUBOXH  . . . . . . . . . . . . . . . . . . . . . . . . . . .   119
  184.          MENUBOXV  . . . . . . . . . . . . . . . . . . . . . . . . . . .   120
  185.          MENUDEFINE  . . . . . . . . . . . . . . . . . . . . . . . . . .   122
  186.          MENUHLP . . . . . . . . . . . . . . . . . . . . . . . . . . . .   123
  187.          MENUITEMSTAT  . . . . . . . . . . . . . . . . . . . . . . . . .   123
  188.          MKDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   124
  189.          MSGOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . .   125
  190.          MSGCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   125
  191.          MSGWIND . . . . . . . . . . . . . . . . . . . . . . . . . . . .   125
  192.  
  193.  
  194.  
  195.  
  196.      Intellicomm v2.01               SCRIPT.DOC                             iv
  197.      
  198.      
  199.  
  200.          MUL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   126
  201.          NEWAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . .   126
  202.          NOTEXIST  . . . . . . . . . . . . . . . . . . . . . . . . . . .   129
  203.          OFFLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . .   129
  204.          ONLINE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   130
  205.          OR  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   130
  206.          PAUSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   130
  207.          PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   131
  208.          PRINTNC . . . . . . . . . . . . . . . . . . . . . . . . . . . .   133
  209.          PRINTRAW  . . . . . . . . . . . . . . . . . . . . . . . . . . .   133
  210.          PORT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   134
  211.          REDIAL  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   135
  212.          RELOADSCRIPT  . . . . . . . . . . . . . . . . . . . . . . . . .   137
  213.          RENAME  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   137
  214.          RENUMBER  . . . . . . . . . . . . . . . . . . . . . . . . . . .   138
  215.          RETURN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   139
  216.          RMDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   139
  217.          RXFLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . .   140
  218.          SAVEBIF . . . . . . . . . . . . . . . . . . . . . . . . . . . .   140
  219.          SAVEINI . . . . . . . . . . . . . . . . . . . . . . . . . . . .   142
  220.          SCAPTURE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   143
  221.          SCREENBLANK . . . . . . . . . . . . . . . . . . . . . . . . . .   143
  222.          SCREENRESTORE . . . . . . . . . . . . . . . . . . . . . . . . .   143
  223.          SCRIPT  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   144
  224.          SCROLL  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   145
  225.          SCROLLBACK  . . . . . . . . . . . . . . . . . . . . . . . . . .   146
  226.          SEND  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   146
  227.          SENDNC  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   146
  228.          SENDNCP . . . . . . . . . . . . . . . . . . . . . . . . . . . .   146
  229.          SENDNP  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   146
  230.          SENDBIF . . . . . . . . . . . . . . . . . . . . . . . . . . . .   148
  231.          SENDKEY . . . . . . . . . . . . . . . . . . . . . . . . . . . .   149
  232.          SENDBREAK . . . . . . . . . . . . . . . . . . . . . . . . . . .   151
  233.          SETENV  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   152
  234.          SETCOMM . . . . . . . . . . . . . . . . . . . . . . . . . . . .   153
  235.          SHL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   155
  236.          SHOWWHENS . . . . . . . . . . . . . . . . . . . . . . . . . . .   155
  237.          SHR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   155
  238.          STAMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   156
  239.          STRBLANK  . . . . . . . . . . . . . . . . . . . . . . . . . . .   156
  240.          STRCHR  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   157
  241.          STRCHRI . . . . . . . . . . . . . . . . . . . . . . . . . . . .   157
  242.          STRCPY  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   158
  243.          STRDEL  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   159
  244.          STRINS  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   159
  245.          STRIPSLASH  . . . . . . . . . . . . . . . . . . . . . . . . . .   160
  246.          STRITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . .   161
  247.          STRLEN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   162
  248.          STRLOWER  . . . . . . . . . . . . . . . . . . . . . . . . . . .   163
  249.          STRCAT  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   163
  250.          STRPAD  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   163
  251.          STRPADL . . . . . . . . . . . . . . . . . . . . . . . . . . . .   164
  252.          STRSET  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   165
  253.          STRPOS  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   165
  254.  
  255.  
  256.  
  257.  
  258.      Intellicomm v2.01               SCRIPT.DOC                              v
  259.      
  260.      
  261.  
  262.          STRRCHR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   167
  263.          STRRCHRI  . . . . . . . . . . . . . . . . . . . . . . . . . . .   167
  264.          STRREPLACE  . . . . . . . . . . . . . . . . . . . . . . . . . .   168
  265.          STRSTRIP  . . . . . . . . . . . . . . . . . . . . . . . . . . .   168
  266.          STRBTRIM  . . . . . . . . . . . . . . . . . . . . . . . . . . .   169
  267.          STRLTRIM  . . . . . . . . . . . . . . . . . . . . . . . . . . .   169
  268.          STRTRIM . . . . . . . . . . . . . . . . . . . . . . . . . . . .   169
  269.          STRUPPER  . . . . . . . . . . . . . . . . . . . . . . . . . . .   169
  270.          SUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   170
  271.          SUBSTR  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   170
  272.          SWITCH  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   171
  273.           CASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   171
  274.           ENDCASE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   171
  275.           DEFAULT  . . . . . . . . . . . . . . . . . . . . . . . . . . .   171
  276.           ENDSWITCH  . . . . . . . . . . . . . . . . . . . . . . . . . .   171
  277.          SYSTEM  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   173
  278.          TAGGER  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   173
  279.          TERMINAL  . . . . . . . . . . . . . . . . . . . . . . . . . . .   174
  280.          TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   176
  281.          TIMERTOTAL  . . . . . . . . . . . . . . . . . . . . . . . . . .   176
  282.          TIMEUP  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   177
  283.          TONE  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   177
  284.          TXFLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . .   178
  285.          UPDATEDNDX  . . . . . . . . . . . . . . . . . . . . . . . . . .   179
  286.          UPLOAD  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   179
  287.          VARIABLE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   181
  288.          VPUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   181
  289.          VGETCHR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   182
  290.          VGETCHRS  . . . . . . . . . . . . . . . . . . . . . . . . . . .   183
  291.          VPOP  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   185
  292.          WAITFOR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   185
  293.          WAITUNTIL . . . . . . . . . . . . . . . . . . . . . . . . . . .   186
  294.          WHEN  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   187
  295.          WHILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   189
  296.           BREAK  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   189
  297.           CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . .   189
  298.           ENDWHILE . . . . . . . . . . . . . . . . . . . . . . . . . . .   189
  299.          WINDOW  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   191
  300.          WNDCLOSE  . . . . . . . . . . . . . . . . . . . . . . . . . . .   192
  301.          WNDOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . .   192
  302.          XOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   193
  303.  
  304.      A.  SYSTEM VARIABLES  . . . . . . . . . . . . . . . . . . . . . . .   195
  305.          A.1  Introduction . . . . . . . . . . . . . . . . . . . . . . .   195
  306.               A.1.1  BIF and INI (main setup) Variables  (195); A.1.2 
  307.               Changing System Variables (195); A.1.3  READ ONLY System
  308.               Variables (196)
  309.          A.2  System Variable Summary  . . . . . . . . . . . . . . . . .   197
  310.          $ALARMS . . . . . . . . . . . . . . . . . . . . . . . . . . . .   197
  311.          $BAR_COLOR  . . . . . . . . . . . . . . . . . . . . . . . . . .   197
  312.          $BBS_AREA . . . . . . . . . . . . . . . . . . . . . . . . . . .   197
  313.          $BETA_VERSION . . . . . . . . . . . . . . . . . . . . . . . . .   197
  314.          $BIF_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   197
  315.          $BIF_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . .   197
  316.  
  317.  
  318.  
  319.  
  320.      Intellicomm v2.01               SCRIPT.DOC                             vi
  321.      
  322.      
  323.  
  324.          $BOLD_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  325.          $BORDER_COLOR . . . . . . . . . . . . . . . . . . . . . . . . .   198
  326.          $BSSWAP . . . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  327.          $CAP_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  328.          $CAP_STAT . . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  329.          $CAREA_FLD  . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  330.          $CARRIER  . . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  331.          $CAT_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   198
  332.          $CAT_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . .   199
  333.          $CCDATE_FLD . . . . . . . . . . . . . . . . . . . . . . . . . .   199
  334.          $CDAY_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . .   199
  335.          $CFDATE_FLD . . . . . . . . . . . . . . . . . . . . . . . . . .   199
  336.          $CFLAG_FLD  . . . . . . . . . . . . . . . . . . . . . . . . . .   199
  337.          $CLOC_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . .   200
  338.          $CNAME_FLD  . . . . . . . . . . . . . . . . . . . . . . . . . .   200
  339.          $COM_PORT . . . . . . . . . . . . . . . . . . . . . . . . . . .   200
  340.          $CPRIORITY_FLD  . . . . . . . . . . . . . . . . . . . . . . . .   200
  341.          $COM_SPEED  . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  342.          $CREC_STAT  . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  343.          $CSIZE_FLD  . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  344.          $CSORT_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  345.          $CSORT_ORDER  . . . . . . . . . . . . . . . . . . . . . . . . .   201
  346.          $CTAG_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  347.          $CTOTAL . . . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  348.          $CVTOTAL  . . . . . . . . . . . . . . . . . . . . . . . . . . .   201
  349.          $CURDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  350.          $CURDRIVE . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  351.          $DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  352.          $DAY  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  353.          $DL_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  354.          $DL_PROTOCOL  . . . . . . . . . . . . . . . . . . . . . . . . .   202
  355.          $DOORWAY  . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  356.          $DOW  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  357.          $DSEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  358.          $ECHO . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   202
  359.          $ERRORLEVEL . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  360.          $FARCH  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  361.          $FDATE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  362.          $FDAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  363.          $FHIDDEN  . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  364.          $FHOUR  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  365.          $FMIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  366.          $FMONTH . . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  367.          $FRDONLY  . . . . . . . . . . . . . . . . . . . . . . . . . . .   203
  368.          $FSEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  369.          $FSIZE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  370.          $FSUBDIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  371.          $FSYSTEM  . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  372.          $FTIME  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  373.          $FVOLID . . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  374.          $FULL_SCRIPT_NAME . . . . . . . . . . . . . . . . . . . . . . .   204
  375.          $FYEAR  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   204
  376.          $HOME_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  377.          $HOTKEY_1 . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  378.  
  379.  
  380.  
  381.  
  382.      Intellicomm v2.01               SCRIPT.DOC                            vii
  383.      
  384.      
  385.  
  386.          $HOTKEY_2 . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  387.          $HOTKEY_3 . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  388.          $HOTKEY_4 . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  389.          $HOTKEY_5 . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  390.          $HOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  391.          $HSEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  392.          $INI_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  393.          $KEY_ALTQ . . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  394.          $KEY_CHECK  . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  395.          $KEY_FILTER . . . . . . . . . . . . . . . . . . . . . . . . . .   205
  396.          $LINEFEED . . . . . . . . . . . . . . . . . . . . . . . . . . .   206
  397.          $LST_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   206
  398.          $MAJOR_VERSION  . . . . . . . . . . . . . . . . . . . . . . . .   206
  399.          $MENUSELECTION  . . . . . . . . . . . . . . . . . . . . . . . .   206
  400.          $MIN  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   206
  401.          $MINOR_VERSION  . . . . . . . . . . . . . . . . . . . . . . . .   206
  402.          $MONTH  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   206
  403.          $MSG_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   206
  404.          $MSG_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . .   207
  405.          $NORM_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . .   207
  406.          $PASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . .   207
  407.          $OPSYSTYPE  . . . . . . . . . . . . . . . . . . . . . . . . . .   207
  408.          $PRN  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   207
  409.          $REP_DIR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   207
  410.          $REP_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . .   208
  411.          $RXCNT  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   208
  412.          $SCRIPT_DIR . . . . . . . . . . . . . . . . . . . . . . . . . .   208
  413.          $SCRIPT_NAME  . . . . . . . . . . . . . . . . . . . . . . . . .   208
  414.          $SCRN_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . .   208
  415.          $SCRN_HEIGHT  . . . . . . . . . . . . . . . . . . . . . . . . .   208
  416.          $SCRN_WIDTH . . . . . . . . . . . . . . . . . . . . . . . . . .   208
  417.          $SCRN_WRAP  . . . . . . . . . . . . . . . . . . . . . . . . . .   208
  418.          $SCRN_X . . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  419.          $SCRN_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  420.          $SEC  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  421.          $SEND_CR  . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  422.          $SOUND  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  423.          $STAT_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  424.          $STAT_ON  . . . . . . . . . . . . . . . . . . . . . . . . . . .   209
  425.          $TERM_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . .   210
  426.          $TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   210
  427.          $TSEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   210
  428.          $TXCNT  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  429.          $UL_PATH  . . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  430.          $UL_PROTOCOL  . . . . . . . . . . . . . . . . . . . . . . . . .   211
  431.          $VIEW_DATE  . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  432.          $WND_BTM  . . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  433.          $WND_HEIGHT . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  434.          $WND_LEFT . . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  435.          $WND_RIGHT  . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  436.          $WND_TOP  . . . . . . . . . . . . . . . . . . . . . . . . . . .   211
  437.          $WND_WIDTH  . . . . . . . . . . . . . . . . . . . . . . . . . .   212
  438.          $YEAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   212
  439.  
  440.  
  441.  
  442.  
  443.      Intellicomm v2.01               SCRIPT.DOC                           viii
  444.      
  445.      
  446.  
  447.      B.  BIF VARIABLES (Advanced Users Only) . . . . . . . . . . . . . .   213
  448.  
  449.      C.  MAIN SETUP VARIABLES (Advanced Users Only)  . . . . . . . . . .   216
  450.  
  451.      D.  COLOR CODES . . . . . . . . . . . . . . . . . . . . . . . . . .   224
  452.          D.1  Using Color Variables  . . . . . . . . . . . . . . . . . .   225
  453.  
  454.      E.  ASCII CODES . . . . . . . . . . . . . . . . . . . . . . . . . .   225
  455.          E.1  How to Use the ASCII Table . . . . . . . . . . . . . . . .   226
  456.  
  457.      F.  KEYBOARD CODES  . . . . . . . . . . . . . . . . . . . . . . . .   228
  458.          F.1  How to use the Keyboard Codes  . . . . . . . . . . . . . .   228
  459.          F.2  Example of Usage . . . . . . . . . . . . . . . . . . . . .   229
  460.  
  461.      G.  SCRIPT ERROR MESSAGES/SOLUTIONS . . . . . . . . . . . . . . . .   233
  462.  
  463.      H.  SCRIPT MEMORY LIMITS  . . . . . . . . . . . . . . . . . . . . .   238
  464.          H.1  Developing Large Scripts . . . . . . . . . . . . . . . . .   238
  465.  
  466.      I.  CREATING SCRIPTS FOR PUBLIC DISTRIBUTION  . . . . . . . . . . .   239
  467.  
  468.      J.  CHANGES FROM THE V1.00 SCRIPT LANGUAGE  . . . . . . . . . . . .   241
  469.          J.1  Version 2 Syntax Changes . . . . . . . . . . . . . . . . .   241
  470.          J.2  Version 2 Command Changes  . . . . . . . . . . . . . . . .   241
  471.          J.3  Icom v1.00 Script Conversion . . . . . . . . . . . . . . .   243
  472.  
  473.  
  474.  
  475.  
  476.      Intellicomm v2.01               SCRIPT.DOC                              1
  477.      
  478.      
  479.  
  480.                           1.  SCRIPT COMMANDS AT A GLANCE
  481.  
  482.      1.1  Introduction
  483.  
  484.      This section contains a short description of all the commands available
  485.      in the Intellicomm script language, grouped by command type/purpose.  Use
  486.      this section to locate the command you need, then look up the command in
  487.      the DETAILED COMMAND SUMMARY (which is sorted alphabetically, by script
  488.      command) for detailed explanations and examples.  If you're viewing this
  489.      document in the Icom File Viewer, you can quickly locate the Detailed
  490.      Summary of a command by pressing [Alt-F] (Find), entering the command of
  491.      interest followed by an underscore (PRINT_) then searching DOWNWARDS. 
  492.      Each command in the Detailed Summary is followed by a line of underscores
  493.      to allow you to locate a specific detailed command summary quickly.
  494.  
  495.      Items beginning with a dollar sign ($) below are not script commands, but
  496.      rather are "System Variables" which can be used with other commands in
  497.      the same way that constant paremeters are used (e.g. SEND $PASSWORD, as
  498.      was used in the introduction of SCRTUTOR.DOC).  Some System Variables are
  499.      "read only" (for informational purposes) and some are "read/write" (you
  500.      can assign other values to them to change the way Icom works).  The
  501.      System Variables are described in detail in the SYSTEM VARIABLES Appendix
  502.      following the command summaries.  Again, each System Variable in the
  503.      Detailed Summary is followed by a line of underscores to allow you to
  504.      find the Detailed Summary quickly.
  505.  
  506.      It is not advised that you attempt to memorize anything below.  The idea
  507.      is to just give this section a quick browse every once and a while until
  508.      you're generally familiar with what is available -- so you'll know what
  509.      commands (and what type of commands) exist when a need arises later.
  510.  
  511.      Immediately skip over commands/variables (or entire sections) you don't
  512.      anticipate having a need for.... The list is long, and it's important
  513.      that you make it right through the list, at least once.  Keep in mind
  514.      that most script writers will only need about 10% of the script commands
  515.      -- don't concern yourself with what you don't anticipate needing.
  516.  
  517.      1.2  Video (Screen) and Cursor Commands
  518.  
  519.      BOX           displays a box (with border and optional title) on the
  520.                    video display.
  521.      CLS           clears the terminal screen or current WINDOW to a specific
  522.                    color, or to the current screen color ($SCRN_COLOR).
  523.      CURSORLARGE   makes the cursor large (half character height).
  524.      CURSORSMALL   makes the cursor small (underline).
  525.      CURSORON      displays the screen cursor, if hidden.
  526.      CURSORONOFF   turns the cursor on or off.  This command (as opposed to
  527.                    CURSORON/CURSOROFF) is intended to be used with a variable
  528.                    ('CURSORONOFF stat' or the like, where 'stat' is a variable
  529.                    holding either 0 or 1).
  530.      CURSOROFF     hides the screen cursor.
  531.      CURSORPUSH    saves the current cursor size, location, and on/off status
  532.                    for later use with CURSORPOP.
  533.      CURSORPOP     restores the cursor to the size, location and on/off status
  534.  
  535.  
  536.  
  537.  
  538.      Intellicomm v2.01               SCRIPT.DOC                              2
  539.      
  540.      
  541.  
  542.                    it had when CURSORPUSH was last called.
  543.      ERASELINE     clears a given screen line (row) to a given color, does not
  544.                    move the cursor (use GOTOXY after ERASELINE to move the
  545.                    cursor to the blank line, if desired).
  546.      GOTOXY        moves the screen cursor to specific X/Y coordinates
  547.                    relative to the top corner of the current WINDOW.
  548.      MSGOPEN       displays a message in a centered box on the screen.
  549.      MSGCLOSE      closes the message box opened with MSGOPEN.
  550.      MSGWIND       displays a message in a box, pauses, closes the message
  551.                    box.
  552.      PRINT         displays text in the current video WINDOW using the current
  553.                    $SCRN_COLOR color, adds a CR/LF (which moves the cursor to
  554.                    the beginning of the next line).
  555.      PRINTNC       displays text in the current video WINDOW using the current
  556.                    $SCRN_COLOR color.  Similar to PRINT, but doesn't add a
  557.                    CR/LF (NC stands for 'N'o 'C'arriage return).
  558.      PRINTRAW      writes directly to the video display (ignoring the current
  559.                    WINDOW), using a specific color.  Much faster than
  560.                    PRINT/PRINTNC or PAUSE.
  561.      SCREENBLANK   activates the Icom screen blanker, if the user has screen
  562.                    blanking activated in the Icom main setup.  Screen blanking
  563.                    is done by Icom automatically even when a script is running
  564.                    (as long as $KEY_CHECK is turned on), but if you want to
  565.                    force the screen to blank at some point, before waiting for
  566.                    the usual timeout, you can use this command.
  567.      SCREENRESTORE restores the screen, if blanked.  Again, Icom automatically
  568.                    unblanks the screen by itself in most cases, when your
  569.                    script does something that the user must participate in
  570.                    (such as operating a menu, or getting input, etc).  But you
  571.                    can always ensure that the screen is not blanked with this
  572.                    command if need be, before important operations.
  573.      SCROLL        scrolls a given area of the video screen up or down, or
  574.                    clears an area to a specific color.
  575.      VGETCHR       gets the video screen character at the current cursor
  576.                    position, stores it in a variable.
  577.      VGETCHRS      gets a given number of characters from the video screen (at
  578.                    specific x/y coordinates) and stores them in a variable.
  579.      VPUSH         saves an area of the screen (or the whole screen),
  580.                    including color data, for later use with VPOP.
  581.      VPOP          restores the screen saved by the last VPUSH.
  582.      WINDOW        defines a new screen window (given screen x1/y1, x2,y2
  583.                    coordinates) or restores the terminal to full-screen if no
  584.                    coordinates are specified.  Data from the modem, and text
  585.                    you print with the PRINT, PRINTNC, and PAUSE commands will
  586.                    stay within the current WINDOW coordinates.
  587.      WNDOPEN       opens a display window (box) on the screen, saving all
  588.                    screen attributes.  A simple call to WNDCLOSE puts
  589.                    everything back the way it was.
  590.      WNDCLOSE      Removes from the video display the last window opened with
  591.                    WNDOPEN.
  592.      $BAR_COLOR    the color defined in the Icom main setup for menu hilight
  593.                    bars.
  594.      $BOLD_COLOR   'hotkeys' color (menus) and bold text color.
  595.      $BORDER_COLOR color used for box borders.
  596.  
  597.  
  598.  
  599.  
  600.      Intellicomm v2.01               SCRIPT.DOC                              3
  601.      
  602.      
  603.  
  604.      $NORM_COLOR   color used for regular text in boxes/menus.
  605.      $SCRN_COLOR   the CURRENT terminal screen color (at the positon of the
  606.                    cursor).  NOTE: BBS ANSI codes can change $SCRN_COLOR.
  607.      $SCRN_HEIGHT  total number of rows (top to bottom) on the real screen,
  608.                    ignoring the current WINDOW.
  609.      $SCRN_WIDTH   total number of columns (left to right) on the real screen,
  610.                    ignoring the current WINDOW.
  611.      $SCRN_WRAP    if non-zero, lines within the current WINDOW (or terminal
  612.                    screen) are wrapped to the next screen line when they reach
  613.                    the end of the window.  If zero, lines are truncated (cut)
  614.                    when they reach the end of the window.  NOTE: BBS ANSI
  615.                    codes can change the status of $SCRN_WRAP.
  616.      $SCRN_X       current column (x position) of the screen cursor.
  617.      $SCRN_Y       current row (y position) of the screen cursor.  NOTE: BBS
  618.                    ANSI codes can change the $SCRN_X and $SCRN_Y positions.
  619.      $STAT_COLOR   status line color.
  620.      $STAT_ON      reports the state of the status line (off is 0, on is 1)
  621.                    and allows you to turn it on and off (ASSIGN $STAT_ON 0
  622.                    turns it off, ASSIGN $STAT_ON 1 turns it on).
  623.      $TERM_COLOR   the DEFAULT terminal screen color, as defined in the Icom
  624.                    main setup.  After BBS ANSI codes have changed your screen
  625.                    color, ASSIGN $SCRN_COLOR $TERM_COLOR to set it back to the
  626.                    default color.
  627.      $WND_TOP      the top screen line of the current WINDOW.
  628.      $WND_BTM      the bottom screen line of the current WINDOW.
  629.      $WND_LEFT     the left screen row of the current WINDOW. 
  630.      $WND_RIGHT    the right screen row of the curren WINDOW.
  631.      $WND_WIDTH    the width (number of screen columns available left to
  632.                    right) of the current screen WINDOW.
  633.      $WND_HEIGHT   the height (number of screen rows available top to bottom)
  634.                    of the current screen WINDOW.
  635.  
  636.      1.3  Menu Handling
  637.  
  638.      MENUBAR      displays the currently defined menu, in 'bar menu' format.
  639.      MENUBOXH     displays the currently defined menu in 'box menu' format. 
  640.                   Menu items are displayed Horizontally in the box.
  641.      MENUBOXV     displays the currently defined menu in 'box menu' format. 
  642.                   Menu items are displayed Vertically in the box.
  643.      MENUDEFINE   define a menu for use by MENUBAR, MENUBOXH, MENUBOXV.
  644.      MENUITEMSTAT hide, disable, or unhide/enable one given menu item, in the
  645.                   currently defined menu.
  646.      MENUHLP      attaches a line of help to a given menu item.  On horizontal
  647.                   menus (MENUBAR or MENUBOXH) the help line is displayed under
  648.                   the first menu item as in the Icom Job Directory and BBS
  649.                   Directory bottom menus (when you press [Left] or [Right] the
  650.                   help line changes to the selected item).  On vertical menus
  651.                   (MENUBOXV) the help line is displayed on the bottom screen
  652.                   line.
  653.      $MENUSELECTION is set to the menu item number selected by the user (or 0
  654.                     if [Esc] is pressed) after MENUBAR, MENUBOXH or MENUBOXV.
  655.  
  656.  
  657.  
  658.  
  659.      Intellicomm v2.01               SCRIPT.DOC                              4
  660.      
  661.      
  662.  
  663.      1.4  Keyboard Input and Output
  664.  
  665.      BOXGETS     displays a box centered on the screen, with optional box
  666.                  title and information line, offers an optional 'default' to
  667.                  the user then gets input (a given number or characters) from
  668.                  the keyboard allowing use of several editing keys ([Del],
  669.                  [Ins], [Left], [Right], [Home], [End], etc) to edit the
  670.                  input.
  671.      GETS        offers an optional default and gets a line of text of a given
  672.                  length from the keyboard.  Similar to BOXGETS, but GETS
  673.                  doesn't display a box.  The [Enter] or [Esc] key, or
  674.                  left/right mouse button which signify Enter and Esc, must be
  675.                  pressed to terminate both BOXGETS and GETS.
  676.      GETSXY      same as GETS above, but GETSXY gets text at a specific screen
  677.                  X,Y coordinate.
  678.      INKEY       gets a single keystroke from the keyboard (any key; Alt-keys,
  679.                  Function keys, regular keys, etc) and stores the value of the
  680.                  key in a variable.  See the KEYBOARD CODES appendix for key
  681.                  values.  This command doesn't WAIT for a keystroke; it simply
  682.                  checks for one and stores it if one is waiting.  You'd use
  683.                  this one in a WHILE 'loop', if you wanted to do something
  684.                  while waiting for a keystroke... such as updating a clock, or
  685.                  counting something, etc.  Use INKEYW to halt script execution
  686.                  and wait for a single keypress.
  687.      INKEYT      same as INKEY above, but INKEYT waits a specified 'Timeout'
  688.                  period for a key to be pressed, and gives up if no keys are
  689.                  pressed in time.
  690.      INKEYW      same as INKEY above, but waits until a key is pressed. 
  691.                  Similar to the PAUSE command but INKEYW (and INKEY) stores
  692.                  the key code of the key pressed (i.e. you can check it to see
  693.                  what the user entered) in a given variable.
  694.      PAUSE       displays an optional message, then pauses for a keystroke
  695.                  from the user.  The key pressed is discarded.
  696.      SENDKEY     sends (simulates) one or more specific keystrokes to the Icom
  697.                  terminal key handler.  Depending on the key(s) you send, this
  698.                  may pop up an Icom menu and select something, or may be sent
  699.                  to the BBS -- whatever would happen if you pressed the key
  700.                  from Terminal mode.  If "Doorway Mode" is on, ALL keys other
  701.                  than [Alt-=] (doorway mode on/off) are sent to the BBS.
  702.      $DOORWAY    the current status of 'Doorway Mode'.  0 = Off, 1 = On.  If
  703.                  $DOORWAY is ON (non-zero), the regular Icom hotkeys ([Alt-Z]
  704.                  to pop up the terminal menu, etc) are sent to the BBS instead
  705.                  of performing their usual function.  Doorway mode is only of
  706.                  use only when $KEY_CHECK (see below) is non-zero, and only
  707.                  with a BBS function or BBS DOOR that supports doorway codes
  708.                  and recognizes the extended key codes.  Doorway codes are
  709.                  often supported in online information systems (online
  710.                  encyclopedias, etc) to allow a more advanced user interface
  711.                  with function keys and support for the [Alt] keys, etc.
  712.      $HOTKEY_?   the ? must be replaced with a number from 1 through 5
  713.                  ($HOTKEY_1, $HOTKEY_2 ... to $HOTKEY_5).  These hotkeys, if
  714.                  defined, are watched for by BOXGETS, GETS, and GETSXY to
  715.                  allow you to cancel input when specific keys are pressed
  716.                  WHILE the user is entering something in the input field.  For
  717.  
  718.  
  719.  
  720.  
  721.      Intellicomm v2.01               SCRIPT.DOC                              5
  722.      
  723.      
  724.  
  725.                  example, the input box Intellicomm displays when prompting
  726.                  for filenames to UPLOAD allows the user to press the [Alt-F]
  727.                  key to display the 'file picker' instead of entering
  728.                  filenames manually.  You can do similar things with your own
  729.                  BOXGETS/GETS/GETSXY input prompts by using the $HOTKEY_?
  730.                  variables.  See the KEYBOARD CODES appendix for a list of
  731.                  extended keys you can ASSIGN to these hotkeys.  Also see the
  732.                  BOXGETS detailed summary for an example of usage.
  733.      $KEY_CHECK  this goes one step further than $DOORWAY, and determines
  734.                  whether ANY keys will be processed by Intellicomm at all.  If
  735.                  $KEY_CHECK is set to zero (0), it's up to you to use INKEY or
  736.                  INKEYW to process ALL user keystrokes (please see the notes
  737.                  in $KEY_ALTQ below).  $KEY_CHECK is automatically turned back
  738.                  on (set to 1) when the script processor exits.
  739.      $KEY_FILTER similar to the $HOTKEY_? variables, this is used with
  740.                  GETS/GETSXY and BOXGETS but the characters defined in
  741.                  $KEY_FILTER (if any) are NOT accepted in input fields.  For
  742.                  example, if you were getting a filename you might put a space
  743.                  in the $KEY_FILTER using ASSIGN $KEY_FILTER " " which would
  744.                  prevent the user from entering a space during the next
  745.                  BOXGETS/GETS/GETSXY command.  You can define up to ten
  746.                  characters to ignore... ASSIGN $KEY_FILTER "*? " would
  747.                  prevent the user from entering asterisks, question marks and
  748.                  spaces in the input field.  All characters assigned to
  749.                  $KEY_FILTER must be regular ASCII characters.  To filter out
  750.                  control characters, use the caret ("^[" is ESC, "^C" is Ctrl-
  751.                  C, etc).  See ASCII CODES in the Appendix for control
  752.                  characters.
  753.      $KEY_ALTQ   if non-zero, Icom checks for [Alt-Q] (abort job or script,
  754.                  turn on script debugging, etc) while your script is running. 
  755.                  If you want to prevent the user from aborting the script,
  756.                  ASSIGN $KEY_ALTQ 0 (set it to 0) and Icom will not pop up the
  757.                  Control Menu when Alt-Q is pressed.  This should only be used
  758.                  when you have something to clean up when your script ends,
  759.                  such as resetting System Variables or re-loading a BIF or
  760.                  main setup file, etc.  If you shut this off, you should
  761.                  substitute your own script abort menu by checking for Alt-Q
  762.                  (key code 4096) after INKEY, INKEYW and/or setting a
  763.                  $HOTKEY_? to Alt-Q (ASSIGN $HOTKEY_1 4096) for BOXGETS,
  764.                  GETS/GETSXY to observe.  The best way to handle it is by
  765.                  using a subroutine (GOSUB MY_INKEY, GOSUB MY_INKEYW, GOSUB
  766.                  MY_BOXGETS, etc.) to get keys, then check for Alt-Q (4096) in
  767.                  the subroutine.  If the user enters Alt-Q Pop up an "Abort
  768.                  script?  Yes  No" menu with BOXMENUH.  If Yes is selected,
  769.                  call your 'clean_up' subroutine to reset whatever needs
  770.                  resetting, then EXIT.
  771.  
  772.      1.5  Communications
  773.  
  774.      CAPTURE    closes current capture, if open, then opens a new capture
  775.                 file.
  776.      CAPCLOSE   closes the current capture file, doesn't open a new one.
  777.      CAPPUSH    saves the current capture D:\PATH\FILENAME.EXT, and status
  778.                 (open, closed, paused), for later use with CAPPOP.  CAPPUSH
  779.  
  780.  
  781.  
  782.  
  783.      Intellicomm v2.01               SCRIPT.DOC                              6
  784.      
  785.      
  786.  
  787.                 saves the capture filename/status only ONCE.  If you call it
  788.                 again before using CAPPOP, you lose the previous CAPPUSH data.
  789.      CAPPOP     restores the capture filename and status (open/closed/paused)
  790.                 to the value they had when CAPPUSH was last called.
  791.      CAPSTAMP   stamps a line in the capture file (if open) containing the
  792.                 current date, time, BIF ID and BBS/Host Name.
  793.      CGETC      gets a character from the current COM port and stores it in a
  794.                 variable.  If no characters are available, CGETC waits until a
  795.                 specified timeout has elapsed (or indefinitely if no timeout
  796.                 is given).
  797.      CGETS      gets a 'string' of characters from the COM port, and stores it
  798.                 in a specified variable.  CGETS also takes an optional 'end-
  799.                 of-string' character and timeout, and it returns control only
  800.                 after a Carriage Return (CR) is received, or the specified
  801.                 end-of-string character is received, or the timeout elapses.
  802.      DIAL       dials one or more BBS Information Files, or a specific phone #
  803.                 (similar to the "Manual" dial option in the BBS Directory), or
  804.                 displays the BBS Directory for manual user input.
  805.      DOWNLOAD   downloads one or more files using a specified protocol.
  806.      HANGUP     same as pressing [Alt-H] from Terminal mode... tells the modem
  807.                 to disconnect.
  808.      INITMODEM  same as pressing [Alt-I] from Terminal mode... sends the
  809.                 "Initialize Modem" string, defined on the main setup/Terminal
  810.                 screen, to the modem.
  811.      LOG        opens a new usage log file (the default usage log is
  812.                 \ICOM\CAP\ICOM.USE).
  813.      LOGCLOSE   closes the usage log, if open.  Once closed, Icom will not
  814.                 write usage data of any sort.
  815.      NEWAREA    uses the commands and prompts defined in the currently loaded
  816.                 BIF to change to a new area of the BBS.  You can change to the
  817.                 Main Menu, Message Menu, Bank Menu, File Menu, or change file
  818.                 areas/message areas ([J]oin a conference, etc).  If the area
  819.                 change is unsuccessful, $ERRORLEVEL is set.  There are some
  820.                 considerations for using this command properly, which are
  821.                 outlined in the DETAILED COMMAND SUMMARY.
  822.      OFFLINE    if the modem is not connected, a command is carried out.
  823.      ONLINE     if the modem IS connected, a command is carried out.
  824.      PORT       changes to another COM port (current port is closed first...
  825.                 you'll lose the connection if connected).
  826.      REDIAL     used after DIAL to re-dial any BIFs that remain tagged.  
  827.      RXBUF      tells you how many (if any) characters are waiting in the
  828.                 receive buffer.  See below.
  829.      RXFLUSH    empties the Icom receive buffer.  Characters received from the
  830.                 COM port that have not been processed yet (CGETC, CGETS, SEND,
  831.                 SENDBIF, SENDNC, WAITFOR, and TERMINAL are the only commands
  832.                 that process incoming characters from the port) will pile up
  833.                 in the receive buffer.  If you aren't expecting (or don't
  834.                 need) input from the port at a given point in your script, or
  835.                 if you want to clear any line noise before an operation, use
  836.                 RXFLUSH to get rid of garbage.
  837.      SCROLLBACK same as pressing [Alt-B] from Terminal Mode.  Enters the
  838.                 scrollback buffer.
  839.      SEND       sends text out the current COM port (to the BBS), and follows
  840.                 it with a Carriage Return (CR, same as pressing the [Enter]
  841.  
  842.  
  843.  
  844.  
  845.      Intellicomm v2.01               SCRIPT.DOC                              7
  846.      
  847.      
  848.  
  849.                 key).  If a "Response Delay" is defined in the current BIF,
  850.                 SEND delays sending of the data for the duration of the
  851.                 Response Delay.
  852.      SENDNP     SEND with No Pause.  Same as SEND above, but doesn't observe
  853.                 the BIF Response Delay.
  854.      SENDNCP    SEND No CR or Pause.  Same as SEND above, but never adds a CR,
  855.                 and doesn't observe the Response Delay,
  856.      SENDBIF    sends a specific BIF command out the current COM port, or runs
  857.                 a @SCRIPT, or executes a !DOS command, as BIF commands are
  858.                 entitled to do.  If "CR w/Commands?" on BIF screen 1 of the
  859.                 current BIF in use is set to "Yes", then a CR is added after
  860.                 the response.  Otherwise, no CR is added (BBS hotkeys), just
  861.                 as with Icom's automated routines.  SENDBIF is exactly what
  862.                 Icom uses to handle BIF responses during automated jobs.
  863.      SENDBREAK  sends a break signal to the current COM port.  On error-
  864.                 correcting modems, a break usually clears the modem transmit
  865.                 buffer (a good way to flush data after a cancelled transmit
  866.                 operation).
  867.      SENDNC     same as SEND, but doesn't add a CR.
  868.      SETCOMM    changes the current COM port settings (baud, parity, etc).
  869.      SHOWWHENS  shows the currently defined WHENs, and the command (up to 20
  870.                 characters) that will be executed WHEN the text is found. 
  871.                 Mainly for debugging BIFs and automated jobs to see which BBS
  872.                 prompts Icom is tracking during a given job.
  873.      STAMP      stamps a COMMENT record in the Usage Log, if open.
  874.      TERMINAL   is an advanced command that will only be needed if your script
  875.                 fails to display characters from the BBS and doesn't allow
  876.                 keys to be processed ([Alt-Z] to pop up the Terminal menu,
  877.                 etc). If you run into this problem, look up TERMINAL's details
  878.                 in the Detailed Command Summary.
  879.      TXBUF      tells you how many (if any) characters are waiting to be sent
  880.                 to the modem (COM port) in the transmit buffer.  See next.
  881.      TXFLUSH    clears characters waiting to be sent to the modem from the
  882.                 transmit buffer.  SEND, SENDBIF, SENDKEY, and SENDNC send
  883.                 characters to the transmit buffer.  When the modem is ready to
  884.                 send, characters are moved from the transmit buffer to the COM
  885.                 port (where the modem then takes them and sends them to the
  886.                 BBS).  Use TXFLUSH to get rid of any characters sitting in the
  887.                 transmit buffer. 
  888.      UPLOAD     uploads one or more files using a specified protocol.
  889.      WAITFOR    handles WHENs (if any) while waiting for specific text from
  890.                 the current COM port.  An optional timeout can be specified
  891.                 with an optional script label to GOTO if the text isn't found.
  892.      WHEN       defines text to watch for (and handle with a specific command,
  893.                 if found) while WAITFOR is active.  Also used to clear
  894.                 previously defined WHENs.
  895.      $BBS_AREA  is set to a letter, enclosed in square brackets, reflecting
  896.                 the current BBS Area (Main Menu, Message Menu, Bank Menu, or
  897.                 File Menu, or 'location unknown' if blank), for use mainly
  898.                 when calling scripts from automated jobs.  When your script
  899.                 starts you can check the current area by checking $BBS_AREA,
  900.                 and can move to a new area if need be with the NEWAREA
  901.                 command.  $BBS_AREA will only be set to an area if Intellicom
  902.                 was AT the main menu of the area when your script was called.
  903.  
  904.  
  905.  
  906.  
  907.      Intellicomm v2.01               SCRIPT.DOC                              8
  908.      
  909.      
  910.  
  911.      $CARRIER   the state of the DCD signal (carrier detect) on the current
  912.                 $COM_PORT.  If 0 (zero), the modem is reporting offline (not
  913.                 connected).  If non-zero the modem is reporting online
  914.                 (connected).  See "Common Questions & Answers" in the Icom
  915.                 online help for a fix if your modem isn't telling the truth
  916.                 and reports online always.
  917.      $COM_PORT  the number of the current COM port (1-8; 1 = COM1, etc).
  918.      $COM_SPEED the current speed (baud rate) of the COM port (300-115200).
  919.      $SEND_CR   a flag (zero is 'off', non-zero is 'on') that determines
  920.                 whether the SEND command adds a Carriage Return (CR; the same
  921.                 as pressing [Enter]) after the data it sends.
  922.  
  923.      1.6  Icom Information / Script Variables
  924.  
  925.      ASSIGN         assigns text or numbers to a variable.
  926.      GETENV         gets DOS environment data (PATH, PROMPT, etc) and stores
  927.                     in a variable.
  928.      SETENV         changes, sets, or clears a DOS environment variable (PATH,
  929.                     PROMPT, etc., or an environment variable you're using to
  930.                     keep track of specific information).
  931.      VARIABLE       defines a variable name and allocates storage space in
  932.                     memory.  You can also assign data to the variable when
  933.                     defining it.
  934.      $BETA_VERSION  the current beta version of Intellicomm (or 0 if a
  935.                     production release).
  936.      $BIF_DIR       the BIF directory (where .BIF files are found).
  937.      $BIF_NAME      the filename of the currently loaded BIF (no extension;
  938.                     it's always .BIF).
  939.      $CAP_NAME      the current capture file (D:\PATH\FNAME.EXT).
  940.      $CAP_STAT      the current status of the capture file (0 = closed, 1 =
  941.                     open, 2 = paused).
  942.      $CAT_DIR       the Catalog Directory (File Tagger databases) as defined
  943.                     in the Icom main setup.
  944.      $CAT_NAME      the name of the currently open Catalog (if open).
  945.      $DSEP          the 'Date Separator' character as defined in the Icom main
  946.                     setup.
  947.      $DL_DIR        the current Download Directory (BIF or main setup if no
  948.                     Download Dir defined in the BIF).
  949.      $DL_PROTOCOL   the "Receive Files" protocol, as defined in the current
  950.                     BIF.
  951.      $ERRORLEVEL    set to specific numbers by commands (see ERRORLEVEL
  952.                     sections in the Detailed Command Summary).
  953.      $FULL_SCRIPT_NAME the full D:\PATH\FILENAME.EXT of the currently
  954.                        executing script.  Also see $SCRIPT_NAME.
  955.      $HOME_DIR      the Icom home directory (where ICOM.EXE is, or where the
  956.                     ICOM environment variable points to).
  957.      $LST_DIR       Icom List Directory (main setup option defaults to
  958.                     \ICOM\LST).  This is where Icom looks for .NEW files lists
  959.                     to auto-import to the Tagger catalogs.
  960.      $MAJOR_VERSION Intellicomm major version number (2, 3, etc).
  961.      $MINOR_VERSION Intellicomm minor version number (0 1 10, etc.) after the
  962.                     decimal.  Icom v2.10 would have a $MAJOR_VERSION of 2 and
  963.                     a $MINOR_VERSION of 10 (ten).
  964.      $MSG_DIR       the current Message Directory (BIF or main setup if no BIF
  965.  
  966.  
  967.  
  968.  
  969.      Intellicomm v2.01               SCRIPT.DOC                              9
  970.      
  971.      
  972.  
  973.                     Message Dir defined).
  974.      $MSG_PROTOCOL  the "Receive Messages" protocol, as defined in the current
  975.                     BIF.
  976.      $PASSWORD      the logon password defined in the current BIF.
  977.      $PRN           the printer device defined in the main setup (defaults to
  978.                     PRN).
  979.      $REP_DIR       the current Reply Directory (BIF or main setup if no BIF
  980.                     Reply Dir defined).
  981.      $REP_PROTOCOL  the "Send Replies" protocol, as defined in the current
  982.                     BIF.
  983.      $SCRIPT_DIR    the Icom Script Directory, as defined in the main setup.
  984.      $SCRIPT_NAME   the FILENAME.EXT of the current script (no D:\PATH\ ...
  985.                     use this when simply want to print the script name for
  986.                     user consumption).
  987.      $TSEP          the 'Time Separator' character as defined in the Icom main
  988.                     setup.
  989.      $UL_PATH       the full Upload PATH (BIF or main setup if no BIF path
  990.                     Upload PATH defined).  Upload PATHs are in the format:
  991.                     D:\DIR1;D:\DIR2 etc.  Use STRITEM to obtain a specific
  992.                     directory from the path.
  993.      $UL_PROTOCOL   the "Send Files" protocol, as defined in the current BIF.
  994.  
  995.      1.7  Text (String) Handling
  996.  
  997.      ADDSLASH checks a variable containing text (usually a directory name) to
  998.               see whether it has a trailing backslash (\) or not.  If it does
  999.               have a trailing backslash, nothing is done.  If it doesn't have
  1000.               a trailing backslash, a backslash is added.  EXCEPTION: if the
  1001.               variable contains only a drive letter (C:), a slash is not
  1002.               added.
  1003.      SETCHR   puts a single character into a string, at a given point,
  1004.               overwriting the previous character.
  1005.      SETCHRS  copies one string into another, at a given point, overwriting
  1006.               the original string portion.
  1007.      STRBLANK checks to see if a variable is blank (empty or all whitespace*).
  1008.      STRCHR   finds the first occurrance of a given character in a given
  1009.               string (case sensitive) and stores the position of the character
  1010.               in a variable.  This command is most likely to be used in
  1011.               combination with another of the string handing functions, such
  1012.               as STRINS or STRDEL.
  1013.      STRCHRI  same as STRCHR, but case (UPPERCASE/lowercase) of the character
  1014.               searched for is ignored.
  1015.      STRCPY   copies one string (or a portion) to another at a given position.
  1016.      STRDEL   deletes a given number of characters from a given position in a
  1017.               variable.
  1018.      STRITEM  gets a specific item from a variable (see detailed summary).
  1019.      STRLOWER converts text in a variable to lower case.
  1020.      STRCAT   adds (concatenates) one string to the end of another.
  1021.      STRINS   inserts a given number of characters from one string to a given
  1022.               position in a variable.  STRCAT adds text only to the end of a
  1023.               variable.  Use STRINS to add text at any position.
  1024.      STRLEN   gets the length of a given constant or variable (check the
  1025.               length of a string).
  1026.      STRPAD   pads a variable (with any character) to a given length.  Pad
  1027.  
  1028.  
  1029.  
  1030.  
  1031.      Intellicomm v2.01               SCRIPT.DOC                             10
  1032.      
  1033.      
  1034.  
  1035.               characters are added to the RIGHT side of the variable.
  1036.      STRPADL  pads a variable (with any character) to a given length.  Pad
  1037.               characters are inserted on the LEFT side of the variable (useful
  1038.               for lining numbers up; right justified).
  1039.      STRSET   sets a given number of characters in a variable (at a given
  1040.               positon) to a given character.
  1041.      STRPOS   looks for a substring in another string, stores the position (if
  1042.               found) in a variable.  Case IS sensitive.
  1043.      STRPOSI  is the same as STRPOS, but case is not sensitive.
  1044.      STRRCHR  searches a given string from the last character towards the
  1045.               first, for a given character (case sensitive).
  1046.      STRRCHRI searches a given string from the last character towards the
  1047.               first, for a given character (case insensitive).
  1048.      STRREPLACE  replaces all occurrances of one string in another (case
  1049.                  sensitive).
  1050.      STRREPLACEI replaces all occurrances of one string in another (case
  1051.                  insensitive).
  1052.      STRSTRIP strip all occurrances of a given character from a given
  1053.               variable.  The character, if found, is not replaced with another
  1054.               character; text from the right is simply pulled over to
  1055.               overwrite the character until the character no longer exists in
  1056.               the string.  Use to simply eliminate unwanted characters from
  1057.               text, such as commas, spaces, etc.
  1058.      STRTRIM  trims whitespace* from the right side of a string.
  1059.      STRLTRIM trims whitespace* from the left side of a string.
  1060.      STRBTRIM trims whitespace* from both the left and right side of a string.
  1061.      STRUPPER converts text in a variable to upper case.
  1062.      SUBSTR   copies a portion of one variable to another variable.
  1063.  
  1064.      * Spaces, tabs, and Carriage Return/Line Feed characters are
  1065.        'whitespace'.  'White' because when you send these characters to a
  1066.        printer they leave white space on the paper.
  1067.  
  1068.      1.8  Math Commands
  1069.  
  1070.      ADD  adds two numbers and stores the result in a variable.
  1071.      AND  is an advanced command for programmers.  If performs a bitwise AND
  1072.           on two numbers, and stores the result in a variable.  If you don't
  1073.           know what a bitwise AND is, you won't need this command.
  1074.      DIV  divides two numbers, stores the result in a variable.
  1075.      DEC  (DECrement) subtracts 1 from the contents of a variable (x = x - 1).
  1076.      INC  (INCrement) adds 1 to the contents of a variable (x = x + 1).  INC
  1077.           and DEC are used mainly for counting.
  1078.      OR   is an advanced command for programmers, similar to the AND command
  1079.           above.  It performs a bitwise OR on two numbers and stores the
  1080.           result in a variable.  If you don't know what a bitwise OR is, you
  1081.           needn't concern yourself with this command.
  1082.      MUL  multiplies two numbers, stores the result in a variable.
  1083.      SHL  (SHift Left) is also an advanced command for programmers which
  1084.           shifts a given number of bits in a number towards the left.  The
  1085.           result is stored in a given variable.  Each bit shifted to the left
  1086.           has the effect of multiplying the original number by two (2).
  1087.      SHR  (SHift Right) is another an advanced command for programmers which
  1088.           shifts a given number of bits in another number towards the right. 
  1089.  
  1090.  
  1091.  
  1092.  
  1093.      Intellicomm v2.01               SCRIPT.DOC                             11
  1094.      
  1095.      
  1096.  
  1097.           The result is stored in a given variable.  Each bit shifted to the
  1098.           right has the effect of dividing the original number by two (2).
  1099.      SUB  subtracts one number from another, stores the result in a variable.
  1100.      XOR  is similar to AND/OR above, but performs a bitwise eXclusive OR on
  1101.           two numbers and stores the result in a variable.  This one, while
  1102.           it's also mainly for programmers, can actually be quite useful to
  1103.           non-programmers and it's worth a looksee in the Detailed Summary.
  1104.  
  1105.      1.9  DOS and File Input/Output Commands
  1106.  
  1107.      APPEND     adds the contents of one text file to the end of another text
  1108.                 file (the original file remains intact).
  1109.      APPENDS    adds one line ('S'tring; a script variable or constant) to the
  1110.                 end of a text file.  Terminates the line with a Carriage
  1111.                 Return (CR) and Line Feed (LF) and closes the file.
  1112.      APPENDSNC  same as APPENDS, but doesn't add CR/LF to terminate the line
  1113.                 (NC stands for 'N'o 'C'arriage return).
  1114.      CHDIR      changes DOS's 'current directory' (same as CHDIR from DOS).
  1115.      COPY       copies one file (text or binary) to another filename and/or
  1116.                 directory.  Overwrites files of the same destination name (use
  1117.                 APPEND to add one file to another).  Similar to the DOS 'COPY'
  1118.                 command.
  1119.      DEL/DELETE delete a file on-disk.  Similar to the DOS 'DELETE' command,
  1120.                 and wildcards (* and ?) are accepted in the filespec.  Be
  1121.                 careful with this one ... DELETE "*.*" doesn't ask you to
  1122.                 confirm before it deletes all files in the directory.
  1123.      DIRFIND    looks for a directory on-disk, executes a script command if it
  1124.                 DOES exist.  This command is similar to EXIST, but looks for a
  1125.                 directory instead of a file.
  1126.      DISKFIND   searches all directories on a given disk for a given filespec
  1127.                 (* and ? accepted).  If the file is found its full
  1128.                 drive/pathname (D:\DIR\FILENAME.EXT) is stored in a given
  1129.                 variable.
  1130.      DISKFREE   stores the amount of free disk space on a given disk in a
  1131.                 given variable.
  1132.      DOS        executes a DOS command (or runs another program or .BAT file)
  1133.                 or performs a DOS shell.
  1134.      EXEC       similar to the DOS command above, but EXEC does not use the
  1135.                 command processor (COMMAND.COM) to execute the given command. 
  1136.                 EXEC is used when you need the 'errorlevel' reported by a .COM
  1137.                 or .EXE.  Most of the COMMAND.COM features (running .BAT
  1138.                 files, executing commands such as COPY, etc) are not supported
  1139.                 by EXEC.  Simple redirections (> or >> to redirect program
  1140.                 output to a file or device) are supported by EXEC if you need
  1141.                 them, but pipes (|) and input redirection (<) are not
  1142.                 supported.  Use the 'DOS' command above for those.
  1143.      EXIST      looks for a file on-disk, executes a script command if it DOES
  1144.                 exist.  This command also sets the file attribute System
  1145.                 Variables listed below, if a file is found.
  1146.      FCLOSE     closes a file previously opened by FOPEN.
  1147.      FFLUSH     flush (write) any data in the write buffer of an open file.
  1148.      FGETC      gets one character from an open file.
  1149.      FGETS      gets one line from an open file.
  1150.      FNSTRIP    takes a given filename and removes various components (drive
  1151.  
  1152.  
  1153.  
  1154.  
  1155.      Intellicomm v2.01               SCRIPT.DOC                             12
  1156.      
  1157.      
  1158.  
  1159.                 only, drive and filename only, path only, etc).
  1160.      FILESIZE   puts the size of a file in a variable, if the file is found
  1161.                 (wildcards are accepted).  Also sets the file attribute System
  1162.                 Variables listed below.
  1163.      FINDFIRST  locates the first file matching a given filespec and set of
  1164.                 file attributes (*.SCR, *.*, hidden files, read only files,
  1165.                 subdirectories only, etc) and stores the filename in a given
  1166.                 variable.  This command also sets the file attribute System
  1167.                 Variables listed below, if a file is found.
  1168.      FINDNEXT   locates the next matching file after a FINDFIRST and stores
  1169.                 the filename in a given variable.  This command also sets the
  1170.                 file attribute System Variables listed below.
  1171.      FOPEN      opens a file for appending, reading, writing or read/write.
  1172.      FPUTC      writes a character to an open file.
  1173.      FPUTS      writes a line to an open file, following it with a Carriage
  1174.                 Return (CR) and Line Feed (LF).
  1175.      FPUTSNC    same as FPUTS but doesn't add CR/LF to the end of the line.
  1176.      FSEEK      seeks to a specific position (byte) in an open file.
  1177.      FTELL      reports the current position (byte) of an open file.
  1178.      GETFNAME   displays all files matching a given filespec, and allows the
  1179.                 user to "Select" one or more files for your script to operate
  1180.                 on.  Useful whenever you must get one or more filenames from
  1181.                 the user.
  1182.      LOCATEFILE searches the current Download Dir, Upload PATH, and the DOS
  1183.                 PATH (if "Use PATH to locate files" is turned ON in the Icom
  1184.                 main setup) to locate a given filespec (* and ? accepted).  If
  1185.                 the file is found, its full path is stored in a given
  1186.                 variable.
  1187.      MKDIR      makes a new disk directory.
  1188.      NOTEXIST   looks for a file (or filespec) on-disk, executes a script
  1189.                 command if it DOESN'T exist.  If the file does exist, this
  1190.                 command also sets all the file attribute System Variables
  1191.                 listed below.
  1192.      RENAME     rename or MOVE a file (from one directory to another) on-disk.
  1193.      RENUMBER   Renumbers a given set of files, similar to the Capture file
  1194.                 renumbering (ICOM.CAP, ICOM01.CAP, ICOM02.CAP, etc).
  1195.      RMDIR      remove (delete) an empty disk directory.
  1196.      SCAPTURE   writes (appends to, if the file exists) a snapshot of the
  1197.                 screen to a given file (or the Screen Capture file
  1198.                 \ICOM\CAP\SCREEN.CAP by default if no filename specified).  
  1199.      $CURDIR    the current DOS directory.
  1200.  
  1201.      The following System Variables are set by the EXIST, FILESIZE, FINDFIRST,
  1202.      FINDNEXT, and NOTEXIST commands, if the specified file file/filespec
  1203.      exists.  If the file doesn't exist all except $FSIZE are set to 0 ($FSIZE
  1204.      is set to -1).  Note that these variables are set to the attributes of
  1205.      the currently executing SCRIPT when a script begins.  So if you want to
  1206.      check the script size or modification date (or any other attribute) just
  1207.      access these variables at script startup, before you use EXIST, FILESIZE,
  1208.      FINDFIRST, FINDNEXT, or NOTEXIST:
  1209.  
  1210.      $FDAY     file modification date, day of month (0-31).
  1211.      $FMONTH   file modification date, month (1-12).
  1212.      $FYEAR    file modification date, full year (1993, etc).
  1213.  
  1214.  
  1215.  
  1216.  
  1217.      Intellicomm v2.01               SCRIPT.DOC                             13
  1218.      
  1219.      
  1220.  
  1221.      $FHOUR    file modification time, hour (0-23).
  1222.      $FMIN     file modification time, minute (0-59).
  1223.      $FSEC     file modification time, second (0-59).
  1224.      $FSIZE    size of the file, in bytes.
  1225.      $FRDONLY  read-only attribute (will hold + if set, - if clear).
  1226.      $FHIDDEN  hidden attribute (+ if set, - if clear).  You must use
  1227.                FINDFIRST/FINDNEXT to find hidden files.
  1228.      $FSYSTEM  'system file' attribute (+ if set, - if clear).  You must use
  1229.                FINDFIRST/FINDNEXT to find system files.
  1230.      $FVOLID   Volume ID attribute (+ if set, - if clear).  This will only be
  1231.                set on one file in the root directory.  You must use
  1232.                FINDFIRST/FINDNEXT to find the Volume ID.
  1233.      $FSUBDIR  subdirectory attribute (+ if set, - if clear).  I.e. this is
  1234.                not a file, it's the name of a subdirectory.  You must use
  1235.                FINDFIRST/FINDNEXT to find subdirectories.
  1236.      $FARCH    archive attribute (+ if set, - if clear).  If the archive
  1237.                attribute is +, the file has been changed since the last disk
  1238.                BACKUP (most backup programs clear the archive attribute after
  1239.                the file is backed up.  DOS sets it again if you modify the
  1240.                file or create a new file).
  1241.  
  1242.      1.10  Date and Time
  1243.  
  1244.      TIMER      starts a timer and sets it to expire after a given number
  1245.                 (tenths of a second).
  1246.      TIMERTOTAL the total time elapsed (in tenths of a second) since TIMER was
  1247.                 last called.
  1248.      TIMEUP     checks the timer started with TIMERSTART to see whether it has
  1249.                 expired.  If it has, the script command following TIMEUP is
  1250.                 executed.
  1251.      $DATE      the current system date in text format (MM/DD/YY or the format
  1252.                 defined by the user in the Icom main setup).
  1253.      $DAY       current day of month (1-31)
  1254.      $DOW       current day of week (1-7)
  1255.      $HOUR      current hour (0-23)
  1256.      $HSEC      current hundredth of a second (0-99)
  1257.      $MIN       current minute (0-59)
  1258.      $MONTH     current month (1-12)
  1259.      $SEC       current second (0-59)
  1260.      $TIME      the current system time in text format (HH:MM:SS or the format
  1261.                 defined by the user in the Icom main setup).
  1262.      $YEAR      current year (1993, etc.)
  1263.  
  1264.      1.11  Script Flow / Decision-Making
  1265.  
  1266.      IF        compares two items (usually one or both items being variables)
  1267.                for equality, inequality,  greater than/less than, etc.  IF has
  1268.                two incarnations.  If you specify another script command after
  1269.                the IF comparison, the specified command is executed if the
  1270.                comparison is TRUE, and is skipped if the comparison is FALSE. 
  1271.                If no command is specified after the IF comparison, it is
  1272.                assumed you are using an IF/ELSE/ENDIF sequence, which allows
  1273.                you to execute one SET of commands if the comparison is TRUE,
  1274.                and another SET of commands if the comparison is FALSE (the
  1275.  
  1276.  
  1277.  
  1278.  
  1279.      Intellicomm v2.01               SCRIPT.DOC                             14
  1280.      
  1281.      
  1282.  
  1283.                commands after the ELSE, if ELSE is used).
  1284.      CHECKVERSION takes a version number in the format "x.xx" ... or "x" ...
  1285.                or "x.x" (e.g. "2.00", "2", "2.0", etc) and compares the
  1286.                numbers to the current Intellicomm version number.  If the Icom
  1287.                version number is less than the version number (or portion of
  1288.                the version number) you specify, the script aborts with the
  1289.                error message: "Sorry, this script requires Intellicomm vx.xx
  1290.                or above." (where x.xx is the version number specified in
  1291.                CHECKVERSION).
  1292.      DELAY     pauses your script; allows incoming characters from the BBS to
  1293.                be displayed during the pause.
  1294.      DELAYNC   pauses your script; DOESN'T allow incoming characters from the
  1295.                COM port to be displayed.
  1296.      EXIT      ends the script with optional error return code.  See the
  1297.                detailed summary before using this command with an error return
  1298.                code.
  1299.      GOSUB     turns control over to a subroutine temporarily.  Similar to
  1300.                GOTO, but GOSUBs are temporary, and they RETURN control to the
  1301.                command following the GOSUB (or back to the WAITFOR if called
  1302.                from a WHEN) when they're done.  GOSUB is especially useful in
  1303.                WHEN commands to have more than one command carried out when
  1304.                BBS text is found.
  1305.      GOTO      jumps to a 'label:' without returning.
  1306.      RELOADSCRIPT reloads the current script from disk and starts running it
  1307.      at
  1308.                the beginning again.
  1309.      RETURN    returns from a subroutine, or back to the caller (whatever
  1310.                started the script) if used after a GOSUB.
  1311.      SCRIPT    runs another script then returns control to the calling script. 
  1312.                Similar to GOSUB, but runs another script as the subroutine.
  1313.      SWITCH    executes one or more script commands based on a given
  1314.      condition.
  1315.       CASE     specifies a condition.
  1316.       ENDCASE  denotes the end of one condition (mandatory).
  1317.       ENDSWITCH denotes the end of the SWITCH statement (mandatory).
  1318.      SYSTEM    exits Intellicomm (after closing the port, etc., and either
  1319.                hangup up, staying connected, or prompting whether to hang up)
  1320.                back to DOS with an optional DOS 'errorlevel'.
  1321.      WAITUNTIL displays a box on the screen showing the time and/or day to
  1322.                WAITUNTIL, along with the current date and time, and a list of
  1323.                menu options (complete with a screen blanker) then pauses the
  1324.                script until the specified time and/or day, or until the user
  1325.                aborts the pause.
  1326.      WHILE     executes a set of commands WHILE a condition remains true.
  1327.       BREAK    exits a WHILE 'loop'.
  1328.       CONTINUE jumps back to the top of a WHILE 'loop' (check condition
  1329.      again).
  1330.       ENDWHILE denotes the end of the WHILE loop (mandatory).
  1331.  
  1332.      1.12  Other Useful Commands
  1333.  
  1334.      ALARM    sounds an alarm on the PC speaker to get the user's attention,
  1335.               but only if the System Variables $ALARMS and $SOUND are non-
  1336.               zero.  If $ALARMS *or* $SOUND are set to zero, the ALARM is
  1337.  
  1338.  
  1339.  
  1340.  
  1341.      Intellicomm v2.01               SCRIPT.DOC                             15
  1342.      
  1343.      
  1344.  
  1345.               ignored.  Icom automatically sets $ALARMS to 0 before running
  1346.               automated jobs.  You can change the value of $ALARMS and/or
  1347.               $SOUND by ASSIGNing 0 (off) or 1 (on) to them.
  1348.      BEEP     sounds a beep on the PC speaker to get the user's attention, but
  1349.               only if the System Variable $SOUND is non-zero.  If $SOUND is
  1350.               set to zero BEEP (all sound) is ignored.  Icom automatically
  1351.               sets $SOUND to 0 before running automated jobs.
  1352.      CHAT     enters into Chat Mode.  Control returns to the script when the
  1353.               user is finished chatting and presses [Esc] to exit Chat Mode.
  1354.      DEBUG    turns the script debugger on or off.
  1355.      EDIT     loads a text file for editing, positions to optional line #.
  1356.      FILEMAN  calls the Icom File Manager to display a given directory and/or
  1357.               filespec.  The user can Edit, View, Copy, Ren/Move, Delete, Find
  1358.               files, or display another directory.  Control returns to the
  1359.               script when the user exits the File Manager.
  1360.      HELP     displays a specific help topic (or the help index).
  1361.      HELPFIND similar to using the online help "Search" feature.  It searches
  1362.               all topics in the online help file for a given keyword, and
  1363.               displays all topics that contain the keyword to the user.
  1364.      LIST     displays a text file for viewing, positions to optional line #.
  1365.      LOADBIF  loads a new BIF into memory.
  1366.      LOADINI  loads a new main setup (.INI) file into memory.
  1367.      SAVEBIF  saves the current BIF information (in memory) to disk.
  1368.      SAVEINI  saves the current main setup data (in memory) to disk.
  1369.      TAGGER   enters the File Tagger, loading a specified catalog for viewing.
  1370.      TONE     sounds a specific tone on the speaker, for a specific duration.
  1371.      $ALARMS  determines whether alarms are heard or not (this is a main setup
  1372.               option and is used globally in Intellicomm).
  1373.      $OPSYSTYPE reports the Operating System in use on the computer (DESQview,
  1374.                 DOS, OS/2 or Windows).
  1375.      $SOUND   determines whether any sound at all is heard (beeps from the
  1376.               BBS, ALARMs, etc.  This is also a main setup option).
  1377.      GlobalStr[] is a global variable 'array' available to all scripts.  The
  1378.                  GlobalStr array stores parameters (if any) passed to a script
  1379.                  from DOS, Custom Commands, BIFs or other scripts, and is
  1380.                  otherwise useful for simply storing information semi-
  1381.                  permanently (for the duration of the Icom session) and for
  1382.                  other useful things.  See SCRTUTOR.DOC for more details on
  1383.                  GlobalStr.
  1384.  
  1385.      1.13  File Tagger Commands (Advanced use only)
  1386.  
  1387.      These commands allow you to manipulate File Tagger catalogs (databases)
  1388.      directly, and are for advanced script writers only.  Read INTRODUCTION TO
  1389.      DATABASE COMMANDS in SCRTUTOR.DOC before using these commands.
  1390.  
  1391.      CADDREC     adds a new record to the currently open (COPEN) catalog, and
  1392.                  updates the NDX's (indexes, used to sort catalogs) to include
  1393.                  the new record's data.
  1394.      CCLEARBUF   clears all $CXXXX_FLD variables and the record description
  1395.                  buffer.
  1396.      CCLEARDESC  clears only the record description buffer.
  1397.      CCLOSE      closes the currently open catalog.
  1398.      CDATE2DATE  converts a dBASE date (YYYYMMDD ... as dates are stored in
  1399.  
  1400.  
  1401.  
  1402.  
  1403.      Intellicomm v2.01               SCRIPT.DOC                             16
  1404.      
  1405.      
  1406.  
  1407.                  catalogs) to the date format defined by the user in the Icom
  1408.                  main setup.  [For displaying dates to the user.]
  1409.      CDATEDIFF   takes two dates in dBASE date format (YYYYMMDD) and stores
  1410.                  the difference (in days) between the two dates in a given
  1411.                  variable.
  1412.      CDELREC     delete or undelete a given record.  This command doesn't
  1413.                  actually remove the record from the database, it simply marks
  1414.                  a given record's status for the next CPACK (which actually
  1415.                  removes all deleted records).
  1416.      CEDITREC    displays the current record obtained with CGETREC for
  1417.                  editing.  This displays the same editing screen you see when
  1418.                  you select "Edit" to edit a record from within the Tagger. 
  1419.                  As well as being useful for record editing, this command can
  1420.                  be useful for debugging, since it shows you last record
  1421.                  obtained with CGETREC.  Once in edit mode the user can press
  1422.                  [PgUp], [PgDn], to browse through the catalog, just as in
  1423.                  edit mode.  Control is returned to your script when the user
  1424.                  presses [Esc] to exit edit mode.
  1425.      CEMPTY      executes a given command if the database opened with COPEN is
  1426.                  empty (e.g. CEMPTY RETURN, CEMPTY GOTO DONE, etc).
  1427.      CEXPORT     exports files in the currently open (COPEN) database to a
  1428.                  given text filename, in a given BIF format.  If the catalog
  1429.                  is currently sorted (CSETSORT), the $VIEW_DATE is observed
  1430.                  when exporting records (i.e. you can export only file newer
  1431.                  than a given date by setting $VIEW_DATE).
  1432.      CFLUSH      writes any data in the CPUTREC, CPUTDESC buffers to disk.
  1433.      CFORMATDESC re-formats the current file comment/description to a new line
  1434.                  length.  CGETREC automatically formats file comments to a
  1435.                  line length of 45 characters.  Use this command to make
  1436.                  comment lines longer or shorter.
  1437.      CGETDESC    gets a given line from the file comment/description field. 
  1438.                  Use CGETREC to get a record from the database before
  1439.                  CGETDESC.
  1440.      CGETREC     gets the next (or first, if no prior calls to CGETREC) record
  1441.                  from the currently open catalog, and stores the record data
  1442.                  in the System Variables listed below.
  1443.      CIMPORTNEW  imports *.NEW files lists (captured via your script, or by an
  1444.                  automated job) into the proper File Tagger catalog(s).  The
  1445.                  base filename of the .NEW list must be the same base filename
  1446.                  of the .BIF where the list was obtained.
  1447.      CIMPORTTEXT imports a given text file (BBS file listing) into the
  1448.                  currently open catalog, using a given BIF file list format.
  1449.      CNOTEREC    toggles the 'Noted' status of the current record and updates
  1450.                  the NDX's (indexes) with the new data.  Similar to hilighting
  1451.                  a record from within the Tagger and selecting "Note" from the
  1452.                  bottom menu.
  1453.      COPEN       opens an existing File Tagger catalog, or creates a new one
  1454.                  if the catalog doesn't exist.  Only the filename (no
  1455.                  extension or directory) is needed.
  1456.      CPACK       packs a given database (or the currently open database if one
  1457.                  is open and no catalog name is given), removing all records
  1458.                  flagged as "Deleted".  Also packs the .DBT (file comments
  1459.                  that are no longer attached to a valid record) and rebuilds
  1460.                  the .NDX files associated with the catalog.
  1461.  
  1462.  
  1463.  
  1464.  
  1465.      Intellicomm v2.01               SCRIPT.DOC                             17
  1466.      
  1467.      
  1468.  
  1469.      CPURGE      purges the catalog, deleting records older than the number of
  1470.                  days set by the user in the Icom main setup/Tagger settings. 
  1471.                  "Deleted" records are simply flagged as deleted.  They are
  1472.                  not removed from the catalog.  You must CPACK to physically
  1473.                  remove purged records.
  1474.      CPUTDESC    updates a given file comment line with new data.  CGETREC
  1475.                  gets the entire comment (all lines are stored in a memory
  1476.                  buffer) and formats it to 45 characters per line. 
  1477.                  CFORMATDESC re-format the comment to any number of characters
  1478.                  per line.  CGETDESC gets individual lines from the comment...
  1479.                  and CPUTDESC is used to replace ONE description line with new
  1480.                  data.
  1481.      CPUTREC     updates an existing record with new data.  CGETREC stores
  1482.                  record data in the System Variables listed below.  If you
  1483.                  modify any of the data (in memory) you must CPUTREC to write
  1484.                  the changes to disk.
  1485.      CSAVEBMARK  saves a new 'bookmark' in the currently open catalog, or
  1486.                  clears the existing bookmark.  The bookmark is where the
  1487.                  Tagger hilight bar automatically seeks to when the catalog is
  1488.                  displayed.
  1489.      CSAVESORT   saves the current sort order and direction (set with
  1490.                  CSETSORT) in the currently open catalog header.  The saved
  1491.                  sort order/direction will be in effect the next time the
  1492.                  catalog is COPENed or viewed in the Tagger.
  1493.      CSAVEVDATE  saves a new 'view date'.  The View Date is observed by the
  1494.                  File Tagger in browse or edit mode, and only files that were
  1495.                  imported on or after the current View Date are displayed. 
  1496.                  Similarly, CGETREC only gets records imported on or after the
  1497.                  View Date, if the catalog is sorted (CSETSORT).  Setting a
  1498.                  $VIEW_DATE temporarily is done by simply ASSIGNing the
  1499.                  $VIEW_DATE variable a new date.  To actually store a new View
  1500.                  Date in the catalog (so the Tagger will observe it the next
  1501.                  time the catalog is opened), you must CSAVEDATE to update the
  1502.                  catalog on-disk.  Tagged records are unaffected by the View
  1503.                  Date, and 'Noted' records are also unaffected by the View
  1504.                  Date if the user has that option turned on the the Icom main
  1505.                  setup/Tagger settings.
  1506.      CSEEK       allows you to seek to a specific record in the catalog (if no
  1507.                  sort order is set with CSETSORT), or to a 'relative' position
  1508.                  according to the sort order and $VIEW_DATE (top, bottom, 10
  1509.                  records back from current position, 100 records ahead from
  1510.                  current position, etc).
  1511.      CSETSORT    set the current sort order to 1 (sorted by Tag Status/
  1512.                  Location), 2 (Catalog Date/Filesize), 3 (Filename/File Date)
  1513.                  or -1 (unsorted).  Also set the direction of the sort
  1514.                  (forwards or backwards).  The current sort order is observed
  1515.                  by CGETREC, and CSEEK.
  1516.      CTAGALL     Tag, Note or Untag all records in the currently open catalog. 
  1517.                  The $VIEW_DATE is ignored; ALL records are game.
  1518.      CTAGREC     toggles the tag status of a given record (or the current
  1519.                  record obtained with CGETREC if no record # specified). 
  1520.                  Updates the indexes (sorting information) with the new data.
  1521.      CTELL       report the current record number (last obtained with
  1522.                  CGETREC).
  1523.  
  1524.  
  1525.  
  1526.  
  1527.      Intellicomm v2.01               SCRIPT.DOC                             18
  1528.      
  1529.      
  1530.  
  1531.      DATE2CDATE  Converts a date (see $DATE) in the format the user has set up
  1532.                  in the Icom main setup, to a dBASE-style date (YYYYMMDD).
  1533.      UPDATEDNDX  updates DOWNLOAD.NDX with any new files that were DOWNLOADed. 
  1534.                  Files listed in DOWNLOAD.NDX are never added to BBS file
  1535.                  listings (provided that the 'Use DOWNLOAD.NDX' item is turned
  1536.                  on in the main setup).  To update the directories scanned for
  1537.                  downloads, see the main setup/Tagger section "DOWNLOAD.NDX
  1538.                  Directories" option.
  1539.      $CAT_DIR    the Catalog Directory as defined in the main setup (where
  1540.                  Tagger catalogs are stored and created).
  1541.      $CAT_NAME   the filename of the currently open catalog (no extension). 
  1542.                  E.g. NEWFILES, FILELIST, etc.
  1543.      $CSORT_DIR  current sort direction (0 = forward, 1 = reversed)
  1544.      $CSORT_ORDER current sort order (-1 = Unsorted, 1 = Tag Status/Location,
  1545.                   2 = Catalog Date/Filesize, 3 = Filename/File Date).
  1546.      $CTOTAL     the total number of records in the catalog, ignoring the View
  1547.                  Date.
  1548.      $CVTOTAL    the total number of records in the catalog currently visible
  1549.                  according to the current View Date ($VIEW_DATE).  This
  1550.                  variable is set when you open a catalog, and is re-calculated
  1551.                  if you change the $VIEW_DATE variable.
  1552.      $VIEW_DATE  the current catalog $VIEW_DATE in the format YYYYMMDD.  COPEN
  1553.                  automatically sets this variable to the View Date stored in
  1554.                  the catalog (as defined by the user; or as defined by
  1555.                  Intellicomm's last import if Auto View Date Update is turned
  1556.                  on in the main setup).  If the catalog is set to use an index
  1557.                  with CSETSORT then CGETREC and CSEEK observe the date in
  1558.                  $VIEW_DATE, and only operate on records that were imported
  1559.                  ($CCDATE_FLD) on or after the View Date.  Records imported
  1560.                  prior to the View Date are ignored.
  1561.  
  1562.      The following variables are set by CGETREC when it obtains a record:
  1563.  
  1564.      $CREC_STAT  the status of the record ("A" = Active, "D" = Deleted).
  1565.      $CTAG_FLD   is set to "T" if the file is tagged, "N" if the file is
  1566.                  Noted, or blank if neither.
  1567.      $CPRIORITY_FLD the 'transfer priority' (a number from 1-200) of the
  1568.                  currently loaded catalog record.
  1569.      $CNAME_FLD  the File Name field in the format FILENAME.EXT.
  1570.      $CFDATE_FLD the File Date field in the format YYYYMMDD.
  1571.      $CSIZE_FLD  the File Size field.
  1572.      $CCDATE_FLD the Catalog Date field in the format YYYYMMDD (the date that
  1573.                  a record was imported to the catalog).  This is what
  1574.                  $VIEW_DATE compares to, in order to filter out older records.
  1575.      $CLOC_FLD   the BIF/Location field (base name of the .BIF needed to
  1576.                  download the files.  LOADBIF $CLOC_FLD loads the proper BIF
  1577.                  if necessary).
  1578.      $CAREA_FLD  the BBS Area (conference) the file is in (NEWAREA $CAREA_FLD
  1579.                  accesses the proper area if necessary).
  1580.      $CDAY_FLD   the Transfer Day set for this file (0 = Anyday, 1 = Sunday, 2
  1581.                  = Monday, etc).  Use $DOW to get the current day of the week
  1582.                  for comparison.
  1583.      $CFLAG_FLD  a general purpose flag field that EACH catalog record has,
  1584.                  that you can put to any use you see fit in scripts.
  1585.  
  1586.  
  1587.  
  1588.  
  1589.      Intellicomm v2.01               SCRIPT.DOC                             19
  1590.      
  1591.      
  1592.  
  1593.  
  1594.  
  1595.  
  1596.      Intellicomm v2.01               SCRIPT.DOC                             20
  1597.      
  1598.      
  1599.  
  1600.                       2.  USING THE DETAILED COMMAND SUMMARIES
  1601.  
  1602.  
  1603.      !!PLEASE READ THIS INTRODUCTION!!
  1604.  
  1605.      This section lists all the script commands in alphabetical order, giving
  1606.      detailed information about each command.  If you haven't looked at the
  1607.      section on SCRIPT VARIABLES yet, you should read at least the first
  1608.      couple of paragraphs so you'll know what variables are.  Variables are
  1609.      used in many of the examples below, and are referred to frequently in the
  1610.      command descriptions.  
  1611.  
  1612.      The Command Summaries require some explanation before you use them.  For
  1613.      each script command you will find the COMMAND itself, a SUMMARY showing
  1614.      any parameters the command takes, a DESCRIPTION outlining what the
  1615.      command's purpose is, the ERRORLEVELs the command will set (if any), a
  1616.      SEE ALSO section which points out similar script commands (if any), and
  1617.      an EXAMPLE showing how the command can be used in a real script.
  1618.  
  1619.      2.1  COMMAND Description
  1620.  
  1621.      The COMMAND itself is listed first, followed by a line of underscores.
  1622.  
  1623.      2.2  SUMMARY Description
  1624.  
  1625.      Following the command is the SUMMARY, which quickly shows whether any
  1626.      parameters are accepted, what parameter format is expected (string, 
  1627.      number, or command), and whether the parameter is mandatory or optional. 
  1628.      You'll never use a script command exactly as it's outlined in the SUMMARY
  1629.      section.  For example, the BOXGETS command (displays a box and gets a
  1630.      string from the keyboard) has the following summary:
  1631.  
  1632.      SUMMARY
  1633.  
  1634.       BOXGETS vDATA nMAXLENGTH [sTITLE] [sHELPLINE]
  1635.  
  1636.      You wouldn't actually put this in a script, specifying vDATA, etc., every
  1637.      time you used BOXGETS.  These are simply conventions used in all the
  1638.      SUMMARY sections, which quickly show you:
  1639.  
  1640.       1. Whether any parameters are accepted.  Above you can see that BOXGETS
  1641.          takes at least 'some' sort of parameters, even though you might not
  1642.          understand exactly 'what' as yet.
  1643.       2. It shows you which, if any, parameter(s) are optional.  Optional
  1644.          parameters are enclosed in square brackets and if you omit the
  1645.          parameter some default value is assumed.  The only way to tell
  1646.          exactly what default value will be used is to read the DESCRIPTION of
  1647.          the command (just below the SUMMARY section).
  1648.       3. It shows you what TYPE of parameters are expected, and, in general,
  1649.          what purpose the parameter serves.  The first letter of the parameter
  1650.          (always lowercase) shows you the type of parameter expected, while
  1651.          any characters that follow (always UPPERCASE) simply provide a short
  1652.          description of the purpose the parameter serves.  The BOXGETS command
  1653.          expects a 'v'ariable as the first parameter, a 'n'umber as the second
  1654.  
  1655.  
  1656.  
  1657.  
  1658.      Intellicomm v2.01               SCRIPT.DOC                             21
  1659.      
  1660.      
  1661.  
  1662.          parameter, and 's'trings (text and/or numbers) for the rest of the
  1663.          parameters.  Following is a list of the various parameter types used
  1664.          in the SUMMARY sections below:
  1665.  
  1666.          cPARAMETER  If a parameter begins with a lowercase 'c', then the
  1667.                      script command expects another script COMMAND as the
  1668.                      parameter.  This parameter type is used only by decision-
  1669.                      making commands, such as ONLINE, OFFLINE, WHEN, etc.
  1670.          nPARAMETER  If a parameter begins with a lowercase 'n', then the
  1671.                      script command expects a NUMBER (either a constant number
  1672.                      or a variable holding a number) as the parameter.
  1673.          sPARAMETER  If a parameter begins with a lowercase 's', then the
  1674.                      script command expects a STRING (either a constant string
  1675.                      in double quotes, or a variable holding a string) as the
  1676.                      parameter.  When a string parameter is expected, you can
  1677.                      also get away with specifying a numeric parameter (PRINT
  1678.                      1 is the same as PRINT "1").
  1679.          vPARAMETER  If a parameter begins with a lowercase 'v', then the
  1680.                      script command expects a VARIABLE as the parameter.  This
  1681.                      will only be true of one parameter per command, and it's
  1682.                      always the first parameter following the command.  It's
  1683.                      used by commands that assign new data (ADD, GETS, etc) to
  1684.                      script variables.
  1685.         [PARAMETER] If a parameter is in square brackets, then it is OPTIONAL.
  1686.  
  1687.         ...         If three periods follow all parameters, then the script
  1688.                     command accepts a variable number of parameters which can
  1689.                     be either strings or numbers.  This is normally used with
  1690.                     commands that display data to the screen (or write it to a
  1691.                     text file) to allow you to print the contents of one or
  1692.                     more variables among some constant text.  For example:
  1693.  
  1694.                             VARIABLE s "is"
  1695.                             VARIABLE n 1
  1696.                             PRINT "This " s " text line " n 
  1697.  
  1698.                     The above would print 'This is text line 1' (no quotes). 
  1699.                     It's just a convenience, and it allows you to avoid doing
  1700.                     this:
  1701.  
  1702.                             PRINTNC "This "      ;PRINTNC doesn't add a CR
  1703.                             PRINTNC s
  1704.                             PRINTNC " text line "
  1705.                             PRINT n
  1706.  
  1707.                     Any time you see three periods following all parameters in
  1708.                     the SUMMARY sections below, it means that the command will
  1709.                     group together all parameters you specify (up to the
  1710.                     maximum script line length of 256 characters).
  1711.  
  1712.      2.2.1  How to Specify Parameters
  1713.  
  1714.      Constant strings (in quotes) and constant numbers are NEVER mandatory. 
  1715.      You can always substitute ANY script parameter with ANY type of script
  1716.  
  1717.  
  1718.  
  1719.  
  1720.      Intellicomm v2.01               SCRIPT.DOC                             22
  1721.      
  1722.      
  1723.  
  1724.      variable:
  1725.  
  1726.       PRINT my_variable             ;user defined variable (VARIABLE command)
  1727.       PRINT $DATE                   ;System Variable
  1728.       PRINT GlobalStr[5]            ;Global array member (see SCRTUTOR.DOC)
  1729.       PRINT GlobalStr[my_variable]  ;Global member indexed by my_variable
  1730.       PRINT *minit                  ;Main Setup Variable (see Appendix)
  1731.       PRINT *[G]desc                ;BIF Variable (see Appendix)
  1732.  
  1733.      When a script command is expecting a numeric parameter (a number), if you
  1734.      omit the number (or you specify a variable that is holding a non-numeric
  1735.      value) 0 is assumed unless a specific default value is mentioned in the
  1736.      command DESCRIPTION section.  For example if you did this:
  1737.  
  1738.        variable x "here is some text"  ;store text in 'x'
  1739.        variable y
  1740.        add y x 10  ;y = x + 10
  1741.  
  1742.      then the result in 'y' would be 10, since 'x' is not holding a number (0
  1743.      + 10 = 10).  If you truly did want to "add" text to a number or vice
  1744.      versa (make a string longer), you'd use STRCAT:  Not ADD.
  1745.  
  1746.      NOTE: Script commands that accept another script command (such as the
  1747.      OFFLINE command demonstrated earlier) provide your scripts with decision-
  1748.      making abilities.  All commands that take a command parameter will ONLY
  1749.      execute the command IF a certain condition is true or false.  For
  1750.      example:
  1751.  
  1752.      ONLINE cCOMMAND
  1753.  
  1754.      The ONLINE command ONLY executes cCOMMAND (which signifies any other
  1755.      script command) IF the modem is currently offline.  The WHEN commmand
  1756.      ONLY executes cCOMMAND if/when specific text is found from the BBS, and
  1757.      so forth.  If the condition is false cCOMMAND is not executed, and Icom
  1758.      skips the rest of the script line, and proceeds to the next line of the
  1759.      script.
  1760.  
  1761.      2.3  ERRORLEVEL Description
  1762.  
  1763.      Listed in each ERRORLEVEL section are the numbers (if any) you can check
  1764.      by accessing the $ERRORLEVEL System Variable, after a script command
  1765.      finishes.  If no ERRORLEVEL section exists then the command doesn't
  1766.      modify the $ERRORLEVEL variable.
  1767.  
  1768.      For example, the GETS command gets keyboard input from the user, but you
  1769.      might want to check to see whether the user pressed the [Esc] key, or
  1770.      simply entered nothing.  You can test for these conditions by referring
  1771.      to the Detailed Command Summary of the GETS command, and looking at the
  1772.      ERRORLEVEL section:
  1773.  
  1774.       0  No errors, the user entered something.
  1775.       1  The user pressed the [Enter] key, but didn't enter anything.
  1776.       2  The user pressed the [Esc] key or right mouse button.
  1777.  
  1778.  
  1779.  
  1780.  
  1781.      Intellicomm v2.01               SCRIPT.DOC                             23
  1782.      
  1783.      
  1784.  
  1785.      In a script you could test for these conditions by doing something like
  1786.      the following:
  1787.  
  1788.       variable myvariable
  1789.  
  1790.       while 1               ;loop until BREAK
  1791.        gets myvariable 10   ;10 is the max characters the user can enter
  1792.  
  1793.        if $ERRORLEVEL = 0   ;[Esc] not hit, variable not empty
  1794.         print "Thanks for entering: " myvariable
  1795.         break               ;exit the WHILE loop
  1796.        else                 ;variable empty or [Esc] was pressed
  1797.         print "Please enter something, or press [Esc] to cancel."
  1798.        endif
  1799.       endwhile
  1800.  
  1801.      The $ERRORLEVEL variable remains valid only for a short time, until
  1802.      another script command modifies it.  Make sure you check for errors
  1803.      immediately after the command in question, before using any other
  1804.      commands, or the value of $ERRORLEVEL may not be valid.  If you must
  1805.      check $ERRORLEVEL at some later point, just assign it to your own
  1806.      variable immediately after the command, then check your own variable
  1807.      later:
  1808.  
  1809.       variable MyVariable
  1810.       variable MyErrorlevel
  1811.  
  1812.      GetAgain:
  1813.  
  1814.       gets MyVariable 10
  1815.       assign MyErrorlevel $ERRORLEVEL  ;save the value for later use
  1816.  
  1817.        ;you could not use other script commands which modified
  1818.        ; $ERRORLEVEL ... and later in the script:
  1819.  
  1820.       if MyErrorlevel <> 0             ;not equal to zero?
  1821.        msgwind "Please enter something!"
  1822.        goto GetAgain
  1823.       endif
  1824.  
  1825.  
  1826.  
  1827.  
  1828.      Intellicomm v2.01               SCRIPT.DOC                             24
  1829.      
  1830.      
  1831.  
  1832.                             3.  DETAILED COMMAND SUMMARY
  1833.  
  1834.  
  1835.      ADD______________________________________________________________________
  1836.  
  1837.      SUMMARY
  1838.  
  1839.       ADD vSUM nADDEND1 nADDEND2
  1840.  
  1841.      DESCRIPTION
  1842.  
  1843.       Adds nADDEND1 to nADDEND2 and stores the result in vSUM.  If either of
  1844.       the addends is missing (or contain text instead of a number), ADD will
  1845.       assume 0.
  1846.  
  1847.      SEE ALSO
  1848.  
  1849.       ADD, DIV, MUL, SUB
  1850.  
  1851.      EXAMPLE
  1852.  
  1853.       variable result
  1854.       ADD result 5 10   ;stores 5 + 10 (15) in variable 'result'
  1855.       print result
  1856.  
  1857.      ADDSLASH_________________________________________________________________
  1858.  
  1859.      SUMMARY
  1860.  
  1861.       ADDSLASH vSTRING
  1862.  
  1863.      DESCRIPTION
  1864.  
  1865.       To be used when building filenames, ADDSLASH checks vSTRING to ensure
  1866.       that it has a trailing back slash (\).  If not, one is added.  Note that
  1867.       if the very last character in vSTRING is a colon (a lone drive letter,
  1868.       such as C:), a slash is not added.
  1869.  
  1870.      SEE ALSO
  1871.  
  1872.       STRIPSLASH
  1873.  
  1874.      EXAMPLE
  1875.  
  1876.       variable customdir "C:\TEMP\"  ;default value
  1877.  
  1878.       printnc "Enter directory: "
  1879.       gets customdir 64
  1880.  
  1881.       ADDSLASH customdir   ;add trailing slash if user forgot to add one
  1882.  
  1883.      ALARM____________________________________________________________________
  1884.  
  1885.      SUMMARY
  1886.  
  1887.  
  1888.  
  1889.  
  1890.      Intellicomm v2.01               SCRIPT.DOC                             25
  1891.      
  1892.      
  1893.  
  1894.       ALARM nTIMES
  1895.  
  1896.      DESCRIPTION
  1897.  
  1898.       Sounds an alarm on the PC speaker nTIMES times.  The alarm sounded is
  1899.       the same alarm you hear in manual mode after a connection and a file
  1900.       transfer.  The alarm is only sounded if the user has BOTH of these main
  1901.       setup items turned on (both are on the "General" setup screen):
  1902.  
  1903.       | Sound . . . . . . . . . . On                                  |
  1904.       | Pager . . . . . . . . . . On                                  |
  1905.  
  1906.       You can force these items on by modifying the $SOUND and/or $ALARMS
  1907.       System Variables, if necessary.  If you do modify the values make sure
  1908.       you save the ORIGINAL values first, and restore them when you're done. 
  1909.       See the example below.
  1910.  
  1911.      SEE ALSO
  1912.  
  1913.       TONE, $ALARMS, $SOUND
  1914.  
  1915.      EXAMPLE 1
  1916.  
  1917.       ALARM 1                     ;sound the alarm once
  1918.  
  1919.      EXAMPLE 2
  1920.  
  1921.       variable old_alarms $alarms ;save original value of $ALARMS
  1922.       variable old_sound  $sound  ;save original value of $SOUND
  1923.  
  1924.       assign $alarms 1            ;1 = On, 0 = Off
  1925.       assign $sound  1            ;1 = On, 0 = Off
  1926.       ALARM 3                     ;this will DEFINITELY be sounded
  1927.       assign $alarms old_alarms   ;restore the original values
  1928.       assign $sound old_sound
  1929.  
  1930.      AND______________________________________________________________________
  1931.  
  1932.      SUMMARY
  1933.  
  1934.       AND vRESULT nNUM nBITMASK
  1935.  
  1936.      DESCRIPTION
  1937.  
  1938.       Performs a bitwise AND on nNUM using nBITMASK, and stores the result in
  1939.       vRESULT.  Unless you're a programmer, you probably will never use AND.
  1940.  
  1941.      SEE ALSO
  1942.  
  1943.       OR, SHL, SHR, XOR
  1944.  
  1945.      EXAMPLE
  1946.  
  1947.       variable someflag
  1948.  
  1949.  
  1950.  
  1951.  
  1952.      Intellicomm v2.01               SCRIPT.DOC                             26
  1953.      
  1954.      
  1955.  
  1956.       variable result
  1957.       AND result someflag 1
  1958.       if result = 0
  1959.        print "Bit 1 is CLEAR in variable 'someflag'"
  1960.       else
  1961.        print "Bit 1 is SET in variable 'someflag'"
  1962.       endif
  1963.  
  1964.      APPEND___________________________________________________________________
  1965.  
  1966.      SUMMARY
  1967.  
  1968.       APPEND sSOURCEFILE sTARGETFILE
  1969.  
  1970.      DESCRIPTION
  1971.  
  1972.       Adds the entire contents of file sSOURCEFILE to the end of file
  1973.       sTARGETFILE.  If sTARGETFILE exists, Control-Z characters (if any) are
  1974.       stripped from the end of the file before appending sSOURCEFILE.  If
  1975.       sTARGETFILE doesn't exist it is created if possible.
  1976.  
  1977.       You may (and should) specify a drive and path in both filenames.  If
  1978.       drives/directories are not specified, APPEND assumes the current DOS
  1979.       directory, which could be any drive/directory on the system unless your
  1980.       script issued a CHDIR command recently.
  1981.  
  1982.       NOTE: Neither the source nor the target file should be open (CAPTURE or
  1983.       FOPEN) when APPEND is called.  If you want to APPEND to (or from) the
  1984.       currently open CAPTURE file, close it first:
  1985.  
  1986.        CAPPUSH    ;save filename, open/closed/paused status
  1987.        CAPCLOSE   ;close it
  1988.        APPEND "D:\TEMP\MYDATA.TXT" $CAPTURE_FNAME
  1989.         ... or ...
  1990.        APPEND $CAPTURE_FNAME "D:\TEMP\TMPCAP.CAP"
  1991.        CAPPOP     ;restore to previous state
  1992.  
  1993.       If you have previously FOPENed either the sSOURCEFILE or sTARGETFILE,
  1994.       you should also FCLOSE the file before using APPEND on the file(s).  But
  1995.       FCLOSE causes the current file pointer position to be lost.  If you
  1996.       don't want to lose the position of the file pointer:
  1997.  
  1998.        VARIABLE fpos
  1999.        FTELL fpos myfile       ;store file pointer position
  2000.        ;where 'myfile' is the file handle of the open file
  2001.        FCLOSE myfile           ;close it
  2002.        APPEND ...              ;do your append to or from the file
  2003.        FOPEN myfile ...        ;repeat the FOPEN as it was done earlier
  2004.        FSEEK myfile fpos 1     ;seek back to same position
  2005.  
  2006.      ERRORLEVEL
  2007.  
  2008.       0  Successful.
  2009.       1  Source file couldn't be opened.
  2010.  
  2011.  
  2012.  
  2013.  
  2014.      Intellicomm v2.01               SCRIPT.DOC                             27
  2015.      
  2016.      
  2017.  
  2018.       2  Target file couldn't be opened.
  2019.  
  2020.      SEE ALSO
  2021.  
  2022.       APPENDS, APPENDSNC, COPY, FOPEN, FPUTS, FPUTSNC, FPUTC, FCLOSE
  2023.  
  2024.      EXAMPLE
  2025.  
  2026.       APPEND "C:\TEMP\MYFILE.TXT" "D:\ANOTHER.TXT"
  2027.  
  2028.      APPENDS__________________________________________________________________
  2029.      APPENDSNC________________________________________________________________
  2030.  
  2031.      SUMMARY
  2032.  
  2033.       APPENDS sTARGETFILE sSTRING
  2034.       APPENDSNC sTARGETFILE sSTRING
  2035.  
  2036.      DESCRIPTION
  2037.  
  2038.       APPENDS(tring), adds sSTRING to the file sTARGETFILE (a FILENAME.EXT
  2039.       preferably including a drive and/or directory; D:\PATH\FILENAME.EXT,
  2040.       etc).  If sTARGETFILE exists, Control-Z characters are stripped from the
  2041.       end of the file before sSTRING is added.  If the file doesn't exist, it
  2042.       is created if possible.
  2043.  
  2044.       sSTRING is followed by a Carriage Return (CR) and Line Feed (LF) to
  2045.       terminate the line in the file when APPENDS is used.  APPENDSNC (NC for
  2046.       'N'o 'C'arriage Return) does the same as APPENDS but doesn't terminate
  2047.       the line with CR/LF.  I.e. if you execute multiple APPENDSNC commands,
  2048.       you'll end up with a single line of text in sTARGETFILE.
  2049.  
  2050.       These commands can be used in your scripts to easily keep track of
  2051.       errors/status messages on-disk.  The LIST command can then be used to
  2052.       display the errors/messages when your script ends.  Or you can use FOPEN
  2053.       and FGETS to get each error/status line out of the file, and you can
  2054.       then test the results to do some "post script" error handling or
  2055.       cleanup.  You can also use APPENDS to add new "keywords" to the Tagger's
  2056.       keyword lists (stored in \ICOM\*.KWD files), and you can add notes to
  2057.       BIFs, etc.  
  2058.  
  2059.       NOTE 1: When specifying sTARGETFILE, if you omit the drive and path
  2060.       (D:\PATH\), the CURRENT DOS DIRECTORY is assumed which could be any
  2061.       drive and/or directory on the system.  Always specify full pathnames (or
  2062.       use a CHDIR command) to ensure that you're dealing with the proper
  2063.       directory.
  2064.  
  2065.       NOTE 2: The FOPEN command is not required prior to using APPENDS/
  2066.       APPENDSNC, and in fact the file you're appending to should NOT be open
  2067.       (Icom never leaves BIF, Keyword files, etc., open; it loads them into
  2068.       memory when necessary, then closes them).  APPENDS/NC automatically
  2069.       calls FOPEN prior to appending, and FCLOSE to close the file after the
  2070.       append.  Thus, if you're appending many lines to a text file it would be
  2071.       more efficient to use FOPEN (in append mode), FPUTS or FPUTSNC (several
  2072.  
  2073.  
  2074.  
  2075.  
  2076.      Intellicomm v2.01               SCRIPT.DOC                             28
  2077.      
  2078.      
  2079.  
  2080.       times, if necessary) to add your text, then FCLOSE.  This avoids the
  2081.       calls to FOPEN and FCLOSE which APPENDS/APPENDSNC automatically does for
  2082.       each line, and thus allows 'buffering' of the data for more efficient
  2083.       disk writes.
  2084.  
  2085.      ERRORLEVEL (Both commands)
  2086.  
  2087.       0  Successful.
  2088.       1  sTARGETFILE couldn't be opened.  Either you specified a bad
  2089.          "FILENAME.EXT" (or D:\PATH\FILENAME.EXT ... this command will NOT
  2090.          create directories), or the disk drive door was open, or there were
  2091.          no available DOS 'file handles'; the user can remedy the latter by
  2092.          increasing FILES= in the CONFIG.SYS file.
  2093.       2  sSTRING couldn't be appended (disk write error).  This usually occurs
  2094.          if the disk is full, but could be any number of disk write errors.
  2095.  
  2096.      SEE ALSO
  2097.  
  2098.       APPEND, FOPEN, FPUTSNC, FPUTS, FPUTC, FCLOSE
  2099.  
  2100.      EXAMPLE 1
  2101.  
  2102.       variable errorfile $HOME_DIR  ;put the Icom home dir in 'errorfile'
  2103.       strcat errorfile "ERRORS.!!!" ;add the filename
  2104.       delete errorfile              ;start fresh, kill last error file if any
  2105.        ;when errors are encountered in your script...
  2106.       APPENDS errorfile "<X has occurred> error."
  2107.        ;when your script ends:
  2108.       EXIST errorfile LIST errorfile  ;if errors occurred, list them 
  2109.  
  2110.      EXAMPLE 2
  2111.  
  2112.       variable filename $HOME_DIR "NOTE.KWD" ;Tagger 'Note File' keywords
  2113.  
  2114.        ;NOTE: You shouldn't  modify ANY Icom system files without notifying
  2115.        ; the user (in your script docs) and/or getting permission via keyboard
  2116.        ; input first.
  2117.  
  2118.       APPENDS filename " Note this text "  ;add a new keyword to 'Note'
  2119.  
  2120.       assign filename $BIF_DIR    ;put the Icom BIF Directory in 'filename'
  2121.       strcat filename $BIF_NAME   ;note: the .BIF extension isn't in here
  2122.       strcat filename ".BIF"      ; so we must add it
  2123.  
  2124.        ;BIF 'notes' are always at the end of a BIF and use the format:
  2125.        ; <TAB>"One line of note text"<CR><LF>
  2126.        ; ^I (Control-I) is a <TAB> character, and ^" is used to specify
  2127.        ; double quotes within strings (which must also be surrounded by
  2128.        ; double quotes)
  2129.  
  2130.       APPENDS filename "^I^"Add this line of text to the BIF notes.^""
  2131.  
  2132.      ASSIGN___________________________________________________________________
  2133.  
  2134.  
  2135.  
  2136.  
  2137.      Intellicomm v2.01               SCRIPT.DOC                             29
  2138.      
  2139.      
  2140.  
  2141.      SUMMARY
  2142.  
  2143.       ASSIGN vVARIABLE snNEWDATA
  2144.  
  2145.      DESCRIPTION
  2146.  
  2147.       Copies sNEWDATA (or nNEWDATA; text or a number) to vVARIABLE.  ASSIGN is
  2148.       used when you want to change the contents of an existing variable.  The
  2149.       variable vVARIABLE must be defined with the VARIABLE command (or must be
  2150.       a System/Main Setup/BIF Variable) before using ASSIGN.
  2151.  
  2152.       Note that as with all 's'tring-type parameters, you can also use numbers
  2153.       where necessary.  Either of these will assign the number 1 to
  2154.       'myvariable':
  2155.  
  2156.        ASSIGN myvariable "1"
  2157.        ASSIGN myvariable 1
  2158.  
  2159.      SEE ALSO
  2160.  
  2161.       VARIABLE
  2162.  
  2163.      EXAMPLES
  2164.  
  2165.        variable myvariable
  2166.  
  2167.        ASSIGN myvariable 0            ;myvariable = zero
  2168.        ASSIGN myvariable -1           ;myvariable = minus one
  2169.        ASSIGN myvariable "some text"  ;myvariable = "some text"
  2170.        ASSIGN myvariable $DOW         ;Store Day of Week in myvariable
  2171.        ASSIGN $DL_PROTOCOL "Z"        ;change download protocol to Zmodem
  2172.        ASSIGN $SCRN_COLOR 79          ;change current screen color to
  2173.                                       ; white on red (see COLOR CODES
  2174.                                       ; appendix)
  2175.  
  2176.      BEEP_____________________________________________________________________
  2177.  
  2178.      SUMMARY
  2179.  
  2180.       BEEP
  2181.  
  2182.      DESCRIPTION
  2183.  
  2184.       Sounds a beep on the PC speaker.
  2185.  
  2186.      SEE ALSO
  2187.  
  2188.       TONE
  2189.  
  2190.      EXAMPLE
  2191.  
  2192.       printnc "Roadrunner... "
  2193.       BEEP
  2194.       BEEP
  2195.  
  2196.  
  2197.  
  2198.  
  2199.      Intellicomm v2.01               SCRIPT.DOC                             30
  2200.      
  2201.      
  2202.  
  2203.       print "The coyote's after you."
  2204.       printnc "Roadrunner... "
  2205.       BEEP
  2206.       BEEP
  2207.       print "If he catches you you're through."
  2208.  
  2209.      BOX______________________________________________________________________
  2210.  
  2211.      SUMMARY
  2212.  
  2213.       BOX sBOXTITLE nX1 nY1 nX2 nY2
  2214.  
  2215.      DESCRIPTION
  2216.  
  2217.       The parameters, from left to right are:
  2218.  
  2219.         1. The Box Title (goes in the top border, as you see in Icom boxes).
  2220.         2. The x1 screen column (left to right) of the top corner.
  2221.         3. The y1 screen row (top to bottom) of the top corner.
  2222.         4. The x2 screen column of the bottom corner.
  2223.         5. The y2 screen row of the bottom corner.
  2224.  
  2225.       Screen coordinates start at 1, 1 (top left corner).  A standard text
  2226.       screen (mono or color) is 80 columns wide by 25 rows high (x coordinates
  2227.       range from 1-80, y coordinates range from 1-25).  EGA displays can
  2228.       display 42 rows (y coordinates range from 1-42), and VGA displays can
  2229.       display 50 rows (y coordinates range from 1-50).  The terminal status
  2230.       line is normally occupying the bottom-most screen line and CAN be
  2231.       overwritten with the BOX command (see the NOTE below).  You can check
  2232.       the current number of columns/rows on-screen by accessing the
  2233.       $SCRN_HEIGHT and $SCRN_WIDTH System Variables, if need be.
  2234.  
  2235.       NOTE: The information currently on-screen (if any) is overwritten by the
  2236.       BOX command.  If you wish to save the current screen before displaying
  2237.       your BOX and restore the screen after you're done with it, use VPUSH and
  2238.       VPOP before/after the BOX command, or use the WNDOPEN command which does
  2239.       the same thing as BOX but saves the current screen data, color and
  2240.       cursor coordinates.  Further, BOX does NOT set the logical screen window
  2241.       (see the WINDOW command) so PRINT, PRINTNC, CLS and GOTOXY do not
  2242.       observe the box limits.  Again, use WNDOPEN if this is what you want.
  2243.  
  2244.      SEE ALSO
  2245.  
  2246.       WNDOPEN, $SCRN_HEIGHT, $SCRN_WIDTH
  2247.  
  2248.      EXAMPLE
  2249.  
  2250.       vpush      ;save current screen
  2251.       BOX "Box Title" 1 1 $SCRN_WIDTH $SCRN_HEIGHT
  2252.        ;displays a box that covers the whole screen
  2253.       gotoxy 2 2
  2254.       pause "Press a key and this box is history..."
  2255.       vpop      ;restore screen saved with VPUSH
  2256.  
  2257.  
  2258.  
  2259.  
  2260.      Intellicomm v2.01               SCRIPT.DOC                             31
  2261.      
  2262.      
  2263.  
  2264.       BOX "Box Title" 20 10 60 16
  2265.        ;display a box with top corner at screen column 20, row 10
  2266.        ; and bottom corner at a screen column 60, row 16
  2267.        ; The coordinates are where the box border is drawn, so you'd have from
  2268.        ; 21, 11 to 59, 15 to write in, if you wanted to stay in the borders.
  2269.  
  2270.       printraw 23 13 $NORM_COLOR "Here is some text inside the box."
  2271.        ;printraw takes only two screen coordinates; row (x1) and column (y1)
  2272.        ; to start printing the message at.  $NORM_COLOR is the proper color
  2273.        ; to use inside boxes (it's the color BOX sets the inside of the
  2274.        ; all boxes to; as defined by the user in the main setup).
  2275.  
  2276.      BOXGETS__________________________________________________________________
  2277.  
  2278.      SUMMARY
  2279.  
  2280.       BOXGETS vINPUT nMAXLEN [sBOXTITLE] [sHELPLINE]
  2281.  
  2282.      DESCRIPTION
  2283.  
  2284.       Displays a centered box on the screen (adjusted to size according to the
  2285.       parameters specified after BOXGETS) gets user input of no more than
  2286.       nMAXLEN characters, and stores the user input in variable vINPUT. 
  2287.       sBOXTITLE (if any) is displayed in the box border and sHELPLINE (if any)
  2288.       is displayed centered inside the box just above the input field.  If
  2289.       variable vINPUT contains any data, it is offered to the user as a
  2290.       default response.
  2291.  
  2292.       If you wish to display a Help Line, but DON'T want a Box Title, simply
  2293.       specify "" as the Box Title (e.g. BOXGETS myvar 10 "" "Help Line").
  2294.  
  2295.       The box and user input line use the same colors that Icom uses on its
  2296.       own boxes/menus, etc., as defined by the user in the Icom main setup.
  2297.       Output from the BOXGETS command looks like this (with graphics
  2298.       characters instead of text) with a 'Help Line':
  2299.  
  2300.         +=| Box Title |====================================================+
  2301.         |                                                                  |
  2302.         |  This is the Help Line where you can give the user instructions  |
  2303.         |                                                                  |
  2304.         |  ><User input here>                                              |
  2305.         |                                                                  |
  2306.         +==================================================================+
  2307.  
  2308.       It looks like this if no Help Line is specified (size adjusted according
  2309.       to the 'len' parameter:
  2310.  
  2311.                               +=| Box Title |========+
  2312.                               |                      |
  2313.                               |  ><User input here>  |
  2314.                               |                      |
  2315.                               +======================+
  2316.  
  2317.       The contents of the screen that the box overwrites is saved prior to
  2318.  
  2319.  
  2320.  
  2321.  
  2322.      Intellicomm v2.01               SCRIPT.DOC                             32
  2323.      
  2324.      
  2325.  
  2326.       displaying the box and restored when the user presses [Enter] or the
  2327.       left mouse button, [Esc] or the right mouse button, or presses a key
  2328.       that matches a $HOTKEY_? variable (see the example).  When the box is on
  2329.       the screen, the user can type text (or numbers, symbols, etc.) on the
  2330.       input line to the maximum length specified by the 'len' parameter, and
  2331.       can use any of the following editing keys:
  2332.  
  2333.        [Left]       Moves the cursor one position to the left (if possible).
  2334.        [Right]      Moves the cursor one position to the right (if possible). 
  2335.  
  2336.        [Home]       Moves the cursor to the first character on the input line.
  2337.        [End]        Moves the cursor to the the position after the last
  2338.                     character on the input line.
  2339.        [Ctrl-Left]  Moves the cursor to the beginning of the previous word.
  2340.        [Ctrl-Right] Moves the cursor to the beginning of the next word.
  2341.        [Ctrl-End]   Deletes all characters from the cursor to the end of the
  2342.                     input line.
  2343.        [Ins]        Toggles insert/typeover mode (insert/typeover mode is
  2344.                     saved from one BOXGETS/GETS to the next).
  2345.        [Del]        Deletes the character under (at) the cursor pulling
  2346.                     characters from the right (if any) to the cursor position.
  2347.        [Backspace]  Deletes the character to the left of the cursor, moves the
  2348.                     cursor left one position, pulling characters to the right
  2349.                     (if any) along with it.
  2350.        [Enter]      Ends BOXGETS, restores the screen (see ERRORLEVEL below).
  2351.        [Esc]        Ends BOXGETS, restores the screen (see ERRORLEVEL below).
  2352.  
  2353.       The mouse can also be used to move the cursor by moving it left/right,
  2354.       and pressing the Left mouse button is equivalent to pressing the [Enter]
  2355.       key while pressing the Right mouse button is equivalent to pressing the
  2356.       [Esc] key.
  2357.  
  2358.       As well, while the user is entering text in the box, certain 'hotkeys'
  2359.       remain active for convenience.  The hotkeys available are:
  2360.  
  2361.        [Alt-A]  Call Editor (internal or external as defined in main setup).
  2362.        [Alt-J]  Jump to DOS shell.
  2363.        [Alt-N]  User-defined Hotkey 1 (defined in main setup).
  2364.        [Alt-O]  User-defined Hotkey 2    ""          "" 
  2365.        [Alt-V]  Call Archiver (as defined in main setup).
  2366.  
  2367.       If the user presses any of these hotkeys while entering text in the edit
  2368.       box, control is temporarily turned over to the task the user selected. 
  2369.       When the user exits the called task control returns to the edit box with
  2370.       everything exactly as it was before the hotkey was pressed.  The same
  2371.       applies to the GETS/GETSXY (BOXGETS without the box) commands.
  2372.       
  2373.       NOTE 1: Offering default responses (by placing the default in variable
  2374.       'var' before calling BOXGETS) is a handy feature, but won't be practical
  2375.       in all cases.  Where default responses are not possible, make sure that
  2376.       you CLEAR your variable before calling BOXGETS (ASSIGN myvariable ""
  2377.       clears a variable).  See the EXAMPLE for more information.
  2378.  
  2379.       NOTE 2: If a default is offered, the user can edit it using the cursor
  2380.  
  2381.  
  2382.  
  2383.  
  2384.      Intellicomm v2.01               SCRIPT.DOC                             33
  2385.      
  2386.      
  2387.  
  2388.       keys mentioned above.  However, if the user presses a NON-editing key (a
  2389.       letter, number, etc) as the first character, the default response is
  2390.       cleared automatically.  It's assumed that the user didn't want the
  2391.       default if anything but an editing key is pressed as the first key.
  2392.  
  2393.      ERRORLEVEL
  2394.  
  2395.       0   The user entered something (variable vINPUT contains data) then
  2396.           pressed the [Enter] key or left mouse button.
  2397.       1   The user pressed [Enter], but variable vINPUT is empty ... nothing
  2398.           was entered.
  2399.       2   The user pressed the [Esc] key or right mouse button to cancel.  If
  2400.           this occurs, the contents of variable vINPUT reverts to its original
  2401.           value whether the user changed it on the input line or not.
  2402.      256+ If a value of 256 or greater is in $ERRORLEVEL when BOXGETS returns,
  2403.           the user pressed a key defined in one of the $HOTKEY_? variables. 
  2404.           See the example for details.
  2405.  
  2406.      SEE ALSO
  2407.  
  2408.       GETS, GETSXY, INKEY
  2409.  
  2410.      EXAMPLE 1
  2411.  
  2412.       variable myvariable 5  ;define 'myvariable', assign 5 as a default.
  2413.  
  2414.       BOXGETS myvariable 3 "Capturing Bulletin" "Enter bulletin to capture"
  2415.        ;a box would be displayed as outlined above, and on the 'User Input'
  2416.        ; line, 5 would be offered as a default bulletin number.
  2417.  
  2418.        ;if $ERRORLEVEL is equal to 0, the user entered something, so we
  2419.        ; execute the subroutine 'cap_bulletin'.
  2420.       if $ERRORLEVEL = 0 gosub cap_bulletin
  2421.  
  2422.       assign myvariable ""  ;clear the contents of 'myvariable' (no default).
  2423.       BOXGETS myvariable 64 "Box Title" "Help Line" ;example of no default
  2424.  
  2425.       return            ;exit the script
  2426.  
  2427.      cap_bulletin:
  2428.       send "B " myvariable " NS" ;send PCBoard [B]ulletin command
  2429.       waitfor "Command? " 120    ;wait 2 minutes to return to menu prompt.
  2430.       return                     ;return from subroutine
  2431.  
  2432.      EXAMPLE 2 ($HOTKEY_? USAGE -- ADVANCED)
  2433.  
  2434.       variable s
  2435.       
  2436.       assign s "SOMEFILE.EXT"  ;a default value for BOXGETS
  2437.       assign $HOTKEY_1 8448    ;Assign [Alt-F] to $HOTKEY_1 for BOXGETS
  2438.                                ; If the user presses [Alt-F] while entering
  2439.                                ; text, BOXGETS will set $ERRORLEVEL to 8448
  2440.                                ; (the value of the key pressed).
  2441.       BOXGETS s 64 "Upload" "Enter filename or press [Alt-F] for File Picker"
  2442.  
  2443.  
  2444.  
  2445.  
  2446.      Intellicomm v2.01               SCRIPT.DOC                             34
  2447.      
  2448.      
  2449.  
  2450.       assign $HOTKEY_1 0     ;clear the hotkey
  2451.  
  2452.       switch $ERRORLEVEL
  2453.        case 0                ;regular text was entered
  2454.         upload $UL_PROTOCOL s
  2455.        endcase
  2456.        case 1                 ;'s' is empty or [Esc] was pressed
  2457.        case 2
  2458.        endcase
  2459.        case 8448              ;[Alt-F] was pressed
  2460.         variable lstname $HOME_DIR "GETFNAME.LST" ;C:\ICOM\GETFNAME.LST
  2461.         stritem s $UL_PATH 1            ;store 1st dir on U/L PATH in s
  2462.         getfname s "Upload" "Please ^"Select^" one or more files to upload"
  2463.         notexist lstname goto skip_ul
  2464.         strins lstname "@" 0 1          ;@C:\ICOM\GETFNAME.LST
  2465.         upload "Z" lstname              ;uploads all files on the list
  2466.          ;Confused?  See the GETFNAME detailed summary
  2467.        endcase
  2468.       endswitch
  2469.  
  2470.         ;Note that the above can be accomplished with a simple UPLOAD command.
  2471.         ; If you don't specify a filename after UPLOAD, basically the same
  2472.         ; process as the above is carried out by UPLOAD.
  2473.  
  2474.      CADDREC__________________________________________________________________
  2475.  
  2476.      SUMMARY
  2477.  
  2478.       CADDREC
  2479.  
  2480.      DESCRIPTION
  2481.  
  2482.       CatalogADDRECord adds a new record to the currently open Tagger catalog
  2483.       (see COPEN).  The contents of the new record will be the current
  2484.       contents of the various Tagger record fields (explained in
  2485.       SCRTUTOR.DOC).  See the example for details.
  2486.  
  2487.       NOTE: The $CCDATE_FLD (Catalog Date field) is automatically set to
  2488.       'today' by CADDREC.
  2489.  
  2490.      ERRORLEVEL
  2491.  
  2492.       0 = Record successfully added.
  2493.       1 = Unable to add record (disk write error, etc).
  2494.  
  2495.      SEE ALSO
  2496.  
  2497.       CPUTREC
  2498.  
  2499.      EXAMPLE
  2500.  
  2501.       notexist "C:\TEST\SOMEFILE.ZIP" exit  ;some file you wish to import
  2502.  
  2503.        ;NOTEXIST (as well as EXIST,FINDFIRST,FINDNEXT) sets various System
  2504.  
  2505.  
  2506.  
  2507.  
  2508.      Intellicomm v2.01               SCRIPT.DOC                             35
  2509.      
  2510.      
  2511.  
  2512.        ; Variables which provide information about the file that was found.
  2513.        ; See FINDFIRST for details.  We're only interested in $FDATE here
  2514.        ; (the date of the file)
  2515.  
  2516.       copen "FILELIST"
  2517.       cclearbuf                             ;clear all the fields
  2518.  
  2519.       assign $CNAME_FLD "SOMEFILE.ZIP"
  2520.       date2cdate $CFDATE_FLD $FDATE         ;file date to dBASE format
  2521.       
  2522.        ;if you want to tag the file for upload you must either do it after
  2523.        ; the new record has been added (with CTAGREC) or you must be sure
  2524.        ; to include the "Upload Pending> BIFID1;BIFID2" line to the end of
  2525.        ; the file description, to tell Icom where to upload the file.  A
  2526.        ; simple tag isn't good enough when dealing with the FILELIST (upload) 
  2527.        ; catalog
  2528.        
  2529.       assign $CTAG_STAT "T"   ;tagged
  2530.       cputdesc "This is a description of SOMEFILE.ZIP.  It might continue on"
  2531.       cputdesc "for several lines...  See CPUTDESC for details."
  2532.       cputdesc "Upload Pending^P JOESBBS"
  2533.  
  2534.        ;Note that ^P (Ctrl-P) is the proper character to use after Upload
  2535.        ; Pending and Uploaded To.  This is the hard way to tag a file and
  2536.        ; it should only be attempted when adding new records with CADDREC
  2537.        ; (if even then).  Read on for an easier way.
  2538.  
  2539.        ;Once you get all the fields (in memory) set up the way you want them,
  2540.        ; go ahead and call CADDREC to add the new data to the catalog.
  2541.  
  2542.       CADDREC
  2543.  
  2544.       if $ERRORLEVEL = 0      ;was CADDREC successful?
  2545.        variable RecordNumber  ;Yes
  2546.        ctell RecordNumber     ;what record # did we add?
  2547.        print "Record #" RecordNumber " added to FILELIST catalog."
  2548.         ;you could perform 'CTAGREC RecordNumber "JOESBBS"' here and
  2549.         ; achieve the same effect as the (more difficult) tag above.
  2550.       else
  2551.        print "Unable to add record to FILELIST."
  2552.       endif
  2553.  
  2554.       cclose
  2555.  
  2556.      CAPCLOSE_________________________________________________________________
  2557.  
  2558.      SUMMARY
  2559.  
  2560.       CAPCLOSE
  2561.  
  2562.      DESCRIPTION
  2563.  
  2564.       Closes the current capture file, if open (no harm is done if the capture
  2565.       file was already closed).  To PAUSE the capture file without closing it,
  2566.  
  2567.  
  2568.  
  2569.  
  2570.      Intellicomm v2.01               SCRIPT.DOC                             36
  2571.      
  2572.      
  2573.  
  2574.       use the CAPPAUSE command.
  2575.  
  2576.      SEE ALSO
  2577.  
  2578.       CAPTURE, CAPPAUSE, $CAP_NAME, $CAP_STAT
  2579.  
  2580.      EXAMPLE
  2581.  
  2582.        dial "A BBS"   ;capture is normally opened automatically on connect
  2583.        CAPCLOSE       ;...use CAPCLOSE to close it if you like.
  2584.  
  2585.      CAPPAUSE_________________________________________________________________
  2586.  
  2587.      SUMMARY
  2588.  
  2589.       CAPPAUSE
  2590.  
  2591.      DESCRIPTION
  2592.  
  2593.       Toggles the pause status of the capture file (if open).  If the capture
  2594.       file is currently unpaused (capturing), then CAPPAUSE pauses it.  If
  2595.       paused, CAPPAUSE unpauses it.  While paused, nothing received from the
  2596.       BBS, or printed with PRINT, PRINTNC or PAUSE is written in the file.
  2597.  
  2598.       You can check the current state of the capture file by accessing the
  2599.       $CAP_STAT System Variable.
  2600.  
  2601.      SEE ALSO
  2602.  
  2603.       CAPPUSH, CAPPOP, CAPTURE, CAPCLOSE, $CAP_NAME, CAP_STAT
  2604.  
  2605.      EXAMPLE
  2606.  
  2607.       cappush
  2608.       if $CAP_STAT = 1 CAPPAUSE    ;pause if open
  2609.  
  2610.       print "This portion of the online session will not be captured."
  2611.       send "CHAT"
  2612.       chat
  2613.       
  2614.       cappop  ;restore the previous state (open/closed/paused)
  2615.  
  2616.      CAPSTAMP_________________________________________________________________
  2617.  
  2618.      SUMMARY
  2619.  
  2620.       CAPSTAMP
  2621.  
  2622.      DESCRIPTION
  2623.  
  2624.        Stamps the same type of header that Icom itself stamps:
  2625.  
  2626.      ==<< YY-MM-DD HH:MM:SS BIFID - BBS Name >>============================
  2627.  
  2628.  
  2629.  
  2630.  
  2631.      Intellicomm v2.01               SCRIPT.DOC                             37
  2632.      
  2633.      
  2634.  
  2635.       in the current capture file (if open) and if *capstamp (the main setup
  2636.       option 'Stamp Date/Time Cap Open' is on.
  2637.  
  2638.      ERRORLEVEL
  2639.  
  2640.      SEE ALSO
  2641.  
  2642.      EXAMPLE
  2643.  
  2644.       variable old_stamp *capstamp
  2645.  
  2646.       capture "NEWCAP.CAP"
  2647.       assign *capstamp 1       ;to make sure it gets stamped, whether the user
  2648.                                ; has this option turned on or not
  2649.       CAPSTAMP
  2650.  
  2651.       assign *capstamp old_stamp
  2652.  
  2653.      CAPPUSH__________________________________________________________________
  2654.      CAPPOP___________________________________________________________________
  2655.  
  2656.      SUMMARY
  2657.  
  2658.       CAPPUSH
  2659.       CAPPOP
  2660.  
  2661.      DESCRIPTION
  2662.  
  2663.       CAPPUSH saves the current $CAP_NAME (capture filename
  2664.       D:\PATH\FILENAME.EXT) and $CAP_STAT (open/closed/paused status) to an
  2665.       internal buffer.  CAPPOP restores the capture filename/status saved with
  2666.       the last CAPPUSH (multiple times, if necessary).  Every time you call
  2667.       CAPPUSH, you overwrite the previously saved values.  I.e. no "stack" is
  2668.       available to save multiple capture filenames.  You're free to implement
  2669.       your own form of CAPPUSH if you must save multiple capture filenames in
  2670.       your scripts:
  2671.  
  2672.        variable capname1 $CAPTURE_NAME
  2673.        variable capstat1 $CAPTURE_STAT
  2674.          ...later
  2675.        variable capname2 $CAPTURE_NAME
  2676.        variable capstat2 $CAPTURE_STAT
  2677.          ...restore as needed
  2678.        assign $CAPTURE_NAME capname2
  2679.        assign $CAPTURE_STAT capstat2
  2680.  
  2681.          ...etc.
  2682.  
  2683.      SEE ALSO
  2684.  
  2685.       CAPCLOSE, CAPPAUSE, CAPTURE, $CAP_NAME, $CAP_STAT
  2686.  
  2687.      EXAMPLE
  2688.  
  2689.  
  2690.  
  2691.  
  2692.      Intellicomm v2.01               SCRIPT.DOC                             38
  2693.      
  2694.      
  2695.  
  2696.       CAPPUSH                   ;save old capture filename/status
  2697.       capture "\TEMP\TEMP.CAP"  ;open a new capture file
  2698.       send "B 15 NS"            ;PCBoard, show bulletin #15 in non-stop mode
  2699.       waitfor "Command? "       ;wait for BBS main menu
  2700.       CAPPOP                    ;restore the original capture filename/state
  2701.  
  2702.      CAPTURE__________________________________________________________________
  2703.  
  2704.      SUMMARY
  2705.  
  2706.       CAPTURE [sCAPFILE ...]
  2707.  
  2708.      DESCRIPTION
  2709.  
  2710.       CAPTURE closes the current capture file (if open), then opens a new
  2711.       capture file.  sCAPFILE may contain the full D:\PATH\FILENAME.EXT
  2712.       (drive, path, filename, extension) of the new capture file.  If you omit
  2713.       D:\PATH\ or .EXT, the D:\PATH\ and/or .EXT is taken from the current
  2714.       contents of $CAP_NAME (the last capture file opened, or the default
  2715.       capture filename as defined in the Icom main setup).
  2716.  
  2717.       Note that CAPTURE accepts multiple parameters, and the purpose of this
  2718.       is to allow you to build filenames based on the contents of variables:
  2719.  
  2720.        variable mycapdrive "D:"
  2721.        variable mycapdir "\TEMP\CAP\"
  2722.        variable mycapfname "TEMP.CAP"
  2723.  
  2724.        CAPTURE mycapdrive mycapdir mycapfname
  2725.  
  2726.       The above is the same as CAPTURE "D:\TEMP\CAP\TEMP.CAP".
  2727.  
  2728.       If the sCAPFILE parameter is omitted (or is a blank) and the capture
  2729.       file is currently closed, CAPTURE prompts the user for a new capture
  2730.       filename.  If the capture file is currently open, the Close/Pause menu
  2731.       is displayed (same as pressing [Alt-L] from Terminal Mode).  Thus, you
  2732.       can use CAPTURE to interact with the user as well, possibly to prompt
  2733.       for a custom capture filename.
  2734.  
  2735.       When a capture is open, Icom appends each line sent from the BBS *and*
  2736.       any data your script displays with the PRINT, PRINTNC or PAUSE commands,
  2737.       to the end of the capture file.  CAPTURE always adds to the end of files
  2738.       if they exist; it never overwrites files.  If you wish to start a new
  2739.       capture file, simply use a DELETE, RENAME, or RENUMBER command prior to
  2740.       calling CAPTURE.
  2741.  
  2742.       You can later view the capture file to review the BBS session, using
  2743.       either an external text file viewer, or Icom's built-in File Viewer
  2744.       (also see the LIST command; you can also have your script display
  2745.       capture files via the File Viewer).  See the EXAMPLE below for useful
  2746.       capture techniques.
  2747.  
  2748.       NOTE 1: The "Stamp Date/Time Cap Open" item on the Icom main setup
  2749.       General Settings screen controls whether the CAPTURE command stamps
  2750.  
  2751.  
  2752.  
  2753.  
  2754.      Intellicomm v2.01               SCRIPT.DOC                             39
  2755.      
  2756.      
  2757.  
  2758.       newly opened capture files with a line similar to this:
  2759.  
  2760.       ==<< YY-MM-DD HH:MM:SS BIFNAME - BBS Description >>====================
  2761.  
  2762.       These lines can be useful in processing capture files after an online
  2763.       session (either by eye or with the script file I/O commands), since they
  2764.       give you both the date/time of the connection (always in the format YY-
  2765.       MM-DD HH:MM:SS [Year-Month-Day  Hour:Minute:Second]), and the BIF ID. 
  2766.       However, there may be times when you want to disable this capture
  2767.       stamping.  If the need arises you can do so by modifying the *capstamp
  2768.       Main Setup Variable:
  2769.  
  2770.         variable old_capstamp *capstamp  ;save old value
  2771.         assign *capstamp 0               ;0 = Off
  2772.         CAPTURE "SOMEFILE.CAP"           ;won't stamp date/time line on open
  2773.         assign *capstamp old_capstamp    ;restore previous value
  2774.  
  2775.       NOTE 2: As mentioned earlier, if you omit the drive, path, or extension
  2776.       when specifying the sCAPFILE parameter, CAPTURE simply "fills in" the
  2777.       portion you DO specify.  For example, if you did this:
  2778.  
  2779.         CAPTURE "C:\ICOM\LST\MYLIST.NEW"
  2780.         CAPTURE "ICOM"
  2781.  
  2782.       then the second CAPTURE command would capture to C:\ICOM\LST\ICOM.NEW. 
  2783.       Only a filename was specified in the second CAPTURE command, so that's
  2784.       all CAPTURE replaces.  This can be useful in many cases ... and can
  2785.       produce unexpected results in other cases if you don't keep it in mind. 
  2786.       To ensure that you're capturing to the exact drive/directory/filename/
  2787.       extension you want, make sure you SPECIFY them in the CAPTURE command.  
  2788.  
  2789.      ERRORLEVEL
  2790.  
  2791.       0  Successful capture open.
  2792.       1  Unable to open capture file (bad filename, disk full, or no file
  2793.          handles).  A status window (MSGWIND) will be displayed by CAPTURE
  2794.          automatically if the open fails, to notify the user.  So there's no
  2795.          need to display an error message in the script, but you might want to
  2796.          abort a specific task, such as sending a command to the BBS to
  2797.          display a long list of files, etc., if you get an error opening the
  2798.          file.
  2799.          Note also that if a disk write error occurs while Icom is updating
  2800.          (adding to) the capture file, an error is displayed to the user and
  2801.          the capture file is automatically closed.
  2802.  
  2803.      SEE ALSO
  2804.  
  2805.       CAPCLOSE, CAPPAUSE, DELETE, RENAME, RENUMBER, $CAP_NAME, $CAP_STAT
  2806.  
  2807.      EXAMPLE
  2808.  
  2809.       variable key
  2810.  
  2811.       CAPPUSH                    ;save current capture filename/status
  2812.  
  2813.  
  2814.  
  2815.  
  2816.      Intellicomm v2.01               SCRIPT.DOC                             40
  2817.      
  2818.      
  2819.  
  2820.       CAPTURE "\TEMP\BLT5.CAP"   ;close curent cap, open a new capture file
  2821.       send "B 5 NS"              ;PCBoard read bulletin 5, non-stop
  2822.       waitfor "Command?" 120
  2823.  
  2824.       msgopen "Capturing bulletin 1 to printer; ready printer and press a key"
  2825.       inkeyw key      ;pause for a keystroke or mouse click
  2826.       msgclose        ;close the message window
  2827.       send "B 1 NS"   ;Tell the BBS to display bulletin 1, non-stop
  2828.       CAPTURE $PRN    ;start capturing to the printer
  2829.       waitfor "Command?" 120
  2830.  
  2831.       CAPPOP          ;restore the original capture filename and state
  2832.  
  2833.      CCLEARBUF________________________________________________________________
  2834.  
  2835.      SUMMARY
  2836.  
  2837.       CCLEARBUF
  2838.  
  2839.      DESCRIPTION
  2840.  
  2841.       Clears $CCDATE_FLD, $CDAY_FLD, $CFDATE_FLD, $CFLAG_FLD, $CLOC_FLD,
  2842.       $CNAME_FLD, $CPRIORITY_FLD, $CSIZE_FLD, $CTAG_FLD, and the file (record)
  2843.       description buffer.  Use CCLEARBUF to clear the entire record buffer
  2844.       before you ASSIGN various items to various fields and CADDREC (add a new
  2845.       record to the catalog).  Note that CCLEARBUF doesn't clear any records
  2846.       on-disk.  It only clears the catalog record buffer (where records are
  2847.       loaded from disk when you perform a CGETREC).
  2848.  
  2849.      SEE ALSO
  2850.  
  2851.       CCLEARDESC
  2852.  
  2853.      EXAMPLE
  2854.  
  2855.       copen "NEWFILES"
  2856.  
  2857.       CCLEARDESC
  2858.       assign $NAME_FLD "SOMEFILE.EXT"
  2859.       assign $CLOC_FLD "BIFID"
  2860.       caddrec
  2861.       cclose
  2862.  
  2863.      CCLEARDESC_______________________________________________________________
  2864.  
  2865.      SUMMARY
  2866.  
  2867.       CCLEARDESC
  2868.  
  2869.      DESCRIPTION
  2870.  
  2871.       Clears the catalog description buffer (memory only).  The description
  2872.       buffer is located in memory and it is where file descriptions are loaded
  2873.       when you perform a CGETREC.  CGETDESC / CPUTDESC then allow you to
  2874.  
  2875.  
  2876.  
  2877.  
  2878.      Intellicomm v2.01               SCRIPT.DOC                             41
  2879.      
  2880.      
  2881.  
  2882.       access this memory buffer.
  2883.  
  2884.       Use CCLEARDESC to quickly clear out the description buffer, when you
  2885.       want to CPUTDESC an entirely new description in the buffer (such as
  2886.       clearing the description before using the FILE_ID.DIZ description).
  2887.  
  2888.      SEE ALSO
  2889.  
  2890.       CCLEARBUF
  2891.  
  2892.      EXAMPLE
  2893.  
  2894.       copen "NEWFILES"
  2895.       cgetrec
  2896.       CCLEARDESC
  2897.       cputdesc "This is a new description."
  2898.       cputrec
  2899.       cclose
  2900.  
  2901.      CCLOSE___________________________________________________________________
  2902.  
  2903.      SUMMARY
  2904.  
  2905.       CCLOSE
  2906.  
  2907.      DESCRIPTION
  2908.  
  2909.       Closes the currently open Tagger catalog (see COPEN).  CCLOSE is called
  2910.       automatically when your script ends, if you forget to call it yourself. 
  2911.       But you should get into the habit of doing it yourself in case it
  2912.       becomes necessary to remove this auto-CCLOSE protection in the future.
  2913.  
  2914.      SEE ALSO
  2915.  
  2916.       COPEN
  2917.  
  2918.      EXAMPLE
  2919.  
  2920.       ;See SCRTUTOR.DOC for real examples
  2921.  
  2922.       COPEN "NEWFILES"
  2923.       CCLOSE
  2924.  
  2925.      CDATE2DATE_______________________________________________________________
  2926.  
  2927.      SUMMARY
  2928.  
  2929.       CDATE2DATE vDATE sCDATE
  2930.  
  2931.      DESCRIPTION
  2932.  
  2933.       Converts a Catalog/dBASE date to the date format the user has set up in
  2934.       the Icom main setup.  Catalog dates are stored in the format YYYYMMDD
  2935.       (YearMonthDay), which is great for sorting an indexing... but not so
  2936.  
  2937.  
  2938.  
  2939.  
  2940.      Intellicomm v2.01               SCRIPT.DOC                             42
  2941.      
  2942.      
  2943.  
  2944.       great for human consumption.  Use CDATE2DATE to easily convert Catalog
  2945.       dates ($VIEW_DATE, $CCDATE_FLD, $CFDATE_FLD) to a more eye-pleasing
  2946.       format.
  2947.  
  2948.      SEE ALSO
  2949.  
  2950.       DATE2CDATE
  2951.  
  2952.      EXAMPLE
  2953.  
  2954.       variable vdate
  2955.       variable fdate
  2956.       variable cdate
  2957.       copen "NEWFILES"
  2958.       CDATE2DATE vdate $VIEW_DATE   ;current View Date of catalog
  2959.  
  2960.       cgetrec                       ;grab a record (any one will do)
  2961.       CDATE2DATE fdate $CFDATE_FLD  ;File Date
  2962.       CDATE2DATE cdate $CCDATE_FLD  ;Catalog Date
  2963.  
  2964.       print "NEWFILES Catalog.  Current View Date: " vdate
  2965.       print "Filename    : " $CNAME_FLD
  2966.       print "File Size   : " $CSIZE_FLD
  2967.       print "File Date   : " fdate
  2968.       print "Catalog Date: " cdate
  2969.  
  2970.       cclose
  2971.  
  2972.      CDATEDIFF________________________________________________________________
  2973.  
  2974.      SUMMARY
  2975.  
  2976.       CDATEDIFF vDIFFERENCE sCDATE1 sCDATE2
  2977.  
  2978.      DESCRIPTION
  2979.  
  2980.       Subtracts sCDATE2 from sCDATE1 and stores the difference (in days) in
  2981.       vDIFFERENCE.  Both sCDATE1 and sCDATE2 must contain valid dates in
  2982.       Tagger catalog (dBASE) format: YYYYMMDD.
  2983.  
  2984.       NOTE: If sCDATE1 is more recent than sCDATE2, you'll get a negative
  2985.       number in vDIFFERENCE.  sCDATE2 is subtracted FROM sCDATE1, so sCDATE2
  2986.       should be the same as, or more recent than, sCDATE1.  You'll almost
  2987.       always use this to compare a record's Catalog Date ($CCDATE_FLD) or File
  2988.       Date ($CFDATE) with today's date ($DATE) ... and since you know that a
  2989.       Catalog Date can never be more recent than today's date, it's a simple
  2990.       matter to use today's date as the second date parameter.  A file date is
  2991.       another story, and many BBS operators do post files with dates well into
  2992.       the future (01-01-95, etc), to keep the file from being purged from the
  2993.       listings.  You can handle that problem as well.  See the example for
  2994.       details.
  2995.  
  2996.      SEE ALSO
  2997.  
  2998.  
  2999.  
  3000.  
  3001.      Intellicomm v2.01               SCRIPT.DOC                             43
  3002.      
  3003.      
  3004.  
  3005.       DATE2CDATE
  3006.  
  3007.      EXAMPLE
  3008.  
  3009.       variable diff
  3010.       variable today
  3011.  
  3012.        ;first, we must convert today's date to dBASE format before it'll be
  3013.        ; accepted by CDATEDIFF
  3014.  
  3015.       date2cdate today $DATE
  3016.  
  3017.       copen "NEWFILES"
  3018.       cgetrec           ;get a record
  3019.  
  3020.        ;While IF isn't smart enough to do a real date comparison, it works in
  3021.        ; this case since the dates are stored in the format YYYYMMDD.
  3022.        ; ASCII-wise, 0 is 'less than' 9, so if the current record has a year
  3023.        ; that is 'greater than' the current year, or a month 'greater than'
  3024.        ; the current month, or a day 'greater than' today ... we'll know that
  3025.        ; its date is more recent than today (in which case CDATEDIFF is
  3026.        ; invalid since we're comparing to 'today' in the example).  This ONLY
  3027.        ; works in this one case, with the dates stored in the format YYYYMMDD.
  3028.        ; See the IF summary for details on string comparisons (these dates are
  3029.        ; just strings of ASCII characters to IF).
  3030.  
  3031.       print "Filename: " $CNAME_FLD
  3032.  
  3033.       if $CFDATE_FLD > today    ;the File Date is greater than today's date?
  3034.        assign diff 0
  3035.       else
  3036.        cdatediff diff $CFDATE_FLD today
  3037.       endif
  3038.       print "File Age: " diff " day(s) old"
  3039.  
  3040.       cdatediff diff $CCDATE_FLD today
  3041.       print "Imported: " diff " day(s) ago"
  3042.  
  3043.       cclose
  3044.  
  3045.      CDELREC__________________________________________________________________
  3046.  
  3047.      SUMMARY
  3048.  
  3049.       CDELREC nRECNUMBER
  3050.  
  3051.      DESCRIPTION
  3052.  
  3053.       Toggles the deleted status of record nRECNUMBER in the currently open
  3054.       Tagger catalog (see COPEN).  With most other record-oriented commands
  3055.       the nRECNUMBER parameter is optional.  But it's mandatory with CDELREC
  3056.       so that you're always deleting precisely the record you had in mind.
  3057.  
  3058.  
  3059.  
  3060.  
  3061.      Intellicomm v2.01               SCRIPT.DOC                             44
  3062.      
  3063.      
  3064.  
  3065.      ERRORLEVEL
  3066.  
  3067.       0  Deleted status successfully toggled.
  3068.       1  Invalid nRECNUMBER or disk write error.
  3069.  
  3070.      EXAMPLE
  3071.  
  3072.       variable record
  3073.  
  3074.       copen "NEWFILES"
  3075.       csetsort -1      ;-1 = Unsorted (CGETREC ignores $VIEW_DATE)
  3076.  
  3077.        ;delete any records with a Catalog Date ($CCDATE_FLD) older than
  3078.        ; the View Date ($VIEW_DATE).
  3079.  
  3080.       while 1
  3081.        cgetrec
  3082.        if $errorlevel <> 0 break     ;end of catalog
  3083.  
  3084.        if $CREC_STAT = "D" continue  ;already deleted, skip it
  3085.  
  3086.          ;Note that using the IF command to compare dates is only valid when
  3087.          ; both dates are in the format YYYYMMDD, as is the case with
  3088.          ; $CCDATE_FLD and $VIEW_DATE.  You could not use $DATE and get
  3089.          ; a valid comparison, since $DATE does not use the format YYYYMMDD
  3090.          ; (though you can convert it to YYYYMMDD with a call to DATE2CDATE).
  3091.  
  3092.        if $CCDATE_FLD < $VIEW_DATE  ;older than View Date?
  3093.         ctell record                ;get the current record number for CDELREC
  3094.         CDELREC record  
  3095.        endif
  3096.       endwhile
  3097.  
  3098.       ;you'd have to call CPACK here to actually remove the deleted records
  3099.  
  3100.       cclose
  3101.  
  3102.      CEDITREC_________________________________________________________________
  3103.  
  3104.      SUMMARY
  3105.  
  3106.       CEDITREC [nRECNUMBER]
  3107.  
  3108.      DESCRIPTION
  3109.  
  3110.       Enters Tagger "Edit Mode", displaying either the current record (if
  3111.       nRECNUMBER is omitted) or record number nRECNUMBER.  The user can then
  3112.       edit the record, and press [PgUp] / [PgDn] to move to the next/previous
  3113.       records according to the current sort order (set with CSETSORT). 
  3114.       CEDITREC does not return until the user presses [Esc] to exit Edit Mode.
  3115.  
  3116.      EXAMPLE
  3117.  
  3118.  
  3119.  
  3120.  
  3121.      Intellicomm v2.01               SCRIPT.DOC                             45
  3122.      
  3123.      
  3124.  
  3125.      COPEN "NEWFILES"
  3126.      CSETSORT 1       ;Tag Status/Location, forward
  3127.      CEDITREC         ;Enter edit mode (top of catalog)
  3128.      CCLOSE
  3129.  
  3130.      CEMPTY___________________________________________________________________
  3131.  
  3132.      SUMMARY
  3133.  
  3134.       CEMPTY cCOMMAND
  3135.  
  3136.      DESCRIPTION
  3137.  
  3138.       Checks the currently open Tagger catalog (see COPEN) and executes
  3139.       cCOMMAND if it is empty (no valid file records except the header
  3140.       record).  If the catalog is NOT empty, cCOMMAND is skipped.
  3141.  
  3142.      EXAMPLE
  3143.  
  3144.       copen "NEWFILES"
  3145.       CEMPTY goto done
  3146.  
  3147.       while 1
  3148.        cgetrec
  3149.        if $errorlevel <> 0 break
  3150.        print $CNAME_FLD
  3151.       endwhile
  3152.  
  3153.      done:
  3154.       cclose
  3155.  
  3156.      CEXPORT__________________________________________________________________
  3157.  
  3158.      SUMMARY
  3159.  
  3160.       CEXPORT [sBIFNAME] [sTEXTFILE] [nEXPORTTYPE] [nNODISPLAY]
  3161.  
  3162.      DESCRIPTION
  3163.  
  3164.       Same as selecting "Tools|Export to Text File" from within the File
  3165.       Tagger.  CEXPORT exports all visible records (according to the View
  3166.       Date) in sBIFNAME format (according to the positions on the BIF
  3167.       "Bank/List" screen) to text file sTEXTFILE.  The records are written to
  3168.       sTEXTFILE in the current sort order (see CSETSORT).  If sTEXTFILE
  3169.       exists, it is appended to.  Otherwise, it is created.  If either
  3170.       sBIFNAME or sTEXTFILE is omitted, the user is prompted for the
  3171.       information, as in the File Tagger.
  3172.  
  3173.       nEXPORTTYPE is an optional number from 1 to 5, which controls the TYPE
  3174.       of files that are exported:
  3175.  
  3176.        1 = All files (Noted, Tagged and Untagged).
  3177.        2 = Tagged files only.
  3178.        3 = Noted files only.
  3179.  
  3180.  
  3181.  
  3182.  
  3183.      Intellicomm v2.01               SCRIPT.DOC                             46
  3184.      
  3185.      
  3186.  
  3187.        4 = Tagged or Noted files only.
  3188.        5 = Untagged files only.
  3189.  
  3190.       Again, if nEXPORTTYPE is omitted (or 0), the user is prompted for the
  3191.       type of files to export.
  3192.       
  3193.       nDISPLAY controls whether the export routines display any information to
  3194.       the screen.  If nNODISPLAY is 0 (zero) or is omitted, CEXPORTREC
  3195.       displays a message to the user while the export takes place.  If you
  3196.       want to hide this message, nNODISPLAY can be specified as a non-zero
  3197.       value.
  3198.  
  3199.      ERRORLEVEL
  3200.  
  3201.       0  Export successful.
  3202.       1  Catalog empty (nothing exported).
  3203.       2  sBIFNAME was omitted, CEXPORT prompted for a BIF format, and the user
  3204.          pressed [Esc].
  3205.       3  Unable to get the BIF "Bank/List" information from sBIFNAME (sBIFNAME
  3206.          doesn't exist, disk read error, BIF damaged, etc).
  3207.       4  sTEXTFILE was omitted, CEXPORT prompted for a text file to export to,
  3208.          and the user pressed [Esc].  OR nEXPORTTYPE was omitted, CEXPORT
  3209.          prompted for the type of files to export, and the user selected
  3210.          "Cancel" or pressed [Escl.
  3211.       5  Unable to open sTEXTFILE.  Most likely the filename was invalid
  3212.          (CEXPORT does not create directories), but could also be a disk write
  3213.          error or a lack of DOS file handles.  The user can remedy the latter
  3214.          by increasing FILES= in the CONFIG.SYS file.
  3215.       6  User abort ([Esc] key pressed before export complete).
  3216.       7  Disk read error.  Error reading catalog (disk read error, catalog
  3217.          damaged, etc).
  3218.       8  Disk write error.  Error writing to sTEXTFILE (disk full, various
  3219.          other disk errors).
  3220.  
  3221.      SEE ALSO
  3222.  
  3223.       CIMPORT
  3224.  
  3225.      EXAMPLE
  3226.  
  3227.       COPEN "NEWFILES"
  3228.  
  3229.       date2cdate $VIEW_DATE $DATE  ;View Date = today
  3230.       csetsort 3                   ;Sort by Filename/File Date
  3231.  
  3232.        ;export all records that were imported today (if any), sorted 
  3233.        ; by filename/file date
  3234.  
  3235.       CEXPORT PCB150 "C:\TEMP\ALLFILES.TXT" 1 ;1 = Export all files
  3236.  
  3237.        ;export any TAGGED records, sorted by Location (BBS the file is Tagged
  3238.        ; for).  The View Date is ignored on Tagged files so it's not necessary
  3239.        ; to reset the View Date.  Anything Tagged will be exported.
  3240.  
  3241.  
  3242.  
  3243.  
  3244.      Intellicomm v2.01               SCRIPT.DOC                             47
  3245.      
  3246.      
  3247.  
  3248.       csetsort 1                              ;Sort by Tag Status/Location
  3249.       CEXPORT PCB150 "C:\TEMP\TAGGED.TXT" 2   ;2 = Export Tagged files 
  3250.       cclose
  3251.  
  3252.      CFLUSH___________________________________________________________________
  3253.  
  3254.      SUMMARY
  3255.  
  3256.       CFLUSH
  3257.  
  3258.      DESCRIPTION
  3259.  
  3260.       Writes any data in the catalog buffers of the currently open catalog
  3261.       (see COPEN) to disk.  Disk input/output is 'buffered' when reading
  3262.       from/writing to Tagger catalogs (CADDREC, CGETREC, CPUTREC) meaning that
  3263.       memory buffers are used to group disk reads/writes together for more
  3264.       effecient transfers.  CFLUSH immediately writes any data in the write
  3265.       buffers to disk, and clears the contents of the buffers.  Note that
  3266.       CFLUSH is called automatically when you CCLOSE a catalog, and it
  3267.       normally will not be needed.
  3268.  
  3269.       If power outages are frequent in your area, or if you have just
  3270.       completed some critical script operations on a catalog and you want to
  3271.       ensure that the changes are written to disk immediately, you'll want to
  3272.       use CFLUSH.  Otherwise you should let the memory buffers do their work,
  3273.       and just CCLOSE the catalog (which performs a CFLUSH automatically) when
  3274.       you're finished with it.
  3275.  
  3276.      EXAMPLE
  3277.  
  3278.       copen "NEWFILES"
  3279.       ceditrec
  3280.       CFLUSH
  3281.  
  3282.      CFORMATDESC______________________________________________________________
  3283.  
  3284.      SUMMARY
  3285.  
  3286.       CFORMATDESC nWIDTH
  3287.  
  3288.      DESCRIPTION
  3289.  
  3290.       After calling CGETREC (get a Tagger catalog record), all file
  3291.       descriptions are formatted to a maximum length of 45 characters per line
  3292.       automatically.  CFORMATDESC re-formats a record's file description to a
  3293.       new line length of nWIDTH characters maximum.
  3294.  
  3295.      SEE ALSO
  3296.  
  3297.       CGETDESC, CPUTDESC
  3298.  
  3299.      EXAMPLE
  3300.       
  3301.       variable line
  3302.  
  3303.  
  3304.  
  3305.  
  3306.      Intellicomm v2.01               SCRIPT.DOC                             48
  3307.      
  3308.      
  3309.  
  3310.       copen "NEWFILES"
  3311.       while 1
  3312.        cgetrec
  3313.        if $ERRORLEVEL <> 0 break
  3314.        CFORMATDESC 65              ;65 characters per line
  3315.        cgetdesc line 1             ;get line 1 (will be 65 characters or less)
  3316.        print $CNAME_FLD "^I" line  ;^I is a TAB character
  3317.       endwhile
  3318.       cclose
  3319.  
  3320.      CGETC____________________________________________________________________
  3321.  
  3322.      SUMMARY
  3323.  
  3324.       CGETC vCHAR [nTIMEOUT]
  3325.  
  3326.      DESCRIPTION
  3327.  
  3328.       Gets a single character from the receive buffer and stores it in
  3329.       variable vCHAR.  If nTIMEOUT is specified and no characters are received
  3330.       by nTIMEOUT (specified in tenths of a second), CGETC ends and vCHAR will
  3331.       be empty.  If nTIMEOUT is omitted, CGETC waits for a character
  3332.       indefinitely.
  3333.  
  3334.       Note that CGETC doesn't deal directly with the COM port.  Only Icom's
  3335.       interrupt handler deals directly with the port, and the interrupt
  3336.       handler is driven (called) by hardware interrupts generated by the COM
  3337.       port itself.  If/when a character is received, the port sends an
  3338.       interrupt to the processor, and the processor (if it has time) turns
  3339.       control over to Icom's interrupt handler which then grabs the character
  3340.       and stores it in the receive buffer.
  3341.  
  3342.       CGETC simply checks Icom's "Receive Buffer" (size is configurable on the
  3343.       main setup/Terminal screen; it defaults to 4 Kbytes) to see if the
  3344.       interrupt handler stored any characters there.  What this means is that
  3345.       whether you call CGETC in your script or not, characters are still being
  3346.       taken from the COM port and stored in the Receive Buffer (until the
  3347.       buffer is about three quarters full, at which time the interrupt handler
  3348.       will activate Flow Control to pause the modems).  It works in the
  3349.       background, and is driven completely by the hardware itself ... and it's
  3350.       independant of both Intellicomm's terminal and scripts.  So if any
  3351.       characters are "lost", it's because your computer's processor (the
  3352.       hardware) couldn't turn control over to Icom's interrupt handler fast
  3353.       enough.  It has nothing to do with your lack of calling CGETC, or the
  3354.       speed at which CGETC is actually called.  And the only way to remedy the
  3355.       situation is either to get a faster processor, or to slow the COM port
  3356.       (baud rate) down.
  3357.  
  3358.       Further, there are certain commands you must avoid using, if you intend
  3359.       to use CGETC.  One TERMINAL command in your script can do the equivalent
  3360.       of many CGETC's and display the received character(s) on the screen
  3361.       (i.e. any characters in the Receive Buffer are "eaten" by TERMINAL
  3362.       commands, and your script, using CGETC, will never even know they were
  3363.       there). So unless you want Icom's terminal to steal characters before
  3364.  
  3365.  
  3366.  
  3367.  
  3368.      Intellicomm v2.01               SCRIPT.DOC                             49
  3369.      
  3370.      
  3371.  
  3372.       CGETC even sees them, don't call TERMINAL in and around your CGETC's. 
  3373.       This use of CGETC, for example, would get every other character received
  3374.       (at best):
  3375.  
  3376.        variable c
  3377.  
  3378.        while 1
  3379.         CGETC c 10
  3380.         printnc c
  3381.         terminal     ;TERMINAL does its own CGETC/printnc
  3382.        endwhile
  3383.  
  3384.       TERMINAL doesn't do just one CGETC, it does the equivalent of this:
  3385.  
  3386.        while $RXCNT > 0   ;$RXCNT is the number of chars in the Receive Buffer
  3387.         CGETC c
  3388.         printnc c
  3389.         inkey c           ;it also checks for and processes keystrokes
  3390.        endwhile
  3391.  
  3392.       I.e. *all* characters waiting in the receive buffer are handle by one
  3393.       single TERMINAL command.  Further, the following script commands call
  3394.       TERMINAL on their own:
  3395.  
  3396.        DELAY (use DELAYNC instead; it does not call TERMINAL)
  3397.        SEND (and its variations SENDNC/SENDNCP/SENDNP)
  3398.        SENDBIF
  3399.        WAITFOR
  3400.  
  3401.       So, you don't want to do this either (though you probably wouln't want
  3402.       to anyway):
  3403.  
  3404.        variable c
  3405.  
  3406.        while 1
  3407.         if $RXCNT > 0
  3408.          CGETC c
  3409.          sendnc c    ;SENDNC calls TERMINAL, so CGETC is useless
  3410.         endif   
  3411.        endwhile
  3412.  
  3413.      ERRORLEVEL
  3414.  
  3415.       0  Character received and stored in vCHAR.
  3416.       1  nTIMEOUT elapsed and no character was received.  Variable vCHAR will
  3417.          be empty in this case.
  3418.  
  3419.      SEE ALSO
  3420.  
  3421.       CGETS, RXBUF, TERMINAL
  3422.  
  3423.      EXAMPLE
  3424.  
  3425.       variable c
  3426.  
  3427.  
  3428.  
  3429.  
  3430.      Intellicomm v2.01               SCRIPT.DOC                             50
  3431.      
  3432.      
  3433.  
  3434.       CGETC c 100   ;wait 10 seconds maximum, then abort
  3435.       
  3436.       if $ERRORLEVEL > 0 print "Timeout."   ;one way to check...
  3437.       if c = "" print "Timeout."            ;another way to check
  3438.  
  3439.        ;If you don't use a timeout, you should make sure something is
  3440.        ; waiting in the receive buffer before you call CGETC
  3441.  
  3442.       if $RXCNT > 0 CGETC c
  3443.  
  3444.        ;variable 'c' will definitely have a character if $RXCNT is
  3445.        ; greater than (>) zero and there's no need to check $ERRORLEVEL.
  3446.  
  3447.      CGETDESC_________________________________________________________________
  3448.  
  3449.      SUMMARY
  3450.  
  3451.       CGETDESC vLINEBUF nLINENUM
  3452.  
  3453.      DESCRIPTION
  3454.  
  3455.       Gets description line number nLINENUM from the current Tagger catalog
  3456.       record (see below) and stores it in variable vLINEBUF.  Before using
  3457.       CGETDESC you must COPEN a Tagger catalog, and call CGETREC to get a
  3458.       record.  CGETDESC is only valid after a call to CGETREC.
  3459.  
  3460.       File description lines are formatted to a maximum of 45 characters per
  3461.       line by CGETREC.  Thus CGETDESC gets 45 characters of the description
  3462.       maximum, by default.  To change this line length, you can call
  3463.       CFORMATDESC after CGETREC.
  3464.  
  3465.      ERRORLEVEL
  3466.  
  3467.       0  Description line number nLINENUM was successfully loaded into
  3468.          vLINEBUF.
  3469.       1  There was no description line numbered nLINENUM (you've reached the
  3470.          end of the description, or it was empty to begin with).
  3471.  
  3472.      SEE ALSO
  3473.  
  3474.       CFORMATDESC, CGETREC 
  3475.  
  3476.      EXAMPLE
  3477.  
  3478.       This example demonstrates the entry of a file description to a BBS,
  3479.       during an upload.  Such a script could be plugged in to the "Description
  3480.       (@SCRIPTNAME)" item on the BIF "File" screen.  When this is the case,
  3481.       Intellicomm will already have the catalog open and will already have
  3482.       obtained the next tagged record (CGETREC), and will already have found
  3483.       the BBS "Enter Description" prompt.  Thus, all the script has to do is
  3484.       enter the description to the BBS.  Using the example below, you could
  3485.       make modifications (add a couple of WAITFORs or the like) to handle any
  3486.       curves a BBS developer can dream up.
  3487.  
  3488.  
  3489.  
  3490.  
  3491.      Intellicomm v2.01               SCRIPT.DOC                             51
  3492.      
  3493.      
  3494.  
  3495.       variable linenum 1
  3496.       variable linedat
  3497.  
  3498.       CGETDESC linedat 1                ;get line 1
  3499.       strblank linedat goto no_descrip  ;if blank, goto no_descrip
  3500.  
  3501.       while 1                           ;endless loop (until BREAK)
  3502.        CGETDESC linedat linenum 
  3503.        if $errorlevel = 1 break         ;no more description lines
  3504.        delay 10                         ;pause for a second (let BBS catch up)
  3505.        send linedat
  3506.        if linenum >= *[F]flmx break     ;Max Lines (BIF "File" screen)
  3507.        inc linenum                      ;INCrement (linenum = linenum + 1)
  3508.       endwhile
  3509.  
  3510.       if *[F]flmx > 1 send ""           ;If more than 1 line permitted, send
  3511.                                         ; [Enter] on a blank line
  3512.       return
  3513.  
  3514.      no_descrip:
  3515.       send "No description was available for this file."
  3516.       return
  3517.  
  3518.      CGETREC__________________________________________________________________
  3519.  
  3520.      SUMMARY
  3521.  
  3522.       CGETREC [nRECNUM]
  3523.  
  3524.      DESCRIPTION
  3525.  
  3526.       Loads either the current record (CTELL) or record number nRECNUM from
  3527.       the currently open catalog.  Please see INTRODUCTION TO DATABASE
  3528.       COMMANDS in file SCRTUTOR.DOC (included with Intellicomm) for detailed
  3529.       information.
  3530.  
  3531.      ERRORLEVEL
  3532.  
  3533.       0 = Record successfully loaded.
  3534.       1 = Unable to load record (end of catalog or nRECNUM is an invalid
  3535.           record number).
  3536.  
  3537.      SEE ALSO
  3538.  
  3539.       COPEN, CCLOSE
  3540.  
  3541.      EXAMPLE
  3542.  
  3543.       copen "NEWFILES"
  3544.  
  3545.       while 1
  3546.        CGETREC
  3547.        if $ERRORLEVEL > 0 break   ;end of catalog
  3548.       endwhile
  3549.  
  3550.  
  3551.  
  3552.  
  3553.      Intellicomm v2.01               SCRIPT.DOC                             52
  3554.      
  3555.      
  3556.  
  3557.      CGETS____________________________________________________________________
  3558.  
  3559.      SUMMARY
  3560.  
  3561.       CGETS vLINEBUF [nMAXCHARS] [sENDCHAR] [nTIMEOUT]
  3562.  
  3563.      DESCRIPTION
  3564.  
  3565.       Gets a line of input from the current COM port ($COM_PORT) and stores it
  3566.       in variable vLINEBUF.  Input is terminated when any of the following
  3567.       occurs:
  3568.  
  3569.       1. nMAXCHARS number of characters have been received.  150 characters
  3570.       (the maximum allowed) is assumed if nMAXCHARS is zero or is omitted.
  3571.  
  3572.       2. Either a Carriage Return or character sENDCHAR is received.  Note
  3573.       that neither a Carriage Return nor sENDCHAR is stored in vLINEBUF, if
  3574.       received.
  3575.  
  3576.       3. nTIMEOUT tenths of a second have elapsed (only if nTIMEOUT is
  3577.       specified).
  3578.  
  3579.       CGETS uses the equivalent of CGETC to get each character from the COM
  3580.       port.  Please see CGETC for more detailed information.
  3581.  
  3582.      ERRORLEVEL
  3583.  
  3584.       0  vLINEBUF contains one or more characters, and nTIMEOUT did not lapse.
  3585.       1  vLINEBUF is empty.  Either nTIMEOUT elapsed before a character was
  3586.          received, or nENDCHAR was the first character received.
  3587.       2  nTIMEOUT was specified, and the timeout period elapsed before a
  3588.          Carriage Return or nENDCHAR was received, or before nMAXCHARS were
  3589.          received.
  3590.  
  3591.      SEE ALSO
  3592.  
  3593.       CGETC
  3594.  
  3595.      EXAMPLE
  3596.  
  3597.      variable UserName
  3598.  
  3599.      sendnc "Please enter your name: "
  3600.      CGETS UserName 50 "^M" 60
  3601.  
  3602.      send "^M^JWelcome, " UserName "."
  3603.  
  3604.      CHAT_____________________________________________________________________
  3605.  
  3606.      SUMMARY
  3607.  
  3608.       CHAT
  3609.  
  3610.      DESCRIPTION
  3611.  
  3612.  
  3613.  
  3614.  
  3615.      Intellicomm v2.01               SCRIPT.DOC                             53
  3616.      
  3617.      
  3618.  
  3619.       Enters chat mode (same as pressing [Alt-T] from Terminal mode).  This
  3620.       command does not return until the users presses [Esc] to exit chat mode.
  3621.  
  3622.      EXAMPLE
  3623.  
  3624.       print "Entering chat mode..."
  3625.       CHAT
  3626.  
  3627.      CHECKVERSION_____________________________________________________________
  3628.  
  3629.      SUMMARY
  3630.  
  3631.       CHECKVERSION sMINIMUMVERSION
  3632.  
  3633.      DESCRIPTION
  3634.  
  3635.       CHECKVERSION is meant to be used as the first command in a script that
  3636.       is distributed to the general public.  It checks the current Intellicomm
  3637.       version number, and aborts the script with the following message if the
  3638.       version of Intellicomm executing the script is lower than
  3639.       sMINIMUMVERSION:
  3640.  
  3641.      Sorry, this script requires Intellicomm sMINIMUMVERSION or above.
  3642.  
  3643.       (where sMINIMUMVERSION is the version you specify).  sMINIMUMVERSION can
  3644.       specify the major version number only ("2") or the major version and the
  3645.       first decimal ("2.0") or the full version number ("2.00").  Only the
  3646.       portion you specify in sMINIMUMVERSION is checked.
  3647.  
  3648.       NOTE: CHECKVERSION will not be very useful until Intellicomm v1.00 is no
  3649.       longer in use, since Icom v1.00 did not support the CHECKVERSION command
  3650.       at thus if your v2.0x script is executed under Icom v1.00, Icom v1.00
  3651.       will simply ignore the command and continue to execute the script
  3652.       anyway.  Further, until new script commands/variables/concepts are
  3653.       introduced in the future, there's no need to check the version number. 
  3654.       So... keep CHECKVERSION in mind for the future, but don't bother with it
  3655.       for the time being.
  3656.  
  3657.      ERRORLEVEL
  3658.  
  3659.       None.  If sMINIMUMVERSION is higher than the current Intellicomm
  3660.       version, CHECKVERSION aborts the script.
  3661.  
  3662.      SEE ALSO
  3663.  
  3664.       $BETA_VERSION, $MAJOR_VERSION, $MINOR_VERSION
  3665.  
  3666.      EXAMPLE
  3667.  
  3668.       CHECKVERSION "2"    ;is the major version 2.xx or greater?  If not the
  3669.                           ; script aborts
  3670.  
  3671.       CHECKVERSION "2.0"  ;is v2.0x or greater?
  3672.  
  3673.  
  3674.  
  3675.  
  3676.      Intellicomm v2.01               SCRIPT.DOC                             54
  3677.      
  3678.      
  3679.  
  3680.       CHECKVERSION "2.01" ;is v2.01 or greater?
  3681.  
  3682.      CHDIR____________________________________________________________________
  3683.  
  3684.      SUMMARY
  3685.  
  3686.       CHDIR sNEWDIR
  3687.  
  3688.      DESCRIPTION
  3689.  
  3690.       Changes to a new drive and/or directory.  Similar to the DOS 'CHDIR'
  3691.       command, but this command actually changes the current drive as well
  3692.       (DOS's CHDIR simply changes the current directory of a drive but leaves
  3693.       you on the current drive).  You can specify a drive alone, a drive and
  3694.       directory, or a directory alone (to change directories on the current
  3695.       drive).  You can also specify subdirectories (CHDIR "\ICOM\LST").
  3696.  
  3697.      ERRORLEVEL
  3698.       
  3699.       0 = Successful.
  3700.       1 = Unsuccessful.
  3701.  
  3702.      SEE ALSO
  3703.  
  3704.       $CURDIR
  3705.  
  3706.      EXAMPLE
  3707.  
  3708.       variable old_dir $CUR_DIR        ;store current directory in 'old_dir'
  3709.  
  3710.       CHDIR "a:"                       ;change to drive A:
  3711.       if $ERRORLEVEL = 0               ;successful if 0
  3712.        dos ""                          ;DOS shell
  3713.        CHDIR old_dir                   ;change back to original
  3714.      drive/directory
  3715.       else
  3716.        print "Unable to change to A:"
  3717.       endif
  3718.  
  3719.      CIMPORTNEW_______________________________________________________________
  3720.  
  3721.      SUMMARY
  3722.  
  3723.       CIMPORTNEW
  3724.  
  3725.      DESCRIPTION
  3726.  
  3727.       Imports all new files lists (*.NEW) from the Intellicomm "List
  3728.       Directory" (\ICOM\LST).  This is the same as selecting "Tools | Import
  3729.       BBS Lists (*.NEW)" from the File Tagger.
  3730.  
  3731.       The lists are imported into either the Catalog Name defined on the BIF
  3732.       "Bank/List" screen, or the NEWFILES catalog if no custom catalog is
  3733.       defined.
  3734.  
  3735.  
  3736.  
  3737.  
  3738.      Intellicomm v2.01               SCRIPT.DOC                             55
  3739.      
  3740.      
  3741.  
  3742.       No catalogs need be opened (COPEN) before calling CIMPORTNEW.
  3743.  
  3744.       CIMPORTNEW is automatically executed after all automated jobs, but if
  3745.       you use stand-alone scripts exclusively to carry out your online
  3746.       sessions, you'll have to call it yourself.
  3747.  
  3748.      SEE ALSO
  3749.  
  3750.       CIMPORTTEXT
  3751.  
  3752.      EXAMPLE
  3753.  
  3754.      print "Importing *.NEW"
  3755.      CIMPORTNEW
  3756.  
  3757.      CIMPORTTEXT______________________________________________________________
  3758.  
  3759.      SUMMARY
  3760.  
  3761.       CIMPORTTEXT [sFILESPEC] [sBIFNAME]
  3762.  
  3763.      DESCRIPTION
  3764.  
  3765.       Imports the file(s) specified by sFILESPEC into the currently open
  3766.       catalog, using the filename/date/size (etc.) positions from the sBIFNAME
  3767.       (a BIF or BIF template) "Bank/List" screen.  This is the same as
  3768.       selecting "Tools | Import from Text File" from the File Tagger.
  3769.  
  3770.       If sFILESPEC and/or sBIFNAME is missing, the user is prompted for the
  3771.       information.  Wildcards (?, *) may be used in sFILESPEC to specify
  3772.       multiple files (\ICOM\CAP\*.CAP, etc).
  3773.  
  3774.       NOTE: The catalog you wish to import to must be opened first using the
  3775.       COPEN command.
  3776.  
  3777.      ERRORLEVEL
  3778.  
  3779.       0  Import successful.
  3780.       1  sFILESPEC was omitted, and the user pressed [Esc] when prompted for a
  3781.          filespec.
  3782.       2  sFILESPEC not found.
  3783.       3  sBIFNAME is an invalid BIF.
  3784.  
  3785.      SEE ALSO
  3786.  
  3787.       CIMPORTNEW
  3788.  
  3789.      EXAMPLE
  3790.  
  3791.      copen "NEWFILES"
  3792.      CIMPORTTEXT "C:\ICOM\CAP\ICOM.CAP" "PCB150"
  3793.      cclose
  3794.  
  3795.  
  3796.  
  3797.  
  3798.      Intellicomm v2.01               SCRIPT.DOC                             56
  3799.      
  3800.      
  3801.  
  3802.      CLS______________________________________________________________________
  3803.  
  3804.      SUMMARY
  3805.  
  3806.       CLS [nCOLOR]
  3807.  
  3808.      DESCRIPTION
  3809.  
  3810.       Clears the current screen WINDOW to nCOLOR if specified, or to the
  3811.       current screen color ($SCRN_COLOR) if nCOLOR is omitted.   Also moves
  3812.       the  cursor to the top left corner of the WINDOW (same as GOTOXY 1 1). 
  3813.       See the COLOR CODES appendix for color numbers to use in nCOLOR.
  3814.  
  3815.      SEE ALSO
  3816.  
  3817.       ERASELINE, SCROLL, $SCRN_COLOR, $TERM_COLOR
  3818.  
  3819.      EXAMPLE
  3820.  
  3821.       CLS $TERM_COLOR   ;default terminal color
  3822.       msgwind "You now have a clear screen"
  3823.  
  3824.      CNOTEREC_________________________________________________________________
  3825.  
  3826.      SUMMARY
  3827.  
  3828.       CNOTEREC [nRECNUM]
  3829.  
  3830.      DESCRIPTION
  3831.  
  3832.       TOGGLES the Noted status of the record specified by nRECNUM (or the
  3833.       current record if nRECNUM is 0 [zero] or omitted).  If nRECNUM is
  3834.       specified, that record number is noted/un-noted.  If nRECNUM is omitted,
  3835.       the current record (last record obtained via CGETREC) is noted/un-noted.
  3836.  
  3837.       Using CNOTEREC is similar to highlighting a given record in Tagger
  3838.       browse mode and selecting "Note".  I.e. if the record is Noted and you
  3839.       CNOTEREC it, it becomes un-noted.  If the record is un-noted and you
  3840.       CNOTEREC it, it becomes noted.
  3841.  
  3842.      ERRORLEVEL
  3843.  
  3844.       0  CNOTEREC was successful.
  3845.       1  Unable to load nRECNUM (if specified).
  3846.       2  The current record (or nRECNUM) is marked as "deleted".  Deleted
  3847.          records cannot be noted or un-noted.  This errorlevel is returned
  3848.          only to eliminate confusion: you should never "undelete" a deleted
  3849.          record to Note it.  If the record is deleted, either the user deleted
  3850.          it for a reason; or Icom has already successfully downloaded the
  3851.          file.
  3852.       3  Unable to switch the Note status (likely a disk write error).  If you
  3853.          get this error, try a CPACK to rebuild the indexes.
  3854.  
  3855.      SEE ALSO
  3856.  
  3857.  
  3858.  
  3859.  
  3860.      Intellicomm v2.01               SCRIPT.DOC                             57
  3861.      
  3862.      
  3863.  
  3864.       CTAGREC
  3865.  
  3866.      EXAMPLE 1
  3867.  
  3868.       copen "newfiles"
  3869.       cgetrec
  3870.       CNOTEREC
  3871.       cclose
  3872.  
  3873.      COPEN____________________________________________________________________
  3874.  
  3875.      SUMMARY
  3876.  
  3877.       COPEN sCATNAME
  3878.  
  3879.      DESCRIPTION
  3880.  
  3881.      Opens a File Tagger catalog for reading and/or writing (both).  sCATNAME
  3882.      is the base name of the catalog, with no drive/path or extension.  The
  3883.      catalog must exist in the Catalog Directory ($CAT_DIR).  If sCATNAME is
  3884.      not found in $CAT_DIR, it is created.
  3885.  
  3886.      Each catalog is comprised of five files:
  3887.  
  3888.       CATNAME.DBF  dBASE-compatible database holds filenames, etc.
  3889.       CATNAME.DBT  dBASE-compatible memo file holds EXTENDED file comments. 
  3890.                    The extended comment is any file description lines after
  3891.                    the primary (first) description line.
  3892.       CATNAMET.NDX dBASE-compatible index file holds the information necessary
  3893.                    to sort CATNAME.DBF by "Tag Status/Location" (as seen in
  3894.                    the File Tagger).
  3895.       CATNAMEC.NDX Same as above but holds information necessary to sort
  3896.                    CATNAME.DBF by "Catalog Date/Filesize" (as seen in the File
  3897.                    Tagger).
  3898.       CATNAMEN.NDX Another index that holds information necessary to sort
  3899.                    CATNAME.DBF by "Filename/File Date" (as seen in the File
  3900.                    Tagger).
  3901.  
  3902.      All five files are either opened or created when you call COPEN.
  3903.      No D:\PATH\ or .EXT is accepted in the sCATNAME parameter.  All File
  3904.      Tagger catalogs must reside in the Catalog Directory ($CAT_DIR).  You're
  3905.      free to keep catalogs in other directories if you like, but if you do you
  3906.      must make sure to COPY or RENAME (move from one directory to another)
  3907.      them before you call COPEN, or change the $DBF_PATH System Variable to
  3908.      point to a different directory (making sure you restore to the original
  3909.      value before your script exits).
  3910.  
  3911.      Further, you cannot open more than one catalog at a time with COPEN,
  3912.      unlike FOPEN which does allow up to 10 files to be open at once.  If a
  3913.      catalog is currently open when you call COPEN, it will be automatically
  3914.      closed before the new catalog is opened.  Note that when this happens,
  3915.      the contents of the $CXXXX_FLD variables and the file description is NOT
  3916.      cleared.  I.e. you can COPEN one catalog, get a record, then COPEN
  3917.      another catalog, CADDREC or CPUTREC (the same record) to copy record from
  3918.  
  3919.  
  3920.  
  3921.  
  3922.      Intellicomm v2.01               SCRIPT.DOC                             58
  3923.      
  3924.      
  3925.  
  3926.      one catalog to another.  Here's an example that copies all Tagged files
  3927.      from the NEWFILES catalog into another catalog called CUSTOM:
  3928.  
  3929.        variable last_rec 0
  3930.  
  3931.        while 1
  3932.         copen "NEWFILES"
  3933.         csetsort 1 0          ;set to Tag Status/Location sort; Noted files
  3934.                               ; come first, Tagged second, then Untagged
  3935.         if last_rec > 0       ;seek back to our original postion
  3936.          cgetrec last_rec     ; in NEWFILES if we have a 'last_rec'
  3937.         endif                 ; (see CTELL below)
  3938.         cgetrec               ;get the next record
  3939.         if $ERRORLEVEL <> 0 break     ;exit loop at end of catalog
  3940.         if $CTAG_FLD = "N" continue   ;skip noted records (Noted sort first)
  3941.         if $CTAG_FLD <> "T" break     ;exit loop once Tagged files are done
  3942.         ctell last_rec        ;save the current record number
  3943.         copen "CUSTOM"        ;close NEWFILES/open a cutom catalog
  3944.         caddrec               ;add the Tagged NEWFILES record to the catalog
  3945.        endwhile
  3946.  
  3947.      COPEN also automatically sets the $VIEW_DATE System Variable to the View
  3948.      Date stored in the catalog header (date of last import, or manual View
  3949.      Date set by the user).  It also sets the current sort order (CSETSORT) to
  3950.      the order set by the user the last time the catalog was viewed.  If you
  3951.      leave $VIEW_DATE alone, ONLY records that were imported on or after the
  3952.      $VIEW_DATE will be returned by CGETREC.  To view all records in the
  3953.      database, ASSIGN $VIEW_DATE "19900101" (Jan 1st, 1990... or any date
  3954.      that's older than Intellicomm).
  3955.  
  3956.      For more information on COPEN and File Tagger catalogs in general, please
  3957.      see the INTRODUCTION TO DATABASE COMMANDS section in the file
  3958.      SCRTUTOR.DOC (the script tutorial included with Intellicomm).
  3959.  
  3960.      ERRORLEVEL
  3961.  
  3962.       0  Catalog successfully opened (may have been created).
  3963.       1  Unable to open catalog.  Either the sCATNAME parameter in the COPEN
  3964.          command was an invalid filename (could not create), or the disk is
  3965.          full, or a disk write error occurred, or the existing catalog is
  3966.          damaged ... or DOS was out of file handles (increase FILES= in your
  3967.          CONFIG.SYS file).  COPEN will display a status window indicating the
  3968.          reason for the failure.
  3969.  
  3970.  
  3971.      SEE ALSO
  3972.  
  3973.       CCLOSE
  3974.  
  3975.      EXAMPLE
  3976.  
  3977.       COPEN "NEWFILES"  ;open the default 'download' catalog
  3978.       cclose
  3979.       COPEN "FILELIST"  ;open the 'upload' catalog
  3980.  
  3981.  
  3982.  
  3983.  
  3984.      Intellicomm v2.01               SCRIPT.DOC                             59
  3985.      
  3986.      
  3987.  
  3988.       cclose
  3989.        ;You can find much more meaningful examples in SCRTUTOR.DOC.
  3990.  
  3991.      COPY_____________________________________________________________________
  3992.  
  3993.      SUMMARY
  3994.  
  3995.       COPY sSOURCEFILE sTARGETFILE
  3996.  
  3997.      DESCRIPTION
  3998.  
  3999.       Copies sSOURCEFILE (the source filename) to sTARGETFILE (the destination
  4000.       filename), overwriting any file of the same destination filename.  Both
  4001.       sSOURCEFILE and sTARGETFILE can (and should) include the full
  4002.       D:\PATH\FILENAME.EXT of the files.  If the D: (drive) is omitted in
  4003.       either parameter, the current drive ($CURDRIVE) is assumed.  If the
  4004.       \PATH\ (or \PATH1\PATH2\, etc) is omitted in either paramater, the
  4005.       current directory ($CURDIR) is assumed.
  4006.  
  4007.       This command copies either binary or text files, and it maintains the
  4008.       original file date/time stamp (from the source file) on the newly
  4009.       created destination file.  This command does NOT create directories.  If
  4010.       the directory specified in the destination filename does not exist, the
  4011.       COPY command will fail ($ERRORLEVEL 3).
  4012.  
  4013.       Like the DOS 'COPY' command, if you do not specify drives/directories in
  4014.       the source or destination filenames, the current DOS drive/directory is
  4015.       assumed.  So make sure you specify directories unless you're sure of the
  4016.       current directory (use $CURDIR to get the current directory, or CHDIR to
  4017.       change directories first, if necessary).  UNLIKE the DOS 'COPY' command,
  4018.       you cannot use wildcards (*, ?) in the source or destination filenames. 
  4019.       If you wish to use wildcards, use COMMAND.COM's COPY using the script
  4020.       DOS command (e.g. DOS "copy *.* \temp").  The script equivalent is
  4021.       faster than shelling out to COMMAND.COM though, if you don't need
  4022.       wildcards.
  4023.  
  4024.      ERRORLEVEL
  4025.  
  4026.       0  Successful copy.
  4027.       1  Source and destination are the same filename.
  4028.       2  Unable to find/open the source file.
  4029.       3  Unable to create the destination file.
  4030.       4  Disk write error writing to destination (disk full usually, the
  4031.          portion of the destination that was written is deleted).
  4032.       5  Disk error reading source file, or disk error writing destination
  4033.          file (as above, the portion of the destination written is deleted).
  4034.       6  Filesize of destination (after copy) is not the same as the size of
  4035.          the source file (the destination file is deleted).
  4036.  
  4037.      SEE ALSO
  4038.  
  4039.       APPEND, APPENDS, APPENDSNC, DIRFIND, DISKFIND, DISKFREE, DOS, EXIST,
  4040.       FILESIZE, FNSTRIP, LOCATEFILE, MKDIR, NOTEXIST
  4041.  
  4042.  
  4043.  
  4044.  
  4045.      Intellicomm v2.01               SCRIPT.DOC                             60
  4046.      
  4047.      
  4048.  
  4049.      EXAMPLE
  4050.  
  4051.       variable source
  4052.       variable destination
  4053.  
  4054.       print "Enter source filename:"
  4055.       gets source 80                     ;get 80 characters max
  4056.       print "Enter destination drive, path and filename:"
  4057.       gets destination 80
  4058.       COPY source destination
  4059.       if $ERRORLEVEL = 0                 ;copy successful?
  4060.        print source " copied to " destination
  4061.       else
  4062.        print "Unable to copy file."
  4063.       endif
  4064.  
  4065.      CPACK____________________________________________________________________
  4066.  
  4067.      SUMMARY
  4068.  
  4069.       CPACK [sCATALOG_NAME]
  4070.  
  4071.      DESCRIPTION
  4072.  
  4073.       Physically removes any records marked as "deleted" from sCATALOG_NAME
  4074.       (or the currently open catalog, if sCATALOG_NAME is omitted).  Also
  4075.       removes any unattached extended file descriptions from the .DBT, and
  4076.       rebuilds the three indexes (.NDX) related to sCATALOG_NAME.
  4077.  
  4078.      ERRORLEVEL
  4079.  
  4080.      SEE ALSO
  4081.  
  4082.       CDELREC, CPURGE
  4083.  
  4084.      EXAMPLE 1
  4085.  
  4086.       copen "NEWFILES"
  4087.       cpurge           ;kill old records as configured in the Icom main setup
  4088.                        ; (optional)
  4089.       CPACK
  4090.       cclose
  4091.  
  4092.      EXAMPLE 2
  4093.  
  4094.       CPACK "NEWFILES"  ;COPEN/CCLOSE are done by CPACK.
  4095.  
  4096.      CPURGE___________________________________________________________________
  4097.  
  4098.      SUMMARY
  4099.  
  4100.       CPURGE [sCATNAME]
  4101.  
  4102.      DESCRIPTION
  4103.  
  4104.  
  4105.  
  4106.  
  4107.      Intellicomm v2.01               SCRIPT.DOC                             61
  4108.      
  4109.      
  4110.  
  4111.       Marks untagged/noted records in sCATNAME as deleted.  If sCATNAME is
  4112.       omitted, the currently open catalog is assumed.  CPURGE uses two Icom
  4113.       main setup variables to perform the purge:
  4114.  
  4115.        *prgnote  (Tagger Settings, item "Purge Noted # Days Old")
  4116.        *purge    (Tagger Settings, item "Purge Untagged # Days Old")
  4117.  
  4118.       If *prgnote is 0 (zero), no Noted records are deleted.  If *purge is 0
  4119.       (zero), no Untagged records are deleted.
  4120.  
  4121.      SEE ALSO
  4122.  
  4123.       CDELREC, CPACK
  4124.  
  4125.      EXAMPLE
  4126.  
  4127.      CPUTDESC_________________________________________________________________
  4128.  
  4129.      SUMMARY
  4130.  
  4131.       CPUTDESC sNEWTEXT nLINE
  4132.  
  4133.      DESCRIPTION
  4134.  
  4135.       Appends a new description line (if nLINE is 0), or replaces an existing
  4136.       description line (if nLINE is 1 or greater) to the currently loaded file
  4137.       description.  Before using CPUTDESC a catalog must be opened with COPEN,
  4138.       and a record must be loaded using CGETREC.
  4139.  
  4140.       CPUTDESC does not modify the description on-disk in the catalog -- it
  4141.       works only with the description memory buffer, similar to the catalog
  4142.       $CXXXX_FLD variables.  To save a description you modify with CPUTDESC,
  4143.       you must save the catalog record back (from memory) to disk with
  4144.       CPUTREC.
  4145.  
  4146.       Technically what CPUTDESC does is to first locate description line
  4147.       number nLINE in the description memory buffer (or seek to the END of the
  4148.       description of nLINE is 0).  It then deletes the existing text (in the
  4149.       memory buffer ONLY) on that line, then inserts sNEWTEXT (if any).  If
  4150.       sNEWTEXT is blank ("") then line number nLINE is simply removed.
  4151.  
  4152.       Note that you may wish to use CFORMATDESC to re-format the description
  4153.       to a different line length before using CGETDESC or CPUTDESC. 
  4154.       Descriptions are formatted to a maximum of 45 characters per line by
  4155.       CGETREC.
  4156.  
  4157.      ERRORLEVEL
  4158.  
  4159.       0  Description line number nLINE was non-zero, and the line did exist. 
  4160.          The contents of that line was either replaced with sNEWTEXT, or the
  4161.          line was removed (if sNEWTEXT was blank).
  4162.       1  There was no description line number nLINE, and nothing was done. 
  4163.          sNEWTEXT was not added.  It would be a programming error to get this
  4164.          error code, since you shouldn't be replacing existing description
  4165.  
  4166.  
  4167.  
  4168.  
  4169.      Intellicomm v2.01               SCRIPT.DOC                             62
  4170.      
  4171.      
  4172.  
  4173.          lines until you know (a) how many lines already exist, and (b) what
  4174.          the contents of those lines was.  It would make no sense to do this:
  4175.  
  4176.           CGETREC
  4177.           CPUTDESC "Replace line 4 with this text." 4
  4178.  
  4179.           Since the only time you'd want to replace line 4 is if you KNEW that
  4180.           there was a line 4, and you knew what it contained.  If you 'did' do
  4181.           something like the above, and line 4 didn't exist in the
  4182.           description, you'd get $ERRORLEVEL 1 and "Replace line 4 with this
  4183.           text."  wouldn't be added.  It would make more sense to do this:
  4184.  
  4185.           cgetrec
  4186.           cgetdesc myvariable 4   ;get line 4 (CGETDESC also sets $ERRORLEVEL)
  4187.           if $ERRORLEVEL = 0      ;did line 4 exist? (yes if $ERRORLEVEL = 0)
  4188.            if myvariable = "Some text you want to replace."
  4189.              ;NOW you can go ahead specifying line 4, since you know it
  4190.              ; exists, and you know that the line contained some text you
  4191.              ; didn't want.
  4192.             CPUTDESC "Replace line 4 with this text." 4
  4193.              ;Alternatively, if you wanted to just kill the text on line 4
  4194.              ; that you didn't want:
  4195.             CPUTDESC "" 4
  4196.             cputrec        ;write the new description to disk
  4197.            endif
  4198.           endif
  4199.  
  4200.           You'd never get $ERRORLEVEL 1 after CPUTDESC using a technique
  4201.           similar to the above, since you've already obtained line 4, you know
  4202.           what it contains, and you're replacing it.  Really the only other
  4203.           use for CPUTDESC is to *add* text to an existing description (or to
  4204.           build an entirely new description).  In either case, you needn't
  4205.           specify a line number at all:
  4206.  
  4207.           CPUTDESC "Add this to the end of the description." 0
  4208.  
  4209.           Or simply leave the 0 off:
  4210.  
  4211.           CPUTDESC "Add this to the end of the description."
  4212.  
  4213.           TIP: To replace an entire description, use CCLEARDESC (get rid of
  4214.           the existing description) then 'CPUTDESC "new data" 0' (add the new
  4215.           one).  You can use 'CPUTDESC "new data" 0' multiple times in a loop
  4216.           (or anywhere else) if necessary, to continue adding new lines of
  4217.           text.
  4218.  
  4219.      SEE ALSO
  4220.  
  4221.       CCLEARDESC, CPUTDESC, CPUTREC
  4222.  
  4223.      EXAMPLE
  4224.  
  4225.       copen "FILELIST"
  4226.       cgetrec
  4227.  
  4228.  
  4229.  
  4230.  
  4231.      Intellicomm v2.01               SCRIPT.DOC                             63
  4232.      
  4233.      
  4234.  
  4235.       cputdesc "Line added complements of CPUTDESC" 0
  4236.       cputrec
  4237.  
  4238.       Please see POSTFILE.SCR for a more meaningful example of CPUTDESC.
  4239.  
  4240.      CPUTREC__________________________________________________________________
  4241.  
  4242.      SUMMARY
  4243.  
  4244.       CPUTREC [nRECNUM]
  4245.  
  4246.      DESCRIPTION
  4247.  
  4248.       Writes the current record to disk, and updates the catalog indexes if
  4249.       necessary.  CPUTREC is to be used after COPEN/CGETREC when one or more
  4250.       of the $CXXXX_FLD variables has been modified or CPUTDESC has been used.
  4251.  
  4252.       If nRECNUM is specified, it must be a valid record number for the
  4253.       currently open catalog.  Normally you'll omit nRECNUM, which simply
  4254.       updates the last record loaded by CGETREC.
  4255.  
  4256.      ERRORLEVEL
  4257.  
  4258.       0  The record was written to disk.
  4259.       1  Error updating the record.
  4260.  
  4261.      SEE ALSO
  4262.  
  4263.       CADDREC
  4264.  
  4265.      EXAMPLE
  4266.  
  4267.       copen "NEWFILES"
  4268.       cgetrec
  4269.       date2cdate $CCDATE_FLD $DATE  ;assign today's date to the Catalog Date
  4270.       cputdesc "Add this to the file description" 0
  4271.       CPUTREC     ;updates the Catalog Date, description, and all indexes
  4272.       cclose
  4273.  
  4274.      CSAVEBMARK_______________________________________________________________
  4275.  
  4276.      SUMMARY
  4277.  
  4278.       CSAVEBMARK [nBOOKMARK_RECNUM]
  4279.  
  4280.      DESCRIPTION
  4281.  
  4282.       Saves the current record (or nBOOKMARK_RECNUM if specified) as the
  4283.       bookmark.  The next time the user views the catalog in the File Tagger,
  4284.       the bookmarked record will be automatically hilighted.
  4285.  
  4286.      SEE ALSO
  4287.  
  4288.       CSAVESORT, CSAVEVDATE
  4289.  
  4290.  
  4291.  
  4292.  
  4293.      Intellicomm v2.01               SCRIPT.DOC                             64
  4294.      
  4295.      
  4296.  
  4297.      EXAMPLE
  4298.  
  4299.      CSAVESORT________________________________________________________________
  4300.  
  4301.      SUMMARY
  4302.  
  4303.       CSAVESORT
  4304.  
  4305.      DESCRIPTION
  4306.  
  4307.       Saves the current sort order, as set by CSETSORT.  The next time the
  4308.       user views the catalog (or the next time it is COPENed) the sort order
  4309.       saved by CSAVESORT will be used.
  4310.  
  4311.      SEE ALSO
  4312.  
  4313.       CSAVEBMARK, CSETSORT, CSAVEVDATE, $CSORT_DIR, $CSORT_ORDER
  4314.  
  4315.      EXAMPLE
  4316.  
  4317.       COPEN "NEWFILES"
  4318.       CSETSORT 3 1     ;sort by Filename/Date, Reversed
  4319.       CSAVESORT
  4320.       CCLOSE
  4321.  
  4322.      CSAVEVDATE_______________________________________________________________
  4323.  
  4324.      SUMMARY
  4325.  
  4326.       CSAVEVDATE [sVIEWDATE]
  4327.  
  4328.      DESCRIPTION
  4329.  
  4330.       Saves the current $VIEW_DATE (or sVIEWDATE if specified) in the catalog
  4331.       header.  The next time the user views the catalog (or the catalog is
  4332.       COPENed) the View Date saved by CSAVEVDATE will be in effect.
  4333.  
  4334.       NOTE 1: If sVIEWDATE is used, it must be specified in dBASE date format
  4335.       YYYYMMDD (YearMonthDay).  Use DATE2CDATE to convert $DATE (today's date)
  4336.       to dBASE format.
  4337.  
  4338.       NOTE 2: CSAVEVDATE "19800101" (January 1st, 1980) will effectively
  4339.       disable the 'View Date' feature, allowing ALL records in the catalog to
  4340.       be displayed.  No records should have a Catalog Date older than 1980.
  4341.  
  4342.      SEE ALSO
  4343.  
  4344.       CSAVEBMARK, CSAVESORT, $VIEW_DATE
  4345.  
  4346.      CSEEK____________________________________________________________________
  4347.  
  4348.      SUMMARY
  4349.  
  4350.       CSEEK [nNUMRECS] [nORIGIN]
  4351.  
  4352.  
  4353.  
  4354.  
  4355.      Intellicomm v2.01               SCRIPT.DOC                             65
  4356.      
  4357.      
  4358.  
  4359.      DESCRIPTION
  4360.  
  4361.       This advanced command moves the 'record pointer' of the currently open
  4362.       catalog.  The record pointer holds the record number that CGETREC will
  4363.       load next.  nNUMRECS specifies the number of records from nORIGIN to
  4364.       seek (a positive number seeks FORWARD, a negative number seeks
  4365.       BACKWARDS), nORIGIN specifies the origin of the seek as follows:
  4366.  
  4367.       0 = From the beginning of the catalog.
  4368.       1 = From the current record.
  4369.       2 = From the end of the catalog.
  4370.       3 = Seek to an absolute record number (the record number specified by
  4371.           nNUMRECS).
  4372.  
  4373.       NOTE 1: CSEEK will confuse the daylights out of you until you read the
  4374.       section "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC.  You must
  4375.       have a good grasp of the CSETSORT / CGETREC commands before using CSEEK.
  4376.  
  4377.       NOTE 2: CSEEK will be used very infrequently, and most times you'll just
  4378.       CSETSORT then CGETREC to get catalog records (CGETREC calls CSEEK 1 0
  4379.       automatically to seek to the next record).  CSEEK is provided for
  4380.       advanced use only.
  4381.  
  4382.      ERRORLEVEL
  4383.  
  4384.       0  CSEEK was successful.
  4385.       1  CSEEK was unsuccessful (no such record).
  4386.  
  4387.      SEE ALSO
  4388.  
  4389.       CTELL
  4390.  
  4391.      EXAMPLE
  4392.  
  4393.       COPEN "NEWFILES"
  4394.  
  4395.       CSETSORT -1 0     ;unsorted (no index or View Date in effect)
  4396.       CSEEK 0 2         ;seek to the end of the catalog
  4397.  
  4398.  
  4399.      CSETSORT_________________________________________________________________
  4400.  
  4401.      SUMMARY
  4402.  
  4403.       CSETSORT [nSORTORDER] [nDIRECTION]
  4404.  
  4405.      DESCRIPTION
  4406.  
  4407.       Sets the sort order and direction for the currently open catalog as
  4408.       follows:
  4409.  
  4410.       nSORTORDER:
  4411.       -1 = Unsorted
  4412.        1 = Tag Status/Location
  4413.  
  4414.  
  4415.  
  4416.  
  4417.      Intellicomm v2.01               SCRIPT.DOC                             66
  4418.      
  4419.      
  4420.  
  4421.        2 = Catalog Date/Filesize
  4422.        3 = Filename/File Date
  4423.  
  4424.       nDIRECTION:
  4425.       0 = Forward
  4426.       1 = Reversed
  4427.  
  4428.       If nSORTORDER or nDIRECTION are 0 (or omitted), CSETSORT displays a menu
  4429.       of the available sort orders / directions, and prompts the user for
  4430.       input.
  4431.  
  4432.      SEE ALSO
  4433.  
  4434.       CSAVESORT, SCRDEMO.SCR (CSETSORT is used by SCRDEMO.SCR)
  4435.  
  4436.      EXAMPLE 1
  4437.  
  4438.       COPEN "NEWFILES"
  4439.       CSETSORT      ;prompt the user for the sort order/direction
  4440.       ...
  4441.       CCLOSE
  4442.  
  4443.      EXAMPLE 2
  4444.  
  4445.       COPEN "NEWFILES"
  4446.       CSETSORT 3 0  ;sort by Filename/File Date, Forward
  4447.  
  4448.       ...
  4449.       CCLOSE
  4450.  
  4451.      CTAGALL__________________________________________________________________
  4452.  
  4453.      SUMMARY
  4454.  
  4455.       CTAGALL
  4456.  
  4457.      DESCRIPTION
  4458.  
  4459.       BETA NOTE: Command not implemented yet.
  4460.  
  4461.      ERRORLEVEL
  4462.  
  4463.      SEE ALSO
  4464.  
  4465.      EXAMPLE
  4466.  
  4467.      CTAGREC__________________________________________________________________
  4468.  
  4469.      SUMMARY
  4470.  
  4471.       CTAGREC [nRECNUM] [nMODE] [sBIF_ID[;sBIF_ID]...]
  4472.  
  4473.      DESCRIPTION
  4474.  
  4475.  
  4476.  
  4477.  
  4478.      Intellicomm v2.01               SCRIPT.DOC                             67
  4479.      
  4480.      
  4481.  
  4482.       TOGGLES the Tag status of the record specified by nRECNUM (or the
  4483.       current record if nRECNUM is 0 [zero] or omitted).  If nRECNUM is
  4484.       specified, that record number is tagged/untagged.  If nRECNUM is
  4485.       omitted, the current record (last record obtained via CGETREC) is
  4486.       tagged/untagged.
  4487.  
  4488.       Using CTAGREC is similar to highlighting a given record in Tagger browse
  4489.       mode and selecting "Tag".  I.e. if the record is Tagged and you CTAGREC
  4490.       it, it becomes untagged.  If the record is untagged and you CTAGREC it,
  4491.       it becomes Tagged.  It works a little differently if working with the
  4492.       FILELIST (upload) catalog, however.  See below.
  4493.  
  4494.       [nMODE] and [sBIF_ID[;sBIF_ID]...] are only valid if the FILELIST
  4495.       (upload) catalog is open, and they are used to add the "Upload Pending"
  4496.       strings you see in the File Tagger after you Tag a file for uploading. 
  4497.       If sBIFID is blank ("") then all Upload Pending BIFID's are removed from
  4498.       the record, and the record is untagged.  If one or more BIFID's are
  4499.       specified (in the format "BIFID" or "BIFID1;BIFID2;BIFID3"...etc) then
  4500.       nMODE comes into play as follows:
  4501.  
  4502.        nMODE = -1  the passed BIFID(s) are removed from ULPEND (if found).
  4503.        nMODE =  0  the passed BIFID(s) replace the existing ones.
  4504.        nMODE =  1  the passed BIFID(s) are appended to the existing ULPEND.
  4505.  
  4506.       See the example for details.
  4507.  
  4508.      ERRORLEVEL
  4509.  
  4510.       0  CTAGREC was successful.
  4511.       1  Unable to load nRECNUM (if specified).
  4512.       2  The current record (or nRECNUM) is marked as "deleted".  Deleted
  4513.          records cannot be tagged/untagged.  This errorlevel is returned only
  4514.          to eliminate confusion: you should never "undelete" a deleted record
  4515.          to Tag it.  If the record is deleted, either the user deleted it for
  4516.          a reason; or Icom has already successfully downloaded the file.
  4517.       3  Unable to switch the Tag status (likely a disk write error).  If you
  4518.          get this error, try a CPACK to rebuild the indexes.
  4519.  
  4520.      SEE ALSO
  4521.  
  4522.       CNOTEREC
  4523.  
  4524.      EXAMPLE 1
  4525.  
  4526.       copen "newfiles"
  4527.       cgetrec
  4528.       CTAGREC
  4529.       cclose
  4530.  
  4531.      EXAMPLE 2
  4532.  
  4533.        ;Tagging files for upload is only useful to have Icom itself upload
  4534.        ; the files (i.e. using the PREJOB.SCR to Tag files for upload prior
  4535.        ; to an automated job that had one or more "Upload tagged files"
  4536.  
  4537.  
  4538.  
  4539.  
  4540.      Intellicomm v2.01               SCRIPT.DOC                             68
  4541.      
  4542.      
  4543.  
  4544.        ; tasks). Uploading files (handling the entire process) from a script
  4545.        ; and trying to use the FILELIST catalog would be a very complex
  4546.        ; procedure, and it is not recommended.
  4547.  
  4548.       copen "filelist"      ;open the upload catalog
  4549.       cgetrec
  4550.       CTAGREC 0 1 "JOESBBS" ;tag for uploading to joesbbs... if JOESBBS
  4551.                             ; already exists in the "Upload Pending" string,
  4552.                             ; no action is taken.  If JOESBBS doesn't exist,
  4553.                             ; it is appended (Upload Pending:ABBS;JOESBBS).
  4554.  
  4555.       CTAGREC 0 -1 "JOESBBS" ;JOESBBS is removed from the "Upload Pending"
  4556.                              ; string if it exists.  If no more BIFID's remain
  4557.                              ; in the Upload Pending string, the record is
  4558.                              ; also automatically Untagged.
  4559.       CTAGREC 0 0 "JOESBBS"  ;all other BIFID's in the Upload Pending string
  4560.                              ; (if any) are removed, and JOESBBS is added.
  4561.  
  4562.  
  4563.       CTAGREC 0 0 ""         ;all BIFID's are removed from the Upload Pending
  4564.                              ; string, none are added, and the record is
  4565.                              ; Untagged
  4566.       cclose
  4567.  
  4568.      CTELL____________________________________________________________________
  4569.  
  4570.      SUMMARY
  4571.  
  4572.       CTELL vCUR_REC
  4573.  
  4574.      DESCRIPTION
  4575.  
  4576.       Stores the record number of the currently loaded record in variable
  4577.       vCUR_REC (a user-defined variable, defined using the VARIABLE command). 
  4578.       CTELL is useful for saving your position in a catalog.  Use CTELL to get
  4579.       the current record number, then use CSEEK vCUR_REC 3 (seek to absolute
  4580.       record number) to seek back to it later.
  4581.  
  4582.       NOTE: You must use CTELL before using CDELREC (delete a catalog record),
  4583.       since you must specify a record number with CDELREC.
  4584.  
  4585.      EXAMPLE
  4586.  
  4587.       variable recnum
  4588.       copen "NEWFILES"
  4589.       CTELL recnum     ;store current position in 'recnum'
  4590.       ...              ;CGETREC and otherwise fiddle around
  4591.       cseek recnum 3   ;seek back to original position
  4592.       ...              ;do whatever needs doing
  4593.       CCLOSE
  4594.  
  4595.      SEE ALSO
  4596.  
  4597.  
  4598.  
  4599.  
  4600.      Intellicomm v2.01               SCRIPT.DOC                             69
  4601.      
  4602.      
  4603.  
  4604.      CURSORLARGE______________________________________________________________
  4605.      CURSORSMALL______________________________________________________________
  4606.  
  4607.      SUMMARY
  4608.  
  4609.       CURSORLARGE
  4610.       CURSORSMALL
  4611.  
  4612.      DESCRIPTION
  4613.  
  4614.       CURSORLARGE changes the cursor to large (half character height) while
  4615.       CURSORSMALL changes the cursor to small (underline).  If the cursor is
  4616.       hidden (CURSOROFF, etc) when either command is called, it will be re-
  4617.       displayed.  Note that the BOXGETS and GETS/GETSXY commands do not use
  4618.       the current cursor size, and they display the cursor as large/small
  4619.       according to the current Insert/Typeover status set by the user.
  4620.  
  4621.      SEE ALSO
  4622.  
  4623.       CURSORPOP, CURSORPUSH, CURSOROFF, CURSORON
  4624.  
  4625.      EXAMPLE
  4626.  
  4627.       CURSORLARGE
  4628.       pause "Press a key... "
  4629.       CURSORSMALL
  4630.  
  4631.      CURSOROFF________________________________________________________________
  4632.      CURSORON_________________________________________________________________
  4633.  
  4634.      SUMMARY
  4635.  
  4636.       CURSOROFF
  4637.       CURSORON
  4638.  
  4639.      DESCRIPTION
  4640.  
  4641.       CURSOROFF hides the screen cursor, while CURSORON re-displays a hidden
  4642.       screen cursor.
  4643.  
  4644.      SEE ALSO
  4645.  
  4646.       CURSORONOFF, CURSORPUSH, CURSORPOP
  4647.  
  4648.      EXAMPLE
  4649.  
  4650.  
  4651.      CURSOROFF
  4652.      pause "Press any key to continue..."
  4653.      CURSORON
  4654.  
  4655.      CURSORONOFF______________________________________________________________
  4656.  
  4657.      SUMMARY
  4658.  
  4659.  
  4660.  
  4661.  
  4662.      Intellicomm v2.01               SCRIPT.DOC                             70
  4663.      
  4664.      
  4665.  
  4666.       CURSORONOFF nSTATE
  4667.  
  4668.      DESCRIPTION
  4669.  
  4670.       Turns the cursor on or off, according to nSTATE.  If nSTATE is 0 (zero)
  4671.       the cursor is turned off (hidden).  If nSTATE is non-zero the cursor is
  4672.       turned on (unhidden).
  4673.  
  4674.      SEE ALSO
  4675.  
  4676.       CURSORON, CURSOROFF
  4677.  
  4678.      EXAMPLE
  4679.  
  4680.       pause "Press a key to hide the cursor..."
  4681.       CURSORONOFF 0
  4682.  
  4683.       pause "Press a key to unhide the cursor..."
  4684.       CURSORONOFF 1
  4685.  
  4686.      CURSORPOP________________________________________________________________
  4687.      CURSORPUSH_______________________________________________________________
  4688.  
  4689.      SUMMARY
  4690.  
  4691.       CURSORPOP
  4692.       CURSORPUSH [nNEWSTATUS]
  4693.  
  4694.      DESCRIPTION
  4695.  
  4696.       CURSORPUSH saves the position (screen x/y coordinate), size, and on/off
  4697.       status of the cursor, and optionally sets a new on/off status.  If
  4698.       nNEWSTATUS is omitted, the cursor status (on/off) remains unchanged
  4699.       after CURSORPUSH.  If nNEWSTATUS is specified, a value of -1 means to
  4700.       leave the cursor status as is (same as not specifying it) while a value
  4701.       of 0 (zero) means to turn the cursor off (same as CURSOROFF) while a
  4702.       value of 1 (one) means to turn the cursor on (same as CURSORON).
  4703.  
  4704.       You can call CURSORPUSH up to 16 times (if necessary, saving different
  4705.       cursor states/positions) before calling CURSORPOP.  If you call
  4706.       CURSORPUSH 17 times without a single CURPOP, you'll get a CURSORPUSH
  4707.       Stack Overflow error and your script will abort.
  4708.  
  4709.       CURSORPOP restores the cursor to the location, size and on/off status it
  4710.       had before the *last* CURSORPUSH (last in, first out).
  4711.  
  4712.      SEE ALSO
  4713.  
  4714.       CURSORON, CURSOROFF
  4715.  
  4716.      EXAMPLE
  4717.  
  4718.      vpush        ;save contents of the video screen
  4719.      CURSORPUSH   ;save cursor state
  4720.  
  4721.  
  4722.  
  4723.  
  4724.      Intellicomm v2.01               SCRIPT.DOC                             71
  4725.      
  4726.      
  4727.  
  4728.      cursoron     ;turn cursor on
  4729.      cursorlarge  ;large cursor
  4730.      cls          ;clear screen, GOTOXY 1 1   
  4731.      pause "Press a key to restore..."
  4732.      vpop
  4733.      curpop
  4734.      pause "Back to normal..."
  4735.  
  4736.  
  4737.      DATE2CDATE_______________________________________________________________
  4738.  
  4739.      SUMMARY
  4740.  
  4741.       DATE2CDATE vCDATE sDATE
  4742.  
  4743.      DESCRIPTION
  4744.  
  4745.       Converts sDATE (a date in the format returned by $DATE or $FDATE) to a
  4746.       dBASE style date (YYYYMMDD) and stores in vCDATE.
  4747.  
  4748.      SEE ALSO
  4749.  
  4750.       CDATE2DATE
  4751.  
  4752.      EXAMPLE 1
  4753.  
  4754.       CGETREC
  4755.       DATE2CDATE $CCDATE_FLD $DATE  ;assign today's date to Catalog Date
  4756.       CPUTREC
  4757.  
  4758.      EXAMPLE 2
  4759.  
  4760.       DATE2CDATE $VIEW_DATE $DATE   ;assign today's date to View Date
  4761.       CSAVEVDATE                    ;save in catalog header
  4762.  
  4763.      DEBUG____________________________________________________________________
  4764.  
  4765.      SUMMARY
  4766.  
  4767.       DEBUG nSTAT | vVARIABLE
  4768.  
  4769.      DESCRIPTION
  4770.  
  4771.       | above means 'OR'.  You can use 0, 1, 2 (nSTAT), OR a variable name
  4772.       (vVARIABLE).  The script debugger is explained in detail in
  4773.       SCRTUTOR.DOC.
  4774.  
  4775.       DEBUG 0 turns debugging off, DEBUG 1 turns step-by-step debugging on,
  4776.       DEBUG 2 turns 'animated' debugging mode on.  A variable name, if
  4777.       specified, pauses the script and displays the contents of the variable. 
  4778.       All can be very useful in finding script logic errors.
  4779.  
  4780.      EXAMPLE
  4781.  
  4782.  
  4783.  
  4784.  
  4785.      Intellicomm v2.01               SCRIPT.DOC                             72
  4786.      
  4787.      
  4788.  
  4789.       variable count
  4790.  
  4791.       DEBUG 2           ;turn 'animate' mode on... displays each script line
  4792.                         ; on the status line at the rate of two lines per
  4793.                         ; second, prior to executing the line.
  4794.       assign count 0
  4795.       while count < 10
  4796.        inc count
  4797.       endwhile
  4798.  
  4799.       DEBUG count      ;displays the contents of 'count' (would be 10)
  4800.  
  4801.       DEBUG 1          ;turn 'step-by-step' debugging on... displays each
  4802.                        ; script line on the status line, then pauses until
  4803.                        ; you press [Space] or [Enter] before executing the
  4804.                        ; line.
  4805.  
  4806.       while count < 10 ;this displays "WHILE 10 < 10" (the variable's value is
  4807.        inc count       ; displayed, rather than showing the variable name).
  4808.       endwhile
  4809.       
  4810.       DEBUG 0          ;turn debug mode off.
  4811.       return
  4812.       
  4813.      DEC______________________________________________________________________
  4814.  
  4815.      SUMMARY
  4816.  
  4817.       DEC vNUM
  4818.  
  4819.      DESCRIPTION
  4820.  
  4821.       Subtracts 1 from the contents of the specified variable vNUM.  If the
  4822.       variable contained the number 10, DEC would decrement it to 9.  If the
  4823.       variable contained 0, DEC would changes it to -1.  If the variable
  4824.       contained TEXT instead of a number, iot will contain -1 when DEC
  4825.       finishes with it (since 0 is assumed if vNUM is missing, or if it's non-
  4826.       numeric).  DEC first converts the variable to a number (text translates
  4827.       to the number 0), then subtracts 1 from that number.
  4828.  
  4829.      SEE ALSO
  4830.  
  4831.       ADD, SUB, INC
  4832.  
  4833.      EXAMPLE
  4834.       
  4835.       variable count 10  ;define variable 'count', assign 10 to it
  4836.  
  4837.       ;count from 10 down to 1
  4838.  
  4839.       while count > 0    ;while count is greater than 0, do to endwhile
  4840.        print count       ;print the contents of 'count'
  4841.        DEC count         ;count = count - 1
  4842.       endwhile
  4843.  
  4844.  
  4845.  
  4846.  
  4847.      Intellicomm v2.01               SCRIPT.DOC                             73
  4848.      
  4849.      
  4850.  
  4851.      DELAY____________________________________________________________________
  4852.      _ 
  4853.      SUMMARY
  4854.  
  4855.       DELAY nTENTHS
  4856.  
  4857.      DESCRIPTION
  4858.  
  4859.       Delays execution of the script for nTENTHS tenths of a second.  So to
  4860.       delay for one second you'd use DELAY 10, to delay for a minute you'd use
  4861.       DELAY 600, and so forth.
  4862.  
  4863.       NOTE: DELAY updates the terminal screen with incoming characters from
  4864.       the BBS while paused.  To pause and freeze the display, use DELAYNC.
  4865.  
  4866.      SEE ALSO
  4867.  
  4868.       DELAYNC, PAUSE, WAITUNTIL
  4869.  
  4870.      EXAMPLE
  4871.  
  4872.       send "D"            ;send a [D]ownload command to the BBS
  4873.       delay 10            ;pause for a second to wait for the filename prompt
  4874.       send "ICOM201A.ZIP"
  4875.       delay 50            ;wait 5 seconds for the D/L to start
  4876.       download "Z"        ;download using Zmodem
  4877.  
  4878.      DELAYNC__________________________________________________________________
  4879.  
  4880.      SUMMARY
  4881.  
  4882.       DELAYNC nTENTHS
  4883.  
  4884.      DESCRIPTION
  4885.  
  4886.       Delays execution of the script for nTENTHS tenths of a second.  So to
  4887.       delay for one second you'd use DELAYNC 10, to delay for a minute you'd
  4888.       use DELAYNC 600.
  4889.  
  4890.       NOTE: The NC in DELAYNC stands for 'N'o 'C'omm. updating.  DELAYNC does
  4891.       NOT update the terminal screen with incoming characters from the BBS
  4892.       during the delay.  To allow incoming characters to be displayed during a
  4893.       delay, use the DELAY command.  You won't actually lose any characters
  4894.       from the BBS during a DELAYNC; Icom's interrupt handler is still getting
  4895.       characters from the COM port and storing them in its internal buffer
  4896.       (which defaults to 4 kilobytes in size).  It just doesn't update the
  4897.       terminal screen with the incoming characters.
  4898.  
  4899.      SEE ALSO
  4900.  
  4901.       DELAY, PAUSE, WAITUNTIL
  4902.  
  4903.      EXAMPLE
  4904.  
  4905.  
  4906.  
  4907.  
  4908.      Intellicomm v2.01               SCRIPT.DOC                             74
  4909.      
  4910.      
  4911.  
  4912.       ;^M^J is carriage return/line feed (move to a new line)
  4913.       print "^M^JNOTE: <some important message>"
  4914.  
  4915.      DEL___________________________________________________________________
  4916.      DELETE________________________________________________________________
  4917.  
  4918.      SUMMARY
  4919.  
  4920.       DEL    sFILESPEC
  4921.       DELETE sFILESPEC
  4922.       
  4923.      DESCRIPTION
  4924.  
  4925.       Similar to the DOS 'DEL' and 'DELETE' commands, this script command
  4926.       deletes a specified filespec from the disk.  You are allowed to use
  4927.       wildcards (*, ?) in the filespec portion if necessary.  You cannot
  4928.       delete directories with the DELETE command (use RMDIR to delete
  4929.       directories).
  4930.  
  4931.       You may omit the drive and/or directory in sFILESPEC if the file(s) to
  4932.       be deleted are in the current DOS directory ($CURDIR), but if you use
  4933.       this method make sure you KNOW which directory you're in first by using 
  4934.       CHDIR.  Icom changes directories for various purposes during its course
  4935.       of operation, and you really can never be sure which directory you're in
  4936.       when your script is running, unless you check $CURDIR or use CHDIR at
  4937.       some point before the DELETE command.
  4938.  
  4939.       WARNING: Do not attempt to delete a file that is currently 'open' with
  4940.       the FOPEN command or CAPTURE command.  It can cause sharing violations
  4941.       and/or exception 13's.  You must CCLOSE (catalogs, if you COPENed one)
  4942.       FCLOSE (regular files, if you FOPENed the file) or CAPCLOSE (the capture
  4943.       file) before deleting them.
  4944.  
  4945.      ERRORLEVEL
  4946.  
  4947.       0  File(s) successfully deleted.
  4948.       1  Error deleting one or more files (file not found, or the file's "read
  4949.          only" attribute is set).  $ERRORLEVEL can be above 1 (2,3,4,etc) if
  4950.          more than one error occurs ... it is set to the number of files that
  4951.          could not be deleted.
  4952.  
  4953.      SEE ALSO
  4954.  
  4955.       DISKFIND, DOS, EXIST, LOCATEFILE, NOTEXIST, RENAME, RENUMBER, RMDIR
  4956.  
  4957.      EXAMPLE
  4958.  
  4959.       ;CAPTURE always appends (adds to the end) of existing files.  If
  4960.       ; you wish to create a new capture file, simply DELETE the existing
  4961.       ; file prior to calling CAPTURE.
  4962.       
  4963.       CAPCLOSE                     ;always make sure it's closed...
  4964.       DELETE "\ICOM\CAP\ICOM.CAP"  ;or use DELETE $CAP_NAME
  4965.       CAPTURE "\ICOM\CAP\ICOM.CAP" ;or use CAPTURE $CAP_NAME
  4966.  
  4967.  
  4968.  
  4969.  
  4970.      Intellicomm v2.01               SCRIPT.DOC                             75
  4971.      
  4972.      
  4973.  
  4974.       
  4975.      DIAL_____________________________________________________________________
  4976.  
  4977.      SUMMARY
  4978.  
  4979.       DIAL [sBBSNAME] [nEXACTMATCH]
  4980.  
  4981.      DESCRIPTION
  4982.  
  4983.       Dials one or more BIFs, or a specific telephone number, or displays the
  4984.       BBS Directory for user input.
  4985.  
  4986.       Variation 1, dialing one or more BIFs:
  4987.  
  4988.       If sBBSNAME is specified and nEXACTMATCH is omitted, DIAL switches to
  4989.       the BBS Directory (the equivalent of pressing [Alt-D] in Icom), selects
  4990.       "Find" from the BBS Directory menu, enters sBBSNAME, then selects "Find
  4991.       all/Tag all".  Any/all BIFs matching sBBSNAME are then tagged and
  4992.       dialed. If nEXACTMATCH is specified (as a non-zero number) then "Find
  4993.       all/Tag all" is NOT in effect and only one BIF is tagged: its
  4994.       description must match sBBSNAME exactly.
  4995.  
  4996.       Variation 2, dialing a specific telephone number:
  4997.  
  4998.       If sBBSNAME contains "^M" as its first character, a specific telephone
  4999.       number is dialed (similar to selecting "Manual" from the BBS Directory;
  5000.       e.g. DIAL "^M555-1234").
  5001.  
  5002.       Variation 3, manual user input:
  5003.  
  5004.       If both sBBSNAME and NEXACTMATCH are omitted, the BBS Directory is
  5005.       displayed for manual user input (the same as pressing [Alt-D]).
  5006.  
  5007.       Only when DIAL connects (or aborts due to an error) does your script
  5008.       continue running.  If multiple BBS's are tagged (when not specifying
  5009.       nEXACTMATCH or a manual number) you can check the $BIF_NAME System
  5010.       Variable when DIAL returns, to see which bulletin board you are
  5011.       connected to.
  5012.  
  5013.       NOTE: Using the DIAL or REDIAL commands cause any previously defined
  5014.       WHEN commands to be lost.  All WHENs are cleared when DIAL exits.
  5015.  
  5016.       TIP: You can use a single character as the sBBSNAME parameter if you
  5017.       like.  By placing specific characters in your BIF descriptions (@, !, #,
  5018.       etc) you could set up a system whereby different groups of BIFs could be
  5019.       dialed under different circumstances.  You could dial one set on
  5020.       weekdays by putting, say, ! in the descriptions of the BIFs you want to
  5021.       dial on weekdays, then using DIAL "!".  You could dial another set on
  5022.       weekends by placing @ in those descriptions then using DIAL "@".  The
  5023.       $DOW (Day Of Week) System Variable will tell your script what day it is. 
  5024.       You could also place multiple symbols in some BIFs (!@) to have certain
  5025.       BIFs dialed on both weekdays and weekends, etc.  The same sort of thing
  5026.       can be done using the time of day ($HOUR, $MIN, $SEC) or day of month
  5027.       ($DAY) to have various BBS's called at certain times of the day, or on
  5028.  
  5029.  
  5030.  
  5031.  
  5032.      Intellicomm v2.01               SCRIPT.DOC                             76
  5033.      
  5034.      
  5035.  
  5036.       certain days of the month.
  5037.  
  5038.       Regardless of how DIAL is used, the $ERRORLEVEL System Variable is set
  5039.       to 0 if dialing is successful and a connection is established.  At that
  5040.       point it's up to your script to perform the logon.  If you'd rather have
  5041.       Icom perform the logon (to take advantage of the BIF, and possible
  5042.       logons through the PC-Pursuit or iNet long-distance services), then you
  5043.       shouldn't use a DIAL command in your script.  Rather you should define a
  5044.       job such as this:
  5045.  
  5046.         Call <some BBS>
  5047.           CC: @MYSCRIPT
  5048.           Send message replies
  5049.           ...etc.
  5050.  
  5051.       I.e. use an automated job to perform the dialing/logon, then run your
  5052.       script via the "Custom Command" task.  Icom will take care of both the
  5053.       logon and logoff in these cases, assuming the BIF is set properly.  If
  5054.       possible, when using Custom Commands to execute scripts, you should have
  5055.       your script return to one of the BBS 'main' menus before it exits and
  5056.       returns control to Intellicomm (the Main Menu A, Main Menu B, Message
  5057.       Menu, Bank Menu, or File Menu prompt).  Icom does perform a check of the
  5058.       current BBS prompt after Custom Commands to locate its position, but if
  5059.       you leave it in an area of the BBS that it isn't familiar with (i.e. a
  5060.       DOOR or sub-menu other than one of the menus mentioned above) it may not
  5061.       be able to get back to a menu it recognizes, and thus may be forced to
  5062.       disconnect and call back, wasting online time (though your script would
  5063.       not be executed after the call-back; jobs are flagged as 'complete' when
  5064.       they finish).
  5065.  
  5066.      ERRORLEVEL
  5067.  
  5068.       0  Dial/connection successful.
  5069.       1  No connection (the user may have pressed the [Esc] key, or the number
  5070.          may have been tried to the "Max. Redials" for the BIF, and too many
  5071.          other possibilities to list... but you didn't get connected).
  5072.       2  A "Search String" was specified, but no matches were found in any of
  5073.          the BIF descriptions.  If this happens Icom also displays a status
  5074.          window stating "Text not found".
  5075.  
  5076.       The easiest way to check whether DIAL was successful is to use the
  5077.       OFFLINE command after DIAL to check the connect status.  Example:
  5078.  
  5079.       DIAL "My Favorite BBS" 1
  5080.       offline exit              ;exit the script if offline
  5081.  
  5082.      SEE ALSO
  5083.  
  5084.       REDIAL
  5085.  
  5086.      EXAMPLE
  5087.  
  5088.       DIAL "Joe's BBS"
  5089.       if $ERRORLEVEL <> 0 return  ;exit if $ERRORLEVEL is not equal to 0
  5090.  
  5091.  
  5092.  
  5093.  
  5094.      Intellicomm v2.01               SCRIPT.DOC                             77
  5095.      
  5096.      
  5097.  
  5098.       when "Name?" send "John Smith"
  5099.       when "Password?" send "mypassword"
  5100.       waitfor "Selection:" 60
  5101.       return                      ;leaves the user in Manual Terminal mode if
  5102.                                   ; online when the script ends
  5103.  
  5104.      ADVANCED EXAMPLE
  5105.  
  5106.       DIAL "BBS"         ;tags/dials ALL BIFs with 'BBS' in their descriptions
  5107.       while 1            ;enter an endless loop (until BREAK)
  5108.        switch $BIF_NAME  ;check which BIF 'DIAL' connected to
  5109.         case "JOESBBS"
  5110.          gosub handle_joes_bbs
  5111.         endcase
  5112.         case "THEBBS"
  5113.          gosub handle_the_bbs
  5114.         endcase
  5115.         ;subroutines not given... It is assumed they would perform the
  5116.         ; logon/online session/logoff then RETURN for the redial
  5117.        endswitch
  5118.        hangup
  5119.        redial         ;dial any BIFs still tagged
  5120.        offline break  ;exit loop if not connected (nothing left to dial)
  5121.       endwhile
  5122.  
  5123.      DIREXIST_________________________________________________________________
  5124.  
  5125.      SUMMARY
  5126.  
  5127.       DIREXIST sDIRECTORY_NAME cCOMMAND
  5128.  
  5129.      DESCRIPTION
  5130.  
  5131.       Executes cCOMMAND if sDIRECTORY_NAME (a \DIRECTORY\SUBDIR or
  5132.       D:\DIRECTORY\, etc) exists; skips cCOMMAND if sDIRECTORY_NAME does not
  5133.       exist.
  5134.  
  5135.      SEE ALSO
  5136.  
  5137.       EXIST, NOTEXIST, FINDFIRST, FINDNEXT
  5138.  
  5139.      EXAMPLE
  5140.  
  5141.       DIREXIST $DL_DIR goto start
  5142.       mkdir $DL_DIR
  5143.      start:
  5144.  
  5145.      DISKFIND_________________________________________________________________
  5146.  
  5147.      SUMMARY
  5148.  
  5149.       DISKFIND vFILEFOUND sFILESPEC ...
  5150.  
  5151.      DESCRIPTION
  5152.  
  5153.  
  5154.  
  5155.  
  5156.      Intellicomm v2.01               SCRIPT.DOC                             78
  5157.      
  5158.      
  5159.  
  5160.       Searches the specified disk drive for sFILESPEC in the format
  5161.       D:FILENAME.EXT.  If a file is found matching the filespec its full
  5162.       pathname (D:\PATH\FILENAME.EXT) is stored in vFILEFOUND.
  5163.  
  5164.       sFILESPEC may contain wildcards (*, ?) and the disk drive is optional. 
  5165.       If no disk drive is specified the current drive is assumed.  Directory
  5166.       names (\PATH\) should not be specified in sFILESPEC, as the purpose of
  5167.       DISKFIND is to locate a file when you DON'T know which directory the
  5168.       file is in.  Every directory on the drive is searched and thus you
  5169.       simply give DISKFIND a filename (or filespec such as "C:ICOM*.*"). 
  5170.       Directories will be ignored if specified.
  5171.  
  5172.       The search begins at the root directory of the drive and traverses
  5173.       through directories and subdirectories as they are encountered.
  5174.  
  5175.      ERRORLEVEL
  5176.  
  5177.       0  The file was found and its full pathname is stored in vFILEFOUND.
  5178.       1  The file was not found (vFILEFOUND is empty).
  5179.       2  An invalid drive was specified (vFILEFOUND is empty).
  5180.  
  5181.      SEE ALSO
  5182.  
  5183.       LOCATEFILE
  5184.  
  5185.      EXAMPLE
  5186.  
  5187.       variable findme "*.DBF"  ;define variable 'findme' assign *.DBF to it
  5188.  
  5189.       DISKFIND findme findme   ;you can store the result in the same variable
  5190.  
  5191.       if $ERRORLEVEL = 0
  5192.        print "Found a dBASE database (or Icom File Tagger catalog):"
  5193.        print findme
  5194.       else
  5195.        msgwind "*.DBF not found"
  5196.       endif
  5197.  
  5198.  
  5199.  
  5200.      DISKFREE_________________________________________________________________
  5201.  
  5202.      SUMMARY
  5203.  
  5204.       DISKFREE vBYTESFREE [sDRIVE]
  5205.  
  5206.      DESCRIPTION
  5207.  
  5208.       Places the number of free bytes available on drive sDRIVE in vBYTESFREE. 
  5209.       If sDRIVE is omitted the current drive is assumed.
  5210.  
  5211.      ERRORLEVEL
  5212.  
  5213.       None.  If sDRIVE is invalid, vBYTESFREE is set to -1 (minus one).
  5214.  
  5215.  
  5216.  
  5217.  
  5218.      Intellicomm v2.01               SCRIPT.DOC                             79
  5219.      
  5220.      
  5221.  
  5222.      EXAMPLE
  5223.  
  5224.       variable cfree
  5225.       DISKFREE cfree "C"  ;the colon (C:) is not needed
  5226.       print "Drive C: has " cfree " bytes free."
  5227.  
  5228.      DIV______________________________________________________________________
  5229.  
  5230.      SUMMARY
  5231.  
  5232.       DIV vQUOTIENT nDIVIDEND nDIVISOR
  5233.  
  5234.      DESCRIPTION
  5235.  
  5236.       Divides nDIVIDEND by nDIVISOR and stores the result (rounded; no
  5237.       remainder) in vQUOTIENT.
  5238.  
  5239.      SEE ALSO
  5240.  
  5241.       ADD, MUL, SUB
  5242.  
  5243.      EXAMPLE
  5244.  
  5245.       variable result
  5246.       ADD result 10 5   ;stores 10 divided by 5 (2) in variable 'result'
  5247.       print result
  5248.  
  5249.      DOS______________________________________________________________________
  5250.  
  5251.      SUMMARY
  5252.  
  5253.       DOS [sCOMMAND ...]
  5254.  
  5255.      DESCRIPTION
  5256.  
  5257.       Executes an external program.  If sCOMMAND is omitted a DOS shell is
  5258.       performed (the same as pressing [Alt-J]).  The DOS command calls
  5259.       COMMAND.COM to executed sCOMMAND and thus batch files (.BAT) can be
  5260.       executed, and redirection (>, >>, <) and/or pipes (|) can be used in the
  5261.       command no different than if you were sitting at the C:> prompt.
  5262.  
  5263.       NOTE: Intellicomm will swap itself out of base memory before executing
  5264.       sCOMMAND depending upon the setting of the *swpon (Swap On) System
  5265.       Variable defined by the user in the main setup:
  5266.  
  5267.        *swpon = 0   No swapping
  5268.        *swpon = 1   When not connected
  5269.        *swpon = 2   Connected or not
  5270.  
  5271.       See the System Variables section below for more information on *swpon.
  5272.  
  5273.       To force a Swap regardless of the setting of *swpon specify "SW:" as the
  5274.       first item in sCOMMAND.  To force NO swapping regardless of the setting
  5275.       of *swpon specify "NS:" as the first item in sCOMMAND.  See the example
  5276.  
  5277.  
  5278.  
  5279.  
  5280.      Intellicomm v2.01               SCRIPT.DOC                             80
  5281.      
  5282.      
  5283.  
  5284.       for details.
  5285.  
  5286.      ERRORLEVEL
  5287.  
  5288.       -3  Not enough memory to load COMMAND.COM.
  5289.       -2  No file handles to open COMMAND.COM (increase FILES= in CONFIG.SYS).
  5290.       -1  COMMAND.COM could not be located.
  5291.        0+ (Zero or greater) COMMAND.COM was located and executed.  Whether the
  5292.           DOS sCOMMAND was carried out successfully cannot be determined as
  5293.           COMMAND.COM does not return an errorlevel to indicate external
  5294.           program errors.  Use the EXEC command when you must determine the
  5295.           exit code of a program.
  5296.  
  5297.      SEE ALSO
  5298.  
  5299.       EXEC
  5300.  
  5301.      EXAMPLE
  5302.  
  5303.       DOS               ;DOS shell, swapping determined by *swpon
  5304.       DOS "SW:"         ;DOS shell, force Icom to swap out
  5305.       DOS "NS:"         ;DOS shell, force Icom NOT to swap out
  5306.  
  5307.       DOS "123.EXE"     ;COMMAND.COM seaches the PATH for 123.EXE and executes
  5308.                         ; it if found.  *swpon determines swapping.
  5309.       DOS "NS:LIST.COM" ;Execute LIST.COM, do not swap out.
  5310.  
  5311.       DOS "SW:C:\BAT\DELUXE.BAT"  ;Execute C:\BAT\DELUXE.BAT, swap out first
  5312.  
  5313.       DOS "DIR > DIRLIST.TXT"     ;Execute a 'DIR'ectory command, redirect
  5314.                                   ; output to a file called DIRLIST.TXT
  5315.  
  5316.        ;Get user input and execute the command
  5317.  
  5318.       variable command
  5319.       boxgets command "DOS Command" "Enter a DOS command to execute" 64
  5320.       dos command
  5321.  
  5322.      DOWNLOAD_________________________________________________________________
  5323.  
  5324.      SUMMARY
  5325.  
  5326.       DOWNLOAD sPROTOCOL [sFILENAME]
  5327.  
  5328.      DESCRIPTION
  5329.  
  5330.       Downloads sFILENAME (if specified) using transfer protocol sPROTOCOL. 
  5331.       sFILENAME is required by the protocols which have an asterisk following
  5332.       their name below.  sFILENAME can be specified for protocols which do not
  5333.       require a filename to be specified (Ymodem/Zmodem): if you pass a
  5334.       filename to these protocols, the first file accepted will use the
  5335.       filename you specify.  Normally you will not specify sFILENAME when
  5336.       calling Ymodem or Zmodem, since the proper filename is passed by the
  5337.       sending protocol, but it can be useful to 'force' a specific filename
  5338.  
  5339.  
  5340.  
  5341.  
  5342.      Intellicomm v2.01               SCRIPT.DOC                             81
  5343.      
  5344.      
  5345.  
  5346.       under some circumstances.
  5347.  
  5348.       sPROTOCOL is the 'hotkey' used to select the protocol from the protocol
  5349.       menu from Terminal Mode (including external protocols, if any are
  5350.       installed):
  5351.  
  5352.       "A" = ASCII*
  5353.       "R" = Relaxed Xmodem*
  5354.       "X" = Xmodem*
  5355.       "1" = Xmodem-1K*
  5356.       "K" = Xmodem-1K-G*
  5357.       "Y" = Ymodem
  5358.       "G" = Ymodem-G
  5359.       "Z" = Zmodem
  5360.  
  5361.       NOTE: Ymodem, Ymodem-G and Zmodem are 'batch' transfer protocols.  This
  5362.       means that they can download several files using a single DOWNLOAD
  5363.       command.
  5364.  
  5365.      ERRORLEVEL
  5366.  
  5367.       0  Transfer successful (if batch, all files were downloaded)
  5368.       1  User abort ([Esc] pressed)
  5369.       2  Connection lost
  5370.       3  Remote (BBS protocol) cancelled
  5371.       4  Disk read/write error
  5372.       5  Bad external protocol (if called an external and not found)
  5373.       6  Flow control error (not relevant to DOWNLOAD, only UPLOAD)
  5374.       7  Miscellaneous protocol error (too many timeouts, etc).
  5375.  
  5376.      SEE ALSO
  5377.  
  5378.       UPLOAD
  5379.  
  5380.      EXAMPLE 1
  5381.  
  5382.       variable filename
  5383.  
  5384.       assign filename "FILENAME.ZIP"  ;some filename to download
  5385.       send "D " filename              ;tell BBS to download
  5386.       waitfor "(Ctrl-X) Aborts"       ;wait for 'begin transfer' prompt
  5387.       DOWNLOAD "1" filename           ;Download FILENAME.ZIP using Xmodem-1K
  5388.  
  5389.      EXAMPLE 2
  5390.  
  5391.       send "D FILE1.ZIP FILE2.ZIP FILE3.ZIP Z" ;PCBoard (and others) Download
  5392.                                                ; several files using Zmodem
  5393.       waitfor "(Ctrl-X) Aborts"
  5394.       DOWNLOAD "Z"                    ;Download one or more files using Zmodem
  5395.  
  5396.      EDIT_____________________________________________________________________
  5397.  
  5398.      SUMMARY
  5399.  
  5400.  
  5401.  
  5402.  
  5403.      Intellicomm v2.01               SCRIPT.DOC                             82
  5404.      
  5405.      
  5406.  
  5407.       EDIT [sFILENAME] [nLINENUM]
  5408.  
  5409.      DESCRIPTION
  5410.  
  5411.       Enters Icom's internal Text Editor, or the external editor defined by
  5412.       the user (main setup/Filenames and Paths screen, main setup variable
  5413.       *editor).  sFILENAME is an optional [D:][\PATH\]FILENAME[.EXT] to load
  5414.       (a filename with optional drive, path and extension) to load.  nLINENUM
  5415.       is only valid when *editor is blank (no external editor), and it
  5416.       specifies an optional line number to position the cursor to after
  5417.       loading sFILENAME.
  5418.  
  5419.       NOTE: If you want to ensure use of Icom's internal Text Editor, simply
  5420.       save the *editor main setup variable, clear it, then call EDIT. 
  5421.       Example:
  5422.  
  5423.       variable filename $SCRIPT_DIR "SCRDEMO.SCR"
  5424.       variable oldeditor *editor  ;save external editor (if any)
  5425.  
  5426.       assign *editor ""           ;clear external editor
  5427.       EDIT filename 100           ;edit C:\ICOM\SCR\SCRDEMO.SCR, position to
  5428.                                   ; line 100
  5429.       assign *editor oldeditor    ;restore original external editor
  5430.  
  5431.       This should only be done when you must seek to a specific line number in
  5432.       a file.  You should otherwise let the user edit files in his preferred
  5433.       external text editor.
  5434.  
  5435.      SEE ALSO
  5436.  
  5437.       LIST
  5438.  
  5439.      EXAMPLE
  5440.  
  5441.       variable filename $HOME_DIR "POSTMAIL.BAT"
  5442.       
  5443.       pause "Press a key to edit POSTMAIL.BAT..."
  5444.       edit filename
  5445.  
  5446.      ERASELINE________________________________________________________________
  5447.  
  5448.      SUMMARY
  5449.  
  5450.       ERASELINE nLINE [nCOLOR]
  5451.  
  5452.      DESCRIPTION
  5453.  
  5454.       Clears screen line nLINE changing the line to nCOLOR.  If nCOLOR is
  5455.       omitted $SCRN_COLOR is assumed.  nLINE can be any number from 1 (top
  5456.       line) to $SCRN_HEIGHT (the bottom screen line).  On EGA/VGA displays,
  5457.       $SCRN_HEIGHT can be 25, 42, or 50.  On other displays the screen height
  5458.       is limited to 25 lines.  Note that the status line is normally on the
  5459.       last line of the screen ($SCRN_HEIGHT) and CAN be overwritten by
  5460.       ERASELINE if desired.
  5461.  
  5462.  
  5463.  
  5464.  
  5465.      Intellicomm v2.01               SCRIPT.DOC                             83
  5466.      
  5467.      
  5468.  
  5469.       ERASELINE does not move the screen cursor.  Use 'GOTOXY 1 nLINE' (where
  5470.       nLINE is the line specified in ERASELINE) if you wish to move the cursor
  5471.       to the beginning of the blank line.
  5472.  
  5473.      SEE ALSO
  5474.  
  5475.       CLS, SCROLL, VPUSH, VPOP, $SCRN_COLOR, $SCRN_HEIGHT
  5476.  
  5477.      EXAMPLE
  5478.  
  5479.       ERASELINE 1 $TERM_COLOR   ;clear first line on screen to $TERM_COLOR
  5480.       printraw -1 1 $TERM_COLOR "Centered Title on line 1"  ;-1 centers line
  5481.  
  5482.       ERASELINE 2               ;clear line 2 to the current screen color
  5483.  
  5484.      EXEC_____________________________________________________________________
  5485.  
  5486.      SUMMARY
  5487.  
  5488.       EXEC [SW:|NS:][D:\PATH\]FNAME[.EXT] [PARM ...] [>redirect | >>redirect]
  5489.  
  5490.       (Sorry!  It looks terribly complicated, but it isn't as bad as you
  5491.       think.)
  5492.  
  5493.      DESCRIPTION
  5494.  
  5495.       EXEC executes file FNAME, passing any specified parameters to it, then
  5496.       returns to the script (continuing at the next script line, if any). 
  5497.       FNAME is the external program to execute, and can include a D:\PATH\ (or
  5498.       just a \PATH\) if the program to execute is not on the DOS PATH.  You
  5499.       may include an extension as well, but it must be either .COM or .EXE. 
  5500.       .BAT files are not supported by EXEC (use the DOS command to execute DOS
  5501.       commands such as 'DIR', etc., or batch files).  You may precede FNAME
  5502.       with SW: (Swap) to force Icom to swap itself out of memory (to XMS/EMS
  5503.       if available, or to disk if not) leaving the external program with lots
  5504.       of free memory to work with.  Or you can precede FNAME with NS: (No
  5505.       Swap) to force Icom to stay in memory.  The advantage of the former is
  5506.       that you can run very large external programs, since Icom will free up
  5507.       all the memory it was using, minus just about 200 bytes of code (which
  5508.       it uses to swap itself back in after the program finishes).  The
  5509.       advantage of the latter is that it's faster, since no swapping takes
  5510.       place.  You can try NS: to avoid a swap first if you like.  If you get a
  5511.       "Not enough memory" error trying to run the external program, precede
  5512.       the command with SW: to force a swap.
  5513.  
  5514.       If the executed program displays output to STDOUT (DOS standard output
  5515.       device, as opposed to direct screen writes which most non-command line
  5516.       utilities use), you can have the output redirected to a file or other
  5517.       device such as PRN in the usual manner by following the command with
  5518.       either one or two 'greater than' (>) signs, followed by the name of the
  5519.       file or device you want to redirect TO.  Examples:
  5520.  
  5521.         EXEC "UTIL.EXE /parm1 /parm2 > OUTPUT.FIL"
  5522.         EXEC "C:\UTIL\UTIL2.COM *.* /parm1 >>\TEMP\OUTPUT.FIL"
  5523.  
  5524.  
  5525.  
  5526.  
  5527.      Intellicomm v2.01               SCRIPT.DOC                             84
  5528.      
  5529.      
  5530.  
  5531.       The first example redirects output from UTIL.EXE into a file (in the
  5532.       current directory; whatever it happened to be) called OUTPUT.FIL.  You
  5533.       could then LIST "OUTPUT.FIL" and view the results, etc.  Since only one
  5534.       '>' was specified, if OUTPUT.FIL existed in the current directory, it
  5535.       would be overwritten with the new output.
  5536.  
  5537.       The second example redirects output from C:\UTIL\UTIL2.COM into a file
  5538.       called \TEMP\OUTPUT.FIL.  Since two '>>' greater thans were specified,
  5539.       output would be appended (added to the end of) \TEMP\OUTPUT.FIL if it
  5540.       already existed.
  5541.  
  5542.       If you specify a device name to redirect to, do NOT follow the device
  5543.       name with a colon.  For example use '> PRN' and not '> PRN:'.  Note that
  5544.       these are the only two forms of redirection the EXEC command supports. 
  5545.       It does not support pipes (|) or input redirection (<).  You must use
  5546.       the DOS command for those.
  5547.  
  5548.       When to use EXEC vs. using the DOS command?  EXEC is designed to run
  5549.       only .COM or .EXE programs and it does NOT invoke a copy of the command
  5550.       processor (COMMAND.COM usually) to execute the specified program.  This
  5551.       is an important point when you must check the error return code from a
  5552.       program such as a virus checker or the like, since COMMAND.COM (which is
  5553.       what the 'DOS' command uses to run external programs/commands) does
  5554.       *not* return the errorlevel of the program it executes.  The advantage
  5555.       of the 'DOS' command is that you can run .BAT files, and can execute
  5556.       internal DOS commands such as COPY, DEL, MKDIR, RMDIR (though using the
  5557.       script equivalents of these commands is faster).  The disadvantage of
  5558.       using the DOS command is that you cannot check the error return code (if
  5559.       any) of the program you execute.  With the EXEC command, you *can* check
  5560.       the error code returned by the program (see below) but you cannot
  5561.       execute .BAT files or internal DOS commands which require COMMAND.COM.
  5562.  
  5563.      ERRORLEVEL
  5564.  
  5565.       If the program is successfully executed, $ERRORLEVEL is set to the
  5566.       return code of the program (or to a negative value if the program could
  5567.       not be executed).  This is similar to the 'ERRORLEVEL' variable you can
  5568.       test from a batch (.BAT) file after executing a program.
  5569.  
  5570.        1+   Any value above zero is the return code of the program that was
  5571.             executed.  Such a value will only be useful if the program's
  5572.             documentation specifically outlines the MEANING of error return
  5573.             codes.  Some programs do not return a value, and in those cases
  5574.             it's useless to test for an $ERRORLEVEL above zero.
  5575.        0    Program successfully loaded and executed.  Again, unless a
  5576.             program's documentation specifically states that it sets the DOS
  5577.             errorlevel to zero on successful execution, you should not assume
  5578.             that you'll get a zero return code on successful execution.  Some
  5579.             programs just leave errorlevel alone ... in which case it could be
  5580.             set to any (zero or positive) value when the program finishes. 
  5581.             You're free to always check for a NEGATIVE $ERRORLEVEL after an
  5582.             EXEC (see below), but only check for zero or greater if you know
  5583.             the program you just EXECed returns an errorlevel.
  5584.       -1    No such file or directory (program not found; remember to specify
  5585.  
  5586.  
  5587.  
  5588.  
  5589.      Intellicomm v2.01               SCRIPT.DOC                             85
  5590.      
  5591.      
  5592.  
  5593.             the full D:\PATH\ to the file if it isn't in a directory on your
  5594.             DOS PATH).  Programs never return this errorlevel.  It is set by
  5595.             the EXEC command.
  5596.       -2    Too many open files (no file handles).  Increase the FILES= in
  5597.             your CONFIG.SYS file, then reboot to remedy the situation. 
  5598.             Programs never return this errorlevel.  It is set by the EXEC
  5599.             command.
  5600.       -3    Not enough memory to execute the program.  You can remedy this one
  5601.             by preceding the command with "SW:" to have Icom swap itself out
  5602.             of memory before executing the external program.  Programs never
  5603.             return this errorlevel.  It is set by the EXEC command.
  5604.  
  5605.      SEE ALSO
  5606.  
  5607.       DOS
  5608.  
  5609.      EXAMPLE
  5610.  
  5611.       EXEC "SW:C:\UTIL\BIGPROG.EXE /1stparm /2ndparm"
  5612.  
  5613.       if $ERRORLEVEL < 0      ;less than zero?
  5614.        print "Unable to execute BIGPROG.EXE, errorcode: " $ERRORLEVEL
  5615.       else
  5616.        print "BIGPROG.EXE returned errorlevel: " $ERRORLEVEL 
  5617.       endif
  5618.  
  5619.      EXIST____________________________________________________________________
  5620.  
  5621.      SUMMARY
  5622.  
  5623.       EXIST sFILESPEC cCOMMAND
  5624.  
  5625.      DESCRIPTION
  5626.  
  5627.       If sFILESPEC exists, cCOMMAND is executed.  If sFILESPEC doesn't exist,
  5628.       cCOMMAND is skipped.
  5629.  
  5630.       sFILESPEC is a file specification (wildcards * and ? are accepted)
  5631.       including an optional drive and path (D:\PATH\*.BAT for example).  If
  5632.       you omit the drive (D:) the current drive ($CURDRIVE) is assumed.  If
  5633.       both the drive and path are omitted, the current path is assumed
  5634.       ($CURDIR).
  5635.  
  5636.      ERRORLEVEL
  5637.  
  5638.       No errorlevel is necessary.  Use cCOMMAND.
  5639.  
  5640.      SEE ALSO
  5641.  
  5642.       DISKFIND, FINDFIRST, FINDNEXT, NOTEXIST
  5643.  
  5644.      EXAMPLE
  5645.  
  5646.       variable filename $HOME_DIR "POSTDOWN.BAT"
  5647.  
  5648.  
  5649.  
  5650.  
  5651.      Intellicomm v2.01               SCRIPT.DOC                             86
  5652.      
  5653.      
  5654.  
  5655.       exist filename edit filename  ;edit POSTDOWN.BAT if it exists
  5656.  
  5657.      EXIT_____________________________________________________________________
  5658.  
  5659.      SUMMARY
  5660.  
  5661.       EXIT [nERRORCODE]
  5662.  
  5663.      DESCRIPTION
  5664.  
  5665.       Exits the script processor.  Use EXIT if you have chained to another
  5666.       script (using the SCRIPT command) and you don't wish to return to the
  5667.       original script.
  5668.  
  5669.       nERRORCODE is only valid if Intellicomm is in fully automated mode (i.e.
  5670.       the script must have been called via a job Custom Command/Run Script
  5671.       task).  If nERRORCODE is 0 (zero) no action is taken by Intellicomm.  If
  5672.       nERRORCODE is 1 or greater, Intellicomm cancels the rest of the job
  5673.       tasks for the CURRENT BBS, and removes the current BBS from the dialing
  5674.       queue.  If nERRORCODE is less than zero (-1, -2, etc) Intellicomm aborts
  5675.       all automated jobs.
  5676.  
  5677.       NOTE: If a non-zero nERRORCODE follows the EXIT command, Intellicomm
  5678.       prints a message to the screen stating "Script aborted by EXIT code:
  5679.       nERRORCODE".
  5680.  
  5681.      SEE ALSO
  5682.  
  5683.       SCRIPT, RETURN, SCRTUTOR.DOC section "WHAT HAPPENS WHEN A SCRIPT ENDS?"
  5684.  
  5685.      EXAMPLE
  5686.  
  5687.       waitfor "Some text" 120 major_error
  5688.       ...
  5689.       return
  5690.  
  5691.      major_error:
  5692.       EXIT 1      ;abort all scripts, and the automated job for current BBS as
  5693.                   ; well
  5694.  
  5695.      FCLOSE___________________________________________________________________
  5696.  
  5697.      SUMMARY
  5698.  
  5699.       FCLOSE vHANDLE
  5700.  
  5701.      DESCRIPTION
  5702.  
  5703.       Closes the file vHANDLE.  vHANDLE must be a valid file handle stored by
  5704.       the FOPEN command.
  5705.  
  5706.      ERRORLEVEL
  5707.  
  5708.       0  FCLOSE successful
  5709.  
  5710.  
  5711.  
  5712.  
  5713.      Intellicomm v2.01               SCRIPT.DOC                             87
  5714.      
  5715.      
  5716.  
  5717.       1  FCLOSE unsuccessful (disk error; most likely the disk is full).
  5718.  
  5719.      SEE ALSO
  5720.  
  5721.       FOPEN
  5722.  
  5723.      EXAMPLE
  5724.  
  5725.      FFLUSH___________________________________________________________________
  5726.  
  5727.      SUMMARY
  5728.  
  5729.       FFLUSH vHANDLE
  5730.  
  5731.      DESCRIPTION
  5732.  
  5733.       Immediately writes any data in vHANDLE's file output buffer to disk.
  5734.       vHANDLE is the variable you used when you FOPENed the file.
  5735.  
  5736.       FPUTS and FPUTC do not write data to disk immediately.  They buffer data
  5737.       until an effecient disk write can be made (or until FCLOSE is called). 
  5738.       If you have something very important to write to disk, use FFLUSH after
  5739.       FPUTS / FPUTC, etc., to immediately write the data to disk.  If the
  5740.       computer locks up, or the power goes out while data is waiting to be
  5741.       written to disk in the file output buffer, the data will be lost.
  5742.  
  5743.       NOTE 1: FFLUSH is automatically called when you FCLOSE a file.
  5744.  
  5745.       NOTE 2: Disk cache programs (such as DOS's SMARTDrive) also buffer data
  5746.       in memory, for more effecient disk writes.  FFLUSH cannot force a disk
  5747.       cache to write data to disk, so if a disk cache with a write-behind
  5748.       buffer is operating, FFLUSH has no effect.  This is not a limitation of
  5749.       Icom's script language, or even a limitation of DOS: it's a limitation
  5750.       of using disk cache write-behind buffers.  They write data on their own
  5751.       time, and I have yet to figure out how to force any disk cache to write
  5752.       its data to disk, if indeed there is any way (aside from executing non-
  5753.       standard and slow commands at the DOS prompt).  If anyone knows the
  5754.       secret, feel free to pass it along, as I'd like to have FFLUSH force
  5755.       disk cache programs to write to disk as well.
  5756.  
  5757.      ERRORLEVEL
  5758.  
  5759.       0  Disk write (FLUSH) was successful.
  5760.       1  Disk write unsuccessful (the disk is likely full).
  5761.  
  5762.      SEE ALSO
  5763.  
  5764.       FOPEN, FCLOSE
  5765.  
  5766.      EXAMPLE
  5767.  
  5768.      FGETC____________________________________________________________________
  5769.  
  5770.      SUMMARY
  5771.  
  5772.  
  5773.  
  5774.  
  5775.      Intellicomm v2.01               SCRIPT.DOC                             88
  5776.      
  5777.      
  5778.  
  5779.       FGETC vBUFFER vHANDLE
  5780.  
  5781.      DESCRIPTION
  5782.  
  5783.       Gets a single character from file vHANDLE (a valid file handle variable
  5784.       as stored by FOPEN) and stores the character in variable vBUFFER.  Also
  5785.       increments the file pointer by one character (multiple calls to FGETC go
  5786.       through a file character by character).
  5787.  
  5788.      ERRORLEVEL
  5789.  
  5790.       0  FGETC successful (a character was stored in vBUFFER).
  5791.       1  End of file (vBUFFER contains -1).
  5792.  
  5793.      SEE ALSO
  5794.  
  5795.       FGETS
  5796.  
  5797.      EXAMPLE
  5798.  
  5799.       variable fh
  5800.       variable buf
  5801.  
  5802.       fopen fh "TEST.DAT" "r"   ;open TEST.DAT for reading
  5803.       while 1                   ;loop until BREAK
  5804.        FGETC buf fh
  5805.        if $errorlevel = 1 break ;end of file
  5806.        printnc buf
  5807.       endwhile
  5808.       fclose fh
  5809.  
  5810.      FGETS____________________________________________________________________
  5811.  
  5812.      SUMMARY
  5813.  
  5814.       FGETS vBUFFER vHANDLE
  5815.  
  5816.      DESCRIPTION
  5817.  
  5818.       Gets a line of characters from file vHANDLE (a valid file handle
  5819.       variable as stored by FOPEN) and stores the characters in variable
  5820.       vBUFFER.  Also increments the file pointer by the number of characters
  5821.       read (multiple calls to FGETS go through a file line by line).
  5822.  
  5823.       FGETS stops reading when a line feed character is encountered, 256
  5824.       characters (the maximum number of characters that can be stored in a
  5825.       script variable) have been read, or the end of the file is encountered. 
  5826.       In text files, carriage return / line feed pairs end each line.  FPUTS
  5827.       also writes a carriage return / line feed after the line of data
  5828.       written.
  5829.  
  5830.       NOTE: The carriage return / line feed pair at the end of each line are
  5831.       stripped by FGETS, since you will rarely want them.
  5832.  
  5833.  
  5834.  
  5835.  
  5836.      Intellicomm v2.01               SCRIPT.DOC                             89
  5837.      
  5838.      
  5839.  
  5840.      ERRORLEVEL
  5841.  
  5842.       0  FGETS successful (characters were stored in vBUFFER).
  5843.       1  End of file (vBUFFER is empty).  It's possible for vBUFFER to be
  5844.          empty after FGETS, but to not have an end of file condition
  5845.          ($ERRORLEVEL 1).  Blank lines in text files will result in an empty
  5846.          vBUFFER, but $ERRORLEVEL will *not* be set to 1 until the end of the
  5847.          file is reached.
  5848.  
  5849.      SEE ALSO
  5850.  
  5851.       FGETC
  5852.  
  5853.      EXAMPLE
  5854.  
  5855.       variable fh
  5856.       variable buf
  5857.  
  5858.       fopen fh "TEST.DAT" "r"   ;open TEST.DAT for reading
  5859.       while 1                   ;loop until BREAK
  5860.        FGETS buf fh
  5861.        if $errorlevel = 1 break ;end of file
  5862.        printnc buf
  5863.       endwhile
  5864.       fclose fh
  5865.  
  5866.      FILEMAN__________________________________________________________________
  5867.  
  5868.      SUMMARY
  5869.  
  5870.       FILEMAN [sDRIVEDIR] [sFILESPEC]
  5871.  
  5872.      DESCRIPTION
  5873.  
  5874.  
  5875.       Enters Icom's internal File Manager (same as pressing [Alt-F] from most
  5876.       places in Intellicomm).  sDRIVEDIR is an optional drive and directory
  5877.       (D:\PATH) to display.  If omitted, $CUR_DIR is assumed.  sFILESPEC is an
  5878.       optional filespec to display (wildcards ? and * are accepted).  If
  5879.       omitted, *.* is assumed.
  5880.  
  5881.      EXAMPLE
  5882.  
  5883.       FILEMAN $HOME_DIR "*.*"  ;display all files in the \ICOM directory
  5884.  
  5885.      FILESIZE_________________________________________________________________
  5886.  
  5887.      SUMMARY
  5888.  
  5889.       FILESIZE vBUFFER [sFILENAME]
  5890.  
  5891.      DESCRIPTION
  5892.  
  5893.       Stores the size (in bytes) of file sFILENAME in variable vBUFFER.  If
  5894.  
  5895.  
  5896.  
  5897.  
  5898.      Intellicomm v2.01               SCRIPT.DOC                             90
  5899.      
  5900.      
  5901.  
  5902.       sFILESPEC is omitted, the last file found with EXIST, FINDFIRST, or
  5903.       FINDNEXT is assumed.  sFILENAME can be a full D:\PATH\FILENAME.EXT
  5904.       (drive, path, filename, extension).  If you omit either the drive or the
  5905.       path, the current drive/directory is assumed.
  5906.  
  5907.      ERRORLEVEL
  5908.  
  5909.       There's no need to check $ERRORLEVEL after FILESIZE.  If the file
  5910.       doesn't exist, vBUFFER will contain -1 (minus one).
  5911.  
  5912.      SEE ALSO
  5913.  
  5914.       FINDFIRST, FINDNEXT, $FSIZE
  5915.  
  5916.      FINDFIRST________________________________________________________________
  5917.  
  5918.      SUMMARY
  5919.  
  5920.       FINDFIRST vBUFFER sFILESPEC [nATTRIBUTES]
  5921.  
  5922.      DESCRIPTION
  5923.  
  5924.       FINDFIRST is used to check for the existence of files (including hidden
  5925.       files and system files), directories, and/or disk labels.
  5926.  
  5927.       vBUFFER is a variable where FINDFIRST will store the name of the first
  5928.       matching file or directory name.
  5929.  
  5930.       sFILESPEC is the file specification to search for (wildcards ? and * are
  5931.       accepted), and it may contain an optional drive and path (D:\PATH). 
  5932.       Examples: "C:\ICOM\*.*", "\ICOM\SCR\POST????.SCR", etc).  If the drive
  5933.       is omitted, the current drive is assumed ($CUR_DRIVE).  If the path is
  5934.       omitted the current directory is assumed.  The filename portion MUST be
  5935.       specified.  *.* is not assumed if you specify a D:\PATH but omit a
  5936.       filespec.
  5937.       nATTRIBUTES allows you to specify file attributes that the file much
  5938.       match in order to be found by FINDFIRST.  If nATTRIBUTES is omitted, 0
  5939.       (normal and read only files) is assumed.  To specify nATTRIBUTES, select
  5940.       one or more attributes from the list below:
  5941.  
  5942.        0   Normal and read only files
  5943.        2   Hidden files
  5944.        4   System files
  5945.        8   Disk volume label
  5946.        16  Subdirectories
  5947.  
  5948.       ...and ADD the numbers up.  For example, to find normal files, hidden
  5949.       files, and subdirectories, add 0 (not necessary really; 0 is useless
  5950.       when adding), 2 (Hidden files) and 16 (Subdirectories) together (0 + 2 +
  5951.       16 = 18) and specify 18 as the nATTRIBUTES parameter.
  5952.  
  5953.       NOTE: If FINDFIRST locates a file, directory or volume label, it stores
  5954.       the FILENAME.EXT in vBUFFER, and also sets the $FXXXX variables listed
  5955.       in the "SEE ALSO" section below.  The $FXXXX variables allow you to
  5956.  
  5957.  
  5958.  
  5959.  
  5960.      Intellicomm v2.01               SCRIPT.DOC                             91
  5961.      
  5962.      
  5963.  
  5964.       check the date, time, and attributes of the item that FINDFIRST located.
  5965.  
  5966.      ERRORLEVEL
  5967.  
  5968.       0  FINDFIRST successful (a matching item was found and its name has been
  5969.          stored in vBUFFER).
  5970.       1  FINDFIRST unsuccessful (nothing found matching sFILESPEC with the
  5971.          specified nATTRIBUTES).
  5972.  
  5973.      SEE ALSO
  5974.  
  5975.       EXIST, FINDNEXT, NOTEXIST, $FARCH, $FDATE, $FDAY, $FHIDDEN, $FHOUR,
  5976.       $FMIN, $FMONTH, $FRDONLY, $FSEC, $FSIZE, $FSUBDIR, $FSYSTEM, $FTIME,
  5977.       $FVOLID, $FYEAR
  5978.  
  5979.      EXAMPLE
  5980.  
  5981.        ;simulates a regular 'DIR' command from DOS, but shows Hidden and
  5982.        ; System files/subdirectories as well
  5983.  
  5984.       variable buf
  5985.  
  5986.       FINDFIRST buf "C:\*.*" 8   ;get the disk volume label (always in root
  5987.                                  ; directory)
  5988.       print "The volume in drive C: is " buf
  5989.       print
  5990.  
  5991.       FINDFIRST buf "C:\*.*" 22  ;all attributes except volume label
  5992.  
  5993.       while $ERRORLEVEL = 0      ;end loop when no more files
  5994.        strpad buf " " 15         ;pad with spaces to a length of 15
  5995.        printnc buf
  5996.        if $FSUBDIR = "+"         ;is it a subdirectory?
  5997.         printnc "<DIR>          "
  5998.        else
  5999.         assign buf $FSIZE        ;get the filesize
  6000.         strpadl buf " " 15       ;pad left side with spaces to 15 chars
  6001.         printnc buf
  6002.        endif
  6003.        printnc "  " $FDATE
  6004.        print "  " $FTIME
  6005.        findnext buf              ;also sets $ERRORLEVEL = 1 if no more files
  6006.       endwhile
  6007.  
  6008.      FINDNEXT_________________________________________________________________
  6009.  
  6010.      SUMMARY
  6011.  
  6012.       FINDNEXT vBUFFER
  6013.  
  6014.      DESCRIPTION
  6015.  
  6016.       Finds the next matching file after using FINDFIRST, and (if any more
  6017.       files exist) stores the name of the item in variable vBUFFER.  FINDNEXT
  6018.  
  6019.  
  6020.  
  6021.  
  6022.      Intellicomm v2.01               SCRIPT.DOC                             92
  6023.      
  6024.      
  6025.  
  6026.       is only of use when wildcards (* or ?) were used in the original
  6027.       FINDFIRST 'sFILESPEC' parameter.  For example, this is useless:
  6028.  
  6029.        findfirst buf "c:\icom\icom.exe"
  6030.        FINDNEXT buf    ;can't possible have another file called ICOM.EXE
  6031.  
  6032.       This isn't:
  6033.  
  6034.        findfirst buf "c:\icom\icom.*"   ;any extension will do, so you could
  6035.                                         ; match ICOM.EXE, ICOM.PWD, ICOM.HLP,
  6036.                                         ; ICOM.DAT, etc.
  6037.        FINDNEXT buf                     ;this is likely to find another file
  6038.                                         ; matching ICOM.*
  6039.  
  6040.       NOTE 1: The attributes (nATTRIBUTES) parameter specified in the original
  6041.       FINDFIRST also apply to FINDNEXT.  So if you were searching for
  6042.       Subdirectories in the original FINDFIRST, FINDNEXT would only find
  6043.       Subdirectories.
  6044.  
  6045.       NOTE 2: The $FXXXX variables listed in the 'SEE ALSO' section of
  6046.       FINDFIRST are also set by FINDNEXT.  See FINDFIRST for details.
  6047.  
  6048.      ERRORLEVEL
  6049.  
  6050.       0  FINDNEXT successful (the name of the item was stored in vBUFFER).
  6051.       1  FINDNEXT unsuccessful (nothing else was found).
  6052.  
  6053.      SEE ALSO
  6054.  
  6055.       FINDFIRST
  6056.  
  6057.      EXAMPLE
  6058.  
  6059.        ;display all .BAT files in the \ICOM directory
  6060.  
  6061.       variable buf
  6062.  
  6063.       findfirst buf "\ICOM\*.BAT"
  6064.       while $ERRORLEVEL = 0
  6065.        print buf
  6066.        FINDNEXT buf
  6067.       endwhile
  6068.  
  6069.      FNSTRIP__________________________________________________________________
  6070.  
  6071.      SUMMARY
  6072.  
  6073.       FNSTRIP vBUFFER sFILESPEC nMODE
  6074.  
  6075.      DESCRIPTION
  6076.  
  6077.       Gets portions of sFILESPEC according to nMODE and stores the result in
  6078.       vBUFFER.
  6079.  
  6080.  
  6081.  
  6082.  
  6083.      Intellicomm v2.01               SCRIPT.DOC                             93
  6084.      
  6085.      
  6086.  
  6087.       Values for nMODE:
  6088.  
  6089.       0  Full filename
  6090.       1  All except the drive
  6091.       2  D:NAME.EXT      Drive, name, extension
  6092.       3  NAME.EXT        Name and extension
  6093.       4  D:\PATH\NAME    Drive, path, and name (no extension)
  6094.       5  \PATH\NAME      Path and name (no extension)
  6095.       6  D:NAME          Drive and name (no extension)
  6096.       7  NAME            Name only (no extension)
  6097.       12 D:\PATH\        Drive and path only
  6098.       13 \PATH\          Path only
  6099.       14 D:              Drive only
  6100.       15 .EXT            Extension only
  6101.  
  6102.      EXAMPLE
  6103.  
  6104.       variable drive_path
  6105.  
  6106.       FNSTRIP drive_path "D:\PATH\FILENAME.EXT" 12
  6107.       print drive_path   ;this prints D:\PATH\
  6108.  
  6109.      FOPEN____________________________________________________________________
  6110.  
  6111.      SUMMARY
  6112.  
  6113.       FOPEN vHANDLEBUF sFILENAME sMODE
  6114.  
  6115.      DESCRIPTION
  6116.  
  6117.       NOTE: Before using FOPEN, please read the section "PERMANENT VARIABLES:
  6118.       INTRODUCTION TO FILE INPUT/OUTPUT" in SCRTUTOR.DOC.
  6119.  
  6120.       Opens file sFILENAME for reading/writing or both (as specified by sMODE)
  6121.       and stores a file 'handle' in variable vHANDLEBUF.
  6122.  
  6123.       vHANDLEBUF should be a variable defined with the script VARIABLE
  6124.       command.  vHANDLEBUF is used to distinguish one open file from another (
  6125.       must then be used by various other file-related commands, to manipulate
  6126.       the open file.
  6127.  
  6128.       sFILENAME is the name of the file to open.  A drive and path can (and
  6129.       should) be specified along with the filename.  Wildcards (? and *) are
  6130.       NOT accepted by FOPEN.
  6131.  
  6132.       sMODE must be one of the following values:
  6133.  
  6134.       "r"   Opens sFILENAME for Reading (no writes are allowed: the file
  6135.             cannot be modified).
  6136.       "w"   Opens sFILENAME for Writing.  If the file exists, its contents
  6137.             will be destroyed.  No reads are allowed in this mode.
  6138.       "a"   Opens sFILENAME for Appending (no reads are allowed; data is added
  6139.             to the end of the file).  If the file does not exist, it will be
  6140.             created.
  6141.  
  6142.  
  6143.  
  6144.  
  6145.      Intellicomm v2.01               SCRIPT.DOC                             94
  6146.      
  6147.      
  6148.  
  6149.       
  6150.       Advanced (open for reading AND writing):
  6151.  
  6152.       "r+"  Opens sFILENAME for Reading and writing.  If sFILENAME does not
  6153.             exist, it will be created.
  6154.       "w+"  Opens sFILENAME for Writing and reading.  If sFILENAME exists, its
  6155.             contents are destroyed (use "r+" to open for read/write without
  6156.             destroying existing files).
  6157.       "a+"  Opens sFILENAME for reading and Appending (adds to the end).  If
  6158.             the file doesn't exist, it will be created.
  6159.  
  6160.       NOTE 1: Never open the same file twice.  For example, you can open the
  6161.       capture file to add some data to it, but you must first call CAPCLOSE to
  6162.       close the file:
  6163.  
  6164.        variable f
  6165.  
  6166.        cappush     ;save capture status/filename
  6167.        capclose
  6168.        FOPEN f $CAP_NAME "a"
  6169.        fputs f "^M^JAdd something to the capture file...^M^J"
  6170.        fclose f
  6171.        cappop      ;reset the capture file to its original state
  6172.  
  6173.       You 'can' get away with opening the same file multiple times on some
  6174.       computers, but if SHARE is loaded the user will receive an error message
  6175.       and the FOPEN will not succeed.  Exception 12 and 13 errors (which
  6176.       effectively hang the machine, requiring a re-boot) can also result from
  6177.       operating on an open file.
  6178.  
  6179.       NOTE 2: Never attempt to DELETE or RENAME an open file.  It will result
  6180.       in lost chains, and even exception 13's.
  6181.  
  6182.       NOTE 3: Most of the file-oriented commands such as COPY, APPEND, etc.,
  6183.       perform their own FOPEN.  Don't attempt to use a file-oriented command
  6184.       on an open file (FINDFIRST/FINDNEXT/EXIST/NOTEXIT are fine, but most
  6185.       others can cause SHARE or exception errors if used on an open file).
  6186.  
  6187.       NOTE 4: Most Intellicomm data files (.BAT, .BIF, .INI, .KWD, .SCR [even
  6188.       the currently executing script]) are CLOSED when scripts are running. 
  6189.       Exceptions are the capture file ($CAP_NAME, which can be closed with
  6190.       CAPCLOSE), any files you've previously opened with FOPEN (which can be
  6191.       closed with FCLOSE), and any catalogs you've opened with COPEN (which
  6192.       opens *5* files: the .DBF, .DBT, and the 3 .NDX files related to the
  6193.       catalog.  Catalogs can be closed with CCLOSE).  You can safely FOPEN any
  6194.       other Intellicomm data files, if you know what you're doing and have a
  6195.       specific need to use a data file directly.  When Intellicomm needs
  6196.       information from a data file it normally opens the file, takes what it
  6197.       needs, and closes it immediately.  This is true even while scripts are
  6198.       running: LOADBIF, for example, does not leave the .BIF open.  It simply
  6199.       loads the information into memory, and the .BIF file itself is closed
  6200.       when LOADBIF finishes.
  6201.  
  6202.       NOTE 5: Never write to ICOM.USE (the Usage Log) unless you've read the
  6203.  
  6204.  
  6205.  
  6206.  
  6207.      Intellicomm v2.01               SCRIPT.DOC                             95
  6208.      
  6209.      
  6210.  
  6211.       Call Data Standard specifications (available on many BBS's as CDS.ZIP). 
  6212.       Icom's Usage Log follows a fixed format, and writing anything other than
  6213.       comments to the file (which should be done with the STAMP command and
  6214.       not with FOPEN/FPUTS/FCLOSE) could render the entire Usage Log
  6215.       unreadable.
  6216.  
  6217.      ERRORLEVEL
  6218.  
  6219.       0  sFILENAME successfully opened.
  6220.       1  sFILENAME doesn't exist (read mode) or couldn't be created (invalid
  6221.          drive, path or filename in write mode, or root directory full).
  6222.       2  Too many open files.  Tell the user to increase the FILES= line in
  6223.          the computer's CONFIG.SYS file.
  6224.       3  Not enough memory to open the file.
  6225.       4  Permission denied (tried to open a read-only file in Write mode).
  6226.       5  Miscellaneous errors too numerous and obscure to mention.  The file
  6227.          wasn't opened.
  6228.  
  6229.       NOTE: If you get anything other than $ERRORLEVEL = 0 after FOPEN, do not
  6230.       attempt to use vHANDLEBUF.  This bit below would abort with an "Invalid
  6231.       file handle" error:
  6232.  
  6233.       variable f
  6234.  
  6235.       FOPEN f "|INVALID" "w"   ; '|' is not valid in DOS filenames
  6236.       if $ERRORLEVEL > 0
  6237.        fclose f                ;aborts the script.  The file is NEVER opened
  6238.       endif                    ; if an $errorlevel is returned, and the value
  6239.                                ; stored in variable 'f' will be 0 (zero) which
  6240.                                ; is always an invalid file handle.
  6241.  
  6242.  
  6243.      SEE ALSO
  6244.  
  6245.       APPEND, APPENDS, APPENDSNC (quicker ways to add to a file without
  6246.       bothering with FOPEN/FCLOSE), FCLOSE
  6247.  
  6248.      EXAMPLE 1
  6249.  
  6250.       variable datfile
  6251.       FOPEN datfile "TEMP.$$$" "w"
  6252.       fputs datfile "Store this on line 1 of TEMP.$$$"
  6253.       fputs datfile "Store this on line 2 of TEMP.$$$"
  6254.       fclose datfile
  6255.  
  6256.      EXAMPLE 2
  6257.  
  6258.       variable key
  6259.       variable f
  6260.  
  6261.       msgopen "Please turn on your printer and press a key..."
  6262.       inkey key
  6263.       msgclose
  6264.       fopen f $PRN "w"     ;open the printer device for writing
  6265.  
  6266.  
  6267.  
  6268.  
  6269.      Intellicomm v2.01               SCRIPT.DOC                             96
  6270.      
  6271.      
  6272.  
  6273.       fputs f "These lines will be printed on the printer."
  6274.       fputs f "Most printers require a CR before they actually print anything"
  6275.       fputs f "but FPUTS sends a CR so that's no problem.  If you use FPUTC"
  6276.       fputs f "or FPUTSNC (no CR) then your line will not be printed until"
  6277.       fputs f "you send a CR."
  6278.       fputs f "^L"   ;Ctrl-L is a Form Feed.  It causes the printer to move to
  6279.                      ; the top of the next page.
  6280.       fclose f
  6281.  
  6282.      FPUTC____________________________________________________________________
  6283.  
  6284.      SUMMARY
  6285.  
  6286.       FPUTC vHANDLE sCHARACTER
  6287.  
  6288.      DESCRIPTION
  6289.  
  6290.       Writes the character sCHARACTER to the file handle specified by vHANDLE. 
  6291.       vHANDLE must be a file handle obtained via FOPEN.  No carriage return or
  6292.       line feed is added after sCHARACTER (as with FPUTS).
  6293.  
  6294.      ERRORLEVEL
  6295.  
  6296.       0  sCHARACTER was successfully written.
  6297.       1  Unable to write sCHARACTER (the disk is likely full).
  6298.  
  6299.      SEE ALSO
  6300.  
  6301.       FPUTS, FPUTSNC
  6302.  
  6303.      EXAMPLE
  6304.  
  6305.      FPUTS____________________________________________________________________
  6306.  
  6307.      SUMMARY
  6308.  
  6309.       FPUTS vHANDLE sSTRING ...
  6310.  
  6311.      DESCRIPTION
  6312.  
  6313.       Writes sSTRING to the file signified by vHANDLE.  A carriage return and
  6314.       line feed are automatically added to the end of sSTRING (terminating the
  6315.       line in the file).  Use FPUTSNC if you don't want CR/LF added.
  6316.  
  6317.       vHANDLE must be a valid file handle obtained via FOPEN.
  6318.  
  6319.      ERRORLEVEL
  6320.  
  6321.       0  sSTRING was successfully written.
  6322.       1  Unable to write sSTRING (the disk is likely full).
  6323.  
  6324.      SEE ALSO
  6325.  
  6326.       FPUTC, FPUTSNC
  6327.  
  6328.  
  6329.  
  6330.  
  6331.      Intellicomm v2.01               SCRIPT.DOC                             97
  6332.      
  6333.      
  6334.  
  6335.      EXAMPLE
  6336.  
  6337.       variable datfile
  6338.       fopen datfile "TEMP.$$$" "w"
  6339.       FPUTS datfile "Store this on line 1 of TEMP.$$$"
  6340.       FPUTS datfile "Store this on line 2 of TEMP.$$$"
  6341.       fclose datfile
  6342.  
  6343.      FPUTSNC__________________________________________________________________
  6344.  
  6345.      SUMMARY
  6346.  
  6347.       FPUTSNC vHANDLE sSTRING ...
  6348.  
  6349.      DESCRIPTION
  6350.  
  6351.       Writes sSTRING to the file signified by vHANDLE.  A carriage return and
  6352.       line feed are NOT automatically added to the end of sSTRING (as with
  6353.       FPUTS).  Use FPUTS if you want to terminate the line with CR/LF.
  6354.  
  6355.       vHANDLE must be a valid file handle obtained via FOPEN.
  6356.  
  6357.      ERRORLEVEL
  6358.  
  6359.       0  sSTRING was successfully written.
  6360.       1  Unable to write sSTRING (the disk is likely full).
  6361.  
  6362.      SEE ALSO
  6363.  
  6364.       FPUTC, FPUTS
  6365.  
  6366.      EXAMPLE
  6367.  
  6368.       variable datfile
  6369.       fopen datfile "TEMP.$$$" "w"
  6370.       FPUTS datfile "Store this on line 1 of TEMP.$$$"
  6371.       FPUTS datfile "Store this on line 2 of TEMP.$$$"
  6372.       fclose datfile
  6373.  
  6374.      FSEEK____________________________________________________________________
  6375.  
  6376.      SUMMARY
  6377.  
  6378.       FSEEK vHANDLE nOFFSET nORIGIN
  6379.  
  6380.      DESCRIPTION
  6381.  
  6382.       FSEEK is an advanced command that moves the file pointer of the file
  6383.       signified by vHANDLE.  The file pointer determines whether the next
  6384.       read/write will take place, as outlined in "INTRODUCTION TO FILE
  6385.       INPUT/OUTPUT" section of SCRTUTOR.DOC.
  6386.  
  6387.       vHANDLE is a valid file handle obtained by FOPEN.
  6388.  
  6389.  
  6390.  
  6391.  
  6392.      Intellicomm v2.01               SCRIPT.DOC                             98
  6393.      
  6394.      
  6395.  
  6396.       nOFFSET is the number of bytes to seek from nORIGIN (0 = the first byte
  6397.       in the file).  Positive numbers seek forward from nORIGIN, negative
  6398.       numbers seek backwards from nORIGIN.
  6399.  
  6400.       nORIGIN is a number that specifies the initial location of the seek:
  6401.  
  6402.        0 = From the beginning of the file.
  6403.        1 = From the current position of the file pointer.
  6404.        2 = From the end of the file.
  6405.  
  6406.       NOTE: It is legal to seek past the end of a file, but you cannot seek
  6407.       past the beginning of a file.  If you seek past the end of a file, the
  6408.       portion of the file from the original end-of-file to the new FSEEK
  6409.       position will likely contain garbage.  Assume a file called HELLO, with
  6410.       5 bytes in it:
  6411.  
  6412.        HELLO
  6413.  
  6414.       If you did this to modify HELLO in your script:
  6415.  
  6416.        variable f
  6417.        fopen f "HELLO" "r+"   ;open for read/write
  6418.        FSEEK f 10 0           ;seek 10 bytes from the beginning (past the end)
  6419.        fputs f "THERE"
  6420.        fclose f 
  6421.  
  6422.       ...the file HELLO would likely contain garbage between "HELLO" (the
  6423.       original file contents) and "THERE" (the portion added at position 10 in
  6424.       the above example):
  6425.  
  6426.                 1
  6427.       012345678901234   <-- Numeric ruler for reference
  6428.       HELLO%~@-\THERE   <-- Contents of file HELLO after FSEEK 10 0/FPUTS
  6429.  
  6430.      ERRORLEVEL
  6431.  
  6432.       0  FSEEK was successful (the file pointer has been moved).
  6433.  
  6434.       1  FSEEK was unsuccessful (the file pointer remains where it was
  6435.          previously).  This error will occur if you attempt to seek past the
  6436.          beginning of the file ('FSEEK f -100 2' to seek back 100 bytes from
  6437.          the END of the file, on a file that is only 50 bytes long for
  6438.          example).
  6439.  
  6440.      SEE ALSO
  6441.  
  6442.       FOPEN
  6443.  
  6444.      EXAMPLE
  6445.  
  6446.       Please see "PERMANENT VARIABLES: INTRODUCTION TO FILE INPUT / OUTPUT" in
  6447.       SCRTUTOR.DOC for detailed FSEEK explanations and examples.
  6448.  
  6449.       variable fh
  6450.  
  6451.  
  6452.  
  6453.  
  6454.      Intellicomm v2.01               SCRIPT.DOC                             99
  6455.      
  6456.      
  6457.  
  6458.       fopen fh "TEST.$$$" "r+"
  6459.       FSEEK fh 100 0
  6460.       fputs fh "TEST"
  6461.       fclose f
  6462.  
  6463.      FTELL____________________________________________________________________
  6464.  
  6465.      SUMMARY
  6466.  
  6467.       FTELL vBUFFER vHANDLE
  6468.  
  6469.      DESCRIPTION
  6470.  
  6471.       Gets the current position of the file pointer for file vHANDLE and
  6472.       stores it in vBUFFER.
  6473.  
  6474.       vHANDLE must be a valid file handle obtained via FOPEN.
  6475.  
  6476.      EXAMPLE
  6477.  
  6478.       variable fh
  6479.       variable buf
  6480.  
  6481.       fopen fh "TEST.FIL" "r"
  6482.       fgets buf fh
  6483.       FTELL buf fh
  6484.       print "Current positon: " buf
  6485.  
  6486.      GETENV___________________________________________________________________
  6487.  
  6488.      SUMMARY
  6489.  
  6490.       GETENV vBUFFER sENVLABEL
  6491.  
  6492.      DESCRIPTION
  6493.  
  6494.       Gets the contents of envirnment variable sENVLABEL and if found, stores
  6495.       it in vBUFFER.
  6496.  
  6497.      ERRORLEVEL
  6498.  
  6499.       0  Label sENVLABEL was found in the environment and its contents has
  6500.          been stored in vBUFFER.
  6501.       1  Label sENVLABEL does not exist in the environment.
  6502.  
  6503.      SEE ALSO
  6504.  
  6505.       SETENV
  6506.  
  6507.      EXAMPLE
  6508.  
  6509.       variable path
  6510.  
  6511.       GETENV path "PATH"
  6512.  
  6513.  
  6514.  
  6515.  
  6516.      Intellicomm v2.01               SCRIPT.DOC                            100
  6517.      
  6518.      
  6519.  
  6520.       print "PATH=" path
  6521.  
  6522.      GETFNAME_________________________________________________________________
  6523.  
  6524.      SUMMARY
  6525.  
  6526.       GETFNAME [sDIRECTORY] [sFILESPEC] [sHELPLINE]
  6527.  
  6528.      DESCRIPTION
  6529.  
  6530.       This command requires a few skills to use, but it can be very useful in
  6531.       advanced script projects.  GETFNAME accesses a variation of the Icom
  6532.       "File Manager" (FILEMAN command) displaying all files that match
  6533.       sDIRECTORY sFILESPEC (a D:\PATH\FILESPEC the drive, path, AND filespec
  6534.       are all optional) as the File Manager does.  But GETFNAME allows the
  6535.       user to "Select" one or more files for your script to operate on.  Note
  6536.       that D:\PATH\ and FILESPEC are specified *separately* in different
  6537.       parameters.
  6538.  
  6539.       If you omit the 'D:' (Drive) in sDIRECTORY, the current drive is assumed
  6540.       If you omit the \PATH\ portion, the \ICOM directory, or the last
  6541.       directory displayed is assumed (a trailing slash is not necessary when
  6542.       specifying path names, but is acceptable).  If you omit the FILESPEC,
  6543.       *.* is assumed.  Thus if you use:
  6544.  
  6545.        GETFNAME "\"
  6546.  
  6547.       D:\*.* (where D: is the current drive) is displayed to the user.  As in
  6548.       the Icom File Manager, the user can change to a new directory if need
  6549.       be, and can also View, Edit, Find (full disk search), Ren/Move, Delete
  6550.       files, etc., before making a selection.
  6551.  
  6552.       If sHELPLINE is specified, it is displayed in the File Manager message
  6553.       box, until the user presses a key.  Note that if you omit the sFILESPEC
  6554.       parameter but DO want to specify a help line, you must do the following:
  6555.  
  6556.        GETFNAME "\" "" "Help Line"   ;<-- Help must be the THIRD parameter
  6557.  
  6558.       Since the user is able to "Tag" and "Select" multiple files, GETFNAME
  6559.       does not store the selected filename(s) in a script variable, but
  6560.       instead writes all the selected files out to a text file called
  6561.       \ICOM\GETFNAME.LST, which you can read using the script File I/O
  6562.       commands (see the example below).  For example, if you displayed
  6563.       C:\ICOM\*.BAT with GETFNAME, and the user Tagged/Selected the files:
  6564.       POSTMAIL.BAT and POSTDOWN.BAT, the file \ICOM\GETFNAME.LST would contain
  6565.       the following two lines:
  6566.  
  6567.      C:\ICOM\POSTMAIL.BAT
  6568.      C:\ICOM\POSTDOWN.BAT
  6569.  
  6570.      ERRORLEVEL
  6571.  
  6572.       GETFNAME does not set $ERRORLEVEL.  On entry it deletes the file
  6573.       C:\ICOM\GETFNAME.LST if it exists, and thus if the user doesn't select
  6574.  
  6575.  
  6576.  
  6577.  
  6578.      Intellicomm v2.01               SCRIPT.DOC                            101
  6579.      
  6580.      
  6581.  
  6582.       any files, GETFNAME.LST will not exist.  This is how you can determine
  6583.       whether the user selected any files or not: by the existence or non-
  6584.       existence of GETFNAME.LST after GETFNAME finishes (see example below).
  6585.  
  6586.      SEE ALSO
  6587.  
  6588.       DIRFIND, DISKFIND, LOCATEFILE
  6589.  
  6590.      EXAMPLE
  6591.  
  6592.      ;NOTE that this example is only meant to illustrate the GETFNAME command
  6593.      ; and you could accomplish much the same thing by using a single UPLOAD
  6594.      ; command, without specifying the filenames to upload.  When this is the
  6595.      ; case, UPLOAD prompts the user to enter filenames just as when you 
  6596.      ; press [PgUp] when online, and the user could also press [Alt-F] to
  6597.      ; enter the Upload File Picker (which does the same thing as below).
  6598.  
  6599.      variable lstname $HOME_DIR "GETFNAME.LST" ;C:\ICOM\GETFNAME.LST
  6600.      variable lst                              ;file handle for GETFNAME.LST
  6601.      variable s                                ;general purpose
  6602.  
  6603.      stritem s $UL_PATH 1                      ;store 1st dir on U/L PATH in s
  6604.  
  6605.      GETFNAME s "" "Please ^"Select^" one or more files to upload"
  6606.      notexist lstname goto skip_ul
  6607.  
  6608.      strins lstname "@" 0 1                    ;@C:\ICOM\GETFNAME.LST
  6609.      upload "Z" lstname                        ;uploads all files on the list
  6610.      strdel lstname 0 1                        ;kill the @ (position 0, 1
  6611.      char)
  6612.  
  6613.      ;This below illustrates how to extract each filename separately from
  6614.      ; GETFNAME.LST.  We only PRINT the filenames below (which are stored
  6615.      ; in 's' by FGETS), but you'd be free to do whatever you wanted with
  6616.      ; the filename(s), including FOPENing the file, DELETEing it, etc.
  6617.  
  6618.      if $ERRORLEVEL = 0           ;set by UPLOAD if successful
  6619.       print "Files uploaded:" 
  6620.       fopen lst lstname "r"       ;open GETFNAME.LST for "r"eading
  6621.       while 1                     ;endless loop (until BREAK)
  6622.        fgets s lst                ;get first/next line from GETFNAME.LST
  6623.        if $ERRORLEVEL <> 0 BREAK  ;exit loop at end of file (set by FGETS)
  6624.        print s                    ;do whatever you like with each file
  6625.       endwhile
  6626.       fclose lst                  ;always close what you FOPEN
  6627.      endif
  6628.  
  6629.      delete lstname               ;not necessary, but nice to keep it clean
  6630.      skip_ul:
  6631.       return
  6632.  
  6633.      GETS_____________________________________________________________________
  6634.      GETSXY___________________________________________________________________
  6635.  
  6636.  
  6637.  
  6638.  
  6639.      Intellicomm v2.01               SCRIPT.DOC                            102
  6640.      
  6641.      
  6642.  
  6643.      SUMMARY
  6644.  
  6645.       GETS vINPUT nMAXLEN
  6646.       GETSXY vINPUT nMAXLEN [nX] [nY] [nCOLOR]
  6647.  
  6648.      DESCRIPTION
  6649.  
  6650.       Both commands get user input from the keyboard, a maximum of nMAXLEN
  6651.       characters long, and store the result in variable vINPUT.  If variable
  6652.       vINPUT contains any data, it is offered to the user as a default value. 
  6653.       I.e. if you do not wish to offer a default, you must clear the vINPUT
  6654.       variable if it was used previously:
  6655.  
  6656.        assign myvariable ""   ;clear variable 'myvariable'
  6657.        GETS myvariable 10     ;get up to 10 characters of input
  6658.  
  6659.       GETS obtains the input at the current cursor position ($SCRN_Y,
  6660.       $SCRN_Y), while GETSXY obtains input at specific screen X,Y coordinates
  6661.       (nX, nY parameters above).  Both nX and nY are optional and if both
  6662.       coordinates are omitted, the input is obtained at the current cursor
  6663.       position (as with GETS).  If only the nX (screen column, left to right)
  6664.       position is specified, $SCRN_Y (the current cursor row) is used.
  6665.  
  6666.       Both commands get input and display the input 'field' in a specific
  6667.       color, showing the maximum length (nMAXLEN) of the input field.  GETS
  6668.       uses the $BAR_COLOR color (as with most Intellicomm input fields) as
  6669.       does GETSXY if the [nCOLOR] parameter is omitted.  If you specify
  6670.       [nCOLOR] with GETSXY (or if you temporarily change $BAR_COLOR prior to
  6671.       using either GETS or GETSXY), you can display an input field using
  6672.       another color.  See the COLOR CODES Appendix for information on creating
  6673.       custom color codes.
  6674.  
  6675.       GETS and GETSXY use the same input routine that BOXGETS uses, but they
  6676.       don't display a box or prompt (>) character.  Please see the BOXGETS
  6677.       description for more details on cursor keys and hotkeys available to the
  6678.       user when entering input, and an example of checking $ERRORLEVEL after
  6679.       the user input (Esc key pressed, etc).
  6680.  
  6681.      ERRORLEVEL
  6682.  
  6683.       0   The user entered something then pressed the [Enter] key or left
  6684.           mouse button (variable vINPUT contains data).
  6685.       1   The user pressed [Enter], but variable vINPUT is empty ... nothing
  6686.           was entered.
  6687.       2   The user pressed the [Esc] key or right mouse button to cancel.  If
  6688.           this occurs, the contents of vINPUT reverts to its original value 
  6689.           (the default you offered) whether the user changed it on the input
  6690.           line or not.
  6691.      256+ If a value of 256 or greater is in $ERRORLEVEL when BOXGETS returns,
  6692.           the user pressed a key defined in one of the $HOTKEY_? variables. 
  6693.           See the BOXGETS example for details.
  6694.  
  6695.      SEE ALSO
  6696.  
  6697.  
  6698.  
  6699.  
  6700.      Intellicomm v2.01               SCRIPT.DOC                            103
  6701.      
  6702.      
  6703.  
  6704.       BOXGETS, INKEY
  6705.  
  6706.      EXAMPLE
  6707.  
  6708.       variable myvariable            ;define a variable called 'myvariable'
  6709.  
  6710.       assign myvariable "Default Response"  ;give the user a default
  6711.       printnc "Enter your response: "       ;print, no CR
  6712.       GETS myvariable 30                    ;30 chars max
  6713.       printnc "You entered: "
  6714.       print myvariable
  6715.       
  6716.        ;this bit below gets user input on the status line (similar to the
  6717.        ; way Icom prompts for a new capture file when you press [Alt-L])
  6718.  
  6719.       assign $STAT_ON 0                     ;turn the status line off
  6720.       scroll 1 $SCRN_HEIGHT $SCRN_WIDTH $SCRN_HEIGHT 0 $STAT_COLOR
  6721.        ;draws a blank line in the usual status bar color, on the bottom
  6722.        ; screen line
  6723.       printraw 1 $SCRN_HEIGHT $STAT_COLOR "Enter your response:"
  6724.       GETSXY myvariable 80 22 $SCRN_HEIGHT $STAT_COLOR  ;on the status line
  6725.       
  6726.       assign $STAT_ON 1                     ;restore status line
  6727.  
  6728.      GOSUB____________________________________________________________________
  6729.      RETURN___________________________________________________________________
  6730.  
  6731.      SUMMARY
  6732.  
  6733.       GOSUB LABEL
  6734.  
  6735.      DESCRIPTION
  6736.  
  6737.       GOSUB/RETURN work as a team and allow you to execute a set of script
  6738.       commands, then continue where you came from.  While GOTO simply jumps to
  6739.       a label without returning, GOSUB jumps to the label, then RETURNs to the
  6740.       command(s) following the GOSUB, if any.  One exception is when GOSUB is
  6741.       used in a WHEN command.  In that case, control returns to the WAITFOR
  6742.       if/when a RETURN is found (see the example below).
  6743.  
  6744.       NOTE: If Icom runs across a RETURN command and has not previously
  6745.       executed a GOSUB command, the script simply ends at that point (RETURN
  6746.       is the usual command to exit a script).
  6747.  
  6748.       NOTE FOR ADVANCED SCRIPT WRITERS: GOSUB can also jump to a label using a
  6749.       variable.  Just store the label's name in the variable, then specify the
  6750.       variable preceded by an asterisk:
  6751.  
  6752.        variable label "some_label"
  6753.  
  6754.        gosub *label    ;same as 'gosub some_label'
  6755.  
  6756.        some_label:
  6757.  
  6758.  
  6759.  
  6760.  
  6761.      Intellicomm v2.01               SCRIPT.DOC                            104
  6762.      
  6763.      
  6764.  
  6765.      SEE ALSO
  6766.  
  6767.       GOTO
  6768.  
  6769.      EXAMPLE
  6770.  
  6771.       GOSUB initialize_script  ;jump to label 'initialize_script:'
  6772.                                ;control returns to this line after the RETURN
  6773.       send "Some Command"
  6774.       waitfor main_menu 120    
  6775.  
  6776.       when
  6777.       when "some prompt" gosub handle_some_prompt
  6778.       when "another prompt" "do this"
  6779.       waitfor main_menu 120    ;control returns to WAITFOR after the GOSUB
  6780.  
  6781.       RETURN                   ;exit script (no GOSUB is active)
  6782.  
  6783.      initialize_script:        ;subroutine labels are the same as GOTO labels
  6784.  
  6785.        ;define a variable for use later in the script
  6786.       variable main_menu
  6787.       getbif main_menu "L" "mnap"    ;BIF [L]ogon section, Main Menu A prompt
  6788.       RETURN                   ;return from the subroutine
  6789.  
  6790.      handle_some_prompt:
  6791.       ... ;any number of commands can be placed here to handle what needs
  6792.      doing
  6793.       RETURN
  6794.  
  6795.      GOTO_____________________________________________________________________
  6796.  
  6797.      SUMMARY
  6798.  
  6799.       GOTO LABEL
  6800.  
  6801.      DESCRIPTION
  6802.  
  6803.       Jumps to the label specified by LABEL (a colon is not needed after
  6804.       LABEL, but is acceptable).  GOTO is used to skip over a portion of a
  6805.       script when a certain condition warrants it.
  6806.  
  6807.       Script labels are covered in the introduction of SCRTUTOR.DOC.
  6808.  
  6809.       NOTE FOR ADVANCED SCRIPT WRITERS: GOTO can also jump to a label using a
  6810.       variable.  Just store the label's name in the variable, then specify the
  6811.       variable preceded by an asterisk:
  6812.  
  6813.        variable label "some_label"
  6814.  
  6815.        goto *label    ;same as 'goto some_label'
  6816.  
  6817.        some_label:
  6818.  
  6819.  
  6820.  
  6821.  
  6822.      Intellicomm v2.01               SCRIPT.DOC                            105
  6823.      
  6824.      
  6825.  
  6826.      SEE ALSO
  6827.  
  6828.       GOSUB
  6829.  
  6830.      EXAMPLE
  6831.  
  6832.       online GOTO skip_logon  ;skip dial/logon if have a connection
  6833.  
  6834.       dial "Favorite BBS" 1
  6835.       waitfor "name:"
  6836.       send "Joe Smith"
  6837.       ...etc.
  6838.  
  6839.      skip_logon:
  6840.  
  6841.       send "D SOMEFILE.ZIP Z"
  6842.       download ""
  6843.       hangup
  6844.       return
  6845.  
  6846.      GOTOXY___________________________________________________________________
  6847.  
  6848.      SUMMARY
  6849.  
  6850.       GOTOXY nX nY
  6851.  
  6852.      DESCRIPTION
  6853.  
  6854.       Moves the cursor to screen column nX (left to right), row nY (top to
  6855.       bottom).  The top left corner of the screen is 1 1.
  6856.  
  6857.       If WINDOW or WNDOPEN are currently in effect, the top corner of the
  6858.       WINDOW ($WND_LEFT, $WND_TOP) represents screen coordinate 1 1, instead
  6859.       of the actual top of the video display.
  6860.  
  6861.      SEE ALSO
  6862.  
  6863.       CURPUSH, CURPOP
  6864.  
  6865.      EXAMPLE
  6866.  
  6867.       GOTOXY 1 1
  6868.       print "This is displayed at the top of the screen, or the top of the"
  6869.       print "current WINDOW (if any)."
  6870.  
  6871.      HANGUP___________________________________________________________________
  6872.  
  6873.      SUMMARY
  6874.  
  6875.       HANGUP
  6876.  
  6877.      DESCRIPTION
  6878.  
  6879.       Causes the modem to disconnect.  If the main setup item "Drop DTR to
  6880.  
  6881.  
  6882.  
  6883.  
  6884.      Intellicomm v2.01               SCRIPT.DOC                            106
  6885.      
  6886.      
  6887.  
  6888.       Hangup?" (*dtrhangup) is set to Yes, HANGUP drops the DTR (Data Terminal
  6889.       Ready) line for 1.5 seconds, delays for 0.5 seconds, then checks the
  6890.       carrier status.  If still connected (or if "Drop DTR to Hangup" was set
  6891.       to No) the main setup "Modem Hangup String" (normally +++ATH0) is then
  6892.       sent to the modem.
  6893.  
  6894.       Note that HANGUP ignores the main setup "Confirm Hangup?" option which
  6895.       asks the user for confirmation before hanging up.  You can easily
  6896.       simulate your own 'Hangup?  Yes  No' menu with these commands:
  6897.  
  6898.       IF *hconfirm = 0            ;Confirm Hangup variable set to NO (0)?
  6899.        HANGUP
  6900.       ELSE
  6901.        MENUDEFINE "~Yes" "~No"    ;define a Yes/No menu
  6902.        MENUBOXH "" "^IHangup?"    ;^I (TAB) puts help on same line as menu
  6903.        IF $ERRORLEVEL = 1 HANGUP  ;if "Yes" (item 1) then hang up
  6904.       ENDIF
  6905.  
  6906.       This gives the exact same menu in a box that the main setup "Confirm
  6907.       Hangup?" option does.
  6908.  
  6909.      ERRORLEVEL
  6910.  
  6911.       0  Successful (disconnected).
  6912.       1  Unsuccessful (modem reports still connected).  Note that if the modem
  6913.          is forcing the carrier detect signal on, HANGUP will always set
  6914.          $ERRORLEVEL 1 and will display a "Hangup Failed" message.  HANGUP
  6915.          checks the carrier detect before returning and if it's being forced
  6916.          on, Icom will always think it's connected (it has no other way of
  6917.          knowing, other than what the modem tells it).  This problem is quite
  6918.          common due to the way modems are configured from the factory, and the
  6919.          usual fixes are outlined in the "Common Questions & Answers" online
  6920.          help link.
  6921.  
  6922.      HELP_____________________________________________________________________
  6923.  
  6924.      SUMMARY
  6925.  
  6926.       HELP [sHELPLINK]
  6927.  
  6928.      DESCRIPTION
  6929.  
  6930.       If sHELPLINK is omitted the Help Index is displayed.  If sHELPLINK is
  6931.       specified, all .HLP files are searched for the link and, if found, the
  6932.       topic is displayed.  Specify sHELPLINK exactly as you see it in the
  6933.       online help system (see example).
  6934.  
  6935.      ERRORLEVEL
  6936.  
  6937.       0  sHELPLINK was found and displayed
  6938.       1  sHELPLINK not found
  6939.  
  6940.      SEE ALSO
  6941.  
  6942.  
  6943.  
  6944.  
  6945.      Intellicomm v2.01               SCRIPT.DOC                            107
  6946.      
  6947.      
  6948.  
  6949.       HELPFIND
  6950.  
  6951.      EXAMPLE
  6952.  
  6953.       HELP "Script Language"  ;display the Script Language link
  6954.  
  6955.      HELPFIND_________________________________________________________________
  6956.  
  6957.      SUMMARY
  6958.  
  6959.       HELPFIND sSEARCHTEXT
  6960.  
  6961.      DESCRIPTION
  6962.  
  6963.       Similar to pressing [Ctrl-F1] (Search) in the help system.  Searches all
  6964.       help topics for the text sSEARCHTEXT, writes all links containing the
  6965.       text to the file SEARCH.HLP, then displays the file SEARCH.HLP (all the
  6966.       links found, if any) for selection/viewing.
  6967.  
  6968.      ERRORLEVEL
  6969.  
  6970.       0  sSEARCHTEXT was found and SEARCH.HLP was displayed.
  6971.       1  sSEARCHTEXT was not found.
  6972.  
  6973.      SEE ALSO
  6974.  
  6975.       HELP
  6976.  
  6977.      EXAMPLE
  6978.  
  6979.       HELPFIND "script"  ;find all topics containing the word 'script'
  6980.                          ; and display them
  6981.       
  6982.        ;Later in your script you can display the results of the previous
  6983.        ; HELPFIND by using:
  6984.  
  6985.       HELP "Search Results"
  6986.  
  6987.      IF_____________________________________________________________________
  6988.       ELSE__________________________________________________________________
  6989.       ENDIF_________________________________________________________________
  6990.  
  6991.      SUMMARY
  6992.  
  6993.       IF ITEM1 OPERATOR ITEM2 [cCOMMAND]
  6994.        [cCOMMAND]
  6995.        ...
  6996.       [ELSE]
  6997.        [cCOMMAND]
  6998.        ...
  6999.       [ENDIF]
  7000.  
  7001.      DESCRIPTION
  7002.  
  7003.  
  7004.  
  7005.  
  7006.      Intellicomm v2.01               SCRIPT.DOC                            108
  7007.      
  7008.      
  7009.  
  7010.       IF compares ITEM1 and ITEM2 according to OPERATOR and if the comparison
  7011.       is true it executes the cCOMMAND parameter on the same line as the IF
  7012.       command (if specified), or skips cCOMMAND if the comparison is false. 
  7013.       If a cCOMMAND parameter is given on the same line as the IF statement,
  7014.       you *cannot* use ELSE or ENDIF.  If no cCOMMAND is given on the same
  7015.       line as the IF command, an IF/ENDIF sequence is assumed and the ENDIF
  7016.       becomes mandatory.  IF/ENDIF is used to execute a SET of commands (as
  7017.       opposed to a single command) and this sequence either:
  7018.  
  7019.        -  executes the command(s) (if any) between IF and ELSE if the
  7020.           comparison is true.
  7021.  
  7022.       OR (ELSE)
  7023.  
  7024.        -  executes the command(s) between ELSE (if specified) and ENDIF if the
  7025.           comparison is FALSE.  If no ELSE is specified, and the condition is
  7026.           false, control is passed to the script command following the ENDIF.
  7027.  
  7028.       The square brackets in the summary denote OPTIONAL items, and should not
  7029.       be used in your script.  ENDIF is only optional if the cCOMMAND
  7030.       parameter is specified on the same line as the IF.  The '...' simply
  7031.       means that more of the same (more commands) can follow.
  7032.  
  7033.       The OPERATOR parameter can be one of the following:
  7034.  
  7035.       OPERATOR      MEANING
  7036.       ---------------------------------------------------------------------
  7037.          =          Equal to
  7038.          <>         Not equal to
  7039.          <          Less than
  7040.          <=         Less than or equal to
  7041.          >          Greater than
  7042.          >=         Greater than or equal to (=> is not valid)
  7043.  
  7044.       If you plan to use variables with IF, only ITEM1 and/or ITEM2 can be
  7045.       variables.  For example, you cannot assign "<>" (Not equal to) to a
  7046.       variable and specify the variable as the OPERATOR parameter.  Nor could
  7047.       you assign the word "PRINT" to a variable and specify that variable as
  7048.       the cCOMMAND paremeter.  You CAN specify another IF as the cCOMMAND
  7049.       parameter:
  7050.  
  7051.        IF myvariable >= 1 IF myvariable <= 10 PRINT ">= 1 and <= 10" 
  7052.  
  7053.       If both ITEM1 and ITEM2 are numbers (variables or contants containing
  7054.       only characters from 0-9 ... surrounding quotes "" or '' are ignored)
  7055.       then a numeric comparison is performed and 1000 is greater than (>) 999,
  7056.       1 is less than (<) 2 as you'd expect.
  7057.  
  7058.       If either ITEM1 or ITEM2 contain TEXT (characters other than 0-9) then a
  7059.       text or "ASCII" comparison is performed.  Text comparisons use the ASCII
  7060.       codes of each character, as outlined in the ASCII CODES Appendix.  One
  7061.       string will be 'greater than' another string if it contains a character
  7062.       with a higher ASCII code.  "B" is greater than "A", and "C" is greater
  7063.       than "B", "Yes" (which starts with a "Y") is greater than "No" (which
  7064.  
  7065.  
  7066.  
  7067.  
  7068.      Intellicomm v2.01               SCRIPT.DOC                            109
  7069.      
  7070.      
  7071.  
  7072.       starts with a "N"), etc.  The ASCII codes assign numbers to all the
  7073.       characters, and these numbers go in the order you'd expect when
  7074.       comparing alphabetic characters.  According to ASCII though, lowercase
  7075.       text is *greater than* UPPERCASE text.  If you compared "Icom" and
  7076.       "ICOM" ... "Icom" would be greater due to the lowercase "c".  The ASCII
  7077.       CODES Appendix shows you the numeric ASCII equivalent of each character
  7078.       so you can see which characters are greater than or less than others.
  7079.  
  7080.       Text comparisons won't be used with IF in a greater than/less than
  7081.       situation very often.  You'll normally want to see if one piece of text
  7082.       (perhaps something the user entered via the GETS command) is EQUAL TO
  7083.       (=) or NOT EQUAL TO (<> ... greater than or less than) some other text. 
  7084.       In order for your comparisons to be accurate, however, you must make
  7085.       sure you're comparing text that is the same case (both strings
  7086.       uppercase, or both lowercase).  The STRUPPER and STRLOWER commands
  7087.       convert text to uppercase/lowercase mainly for this purpose.
  7088.  
  7089.       If you get confused about whether to use < or > for greater than/less
  7090.       just think of them as arrows.  Greater than (>) points to the right ...
  7091.       there are a 'greater' number of right-handed people than there are left-
  7092.       handed people.  So >, which points towards your RIGHT hand is GREATER
  7093.       THAN.
  7094.  
  7095.       NOTE: You needn't indent the commands as was done above in the summary. 
  7096.       Indenting simply make the script more understandable, and also helps you
  7097.       to see that something is MISSING if you forget the ENDIF.  ENDIF is
  7098.       mandatory when IF is used, and your script will abort with an 'IF
  7099.       without ENDIF' error if you forget the ENDIF.
  7100.  
  7101.       TIP:  You can use the IF/ENDIF sequence on its own, OR with any script
  7102.       command that accepts another cCOMMAND as its parameter (EXIST, NOTEXIST,
  7103.       OFFLINE, ONLINE, WHEN, etc).
  7104.  
  7105.      ERRORLEVEL
  7106.  
  7107.       IF does not change $ERRORLEVEL.  The decision-making logic is built into
  7108.       the command.
  7109.  
  7110.      SEE ALSO
  7111.  
  7112.       WHILE/ENDWHILE
  7113.  
  7114.      EXAMPLE 1
  7115.       
  7116.       MENUDEFINE "~Yes" "~No"
  7117.       MENUBOXV "DELETING SOMEFILE.TXT" "Are you sure you want to do this?"
  7118.  
  7119.        ;MENUBOXV sets $ERRORLEVEL according to what the user selected.
  7120.        ; If $ERRORLEVEL = 1, the user selected "Yes" (menu item 1).  See the
  7121.        ; MENUBOXV summary for details.
  7122.  
  7123.       IF $ERRORLEVEL = 1 DELETE "SOMEFILE.TXT"
  7124.  
  7125.       variable Dog1 "DOG"
  7126.  
  7127.  
  7128.  
  7129.  
  7130.      Intellicomm v2.01               SCRIPT.DOC                            110
  7131.      
  7132.      
  7133.  
  7134.       variable Dog2 "Dog"
  7135.  
  7136.       strupper Dog2   ;convert "Dog" to "DOG" (all uppercase)
  7137.  
  7138.       IF Dog1 = Dog2 print "Dog1 and Dog2 are both the same."
  7139.  
  7140.        ;without the strupper to convert "Dog" (what Dog2 is initially
  7141.        ;assigned) to "DOG", the above would NOT be printed.
  7142.        
  7143.       assign Dog2 "CAT"  ;put the word CAT in 'Dog2'
  7144.  
  7145.        ;With "CAT" in Dog2, Dog1 is now GREATER THAN (>) Dog2
  7146.  
  7147.       IF Dog1 < Dog2  print "Would this be printed?"
  7148.  
  7149.        ;above, the print is ignored, since Dog1 is GREATER THAN (>)
  7150.        ;Dog2, not LESS THAN (<) Dog2
  7151.  
  7152.      EXAMPLE 2
  7153.  
  7154.       variable number    ;define a variable called 'number'
  7155.  
  7156.       printnc "Enter a number from 1 to 10: "
  7157.       gets number 2      ;2 is the max characters to get
  7158.  
  7159.       IF number <= 5 print "The number is less than or equal to 5."
  7160.       IF number > 5 print "The number is greater than 5."
  7161.       IF number = 10 print "The number is 10."
  7162.       IF number > 1 IF number < 10 print "The number is between 1 and 10."
  7163.  
  7164.         ;Example of 'nested' IFs
  7165.  
  7166.       IF number < 5 IF number = 1
  7167.                      print "The number is 1."
  7168.                     ELSE
  7169.                      printnc "The number is less than five and ... "
  7170.                      IF number = 2 print "The number is 2."
  7171.                      IF number = 3
  7172.                       print "The number is 3."
  7173.                      ELSE
  7174.                       print "The number is 4."
  7175.                      ENDIF
  7176.                     ENDIF
  7177.  
  7178.      EXAMPLE 3
  7179.       
  7180.       variable attempts  ;define variable 'attempts' (set to 0 automatically)
  7181.       variable success   ;define variable 'success'   ""             ""
  7182.  
  7183.       when "Name?"     send "John Smith"
  7184.       when "password?" IF attempts <= 3   ;if less than or equal to 3
  7185.                         send "mypassword" 
  7186.                         inc attempts      ;INCrement; attempts = attempts + 1
  7187.                        ELSE
  7188.  
  7189.  
  7190.  
  7191.  
  7192.      Intellicomm v2.01               SCRIPT.DOC                            111
  7193.      
  7194.      
  7195.  
  7196.                         stamp "Too many password failures."
  7197.                         goto LOGON_ERROR
  7198.                        ENDIF
  7199.       when "More?"     send "N"
  7200.       waitfor "Main Menu:" 120 LOGON_ERROR
  7201.  
  7202.       assign success 1      ;variable 'success' will be 1 if we found the
  7203.                             ; Main Menu: prompt, or will be 0 if we jumped
  7204.                             ; to LOGON_ERROR
  7205.  
  7206.      LOGON_ERROR:
  7207.       
  7208.       IF success = 1        ;if variable 'success' is equal to 1
  7209.        alarm
  7210.       ELSE
  7211.        stamp "Logon unsuccessful."
  7212.        hangup
  7213.       ENDIF
  7214.  
  7215.       return
  7216.  
  7217.      INC______________________________________________________________________
  7218.  
  7219.      SUMMARY
  7220.  
  7221.       INC vNUM
  7222.  
  7223.      DESCRIPTION
  7224.  
  7225.       Adds 1 to the contents of the variable vNUM (vNUM = vNUM + 1).
  7226.  
  7227.      SEE ALSO
  7228.  
  7229.       ADD, DEC
  7230.  
  7231.      EXAMPLE
  7232.  
  7233.       variable x 10   ;define 'x' and assign 10 to it
  7234.       inc x           ;increment the contents of 'x'
  7235.       print x         ;prints 11
  7236.  
  7237.  
  7238.      INITMODEM________________________________________________________________
  7239.  
  7240.      SUMMARY
  7241.  
  7242.       INITMODEM
  7243.  
  7244.      DESCRIPTION
  7245.  
  7246.       Displays a message to the user, flushes the send/transmit buffers
  7247.       (RXFLUSH, TXFLUSH) sends the main setup "Initialize Modem" string to the
  7248.       modem (*minit variable), then waits for 1.5 seconds for the COM port DCD
  7249.       (carrier detect) signal to return to normal.  Some modems fluctuate the
  7250.  
  7251.  
  7252.  
  7253.  
  7254.      Intellicomm v2.01               SCRIPT.DOC                            112
  7255.      
  7256.      
  7257.  
  7258.       COM port online/offline status after an ATZ (reset) command, which is
  7259.       often used in modem init strings... and this can cause Intellicomm to
  7260.       think that a connection was established then lost.  Thus, INITMODEM
  7261.       waits for the modem to settle down before returning to Intellicomm.
  7262.  
  7263.       Note that your modem must be in "command state" or it will simply send
  7264.       the Initialize Modem string over the telephone line (to the BBS) if
  7265.       you're already online.  You can activate command state on most modems by
  7266.       sending three plus signs and waiting for a second or two.  See the
  7267.       example below for more details.
  7268.  
  7269.      ERRORLEVEL
  7270.  
  7271.      SEE ALSO
  7272.  
  7273.      EXAMPLE
  7274.  
  7275.        if $carrier = 0   ;offline?  No problem
  7276.         INITMODEM
  7277.        else
  7278.          ;This may or may not work... it depends on the modem.  It's
  7279.          ; provided more for demonstration purposes than anything.  It
  7280.          ; really shouldn't be necessary to re-initialize the modem while
  7281.          ; online.
  7282.         send "+++~"      ;put modem into command state
  7283.         INITMODEM        ;send the init string
  7284.         send "ATO"       ;return to online state (exit command state)
  7285.        endif
  7286.  
  7287.      INKEY____________________________________________________________________
  7288.      INKEYT___________________________________________________________________
  7289.      INKEYW___________________________________________________________________
  7290.  
  7291.      SUMMARY
  7292.  
  7293.       INKEY vKEYCODE
  7294.       INKEYW vKEYCODE
  7295.       INKEYT vKEYCODE nTIMEOUT
  7296.  
  7297.      DESCRIPTION
  7298.  
  7299.       These commands get a single key stroke from the keyboard and store its
  7300.       code (see Keyboard Codes Appendix) in vKEYCODE.
  7301.  
  7302.       IMPORTANT NOTE:  If you plan to use any of the above commands, you must
  7303.       first set $KEY_CHECK to 0 (shut off regular terminal mode key checks),
  7304.       or the script processor will eat most of the keystrokes before INKEY/W/T
  7305.       gets to them.  This is more important with INKEY than it is for INKEYW
  7306.       or INKEYT, since INKEY doesn't WAIT for a keypress: it just makes a
  7307.       quick check of the keystroke buffer.  Example:
  7308.  
  7309.        variable key
  7310.  
  7311.        assign $KEY_CHECK 0       ;shut off regular keyboard checking
  7312.  
  7313.  
  7314.  
  7315.  
  7316.      Intellicomm v2.01               SCRIPT.DOC                            113
  7317.      
  7318.      
  7319.  
  7320.        while 1
  7321.         INKEY key                ;this now gets EVERY keystroke
  7322.         if key = "^[" break      ;[Esc] pressed?   
  7323.        endwhile
  7324.        assign $KEY_CHECK 1       ;always turn it back on when you're done
  7325.  
  7326.       Note that the key needn't actually be physically pressed at the time
  7327.       that INKEY is called ...  IBM PC's (XT/AT/386/486,etc) buffer keystrokes
  7328.       in internal memory locations called the "keyboard buffer" when the user
  7329.       actually presses a key (where the keycode is saved even after the key is
  7330.       released), and INKEY/INKEYW/INKEYT simply check the keyboard buffer.  So
  7331.       you needn't worry about "timing" your use of INKEY/INKEYW/INKEYT with
  7332.       the user's actual key presses.  On the other hand, if you don't WANT the
  7333.       buffered keystrokes (there's no way to tell how old they are), call
  7334.       KBFLUSH to flush the keyboard buffer, just after you ask for input:
  7335.  
  7336.        print "Press a key..."
  7337.        KBFLUSH                 ;ensures no "old" keystrokes take effect
  7338.        INKEYW key
  7339.  
  7340.       INKEY quickly checks the keyboard buffer for any pressed keys.  If a new
  7341.       keycode is waiting, its value is stored in vKEYCODE.  Otherwise 0 (zero)
  7342.       is stored in vKEYCODE.  You'll use this variation when you want to check
  7343.       for keys WHILE doing something else (displaying information on the
  7344.       screen, etc) at the same time, as illustrated just above in the WHILE
  7345.       loop.
  7346.  
  7347.       INKEYW waits for a key press (if no keys are waiting in the keyboard
  7348.       buffer when it's called).  Your script does not continue until the user
  7349.       has actually pressed a key, at which point the key pressed will be
  7350.       stored in vKEYCODE, and the script will continue.
  7351.  
  7352.       INKEYT is an INKEYW with a timeout (specified in tenths of a second). 
  7353.       It waits for nTIMEOUT tenths of a second for a key press.  If a key is
  7354.       pressed (or is waiting in the keyboard buffer when INKEYT is called), it
  7355.       immediately stores the keycode in vKEYCODE and returns.  If no key is
  7356.       pressed within nTIMEOUT tenths of a second, INKEYT returns (your script
  7357.       continues execution) and vKEYCODE will be 0 (zero).
  7358.  
  7359.       Please see the KEYBOARD CODES appendix for a list of all keyboard codes.
  7360.  
  7361.      ERRORLEVEL
  7362.  
  7363.       None of these commands set $ERRORLEVEL.  You can get all the information
  7364.       you need by checking the vKEYCODE variable you specify.  For a list of
  7365.       key codes, see KEYBOARD CODES in the online help and/or SCRIPT.DOC.
  7366.  
  7367.      SEE ALSO
  7368.  
  7369.       BOXGETS, GETS, $KEY_ALTQ, $KEY_CHECK
  7370.  
  7371.      EXAMPLE
  7372.  
  7373.       variable keycode     ;always need a variable to store codes in
  7374.  
  7375.  
  7376.  
  7377.  
  7378.      Intellicomm v2.01               SCRIPT.DOC                            114
  7379.      
  7380.      
  7381.  
  7382.       printnc "Press a key, or [Esc] to abort: "
  7383.       INKEYW keycode
  7384.       if keycode = "^[" exit
  7385.  
  7386.       printnc "Press a key: "
  7387.       INKEYT keycode 100   ;ends the pause after 10 seconds if no key pressed
  7388.  
  7389.         ;This bit below updates an on-screen clock where [Alt-Z] for Menu is
  7390.         ; usually displayed on the status line, while also processing user
  7391.         ; keystrokes.
  7392.  
  7393.       variable cur_sec
  7394.       variable last_sec -1
  7395.  
  7396.         ;first erase "Alt-Z for Menu" on the status line (bottom screen line)
  7397.       scroll 66 $SCRN_HEIGHT 80 $SCRN_HEIGHT 0 $STAT_COLOR
  7398.       
  7399.       while 1              ;endless loop (until BREAK)
  7400.        INKEY keycode       ;keep going if nothing there
  7401.        if keycode = "^[" break
  7402.  
  7403.         ;we only want to update the clock once per second, or it will flicker
  7404.        substr cur_sec $TIME 7 1    ;HH:MM:SS .. gets the last 'S' (second)
  7405.      char
  7406.        if cur_sec = last_sec continue
  7407.        assign last_sec cur_sec
  7408.        printraw 69 $SCRN_HEIGHT $STAT_COLOR $TIME
  7409.       endwhile
  7410.  
  7411.       assign $STAT_ON 0    ;re-draw the original status line
  7412.       assign $STAT_ON 1
  7413.  
  7414.      KBFLUSH__________________________________________________________________
  7415.  
  7416.      SUMMARY
  7417.  
  7418.       KBFLUSH
  7419.  
  7420.      DESCRIPTION
  7421.  
  7422.       When the user presses keys on the keyboard, the computer stores the key
  7423.       code(s) in the "keyboard buffer".  The keys will sit in this buffer
  7424.       until Intellicomm or your script actually gets it/them one by one with
  7425.       INKEY, INKEYW, INKEYT, or a menu function (MENUBAR, MENUBOXH, MENUBOXV),
  7426.       or GETS, BOXGETS (though GETS/BOXGETS automatically call KBFLUSH on
  7427.       entry).  If there's a critical error message or the like you must
  7428.       display to the user though, and you want to ensure that some previous
  7429.       keystroke doesn't bypass the message, you can call KBFLUSH to flush any
  7430.       existing keystrokes from the keystroke buffer.  Key strokes wait in the
  7431.       keyboard buffer INDEFINITELY, until you call KBFLUSH or one of the
  7432.       INKEY.. / or MENU.. functions.
  7433.  
  7434.      SEE ALSO
  7435.  
  7436.  
  7437.  
  7438.  
  7439.      Intellicomm v2.01               SCRIPT.DOC                            115
  7440.      
  7441.      
  7442.  
  7443.       INKEY, INKEYT, INKEYW
  7444.  
  7445.      EXAMPLE
  7446.  
  7447.       printnc "Are you sure? "
  7448.       menudefine "~Yes" "~No"
  7449.       KBFLUSH
  7450.       menubar
  7451.  
  7452.      LIST_____________________________________________________________________
  7453.  
  7454.      SUMMARY
  7455.  
  7456.       LIST sFILENAME [nLINENUM]
  7457.  
  7458.      DESCRIPTION
  7459.  
  7460.       Enters Icom's internal File Viewer, or the external viewer defined by
  7461.       the user (main setup/Filenames and Paths screen, main setup variable
  7462.       *flister).
  7463.  
  7464.       sFILENAME is the file to view ([D:][\PATH\]FILENAME[.EXT] a filename
  7465.       with optional drive, path and extension).
  7466.  
  7467.       nLINENUM is only valid when *flister is blank (no external viewer), and
  7468.       it specifies an optional line number to position to after loading
  7469.       sFILENAME.
  7470.  
  7471.       NOTE: If you want to ensure use of Icom's internal File Viewer, simply
  7472.       save the *flister main setup variable, clear it, then call LIST. 
  7473.       Example:
  7474.  
  7475.       variable filename $HOME_DIR "SCRTUTOR.DOC"
  7476.       variable oldlister *flister ;save external viewer (if any)
  7477.       
  7478.       assign *flister ""          ;clear external viewer
  7479.       LIST filename 100           ;list C:\ICOM\SCR\SCRTUTOR.DOC position to
  7480.                                   ; line 100
  7481.       assign *flister oldflister  ;restore original external editor
  7482.  
  7483.       This should only be done when you must seek to a specific line number in
  7484.       a file.  You should otherwise let the user view files in his preferred
  7485.       external file viewer.
  7486.  
  7487.      SEE ALSO
  7488.  
  7489.       EDIT
  7490.  
  7491.      EXAMPLE
  7492.  
  7493.       variable filename $HOME_DIR "SCRIPT.DOC"
  7494.       
  7495.       pause "Press a key to view SCRIPT.DOC..."
  7496.       LIST filename
  7497.  
  7498.  
  7499.  
  7500.  
  7501.      Intellicomm v2.01               SCRIPT.DOC                            116
  7502.      
  7503.      
  7504.  
  7505.      LOADBIF__________________________________________________________________
  7506.  
  7507.      SUMMARY
  7508.  
  7509.       LOADBIF sBIFNAME
  7510.  
  7511.      DESCRIPTION
  7512.  
  7513.       Loads the BBS Information File (.BIF) sBIFNAME into memory.  Neither the
  7514.       .BIF extension nor the C:\ICOM\BIF directory should be specified: just
  7515.       the BIF filename.
  7516.  
  7517.       BIFs are completely useless on-disk.  The only way they can be used is
  7518.       to load them into memory.  Icom loads BIFs into memory on its own when
  7519.       dialing, after connecting to a BBS, when importing new files lists, and
  7520.       for various other purposes.  You can do the same from your scripts by
  7521.       using LOADBIF and the various BIF Variables outlined in the BIF
  7522.       VARIABLES Appendix of this manual.
  7523.  
  7524.      ERRORLEVEL
  7525.  
  7526.       0  sBIFNAME is loaded.
  7527.       1  Unable to load sBIFNAME (file not found).
  7528.  
  7529.      SEE ALSO
  7530.  
  7531.       SAVEBIF
  7532.  
  7533.      EXAMPLE
  7534.  
  7535.       LOADBIF "ICOM"  ;load the BIF for the Icom Online Service
  7536.  
  7537.      LOADINI__________________________________________________________________
  7538.  
  7539.      SUMMARY
  7540.  
  7541.       LOADINI sININAME
  7542.  
  7543.      DESCRIPTION
  7544.  
  7545.       Loads the Main Initialization File (.INI) sININAME into memory.  Neither
  7546.       the .INI extension nor the C:\ICOM directory should be specified: just
  7547.       the INI filename.
  7548.  
  7549.       INI files are completely useless on-disk.  The only way they can be used
  7550.       is to load them into memory.  Icom loads ICOM.INI (the default main
  7551.       setup file) into memory on its own at program startup.  You can later
  7552.       load other main setup files from your scripts by using LOADINI and the
  7553.       various Main Setup Variables outlined in the MAIN SETUP VARIABLES
  7554.       Appendix of this manual.
  7555.  
  7556.      ERRORLEVEL
  7557.  
  7558.       0  sININAME is loaded.
  7559.  
  7560.  
  7561.  
  7562.  
  7563.      Intellicomm v2.01               SCRIPT.DOC                            117
  7564.      
  7565.      
  7566.  
  7567.       1  Unable to load sININAME (file not found normally).
  7568.  
  7569.      SEE ALSO
  7570.  
  7571.       SAVEINI
  7572.  
  7573.      EXAMPLE
  7574.  
  7575.       LOADINI "CUSTOM"  ;load the CUSTOM.INI file settings
  7576.  
  7577.      LOCATEFILE_______________________________________________________________
  7578.  
  7579.      SUMMARY
  7580.  
  7581.       LOCATEFILE vBUFFER sFILESPEC ...
  7582.  
  7583.      DESCRIPTION
  7584.  
  7585.       LOCATEFILE searches for sFILESPEC.  If an explicit D:\PATH is specified
  7586.       in sFILESPEC, only the specified directory is searched.  If no directory
  7587.       is specified, LOCATEFILE searches all directories on the Upload PATH,
  7588.       the Download Directory, and (if the Main Setup variable *pathsch is non-
  7589.       zero) all directories on the DOS PATH.  If the file is found, its full
  7590.       D:\PATH\FILENAME.EXT is stored in variable vBUFFER.
  7591.  
  7592.       sFILESPEC specifies the file to search for.  DOS wildcard characters *
  7593.       and ? are accepted, and, as mentioned above, you may specify an optional
  7594.       D:\PATH to search in a specific directory.
  7595.  
  7596.       NOTE: LOCATEFILE does not locate directories or hidden files (it's meant
  7597.       to be used to locate files for uploading, and neither directories nor
  7598.       hidden files can be uploaded).  Use FINDFIRST to locate these.
  7599.  
  7600.      ERRORLEVEL
  7601.  
  7602.       0  sFILESPEC was found and the full D:\PATH\FILENAME.EXT has been stored
  7603.          in vBUFFER.
  7604.       1  sFILESPEC was not found.  Try using DISKFIND if appropriate.
  7605.  
  7606.      SEE ALSO
  7607.  
  7608.       EXIST, FINDFIRST, DISKFIND
  7609.  
  7610.      EXAMPLE
  7611.  
  7612.       variable file
  7613.  
  7614.       LOCATEFILE file "ICOM201A.ZIP"
  7615.       if $errorlevel = 0 upload "Z" file
  7616.  
  7617.      LOG______________________________________________________________________
  7618.  
  7619.      SUMMARY
  7620.  
  7621.  
  7622.  
  7623.  
  7624.      Intellicomm v2.01               SCRIPT.DOC                            118
  7625.      
  7626.      
  7627.  
  7628.       LOG [sLOGNAME]
  7629.  
  7630.      DESCRIPTION
  7631.  
  7632.       Opens the Usage Log.  If sLOGNAME is omitted, the default Usage Log
  7633.       filename (\ICOM\CAP\ICOM.USE, or the filename defined on the main setup
  7634.       Filenames and Paths screen) is assumed.  If the drive, path or extension
  7635.       is omitted in sLOGNAME the D:\PATH .EXT of the last Usage Log is
  7636.       assumed.
  7637.  
  7638.      SEE ALSO
  7639.  
  7640.       LOGCLOSE, STAMP
  7641.  
  7642.      EXAMPLE
  7643.  
  7644.       LOG "TEMP"    ;open a temporary usage log
  7645.  
  7646.  
  7647.      LOGCLOSE_________________________________________________________________
  7648.  
  7649.      SUMMARY
  7650.  
  7651.       LOGCLOSE
  7652.  
  7653.      DESCRIPTION
  7654.  
  7655.       Closes the Usage Log.
  7656.  
  7657.      SEE ALSO
  7658.  
  7659.       LOG, STAMP
  7660.  
  7661.      MENUBAR__________________________________________________________________
  7662.  
  7663.      SUMMARY
  7664.  
  7665.       MENUBAR nX nY [nSTART]
  7666.  
  7667.      DESCRIPTION
  7668.  
  7669.       Activates the last menu defined with MENUDEFINE in 'bar' format, at
  7670.       screen position nX (column, left to right), nY (row, top to bottom). 
  7671.       Menu items run horizontally from screen coordinates nX, nY, and no box
  7672.       is displayed around the menu.  If help is attached to a given menu item
  7673.       (with MENUHLP), its help text is displayed immediately under the first
  7674.       menu item when it is hilighted (as in the Icom Job Directory, BBS
  7675.       Directory bottom menus).
  7676.  
  7677.       If the optional nSTART parameter is specified, the current menu position
  7678.       (hilight) will be set to menu item # nSTART (1st menu option being item
  7679.       1, 2nd being item 2, etc) when the menu is first displayed.  I.e. this
  7680.       is the 'default' menu option.
  7681.  
  7682.  
  7683.  
  7684.  
  7685.      Intellicomm v2.01               SCRIPT.DOC                            119
  7686.      
  7687.      
  7688.  
  7689.      ERRORLEVEL
  7690.  
  7691.       MENUBAR does not set $ERRORLEVEL.  A separate variable called
  7692.       $MENUSELECTION is instead used to hold the last menu selection,
  7693.       undisturbed, from one menu use to the next.  After MENUBAR finishes
  7694.       $MENUSELECTION will be set to one of the following values:
  7695.  
  7696.       0  = [Esc] or right mouse button pressed (nothing selected).
  7697.       1+ = If $MENUSELECTION is 1 or greater, the user selected the
  7698.            corresponding menu item.  If set to 1, the user selected the first
  7699.            menu option.  Hidden or disabled menu items (see MENUITEMSTAT)
  7700.            still count as valid menu items.
  7701.  
  7702.      SEE ALSO
  7703.  
  7704.       MENUBOXH, MENUBOXV, MENUDEFINE, MENUHLP, MENUITEMSTAT, $MENUSELECTION
  7705.  
  7706.      EXAMPLE
  7707.  
  7708.       Please see SCRDEMO.SCR, included with Intellicomm, for several working
  7709.       examples of menu usage.
  7710.  
  7711.      MENUBOXH_________________________________________________________________
  7712.  
  7713.      SUMMARY
  7714.  
  7715.       MENUBOXH [sTITLE] [sHELPLINE] [nSTART]
  7716.  
  7717.      DESCRIPTION
  7718.  
  7719.       A picture is worth a thousand words.  MENUBOXH gives you the following
  7720.       (using graphics characters instead of +=), where "Item 1  Item2  Item3
  7721.       ..." is the last menu defined with the MENUDEFINE command:
  7722.  
  7723.                          +=| sTITLE |====================+
  7724.                          |                               |
  7725.                          |           sHELPLINE           |
  7726.                          |                               |
  7727.                          |  Item 1  Item 2  Item 3  ...  |
  7728.                          |                               |
  7729.                          +===============================+
  7730.  
  7731.       The box is displayed centered on the screen.  If the optional nSTART
  7732.       parameter is specified, the current menu position (hilight) will be set
  7733.       to menu item # nSTART (1st menu option being item 1, 2nd being item 2,
  7734.       etc) when the menu is first displayed.  I.e. nSTART is the 'default'
  7735.       menu option offered to the user.  If sTITLE or sHELPLINE is longer than
  7736.       the combined length of the menu items, the box will be adjusted
  7737.       accordingly.  If sHELPLINE is not specified the menu appears as follows:
  7738.  
  7739.                          +=| sTITLE |====================+
  7740.                          |                               |
  7741.                          |  Item 1  Item 2  Item 3  ...  |
  7742.                          |                               |
  7743.  
  7744.  
  7745.  
  7746.  
  7747.                          Intellicomm v2.01SCRIPT.DOC                       120
  7748.      
  7749.      
  7750.  
  7751.                          +===============================+
  7752.  
  7753.       You can also display sHELPLINE and the menu items all on the same line
  7754.       by using a TAB character as the first character in the sHELPLINE text. 
  7755.       Example (^I is a TAB):
  7756.  
  7757.         MENUDEFINE "~Yes" "~No"
  7758.         MENUBOXH "Title" "^IContinue?"
  7759.  
  7760.       This would give you the following:
  7761.  
  7762.                               +=| Title |============+
  7763.                               |                      |
  7764.                               |  Continue?  Yes  No  |
  7765.                               |                      |
  7766.                               +======================+
  7767.  
  7768.       It is UP TO YOU to ensure that the menu can be displayed properly.  If
  7769.       you define too many menu items to fit on the screen, or your help
  7770.       line/title is too long, the menu will be a mess.
  7771.  
  7772.      ERRORLEVEL
  7773.  
  7774.       MENUBOXH does not set $ERRORLEVEL.  A separate variable called
  7775.       $MENUSELECTION is instead used to hold the last menu selection,
  7776.       undisturbed, from one menu use to the next.  After MENUBOXH finishes
  7777.       $MENUSELECTION will be set to one of the following values:
  7778.  
  7779.       0   [Esc] or right mouse button pressed (nothing selected).
  7780.       1+  If $MENUSELECTION is 1 or greater, the user selected the
  7781.           corresponding menu item.  If set to 1, the user selected the first
  7782.           menu option, if 2 the second option was selected and so forth. 
  7783.           Hidden or disabled menu items (see MENUITEMSTAT) still count as
  7784.           valid menu items.
  7785.  
  7786.      SEE ALSO
  7787.  
  7788.       MENUBAR, MENUBOXV, MENUDEFINE, MENUHLP, MENUITEMSTAT, $MENUSELECTION
  7789.  
  7790.      EXAMPLE
  7791.  
  7792.       Please see SCRDEMO.SCR, included with Intellicomm, for several working
  7793.       examples of menu usage.
  7794.  
  7795.      MENUBOXV_________________________________________________________________
  7796.  
  7797.      SUMMARY
  7798.  
  7799.       MENUBOXV [sTITLE] [sHELPLINE] [nSTART]
  7800.  
  7801.      DESCRIPTION
  7802.  
  7803.       Displays the last menu defined with MENUDEFINE in 'vertical box' menu
  7804.       format, as follows:
  7805.  
  7806.  
  7807.  
  7808.  
  7809.                                   Intellicomm v2.01SCRIPT.DOC              121
  7810.      
  7811.      
  7812.  
  7813.                                   +=| sTITLE |==+
  7814.                                   |             |
  7815.                                   |  sHELPLINE  |
  7816.                                   |             |
  7817.                                   |   Item 1    |
  7818.                                   |   Item 2    |
  7819.                                   |   Item 3    |
  7820.                                   +=============+
  7821.  
  7822.       The box size is adjusted to fit the longest item, whether sTITLE,
  7823.       sHELPLINE, or one of the menu items is the longest.  The nSTART
  7824.       parameter is the optional menu item to hilight at menu startup (1 =
  7825.       hilight menu item 1, 2 = hilight menu item 2, etc).  If sHELPLINE is
  7826.       omitted, the menu is displayed as follows:
  7827.  
  7828.                                   +=| sTITLE |==+
  7829.                                   |             |
  7830.                                   |   Item 1    |
  7831.                                   |   Item 2    |
  7832.                                   |   Item 3    |
  7833.                                   +=============+
  7834.  
  7835.       When you plan to use MENUBOXV, you can also use menu "lines" in the
  7836.       menus you define.  Example:
  7837.  
  7838.        MENUDEFINE "Item ~1" "Item ~2" "-" "Item ~3" "Item ~4"
  7839.        MENUBOXV "
  7840.  
  7841.       The commands above would produce the following menu:
  7842.  
  7843.                                    +=| Title |=+
  7844.                                    |           |
  7845.                                    |  Item 1   |
  7846.                                    |  Item 2   |
  7847.                                    |-----------|
  7848.                                    |  Item 3   |
  7849.                                    |  Item 4   |
  7850.                                    +===========+
  7851.       
  7852.      ERRORLEVEL
  7853.  
  7854.       MENUBOXV does not set $ERRORLEVEL.  A separate variable called
  7855.       $MENUSELECTION is instead used to hold the last menu selection,
  7856.       undisturbed, from one menu use to the next.  After MENUBOXV finishes
  7857.       $MENUSELECTION will be set to one of the following values:
  7858.  
  7859.       0  = [Esc] or right mouse button pressed (nothing selected).
  7860.       1+ = If $MENUSELECTION is 1 or greater, the user selected the
  7861.            corresponding menu item.  If set to 1, the user selected the first
  7862.            menu option.  Hidden or disabled menu items (see MENUITEMSTAT)
  7863.            still count as valid menu items.  Menu lines do not count as menu
  7864.            items.
  7865.  
  7866.      SEE ALSO
  7867.  
  7868.  
  7869.  
  7870.  
  7871.      Intellicomm v2.01               SCRIPT.DOC                            122
  7872.      
  7873.      
  7874.  
  7875.       MENUBAR, MENUBOXH, MENUDEFINE, MENUHLP, MENUITEMSTAT, $MENUSELECTION
  7876.  
  7877.      EXAMPLE
  7878.  
  7879.       Please see SCRDEMO.SCR, included with Intellicomm, for several working
  7880.       examples of menu usage.
  7881.  
  7882.      MENUDEFINE_______________________________________________________________
  7883.  
  7884.      SUMMARY
  7885.  
  7886.       MENUDEFINE ITEM1 ITEM2 [ITEM3] ...
  7887.  
  7888.      DESCRIPTION
  7889.  
  7890.       Defines a list of two or more menu options for use with MENUBAR,
  7891.       MENUBOXH (horizontal menu options in a box) and MENUBOXV (vertical menu
  7892.       options in a box).  ITEM1 is the first menu option, ITEM2 is the second
  7893.       menu option, [ITEM3] ... is the third and following menu option(s) (the
  7894.       square brackets denote an optional item and should not be used).  A
  7895.       tilde (~) may (and should) be used within each ITEMx parameter to define
  7896.       the position of the item 'hotkey' (e.g. "~Yes" "~No").  The letter
  7897.       following the tilde will be displayed in 'bold' text, and can be used to
  7898.       select the menu option, once the menu is displayed, without moving the
  7899.       hilight bar.  Use of the tilde is optional, and if you omit a tilde the
  7900.       item will not have a hotkey.  If you're not careful, you can also
  7901.       inadvertantly assign the same hotkey to two different menu options.  If
  7902.       this happens, when the user presses the hotkey, the FIRST item that uses
  7903.       that hotkey will be selected.
  7904.  
  7905.       When using the MENUBOXH command (menu items are stacked on top of one
  7906.       another in a box) you can also use a single hypen as a menu option ("-")
  7907.       to specify a box divider line as you see on many of Icom's vertical box
  7908.       menus (e.g. MENUDEFINE "Item ~1" "-" "Item ~2").
  7909.  
  7910.       NOTE: No limits are enforced as to the number of options you can define
  7911.       with MENUDEFINE, but the screen size (and the type of menu you choose to
  7912.       use) may cause your menu to malfunction if you get out of hand with
  7913.       MENUDEFINE and define too many options.  Experience (trial and error) is
  7914.       the only reliable way to find the limits.  If you specify EGA/VGA
  7915.       extended line video modes (42/50 lines) in the Icom main setup, you can
  7916.       fit more menu options in a MENUBOXH (horizontal box) than you could on a
  7917.       25-line display.  Be sure to take this into account if you plan to
  7918.       distribute your scripts to others who may not have an EGA/VGA display.
  7919.       It's best to test your menus in 25-line video mode before distribution.
  7920.  
  7921.      SEE ALSO
  7922.       
  7923.       MENUBAR, MENUBOXH, MENUBOXV, MENUHLP, MENUITEMSTAT, $MENUSELECTION
  7924.  
  7925.      EXAMPLE
  7926.  
  7927.       MENUDEFINE "~Sure, no problem" "~No Thanks"
  7928.  
  7929.  
  7930.  
  7931.  
  7932.      Intellicomm v2.01               SCRIPT.DOC                            123
  7933.      
  7934.      
  7935.  
  7936.       if $DL_PROTOCOL = "Z" goto start  ;if the D/L protocol is Zmodem
  7937.       boxmenuh "Wrong Protocol!" "Okay to use Zmodem?"
  7938.       if $ERRORLEVEL <> 1 goto done     ;the user didn't select "Sure"
  7939.       assign $DL_PROTOCOL "Z"  ;change the D/L protocol to Zmodem
  7940.      start:
  7941.        ;main body of script here
  7942.  
  7943.      done:
  7944.       return      ;exit the script or subroutine
  7945.  
  7946.  
  7947.      MENUHLP__________________________________________________________________
  7948.  
  7949.      SUMMARY
  7950.  
  7951.       MENUHLP nMENUITEM nHELPTEXT
  7952.  
  7953.      DESCRIPTION
  7954.  
  7955.       Attaches the text nHELPTEXT to menu item number nMENUITEM.  A menu must
  7956.       be defined with MENUDEFINE before using MENUHLP.
  7957.  
  7958.       On bar menus (MENUBAR, MENUBOXH) the nHELPTEXT is displayed under the
  7959.       bar menu as each item is hilighted, similar to Intellicomm's Job
  7960.       Directory bottom bar menu.  On vertical menus (MENUBOXV) nHELPTEXT is
  7961.       displayed on the bottom screen line as each item is hilighted, as
  7962.       demonstrated in the SCRDEMO.SCR main menu.
  7963.  
  7964.      ERRORLEVEL
  7965.  
  7966.       None.  If nMENUITEM is invalid the script aborts and the error is
  7967.       pointed out to you.
  7968.  
  7969.      SEE ALSO
  7970.  
  7971.       MENUDEFINE, MENUITEMSTAT
  7972.  
  7973.      EXAMPLE
  7974.  
  7975.       menudefine "Item ~1" "Item ~2" "Item ~3"
  7976.       MENUHLP 1 "Item 1 description"
  7977.       MENUHLP 2 "Item 2 description"
  7978.       MENUHLP 3 "Item 3 description"
  7979.       menubar
  7980.  
  7981.      MENUITEMSTAT_____________________________________________________________
  7982.  
  7983.      SUMMARY
  7984.  
  7985.       MENUITEMSTAT nMENUITEM nSTATUS
  7986.  
  7987.      DESCRIPTION
  7988.  
  7989.       Sets or clears the disabled and/or hidden status of menu item nMENUITEM. 
  7990.  
  7991.  
  7992.  
  7993.  
  7994.      Intellicomm v2.01               SCRIPT.DOC                            124
  7995.      
  7996.      
  7997.  
  7998.       MENUDEFINE must be used before MENUITEMSTAT.
  7999.  
  8000.       Values for nSTATUS:
  8001.  
  8002.       0  Clear hidden/disabled status of nMENUITEM
  8003.       1  Disable nMENUITEM
  8004.       2  Hide nMENUITEM
  8005.  
  8006.      ERRORLEVEL
  8007.  
  8008.       None.  If nMENUITEM is invalid the script aborts and the error is
  8009.       pointed out to you.
  8010.  
  8011.      SEE ALSO
  8012.  
  8013.       MENUDEFINE, MENUHLP
  8014.  
  8015.      EXAMPLE
  8016.  
  8017.       menudefine "Item ~1" "~Unhide Item 3" "Item ~3"
  8018.       MENUITEMSTAT 3 2       ;Hide item 3
  8019.  
  8020.      again:
  8021.       menubar
  8022.  
  8023.       if $menuselection = 2  ;'Unhide Item 3' selected?
  8024.        MENUITEMSTAT 3 0      ;Unhide item 3
  8025.        goto again            ; and redisplay the menu
  8026.       endif
  8027.  
  8028.      MKDIR____________________________________________________________________
  8029.  
  8030.      SUMMARY
  8031.  
  8032.       MKDIR sPATH
  8033.  
  8034.      DESCRIPTION
  8035.  
  8036.       Creates the directory(s) specified by sPATH (same as MKDIR from DOS). 
  8037.       You can make multiple directories with a single call to MKDIR.  For
  8038.       example, if the directory \TEST doesn't exist, the following will make
  8039.       both \TEST and \TEST\TEST1 directories:
  8040.  
  8041.       MKDIR "\TEST\TEST1"
  8042.  
  8043.      ERRORLEVEL
  8044.  
  8045.       0  sPATH was created.
  8046.       1  sPATH couldn't be created (invalid drive or path, or root directory
  8047.          full).
  8048.       4  Permission denied (directory already exists).
  8049.       5  Miscellaneous errors.  The directory wasn't created.
  8050.  
  8051.      SEE ALSO
  8052.  
  8053.  
  8054.  
  8055.  
  8056.      Intellicomm v2.01               SCRIPT.DOC                            125
  8057.      
  8058.      
  8059.  
  8060.       RMDIR
  8061.  
  8062.      EXAMPLE
  8063.  
  8064.       MKDIR "$TEMP$"  ;create a temporary directory in the current directory
  8065.  
  8066.      MSGOPEN__________________________________________________________________
  8067.  
  8068.      SUMMARY
  8069.  
  8070.       MSGOPEN sMESSAGE ...
  8071.  
  8072.      DESCRIPTION
  8073.  
  8074.       Displays sMESSAGE in a centered message box.  Call MSGCLOSE to remove
  8075.       the message box.
  8076.  
  8077.      SEE ALSO
  8078.  
  8079.       MSGCLOSE, MSGWIND
  8080.  
  8081.      EXAMPLE
  8082.  
  8083.       variable k
  8084.       MSGOPEN "Please press a key..."
  8085.       inkeyw k
  8086.       msgclose
  8087.  
  8088.      MSGCLOSE_________________________________________________________________
  8089.  
  8090.      SUMMARY
  8091.  
  8092.       MSGCLOSE
  8093.  
  8094.      DESCRIPTION
  8095.  
  8096.       Closes a message window opened with MSGOPEN (restores the previous
  8097.       screen contents).
  8098.  
  8099.      SEE ALSO
  8100.  
  8101.       MSGOPEN, MSGWIND
  8102.  
  8103.      EXAMPLE
  8104.  
  8105.       variable k
  8106.       msgopen "Searching for SCRTUTOR.DOC..."
  8107.       diskfind "SCRTUTOR.DOC"
  8108.       MSGCLOSE
  8109.  
  8110.      MSGWIND__________________________________________________________________
  8111.  
  8112.      SUMMARY
  8113.  
  8114.  
  8115.  
  8116.  
  8117.      Intellicomm v2.01               SCRIPT.DOC                            126
  8118.      
  8119.      
  8120.  
  8121.       MSGWIND sMESSAGE ...
  8122.  
  8123.      DESCRIPTION
  8124.  
  8125.       Displays sMESSAGE in a centered box on screen, pauses for *sdelay TENTHS
  8126.       of a second, then closes the message box.  Use MSGWIND for status
  8127.       messages such as "Finished!", where it isn't imperative that the user
  8128.       see the message.
  8129.  
  8130.      SEE ALSO
  8131.  
  8132.       MSGOPEN, MSGCLOSE
  8133.  
  8134.      EXAMPLE
  8135.  
  8136.       MSGWIND "It is now: " $TIME   ;display the current time
  8137.  
  8138.      MUL______________________________________________________________________
  8139.  
  8140.      SUMMARY
  8141.  
  8142.       MUL vPRODUCT nMULTIPLICAND nMULTIPLIER
  8143.  
  8144.      DESCRIPTION
  8145.  
  8146.       Multiplies nMULTIPLICAND by nMULTIPLIER and stores the result in
  8147.       vPRODUCT.  As with any multiplication, the order of the multiplicand and
  8148.       multiplier is irrelevant:  7 x 4 = 28, as 4 x 7 = 28.
  8149.  
  8150.      SEE ALSO
  8151.  
  8152.       ADD, DIV, SUB
  8153.  
  8154.      EXAMPLE
  8155.  
  8156.       variable result
  8157.       MUL result 10 5   ;stores 10 x 5 (50) in variable 'result'
  8158.       print result
  8159.  
  8160.      NEWAREA__________________________________________________________________
  8161.  
  8162.      SUMMARY
  8163.  
  8164.       NEWAREA sAREA
  8165.  
  8166.      DESCRIPTION
  8167.  
  8168.       NEWAREA is a powerful command that can literally save you hours of
  8169.       script writing.  It uses the currently loaded BIF data to reliably
  8170.       access the BBS 'Main Menu', 'Message Menu', 'Bank Menu', or 'File Menu'
  8171.       to/from any other menu.  I.e. if you're in the File Menu and want to get
  8172.       to the Bank Menu, you needn't worry about how to exit the file menu nor
  8173.       how to access the Bank Menu, nor worry about which BBS prompts to handle
  8174.       for either task.  Icom uses the BIF information to handle the whole shot
  8175.  
  8176.  
  8177.  
  8178.  
  8179.      Intellicomm v2.01               SCRIPT.DOC                            127
  8180.      
  8181.      
  8182.  
  8183.       with a single call to NEWAREA.  You can also change BBS message/file
  8184.       areas with NEWAREA, again without worrying about how to go about it. 
  8185.       Icom uses the BIF data to make the change, and handles all the BBS
  8186.       prompts on the way.  It also makes use of Icom's error-handling routines
  8187.       (timeouts/BIF General menu exits, and it will re-try up to three times
  8188.       total if the initial area change fails).
  8189.  
  8190.       NEWAREA determines a change area request according to the sAREA
  8191.       parameter.  If sAREA is 'L', 'M', 'F', or 'B' enclosed in square
  8192.       brackets NEWAREA accesses the following BBS menu:
  8193.        
  8194.        [L]  The Logon Menu (the Main Menu A, Main Menu B prompts defined on
  8195.             BIF Logon screen).
  8196.        [M]  The 'Message Menu' defined on the BIF Message screen.  To access
  8197.             this menu, the BIF 'Access Msg. Menu' command will be sent, to
  8198.             leave it (if NEWAREA is at the Message Menu and you perform for
  8199.             example a NEWAREA [B]) the 'Leave Msg Menu' command is used. 
  8200.             NOTE: You needn't check the BIF to see whether an 'Access Msg.
  8201.             Menu' command is defined: if nothing is defined, Message functions
  8202.             can be carried out from the BBS [L]ogon (Main) Menu, and that is
  8203.             the menu NEWAREA will change to, if necessary.
  8204.        [F]  The 'File Menu' defined on the BIF Message screen.  To access this
  8205.             menu, the BIF 'Access File Menu' command will be sent, to leave it
  8206.             (if NEWAREA is at the File Menu and you perform for example a
  8207.             NEWAREA [B]) the 'Leave File Menu' command is used.
  8208.        [B]  The 'Bank Menu' defined on the BIF Message screen.  To access this
  8209.             menu, the BIF 'Access Bank Menu' command will be sent, to leave it
  8210.             (if NEWAREA is at the Bank Menu and you perform for example a
  8211.             NEWAREA [M]) the 'Leave Bank Menu' command is used.
  8212.  
  8213.       If you specify anything OTHER than a single letter enclosed in square
  8214.       brackets, NEWAREA assumes a message/file area change and will issue the
  8215.       "Area Change" command defined on the BIF File screen.
  8216.  
  8217.       NEWAREA keeps track of the current area and will not send redundant
  8218.       commands to access a menu/file area if you're already there.  Thus you
  8219.       can place calls to NEWAREA virtually anywhere in your script, just to
  8220.       make sure you're where you want to be.  If you're already there, NEWAREA
  8221.       sends no commands.  If you're at a different location, NEWAREA makes the
  8222.       change.  Of course this logic relies on the fact that you haven't
  8223.       changed areas behind NEWAREA's back.  If you use NEWAREA, you should use
  8224.       *only* NEWAREA to change BBS areas.  If you use SEND "OPEN QMAIL4" to
  8225.       access the Qmail door (Message Menu) or SEND "J 2"' to [J]oin a new
  8226.       conference, NEWAREA won't know about it and may fail the next time you
  8227.       call it.
  8228.  
  8229.       If you run your script from an automated job, and if Icom was at a main
  8230.       menu when your script was started, NEWAREA will already know which area
  8231.       of the BBS it's at (Icom keeps track of the current BBS area during
  8232.       automated jobs).  If you run your Script from the Script Manager or from
  8233.       the DOS command line, NEWAREA will first send the BIF General Menu Exit
  8234.       command (a couple of Ctrl-K's and ENTER normally) to locate its position
  8235.       on the BBS before attempting to change areas.
  8236.  
  8237.  
  8238.  
  8239.  
  8240.      Intellicomm v2.01               SCRIPT.DOC                            128
  8241.      
  8242.      
  8243.  
  8244.       NOTE: In order to perform BBS area changes, Intellicomm uses the WHEN
  8245.       slots which scripts use to track BBS prompts.  Since the script WHEN
  8246.       data and Intellicomm's own tracking routines use same memory space, any
  8247.       previously defined WHEN data is lost.  All WHENs are cleared when
  8248.       NEWAREA finishes.  I.e. do NOT use the NEWAREA command during a
  8249.       WHEN/WAITFOR, unless you use a GOTO to jump to the NEWAREA command, and
  8250.       then use another GOTO to get back above the WHENs to re-define them when
  8251.       NEWAREA finishes:
  8252.  
  8253.       redefine_whens:
  8254.        WHEN "prompt1" send "response 1"
  8255.        WHEN "prompt2" goto change_areas
  8256.        WAITFOR "prompt3" 120
  8257.        return
  8258.  
  8259.       change_areas:
  8260.        NEWAREA "[M]"         ;change to the message menu... WHENs are lost
  8261.        goto redefine_whens   ;get back up to re-define the WHEN/WAITFOR
  8262.  
  8263.       Further, if you're experienced with WHEN and know that it needn't
  8264.       actually be called immediately prior to a WAITFOR (i.e. you can execute
  8265.       the WHENs anywhere... Icom stores the data in memory and makes use if it
  8266.       the next time it runs into a WAITFOR), you'll have to take this into
  8267.       consideration if you use the NEWAREA command.  This will NOT work:
  8268.  
  8269.       WHEN "prompt 1" send "response 1"
  8270.       WHEN "prompt 2" send "response 2"
  8271.  
  8272.        ;later in the script you usually 'can' call WAITFOR and the WHENs
  8273.        ; would still be stored in memory.  But... if you use NEWAREA:
  8274.  
  8275.       NEWAREA "[L]"  ;Access the [L]ogon Menu (BBS Main menu)
  8276.  
  8277.        ;the WHENs defined above are now gone
  8278.  
  8279.       send "some command"
  8280.       WAITFOR "some menu" 120  ;simply waits... no WHENs are active
  8281.  
  8282.      ERRORLEVEL
  8283.  
  8284.       0  Area change successful.
  8285.       1  Area change unsuccessful (3 attempts failed, the connection was lost,
  8286.          etc).
  8287.       2  No BIF loaded.  You must call your script from an automated job (in
  8288.          which case the proper BIF data will already be loaded) or must use
  8289.          the LOADBIF or DIAL command to load a BIF into memory.
  8290.  
  8291.      SEE ALSO
  8292.  
  8293.       $BBS_AREA
  8294.  
  8295.      EXAMPLE
  8296.  
  8297.       NEWAREA "2"  ;Access conference 2; Sends J 2 Q on PCBoard systems
  8298.  
  8299.  
  8300.  
  8301.  
  8302.      Intellicomm v2.01               SCRIPT.DOC                            129
  8303.      
  8304.      
  8305.  
  8306.       if $ERRORLEVEL <> 0 return
  8307.       
  8308.       NEWAREA [M]  ;Access the Message Menu
  8309.       if $ERRORLEVEL <> 0 return
  8310.  
  8311.      NOTEXIST_________________________________________________________________
  8312.  
  8313.      SUMMARY
  8314.  
  8315.       NOTEXIST sFILESPEC cCOMMAND
  8316.  
  8317.      DESCRIPTION
  8318.  
  8319.       If sFILESPEC does NOT exist, cCOMMAND is executed.  If sFILESPEC does
  8320.       exist, cCOMMAND is skipped.
  8321.  
  8322.       sFILESPEC is a file specification (wildcards * and ? are accepted)
  8323.       including an optional drive and path (D:\PATH\*.BAT for example).  If
  8324.       you omit the drive (D:) the current drive ($CURDRIVE) is assumed.  If
  8325.       both the drive and path are omitted, the current path is assumed
  8326.       ($CURDIR).
  8327.  
  8328.      ERRORLEVEL
  8329.  
  8330.       No errorlevel is necessary.  Use cCOMMAND.
  8331.  
  8332.      SEE ALSO
  8333.  
  8334.       DISKFIND, EXIST, FINDFIRST, FINDNEXT
  8335.  
  8336.      EXAMPLE
  8337.  
  8338.       variable filename $HOME_DIR "POSTDOWN.BAT"
  8339.       exist filename edit filename  ;edit POSTDOWN.BAT if it exists
  8340.  
  8341.      OFFLINE__________________________________________________________________
  8342.  
  8343.      SUMMARY
  8344.  
  8345.       OFFLINE cCOMMAND
  8346.  
  8347.      DESCRIPTION
  8348.  
  8349.       If the modem is offline (not connected) cCOMMAND is executed.  If the
  8350.       modem is online (connected) cCOMMAND is skipped.
  8351.  
  8352.      SEE ALSO
  8353.  
  8354.       ONLINE, $CARRIER
  8355.  
  8356.      EXAMPLE
  8357.  
  8358.       OFFLINE exit   ;exit the script if modem is not online
  8359.  
  8360.  
  8361.  
  8362.  
  8363.      Intellicomm v2.01               SCRIPT.DOC                            130
  8364.      
  8365.      
  8366.  
  8367.      ONLINE___________________________________________________________________
  8368.  
  8369.      SUMMARY
  8370.  
  8371.       ONLINE cCOMMAND
  8372.  
  8373.      DESCRIPTION
  8374.  
  8375.       If the modem is online (connected) cCOMMAND is executed.  If the modem
  8376.       is offline (not connected) cCOMMAND is skipped.
  8377.  
  8378.      SEE ALSO
  8379.  
  8380.       ONLINE, $CARRIER
  8381.  
  8382.      EXAMPLE
  8383.  
  8384.       ONLINE exit   ;exit the script if modem is online
  8385.  
  8386.      OR_______________________________________________________________________
  8387.  
  8388.      SUMMARY
  8389.  
  8390.       OR vRESULT nNUM nBITMASK
  8391.  
  8392.      DESCRIPTION
  8393.  
  8394.       Performs a bitwise OR on nNUM using nBITMASK, and stores the result in
  8395.       vRESULT.  Unless you're a programmer, you probably will never find a use
  8396.       for OR.
  8397.  
  8398.      SEE ALSO
  8399.  
  8400.       AND, SHL, SHR, XOR
  8401.  
  8402.      EXAMPLE
  8403.  
  8404.       variable someflag 0
  8405.       OR someflag someflag 1  ;set bit 1 in variable 'someflag'
  8406.  
  8407.      PAUSE____________________________________________________________________
  8408.  
  8409.      SUMMARY
  8410.  
  8411.       PAUSE [MESSAGE] ...
  8412.  
  8413.      DESCRIPTION
  8414.  
  8415.       PAUSE displays an optional message to the user (if specified), then
  8416.       pauses script execution until the user presses a key.  If MESSAGE is
  8417.       specified it is printed at the current cursor position ($SCRN_X,
  8418.       $SCRN_Y) in the current screen color ($SCRN_COLOR).  The cursor (if on)
  8419.       will be displayed immediately following the message until the user
  8420.       presses a key.  Once a key is pressed, and if a MESSAGE was displayed,
  8421.  
  8422.  
  8423.  
  8424.  
  8425.      Intellicomm v2.01               SCRIPT.DOC                            131
  8426.      
  8427.      
  8428.  
  8429.       PAUSE prints "^M^J" (Carriage Return/Line Feed) to the screen to advance
  8430.       the cursor to the next screen line (terminating the line that MESSAGE
  8431.       was on).  And the script continues executing at the next script line (if
  8432.       any).
  8433.  
  8434.       Please also see the notes in the PRINT summary below.
  8435.  
  8436.      SEE ALSO
  8437.  
  8438.       BOXGETS, GETS, INKEY, INKEYW, INKEYT, PRINT, PRINTNC, PRINTRAW, WINDOW,
  8439.       WNDOPEN
  8440.  
  8441.      EXAMPLE
  8442.  
  8443.      PAUSE "Press a key to continue: "
  8444.  
  8445.      PRINT____________________________________________________________________
  8446.  
  8447.      SUMMARY
  8448.  
  8449.       PRINT DATA ...
  8450.  
  8451.      DESCRIPTION
  8452.  
  8453.       Displays DATA (either a number, string, or variable) on the screen in
  8454.       the current $SCRN_COLOR, at the current cursor position ($SCRN_X,
  8455.       $SCRN_Y) and follows it with a Carriage Return/Line Feed to terminate
  8456.       the line.  If DATA is too long to be displayed in the current WINDOW, it
  8457.       is either wrapped to the next screen line, or truncated (cut) at the
  8458.       current $WND_RIGHT position, depending on the setting of $SCRN_WRAP (0 =
  8459.       truncate, 1 = wrap).
  8460.  
  8461.       NOTE 1: If the capture file is currently open (see CAPTURE), data you
  8462.       display with PAUSE, PRINT, and PRINTNC is also written to the capture
  8463.       file.  To display data on the screen without capturing it, either turn
  8464.       capture off temporarily (CAPPUSH, then CAPCLOSE or CAPPAUSE, then CAPPOP
  8465.       to restore) or use the PRINTRAW command.
  8466.  
  8467.       NOTE 2: There are several characters you cannot print to the screen with
  8468.       the PRINT command.  PAUSE, PRINT, and PRINTNC perform special functions
  8469.       on certain control characters, if present in the data being printed. 
  8470.       The table below lists all these characters: the ASCII code (number) is
  8471.       first, the characters used to signify the control character in a string
  8472.       comes second (PRINT "^M" prints CR), the control character name (ESC,
  8473.       CR, etc.) is third, and a description of the Function it performs if
  8474.       printed with PAUSE, PRINT, or PRINTNC is fourth:
  8475.  
  8476.       Num Char Name                     Function
  8477.       ------------------------------------------------------------------------
  8478.       -  2    ^B  STX  Toggles 'bold' text on/off.  PRINT always starts
  8479.                        printing text in the color that $SCRN_COLOR is set to. 
  8480.                        If ^B is encountered, $SCRN_COLOR is temporarily set to
  8481.                        $BOLD_COLOR.  When another ^B is encountered (or if the
  8482.                        end of the PRINT string is reached) the previous screen
  8483.  
  8484.  
  8485.  
  8486.  
  8487.      Intellicomm v2.01               SCRIPT.DOC                            132
  8488.      
  8489.      
  8490.  
  8491.                        color is reset.  Example:  PRINT "Normal ^BBold^B
  8492.                        Normal"
  8493.                     The word "Bold" above would be printed in $BOLD_COLOR due
  8494.                     to the ^B's surrounding it.  The rest of the string would
  8495.                     be printed in $SCRN_COLOR.
  8496.        5   ^E  ENQ  Sends the ENQuiry response to the BBS (if any; defined on
  8497.                     the main setup "Terminal" screen).  You'll never want to
  8498.                     do this... it's just mentioned because that's what'll
  8499.                     happen if you try to print this character.  PRINT sends
  8500.                     characters through the terminal display, and the terminal
  8501.                     display responds to ^E ENQuiry, if found.
  8502.        7   ^G  BEL  Same as using BEEP.  If you have something important to
  8503.                     PRINT to the user, you can beep to wake him/her up.
  8504.                     Example: PRINT "^GHey, wake up!"
  8505.                     Note that if $SOUND is equal to 0 (zero), ^G characters 
  8506.                     make no sound, whether used in PAUSE, PRINT, or PRINTNC,
  8507.                     or received from the COM port.
  8508.        9   ^I  HT   Horizontal Tab moves to the next tab column.  Tab columns
  8509.                     exist every five characters from the left of the current
  8510.                     WINDOW ($WND_LEFT).  You can line up columns of data (a
  8511.                     filename, date, size, etc) on these tab columns, by using
  8512.                     tabs (^I) in your PAUSE, PRINT, PRINTNC statements.
  8513.       10   ^J  LF   Line Feed moves the cursor down one row (top to bottom),
  8514.                     keeping it in the same screen column (left to right).  If
  8515.                     the cursor is at the bottom of the current WINDOW when ^J
  8516.                     is printed, the contents of the window scrolls up one
  8517.                     line.  Use both ^M^J (CR/LF) if you want to move the
  8518.                     cursor to the beginning of the new line.  Note that PRINT
  8519.                     and PAUSE (after the key is pressed) both automatically
  8520.                     add ^M^J to the end of the data they print.  PRINTNC does
  8521.                     not.
  8522.       12   ^L  FF   Form Feed is the same as CLS (clear current WINDOW, move
  8523.                     cursor to position 1,1).
  8524.       13   ^M  CR   Carriage Return moves the cursor to screen column 1
  8525.                     (leftmost column, according to the current WINDOW, if any)
  8526.                     maintaining the current screen row.  Follow ^M with ^J
  8527.                     (Line Feed) to move to the next line.
  8528.       24   ^X  CAN  CANcel is the beginning of the Zmodem auto-download
  8529.                     sequence.  If *zauto (Zmodem auto-downloads on/off, main
  8530.                     setup variable) is non-zero, ^X will be "eaten" by PAUSE,
  8531.                     PRINT, and PRINTNC.  If *zauto is set to zero, ^X is
  8532.                     printed to the screen.
  8533.       27   ^[  ESC  Signifies the beginning of an ANSI escape code.  This
  8534.                     character (and perhaps one or more characters following
  8535.                     it, depending upon what follows) is never displayed by
  8536.                     PAUSE, PRINT or PRINTNC.
  8537.  
  8538.       To print any of the above characters to the screen directly, instead of
  8539.       having the terminal act upon the character, use the PRINTRAW command
  8540.       which writes directly to the screen without going through the terminal
  8541.       display routines.
  8542.  
  8543.      SEE ALSO
  8544.  
  8545.  
  8546.  
  8547.  
  8548.      Intellicomm v2.01               SCRIPT.DOC                            133
  8549.      
  8550.      
  8551.  
  8552.       PAUSE, PRINTNC, PRINTRAW, WINDOW, WNDOPEN
  8553.  
  8554.      EXAMPLE
  8555.  
  8556.       variable myvariable
  8557.       assign myvariable "some information"
  8558.  
  8559.       PRINT "Here is " myvariable " to read."
  8560.  
  8561.       ;Displays "Here is some information to read." (without the quotes).
  8562.  
  8563.      PRINTNC__________________________________________________________________
  8564.  
  8565.      SUMMARY
  8566.  
  8567.       PRINTNC [sDATA] ...
  8568.  
  8569.      DESCRIPTION
  8570.  
  8571.       Performs the same function as PRINT (see above), but PRINTNC does not
  8572.       add a Carriage Return/Line feed after sDATA.  I.e. you can use several
  8573.       PRINTNC commands to print data on the same screen line (though you can
  8574.       also accomplish that by specifying multiple parameters after a PRINT
  8575.       statement).  Please read the PRINT summary above for special
  8576.       considerations.
  8577.  
  8578.      SEE ALSO
  8579.  
  8580.       PAUSE, PRINT, PRINTRAW, WINDOW, WNDOPEN
  8581.  
  8582.      EXAMPLE
  8583.  
  8584.       variable keypressed
  8585.  
  8586.       ;This performs basically the same function as PAUSE, but you can
  8587.       ; check the key to see what the user pressed (you might want to cancel
  8588.       ; something if ^[ (ESC) is pressed)
  8589.  
  8590.       PRINTNC "Please press a key: "
  8591.       inkeyw keypressed
  8592.       PRINT    ;prints only ^M^J (CR/LF) to terminate the PRINTNC line above.
  8593.  
  8594.      PRINTRAW_________________________________________________________________
  8595.  
  8596.      SUMMARY
  8597.  
  8598.       PRINTRAW nX nY nCOLOR DATA ...
  8599.  
  8600.      DESCRIPTION
  8601.  
  8602.       Displays DATA (one or more constant strings/numbers or variables) on the
  8603.       video display at screen row nX, column nY (1 1 being the top left screen
  8604.       corner), in color nCOLOR.  See COLOR CODES in the online help, or in the
  8605.       Appendix of this manual for information on creating your own colors. 
  8606.  
  8607.  
  8608.  
  8609.  
  8610.      Intellicomm v2.01               SCRIPT.DOC                            134
  8611.      
  8612.      
  8613.  
  8614.       Usually you'll use one of the Icom system colors ($SCRN_COLOR,
  8615.       $BOLD_COLOR, etc) as the nCOLOR parameter.
  8616.  
  8617.       Note that PRINTRAW does not observe the current screen WINDOW nor does
  8618.       it move the screen cursor.  This allows you to print data on the status
  8619.       line (if it's on ... see $STAT_ON), or outside the current WINDOW, to
  8620.       print data in a window border opened with WNDOPEN for example.
  8621.  
  8622.       Further, you can display any ASCII character with PRINTRAW.  Several
  8623.       control characters perform functions when printed with PAUSE, PRINT or
  8624.       PRINTNC, while PRINTRAW displays all characters in their "raw" format
  8625.       (hence the name of the command).
  8626.  
  8627.       PRINTRAW is also faster than PRINT/PRINTNC, since it needn't observe the
  8628.       current WINDOW, nor perform translations of control characters.
  8629.  
  8630.      SEE ALSO
  8631.  
  8632.       BOX, PRINT, PRINTNC, SCROLL
  8633.  
  8634.      EXAMPLE
  8635.  
  8636.       ;Open a window, top corner 1,5, bottom corner 80,20
  8637.       wndopen "Sample Window" 1 5 80 20
  8638.       print "This goes inside the window, and you can't get outside with"
  8639.       print "either PAUSE, PRINT or PRINTNC."
  8640.  
  8641.       PRINTRAW 63 5 $BORDER_COLOR " In the Border! "
  8642.  
  8643.       ;Displays " In the Border! " (no quotes) at positon 63,5.  Line 5 is the
  8644.       ; top screen border position, and position 63 prints it on the right
  8645.       ; corner.  You always have to work out your screen coordinates with
  8646.       ; PRINTRAW.  It's more work than using PRINT, but you can do more with 
  8647.       ; it.
  8648.  
  8649.      PORT_____________________________________________________________________
  8650.  
  8651.      SUMMARY
  8652.  
  8653.       PORT nCOMPORT
  8654.  
  8655.      DESCRIPTION
  8656.  
  8657.       Closes the current COM port (any characters received at that port after
  8658.       it's closed will be lost) and opens a new COM port number nCOMPORT. 
  8659.       nCOMPORT must be a number from 1 through 8 (for COM1 to COM8).  If you
  8660.       use anything above COM4, the proper port address(es) and IRQ information
  8661.       must first be set up on the Icom main setup "Comm Port Setup" screen. 
  8662.       By default, all ports above COM4 point to (open) COM1.
  8663.  
  8664.       If a 16550 UART is installed, PORT also enables the 16550 FIFO buffer
  8665.       (if the *16550fl main setup variable is non-zero), and sets its receive
  8666.       and transmit triggers to *16550rx, *16550tx.  If you don't understand
  8667.       this, it's not important (though the online help topic "Optimizing
  8668.  
  8669.  
  8670.  
  8671.  
  8672.      Intellicomm v2.01               SCRIPT.DOC                            135
  8673.      
  8674.      
  8675.  
  8676.       Intellicomm" will explain it, if you're interested).  If you do
  8677.       understand it, you'll see that you can use the PORT command to change
  8678.       the 16550 receive/transmit triggers from a script, if necessary.
  8679.  
  8680.      ERRORLEVEL
  8681.  
  8682.       0  Port successfully opened.
  8683.       1  No memory for transmit/receive buffers, or unable to initialize the
  8684.          port itself.  There's not much to a COM port... you have your base
  8685.          address in the computer's memory and the IRQ line the port uses to
  8686.          send an interrupt to the processor.  Both items are dictated by the
  8687.          COM port hardware itself (i.e. see the documentation for your multi
  8688.          I/O card, or your modem docs if an internal modem).  Both the base
  8689.          port address and IRQ line can be configured, for any port from 1-8,
  8690.          on the main setup "Comm Port Settings" screen ... so if a port can't
  8691.          be opened (assuming you don't see an "Insufficient memory" message on
  8692.          the screen, which you will if there is no memory for the buffers) you
  8693.          should be able to fix the problem in the main setup.
  8694.       2  Invalid port specified.  You didn't follow the PORT command with a
  8695.          number from 1 through 8.
  8696.  
  8697.      EXAMPLE
  8698.  
  8699.       PORT 4   ;Open COM4
  8700.       send "This goes out COM4 now."
  8701.  
  8702.      REDIAL___________________________________________________________________
  8703.  
  8704.      SUMMARY
  8705.  
  8706.       REDIAL
  8707.  
  8708.      DESCRIPTION
  8709.  
  8710.       REDIAL will only be needed when you tag and dial multiple BIFs with the
  8711.       DIAL command.  Once DIAL connects to a BBS, it untags that BIF.  REDIAL
  8712.       can then be used to dial the remaining tagged BIFs (until it sets
  8713.       $ERRORLEVEL to non-zero, in which case nothing was left to dial).
  8714.  
  8715.       NOTE: Using the DIAL or REDIAL command causes any previously defined
  8716.       WHEN commands (for tracking BBS prompts) to be lost.  The dialer uses
  8717.       WHEN itself to track the modem response codes, and when it exits all
  8718.       WHENs are cleared.
  8719.  
  8720.      ERRORLEVEL
  8721.  
  8722.       0  You are now connected to the BBS/BIF specified in the $BIF_NAME
  8723.          System Variable, and that BIF has been untagged.
  8724.       1  Nothing left to dial, or user aborted.
  8725.  
  8726.      SEE ALSO
  8727.  
  8728.       DIAL
  8729.  
  8730.  
  8731.  
  8732.  
  8733.      Intellicomm v2.01               SCRIPT.DOC                            136
  8734.      
  8735.      
  8736.  
  8737.      EXAMPLE
  8738.  
  8739.      ;REDIAL is an advanced command, and here follows an advanced example. 
  8740.      ; Using the framework below, you could perform a fair equivalent to
  8741.      ; an Icom internal job dialing/logon session.  If you're faint of heart,
  8742.      ; or new to Icom scripts, skip this example.
  8743.  
  8744.      dial "!" 0               ;Tag/Dial all BBS's with ! in the BIF
  8745.      description
  8746.  
  8747.      while $errorlevel = 0    ;false if not connected
  8748.  
  8749.        ;Perform the auto-logon using the BIF information.  This can log on
  8750.        ; anywhere... as long as the BIF [L]ogon section is set up.
  8751.  
  8752.       when                              ;clear previous WHENs
  8753.       when *[L]namp sendbif "L" "namc"  ;BIF variables, name prompt and
  8754.      command
  8755.       when *[L]pasp sendbif "L" "pasc"  ;Password prompt/response
  8756.       when *[L]lanp sendbif "L" "lanc"  ;Language prompt/response
  8757.       when *[L]ecnp sendbif "L" "ecnc"  ;Confirm prompt/response
  8758.       when *[L]grap sendbif "L" "grac"  ;Graphics
  8759.       when *[L]scap sendbif "L" "scac"  ;Scan messages
  8760.       when *[L]paup sendbif "L" "pauc"  ;Pause
  8761.       when *[L]morp sendbif "L" "morc"  ;More
  8762.       when *[E]exac sendbif "E" "exap"  ;External Extra A
  8763.       when *[E]exbc sendbif "E" "exbp"  ; B
  8764.       when *[E]excc sendbif "E" "excp"  ; C
  8765.       when *[E]exdc sendbif "E" "exdp"  ; D
  8766.       waitfor *[L]mnap 120              ;wait 2 minutes max. for BBS main menu
  8767.  
  8768.       if $errorlevel = 0      ;WAITFOR worked; we're at the BBS main menu
  8769.        switch $BIF_NAME       ; but which BBS did we connect to?
  8770.         case "SOMEBIF1"
  8771.          gosub SomeBIF1_Job
  8772.         endcase
  8773.         case "SOMEBIF2"
  8774.          gosub SomeBIF2_Job
  8775.         endcase
  8776.          ;etc., for all the BIF descriptions you placed ! in
  8777.        endswitch
  8778.        send *[L]lofc          ;send the logoff command
  8779.        waitfor *[L]lofp 5     ;wait 5 seconds for the Logged Off prompt
  8780.       else                    ;WAITFOR timed out
  8781.        print "^M^J^GUnable to logon ... hanging up."
  8782.       endif
  8783.       
  8784.       hangup  ;make sure we're disconnected before trying to dial again
  8785.       REDIAL  ;Here we are at REDIAL, finally.  $ERRORLEVEL will be checked
  8786.               ; at the top of the loop, and we'll exit the loop if no more
  8787.               ; BIFs are tagged (or the user aborts dialing).
  8788.      endwhile
  8789.  
  8790.      return   ;All BIFs are finished
  8791.  
  8792.  
  8793.  
  8794.  
  8795.      Intellicomm v2.01               SCRIPT.DOC                            137
  8796.      
  8797.      
  8798.  
  8799.      SomeBIF1_Job:
  8800.         ;carry out a mail run or the like 
  8801.       return
  8802.  
  8803.      SomeBIF2_Job:
  8804.         ;whatever needs doing on BBS #2
  8805.       return
  8806.  
  8807.      RELOADSCRIPT_____________________________________________________________
  8808.  
  8809.      SUMMARY
  8810.  
  8811.       RELOADSCRIPT
  8812.  
  8813.      DESCRIPTION
  8814.  
  8815.       Reloads the currently executing script from disk, and begins executing
  8816.       it at the beginning again.  This command will mainly be of use to script
  8817.       writers who distribute scripts to the general public.  It can be used to
  8818.       reload/restart a script after the user has defined some initial setup
  8819.       information.
  8820.  
  8821.      EXAMPLE
  8822.  
  8823.      This example below is similar to what the POSTFILE.SCR does before it has
  8824.      been configured properly.  It causes a script to pause and "Edit"/reload
  8825.      itself, until the user sets the script up and removes the setup routine.
  8826.  
  8827.      ;---
  8828.      ;Attention User: Once you plug the proper information into the variables
  8829.      ; below, please remove these comments right down to the RELOADSCRIPT
  8830.      ; command.
  8831.  
  8832.      print $SCRIPT_NAME " has not been configured yet!"
  8833.      pause "Press a key to Edit..."
  8834.      edit $FULL_SCRIPT_NAME
  8835.      RELOADSCRIPT
  8836.  
  8837.      variable someinfo "Default"
  8838.       ;your main setup variables (what the user sets up) go here...
  8839.  
  8840.       ;the main body of your script goes here...
  8841.  
  8842.      return
  8843.  
  8844.  
  8845.      RENAME___________________________________________________________________
  8846.  
  8847.      SUMMARY
  8848.  
  8849.       RENAME sSOURCENAME sTARGETNAME
  8850.  
  8851.      DESCRIPTION
  8852.  
  8853.  
  8854.  
  8855.  
  8856.      Intellicomm v2.01               SCRIPT.DOC                            138
  8857.      
  8858.      
  8859.  
  8860.       Renames or moves a file.  Wildcards (* and ?) are not permitted.
  8861.  
  8862.       sSOURCENAME may contain a drive and path.  If the drive is omitted, the
  8863.       current drive is assumed.  If the path is omitted, the current directory
  8864.       is assumed.
  8865.  
  8866.       If sTARGETNAME contains a filename (but no D:\PATH), the file
  8867.       sSOURCENAME is renamed to sTARGENAME.  If sTARGETNAME contains only a
  8868.       path (D:\PATH or \PATH, etc) sSOURCENAME is MOVED to the directory
  8869.       specified by sTARGETNAME.
  8870.  
  8871.      ERRORLEVEL
  8872.  
  8873.       0  sSOURCENAME successfully renamed/moved.
  8874.       1  Unable to move/rename sSOURCENAME (sTARGETNAME is invalid).
  8875.       2  sSOURCENAME not found.
  8876.  
  8877.      EXAMPLE
  8878.  
  8879.       variable fname $HOME_DIR "EXCLUDE.KWD"  ;Exclude Files keyword list
  8880.  
  8881.       RENAME fname "EXCLUDE.TMP"
  8882.       importnew
  8883.       assign fname $HOME_DIR "EXCLUDE.TMP"
  8884.       RENAME fname "EXCLUDE.KWD"
  8885.  
  8886.      RENUMBER_________________________________________________________________
  8887.  
  8888.      SUMMARY
  8889.  
  8890.       RENUMBER sFILENAME nNUMTOTAL
  8891.  
  8892.      DESCRIPTION
  8893.  
  8894.       Renumbers the file sFILENAME to a maximum number of backup files
  8895.       specified by nNUMTOTAL.  RENUMBER renames files very quickly, placing
  8896.       numbers in either file filename or extension (and backup files) of
  8897.       sFILENAME.  Icom uses RENUMBER to rename the ICOM.CAP (capture) file
  8898.       just prior to dialing.
  8899.  
  8900.       sFILENAME can (and should) specify the full D:\PATH\FILENAME.EXT of the
  8901.       mail file you want to renumber.  Wildcards (* and ?) are not permitted. 
  8902.       If you specify wildcards in sFILENAME you may get a mess.
  8903.  
  8904.       nNUMTOTAL specifies the total number of backups of sFILENAME to keep on
  8905.       disk.
  8906.  
  8907.      ERRORLEVEL
  8908.  
  8909.       0  RENUMBER successful.
  8910.       1  sFILENAME not found.
  8911.  
  8912.      EXAMPLE
  8913.  
  8914.  
  8915.  
  8916.  
  8917.      Intellicomm v2.01               SCRIPT.DOC                            139
  8918.      
  8919.      
  8920.  
  8921.        ;Renumber the capture files...
  8922.       cappush
  8923.       capclose
  8924.       renumber $CAP_NAME *capnum
  8925.       cappop
  8926.  
  8927.      RETURN___________________________________________________________________
  8928.  
  8929.      SUMMARY
  8930.  
  8931.       RETURN [nERRORCODE]
  8932.  
  8933.      DESCRIPTION
  8934.  
  8935.       RETURN pulls double-duty and serves two purposes in the script language. 
  8936.       When Icom encounters a RETURN it first checks to see whether you
  8937.       previously executed a GOSUB (Goto Subroutine) command, and if so it
  8938.       simply returns to the line following the GOSUB.  However, if RETURN is
  8939.       found and no GOSUB has been executed, Icom ends the current script at
  8940.       that point (RETURNs to the calling script, or back to the automated job,
  8941.       or Script Manager, or wherever the script was called from).  The
  8942.       optional nERRORCODE is only checked in the latter case, when RETURN is
  8943.       used to exit a script.  Further, nERRORCODE is only of use when your
  8944.       script is called during an automated job, via a job Custom Command or
  8945.       BIF command.  In most cases, no nERRORCODE number will be specified at
  8946.       all, and you'll simply use RETURN alone.  There are a number of factors
  8947.       that determine what Icom does when a RETURN is found, and what it does
  8948.       if you specify an 'errorcode'.  All the details are given in
  8949.       SCRTUTOR.DOC in the section "WHAT HAPPENS WHEN A SCRIPT ENDS?".
  8950.  
  8951.      SEE ALSO
  8952.  
  8953.       GOSUB, SYSTEM
  8954.  
  8955.      EXAMPLE
  8956.  
  8957.       offline goto done    ;if not online, goto done
  8958.       ...                  ;main body of script here
  8959.  
  8960.      done:
  8961.       return               ;exit the script
  8962.  
  8963.      RMDIR____________________________________________________________________
  8964.  
  8965.      SUMMARY
  8966.  
  8967.       RMDIR sDIRECTORY ...
  8968.  
  8969.      DESCRIPTION
  8970.  
  8971.       Removes the directory sDIRECTORY.  The directory must be empty
  8972.       (including sub-subdirectories) for RMDIR to succeed.
  8973.  
  8974.       Note that the ... above doesn't mean that you can specify multiple
  8975.  
  8976.  
  8977.  
  8978.  
  8979.      Intellicomm v2.01               SCRIPT.DOC                            140
  8980.      
  8981.      
  8982.  
  8983.       directories to remove.  Like all script parameters, ... simply signifies
  8984.       that you can build the last parameter (sDIRECTORY is the last parameter
  8985.       in this case) like this:
  8986.  
  8987.        RMDIR "C:" somevariable anothervariable ... etc.
  8988.  
  8989.       All parameters specified are joined together to make a single parameter.
  8990.  
  8991.      ERRORLEVEL
  8992.  
  8993.       0  sDIRECTORY was removed.
  8994.       1  sDIRECTORY couldn't be removed (invalid drive or path).
  8995.       4  Permission denied (directory not empty).
  8996.       5  Miscellaneous errors.  The directory wasn't removed.
  8997.  
  8998.      SEE ALSO
  8999.  
  9000.       MKDIR
  9001.  
  9002.      EXAMPLE
  9003.  
  9004.       variable tmpdir "\$TEMP$.$$$"
  9005.  
  9006.       mkdir tmpdir   ;make a temporary directory off the root directory
  9007.       ...            ;do your stuff in the temp directory
  9008.       delete tmpdir "\*.*"  ;kill any files you created/copied, etc
  9009.                             ; (expands to \$TEMP$.$$$\*.*)
  9010.       RMDIR tmpdir
  9011.  
  9012.      RXFLUSH__________________________________________________________________
  9013.  
  9014.      SUMMARY
  9015.  
  9016.       RXFLUSH
  9017.  
  9018.      DESCRIPTION
  9019.  
  9020.       'Flushes' or clears the Receive Buffer (a holding area for characters
  9021.       received from the COM port, that have not been displayed to the screen
  9022.       yet).  Use to get rid of line noise, logoff bulletins, etc.
  9023.  
  9024.      SEE ALSO
  9025.  
  9026.       TXFLUSH
  9027.  
  9028.      SAVEBIF__________________________________________________________________
  9029.  
  9030.      SUMMARY
  9031.  
  9032.       SAVEBIF [sBIF_NAME]
  9033.  
  9034.      DESCRIPTION
  9035.  
  9036.       This advanced script command saves the currently loaded BIF information
  9037.  
  9038.  
  9039.  
  9040.  
  9041.      Intellicomm v2.01               SCRIPT.DOC                            141
  9042.      
  9043.      
  9044.  
  9045.       to disk.  If sBIF_NAME is omitted, $BIF_NAME (the current BIF filename)
  9046.       is assumed.
  9047.  
  9048.       Only a filename (JOESBBS, SOMEBIF, etc) is required if sBIF_NAME is
  9049.       specified.  You may specify a D:\PATH and extension if necessary (i.e.
  9050.       if you used FINDFIRST/FINDNEXT to locate various BIF filenames) but
  9051.       SAVEBIF always always saves in $BIF_DIR (ASSIGN $BIF_DIR another value
  9052.       to save to another directory) using the extension .BIF.
  9053.  
  9054.       NOTE 1: Don't use SAVEBIF unless you fully understand the LOADBIF
  9055.       command and BIF Variables.  SAVEBIF is meant to be used after you modify
  9056.       one or more BIF Variables, and you wish to save the modified information
  9057.       to disk.
  9058.  
  9059.       NOTE 2: If sBIF_NAME is specified and a BIF already exists using the
  9060.       same filename, the existing .BIF will be overwritten.  You can use the
  9061.       EXIST or FINDFIRST command to see if a given BIFID already exists:
  9062.  
  9063.        variable bifname "SOME_ID"
  9064.        variable temp
  9065.  
  9066.        assign temp $BIF_DIR bifname
  9067.        notexist temp SAVEBIF bifname
  9068.  
  9069.      ERRORLEVEL
  9070.  
  9071.       0  SAVEBIF successful.
  9072.       1  SAVEBIF unsuccessful (disk write error, invalid sBIF_NAME, disk
  9073.      full).
  9074.  
  9075.      SEE ALSO
  9076.  
  9077.       LOADBIF
  9078.  
  9079.      EXAMPLE
  9080.  
  9081.        ;Could be used to automatically change the Logon Name (or anything
  9082.        ; else) in all BIFs.
  9083.  
  9084.       variable bifname $BIF_DIR "*.BIF"
  9085.       variable v
  9086.  
  9087.       findfirst bifname bifname  ;store the first BIF in 'bifname'
  9088.  
  9089.       while $errorlevel = 0
  9090.        substr v *[L]desc 0 1     ;get the 1st character of the BBS/Host Name
  9091.        if v <> "["               ;don't mess with BIF templates...
  9092.         loadbif bifname
  9093.         assign *[L]namc "Joe Smith"
  9094.         SAVEBIF
  9095.        endif
  9096.        findnext bifname
  9097.       endwhile
  9098.  
  9099.  
  9100.  
  9101.  
  9102.      Intellicomm v2.01               SCRIPT.DOC                            142
  9103.      
  9104.      
  9105.  
  9106.      SAVEINI__________________________________________________________________
  9107.  
  9108.      SUMMARY
  9109.  
  9110.       SAVEINI [sINI_NAME]
  9111.  
  9112.      DESCRIPTION
  9113.  
  9114.       This advanced script command saves the currently loaded INI (main setup
  9115.       variables) information to disk.  If sINI_NAME is omitted, $INI_NAME (the
  9116.       current main setup file) is assumed.
  9117.  
  9118.       Only a filename (CUSTOM, SOMEINI, etc) is required if sINI_NAME is
  9119.       specified.  You may specify a D:\PATH and extension if necessary (i.e.
  9120.       if you used FINDFIRST/FINDNEXT to locate various INI filenames) but
  9121.       SAVEINI always always saves in $HOME_DIR (which cannot be modified)
  9122.       using the extension .INI.
  9123.  
  9124.       NOTE 1: Don't use SAVEINI unless you fully understand the LOADINI
  9125.       command and Main Setup Variables.  SAVEINI is meant to be used after you
  9126.       modify one or more Main Setup Variables, and you wish to save the
  9127.       modified information to disk.
  9128.  
  9129.       NOTE 2: If sINI_NAME is specified and an INI already exists using the
  9130.       same filename, the existing .INI will be overwritten!  You can use the
  9131.       EXIST or FINDFIRST command to see if a given .INI file already exists:
  9132.  
  9133.        variable ininame "CUSTOM"
  9134.        variable temp
  9135.  
  9136.        assign temp $HOME_DIR ininame
  9137.        notexist temp SAVEINI ininame
  9138.  
  9139.      ERRORLEVEL
  9140.  
  9141.       0  SAVEINI successful.
  9142.       1  SAVEINI unsuccessful (disk write error, invalid sINI_NAME, disk
  9143.      full).
  9144.  
  9145.      SEE ALSO
  9146.  
  9147.       LOADINI
  9148.  
  9149.      EXAMPLE
  9150.  
  9151.        ;Could be used to automatically change information in all .INI
  9152.        ; files.  This example changes your home telephone number (User
  9153.        ; Settings screen).
  9154.  
  9155.       variable ini_name $HOME_DIR "*.INI"
  9156.       variable v
  9157.  
  9158.       findfirst ini_name ini_name  ;store the first Ini in 'ini_name'
  9159.  
  9160.  
  9161.  
  9162.  
  9163.      Intellicomm v2.01               SCRIPT.DOC                            143
  9164.      
  9165.      
  9166.  
  9167.       while $errorlevel = 0
  9168.        loadini ini_name
  9169.        assign *uhphn "555-555-1234"
  9170.        SAVEINI ini_name
  9171.        findnext ini_name
  9172.       endwhile
  9173.  
  9174.      SCAPTURE_________________________________________________________________
  9175.  
  9176.      SUMMARY
  9177.  
  9178.       SCAPTURE [sFILENAME] ...
  9179.  
  9180.      DESCRIPTION
  9181.  
  9182.       Saves the contents of the screen to the file sFILENAME.  If sFILENAME is
  9183.       omitted, the default Screen Capture Filename (*scap; defined on the main
  9184.       setup Filenames and Path screen) is assumed.  If sFILENAME is specified
  9185.       but no D:\PATH is given, the file is saved in the current directory.
  9186.  
  9187.       NOTE: SCAPTURE always adds to the end of files.  It never overwrites
  9188.       files.  If you want to overwrite, simply DELETE the existing file (if
  9189.       any) before you use SCAPTURE.
  9190.  
  9191.      SEE ALSO
  9192.  
  9193.       CAPTURE
  9194.  
  9195.      EXAMPLE
  9196.  
  9197.       send "some command"
  9198.       waitfor "some text"
  9199.       SCAPTURE
  9200.       send "^MG"
  9201.       hangup
  9202.       list *scap   ;display the screen capture file
  9203.  
  9204.      SCREENBLANK______________________________________________________________
  9205.      SCREENRESTORE____________________________________________________________
  9206.  
  9207.      SUMMARY
  9208.  
  9209.       SCREENBLANK
  9210.       SCREENRESTORE
  9211.  
  9212.      DESCRIPTION
  9213.  
  9214.       SCREENBLANK activates the screen blanker, just as if the usual
  9215.       inactivity period defined by the user had elapsed.  Note that if the
  9216.       user does not have the screen blanker enabled (Icom main setup,
  9217.       Screen/Color Settings), the SCREENBLANK command has no effect.  There
  9218.       usually will be no need to use the SCREENBLANK command, since
  9219.       Intellicomm activates the screen blanker on its own (after the user-
  9220.       defined inactivity period) even when scripts are running.  The exception
  9221.  
  9222.  
  9223.  
  9224.  
  9225.      Intellicomm v2.01               SCRIPT.DOC                            144
  9226.      
  9227.      
  9228.  
  9229.       to this is if you set $KEY_CHECK to 0 (zero) to do your own keystroke
  9230.       handling.  If that's the case it'll be up to you to blank the screen
  9231.       using SCREENBLANK.
  9232.  
  9233.       SCREENRESTORE restores the screen (if blanked) as if the user had
  9234.       pressed a key.  You should only use this command when you must get the
  9235.       user's attention for some reason (to print an error message or the
  9236.       like), and in most cases Intellicomm itself will automatically restore
  9237.       the screen when something 'new' happens.  For example, if you use
  9238.       WNDOPEN, MSGWIND, BOX ... or MENUBAR, MENUBOXH, MENUBOXV, or
  9239.       BOXGETS/GETS, or after a file transfer completes, or if Icom prints its
  9240.       own error window, SCREENRESTORE will be called automatically.  You'll
  9241.       only have to use it in rare cases.
  9242.  
  9243.      EXAMPLE
  9244.  
  9245.       variable old_key_check $KEY_CHECK  ;save previous value
  9246.       assign $KEY_CHECK 0                ;keys are no longer checked by Icom
  9247.  
  9248.       SCREENRESTORE                      ;make sure this is displayed
  9249.       cls
  9250.       print "NOTE: Do not attempt to abort this file transfer!"
  9251.       delay 50
  9252.  
  9253.        ;the user cannot abort the file transfer due to $KEY_CHECK 0 above
  9254.        ; and further, without doing key checking, Icom will not activate
  9255.        ; the screen blanker
  9256.  
  9257.       SCREENBLANK
  9258.       download "X" "IMPORTNT.FIL"
  9259.       ;SCREENRESTORE is called automatically after the transfer.  It wouldn't
  9260.       ; hurt anything to call it again here, but... it's not necessary.
  9261.  
  9262.       assign $KEY_CHECK old_key_check    ;restore previous value
  9263.  
  9264.      SCRIPT___________________________________________________________________
  9265.  
  9266.      SUMMARY
  9267.  
  9268.       SCRIPT sSCRIPTNAME sPARAMETER ...
  9269.  
  9270.      DESCRIPTION
  9271.  
  9272.       Runs another script from within a script, then continues running the
  9273.       previous script at the next line after the SCRIPT command.  sSCRIPTNAME
  9274.       is the name of the script to run.  Any parameters that follow the script
  9275.       name are placed in the GlobalStr array (see the 'Global Variables'
  9276.       section in SCRTUTOR.DOC) for use in the called script.
  9277.  
  9278.       If both sSCRIPTNAME and sPARAMETER are omitted, the Script Manager is
  9279.       displayed allowing the user to select one or more scripts to Run.
  9280.  
  9281.      ERRORLEVEL
  9282.  
  9283.  
  9284.  
  9285.  
  9286.      Intellicomm v2.01               SCRIPT.DOC                            145
  9287.      
  9288.      
  9289.  
  9290.       0  sSCRIPTNAME loaded and executed with no errors.
  9291.  
  9292.       Any other value in $ERRORLEVEL signifies an error loading the script or
  9293.       an error RETURN code from the called script.  See the RETURN command for
  9294.       more details.
  9295.  
  9296.      SEE ALSO
  9297.  
  9298.       EXIT, RETURN
  9299.  
  9300.      EXAMPLE
  9301.  
  9302.        ;Execute POSTFILE.SCR on the file C:\ICOM\GET\ICOM201A.ZIP"
  9303.       SCRIPT "POSTFILE.SCR" "ICOM201" ".ZIP" "C:\ICOM\GET\ICOM201A.ZIP"
  9304.  
  9305.      SCROLL___________________________________________________________________
  9306.  
  9307.      SUMMARY
  9308.  
  9309.       SCROLL nX1 nY1 nX2 nY2 nMODE nCOLOR
  9310.  
  9311.      DESCRIPTION
  9312.  
  9313.       Scrolls or clears an area of the screen.  nX1 nY1 specify the top
  9314.       corner, nX2, nY2 specify the bottom corner ('X' is a screen column
  9315.       number from left to right, 'Y' is a screen row number from top to
  9316.       bottom.  1 1 is the top corner of the screen, $SCRN_WIDTH, $SCRN_HEIGHT
  9317.       [normally 80, 25] is the bottom corner of the screen).  Screen windows
  9318.       set with the WINDOW or WNDOPEN command are ignored by SCROLL, meaning
  9319.       that 1 1 is always the same (the top corner of the screen), regardless
  9320.       of whether a WINDOW is set.
  9321.  
  9322.       nMODE tells SCROLL what to do.  Positive numbers tell it to scroll the
  9323.       text UP, negative numbers tell it to scroll the text DOWN, zero tells it
  9324.       to simply clear the area.
  9325.  
  9326.       nCOLOR is the screen color used to fill in the scrolled (or cleared)
  9327.       area.  For example if you scroll the screen up by one line, you'll then
  9328.       have a blank line where the bottom-most line used to be.  nCOLOR tells
  9329.       SCROLL what color to set that bottom-most line to.  Normally you'll use
  9330.       one of the $XXXX_COLOR System Variables such as $SCRN_COLOR, $TERM_COLOR
  9331.       or $NORM_COLOR.  Please see the COLOR CODES Appendix for custom colors.
  9332.  
  9333.      SEE ALSO
  9334.  
  9335.       CLS
  9336.  
  9337.      EXAMPLE
  9338.  
  9339.       variable line 1
  9340.  
  9341.       cls
  9342.       while line < $WND_BTM  ;$WND_BTM accounts for the status line, if on
  9343.        print "Line " line
  9344.  
  9345.  
  9346.  
  9347.  
  9348.      Intellicomm v2.01               SCRIPT.DOC                            146
  9349.      
  9350.      
  9351.  
  9352.       endwhile
  9353.       
  9354.       pause "Press a key to scroll..."
  9355.       SCROLL 1 1 $SCRN_WIDTH $WND_BTM 1 $SCRN_COLOR
  9356.  
  9357.      SCROLLBACK_______________________________________________________________
  9358.  
  9359.      SUMMARY
  9360.  
  9361.       SCROLLBACK
  9362.  
  9363.      DESCRIPTION
  9364.  
  9365.       Enters the Terminal's scrollback buffer (same as pressing [Alt-B] from
  9366.       Terminal Mode).  This command was included mainly for use by Script
  9367.       Learn mode, and you probably won't have much use for it in your own
  9368.       scripts unless you turn $KEY_CHECK off.  Normally you'll be better off
  9369.       letting Icom just process the hotkeys ([Alt-B], etc) itself.
  9370.  
  9371.      EXAMPLE
  9372.  
  9373.       See INKEY for an example of turning $KEY_CHECK off, and processing usual
  9374.       Icom hotkeys via script commands.
  9375.  
  9376.      SEND_____________________________________________________________________
  9377.      SENDNC___________________________________________________________________
  9378.      SENDNCP__________________________________________________________________
  9379.      SENDNP___________________________________________________________________
  9380.  
  9381.      SUMMARY
  9382.  
  9383.       SEND [sDATA ...]
  9384.       SENDNC sDATA ...
  9385.       SENDNCP sDATA ...
  9386.       SENDNP [sDATA ...]
  9387.  
  9388.      DESCRIPTION
  9389.  
  9390.       All send sDATA (one or more constant strings/numbers, or variables) out
  9391.       the current COM port ($COM_PORT).
  9392.  
  9393.       SEND and SENDNP add a Carriage Return (CR; same as pressing [Enter])
  9394.       after sSDATA; while SENDNC (NC for 'N'o 'C'R) and SENDNCP do not.
  9395.  
  9396.       Further, SEND and SENDNC delay the sending of sDATA for the duration of
  9397.       the "Response Delay" item defined in BIF screen 1, if the modem is
  9398.       connected and a BIF is in use.  The 'NP' variations SENDNCP and SENDNP
  9399.       (NP for 'N'o 'P'ause) do not.
  9400.  
  9401.       Control characters can be specified in sDATA in the usual manner, by
  9402.       preceding the character with a caret (^) (see SCRTUTOR.DOC and the ASCII
  9403.       CODES appendix).  Further, a tilde (~) causes a 1 second delay in the
  9404.       sending of sDATA; usually to slow the command down to let the BBS (or
  9405.       modem) catch up.
  9406.  
  9407.  
  9408.  
  9409.  
  9410.      Intellicomm v2.01               SCRIPT.DOC                            147
  9411.      
  9412.      
  9413.  
  9414.       As mentioned above, by default both SEND and SENDNP add a carriage
  9415.       return (CR) after sDATA, which is the same as pressing [Enter] on your
  9416.       keyboard. But you can control this by modifying the $SEND_CR System
  9417.       Variable.  On some BBS's, you don't want a CR to follow the command (if
  9418.       BBS "hotkeys" are in use), while on others you must enter the command
  9419.       with a CR.  Rather than re-writing your scripts and changing SEND to
  9420.       SENDNC (send with no CR) or vice versa, you can stick with SEND in all
  9421.       your scripts and control whether a CR is added or not by changing the
  9422.       $SEND_CR System Variable at the top of the script.  If $SEND_CR is non-
  9423.       zero, a CR is added by SEND/SENDNP.  If $SEND_CR is zero, no CR is
  9424.       added.
  9425.  
  9426.       $SEND_CR can also be handy in making your scripts more user-friendly. 
  9427.       You can tell SEND whether to add a CR or not by checking the BIF "CR
  9428.       w/Commands?" item on BIF screen 1:
  9429.  
  9430.        if *[G]adcr = "Yes"   ;Add CR?  [G] = BIF [G]eneral section (scrn 1)
  9431.         assign $SEND_CR 1    ;SEND/SENDNP add carriage returns
  9432.        else
  9433.         assign $SEND_CR 0    ;SEND/SENDNP don't add CR's
  9434.        endif
  9435.  
  9436.       With the above in place at the top of a script the user could simply
  9437.       modify the BIF to get the script to operate differently.
  9438.  
  9439.       NOTE: If you're dealing with BIF information (BIF variables) in your
  9440.       script; instead of using SEND to send BIF responses/commands, you should
  9441.       instead use SENDBIF, which interprets the special BIF command
  9442.       characters:
  9443.  
  9444.        @ = Run another script
  9445.        & = Execute a single script command
  9446.        ! = Execute a DOS command
  9447.  
  9448.      SEE ALSO
  9449.  
  9450.       $SEND_CR
  9451.  
  9452.      SEND EXAMPLE
  9453.  
  9454.       SEND "D^M~NICECAR.GIF^M~Z"
  9455.        
  9456.         ;Translation:
  9457.         ; [D]ownload   ([Enter] and a 1 second pause)
  9458.         ; NICECAR.GIF  ([Enter] and a 1 second pause)
  9459.         ; [Z]modem     ([Enter] added by SEND)
  9460.  
  9461.       delay 30
  9462.       download "Z"
  9463.  
  9464.      SENDNC EXAMPLE
  9465.  
  9466.       variable UserName
  9467.  
  9468.  
  9469.  
  9470.  
  9471.      Intellicomm v2.01               SCRIPT.DOC                            148
  9472.      
  9473.      
  9474.  
  9475.       SENDNC "Please enter your name: "
  9476.       cgets UserName 50 "^M" 60
  9477.  
  9478.       send "^M^JWelcome, " UserName "."
  9479.  
  9480.      SENDBIF__________________________________________________________________
  9481.  
  9482.      SUMMARY
  9483.  
  9484.       SENDBIF sSECTION sTAG
  9485.  
  9486.      DESCRIPTION
  9487.  
  9488.       SENDBIF is used to handle BIF responses, and it usually sends one or
  9489.       more commands to the BBS.  It calls the same routine that Intellicomm
  9490.       itself calls to handle BIF responses, when a BIF prompt is found.  I.e.
  9491.       you will only want to use it when you're certain a BIF has been properly
  9492.       set up.
  9493.  
  9494.       sSECTION is the BIF section, sTAG is the four letter tag of a specific
  9495.       item within a section.  The BIF Variables section outlines all BIF
  9496.       sections and tags.
  9497.  
  9498.       If you use SENDBIF in your scripts (as opposed to regular SEND), you'll
  9499.       be able to control what your scripts send, and how that data it sent,
  9500.       directly from the BIF, instead of having to modify your script directly.
  9501.  
  9502.       SENDBIF supports the following special characters:
  9503.  
  9504.        ^   A tilde is used to specify a control charater (^M is [Enter], ^[ is
  9505.            [Esc], etc.  See the ASCII CODES Appendix).
  9506.        ~   Causes a one second delay.
  9507.  
  9508.       Further, it supports the special command characters permitted in BIF
  9509.       responses:
  9510.  
  9511.        @SCRIPTNAME = Run another script
  9512.        &COMMAND    = Execute a single script command
  9513.        !COMMAND    = Execute a DOS command
  9514.  
  9515.       And both the Response Delay and BS Protection (BIF screen 1) are also
  9516.       supported by SENDBIF.  The Response Delay allows you to pause SENDBIF
  9517.       for a specified length of time (in tenths of a second) before sending
  9518.       the sDATA parameter, and this can be handy on BBS's that flush their
  9519.       input buffers after displaying prompts.  The BS Protection (Backspace
  9520.       Protection) item allows you to have SENDBIF send a specified number of
  9521.       Backspace characters to the BBS, after the Response Delay, to eliminate
  9522.       line noise before sending the proper response.
  9523.  
  9524.      SEE ALSO
  9525.  
  9526.       SEND
  9527.  
  9528.      EXAMPLE
  9529.  
  9530.  
  9531.  
  9532.  
  9533.      Intellicomm v2.01               SCRIPT.DOC                            149
  9534.      
  9535.      
  9536.  
  9537.       Please see the REDIAL example.
  9538.  
  9539.      SENDKEY__________________________________________________________________
  9540.  
  9541.      SUMMARY
  9542.  
  9543.       SENDKEY sKEY ...
  9544.  
  9545.      DESCRIPTION
  9546.  
  9547.       SENDKEY allows you to send one or more keystrokes to the Icom terminal
  9548.       key handler.  The key codes sent via SENDKEY look no different to
  9549.       Intellicomm than had you pressed the key(s) at the keyboard.  You may
  9550.       specify up to 128 keys all with one SENDKEY command.  The 'key'
  9551.       parameter(s) can be either a text string in quotes:
  9552.  
  9553.        SENDKEY "Send this"     ;puts nine keys into the key queue
  9554.  
  9555.       and/or an extended key code, as outlined in the KEY CODES Appendix:
  9556.  
  9557.        SENDKEY 7936            ;puts a single extended key code in the queue
  9558.  
  9559.       SENDKEY converts the keycode differently depending on whether the sKEY
  9560.       parameter is in quotes or not.  If you use this:
  9561.  
  9562.        SENDKEY "15104"       ;15104 is the keycode for the [F1] key
  9563.  
  9564.       it will NOT translate to extended keycode 15104.  Due to the quotes, it
  9565.       will be processed as five separate keystrokes: 1, 5, 1, 0, and 4.  If
  9566.       you use this:
  9567.  
  9568.        SENDKEY 15104         ;no quotes
  9569.  
  9570.       all five characters are converted to a single number (extended keycode
  9571.       15104; the [F1] key).  If you specify more than one 'key' parameter,
  9572.       each must be separated by at least one space or TAB character as with
  9573.       all script parameters.  
  9574.  
  9575.       If a sKEY parameter is an Icom terminal hotkey such as [F1] (help) [Alt-
  9576.       Z] (terminal menu), [Alt-D] (change to the BBS/Dialing Directory), etc.,
  9577.       then it pops up the appropriate Icom menu or carries out whatever task
  9578.       the hotkey would if you pressed the key from terminal mode.  This is
  9579.       where it can be useful to stack several key codes with a single SENDKEY
  9580.       command, since it allows you to operate WITHIN the menu after it opens
  9581.       (see the example below).  However, if 'doorway mode' is on, the extended
  9582.       keycode(s) are simply sent to the BBS (see the $DOORWAY System Variable)
  9583.       no differently than if you pressed the key with doorway mode on.  To
  9584.       send extended keycodes to the BBS instead of having Icom process it as a
  9585.       hotkey, simply turn doorway mode on:
  9586.  
  9587.        variable old_doorway $DOORWAY  ;save the old doorway mode status
  9588.  
  9589.        assign $DOORWAY 1              ;1 turns doorway mode on
  9590.        SENDKEY 15104                  ;send [F1] to the BBS instead of to Icom
  9591.  
  9592.  
  9593.  
  9594.  
  9595.      Intellicomm v2.01               SCRIPT.DOC                            150
  9596.      
  9597.      
  9598.  
  9599.        assign $DOORWAY old_doorway    ;reset doorway mode to its previous
  9600.      state
  9601.  
  9602.       Doorway Mode is used by many BBS doors for extended keycode handling
  9603.       (i.e. use of real menus with hilight bars which allow [Up], [Down] to
  9604.       move the bar, etc).  If you use a BBS door that supports Doorway Mode,
  9605.       you'll know what it is.  If you don't, then Doorway Mode and sending
  9606.       extended keycodes to the BBS with SENDKEY is of no use to you.
  9607.  
  9608.       With doorway mode OFF you can have Icom actually perform tasks within
  9609.       menus you pop up, by stringing several keys together (similar to
  9610.       macros).  However, SENDKEY has not been tested extensively for this use
  9611.       (it was included only for Script Learn mode, for oddball keycodes), so
  9612.       don't be surprised if you can't carry out an entire Intellicomm session
  9613.       with SENDKEY.  See the EXAMPLE below for details of a semi-long SENDKEY
  9614.       example that does work.
  9615.       
  9616.       sKEY parameters (as with all Icom script parameters) may also be
  9617.       variables.  If the contents of the variable contains only numbers, then
  9618.       it's the same as using a constant number (an extended keycode).  If the
  9619.       contents of the variable contains one or more non-numeric characters,
  9620.       it's the same as specifying constant text in quotes.
  9621.  
  9622.      ERRORLEVEL
  9623.       
  9624.       0 = Key(s) successfully queued.
  9625.       1 = Keystroke queue full.  You can send 128 keys at a time.
  9626.  
  9627.       If doorway mode is off and you specify one or more Icom hotkeys to carry
  9628.       out tasks, there is no way to tell whether the actual functions/tasks
  9629.       you requested were successful.  If the keys are successfully queued,
  9630.       they are automatically processed.  But since you can do literally
  9631.       anything with SENDKEY there's really no way for Icom to keep track of
  9632.       what occurred and set an errorlevel.  You could cause Icom to process
  9633.       keystrokes for hours, carrying out myriad tasks with a single SENDKEY
  9634.       command.  In such a case, as single errorlevel after the SENDKEY command
  9635.       finally finished, would be meaningless.
  9636.  
  9637.       If you're carrying out critical tasks you're better off using a regular
  9638.       script command which DOES set an errorlevel.  For example, instead of
  9639.       sending the [Alt-D] extended keycode, a couple of 'T's to Tag a BIF or
  9640.       two, then 'D' to dial a BBS... use the DIAL command.  Most Icom
  9641.       functions DO have script command equivalents (DIAL, FILEMAN [and COPY,
  9642.       DELETE, DISKSEARCH, etc.] HELP, HELPSEARCH, SCRIPT, and so forth) to
  9643.       allow you to carry out most of the common Icom tasks without using
  9644.       SENDKEY and looking up keycodes.  Use SENDKEY only when you cannot
  9645.       accomplish the task with regular script commands, or when you want to
  9646.       send an extended keycode to the BBS (with doorway mode on).
  9647.  
  9648.      SEE ALSO
  9649.  
  9650.       $DOORWAY
  9651.  
  9652.       Also see the "SCRIPT COMMANDS AT A GLANCE" section to locate regular
  9653.  
  9654.  
  9655.  
  9656.  
  9657.      Intellicomm v2.01               SCRIPT.DOC                            151
  9658.      
  9659.      
  9660.  
  9661.       script commands which can be used with more reliability/control than
  9662.       using SENDKEY.
  9663.  
  9664.      EXAMPLE
  9665.  
  9666.       variable s       ;define a variable called 's'
  9667.       
  9668.        ;pop a box up allowing up to 70 characters of input
  9669.       BOXGETS s 70 "SENDKEY Example" "Enter some text"
  9670.  
  9671.       SENDKEYS 7680 s 7936 "DEMOFILE.TXT^M^["
  9672.  
  9673.        ;The above sends the [Alt-A] key (access the Editor) then sends the
  9674.        ; contents of variable 's' (whatever the user entered in the input
  9675.        ; box), then sends [Alt-S] (Save File), enters the filename
  9676.        ; DEMOFILE.TXT followed by ENTER (^M = CR) then presses [Esc] (^[ =
  9677.        ; ESC) to exit the editor.  This would only work with the internal
  9678.        ; editor. SENDKEY does not send keys to external programs (it might in
  9679.        ; the future).
  9680.  
  9681.      SENDBREAK________________________________________________________________
  9682.  
  9683.      SUMMARY
  9684.  
  9685.       SENDBREAK [nDURATION]
  9686.  
  9687.      DESCRIPTION
  9688.  
  9689.       Sends a break signal to the current COM port for nDURATION tenths of a
  9690.       second.  If nDURATION is omitted, 30 tenths (3 seconds) is assumed which
  9691.       is the same duration used when [Ctrl-End] is pressed from Terminal mode.
  9692.  
  9693.       No messages are printed to the screen (as with [Ctrl-End] when SENDBREAK
  9694.       is called from a script.  See the example if you want to notify the user
  9695.       that a break is being sent.
  9696.  
  9697.      SEE ALSO
  9698.  
  9699.       RXFLUSH, TXFLUSH
  9700.  
  9701.      EXAMPLE
  9702.  
  9703.       msgopen "Sending break"
  9704.       SENDBREAK
  9705.       msgclose
  9706.  
  9707.      SETCHR___________________________________________________________________
  9708.  
  9709.      SUMMARY
  9710.  
  9711.       SETCHR vTARGETSTRING sCHARACTER nPOSITION
  9712.  
  9713.      DESCRIPTION
  9714.  
  9715.  
  9716.  
  9717.  
  9718.      Intellicomm v2.01               SCRIPT.DOC                            152
  9719.      
  9720.      
  9721.  
  9722.       Places character sCHARACTER into vTARGETSTRING at nPOSITION
  9723.       *overwriting* the existing character in vTARGETSTRING.  Use STRINS to
  9724.       *insert* a character, without overwriting.  For nPOSITION, 0 is the
  9725.       first character in vTARGETSYRING, 1 is the second, etc.  A character
  9726.       must already exist in vTARGETSTRING at nPOSITION.  
  9727.  
  9728.      SEE ALSO
  9729.  
  9730.       SETCHRS, STRINS
  9731.  
  9732.      EXAMPLE
  9733.       
  9734.       variable s "This is a string."
  9735.       SETCHR s "!" 16     ;changes character 16 (.) to !
  9736.  
  9737.       SETCHR s "!" 17     ;does nothing: no character at position 17 to
  9738.      replace
  9739.                           ; use STRCAT to add one or more characters.
  9740.  
  9741.      SETCHRS__________________________________________________________________
  9742.  
  9743.      SUMMARY
  9744.  
  9745.       SETCHRS vTARGETSTRING sNEWSTRING nPOSITION [nNUMCHARS]
  9746.  
  9747.      DESCRIPTION
  9748.  
  9749.       Places nNUMCHARS of sNEWSTRING into into vTARGETSTRING at nPOSITION
  9750.       *overwriting* the existing portion of vTARGETSTRING.  Use STRINS to
  9751.       *insert* a string, without overwriting.  For nPOSITION, 0 is the first
  9752.       character in vTARGETSYRING, 1 is the second, etc.  A string must already
  9753.       exist in vTARGETSTRING, and must be the same size or longer than
  9754.       sNEWSTRING.  I.e. SETCHRS is designed to replace *existing* characters
  9755.       in vTARGETSTRING and not to add new characters to it.  Use STRCAT,
  9756.       STRINS or STRSET to add to an existing string.
  9757.  
  9758.      SEE ALSO
  9759.  
  9760.       SETCHR, STRINS, STRSET
  9761.  
  9762.      EXAMPLE
  9763.       
  9764.       variable s "This is a string."
  9765.       SETCHRS s "replaced" 8
  9766.       print s   ;prints 'This is replaced.'
  9767.  
  9768.       variable s2 "IS A STRING."
  9769.       SETCHRS s s2 5 2    ;at position 5 in 's', only 2 chars from 's2'
  9770.       print s   ;prints 'This IS replaced.' 
  9771.  
  9772.      SETENV___________________________________________________________________
  9773.  
  9774.      SUMMARY
  9775.  
  9776.  
  9777.  
  9778.  
  9779.      Intellicomm v2.01               SCRIPT.DOC                            153
  9780.      
  9781.      
  9782.  
  9783.       SETENV sENVSTRING ...
  9784.  
  9785.      DESCRIPTION
  9786.  
  9787.       Sets a new environment variable or clears an existing environment
  9788.       variable.  Use the format "VARIABLE=setting" to either change an
  9789.       existing environment variable or to add a new variable.  Use the format
  9790.       "VARIABLE=" (no new setting) to clear an existing environment variable.
  9791.  
  9792.      ERRORLEVEL
  9793.  
  9794.       0  SETENV was successful.
  9795.       1  SETENV was unsuccessful.
  9796.  
  9797.      SEE ALSO
  9798.  
  9799.       GETENV
  9800.  
  9801.      EXAMPLE
  9802.  
  9803.       variable path
  9804.  
  9805.       getenv path "PATH"
  9806.       strcat path ";C:\SOMEDIR"
  9807.       setenv "PATH=" path
  9808.  
  9809.      SETCOMM__________________________________________________________________
  9810.  
  9811.      SUMMARY
  9812.  
  9813.       SETCOMM sPORT_SETTINGS ...
  9814.  
  9815.      DESCRIPTION
  9816.  
  9817.       Sets the current COM port ($COM_PORT) to the settings specified by
  9818.       sPORT_SETTINGS.  sPORT_SETTINGS must be in the following format which is
  9819.       specified in one single parameter (spaces are ignored, but the commas
  9820.       [,] are mandatory):
  9821.  
  9822.        "BAUD, PARITY, DATABITS, STOPBITS"
  9823.  
  9824.       BAUD (the port speed or 'baud rate') must be one of the following:
  9825.  
  9826.         300
  9827.         1200
  9828.         2400
  9829.         4800
  9830.         9600
  9831.         19200
  9832.         38400
  9833.         57600
  9834.         115200
  9835.  
  9836.       PARITY must be one of the following (a single letter):
  9837.  
  9838.  
  9839.  
  9840.  
  9841.      Intellicomm v2.01               SCRIPT.DOC                            154
  9842.      
  9843.      
  9844.  
  9845.         N  (No Parity)
  9846.         E  (Even Parity)
  9847.         O  (Odd Parity)
  9848.  
  9849.  
  9850.       DATABITS must be one of the following:
  9851.  
  9852.         7
  9853.         8
  9854.  
  9855.       STOPBITS must be one of the following:
  9856.  
  9857.         1
  9858.         2
  9859.  
  9860.       Any of the above items can be omitted, allowing you to change the Baud
  9861.       without changing the existing Parity, DataBits, StopBits, but the commas
  9862.       are mandatory whether an item is omitted or not.  See the example for
  9863.       details.
  9864.  
  9865.       NOTE: The "..." after the sPORT_SETTINGS parameter means that you can
  9866.       specify multiple parameters which will be grouped together for you as a
  9867.       single parameter.  This allows you to use multiple variables with a
  9868.       single SETCOMM command:
  9869.  
  9870.        variable baud     "9600"
  9871.        variable parity   "N"
  9872.        variable databits "8"
  9873.        variable stopbits "1"
  9874.  
  9875.        SETCOMM baud "," parity "," databits "," stopbits
  9876.  
  9877.       Note that the commas are still mandatory.
  9878.  
  9879.      ERRORLEVEL
  9880.  
  9881.       0  Port settings changed to sPORT_SETTINGS
  9882.       1  Unable to set port to sPORT_SETTINGS (not all combinations of data
  9883.          bits, stop bits and parity are supported by PC COM ports).
  9884.  
  9885.      SEE ALSO
  9886.  
  9887.       PORT, $COM_PORT, $COM_SPEED
  9888.  
  9889.      EXAMPLE
  9890.  
  9891.       SETCOMM "1200,N,8,1" ;1200 BAUD, No PARITY, 8 DATABITS, 1 STOPBIT
  9892.  
  9893.       SETCOMM "19200,,,"   ;set BAUD to 19200, leave PARITY, DATABITS,
  9894.      STOPBITS
  9895.                            ; as is
  9896.  
  9897.       SETCOMM ",E,7,1"     ;leave BAUD as is, set Even PARITY, 7 DATABITS,
  9898.                            ; 1 STOPBIT
  9899.  
  9900.  
  9901.  
  9902.  
  9903.      Intellicomm v2.01               SCRIPT.DOC                            155
  9904.      
  9905.      
  9906.  
  9907.       SETCOMM ",N,,"       ;set PARITY to None, leave all others as is
  9908.  
  9909.      SHL______________________________________________________________________
  9910.  
  9911.      SUMMARY
  9912.  
  9913.       SHL vRESULT nNUM nBITS
  9914.  
  9915.      DESCRIPTION
  9916.  
  9917.       Shifts nBITS bits in nNUM to the left and stores the result in vRESULT. 
  9918.       SHL (SHift Left) is an advanced command for programmers.
  9919.  
  9920.      SEE ALSO
  9921.  
  9922.       SHR
  9923.  
  9924.      EXAMPLE
  9925.  
  9926.       variable result 1
  9927.  
  9928.       SHL result result 1
  9929.       print result   ;prints 2
  9930.  
  9931.       SHL result result 1
  9932.       print result   ;prints 4
  9933.  
  9934.       SHL result result 2
  9935.       print result   ;prints 16
  9936.  
  9937.      SHOWWHENS________________________________________________________________
  9938.  
  9939.      SUMMARY
  9940.  
  9941.       SHOWWHENS
  9942.  
  9943.      DESCRIPTION
  9944.  
  9945.       Displays a screen that shows the current BBS prompts Intellicomm is
  9946.       tracking (either via script WHEN commands, or Intellicomm's automated
  9947.       routines), and the responses or script commands that will be executed
  9948.       when the prompt is found.  Useful in debugging, to display the contents
  9949.       of WHEN slots.  Note that you can also display this screen by pressing
  9950.       [Alt-W] (Show WHENs).
  9951.  
  9952.      SHR______________________________________________________________________
  9953.  
  9954.      SUMMARY
  9955.  
  9956.       SHR vRESULT nNUM nBITS
  9957.  
  9958.      DESCRIPTION
  9959.  
  9960.       Shifts nBITS bits in nNUM to the right and stores the result in vRESULT. 
  9961.  
  9962.  
  9963.  
  9964.  
  9965.      Intellicomm v2.01               SCRIPT.DOC                            156
  9966.      
  9967.      
  9968.  
  9969.       SHR (SHift Right) is an advanced command for programmers.
  9970.  
  9971.      SEE ALSO
  9972.  
  9973.       SHL
  9974.  
  9975.      EXAMPLE
  9976.  
  9977.       variable result 16
  9978.  
  9979.       SHR result result 2
  9980.       print result   ;prints 4
  9981.  
  9982.       SHR result result 1
  9983.       print result   ;prints 2
  9984.  
  9985.       SHR result result 1
  9986.       print result   ;prints 1
  9987.  
  9988.      STAMP____________________________________________________________________
  9989.  
  9990.      SUMMARY
  9991.  
  9992.       STAMP sCOMMENT ...
  9993.  
  9994.      DESCRIPTION
  9995.  
  9996.       Stamps sCOMMENT in the Usage Log (if open).
  9997.  
  9998.      SEE ALSO
  9999.  
  10000.       LOG, LOGCLOSE
  10001.  
  10002.      EXAMPLE
  10003.  
  10004.       variable waiting_for
  10005.  
  10006.       assign waiting_for "Some Text"
  10007.       waitfor waiting_for 120 error
  10008.       return
  10009.  
  10010.      error:
  10011.       STAMP "WAITFOR unable to find text '" waiting_for "' ... hanging up."
  10012.       hangup
  10013.  
  10014.      STRBLANK_________________________________________________________________
  10015.  
  10016.      SUMMARY
  10017.  
  10018.       STRBLANK vSTRING cCOMMAND
  10019.  
  10020.      DESCRIPTION
  10021.  
  10022.       Checks variable vSTRING to see if it is blank (empty or all whitespace). 
  10023.  
  10024.  
  10025.  
  10026.  
  10027.      Intellicomm v2.01               SCRIPT.DOC                            157
  10028.      
  10029.      
  10030.  
  10031.       If vSTRING is blank, cCOMMAND is executed.  If vSTRING is not blank
  10032.       (contains any characters other than spaces, tabs, carriage returns, line
  10033.       feeds, which are known as 'whitespace') cCOMMAND is skipped.
  10034.  
  10035.      SEE ALSO
  10036.  
  10037.       IF
  10038.  
  10039.      EXAMPLE
  10040.  
  10041.       variable input
  10042.  
  10043.      try_again:
  10044.  
  10045.       boxgets input 15 "Attention" "Please enter input"
  10046.  
  10047.       STRBLANK input goto try_again
  10048.  
  10049.      STRCHR___________________________________________________________________
  10050.      STRCHRI__________________________________________________________________
  10051.  
  10052.      SUMMARY
  10053.  
  10054.       STRCHR vPOSITION sSTRING sCHARACTER [nSTART_POSITION]
  10055.  
  10056.      DESCRIPTION
  10057.  
  10058.       Finds the first occurrance of sCHARACTER in string sSTRING.  If
  10059.       sCHARACTER is found, its numeric position in sSTRING is stored in
  10060.       vPOSITION.  If sCHARACTER is not found, -1 is stored in vPOSITION.
  10061.  
  10062.       nSTART_POSITION is an optional position in sSTRING to start the search
  10063.       at.  If omitted, the search begins at the first character (0) in
  10064.       sSTRING.
  10065.  
  10066.       STRCHR is the case sensitive version.  For example, if "a" is specified
  10067.       as sCHARACTER, it will not match "A" if found in sSTRING.
  10068.  
  10069.       STRCHRI is the case insensitive version.  For example, if "a" is
  10070.       specified as sCHARACTER, it will match "A" if found in sSTRING.
  10071.  
  10072.       NOTE: String positions start at zero.  The first character in sSTRING is
  10073.       0, the second character is 1, etc.
  10074.  
  10075.      SEE ALSO
  10076.  
  10077.       STRRCHR, STRRCHRI, STRPOS, STRPOSI, SUBSTR
  10078.  
  10079.      STRCHR EXAMPLE
  10080.  
  10081.       variable s "This is a string."
  10082.       variable pos
  10083.       
  10084.       STRCHR pos s "."  ;would store 16 in 'pos'
  10085.  
  10086.  
  10087.  
  10088.  
  10089.      Intellicomm v2.01               SCRIPT.DOC                            158
  10090.      
  10091.      
  10092.  
  10093.       if pos = -1
  10094.         print "There is no period in '" s "'"
  10095.       else
  10096.         print "There is a period in '" s "'"
  10097.         print "at position: " pos
  10098.         print "But I'm going to get rid of it..."
  10099.         strdel s pos 1    ;a practical use for knowing the position of a given
  10100.                           ; character in a string...
  10101.       endif
  10102.  
  10103.       STRCHR pos s "."   ;this now stores -1 in 'pos' (no more periods)
  10104.  
  10105.       if pos > -1        ;greater than -1 is another way of checking...
  10106.        print "There are no more periods in this string: " s
  10107.       endif
  10108.  
  10109.      STRCHRI EXAMPLE
  10110.  
  10111.       variable s "This is a string."
  10112.       variable pos
  10113.  
  10114.       STRCHRI pos s "S"   ;this stores 3 in 'pos' since the search is case
  10115.                           ; insignificant, and an 's' exists at position 3
  10116.                           ; (remember, the first character is position 0)
  10117.  
  10118.  
  10119.      STRCPY___________________________________________________________________
  10120.  
  10121.      SUMMARY
  10122.  
  10123.       STRCPY vTARGETSTR sSOURCESTR [nPOSITION] [nNUMCHARS]
  10124.  
  10125.      DESCRIPTION
  10126.  
  10127.       Copies nNUMCHARS characters from sSOURCESTR into vTARGETSTR at
  10128.       nPOSITION.  If nPOSITION is omitted, 0 (first position in vTARGETSTR) is
  10129.       assumed.  If nNUMCHARS is omitted all characters from sSOURCESTR are
  10130.       copied.
  10131.  
  10132.       STRCPY is similar to STRINS but it OVERWRITES existing characters in
  10133.       vTARGETSTR instead of pushing existing characters to the right.  STRCPY
  10134.       is also similar to SETCHRS, but where SETCHRS will not truncate
  10135.       vTARGETSTR after nNUMCHARS characters have been copied: STRCPY *will*
  10136.       truncate vTARGETSTR after nNUMCHARS have been copied from sSOURCESTR. 
  10137.       See the example for details.
  10138.  
  10139.       NOTE: String positions start at zero.  The first character in vTARGETSTR
  10140.       is 0, the second character is 1, etc.
  10141.  
  10142.      SEE ALSO
  10143.  
  10144.       SETCHRS, STRINS, STRSET
  10145.  
  10146.      EXAMPLE
  10147.  
  10148.  
  10149.  
  10150.  
  10151.      Intellicomm v2.01               SCRIPT.DOC                            159
  10152.      
  10153.      
  10154.  
  10155.       variable s
  10156.  
  10157.       STRCPY s "ABCDEF"  ;same as ASSIGN s "ABCDEF"
  10158.       STRCPY s "cd" 2
  10159.       print s            ;prints 'ABcd' (the original 'CD' at position 2 is
  10160.                          ; overwritten, and the 'EF' that originally followed
  10161.                          ; is truncated)
  10162.  
  10163.      STRDEL___________________________________________________________________
  10164.  
  10165.      SUMMARY
  10166.  
  10167.       STRDEL vSTRING nPOSITION [nNUMCHARS]
  10168.  
  10169.      DESCRIPTION
  10170.  
  10171.       Deletes nNUMCHARS characters from vSTRING starting at nPOSITION.  If
  10172.       nNUMCHARS is omitted, all characters from nPOSITION on are deleted.
  10173.  
  10174.       If nNUMCHARS is specified and more characters exist to the right of the
  10175.       deleted text, the characters are placed at nPOSITION.  STRDEL works
  10176.       basically the same way that your word processor would work if you put
  10177.       the cursor under a given character on a line (nPOSITION) and pressed the
  10178.       [Delete] key one or more times (nNUMCHARS).  If you omit nNUMCHARS a
  10179.       "Delete to end of line" (or end of string in this case) is performed.
  10180.  
  10181.       NOTE: String positions start at zero.  The first character in vSTRING is
  10182.       0, the second character is 1, etc.
  10183.  
  10184.      SEE ALSO
  10185.  
  10186.  
  10187.       STRINS, STRSET, STRREPLACE, STRREPLACEI, STRSTRIP, STRTRIM
  10188.  
  10189.      EXAMPLE
  10190.  
  10191.       variable s "Want this, don't want this, want this."
  10192.       variable pos
  10193.       variable num
  10194.  
  10195.       strchr pos s ","   ;get position of first comma
  10196.       STRDEL s pos 1     ;kill the first comma
  10197.  
  10198.       strchr num s ","   ;get position of second comma
  10199.       sub num pos        ;this is how many characters to remove if we want
  10200.                          ; to kill everything from 'pos' (originally the
  10201.                          ; first comma) to the second comma.  'pos' must
  10202.                          ; be subtracted from the position of the first
  10203.                          ; comma to get the number of characters to remove
  10204.       STRDEL pos num
  10205.  
  10206.       print s            ;prints 'Want this, want this.'
  10207.  
  10208.      STRINS___________________________________________________________________
  10209.  
  10210.  
  10211.  
  10212.  
  10213.      Intellicomm v2.01               SCRIPT.DOC                            160
  10214.      
  10215.      
  10216.  
  10217.      SUMMARY
  10218.  
  10219.       STRINS vTARGETSTR sSOURCESTR [nPOSITION] [nNUMCHARS]
  10220.  
  10221.      DESCRIPTION
  10222.  
  10223.       Inserts nNUMCHARS characters from sSOURCESTR into vTARGETSTR at
  10224.       nPOSITION.
  10225.  
  10226.       If nPOSITION is omitted, 0 (first character in vTARGETSTR) is assumed.
  10227.  
  10228.       If nNUMCHARS is omitted the entire sSOURCESTR is inserted in vTARGETSTR
  10229.       at nPOSITION.
  10230.  
  10231.       NOTE 1: String positions start at zero.  The first character in vSTRING
  10232.       is 0, the second character is 1, etc.
  10233.  
  10234.       NOTE 2: STRINS pushes existing characters in vTARGETSTR (from nPOSITION
  10235.       onward) to the right to make room for sSOURCESTR.  It does not overwrite
  10236.       existing characters.  If you want to overwrite existing characters in
  10237.       vTARGETSTR, use STRCPY (or STRREPLACE if appropriate).
  10238.  
  10239.      SEE ALSO
  10240.  
  10241.       STRCAT, STRCPY, STRDEL, STRREPLACE, STRREPLACEI
  10242.  
  10243.      EXAMPLE
  10244.  
  10245.       variable s
  10246.  
  10247.       STRINS s "STRINS text" "inserts " 7
  10248.  
  10249.       print s   ;prints 'STRINS inserts text'
  10250.  
  10251.      STRIPSLASH_______________________________________________________________
  10252.  
  10253.      SUMMARY
  10254.  
  10255.       STRIPSLASH vSTRING
  10256.  
  10257.      DESCRIPTION
  10258.  
  10259.       Checks the end of string vSTRING for a trailing backslach (\) and
  10260.       removes it if one exists.  STRIPSLASH is meant to be used mainly with
  10261.       directory names.
  10262.  
  10263.       EXCEPTION: If the character immediately to the left of the trailing
  10264.       slash is a colon (:) the trailing slash is NOT removed.  In directory
  10265.       names, the backslash next to the drive specifier (C:\) is not a
  10266.       'trailing' slash: it's the leading slash (root directory).  Only
  10267.       trailing slashes are removed by STRIPSLASH.  See example for details.
  10268.  
  10269.      SEE ALSO
  10270.  
  10271.  
  10272.  
  10273.  
  10274.      Intellicomm v2.01               SCRIPT.DOC                            161
  10275.      
  10276.      
  10277.  
  10278.       STRDEL, STRSTRIP, STRTRIM
  10279.  
  10280.      EXAMPLE
  10281.  
  10282.       variable s
  10283.  
  10284.       assign s "C:\"
  10285.       STRIPSLASH s
  10286.       prints           ;prints 'C:\' (again, only trailing slashes are
  10287.      removed:
  10288.                        ; and the slash next to the drive designator is not a
  10289.                        ; trailing slash
  10290.  
  10291.       assign s "C:DIR\"
  10292.       STRIPSLASH s
  10293.       print s          ;prints 'C:DIR'
  10294.  
  10295.       assign s "\DIR\"
  10296.       STRIPSLASH s     ;prints '\DIR'
  10297.  
  10298.  
  10299.      STRITEM__________________________________________________________________
  10300.  
  10301.      SUMMARY
  10302.  
  10303.       STRITEM vITEMBUFFER sSEARCHSTRING nITEMNUMBER [sITEMSEPARATOR]
  10304.  
  10305.      DESCRIPTION
  10306.  
  10307.       Searches sSEARCHSTRING for item number nITEMNUMBER and (if found) stores
  10308.       the item in variable vITEMBUFFER.  If sITEMSEPARATOR is omitted, spaces,
  10309.       tabs and semicolons serve as the default item separator, and spaces/tabs
  10310.       enclosed between single or double quotes (' or ") in sSEARCHSTRING are
  10311.       ignored.  If sITEMSEPARATOR is specified, spaces, tabs and semicolons
  10312.       are ignored and only sITEMSEPARATOR serves to separate one item from
  10313.       another in sSEARCHSTRING.
  10314.  
  10315.      ERRORLEVEL
  10316.  
  10317.       0  Item number nITEMNUMBER was found in sSEARCHSTRING and was stored in
  10318.          vITEMBUFFER.
  10319.       1  Item number nITEMNUMBER does not exist in sSEARCHSTRING.
  10320.  
  10321.      EXAMPLE
  10322.  
  10323.         ;In the first three examples, sITEMSEPARATOR is omitted causing
  10324.         ; STRITEM to use spaces and/or tabs and/or semicolons as the
  10325.         ; item separator; unless the space/tab/semicolon is between quotes.
  10326.  
  10327.       variable s "Item1 Item2  Item3   Item4"
  10328.       variable buf
  10329.       variable i
  10330.  
  10331.       STRITEM buf s 3   ;get item 3 from variable 's'
  10332.  
  10333.  
  10334.  
  10335.  
  10336.      Intellicomm v2.01               SCRIPT.DOC                            162
  10337.      
  10338.      
  10339.  
  10340.       print buf         ;prints "Item3" (no quotes)
  10341.  
  10342.       assign s "'Item 1' 'Item 2'  'Item 3'   'Item 4'"
  10343.  
  10344.       STRITEM buf s 3   ;get item 3 from variable 's'
  10345.       print buf         ;prints "Item 3" (no quotes)
  10346.  
  10347.       getenv s "PATH"   ;get the DOS PATH
  10348.       print "Directories on your PATH:"
  10349.  
  10350.       assign i 1        ;start with item 1
  10351.       while 1
  10352.        getitem buf s i
  10353.        if $ERRORLEVEL > 0 break  ;no more items
  10354.        print buf
  10355.        inc i           ;i = i + 1
  10356.       endwhile
  10357.  
  10358.        ;In the following example, sITENSEPARATOR is specified, causing
  10359.        ; STRITEM to ignore all characters other than the specified
  10360.        ; separator character: "^A" (Ctrl-A).  This can be handy to create
  10361.        ; pseudo 'arrays' with strings.... just separator your array members
  10362.        ; with a control character such as ^A.
  10363.  
  10364.       assign s "Item;1^A  Item;2  ^A  Item;3"
  10365.       getitem buf s 2
  10366.       print buf        ;prints "  Item;2  " (no quotes).  I.e. all characters
  10367.                        ; between the 1st and 2nd ^A are considered the 'item'
  10368.       getitem buf s 3
  10369.       print buf        ;prints "  Item;3" (noting simply that a trailing ^A is
  10370.                        ; NOT needed, but you can specify one if desired).
  10371.  
  10372.      STRLEN___________________________________________________________________
  10373.  
  10374.      SUMMARY
  10375.  
  10376.       STRLEN vLENGTH sSTRING [nPOS]
  10377.  
  10378.      DESCRIPTION
  10379.  
  10380.       Stores the length of string sSTRING from nPOS onward in variable
  10381.       vLENGTH.  If nPOS is omitted, 0 (the beginning of string sSTRING) is
  10382.       assumed.  If nPOS is specified, STRLEN counts the number of characters
  10383.       from nPOS onwards.
  10384.  
  10385.       NOTE: String positions start at zero.  The first character in sSTRING is
  10386.       0, the second character is 1, etc.
  10387.  
  10388.      EXAMPLE
  10389.  
  10390.       variable s "12345"
  10391.       variable len
  10392.  
  10393.       STRLEN len s
  10394.  
  10395.  
  10396.  
  10397.  
  10398.      Intellicomm v2.01               SCRIPT.DOC                            163
  10399.      
  10400.      
  10401.  
  10402.       print len      ;prints '5'
  10403.  
  10404.      STRLOWER_________________________________________________________________
  10405.  
  10406.      SUMMARY
  10407.  
  10408.       STRLOWER vSTRING
  10409.  
  10410.      DESCRIPTION
  10411.  
  10412.       Converts all UPPERCASE characters in vSTRING to lowercase.
  10413.  
  10414.      SEE ALSO
  10415.  
  10416.       STRUPPER
  10417.  
  10418.      EXAMPLE
  10419.  
  10420.       variable s "THIS IS A STRING"
  10421.  
  10422.       STRLOWER s
  10423.       print s        ;prints 'this is a string'
  10424.  
  10425.      STRCAT___________________________________________________________________
  10426.  
  10427.      SUMMARY
  10428.  
  10429.       STRCAT vTARGETSTR sSOURCESTR ...
  10430.  
  10431.      DESCRIPTION
  10432.  
  10433.       Concatenates sSOURCESTR to vTARGETSTR (in English, it adds sSOURCESTR to
  10434.       the end of vTARGETSTR).
  10435.  
  10436.      SEE ALSO
  10437.  
  10438.       STRCPY, STRINS
  10439.  
  10440.      EXAMPLE
  10441.  
  10442.       variable dir1 "C:\DIR1"
  10443.       variable dir2 "C:\DIR2"
  10444.  
  10445.       strcat dir1 ";" dir2
  10446.       print dir1              ;prints 'C:\DIR1;C:\DIR2'
  10447.  
  10448.      STRPAD___________________________________________________________________
  10449.  
  10450.      SUMMARY
  10451.  
  10452.       STRPAD vSTRING sPADCHAR nNEWLENGTH
  10453.  
  10454.      DESCRIPTION
  10455.  
  10456.  
  10457.  
  10458.  
  10459.      Intellicomm v2.01               SCRIPT.DOC                            164
  10460.      
  10461.      
  10462.  
  10463.       Pads the left side of vSTRING with sPADCHAR to make it nNEWLENGTH
  10464.       characters long.  sPADCHAR will normally be " " (a space) to pad a
  10465.       string to a given length for the purpose of lining things up on the
  10466.       screen (PRINT, so that everything is the same length; filenames for
  10467.       example) or writing them to a text file.
  10468.  
  10469.      SEE ALSO
  10470.  
  10471.       STRPADL, STRTRIM
  10472.  
  10473.      EXAMPLE 1
  10474.  
  10475.       variable s "Pad me"
  10476.  
  10477.       STRPAD s "!" 6
  10478.       print s          ;prints 'Pad me' (no change since s is already 6
  10479.                        ; characters long)
  10480.       STRPAD s "!" 10
  10481.       print s          ;prints 'Pad me!!!!'
  10482.  
  10483.      EXAMPLE 2
  10484.  
  10485.       variable f
  10486.       variable s
  10487.       
  10488.       fopen f "MYDATA.DAT" "w"
  10489.  
  10490.       boxgets s 30 "" "Enter Something"
  10491.       STRPAD s " " 30                    ;make it 30 characters long, padding
  10492.                                          ; with spaces (which can be easily
  10493.                                          ; removed with STRTRIM)
  10494.       fputs f s                          ;write it to the file
  10495.       fclose f
  10496.  
  10497.        ;Padding data before writing it to a file is a common technique
  10498.        ; explained in "INTRODUCTION TO FILE INPUT/OUTPUT" in SCRTUTOR.DOC
  10499.  
  10500.      STRPADL__________________________________________________________________
  10501.  
  10502.      SUMMARY
  10503.  
  10504.       STRPAD vSTRING sPADCHAR nNEWLENGTH
  10505.  
  10506.      DESCRIPTION
  10507.  
  10508.       Pads the right side of vSTRING with sPADCHAR to make it nNEWLENGTH
  10509.       characters long.  sPADCHAR will normally be " " (a space) to pad a
  10510.       string to a given length for the purpose of lining things up on the
  10511.       screen (PRINT, so that everything is the same length; filenames for
  10512.       example) or writing them to a text file.  STRPADL is most often used
  10513.       with numbers, to right justify them:
  10514.  
  10515.             1    <-- Pad the left side with X number of spaces to line up
  10516.          1234
  10517.  
  10518.  
  10519.  
  10520.  
  10521.      Intellicomm v2.01               SCRIPT.DOC                            165
  10522.      
  10523.      
  10524.  
  10525.         12345
  10526.  
  10527.      SEE ALSO
  10528.  
  10529.       STRPAD, STRLTRIM
  10530.  
  10531.      EXAMPLE 1
  10532.  
  10533.       variable n1 "1"
  10534.       variable n2 "12"
  10535.       variable n3 "123"
  10536.  
  10537.       STRPAD n1 " " 5
  10538.       STRPAD n2 " " 5
  10539.       STRPAD n3 " " 5
  10540.  
  10541.       print n1         ;prints '    1'
  10542.       print n2         ;prints '   12'
  10543.       print n3         ;prints '  123'
  10544.  
  10545.      STRSET___________________________________________________________________
  10546.  
  10547.      SUMMARY
  10548.  
  10549.       STRSET vTARGETSTR sCHAR nPOSITION nNUM
  10550.  
  10551.      DESCRIPTION
  10552.  
  10553.       Sets nNUM characters of vTARGETSTR to the character sCHAR at nPOSITION. 
  10554.       STRSET is meant to be used to quickly set a string to a given character
  10555.       for drawing lines, or filling the screen with a given character, etc. 
  10556.       See SCRDEMO.SCR for an example.
  10557.  
  10558.       STRSET is not meant to be used to overwrite the middle of a string with
  10559.       a given character: when it finishes writing the last sCHAR character it
  10560.       truncates vTARGETSTR right there.  Use SETCHR to overwrite a portion of
  10561.       a string without truncating it.
  10562.  
  10563.      SEE ALSO
  10564.  
  10565.       SETCHR, SETCHRS
  10566.  
  10567.      EXAMPLE
  10568.       
  10569.       variable s
  10570.  
  10571.       STRSET s "▓" 0 70      ;fill 's' with 70 "▓" characters
  10572.       setchrs s " Hello! " 31 8
  10573.       print s                ;this prints:
  10574.  
  10575.       ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ Hello! ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
  10576.  
  10577.      STRPOS___________________________________________________________________
  10578.  
  10579.  
  10580.  
  10581.  
  10582.      Intellicomm v2.01               SCRIPT.DOC                            166
  10583.      
  10584.      
  10585.  
  10586.      SUMMARY
  10587.  
  10588.       STRPOS vPOSITION sSTRING sSEARCHSTR
  10589.  
  10590.      DESCRIPTION
  10591.  
  10592.       Searches string sSTRING for the string sSEARCHSTR.  If found, the
  10593.       position of sSEARCHSTR in sSTRING is stored in the variable vPOSITION. 
  10594.       If sSEARCHSTR is not found, vPOSITION is set to -1 (negative 1).
  10595.  
  10596.       Case is significant when searching for sSEARCHSTR: "ABC" will not match
  10597.       "abc" or "Abc".  Use STRPOSI for a case insensitive search.
  10598.  
  10599.       NOTE: String positions start at zero.  The first character in vSTRING is
  10600.       0, the second character is 1, etc.
  10601.  
  10602.      SEE ALSO
  10603.  
  10604.       STRPOSI
  10605.  
  10606.      EXAMPLE
  10607.  
  10608.       variable s "ABCDEFGH"
  10609.       variable pos
  10610.       
  10611.       STRPOS pos s "DEF"   ;this stores 3 in 'pos'
  10612.  
  10613.       if pos = -1
  10614.         print "DEF does not exist."
  10615.       else
  10616.         print "DEF exists at position " pos
  10617.       endif
  10618.  
  10619.      STRPOSI__________________________________________________________________
  10620.  
  10621.      SUMMARY
  10622.  
  10623.       STRPOSI vPOSITION sSTRING sSEARCHSTR
  10624.  
  10625.      DESCRIPTION
  10626.  
  10627.       Searches string sSTRING for the string sSEARCHSTR.  If found, the
  10628.       position of sSEARCHSTR in sSTRING is stored in the variable vPOSITION. 
  10629.       If sSEARCHSTR is not found, vPOSITION is set to -1 (negative 1).
  10630.  
  10631.       Case is insignificant when searching for sSEARCHSTR: "ABC" will match
  10632.       "abc" or "Abc".  Use STRPOS for a case sensitive search.
  10633.  
  10634.       NOTE: String positions start at zero.  The first character in vSTRING is
  10635.       0, the second character is 1, etc.
  10636.  
  10637.      SEE ALSO
  10638.  
  10639.       STRPOS
  10640.  
  10641.  
  10642.  
  10643.  
  10644.      Intellicomm v2.01               SCRIPT.DOC                            167
  10645.      
  10646.      
  10647.  
  10648.      EXAMPLE
  10649.  
  10650.       variable s "ABCDEFGH"
  10651.       variable pos
  10652.       
  10653.       STRPOS pos s "def"   ;this stores 3 in 'pos'
  10654.  
  10655.       if pos = -1
  10656.         print "DEF does not exist."
  10657.       else
  10658.         print "DEF exists at position " pos
  10659.       endif
  10660.  
  10661.      STRRCHR__________________________________________________________________
  10662.      STRRCHRI_________________________________________________________________
  10663.  
  10664.      SUMMARY
  10665.  
  10666.       STRRCHR vPOSITION sSTRING sCHARACTER
  10667.       STRRCHRI vPOSITION sSTRING sCHARACTER
  10668.  
  10669.      DESCRIPTION
  10670.  
  10671.       Finds the *last* occurrance of sCHARACTER in sSTRING.  If sCHARACTER is
  10672.       found, its numeric position in sSTRING is stored in variable vPOSITION. 
  10673.       If sCHARACTER is not found, -1 is stored in vPOSITION.
  10674.  
  10675.       STRRCHR is the case sensitive version.  For example, if "a" is specified
  10676.       as sCHARACTER, it will not match "A" if found in sSTRING.
  10677.  
  10678.       STRRCHRI is the case insensitive version.  For example, if "a" is
  10679.       specified as sCHARACTER, it will match "A" if found in sSTRING.
  10680.  
  10681.       NOTE: String positions start at zero.  The first character in sSTRING is
  10682.       0, the second character is 1, etc.
  10683.  
  10684.      SEE ALSO
  10685.  
  10686.       STRCHR, STRCHRI, STRPOS, STRPOSI, SUBSTR
  10687.  
  10688.      STRRCHR EXAMPLE
  10689.  
  10690.        variable pos
  10691.        variable s "This is a string"
  10692.        variable s2
  10693.  
  10694.        STRRCHR pos s " "   ;finds the LAST space in variable 's'
  10695.  
  10696.        if pos = -1
  10697.         print "No spaces exist in 's'"
  10698.        else
  10699.         inc pos            ;pos = pos + 1 (get past the space)
  10700.         substr s2 s
  10701.        endif
  10702.  
  10703.  
  10704.  
  10705.  
  10706.      Intellicomm v2.01               SCRIPT.DOC                            168
  10707.      
  10708.      
  10709.  
  10710.      STRRCHRI EXAMPLE
  10711.  
  10712.  
  10713.      STRREPLACE_______________________________________________________________
  10714.      STRREPLACEI______________________________________________________________
  10715.  
  10716.      SUMMARY
  10717.  
  10718.       STRREPLACE vTARGETSTR sSEARCHSTR sREPLACESTR
  10719.       STRREPLACEI vTARGETSTR sSEARCHSTR sREPLACESTR
  10720.  
  10721.      DESCRIPTION
  10722.  
  10723.       Searches vTARGETSTR for all occurrances of sSEARCHSTR and replaces them
  10724.       with sSREPLACESTR.  SRREPLACE is case sensitive (occurrances of "abc"
  10725.       will not replace occurrances of "ABC") while STRREPLACEI is case
  10726.       insensitive (occurrances of "abc" will replace occurrances of "ABC")
  10727.  
  10728.      SEE ALSO
  10729.  
  10730.       STRPOS, STRPOSI
  10731.  
  10732.      STRREPLACE EXAMPLE
  10733.  
  10734.       variable s "IBM XT"
  10735.  
  10736.       STRREPLACE s "xt" "486"
  10737.       print s                  ;prints 'IBM XT' (no change since STRREPLACE
  10738.                                ; is case sensitive and "xt" doesn't match "XT"
  10739.  
  10740.       strreplace s "XT" "486"
  10741.       print s                  ;prints 'IBM 486'
  10742.  
  10743.      STRREPLACEI EXAMPLE
  10744.  
  10745.       variable s "IBM XT"
  10746.  
  10747.       STRREPLACEI s "xt" "486"
  10748.       print s                  ;prints 'IBM 486'
  10749.  
  10750.      STRSTRIP_________________________________________________________________
  10751.  
  10752.      SUMMARY
  10753.  
  10754.       STRSTRIP vSTRING sCHAR
  10755.  
  10756.      DESCRIPTION
  10757.  
  10758.       Strips all occurrances of character sCHAR from string vSTRING.
  10759.  
  10760.      SEE ALSO
  10761.  
  10762.       STRDEL, STRTRIM
  10763.  
  10764.  
  10765.  
  10766.  
  10767.      Intellicomm v2.01               SCRIPT.DOC                            169
  10768.      
  10769.      
  10770.  
  10771.      EXAMPLE
  10772.  
  10773.       variable s "This is a string"
  10774.  
  10775.       STRSTRIP s " "   ;strip all spaces
  10776.       print s          ;prints 'Thisisastring'
  10777.  
  10778.      STRBTRIM_________________________________________________________________
  10779.      STRLTRIM_________________________________________________________________
  10780.      STRTRIM__________________________________________________________________
  10781.  
  10782.      SUMMARY
  10783.  
  10784.       STRBTRIM vSTRING
  10785.       STRLTRIM vSTRING
  10786.       STRTRIM vSTRING
  10787.  
  10788.      DESCRIPTION
  10789.  
  10790.       The STRxTRIM commands are used to trim extra whitespace characters from
  10791.       string vSTRING.
  10792.  
  10793.       STRBTRIM trims whitespace from both sides of vSTRING.
  10794.       STRLTRIM trims whitespace only from the left side of vSTRING.
  10795.       STRTRIM  trims whitespace only from the right side of vSTRING.
  10796.  
  10797.       ['Whitespace' includes spaces, tabs, carriage returns, line feeds and
  10798.       form feeds.]
  10799.  
  10800.      SEE ALSO
  10801.  
  10802.       STRDEL, STRSTRIP
  10803.  
  10804.      EXAMPLE
  10805.  
  10806.       variable s
  10807.  
  10808.       assign s "  string data  "
  10809.       STRBTRIM s
  10810.       print s                    ;prints 'string data'
  10811.  
  10812.       assign s "  string data  "
  10813.       STRLTRIM s
  10814.       print s                    ;prints 'string data  '
  10815.  
  10816.       assign s "  string data  "
  10817.       STRTRIM s
  10818.       print s                    ;prints '  string data'
  10819.  
  10820.      STRUPPER_________________________________________________________________
  10821.  
  10822.      SUMMARY
  10823.  
  10824.       STRUPPER vSTRING
  10825.  
  10826.  
  10827.  
  10828.  
  10829.      Intellicomm v2.01               SCRIPT.DOC                            170
  10830.      
  10831.      
  10832.  
  10833.      DESCRIPTION
  10834.  
  10835.       Converts all lowercase characters in vSTRING to UPPERCASE.
  10836.  
  10837.      SEE ALSO
  10838.  
  10839.       STRLOWER
  10840.  
  10841.      EXAMPLE
  10842.  
  10843.       variable s "this is a string"
  10844.       STRUPPER s
  10845.       print s        ;prints 'THIS IS A STRING'
  10846.  
  10847.      SUB______________________________________________________________________
  10848.  
  10849.      SUMMARY
  10850.  
  10851.       SUB vREMAINDER nMINUEND nSUBTRAHEND
  10852.  
  10853.      DESCRIPTION
  10854.  
  10855.       Minuend and subtrahend?  Well, that's what my old college math book
  10856.       says.  <grin>  SUBtracts nSUBTRAHEND from nMINUEND and stores the result
  10857.       in nREMAINDER.  If you somehow forgot which number is called the
  10858.       'subtrahend' and which is the 'minuend':
  10859.  
  10860.          10   <-- Minuend
  10861.        -  5   <-- Subtrahend
  10862.        ----
  10863.           5   <-- Remainder (or Difference)
  10864.  
  10865.       We learn something new every day...
  10866.  
  10867.      SEE ALSO
  10868.  
  10869.       ADD, DIV, MUL, SUB
  10870.  
  10871.      EXAMPLE
  10872.  
  10873.       variable result
  10874.       SUB result 10 5  ;stores 10 - 5 (5) in variable 'result'
  10875.       print result
  10876.  
  10877.      SUBSTR___________________________________________________________________
  10878.  
  10879.      SUMMARY
  10880.  
  10881.       SUBSTR vTARGET sSOURCE nPOSITION [nNUM]
  10882.  
  10883.      DESCRIPTION
  10884.  
  10885.       Copies nNUM characters from nPOSITION in string sSOURCE to variable
  10886.       vTARGET.  If nNUM is specified, all characters from nNUM position in
  10887.  
  10888.  
  10889.  
  10890.  
  10891.      Intellicomm v2.01               SCRIPT.DOC                            171
  10892.      
  10893.      
  10894.  
  10895.       sSOURCE are counted.  If nNUM is omitted, 0 (the beginning of sSOURCE)
  10896.       is assumed.
  10897.  
  10898.       NOTE: String positions start at zero.  The first character in vSTRING is
  10899.       0, the second character is 1, etc.
  10900.  
  10901.      SEE ALSO
  10902.  
  10903.       STRCPY
  10904.  
  10905.      EXAMPLE
  10906.  
  10907.       variable s
  10908.  
  10909.       SUBSTR s "This is a string!" 10 6
  10910.       print s                            ;prints 'string'
  10911.  
  10912.  
  10913.      SWITCH___________________________________________________________________
  10914.       CASE____________________________________________________________________
  10915.       ENDCASE_________________________________________________________________
  10916.       DEFAULT_________________________________________________________________
  10917.       ENDSWITCH_______________________________________________________________
  10918.  
  10919.      SUMMARY
  10920.  
  10921.       SWITCH vVARIABLE
  10922.        CASE
  10923.        [CASE]
  10924.        [...]
  10925.          cCOMMAND
  10926.          [cCOMMAND]
  10927.          [...]
  10928.        ENDCASE
  10929.        [CASE]
  10930.        [...]
  10931.          [cCOMMAND]
  10932.          [...]
  10933.        [ENDCASE]
  10934.        [DEFAULT]
  10935.          [cCOMMAND]
  10936.          [...]
  10937.        [ENDCASE]
  10938.       ENDSWITCH
  10939.  
  10940.      DESCRIPTION
  10941.  
  10942.       Compares the contents of vVARIABLE for equality to the CASE
  10943.       statement(s).  If a match is found, the command(s) between the matching
  10944.       CASE/ENDCASE are executed.  If no match is found, and a DEFAULT case is
  10945.       specified, the commands between DEFAULT/ENDCASE are executed.  If no
  10946.       DEFAULT is specified and no matching CASE is found, all commands between
  10947.       SWITCH/ENDCASE are ignored.
  10948.  
  10949.  
  10950.  
  10951.  
  10952.      Intellicomm v2.01               SCRIPT.DOC                            172
  10953.      
  10954.      
  10955.  
  10956.       SWITCH is used when comparing many conditions (such as menu selections),
  10957.       where using IF/ELSE/ENDIF would be impractical.
  10958.  
  10959.      ERRORLEVEL
  10960.  
  10961.       SWITCH, ENDSWITCH, CASE, ENDCASE, DEFAULT do not change $ERRORLEVEL.
  10962.  
  10963.      SEE ALSO
  10964.  
  10965.       IF, WHILE
  10966.  
  10967.      NUMERIC SWITCH EXAMPLE
  10968.  
  10969.       menudefine "Option ~1" "Option ~2" "Option ~3" "e~Xit"
  10970.       menuboxv "Menu" "Select an option"
  10971.  
  10972.       SWITCH $MENUSELECTION
  10973.         CASE 1                ;is $MENUSELECTION equal to 1?
  10974.  
  10975.           print "Option 1 was selected."
  10976.           ;you can carry out any number of commands here before the ENDCASE
  10977.         ENDCASE
  10978.         CASE 2                ;is $MENUSELECTION equal to 2?
  10979.           print "Option 2 was selected."
  10980.         ENDCASE
  10981.         CASE 3                ;is $MENUSELECTION equal to 3?
  10982.           print "Option 3 was selected."
  10983.         ENDCASE
  10984.         DEFAULT
  10985.           print "[Esc] was pressed, or eXit was selected."
  10986.         ENDCASE
  10987.       ENDSWITCH
  10988.  
  10989.      STRING SWITCH EXAMPLE
  10990.  
  10991.       variable old_dir $CUR_DIR
  10992.       variable fname
  10993.       variable ext
  10994.  
  10995.       findfirst fname "*.*"
  10996.  
  10997.       while $ERRORLEVEL = 0          ;while a file is found
  10998.         fnstrip ext fname 15         ;get file .EXT (extension)
  10999.  
  11000.         SWITCH ext
  11001.           CASE ".ZIP"                ;is 'ext' equal to ".ZIP" ?
  11002.             dos "PKZIP /v " fname 
  11003.           ENDCASE
  11004.           CASE ".ARJ"                ;is 'ext' equal to ".ARJ" ?
  11005.             dos "ARJ l " fname 
  11006.           ENDCASE
  11007.           CASE ".LHA"                ;is 'ext' equal to ".LHA" ?
  11008.             dos "LHA l " fname
  11009.           ENDCASE
  11010.  
  11011.  
  11012.  
  11013.  
  11014.      Intellicomm v2.01               SCRIPT.DOC                            173
  11015.      
  11016.      
  11017.  
  11018.           DEFAULT
  11019.             print fname " is not a .ZIP, .ARJ, or .LHA file."
  11020.           ENDCASE
  11021.         ENDSWITCH
  11022.  
  11023.         findnext fname
  11024.       endwhile
  11025.  
  11026.      SYSTEM___________________________________________________________________
  11027.  
  11028.      SUMMARY
  11029.  
  11030.       SYSTEM [nHANGUP] [nERRORLEVEL]
  11031.  
  11032.      DESCRIPTION
  11033.  
  11034.       SYSTEM closes the current COM port (if open), closes all files, etc.,
  11035.       hangs up/stays connected or asks the user what to do, then exits back to
  11036.       the 'caller'.  The caller could be DOS, or a .BAT file, or a menu system
  11037.       (Windows, DESQview, etc): whatever called ICOM.EXE originally.  
  11038.  
  11039.       nHANGUP is optional and can be either 1 (hangup unconditionally), or 2
  11040.       (stay connected) or 0/any other number (or nothing) which causes SYSTEM
  11041.       to ask the user whether to disconnect, if connected.
  11042.  
  11043.       nERRORLEVEL is an optional error code which can be tested with the .BAT
  11044.       ERRORLEVEL statement.  See the example for usage.
  11045.  
  11046.      SEE ALSO
  11047.  
  11048.       EXIT
  11049.  
  11050.      EXAMPLE
  11051.  
  11052.       send "SOME COMMAND"
  11053.       waitfor "Some BBS Prompt" 120 ERROR
  11054.       SYSTEM              ;exit with no errorlevel, asking the user whether to
  11055.                           ;disconnect or not (SYSTEM 0 0 does the same)
  11056.  
  11057.      ERROR:
  11058.       SYSTEM 1 1          ;hangup, exit to DOS with errorlevel set to 1
  11059.  
  11060.      ;If you called a script like this from a .BAT file, you could test the
  11061.      ;ERRORLEVEL to see whether the script was successful or not:
  11062.      ;
  11063.      ; rem SOMEBAT.BAT
  11064.      ; ICOM.EXE /scr:MYSCRIPT.SCR
  11065.      ; if errorlevel 1 goto ERROR
  11066.      ; rem No errors, do whatever needs doing here
  11067.      ; :ERROR
  11068.  
  11069.      TAGGER___________________________________________________________________
  11070.  
  11071.      SUMMARY
  11072.  
  11073.  
  11074.  
  11075.  
  11076.      Intellicomm v2.01               SCRIPT.DOC                            174
  11077.      
  11078.      
  11079.  
  11080.       TAGGER [sCATALOG]
  11081.  
  11082.      DESCRIPTION
  11083.  
  11084.       Enters the File Tagger.  If sCATALOG is specified, the catalog is loaded
  11085.       for viewing.  If sCATALOG is omitted, the NEWFILES catalog is loaded.
  11086.  
  11087.       NOTE: Control will not return to your script until the user exits the
  11088.       File Tagger.
  11089.  
  11090.      SEE ALSO
  11091.  
  11092.       DIAL, FILEMAN, SCRIPT
  11093.  
  11094.      EXAMPLE
  11095.  
  11096.       pause "Enter the File Tagger to Tag files for uploading..."
  11097.       TAGGER "FILELIST"
  11098.  
  11099.      TERMINAL_________________________________________________________________
  11100.  
  11101.      SUMMARY
  11102.  
  11103.       TERMINAL
  11104.  
  11105.      DESCRIPTION
  11106.  
  11107.       TERMINAL is an advanced command that won't be needed by most script
  11108.       writers.  If your script is having problems in that it doesn't display
  11109.       characters from the BBS and doesn't process keystrokes (i.e. [Alt-Z] to
  11110.       call up the Terminal menu), then TERMINAL will solve the problem. 
  11111.       Otherwise, only read this if you're not faint-of-heart and are looking
  11112.       to conquer the entire script language.
  11113.  
  11114.       The TERMINAL command makes a call to Icom's "terminal handler", which is
  11115.       the Icom function that gets and handles characters from the COM port (if
  11116.       any), and processes user keystrokes and mouse clicks (if any).  To make
  11117.       scripts easier to write, TERMINAL is automatically called for you in the
  11118.       following locations:
  11119.  
  11120.        + After a HANGUP command.
  11121.        + After a PORT command.
  11122.        + After a SEND, SENDNC, SENDNP, SENDNCP command.
  11123.        + After a SENDBIF command.
  11124.        + After a SETCOMM command.
  11125.        + Repeatedly during a WAITFOR command.
  11126.        + After a WAITUNTIL command.
  11127.  
  11128.       [During some other commands, such as UPLOAD and DOWNLOAD, the TERMINAL
  11129.       command is not used... but characters are still sent/received.  All
  11130.       protocols deal directly with the COM port without going through the
  11131.       terminal.]
  11132.  
  11133.       WITHOUT this automatic use of the TERMINAL command, nothing from the BBS
  11134.  
  11135.  
  11136.  
  11137.  
  11138.      Intellicomm v2.01               SCRIPT.DOC                            175
  11139.      
  11140.      
  11141.  
  11142.       would ever be displayed on the screen while your script was running
  11143.       (characters would simply fill up Icom's internal receive buffer until
  11144.       flow control was activated).  With Icom v1, before script 'loops' were
  11145.       introduced, it was almost impossible to run into a situation where Icom
  11146.       wouldn't call TERMINAL automatically through one script command or
  11147.       another, for longer than a millisecond or two.  With the v2 script
  11148.       language it's possible to enter a WHILE loop and NEVER call the TERMINAL
  11149.       handler (depending on how long the loop executes for and what commands
  11150.       you execute in the loop).  When in a loop, and not using any of the
  11151.       above commands which automatically call TERMINAL for you, do this if you
  11152.       want the terminal display to be updated in your loop:
  11153.  
  11154.        WHILE <condition>   ;some valid WHILE condition
  11155.          TERMINAL          ;call the TERMINAL handler
  11156.          ...               ;then do whatever it is you're doing in the loop
  11157.        ENDWHILE
  11158.  
  11159.       ...or, if you don't use loops and still have problems, simply place a
  11160.       few TERMINAL commands randomly around your script until it works. 
  11161.       *Each* TERMINAL command in your script will empty the entire Receive
  11162.       Buffer to the screen, and process any waiting keystrokes: both of which
  11163.       are buffered until they're handled by a call to TERMINAL.
  11164.  
  11165.       Another way to look at the TERMINAL command is that by NOT calling it,
  11166.       and by not using script commands that call it automatically (i.e. SEND,
  11167.       etc), you can PREVENT BBS characters from being displayed on the screen
  11168.       and can intercept keystrokes that would otherwise go to the Terminal
  11169.       handler (also see the $KEY_CHECK variable).  You needn't worry about
  11170.       losing data from the BBS while you're not using TERMINAL... at least as
  11171.       long as you've got your "Flow Control" set up properly on your modem and
  11172.       in Icom ("Software flow control": XON/XOFF, etc., or "Hardware flow
  11173.       control": CTS/RTS, etc).  Icom has a program called an "interrupt
  11174.       handler" that runs in the background, and is executed and driven
  11175.       entirely by the computer hardware (the COM port), to process incoming
  11176.       characters from the BBS.  When a character is received from the modem,
  11177.       the COM port sends an interrupt, which in turn causes your processor to
  11178.       call Intellicomm's interrupt handler, which in turn places the character
  11179.       into Icom's internal "Receive Buffer" (the size is configurable in the
  11180.       main setup; it defaults to 4 Kbytes).  When the receive buffer is about
  11181.       80% full, Icom's interrupt handler activates "flow control", telling the
  11182.       modem (and the BBS) to STOP sending data, and this will happen whether
  11183.       you call TERMINAL or not.  [Sometimes it takes a second or two for the
  11184.       BBS to stop sending, and that's why flow control is activated when the
  11185.       buffer is 80% full instead of waiting until it's ready to overflow.] 
  11186.       The characters in the Receive Buffer (and keystrokes/mouse clicks in the
  11187.       keystroke buffer) simply won't be displayed to the screen or acted
  11188.       upon... they'll sit in the Receive Buffer waiting for you to call
  11189.       TERMINAL.
  11190.  
  11191.      EXAMPLE
  11192.  
  11193.       variable key          ;define a variable to hold keystrokes
  11194.       variable old_kcheck $KEY_CHECK
  11195.  
  11196.  
  11197.  
  11198.  
  11199.      Intellicomm v2.01               SCRIPT.DOC                            176
  11200.      
  11201.      
  11202.  
  11203.       assign $KEY_CHECK 0   ;shut off the Terminal's keystroke handler
  11204.  
  11205.       msgopen "I'm not doing anything until you press [Esc]!"
  11206.  
  11207.        ;since there is no TERMINAL command in this loop, and
  11208.        ;since INKEY doesn't call TERMINAL automatically, nothing
  11209.        ;from the BBS is displayed on the screen, and no keystrokes
  11210.        ;(other than ESC) are processed.  Total control...
  11211.  
  11212.       WHILE key <> "^["    ;while key is not equal to the ESC key
  11213.        inkey key
  11214.       ENDWHILE
  11215.       
  11216.       msgclose
  11217.       assign $KEY_CHECK old_kcheck
  11218.       TERMINAL             ;kaboom, all characters received from the modem
  11219.                            ; during the pause are now displayed rapidly
  11220.  
  11221.       Alternatively, instead of calling TERMINAL, you could also use CGETC and
  11222.       process characters one at a time in a loop.
  11223.  
  11224.      TIMER____________________________________________________________________
  11225.  
  11226.      SUMMARY
  11227.  
  11228.       TIMER [nTENTHS]
  11229.  
  11230.      DESCRIPTION
  11231.  
  11232.       Starts a timer that will expire in nTENTHS of a second.  Use TIMEUP to
  11233.       determine whether the timer has expired.  Multiple calls to TIMER
  11234.       cancels the previous TIMER command (if any).
  11235.  
  11236.       If nTENTHS is zero or omitted, the timer never expires (until the script
  11237.       ends).
  11238.  
  11239.      SEE ALSO
  11240.  
  11241.       TIMERTOTAL, TIMEUP
  11242.  
  11243.      EXAMPLE
  11244.  
  11245.       TIMER 100      ;100 tenths (10 seconds)
  11246.  
  11247.       msgopen "Waiting 10 seconds..."
  11248.       while 1
  11249.        timeup break
  11250.       endwhile
  11251.       msgclose
  11252.  
  11253.      TIMERTOTAL_______________________________________________________________
  11254.  
  11255.      SUMMARY
  11256.  
  11257.  
  11258.  
  11259.  
  11260.      Intellicomm v2.01               SCRIPT.DOC                            177
  11261.      
  11262.      
  11263.  
  11264.       TIMERTOTAL vTOTAL
  11265.  
  11266.      DESCRIPTION
  11267.  
  11268.       Stores in vTOTAL the total tenths of a second that have elapsed since
  11269.       the last TIMER command.
  11270.  
  11271.      SEE ALSO
  11272.  
  11273.       TIMER, TIMEUP
  11274.  
  11275.      EXAMPLE
  11276.  
  11277.       variable total
  11278.  
  11279.       cls
  11280.       timer
  11281.  
  11282.       while 1
  11283.        timertotal total
  11284.        printraw 1 1 $SCRN_COLOR "TIMERTOTAL: " total
  11285.        if total > 100 break                         ;break after 10 seconds
  11286.       endwhile
  11287.  
  11288.      TIMEUP___________________________________________________________________
  11289.  
  11290.      SUMMARY
  11291.  
  11292.       TIMEUP cCOMMAND
  11293.  
  11294.      DESCRIPTION
  11295.  
  11296.       If the last timer started with the TIMER command has expired, cCOMMAND
  11297.       is executed.  If the timer has not expired, cCOMMAND is skipped.
  11298.  
  11299.      SEE ALSO
  11300.  
  11301.       TIMER, TIMERTOTAL
  11302.  
  11303.      EXAMPLE
  11304.  
  11305.       timer 100      ;100 tenths (10 seconds)
  11306.  
  11307.       msgopen "Waiting 10 seconds..."
  11308.       while 1
  11309.        TIMEUP break
  11310.       endwhile
  11311.       msgclose
  11312.  
  11313.      TONE_____________________________________________________________________
  11314.  
  11315.      SUMMARY
  11316.  
  11317.       TONE nFREQUENCY nDURATION
  11318.  
  11319.  
  11320.  
  11321.  
  11322.      Intellicomm v2.01               SCRIPT.DOC                            178
  11323.      
  11324.      
  11325.  
  11326.      DESCRIPTION
  11327.  
  11328.       Sounds a tone of nFREQUENCY for nDURATION tenths of a second on the PC
  11329.       Speaker.  The higher the number is for nFREQUENCY, the higher the sound
  11330.       is.  The following list of numbers can be used as a reference for
  11331.       nFREQUENCY.  Though the list does not contain all possible frequencies,
  11332.       it should get you started and allow experimentation:
  11333.  
  11334.        247   B
  11335.        262   C
  11336.        277   C# (# = sharp)
  11337.        294   D
  11338.        311   D#
  11339.        330   E
  11340.        349   F
  11341.        370   F#
  11342.        392   G
  11343.        415   G#
  11344.        440   A
  11345.        466   A#
  11346.        494   B
  11347.        523   Middle C
  11348.        554   C#
  11349.        587   D
  11350.        622   D#
  11351.        659   E
  11352.        698   F
  11353.        740   F#
  11354.        784   G
  11355.        880   A
  11356.        988   B
  11357.        1046  C
  11358.        1175  D
  11359.        1319  E
  11360.        1397  F
  11361.        1568  G
  11362.        1760  A
  11363.        1976  B
  11364.  
  11365.      SEE ALSO
  11366.  
  11367.       ALARM, BEEP
  11368.  
  11369.      EXAMPLE
  11370.  
  11371.        TONE 440 10      ;A
  11372.        delaync 1        ;staccato (distinctive notes that don't blend)
  11373.        TONE 494 10      ;B
  11374.        delaync 1
  11375.        TONE 523 10      ;C
  11376.  
  11377.      TXFLUSH__________________________________________________________________
  11378.  
  11379.      SUMMARY
  11380.  
  11381.  
  11382.  
  11383.  
  11384.      Intellicomm v2.01               SCRIPT.DOC                            179
  11385.      
  11386.      
  11387.  
  11388.       TXFLUSH
  11389.  
  11390.      DESCRIPTION
  11391.  
  11392.       Clears (flushes) the COM port Transmit Buffer.  Characters sent to the
  11393.       modem using SEND, SENDNC, SENDBIF, etc., are not transmitted
  11394.       immediately: they are placed in a Transmit Buffer until the modem is
  11395.       ready to accept the characters.  Use TXFLUSH to clear this buffer if
  11396.       necessary.
  11397.  
  11398.      SEE ALSO
  11399.  
  11400.       RXFLUSH
  11401.  
  11402.      UPDATEDNDX_______________________________________________________________
  11403.  
  11404.      SUMMARY
  11405.  
  11406.       UPDATEDNDX
  11407.  
  11408.      DESCRIPTION
  11409.  
  11410.       Uploades the DOWNLOAD.NDX (same as selecting Tools | Update DOWNLOAD.NDX
  11411.       from the File Tagger).  'Update' means that all directories the user has
  11412.       defined in the main setup 'DOWNLOAD.NDX Directories' item will be
  11413.       scanned, and all files in these directories that do not exist in the
  11414.       DOWNLOAD.NDX index will be added.  This is how Intellicomm keeps track
  11415.       of files you've downloaded, and 
  11416.  
  11417.       On new files imports and automated downloads, Tagger ignores filenames
  11418.       that exist in the DOWNLOAD.NDX.
  11419.  
  11420.      EXAMPLE
  11421.  
  11422.       waitfor "Begin your download..."
  11423.       download "Z"
  11424.       UPDATEDNDX
  11425.  
  11426.      UPLOAD___________________________________________________________________
  11427.  
  11428.      SUMMARY
  11429.  
  11430.       UPLOAD sPROTOCOL sFILENAME1 [sFILENAME2 ...]
  11431.  
  11432.      DESCRIPTION
  11433.  
  11434.       Uploads sFILENAME1 and [sFILENAME 2 ...] if specified using transfer
  11435.       protocol sPROTOCOL.  sFILENAME1 is required by all protocols and may be
  11436.       a filename (FILENAME.EXT) or an explicit file and path
  11437.       (D:\PATH\FILENAME.EXT).  If a lone filename (no D: or \PATH\) is
  11438.       specified in any of the sFILENAME? parameters, UPLOAD searches:
  11439.  
  11440.       1) The directories on the Upload PATH ($UL_PATH), defined in the main
  11441.          setup or the current BIF.
  11442.  
  11443.  
  11444.  
  11445.  
  11446.      Intellicomm v2.01               SCRIPT.DOC                            180
  11447.      
  11448.      
  11449.  
  11450.       2) The current Download Directory ($DL_DIR), defined in the main setup
  11451.          or the current BIF.
  11452.       3) If *pathsch (main setup item "Use PATH to Locate Files") is non-zero,
  11453.          all directories on the DOS PATH are then searched if the file cannot
  11454.          be found in any of the directories above.
  11455.  
  11456.       Note that sFILENAME1 may also be specified as "@FILELIST", where
  11457.       @FILELIST is a 'list' of files.  The contents of the file 'FILELIST'
  11458.       would contain one or more filenames to upload (again, each file on the
  11459.       list may include a D:\PATH\ if necessary), with each filename or
  11460.       filespec on a separate line.
  11461.  
  11462.       sFILENAME2 and beyond are only supported by the 'batch' protocols below
  11463.       which have an asterisk following their name.  Further, batch protocols
  11464.       accept the DOS wildcard characters * and ? in any of the sFILENAMEn
  11465.       parameters, whether specified explicitly or via a @FILELIST.
  11466.  
  11467.       sPROTOCOL is the 'hotkey' used to select the protocol from the protocol
  11468.       menu from Terminal Mode (including external protocols, if any are
  11469.       installed):
  11470.  
  11471.       "A" = ASCII
  11472.       "R" = Relaxed Xmodem
  11473.       "X" = Xmodem
  11474.       "1" = Xmodem-1K
  11475.       "K" = Xmodem-1K-G
  11476.       "Y" = Ymodem*
  11477.       "G" = Ymodem-G*
  11478.       "Z" = Zmodem*
  11479.  
  11480.       NOTE: Ymodem, Ymodem-G and Zmodem are 'batch' transfer protocols.  This
  11481.       means that they can upload several files using a single UPLOAD command.
  11482.  
  11483.      ERRORLEVEL
  11484.  
  11485.       0  Transfer successful (if batch, all files were uploaded)
  11486.       1  User abort ([Esc] pressed)
  11487.       2  Connection lost
  11488.       3  Remote (BBS protocol) cancelled
  11489.       4  Disk read error
  11490.       5  Bad external protocol (if called an external and not found)
  11491.       6  Flow control error (activated by remote and not deactivated)
  11492.       7  Miscellaneous protocol error (too many timeouts, NAKs, etc).
  11493.  
  11494.      SEE ALSO
  11495.  
  11496.       DOWNLOAD
  11497.  
  11498.      EXAMPLE 1
  11499.       
  11500.       UPLOAD "1" "FILENAME.ZIP" ;Upload FILENAME.ZIP using Xmodem-1K
  11501.  
  11502.      EXAMPLE 2
  11503.  
  11504.  
  11505.  
  11506.  
  11507.      Intellicomm v2.01               SCRIPT.DOC                            181
  11508.      
  11509.      
  11510.  
  11511.        ;Upload D:\FILE1.ZIP, C:\TEMP\FILE2.ZIP and FILE3.ZIP using Ymodem
  11512.  
  11513.       UPLOAD "Y" "D:\FILE1.ZIP" "C:\TEMP\FILE2.ZIP" "FILE3.ZIP"
  11514.  
  11515.      EXAMPLE 3
  11516.  
  11517.        ;Example upload using a file list
  11518.  
  11519.       variable f                ;used to hold the file handle (number)
  11520.       fopen f "UPLIST.$$$" "w"  ;create a file called UPLIST.$$$, "w"rite mode
  11521.       fputs f "\DIR1\FILE1.ZIP" ;fputs writes \DIR1\FILE1.ZIP to the file
  11522.       fputs f "\DIR2\*.*"       ;all files in \DIR2
  11523.       fputs f "\DIR3\FILE?.*"
  11524.        ; ... etc
  11525.       fclose f                  ;close the file (important)
  11526.  
  11527.       UPLOAD "Z" "@UPLIST.$$$"  ;@ tells the protocol to use a file list
  11528.       delete "UPLIST.$$$"       ;delete the list
  11529.  
  11530.      VARIABLE_________________________________________________________________
  11531.  
  11532.      SUMMARY
  11533.  
  11534.       VARIABLE vNAME
  11535.  
  11536.      DESCRIPTION
  11537.  
  11538.       Creates a variable called vNAME.
  11539.  
  11540.      SEE ALSO
  11541.  
  11542.       SCRTUTOR.DOC explains variables in detail.
  11543.  
  11544.      EXAMPLE
  11545.  
  11546.       VARIABLE my_variable
  11547.  
  11548.      VPUSH____________________________________________________________________
  11549.  
  11550.      SUMMARY
  11551.  
  11552.       VPUSH [nX1] [nY1] [nX2] [nY2]
  11553.  
  11554.      DESCRIPTION
  11555.  
  11556.       Saves screen data (including colors) to an internal memory buffer for
  11557.       later restoration with VPOP.  The parameters following VPUSH are
  11558.       optional screen coordinates which allow you to save a portion of the
  11559.       screen instead of saving the entire screen (the square brackets denote
  11560.       optional items; you must not use square brackets when specifying the
  11561.       parameters).  nX1 is the top screen column (left to right) nY1 is the
  11562.       top screen row (top to bottom) nX2 is the ending screen colum and nY2 is
  11563.       the ending screen row.  
  11564.  
  11565.  
  11566.  
  11567.  
  11568.      Intellicomm v2.01               SCRIPT.DOC                            182
  11569.      
  11570.      
  11571.  
  11572.       If you omit one or more of the screen coordinates, the screen limit is
  11573.       assumed.  The limits for nX1, nY1 are 1, 1 (top screen corner) and the
  11574.       limits for nX2, nY2 are $SCRN_WIDTH, $SCRN_HEIGHT (System Variables
  11575.       which hold the current width and height of the screen).  VPUSH does NOT
  11576.       observe the screen limits set by the WNDOPEN or WINDOW commands.  No
  11577.       matter what the current WNDOPEN/WINDOW limits are, 1, 1 is always the
  11578.       TOP of the screen to VPUSH and $SCRN_WIDTH, $SCRN_HEIGHT (the total
  11579.       screen witdh and height) are the bottom of the screen.
  11580.  
  11581.       You may VPUSH up to sixteen (16) screens/portions of the screen with
  11582.       multiple VPUSH commands.  To restore the screen data saved by the last
  11583.       VPUSH, use VPOP.
  11584.  
  11585.      ERRORLEVEL
  11586.  
  11587.       0  Screen data saved.
  11588.       1  Not enough memory was available to save the screen data.  VPUSH must
  11589.          allocate 2 bytes of memory per screen character (one for the screen
  11590.          character, and one for the color), so if you save an 80 x 25 screen
  11591.          4200 bytes of memory (about 4K) is required to save the data.
  11592.  
  11593.      SEE ALSO
  11594.  
  11595.       VPOP, WNDOPEN
  11596.  
  11597.      EXAMPLE
  11598.  
  11599.       VPUSH                               ;save the whole screen
  11600.       if $ERRORLEVEL = 1 goto no_memory   ;if $ERRORLEVEL is equal to 1
  11601.       cls
  11602.       pause "The screen was saved before clearing.  Press a key to restore: "
  11603.       VPOP                                ;restore the screen
  11604.  
  11605.       VPUSH 10 10 70 16  ;save from 10,10 to 70,16
  11606.       if $ERRORLEVEL = 1 goto no_memory
  11607.       box "Box Title" 10 10 70 16
  11608.       printraw -1 -1 $NORM_COLOR "This text is centered on the screen in a
  11609.      box"
  11610.       pause
  11611.       VPOP
  11612.       return
  11613.  
  11614.      no_memory:
  11615.       print "Not enough memory was available to save screen data."
  11616.       pause "Please press a key... "
  11617.       exit
  11618.  
  11619.      VGETCHR__________________________________________________________________
  11620.  
  11621.      SUMMARY
  11622.  
  11623.       VGETCHR vBUFFER
  11624.  
  11625.      DESCRIPTION
  11626.  
  11627.  
  11628.  
  11629.  
  11630.      Intellicomm v2.01               SCRIPT.DOC                            183
  11631.      
  11632.      
  11633.  
  11634.  
  11635.       Gets the character at the current cursor position, and stores it in
  11636.       vBUFFER.  Color information is ignored.
  11637.  
  11638.      SEE ALSO
  11639.  
  11640.       VGETCHRS
  11641.  
  11642.      EXAMPLE
  11643.  
  11644.       variable c
  11645.  
  11646.       VGETCHR c
  11647.  
  11648.       print "The character at the current cursor position is '" c "'"
  11649.  
  11650.      VGETCHRS_________________________________________________________________
  11651.  
  11652.      SUMMARY
  11653.  
  11654.       VGETCHRS vBUFFER nSCRN_X nSCRN_Y nNUMCHARS
  11655.  
  11656.      DESCRIPTION
  11657.  
  11658.       Gets nNUMCHARS characters from the video screen at nSCRN_X (x coordinate
  11659.       left to right) nSCRN_Y (y coordinate top to bottom) and stores the
  11660.       characters in vBUFFER.  Screen color information is ignored.
  11661.  
  11662.       The screen coordinates nSCRN_X and nSCRN_Y are NOT relative to the
  11663.       current screen WINDOW: coordinates 1 1 are always the top left corner of
  11664.       the screen.  Coordinates $SCRN_WIDTH $SCRN_HEIGHT (the current width and
  11665.       height of the screen; normally 80 25 or 80 rows by 25 columns) are the
  11666.       bottom right corner of the screen.  This allows VGETCHRS to read video
  11667.       characters that are outside the screen WINDOW, such as characters on the
  11668.       Icom status line.
  11669.  
  11670.       VGETCHRS is mainly of use after a WAITFOR.  For example if you wanted to
  11671.       check the remaining online time in a BBS prompt you could wait for the
  11672.       prompt then use VGETCHRS to get the online time from wherever it shows
  11673.       up on the prompt.  See example 1 below.
  11674.  
  11675.  
  11676.      SEE ALSO
  11677.  
  11678.       VGETCHR
  11679.  
  11680.      EXAMPLE 1
  11681.  
  11682.       ;This example gets the remaining online time from a BBS prompt.
  11683.       ; Different types of BBS software display the online time in
  11684.       ; different positions (or not at all) so any scripts you write
  11685.       ; along these lines will be reliant on a specific BBS or door type.
  11686.       ;
  11687.       ; For the example a standard PCBoard Main Menu prompt is assumed:
  11688.  
  11689.  
  11690.  
  11691.  
  11692.      Intellicomm v2.01               SCRIPT.DOC                            184
  11693.      
  11694.      
  11695.  
  11696.       ;
  11697.       ;(XXX min. left) Main Board Command?
  11698.  
  11699.       variable time_left
  11700.  
  11701.       waitfor "Command?"              ;assumes not at the prompt yet... if
  11702.                                       ; the script is already AT the prompt
  11703.                                       ; this WAITFOR is unnecessary
  11704.       vgetchrs time_left 2 $SCRN_Y 3  ;column 2, current row, 3 characters
  11705.       add time_left time_left 0       ;this math operation, while it does
  11706.                                       ; nothing (adds zero) will get rid of
  11707.      any
  11708.                                       ; spaces or text.  Also if the
  11709.                                       ; characters VGETCHRS got were not
  11710.                                       ; numbers at all, time_left will be
  11711.                                       ; equal to 0 (zero) after the math
  11712.                                       ; operation
  11713.       if time_left = 0 goto have_time ;Impossible, or we wouldn't be online.
  11714.                                       ; More than likely the BBS uses
  11715.      different
  11716.                                       ; prompt format.  If this occurs your
  11717.                                       ; script might just assume that there
  11718.                                       ; is ample online time.
  11719.       if time_left > 30 goto have_time ;more than 30 minutes available
  11720.  
  11721.         ;less than 30 minutes is available... exit the script, logoff, hangup,
  11722.  
  11723.         ; whatever would suit the occasion
  11724.       exit
  11725.  
  11726.      have_time:
  11727.         ;30 minutes or more is available... do whatever you needed more than
  11728.         ; 30 minutes to do
  11729.        send "D SOMEFILE.ZIP Z"
  11730.        waitfor "(Ctrl-X)"
  11731.        download "Z"
  11732.        exit
  11733.  
  11734.      EXAMPLE 2
  11735.  
  11736.       variable BBS
  11737.       variable H
  11738.       variable M
  11739.       variable old_stat $STAT_ON  ;save status line state (on/off)
  11740.  
  11741.        ;Status line reference for example; numeric ruler shows the nSCRN_X
  11742.        ; coordinates of items on the status line
  11743.  
  11744.        ; Joe's BBS            HH:MM | Script|  19200 N81| ICOM.CAP     | ...
  11745.        ;1234567890123456789012345678901234567890123456789012345678901234 ...
  11746.        ;         1         2         3         4         5         6
  11747.  
  11748.       offline return                     ;skip if not online
  11749.       assign $STAT_ON 1                  ;make sure status line is on
  11750.  
  11751.  
  11752.  
  11753.  
  11754.      Intellicomm v2.01               SCRIPT.DOC                            185
  11755.      
  11756.      
  11757.  
  11758.       vgetchrs BBS 2 $SCRN_HEIGHT 20     ;Get 20 characters from column 2
  11759.       vgetchrs H 23 $SCRN_HEIGHT 2       ;Get 2 characters from column 23
  11760.       vgetchrs M 26 $SCRN_HEIGHT 2       ;Get 2 characters from column 26
  11761.       assign $STAT_ON old_stat           ;put it back the way it was (if off)
  11762.  
  11763.       msgopen "Connected to " BBS " for " H " hours and " M " minutes"
  11764.       inkeyw
  11765.       msgclose
  11766.       return
  11767.  
  11768.      VPOP_____________________________________________________________________
  11769.  
  11770.      SUMMARY
  11771.  
  11772.       VPOP
  11773.  
  11774.      DESCRIPTION
  11775.  
  11776.       Restores the last screen saved with VPUSH.
  11777.  
  11778.      SEE ALSO
  11779.  
  11780.       VPUSH
  11781.  
  11782.      EXAMPLE
  11783.  
  11784.  
  11785.       VPUSH
  11786.       cls
  11787.       pause "The screen was saved before it was cleared... Press a key: "
  11788.       VPOP
  11789.  
  11790.      WAITFOR__________________________________________________________________
  11791.  
  11792.      SUMMARY
  11793.  
  11794.       WAITFOR sTEXT [nTIMEOUT] [LABEL]
  11795.  
  11796.      DESCRIPTION
  11797.  
  11798.       WAITFOR pauses a script to wait for specific text from the COM port
  11799.       (modem or BBS) handling any text defined by WHEN commands while waiting
  11800.       (see WHEN below).  sTEXT is the text to wait for, nTIMEOUT is an
  11801.       optional timeout in seconds (stop waiting after timeout), and LABEL is
  11802.       an optional label to GOTO if the text is not found within the timeout
  11803.       period.  
  11804.  
  11805.       NOTE: Only the first twenty characters of sTEXT are tracked by WAITFOR. 
  11806.       The sTEXT specified in a WAITFOR needn't be the 'end' of a BBS prompt,
  11807.       nor need it be a complete BBS prompt.
  11808.  
  11809.       nTIMEOUT is an optional timeout in seconds.  If you specify a timeout,
  11810.       and sTEXT is not found within the timeout period, WAITFOR will either
  11811.       continue at the next script line when the timeout elapses (if LABEL is
  11812.  
  11813.  
  11814.  
  11815.  
  11816.      Intellicomm v2.01               SCRIPT.DOC                            186
  11817.      
  11818.      
  11819.  
  11820.       not specified) or will GOTO the optional LABEL if you specify it.  If no
  11821.       timeout is specified WAITFOR waits indefinitely for the sTEXT.
  11822.  
  11823.       If you do not wish to GOTO a label if sTEXT is not found within the
  11824.       nTIMEOUT timeout, you may omit the LABEL parameter and simply use the
  11825.       $ERRORLEVEL (see below) to determine whether the text was found or not.
  11826.  
  11827.      ERRORLEVEL
  11828.  
  11829.       0  nTEXT was found.
  11830.       1  nTEXT was not found.  This errorlevel can be of use if you do NOT
  11831.          specify a LABEL parameter to jump to.
  11832.  
  11833.      SEE ALSO
  11834.  
  11835.       WHEN
  11836.  
  11837.      EXAMPLE 1
  11838.  
  11839.       WAITFOR "Main Menu?"     ;wait indefinitely for the main menu
  11840.        ;script continues here if/when Main Menu? is found
  11841.  
  11842.      EXAMPLE 2
  11843.  
  11844.       WAITFOR "Main Menu?" 5   ;wait 5 seconds for the main menu
  11845.       if $ERRORLEVEL = 1 gosub locate_position
  11846.  
  11847.        ;demonstrates how to use $ERRORLEVEL to use a command other than
  11848.        ; GOTO if the text is not found (assumes there is a subroutine in
  11849.        ; the script called 'locate_position:'.  See the WHEN command for
  11850.        ; a real example of locating your position on the BBS.
  11851.  
  11852.      EXAMPLE 3
  11853.  
  11854.       when                               ;clear all WHENs
  11855.       when "Name?"     send "James Brown"
  11856.       when "Password?" send "mypassword"
  11857.       WAITFOR "Selection:" 120 NoMenu
  11858.       return
  11859.      NoMenu:
  11860.       hangup
  11861.  
  11862.        ;waits 2 minutes (120 seconds) for the prompt 'Selection:', handling
  11863.        ; a short logon with WHENs while waiting.  If the Selection: prompt
  11864.        ; is found, the script returns (exits back to terminal mode).  If
  11865.        ; the Selection: prompt is not found within 2 minutes, the script
  11866.        ; hangs up.
  11867.  
  11868.      WAITUNTIL________________________________________________________________
  11869.  
  11870.      SUMMARY
  11871.  
  11872.       WAITUNTIL sTIME [sDAY]
  11873.  
  11874.  
  11875.  
  11876.  
  11877.      Intellicomm v2.01               SCRIPT.DOC                            187
  11878.      
  11879.      
  11880.  
  11881.      DESCRIPTION
  11882.  
  11883.       Displays a box menu allowing the user limited control, then pauses
  11884.       script execution until sTIME on sDAY.  If sDAY is omitted, the day of
  11885.       the week is ignored and only sTIME applies.
  11886.  
  11887.       sTIME can be specified in military time (13:00 = 1:00pm) or am/pm time
  11888.       (1:00p = 13:00).
  11889.  
  11890.       sDAY, if specified can be "Anyday", "Sunday", "Monday", "Tuesday",
  11891.       "Wednesday", "Thursday", "Friday" or "Saturday" or a three letter
  11892.       abbreviation ("Sun", "Mon", etc).
  11893.  
  11894.      ERRORLEVEL
  11895.  
  11896.       None.  The box menu displayed during a WAITUNTIL allows the user to
  11897.       abort the script.  If 'Cancel' is selected by the user, the script
  11898.       simply ends.
  11899.  
  11900.      EXAMPLE
  11901.  
  11902.       WAITUNTIL "12:05a" "Sun"   ;wait until Saturday night at 12:05 am.
  11903.                                  ; [technically Sunday morning... this
  11904.                                  ; is pointed out because people rarely
  11905.                                  ; think of 12:05am SATURDAY as being
  11906.                                  ; Sunday morning, but it is to WAITUNTIL
  11907.                                  ; and your computer]
  11908.  
  11909.      WHEN_____________________________________________________________________
  11910.  
  11911.      SUMMARY
  11912.  
  11913.       WHEN [sTEXT] [cCOMMAND]
  11914.  
  11915.      DESCRIPTION
  11916.  
  11917.       WHEN defines BBS text to watch for (nTEXT) and a command to execute
  11918.       (cCOMMAND) if/when the text is found during a WAITFOR.  Up to nineteen
  11919.       WHENs can be specified prior to a WAITFOR, to handle up to nineteen
  11920.       different BBS prompts while waiting.
  11921.  
  11922.       Note that sTEXT and cCOMMAND are specified as optional parameters above:
  11923.       if you omit both parameters all previously defined WHENs (if any) are
  11924.       cleared.
  11925.  
  11926.       NOTE: Only the first twenty characters of sTEXT are tracked.  If you
  11927.       specify more than twenty characters, WHEN ignores the extra characters. 
  11928.       sTEXT needn't be the 'end' of a BBS prompt, nor need it be a complete
  11929.       BBS prompt.  You 'could' do this:
  11930.  
  11931.        WHEN "!" SEND "something"
  11932.  
  11933.       and Icom would SEND "something" every time an exclamation mark was found
  11934.       during a WAITFOR.  The trick is to define enough of the BBS prompt that
  11935.  
  11936.  
  11937.  
  11938.  
  11939.      Intellicomm v2.01               SCRIPT.DOC                            188
  11940.      
  11941.      
  11942.  
  11943.       it doesn't conflict with other regular text from the BBS.... the above
  11944.       probably wouldn't be a good idea since exclamation marks can show up
  11945.       just about anywhere.  And the reason most of the WHEN examples use the
  11946.       END of the BBS prompt as opposed to the beginning is that the command
  11947.       (normally SEND, to send a response to the prompt) is executed
  11948.       *immediately* after the text is found.  If the BBS has some sort of
  11949.       "keyboard buffer flusher" to erase line noise after displaying prompts,
  11950.       your response to the prompt could be lost if it's sent prematurely.  By
  11951.       defining the end of the BBS prompt in WHENs, including the trailing
  11952.       space on the prompt, you can be fairly sure that the BBS has flushed its
  11953.       input buffer already and won't erase your response.  Further, there is
  11954.       usually some sort of punctuation at the END of a prompt (a question mark
  11955.       or colon or the like) which also helps to make the text "unique".  For
  11956.       example, PCBoard asks for your password using the following prompt:
  11957.  
  11958.       Password (Dots will echo)? 
  11959.  
  11960.       You 'could' get away with using:
  11961.  
  11962.        WHEN "password" send $PASSWORD
  11963.  
  11964.       But this has been done many times (in both BIFs and scripts), and has
  11965.       failed many times when the Sysop has an opening bulletin/news file that
  11966.       has the word "password" in it!  On the other hand, if you use the END of
  11967.       the password prompt:
  11968.  
  11969.       WHEN "(Dots will echo)? " SEND $PASSWORD
  11970.  
  11971.       ...it's VERY unlikely that such text would show up anywhere else but at
  11972.       the password prompt, which is the only place you want your password
  11973.       sent.  The same applies to the BBS prompts you define in your BIFs.
  11974.  
  11975.       The easiest way to use WHEN is with a SEND or GOTO command.  If you want
  11976.       ease of use, SEND/GOTO commands in WHENs are the most straightforward
  11977.       route to go.  SEND simply sends the response to the prompt defined by
  11978.       the WHEN, and GOTO cancels the WAITFOR and jumps to another area of the
  11979.       script.  If you want more power and flexibility, and want to use GOSUBs
  11980.       and other commands in WHENs, read on.
  11981.  
  11982.       If you're handling complicated tasks with GOSUBs in WHEN commands, it's
  11983.       important to understand that you have nineteen WHENs to work with in
  11984.       TOTAL.  Going to a subroutine, or even calling another script, does NOT
  11985.       give you another nineteen WHENs to work with.  If you call WHEN more
  11986.       than nineteen times before clearing previous prompts with a lone WHEN
  11987.       comand, the first WHEN you defined is overwritten.  I.e. it wraps around
  11988.       back to the beginning if you go past nineteen.
  11989.  
  11990.       As long as you understand this (Icom deals with the same limitation in
  11991.       its own automated routines which use the exact same routines WHEN uses)
  11992.       it's really a simple matter to use GOTOs instead of GOSUBs, clear all
  11993.       the WHENs in your subroutine/goto, then jump back up to re-define the
  11994.       original WHENs.  Example:
  11995.  
  11996.      redefine_whens:                 ;label to get above the WHENs
  11997.  
  11998.  
  11999.  
  12000.  
  12001.      Intellicomm v2.01               SCRIPT.DOC                            189
  12002.      
  12003.      
  12004.  
  12005.        
  12006.        WHEN                          ;clear any existing WHENs
  12007.        WHEN "this" GOTO handle_this  ;GOTO instead of GOSUB/RETURN
  12008.         ...etc. up to 18 more
  12009.        WAITFOR "some text"
  12010.  
  12011.      handle_this:
  12012.        WHEN                          ;clear the previous WHENs, start anew
  12013.        WHEN "that" SEND "cmd"
  12014.         ...etc. up to 18 more
  12015.        WAITFOR "something else"
  12016.  
  12017.        GOTO redefine_whens           ;jump back up to the original when done
  12018.  
  12019.      ERRORLEVEL
  12020.  
  12021.       No errorlevel is set by WHEN, since it doesn't do anything until WAITFOR
  12022.       is active... and WAITFOR sets its own error.  If you specify more than
  12023.       nineteen WHENs, the first WHEN is overwritten with no error.
  12024.  
  12025.      SEE ALSO
  12026.  
  12027.       WAITFOR
  12028.  
  12029.      EXAMPLE
  12030.  
  12031.       Please see above for advanced use, and see the Introduction to Scripts
  12032.       at the beginning of the SCRTUTOR.DOC for basic usage.
  12033.  
  12034.      WHILE____________________________________________________________________
  12035.       BREAK___________________________________________________________________
  12036.       CONTINUE________________________________________________________________
  12037.       ENDWHILE________________________________________________________________
  12038.  
  12039.      SUMMARY
  12040.  
  12041.       WHILE nNUM1 OPERATOR nNUM2    ;a numeric comparison
  12042.        cCOMMAND
  12043.        [cCOMMAND]
  12044.       ENDWHILE
  12045.  
  12046.       WHILE sSTR1 OPERATOR sSTR2    ;OR a string comparison
  12047.        cCOMMAND
  12048.        [cCOMMAND]
  12049.       ENDWHILE
  12050.  
  12051.      DESCRIPTION
  12052.  
  12053.       WHILE/ENDWHILE is much like IF/ENDIF, but where IF/ENDIF execute a set
  12054.       of commands once and only once if a given condition is true, WHILE
  12055.       executes a set of commands over and over again, WHILE a given condition
  12056.       is true.
  12057.  
  12058.  
  12059.  
  12060.  
  12061.      Intellicomm v2.01               SCRIPT.DOC                            190
  12062.      
  12063.      
  12064.  
  12065.       BREAK
  12066.       -----
  12067.       The optional BREAK command is only valid *between* WHILE and ENDWHILE
  12068.       commands.  BREAK forces the script processor to break from the loop
  12069.       (exit the loop and skip to the next command following ENDWHILE).  BREAK
  12070.       is used for conditions that cannot be specified directly in the WHILE
  12071.       command.  For example, you may have several numeric and/or string
  12072.       comparisons to perform in the WHILE loop (using SWITCH or IF, which are
  12073.       valid in WHILE loops).  Instead of having to do this:
  12074.  
  12075.        WHILE i < 10
  12076.         if i2 = 1 goto endloop
  12077.         ...
  12078.        ENDWHILE
  12079.      endloop:
  12080.  
  12081.       ...you'd use a BREAK instead:
  12082.  
  12083.        WHILE i < 10
  12084.         if i2 = 1 BREAK   ;exit loop if i2 is equal to 1
  12085.         ...
  12086.        ENDWHILE
  12087.  
  12088.       The BREAK above does the same thing as the first 'goto endloop' example. 
  12089.       You can get out of a loop either way, but BREAK is considered better
  12090.       programming practice.
  12091.  
  12092.       CONTINUE
  12093.       --------
  12094.       The optional CONTINUE command is only valid *between* WHILE and ENDWHILE
  12095.       commands.  CONTINUE forces the script processor to immediately jump back
  12096.       up to the WHILE statement.  Instead of having to do this:
  12097.  
  12098.      toploop:
  12099.        WHILE i < 10
  12100.         inc i
  12101.         if i2 = 1 goto toploop
  12102.         ...
  12103.        ENDWHILE
  12104.  
  12105.       ...you'd use a CONTINUE instead:
  12106.  
  12107.        WHILE i < 10
  12108.         inc i
  12109.         if i2 = 1 CONTINUE
  12110.         ...
  12111.        ENDWHILE
  12112.  
  12113.       The CONTINUE above does the same thing as the first 'goto toploop'
  12114.       example.  You can get back to the top of a loop either way, but CONTINUE
  12115.       is considered better programming practice.  One thing to watch when you
  12116.       use CONTINUE, however, is that you make sure that your WHILE condition
  12117.       or variable is modified BEFORE you use the CONTINUE command.  If you did
  12118.       this:
  12119.  
  12120.  
  12121.  
  12122.  
  12123.      Intellicomm v2.01               SCRIPT.DOC                            191
  12124.      
  12125.      
  12126.  
  12127.        WHILE i < 10
  12128.         if i2 = 1 CONTINUE
  12129.         inc i               ;don't increment 'i' AFTER the CONTINUE
  12130.         ...
  12131.        ENDWHILE
  12132.  
  12133.       and 'i2' was equal to 1 ... your script would hang, since variable 'i'
  12134.       would never be incremented, and thus 'i' would always be less than 10 (i
  12135.       < 10).  Take care of your WHILE variables (INCrementing, DECrementing,
  12136.       assigning values to strings, etc) immediately following the WHILE
  12137.       command at the *top* of the loop rather than at the bottom near the
  12138.       ENDWHILE, and you won't have any problems with CONTINUE.  Try to get
  12139.       into the habit of typing your WHILE loops like this:
  12140.  
  12141.        while somevariable > 1   ;or whatever the condition is
  12142.         dec somevariable        ;put your primary modifier in at the top, just
  12143.                                 ; after you define your WHILE condition
  12144.        endwhile                 ;and add the ENDWHILE so you don't forget it
  12145.  
  12146.       ...and AFTER you have the WHILE/ENDWHILE and your key modifier set up,
  12147.       THEN go and fill the rest of the loop in between (between WHILE and DEC
  12148.       in the example above).
  12149.  
  12150.      ERRORLEVEL
  12151.  
  12152.       WHILE/BREAK/CONTINUE/ENDWHILE do not change $ERRORLEVEL.
  12153.  
  12154.      SEE ALSO
  12155.  
  12156.       SWITCH, IF
  12157.  
  12158.      EXAMPLE
  12159.  
  12160.      WINDOW___________________________________________________________________
  12161.  
  12162.      SUMMARY
  12163.  
  12164.       WINDOW [nX1] [nY1] [nX2] [nY2]
  12165.  
  12166.      DESCRIPTION
  12167.  
  12168.       Sets the screen WINDOW.  All text displayed to the screen with PRINT,
  12169.       PRINTNC or PAUSE as well as text received from the communications port,
  12170.       stays within the current WINDOW coordinates.  nX1, nY1 is the top corner
  12171.       of the window (X1 is the screen column, right to left, Y1 is the screen
  12172.       row top to bottom) while nX2, nY2 is the bottom corner.  If no screen
  12173.       coordinates follow WINDOW the window is set to the full screen.
  12174.  
  12175.      SEE ALSO
  12176.  
  12177.       WNDOPEN, WNDCLOSE
  12178.  
  12179.      EXAMPLE
  12180.  
  12181.  
  12182.  
  12183.  
  12184.      Intellicomm v2.01               SCRIPT.DOC                            192
  12185.      
  12186.      
  12187.  
  12188.       cls
  12189.       WINDOW 5 5 75 20  ;leaves 4 rows/columns around the Window on all sides
  12190.  
  12191.      WNDCLOSE_________________________________________________________________
  12192.  
  12193.      SUMMARY
  12194.  
  12195.       WNDCLOSE
  12196.  
  12197.      DESCRIPTION
  12198.  
  12199.       Closes the last window opened with the WNDOPEN command (restores the
  12200.       previous contents of the video screen), restores the previous
  12201.       $SCRN_COLOR, cursor on/off status, and cursor coordinates.  Basically
  12202.       puts everything back the way it was before the last WNDOPEN command.
  12203.  
  12204.      SEE ALSO
  12205.  
  12206.       WNDOPEN
  12207.  
  12208.      EXAMPLE
  12209.  
  12210.       wndopen "Courtesy of WNDOPEN"
  12211.       pause "Press a key to remove this window...
  12212.       WNDCLOSE
  12213.  
  12214.      WNDOPEN__________________________________________________________________
  12215.  
  12216.      SUMMARY
  12217.  
  12218.       WNDOPEN [sTITLE] [nX1] [nY1] [nX2] [nY2]
  12219.  
  12220.      DESCRIPTION
  12221.  
  12222.       WNDOPEN first saves the screen area of the window you're opening (given
  12223.       screen X1, Y1, X2, Y2 coordinates), saves the current WINDOW
  12224.       coordinates, screen color and cursor x,y position, then uses BOX to
  12225.       display a window box with optional title, then uses the WINDOW command
  12226.       to set the current WINDOW within the box, then calls GOTOXY 1 1 to move
  12227.       the cursor to the top of the window.  The process is reversed when
  12228.       WNDCLOSE is called.
  12229.  
  12230.       You can call WNDOPEN up to 16 times (open 16 different windows,
  12231.       overlapping or hiding previous windows) before calling WNDCLOSE.
  12232.  
  12233.       sTITLE is an optional title to display in the window border top left
  12234.       corner.
  12235.  
  12236.       nX1 nY1 specify the top left corner of the window, nX2 nY2 specify the
  12237.       bottom right corner of the window.  [X is a screen column left to right,
  12238.       Y is a screen row top to bottom.]  If nX1 or nY1 is omitted, 1 is
  12239.       assumed (top corner).  If nX2 is omitted, $SCRN_WIDTH is assumed.  If
  12240.       nY2 is omitted, $SCRN_HEIGHT is assumed.
  12241.  
  12242.  
  12243.  
  12244.  
  12245.      Intellicomm v2.01               SCRIPT.DOC                            193
  12246.      
  12247.      
  12248.  
  12249.      SEE ALSO
  12250.  
  12251.       BOX, WNDCLOSE
  12252.  
  12253.      EXAMPLE
  12254.  
  12255.       ;Please see SCRDEMO.SCR for a more detailed example of WNDOPEN/WNDCLOSE
  12256.  
  12257.       WNDOPEN "Courtesy of WNDOPEN"
  12258.       pause "Press a key to remove this window...
  12259.       wndclose
  12260.       
  12261.      XOR______________________________________________________________________
  12262.  
  12263.      SUMMARY
  12264.  
  12265.       XOR vRESULT nNUM nBITMASK
  12266.  
  12267.      DESCRIPTION
  12268.  
  12269.       Performs a bitwise eXclusive OR on nNUM using nBITMASK and stores the
  12270.       result in variable vRESULT.  Exclusive OR gets right down to the nitty
  12271.       grittys of how computers store numbers.  You must understand the binary
  12272.       number system to understand XOR totally -- but you still can make use of
  12273.       it without understanding binary by simply following this tip:  The exact
  12274.       same XOR can change a 1 to a 0, and a 0 to a 1.  Why would you care
  12275.       about such things?  Well, it's an effecient and simple way to handle
  12276.       "toggles".  If you want something to toggle itself on or off, you simply
  12277.       do an
  12278.  
  12279.        XOR someflag someflag 1
  12280.  
  12281.       on the variable (where 'someflag' is the variable you want to toggle),
  12282.       and it'll toggle the value of the variable to on or off (1 or 0)
  12283.       depending upon its current value.
  12284.  
  12285.       You can actually store many toggles in a single variable... since there
  12286.       are many bits in binary numbers that can be turned on/off with XOR.  You
  12287.       can toggle each bit on or off using XOR, but unless you know binary well
  12288.       you should stick to "XOR v v 1" (XOR the variable with the number 1) to
  12289.       turn your toggle off or on.
  12290.  
  12291.      SEE ALSO
  12292.  
  12293.       AND, OR, SHL, SHR
  12294.  
  12295.      EXAMPLE
  12296.  
  12297.        variable mytoggle          ;declare the toggle (starts at 0 by default)
  12298.  
  12299.        gosub switch_toggle        ;sets 'mytoggle' to 1
  12300.        gosub switch_toggle        ;sets 'mytoggle' to 0
  12301.        gosub switch_toggle        ;sets it back to 1 
  12302.        return
  12303.  
  12304.  
  12305.  
  12306.  
  12307.      Intellicomm v2.01               SCRIPT.DOC                            194
  12308.      
  12309.      
  12310.  
  12311.      switch_toggle:
  12312.        XOR mytoggle mytoggle 1    ;changes 1 to 0, or 0 to 1
  12313.        return
  12314.  
  12315.  
  12316.  
  12317.  
  12318.      Intellicomm v2.01               SCRIPT.DOC                            195
  12319.      
  12320.      
  12321.  
  12322.                                      APPENDIXES
  12323.  
  12324.  
  12325.                                 A.  SYSTEM VARIABLES
  12326.  
  12327.      A.1  Introduction
  12328.  
  12329.      System Variables can be used in place of constant parameters with any
  12330.      script command that takes a parameter.  They're used to increase
  12331.      flexibility in your scripts, to allow you to write scripts that can be
  12332.      used by others, and also to allow you to write scripts that will adapt to
  12333.      changes you make to your OWN Intellicomm setup in the future.
  12334.  
  12335.      If you write a script that does some work in your 'Message Directory',
  12336.      and you specify your existing message directory into your script (using a
  12337.      constant such as "C:\MYMSGDIR") to refer to the directory, then your
  12338.      script will fail if you later rename that directory and define a new one
  12339.      in the Icom main setup or BIF.  By using the $MSG_DIR System Variable in
  12340.      your script, instead of specifying the value as a constant, the script
  12341.      adapts to changes when you make them.
  12342.  
  12343.      When you use a System Variable in a script command, it's up to you to
  12344.      make sure that the variable has some relevance to the parameter.  If you
  12345.      try this:
  12346.  
  12347.      PRINTRAW $BAR_COLOR $BORDER_COLOR $BOLD_COLOR "Print this text"
  12348.  
  12349.      it won't make much sense; though you CAN get away with it if you try
  12350.      (PRINTRAW expects the first parm to be a screen column, the second to be
  12351.      a screen row, and only the THIRD parm to be a color).  It would make more
  12352.      sense to use this:
  12353.  
  12354.      PRINTRAW $SCRN_X $SCRN_Y $TERM_COLOR "Print this text"
  12355.  
  12356.      No checks are made to ensure that you're using the "proper" System
  12357.      Variable for a given case, since there really is no such thing as using
  12358.      the "proper" variable for a given case.  The whole idea behind scripts is
  12359.      to allow you to do the unexpected and expand the horizons.
  12360.  
  12361.      A.1.1  BIF and INI (main setup) Variables 
  12362.  
  12363.      The System Variables outlined in this section do not cover all of the
  12364.      Icom system information available to you from a script: they cover only
  12365.      the most commonly used system information.  You can access ANY Icom
  12366.      variables using BIF Variables, and Main Setup Variables.  See the next
  12367.      two appendices below.
  12368.  
  12369.      A.1.2  Changing System Variables
  12370.  
  12371.      Do not CHANGE the value of any important system variables ($SCRN_X and
  12372.      $SCRN_Y are not considered important, unless the BBS is trying to display
  12373.      something on-screen at the time) unless you're sure about what you're
  12374.      doing.  Many of the system variables are made available for informational
  12375.      purposes, and are not meant to be changed ($HOME_DIR, for example, cannot
  12376.  
  12377.  
  12378.  
  12379.  
  12380.      Intellicomm v2.01               SCRIPT.DOC                            196
  12381.      
  12382.      
  12383.  
  12384.      be changed, nor can $DATE or $TIME or some of the other variables that
  12385.      simply return information).  The various COLOR variables and PROTOCOL /
  12386.      DIRECTORY variables can be changed, though if you change any of them in a
  12387.      script you change them globally (the new information is used everywhere
  12388.      in Intellicomm) for the duration of the Icom session; until Icom is
  12389.      removed from memory and re-loaded, or until another main setup file (or
  12390.      BIF, for some variables) is loaded.
  12391.  
  12392.      You can cause Intellicomm to malfunction by changing the contents of some
  12393.      of these System Variables, if you don't do it properly and if you don't
  12394.      restore the original value before your script ends.  If you DO change any
  12395.      important variables in your scripts, make sure that you save the contents
  12396.      of the variable before changing it, then restore the contents when your
  12397.      script ends.  Example:
  12398.  
  12399.       variable old_dl_dir $DL_DIR   ;define 'old_dl_dir', put contents of
  12400.                                     ; original $DL_DIR variable in it.
  12401.       assign $DL_DIR "C:\MYDIR"     ;change the Download Dir to a new
  12402.      directory
  12403.       ...                           ;main body of script here
  12404.       exit_script:                  ;a label you GOTO to exit the script
  12405.        assign $DL_DIR old_dl_dir
  12406.        exit
  12407.  
  12408.      A.1.3  READ ONLY System Variables
  12409.  
  12410.      To avoid problems in your scripts (and with Intellicomm in general) that
  12411.      may be very difficult to locate, some of the System Variables are read
  12412.      only.  If you try to modify the value of these variables directly your
  12413.      script will abort with a "$VARIABLE_NAME is READ ONLY" error.  If a
  12414.      variable is read only, then you can access the contents of the variable
  12415.      for informational purposes:
  12416.  
  12417.       variable myfile $HOME_DIR "MYFILE.EXT
  12418.  
  12419.        ;Using this, you'd end up with something like:
  12420.        ; C:\ICOM\MYFILE.EXT in 'myfile'.  $HOME_DIR is the directory
  12421.        ; that ICOM.EXE is located in.
  12422.  
  12423.      But you cannot change the variable itself:
  12424.  
  12425.       assign $HOME_DIR "C:\SOMEDIR\"
  12426.  
  12427.      Some of the system directories CAN be changed, however.  If you change
  12428.      any of the System Variables that specify directories ($MSG_DIR, $REP_DIR,
  12429.      etc) then Icom will add a slash to the end of the directory name if you
  12430.      forget to specify it in your script.  ALL directory names must have a
  12431.      trailing slash, since Icom simply appends filenames to the directory when
  12432.      it needs a file from a given directory.  You don't want this: 
  12433.      C:\MYDIRMYFILE.EXT.  You want this: C:\MYDIR\MYFILE.EXT.  Thus all
  12434.      directories have a trailing slash in MEMORY.  Sometimes directories are
  12435.      displayed without the trailing slash, and sometimes they're DEFINED
  12436.      without a trailing slash in the main setup/BIFs, but Icom automatically
  12437.      adds the slash when storing the variable in memory.  EXCEPTION:  The
  12438.  
  12439.  
  12440.  
  12441.  
  12442.      Intellicomm v2.01               SCRIPT.DOC                            197
  12443.      
  12444.      
  12445.  
  12446.      $UL_PATH (Upload PATH) System Variable simply contains a list of
  12447.      directories that Icom uses to locate files to upload, and these
  12448.      directories need not have a trailing slash (slashes are added when
  12449.      needed).
  12450.  
  12451.      A.2  System Variable Summary
  12452.  
  12453.      All System Variables are listed in alphabetical order below, with the
  12454.      variable name first, a description of the variable, then any special
  12455.      notes/warnings about using the variable.  To see a quick listing of
  12456.      System Variables grouped by TOPIC, see the COMMANDS AT A GLANCE section.
  12457.  
  12458.      The COLOR variables contain a number that specifies both the foreground
  12459.      and background color.  To create your own colors (to create custom
  12460.      foreground or background colors), see the COLOR CODES Appendix below.  
  12461.  
  12462.  
  12463.      $ALARMS__________________________________________________________________
  12464.  
  12465.       Determines whether alarms are heard.  Intellicomm sounds an alarm after
  12466.       connecting and when file transfers complete.  Also determines whether
  12467.       script ALARM commands are heard.
  12468.  
  12469.      $BAR_COLOR_______________________________________________________________
  12470.  
  12471.       The color of menu hilight bars (currently hilighted item).
  12472.  
  12473.      $BBS_AREA________________________________________________________________
  12474.  
  12475.       Read only.  Of use only when you call a script via a job Custom
  12476.       Command/Run Script task, $BBS_AREA allows you to check which area of the
  12477.       BBS your script is located, when Icom turns control over:
  12478.  
  12479.        [L] = the BBS Main Menu
  12480.        [M] = the BBS Message Menu
  12481.        [F] = the BBS File Menu
  12482.        [B] = the BBS Time Bank Menu
  12483.  
  12484.       The information is presented in this format (between square brackets) to
  12485.       maintain compatibility with the NEWAREA command.  See NEWAREA for
  12486.       details.
  12487.  
  12488.      $BETA_VERSION____________________________________________________________
  12489.  
  12490.       The current beta version of Intellicomm (0 if a production release).
  12491.  
  12492.      $BIF_DIR_________________________________________________________________
  12493.  
  12494.       The BIF Directory (where .BIF files are stored).
  12495.  
  12496.      $BIF_NAME________________________________________________________________
  12497.  
  12498.       The name of the currently loaded BIF.
  12499.  
  12500.  
  12501.  
  12502.  
  12503.      Intellicomm v2.01               SCRIPT.DOC                            198
  12504.      
  12505.      
  12506.  
  12507.      $BOLD_COLOR______________________________________________________________
  12508.  
  12509.       The standard bold text color.  Used to hilight menu hotkeys, and to
  12510.       emphasize important information.  The PRINT, PRINTNC, and PAUSE commands
  12511.       allow you to use $BOLD_COLOR by specifying ^B (Ctrl-B) in your print
  12512.       strings.  Example: PRINT "This is normal.  ^BThis is bold.^B"
  12513.  
  12514.      $BORDER_COLOR____________________________________________________________
  12515.  
  12516.       The color of menu and box borders.  Used by Intellicomm for all menus,
  12517.       boxes, etc., and also by the WNDOPEN, MSGWIND, MSGOPEN commands.
  12518.  
  12519.      $BSSWAP__________________________________________________________________
  12520.  
  12521.       If set to zero, the backspace key sends a backspace character.  If non-
  12522.       zero, the backspace key sends a DEL character.
  12523.  
  12524.      $CAP_NAME________________________________________________________________
  12525.  
  12526.       The full D:\PATH\FILENAME.EXT of the capture log.
  12527.  
  12528.      $CAP_STAT________________________________________________________________
  12529.  
  12530.       Read Only.  This variable can only be changed by Icom (when it
  12531.       opens/closes the capture file), the user ([Alt-L] terminal key), or
  12532.       CAPTURE, CAPPAUSE, CAPCLOSE in a script.
  12533.  
  12534.      $CAREA_FLD_______________________________________________________________
  12535.  
  12536.       The File Area of the currently loaded Tagger catalog record (CGETREC). 
  12537.       Use NEWAREA $CAREA_FLD to change to the proper BBS file area to download
  12538.       the file.
  12539.  
  12540.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12541.       on using the $Cxxxx_FLD variables.
  12542.  
  12543.      $CARRIER_________________________________________________________________
  12544.  
  12545.       Reflects the state of the DCD signal (carrier detect) on the current
  12546.       $COM_PORT.  If 0 (zero), the modem is reporting that it is offline (not
  12547.       connected).  If non-zero the modem is reporting that is is online
  12548.       (connected).
  12549.  
  12550.       Unfortunately most modems do NOT report the carrier status properly when
  12551.       using the factory (default) settings.  If your modem is reporting online
  12552.       all the time ($CARRIER <> 0 even when offline), the fix will be either
  12553.       adding an &C1 command to your Initialize Modem string in the Icom main
  12554.       setup (2400 baud modems and faster) or the flipping of a small switch on
  12555.       or inside the modem; usually switch #6 (1200 bauders and below).  See
  12556.       "Common Questions & Answers" in the Icom online help for more
  12557.       information.
  12558.  
  12559.      $CAT_DIR_________________________________________________________________
  12560.  
  12561.  
  12562.  
  12563.  
  12564.      Intellicomm v2.01               SCRIPT.DOC                            199
  12565.      
  12566.      
  12567.  
  12568.       The Catalog Directory, where Tagger catalogs are stored.
  12569.  
  12570.      $CAT_NAME________________________________________________________________
  12571.  
  12572.       The name of the currently open Tagger catalog (if any).
  12573.  
  12574.      $CCDATE_FLD______________________________________________________________
  12575.  
  12576.       The Catalog Date of the currently loaded Tagger catalog record
  12577.       (CGETREC).  See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for
  12578.       more details on using the $Cxxxx_FLD variables.
  12579.  
  12580.      $CDAY_FLD________________________________________________________________
  12581.  
  12582.       The Transfer Day of the currently loaded Tagger catalog record
  12583.       (CGETREC). 0 = Anyday, 1 = Sunday, 2 = Monday, 3 = Tuesday, 4 =
  12584.       Wednesday, 5 = Thursday, 6 = Friday, 7 = Saturday.  Use $DOW to check
  12585.       the current day of the week.
  12586.  
  12587.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12588.       on using the $Cxxxx_FLD variables.
  12589.  
  12590.      $CFDATE_FLD______________________________________________________________
  12591.  
  12592.       The File Date of the currently loaded Tagger catalog record (CGETREC) in
  12593.       the format YYYYMMDD.  Use CDATE2DATE to convert these dates to the usual
  12594.       MM/DD/YY style.
  12595.  
  12596.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12597.       on using the $Cxxxx_FLD variables.
  12598.  
  12599.      $CFLAG_FLD_______________________________________________________________
  12600.  
  12601.       The user-defineable 'flags' field for the currently loaded catalog
  12602.       record (CGETREC).  $CFLAG_FLD is a general purpose flag in EACH catalog
  12603.       RECORD, that you can use as you see fit.  The real length of the 'FLAGS'
  12604.       field (a new database field introduced in v2.01) is 5 bytes; you have
  12605.       access to one of these bytes from scripts (using $CFLAG_FLD) for
  12606.       anything you want.  Icom uses the FLAGS field (a portion of it that
  12607.       cannot be accessed from scripts) to keep track of file transfer results
  12608.       and Stubborn Tags.  Each time a filename is sent to the BBS during
  12609.       automated transfers, Icom increments a counter stored in the FLAGS
  12610.       field.  If the counter goes past 3, Icom cancels the transfer (keeping
  12611.       the file tagged), which eliminates any possibility that the same
  12612.       filename will be entered over and over again forever due to bad BIF
  12613.       setup, errors, etc.  When 'File not Found', 'No time', 'No bytes',
  12614.       'Transfer Successful', etc. are received from the BBS, Icom makes
  12615.       another note in the flags field, storing 'C' to cancel the transfer
  12616.       (Untag the file), 'S' for a successful transfer, etc.
  12617.  
  12618.       If you write a script to perform auto downloads, you can put $CFLAG_FLD
  12619.       to the same use.  Icom never touches or checks the contents of
  12620.       $CFLAG_FLD (the portion that scripts have access to) so you can use it
  12621.       as you see fit to keep track of anything that your scripts need to keep
  12622.  
  12623.  
  12624.  
  12625.  
  12626.      Intellicomm v2.01               SCRIPT.DOC                            200
  12627.      
  12628.      
  12629.  
  12630.       track of.  The field is set to a blank space (" ") by default, and it's
  12631.       good practice to set it back that way when your script is done with it. 
  12632.       Example:
  12633.  
  12634.        cgetrec 5
  12635.        assign $CFLAG_FLD "A"  ;"A" would signify some condition to you...
  12636.                               ; maybe that you'd already tried to download
  12637.                               ; the file, or that the record should be
  12638.                               ; deleted or untagged, etc.
  12639.        cputrec
  12640.  
  12641.        Later, to check the flag:
  12642.  
  12643.        cgetrec 5
  12644.        if $CFLAG_FLD = "A" return  ;skip something if flag is set
  12645.  
  12646.        And when your script ends:
  12647.  
  12648.        cgetrec 5
  12649.        assign $CFLAG_FLD " "  ;clear the flag
  12650.        cputrec
  12651.  
  12652.      $CLOC_FLD________________________________________________________________
  12653.  
  12654.       The BIF/Location of the currently loaded Tagger catalog record
  12655.       (CGETREC).  Compare $CLOC_FLD to $BIF_NAME to see if the file is
  12656.       available for download on the current BBS (IF $CLOC_FLD = $BIF_NAME).
  12657.  
  12658.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12659.       on using the $Cxxxx_FLD variables.
  12660.  
  12661.      $CNAME_FLD_______________________________________________________________
  12662.  
  12663.       The Filename of the currently loaded Tagger catalog record (CGETREC).
  12664.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12665.       on using the $Cxxxx_FLD variables.
  12666.  
  12667.  
  12668.      $COM_PORT________________________________________________________________
  12669.  
  12670.       The current COM port (1 - 8).
  12671.  
  12672.      $CPRIORITY_FLD___________________________________________________________
  12673.  
  12674.       The 'Transfer Priority' of the currently loaded catalog record
  12675.       (CGETREC).  $CPRIORITY_FLD allows you to check or set the transfer
  12676.       priority of the current file.  Example:
  12677.        
  12678.        cgetrec
  12679.        assign $CPRIORITY_FLD 10   ;set to priority 10 (100 is the default)
  12680.        cputrec                    
  12681.  
  12682.       This will only work on either Tagged or Noted files.  Check $CTAG_FLD to
  12683.       see whether a file is 'T'agged or 'N'oted.  When using the Tag
  12684.  
  12685.  
  12686.  
  12687.  
  12688.      Intellicomm v2.01               SCRIPT.DOC                            201
  12689.      
  12690.      
  12691.  
  12692.       Status/Location sort order (see CSETSORT in SCRTUTOR.DOC), files are
  12693.       sorted by Tag Status, Location, Download Priority (a number from 1-200,
  12694.       1 being top priority), file Conference, Filename.  I.e. all Tagged files
  12695.       for a given BBS are grouped together, with the highest priority file
  12696.       first, the next-highest second, etc.  By simply using the Tag
  12697.       Status/Location index and using CGETREC, you'll get all the Tagged files
  12698.       in the proper order, according to the priorities the user has set.
  12699.  
  12700.      $COM_SPEED_______________________________________________________________
  12701.  
  12702.       The current COM port speed (300-115200).
  12703.  
  12704.      $CREC_STAT_______________________________________________________________
  12705.  
  12706.       The status of the currently loaded Tagger catalog record (CGETREC).
  12707.       "D" = Deleted, "A" = Active.
  12708.  
  12709.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12710.       on using the $Cxxxx_FLD variables.
  12711.  
  12712.      $CSIZE_FLD_______________________________________________________________
  12713.  
  12714.       The File Size of the currently loaded Tagger catalog record (CGETREC).
  12715.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12716.       on using the $Cxxxx_FLD variables.
  12717.  
  12718.      $CSORT_DIR_______________________________________________________________
  12719.  
  12720.       Read only.  The sorting direction of the currently open catalog.  0 =
  12721.       Forward, 1 = Reversed.  Use CSETSORT to change the sort direction.
  12722.  
  12723.      $CSORT_ORDER_____________________________________________________________
  12724.  
  12725.       Read only.  The sorting direction of the currently open catalog.  0 =
  12726.       Forward, 1 = Reversed.  Use CSETSORT to change the sort direction.
  12727.  
  12728.      $CTAG_FLD________________________________________________________________
  12729.  
  12730.       The Tag Status of the currently loaded Tagger catalog record (CGETREC). 
  12731.       N = Noted, T = Tagged, U = Untagged.
  12732.  
  12733.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  12734.       on using the $Cxxxx_FLD variables.
  12735.  
  12736.      $CTOTAL__________________________________________________________________
  12737.  
  12738.       Read only.  The total number of records in the currently open Tagger
  12739.       catalog.
  12740.  
  12741.      $CVTOTAL_________________________________________________________________
  12742.  
  12743.       Read only.  The total number of records that are 'viewable' in the
  12744.       currently open Tagger catalog.  $VIEW_DATE filters out catalog records
  12745.       that are older than a given date, so $CTOTAL and $CVTOTAL will often
  12746.  
  12747.  
  12748.  
  12749.  
  12750.      Intellicomm v2.01               SCRIPT.DOC                            202
  12751.      
  12752.      
  12753.  
  12754.       differ.  ASSIGN $VIEW_DATE "19800101" to make all records 'viewable'.
  12755.  
  12756.      $CURDIR__________________________________________________________________
  12757.  
  12758.       The current DOS drive and directory in the format D:\ or D:\PATH\ (a
  12759.       trailing slash always exists).
  12760.  
  12761.      $CURDRIVE________________________________________________________________
  12762.  
  12763.       The current DOS disk drive, without the colon (A, B, C, etc).
  12764.  
  12765.      $DATE____________________________________________________________________
  12766.  
  12767.       Read only.  The current system date.  $DATE is formatted according to
  12768.       the main setup options "Date Format" [*date] and "Date Separator"
  12769.       [*datesep or $DSEP] on the General Settings screen.
  12770.  
  12771.      $DAY_____________________________________________________________________
  12772.  
  12773.       Read only.  The current system day of month (1-31).
  12774.  
  12775.      $DL_DIR__________________________________________________________________
  12776.  
  12777.       The current Download Directory.  If the currently loaded BIF has a
  12778.       Download Dir defined (BIF File screen), $DL_DIR will be set to the BIF
  12779.       Directory.  If no Download Dir is defined in the BIF, the main setup
  12780.       Download Directory is assumed (main setup, Filenames and Paths screen).
  12781.  
  12782.      $DL_PROTOCOL_____________________________________________________________
  12783.  
  12784.       The 'Receive Files' protocol defined in the currently loaded BIF. 
  12785.       $DL_PROTOCOL uses the same format for protocols (a single letter) that
  12786.       the DOWNLOAD command expects.  Thus you can use DOWNLOAD $DL_PROTOCOL to
  12787.       download files using the protocol defined in the BIF.
  12788.  
  12789.      $DOORWAY_________________________________________________________________
  12790.  
  12791.       The current status of Doorway Mode; 0 = Off, 1 = On.
  12792.  
  12793.      $DOW_____________________________________________________________________
  12794.  
  12795.       The current day-of-week.  1 = Sunday, 2 = Monday, 3 = Tuesday, 4 =
  12796.       Wednesday, 5 = Thursday, 6 = Friday, 7 = Saturday.
  12797.  
  12798.      $DSEP____________________________________________________________________
  12799.  
  12800.       The Date Separator character defined on the main setup General Settings
  12801.       screen.
  12802.  
  12803.      $ECHO____________________________________________________________________
  12804.  
  12805.       Terminal 'echo' status; 0 = Off, 1 = On.  When echo is on, characters
  12806.       typed on the keyboard are also printed to the screen.
  12807.  
  12808.  
  12809.  
  12810.  
  12811.      Intellicomm v2.01               SCRIPT.DOC                            203
  12812.      
  12813.      
  12814.  
  12815.      $ERRORLEVEL______________________________________________________________
  12816.  
  12817.       Used to check the results of many script commands.  See the ERRORLEVEL
  12818.       sections in the Detailed Command Summary section above.
  12819.  
  12820.      $FARCH___________________________________________________________________
  12821.  
  12822.       Read only.  The state of the file Archive attribute; + = On, - = Off. 
  12823.       EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file
  12824.       is found.
  12825.  
  12826.      $FDATE___________________________________________________________________
  12827.  
  12828.       Read only.  The file modification date in the format defined on the main
  12829.       setup General Settings screen (Date Format, Date Separator).  EXIST,
  12830.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12831.       found.
  12832.  
  12833.      $FDAY____________________________________________________________________
  12834.  
  12835.       Read only.  The file modification date, day of month only (1-31). 
  12836.       EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file
  12837.       is found.
  12838.  
  12839.      $FHIDDEN_________________________________________________________________
  12840.  
  12841.       Read only.  The state of the file Hidden attribute; + = On, - = Off. 
  12842.       FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and
  12843.       NOTEXIT cannot find hidden files).
  12844.  
  12845.      $FHOUR___________________________________________________________________
  12846.  
  12847.       Read only.  The file modification time, hour only (0-23).  EXIST,
  12848.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12849.       found.
  12850.  
  12851.      $FMIN____________________________________________________________________
  12852.  
  12853.       Read only.  The file modification time, minute only (0-59).  EXIST,
  12854.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12855.       found.
  12856.  
  12857.      $FMONTH__________________________________________________________________
  12858.  
  12859.       Read only.  The file modification date, month only (1-12).  EXIST,
  12860.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12861.       found.
  12862.  
  12863.      $FRDONLY_________________________________________________________________
  12864.  
  12865.       Read only.  The state of the file Read Only attribute; + = On, - = Off.  
  12866.        EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file
  12867.       is found. 
  12868.  
  12869.  
  12870.  
  12871.  
  12872.      Intellicomm v2.01               SCRIPT.DOC                            204
  12873.      
  12874.      
  12875.  
  12876.       Files with the Read Only attribute set cannot be deleted or overwritten.
  12877.  
  12878.      $FSEC____________________________________________________________________
  12879.  
  12880.       Read only.  The file modification time, second only (0-59).  EXIST,
  12881.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12882.       found.
  12883.  
  12884.      $FSIZE___________________________________________________________________
  12885.  
  12886.       Read only.  The file size.  EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set
  12887.       this variable if the file is found.
  12888.  
  12889.      $FSUBDIR_________________________________________________________________
  12890.  
  12891.       Read only.  The state of the Subdirectory attribute; + = On, - = Off. 
  12892.       FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and
  12893.       NOTEXIT cannot find subdirectories).
  12894.  
  12895.       If the Subdirectory attribute is set, the file is a subdirectory (these
  12896.       directory entries are marked with <DIR> in Icom's File Manager).
  12897.  
  12898.  
  12899.      $FSYSTEM_________________________________________________________________
  12900.  
  12901.       Read only.  The state of the System File attribute; + = On, - = Off. 
  12902.       FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and
  12903.       NOTEXIT cannot find System files).
  12904.  
  12905.      $FTIME___________________________________________________________________
  12906.  
  12907.       Read only.  The file modification time in the format defined on the main
  12908.       setup General Settings screen (Time Format, Time Separator).  EXIST,
  12909.       FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is
  12910.       found.
  12911.  
  12912.      $FVOLID__________________________________________________________________
  12913.  
  12914.       Read only.  The state of the Volume ID attribute; + = On, - = Off. 
  12915.       FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and
  12916.       NOTEXIT cannot find Volume ID's).
  12917.  
  12918.       Only one file per disk (in the root directory) has the Volume ID
  12919.       attribute set.
  12920.  
  12921.      $FULL_SCRIPT_NAME________________________________________________________
  12922.  
  12923.       The full D:\PATH\FILENAME.EXT of the currently executing script.
  12924.  
  12925.      $FYEAR___________________________________________________________________
  12926.  
  12927.       Read only.  The file modification date, year only (1990, 1995, 2000,
  12928.       etc).  EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the
  12929.       file is found.
  12930.  
  12931.  
  12932.  
  12933.  
  12934.      Intellicomm v2.01               SCRIPT.DOC                            205
  12935.      
  12936.      
  12937.  
  12938.      $HOME_DIR________________________________________________________________
  12939.  
  12940.       The D:\PATH\ where ICOM.EXE and many of Intellicomm's data files reside. 
  12941.       $HOME_DIR can be overridden with a SET ICOM=D:\PATH\ command (sets an
  12942.       environment variable) from the DOS prompt or AUTOEXEC.BAT file.
  12943.  
  12944.      $HOTKEY_1________________________________________________________________
  12945.      $HOTKEY_2________________________________________________________________
  12946.      $HOTKEY_3________________________________________________________________
  12947.      $HOTKEY_4________________________________________________________________
  12948.      $HOTKEY_5________________________________________________________________
  12949.  
  12950.       Allows you to define up to 5 'hotkeys' for use with the GETS and BOXGETS
  12951.       commands.  The hotkeys you define must be extended keycodes such as an
  12952.       [Alt] key combination ([Alt-A], [Alt-B], etc).  See the KEYBOARD CODES
  12953.       appendix for appropriate key codes.
  12954.  
  12955.       Please see the BOXGETS command for an example of usage.
  12956.  
  12957.      $HOUR____________________________________________________________________
  12958.  
  12959.       Read only.  The current system time of day, hour only (0-23; 0 =
  12960.       Midnight).
  12961.  
  12962.  
  12963.      $HSEC____________________________________________________________________
  12964.  
  12965.       Read only.  The current system time of day, hundredth of a second only
  12966.       (0-99).
  12967.  
  12968.      $INI_NAME________________________________________________________________
  12969.  
  12970.       The currently loaded .INI (main setup) file.
  12971.  
  12972.      $KEY_ALTQ________________________________________________________________
  12973.  
  12974.       If set to 0 (zero), the script processor ignores [Alt-Q] keypresses
  12975.       which prevents the user from aborting the script.  This can be useful
  12976.       when you have some important cleanup work to do before your script ends. 
  12977.       If set to any number other than zero, [Alt-Q] pops up the Job/Script
  12978.       Control Menu.
  12979.  
  12980.      $KEY_CHECK_______________________________________________________________
  12981.  
  12982.       If set to 0 (zero), the script processor doesn't check for any keys at
  12983.       all, effectively disabling all Intellicomm functions.  You can then
  12984.       handle every keystroke as you see fit.
  12985.  
  12986.       For advanced script writers only.
  12987.  
  12988.      $KEY_FILTER______________________________________________________________
  12989.  
  12990.       Allows you to define up to ten normal ASCII characters that BOXGETS,
  12991.       GETS, and GETSXY will not accept.  For example, if you're prompting the
  12992.  
  12993.  
  12994.  
  12995.  
  12996.      Intellicomm v2.01               SCRIPT.DOC                            206
  12997.      
  12998.      
  12999.  
  13000.       user for a filename, and you don't want to accept wildcards (* and ?):
  13001.        
  13002.        assign $KEY_FILTER "*?"
  13003.        gets somevariable 8      ;GETS will not allow * or ? to be entered
  13004.        assign $KEY_FILTER ""    ;restore to normal
  13005.  
  13006.      $LINEFEED________________________________________________________________
  13007.  
  13008.       If set to 0 (zero), the Terminal does not add line feed characters when
  13009.       carriage returns are received from the COM port.  If set to any number
  13010.       other than zero, line feeds are automatically added by the Terminal
  13011.       display routines whenever a carriage return is received.
  13012.  
  13013.       If lines from the BBS/modem overwrite one another, ASSIGN $LINEFEED 1. 
  13014.       If lines from the BBS/modem are double-spaced, ASSIGN $LINEFEED 0.
  13015.  
  13016.      $LST_DIR_________________________________________________________________
  13017.  
  13018.       The D:\PATH\ that BBS new files lists are captured to (automated jobs,
  13019.       "Get new files list" task).
  13020.  
  13021.      $MAJOR_VERSION___________________________________________________________
  13022.  
  13023.       Read only.  The major Intellicomm version number (2) to the left of the
  13024.       decimal point.
  13025.      $MENUSELECTION___________________________________________________________
  13026.  
  13027.       Set to the menu item selected by MENUBAR, MENUBOXH and MENUBOXV.
  13028.  
  13029.      $MIN_____________________________________________________________________
  13030.  
  13031.       Read only.  The current system time of day, minute only (0-59).
  13032.  
  13033.      $MINOR_VERSION___________________________________________________________
  13034.  
  13035.       Read only.  The minor Intellicomm version number to the left of the
  13036.       decimal point.  Intellicomm v2.01 has a $MINOR_VERSION of 1, v2.10 would
  13037.       have a minor version of 10 (ten), etc.
  13038.  
  13039.      $MONTH___________________________________________________________________
  13040.  
  13041.       Read only.  The current system date, month only (1-12; 1 = January).
  13042.  
  13043.      $MSG_DIR_________________________________________________________________
  13044.  
  13045.       The current Message Directory (where message packets should be
  13046.       downloaded to).  If the currently loaded BIF has a Message Dir defined
  13047.       (BIF Message screen), $MSG_DIR will be set to the BIF Directory.  If no
  13048.       Message Dir is defined in the BIF, the main setup Message Directory is
  13049.       assumed (main setup, Filenames and Paths screen).
  13050.  
  13051.       NOTE: If your script downloads mail packets, it's up to you to do the
  13052.       following in order to get the packet into the proper directory:
  13053.  
  13054.  
  13055.  
  13056.  
  13057.      Intellicomm v2.01               SCRIPT.DOC                            207
  13058.      
  13059.      
  13060.  
  13061.       assign OldDLDir $DL_DIR    ;save existing D/L Directory
  13062.       assign $DL_DIR $MSG_DIR    ;now assign the message dir to the D/L dir
  13063.  
  13064.       download $MSG_PROTOCOL ""  ;now downloads into the Message Directory
  13065.       
  13066.       assign $DL_DIR OldDLDir    ;put it back the way it was
  13067.  
  13068.      $MSG_PROTOCOL____________________________________________________________
  13069.  
  13070.       The 'Receive Mail' protocol defined in the currently loaded BIF. 
  13071.       $MSG_PROTOCOL uses the same format for protocols (a single letter) that
  13072.       the DOWNLOAD command expects.  Thus you can use DOWNLOAD $MSG_PROTOCOL
  13073.       to download mail packets using the protocol defined in the BIF.
  13074.  
  13075.      $NORM_COLOR______________________________________________________________
  13076.  
  13077.       The color of normal text on all Intellicomm displays.
  13078.  
  13079.      $PASSWORD________________________________________________________________
  13080.  
  13081.       The Logon Password defined in the currently loaded BIF.
  13082.  
  13083.      $OPSYSTYPE_______________________________________________________________
  13084.  
  13085.       Allows you to determine which Operating System your script is running
  13086.       under:  0 = DOS, 1 = Windows, 2 = OS/2, 3 = DESQview.  Example:
  13087.  
  13088.        switch $OPSYSTYPE
  13089.         case 0
  13090.          print "DOS detected."
  13091.         endcase
  13092.         case 1
  13093.          print "Windows v3.x detected."
  13094.         endcase
  13095.         case 2
  13096.          print "OS/2 v2.x detected."
  13097.         endcase
  13098.         case 3
  13099.          print "DESQview detected."
  13100.         endcase
  13101.        endswitch
  13102.  
  13103.       Windows versions lower than v3.00 and OS/2 versions lower than v2.0 are
  13104.       ignored and will be reported as DOS (0).
  13105.  
  13106.      $PRN_____________________________________________________________________
  13107.  
  13108.       The printer device as defined on the main setup / Filenames and Paths
  13109.       screen (defaults to PRN).
  13110.  
  13111.      $REP_DIR_________________________________________________________________
  13112.  
  13113.       The current Reply Directory (where message packets should be downloaded
  13114.       to).  If the currently loaded BIF has a Reply Dir defined (BIF Message
  13115.  
  13116.  
  13117.  
  13118.  
  13119.      Intellicomm v2.01               SCRIPT.DOC                            208
  13120.      
  13121.      
  13122.  
  13123.       screen), $REP_DIR will be set to the BIF Directory.  If no Reply Dir is
  13124.       defined in the BIF, the main setup Reply Directory is assumed (main
  13125.       setup, Filenames and Paths screen).
  13126.  
  13127.       NOTE: If your script uploads reply packets, it's up to you to specify
  13128.       the proper directory when you upload:
  13129.  
  13130.       upload $REP_PROTOCOL $REP_DIR "PACKET.REP"
  13131.  
  13132.      $REP_PROTOCOL____________________________________________________________
  13133.  
  13134.       The 'Send Mail' protocol defined in the currently loaded BIF. 
  13135.       $REP_PROTOCOL uses the same format for protocols (a single letter) that
  13136.       the UPLOAD command expects.  Thus you can use UPLOAD $REP_PROTOCOL to
  13137.       upload mail packets using the protocol defined in the BIF.
  13138.  
  13139.      $RXCNT___________________________________________________________________
  13140.  
  13141.       Reports the number of characters currently waiting in the communications
  13142.       Receive Buffer.
  13143.  
  13144.      $SCRIPT_DIR______________________________________________________________
  13145.  
  13146.       The Script Directory (D:\PATH\ where Icom scripts are located).
  13147.  
  13148.      $SCRIPT_NAME_____________________________________________________________
  13149.  
  13150.       The FILENAME.EXT (no D:\PATH\) of the currently executing script.  Use
  13151.       $FULL_SCRIPT_NAME if you require the full D:\PATH\FILENAME.EXT.
  13152.  
  13153.      $SCRN_COLOR______________________________________________________________
  13154.  
  13155.       The current screen color.  Changing $SCRN_COLOR affects only NEW
  13156.       information printed on the screen.  It does not change the color of
  13157.       EXISTING information on the screen.  To display the entire screen in a
  13158.       new color, you must use CLS (clear screen) after changing $SCRN_COLOR.
  13159.  
  13160.      $SCRN_HEIGHT_____________________________________________________________
  13161.  
  13162.       Read only.  The total number of rows (lines top to bottom) available on
  13163.       the video display.  25 rows is the usual but EGA displays can also use
  13164.       43 lines, and VGA displays can use 50 lines.
  13165.  
  13166.      $SCRN_WIDTH______________________________________________________________
  13167.  
  13168.       Read only.  The total number of columns (characters left to right)
  13169.       available on the video display.  80 columns is the usual.
  13170.  
  13171.      $SCRN_WRAP_______________________________________________________________
  13172.  
  13173.       Determines whether the Terminal (and PRINT, PRINTNC, PAUSE commands)
  13174.       truncates or wraps lines that are longer than can fit in the current
  13175.       video display WINDOW.  If $SCRN_WRAP is zero, lines are truncated at
  13176.       $WND_RIGHT (the right-most column of the current WINDOW).  If $SCRN_WRAP
  13177.  
  13178.  
  13179.  
  13180.  
  13181.      Intellicomm v2.01               SCRIPT.DOC                            209
  13182.      
  13183.      
  13184.  
  13185.       is any number other than zero, lines wrapped to the next display line. 
  13186.       Setting $SCRN_WRAP to 1 does not give you word processor type 'word
  13187.       wrapping'.  Words will be split/wrapped to the next line right in the
  13188.       middle of a word if necessary.
  13189.  
  13190.      $SCRN_X__________________________________________________________________
  13191.  
  13192.       Read only.  The current X position (screen column, left to right) of the
  13193.       cursor.  Use GOTOXY to change the cursor position.
  13194.  
  13195.      $SCRN_Y__________________________________________________________________
  13196.  
  13197.       Read only.  The current Y position (screen row, top to bottom) of the
  13198.       cursor.  Use GOTOXY to change the cursor position.
  13199.  
  13200.      $SEC_____________________________________________________________________
  13201.  
  13202.       Read only.  The current system time of day, second only (0-59).
  13203.  
  13204.      $SEND_CR_________________________________________________________________
  13205.  
  13206.       Determines whether the SEND, SENDNP, and SENDNPC commands add a carriage
  13207.       return to the text they send.  If $SEND_CR is zero, no CR is added. 
  13208.       Otherwise a CR is added.
  13209.  
  13210.      $SOUND___________________________________________________________________
  13211.  
  13212.       Determines whether Intellicomm makes any sounds at all on the PC
  13213.       speaker.  If $SOUND is zero, ^G (BELL) characters from the BBS are not
  13214.       heard, nor are alarms, nor do the script ALARM or BEEP commands make any
  13215.       sound.
  13216.  
  13217.      $STAT_COLOR______________________________________________________________
  13218.  
  13219.       The color of the Terminal status line.
  13220.  
  13221.      $STAT_ON_________________________________________________________________
  13222.  
  13223.       Holds the current display status of the Terminal Mode status line (all
  13224.       scripts execute from Terminal Mode).  0 = Off, 1 = On.  You can also
  13225.       hide or unhide the status line by ASSIGNing 0 or 1 to this variable.
  13226.  
  13227.       Changing the state of this variable (ASSIGN $STAT_ON x) automatically
  13228.       resets $WND_BTM (the current WINDOW bottom screen line).  Further if you
  13229.       previously used a WNDOPEN command $WND_BTM will *not* be set properly to
  13230.       reflect the new screen size when you call WNDCLOSE (WNDOPEN saves all
  13231.       $WND_* coordinates when you call it, and restores those same values when
  13232.       you call WNDCLOSE).  Thus if you plan on using either the WINDOW or
  13233.       WNDOPEN commands in your script you should change $STAT_ON *first* or
  13234.       you will lose your current bottom window limit, and will not get the
  13235.       proper $WND_BTM when you call WNDCLOSE.  Example:
  13236.  
  13237.       WNDOPEN "Box Title" 5 5 75 20   ;20 is the bottom screen row of the box
  13238.       PRINT $WND_BTM                  ;$WND_BTM is now 19 (20=box border)
  13239.  
  13240.  
  13241.  
  13242.  
  13243.      Intellicomm v2.01               SCRIPT.DOC                            210
  13244.      
  13245.      
  13246.  
  13247.       ASSIGN $STAT_ON 0               ;turn off the status line
  13248.       PRINT $WND_BTM                  ;$WND_BTM is now $SCRN_HEIGHT (the full
  13249.                                       ; height of the screen), not 19.  PRINT
  13250.                                       ; would write over the bottom box border
  13251.                                       ; right to the end of the screen
  13252.       WNDCLOSE                        ;resets $WND_BTM to whatever value it
  13253.                                       ; was when WNDOPEN was called.  I.e.
  13254.                                       ; the change in $STAT_ON is lost and
  13255.                                       ; though the status line will not be
  13256.                                       ; VISIBLE, the bottom screen line will
  13257.                                       ; not be used.
  13258.        
  13259.        ;this is the correct way to do it:
  13260.  
  13261.       ASSIGN $STAT_ON 0               ;turn off FIRST (resets $WND_BTM)
  13262.       WNDOPEN "Box Title" 5 5 75 20   ;$WND_BTM is now set to row 19
  13263.                                       ; (20=window border), and WNDOPEN 
  13264.                                       ; saved the proper $WND_BTM value.
  13265.       WNDCLOSE                        ;$WND_BTM is now reset to the proper
  13266.                                       ; value, since it was reset
  13267.                                       ; BEFORE the call to WNDOPEN
  13268.  
  13269.       $WND_BTM is also lost when you ASSIGN $STAT_ON 1 to turn the status line
  13270.       back on.  Motto: if changing $STAT_ON, it is best done at the beginning
  13271.       and end of your scripts (unless you don't use any WNDOPEN or WINDOW
  13272.       commands... if that's the case it really doesn't matter).  You should
  13273.       also save the old display status before changing $STAT_ON since as with
  13274.       most System Variables the value is NOT automatically restored when your
  13275.       script ends (you may want to leave it that way... Icom has no way of
  13276.       knowing):
  13277.       
  13278.       VARIABLE old_stat_on $STAT_ON   ;define 'old_stat_on', store the value
  13279.      of
  13280.                                       ; $STAT_ON (0 or 1) in it.
  13281.       ASSIGN $STAT_ON 0               ;turn it off
  13282.        ...                            ;body of script here
  13283.       ASSIGN $STAT_ON old_stat_on     ;restore original value
  13284.       
  13285.  
  13286.      $TERM_COLOR______________________________________________________________
  13287.  
  13288.       The DEFAULT color of the terminal display (not the current color;
  13289.       $SCRN_COLOR holds the current color).
  13290.  
  13291.      $TIME____________________________________________________________________
  13292.  
  13293.       Read only.  The current system time.  $TIME is formatted according to
  13294.       the main setup options "Time Format" [*time] and "Time Separator"
  13295.       [*timesep or $TSEP] on the General Settings screen.
  13296.  
  13297.      $TSEP____________________________________________________________________
  13298.  
  13299.       The Time Separator character defined on the main setup General Settings
  13300.       screen.
  13301.  
  13302.  
  13303.  
  13304.  
  13305.      Intellicomm v2.01               SCRIPT.DOC                            211
  13306.      
  13307.      
  13308.  
  13309.      $TXCNT___________________________________________________________________
  13310.  
  13311.       Reports the number of characters currently waiting in the communications
  13312.       Transmit Buffer.
  13313.  
  13314.      $UL_PATH_________________________________________________________________
  13315.  
  13316.       The current Upload PATH.  If the currently loaded BIF has an Upload PATH
  13317.       defined (BIF File screen), $UL_PATH will be set to the BIF path.  If no
  13318.       Upload PATH is defined in the BIF, the main setup Upload PATH is assumed
  13319.       (main setup, Filenames and Paths screen).
  13320.  
  13321.       Directories on the Upload PATH are defined in the same manner as the
  13322.       regular DOS PATH:
  13323.  
  13324.       "C:\DIR1;C:\DIR2;C:\DIR3 ...etc"
  13325.  
  13326.       When UPLOAD is used, all directories in the Upload PATH are searched to
  13327.       locate the file(s) to upload.
  13328.  
  13329.      $UL_PROTOCOL_____________________________________________________________
  13330.  
  13331.       The 'Send Files' protocol defined in the currently loaded BIF. 
  13332.       $UL_PROTOCOL uses the same format for protocols (a single letter) that
  13333.       the UPLOAD command expects.  Thus you can use UPLOAD $UL_PROTOCOL to
  13334.       upload files using the protocol defined in the BIF.
  13335.  
  13336.      $VIEW_DATE_______________________________________________________________
  13337.  
  13338.       The View Date of the currently open catalog.  Any catalog records with a
  13339.       Catalog Date ($CCDATE_FLD) older than $VIEW_DATE are ignored, and will
  13340.       not be returned by CGETREC.  ASSIGN $VIEW_DATE "19800101" (January 1st,
  13341.       1980) to disable the $VIEW_DATE feature.
  13342.  
  13343.       See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details
  13344.       on using the $VIEW_DATE variable.
  13345.  
  13346.      $WND_BTM_________________________________________________________________
  13347.  
  13348.       The bottom video row of the current WINDOW.
  13349.  
  13350.      $WND_HEIGHT______________________________________________________________
  13351.  
  13352.       The total number of screen rows (top to bottom) in the current WINDOW.
  13353.  
  13354.      $WND_LEFT________________________________________________________________
  13355.  
  13356.       The left-most video column of the current WINDOW.
  13357.  
  13358.      $WND_RIGHT_______________________________________________________________
  13359.  
  13360.       The right-most video column of the current WINDOW.
  13361.  
  13362.      $WND_TOP_________________________________________________________________
  13363.  
  13364.  
  13365.  
  13366.  
  13367.      Intellicomm v2.01               SCRIPT.DOC                            212
  13368.      
  13369.      
  13370.  
  13371.       The top video row of the current WINDOW.
  13372.  
  13373.      $WND_WIDTH_______________________________________________________________
  13374.  
  13375.       The total number of screen columns (left to right) in the current
  13376.      WINDOW.
  13377.  
  13378.      $YEAR____________________________________________________________________
  13379.  
  13380.       Read only.  The current system date, year only.
  13381.  
  13382.  
  13383.  
  13384.  
  13385.      Intellicomm v2.01               SCRIPT.DOC                            213
  13386.      
  13387.      
  13388.  
  13389.  
  13390.                       B.  BIF VARIABLES (Advanced Users Only)
  13391.  
  13392.      BIF Variables allow you to access every configurable item in any BIF
  13393.      (other than the BIF Notes).  They can be used in any script command that
  13394.      takes a parameter, instead of specifying constant (hardcoded) data.
  13395.  
  13396.      BIF Variables start with an asterisk (*) and are then immediately
  13397.      followed by the BIF 'section' and 'tag' of the item.
  13398.  
  13399.             PRINT *[G]desc
  13400.                   | |  |
  13401.       Asterisk----  |  |
  13402.                     |  |
  13403.       BIF Section---   |
  13404.                        |
  13405.       BIF Tag----------
  13406.  
  13407.      The command above tells Intellicomm to access the [G]eneral BIF section
  13408.      (General screen as in the BIF Editor) for the tag "desc" (short for
  13409.      description; the BBS/Host name), and print the value to the screen.
  13410.  
  13411.      You may also wish to use BIF Variables in WHEN commands:
  13412.  
  13413.       WHEN *[L]namp SEND *[L]namc
  13414.  
  13415.      This sends the BIF namc 'name command' (response) WHEN the BIF namp 'name
  13416.      prompt' is found.  Both items are in the BIF [L]ogon section.
  13417.  
  13418.      You can do the same with ANY script command that takes a parameter,
  13419.      instead of specifying constant text.  All the BIF sections and tags are
  13420.      listed in this appendix, along with any special conditions or
  13421.      considerations.
  13422.  
  13423.      NOTE: BIF Variables cannot change the BIF on-disk.  BIFs are loaded from
  13424.      disk into MEMORY automatically by Intellicomm when you dial a BBS (via
  13425.      manual or automated means) or when you use the LOADBIF command in your
  13426.      script.  If you change BIF Variables via ASSIGN or another script
  13427.      assignment command and wish to save the changes to disk you must use
  13428.      SAVEBIF to write the changes to disk.  The $BIF_NAME System Variable
  13429.      holds the filename of the currently loaded BIF (without the .BIF
  13430.      extension).
  13431.  
  13432.      As with the System Variables, if you CHANGE any of the BIF items using
  13433.      ASSIGN or any other script assignment command, you change the data that
  13434.      Icom is working with as well, for the duration of the session or until
  13435.      another BIF is loaded.  To avoid potential problems when running scripts
  13436.      from automated jobs, you can either save/restore original BIF data as we
  13437.      did above with the System Variables, or can simply use LOADBIF $BIF_NAME
  13438.      when your script ends, to reset all the BIF variables to their original
  13439.      values.
  13440.  
  13441.      Below, are all six BIF screens with the appropriate BIF Variable to use
  13442.      in a script displayed where the BIF data would normally be displayed:
  13443.  
  13444.  
  13445.  
  13446.  
  13447.      Intellicomm v2.01               SCRIPT.DOC                            214
  13448.      
  13449.      
  13450.  
  13451.      ╔═╡ BIF Editor Θ Editing VARIABLE.BIF ╞ General BBS Information ╞═══════╗
  13452.      ║ BBS/Host Name  > *[G]desc           Message Type   > *[G]mtyp         ║
  13453.      ║ Phone Number   > *[G]phn1           Bank Type      > *[G]btyp         ║
  13454.      ║ Phone Number   > *[G]phn2           LD Service . . . *[G]ldsv         ║
  13455.      ║ Phone Number   > *[G]phn3           City/Address . . *[G]city         ║
  13456.      ║ Phone Number   > *[G]phn4           CR w/Commands? . *[G]adcr         ║
  13457.      ║ Phone Number   > *[G]phn5           Add Line Feeds?  *[G]adlf         ║
  13458.      ║ Port Settings  > *[G]port           Case-sensitive?  *[G]case         ║
  13459.      ║ Dial Prefix  . . *[G]dpre           Connect Command  *[G]conc         ║
  13460.      ║ Max. Redials . . *[G]datt           Gen. Menu Exit . *[G]mcan         ║
  13461.      ╟─┤ Protocols ├───────────────────────┤ Miscellaneous/Timeouts ├────────╢
  13462.      ║ Send Mail  . . . *[G]mspr           Last Connected . *[G]date         ║
  13463.      ║  BBS Letter  . . *[G]msbl           Total Connects . *[G]nses         ║
  13464.      ║ Receive Mail . . *[G]mrpr           Response Delay . *[G]rdel         ║
  13465.      ║  BBS Letter  . . *[G]mrbl           BS Protection  . *[G]bspt         ║
  13466.      ║ Send Files . . . *[G]fspr           Logon Timeout  . *[G]lout         ║
  13467.      ║  BBS Letter  . . *[G]fsbl           General Timeout  *[G]gout         ║
  13468.      ║ Receive Files  . *[G]frpr           Max. Timeouts  . *[G]tmax         ║
  13469.      ║  BBS Letter  . . *[G]frbl           Max. Online Time *[G]monl         ║
  13470.      ╚═══════════════════════════════════════════════════════════════════════╝
  13471.  
  13472.      ╔═╡ Logon/Global Commands ╞═══════════╡ Logon/Global Prompts ╞══════════╗
  13473.      ║ [Escape] Answer  *[L]escc           [Escape] Prompt  *[L]escp         ║
  13474.      ║ Your Logon Name> *[L]namc           Name . . . . . . *[L]namp         ║
  13475.      ║ Password Answer> $PASSWORD          Password . . . . *[L]pasp         ║
  13476.      ║ Mode/Language  > *[L]lanc           Mode/Language  . *[L]lanp         ║
  13477.      ║ Confirm Answer . *[L]ecnc           Confirm  . . . . *[L]ecnp         ║
  13478.      ║ Graphics Answer  *[L]grac           Graphics . . . . *[L]grap         ║
  13479.      ║ Scan Answer  . . *[L]scac           Scan Messages  . *[L]scap         ║
  13480.      ║ Pause Answer . . *[L]pauc           Pause  . . . . . *[L]paup         ║
  13481.      ║ No More  . . . . *[L]nomc           More . . . . . . *[L]morp         ║
  13482.      ║ Birth Date . . . *[L]bdtc           Enter Birth Date *[L]bdps         ║
  13483.      ║ Home Phone . . . *[L]phnc           Enter Home Phone *[L]phnp         ║
  13484.      ║ Startup Command  *[L]icom           Main Menu A  . . *[L]mnap         ║
  13485.      ║ Logoff . . . . . *[L]lofc           Main Menu B  . . *[L]mnbp         ║
  13486.      ║ Exit Command . . *[L]xitc           Logged Off . . . *[L]lofp         ║
  13487.      ╚═══════════════════════════════════════════════════════════════════════╝
  13488.  
  13489.      ╔═╡ Message Commands ╞════════════════╡ Message Prompts ╞═══════════════╗
  13490.      ║ Access Msg Menu> *[M]ames           Message Menu . . *[M]mmnp         ║
  13491.      ║ Send Replies . . *[M]senc           Send Replies Now *[M]rulp         ║
  13492.      ║ Reply Filename > *[M]rnam           Replies Accepted *[M]rokp         ║
  13493.      ║ Confirm Answer . *[M]crec           Confirm Receive  *[M]crep         ║
  13494.      ║ General Read . . *[M]grdc           Receive Messages *[M]mdlp         ║
  13495.      ║ Personal Read  . *[M]prdc           Receive Success  *[M]mokp         ║
  13496.      ║ Msg Filename   > *[M]mnam           More Mail Found  *[M]mmfp         ║
  13497.      ║ Extract Newfiles *[M]mnew           No Mail Found  . *[M]mnop         ║
  13498.      ║                                     No Time Left . . *[M]mntp         ║
  13499.      ║ More Answer  . . *[M]mmoc           Message More . . *[M]mmop         ║
  13500.      ║ Leave Msg Menu . *[M]lmmc           Message Pause  . *[M]mpap         ║
  13501.      ║ Logoff Msg Menu  *[M]gmmc           Enter Protocol . *[M]mprp         ║
  13502.      ║ Reply Dir  . . . *[M]repd                                             ║
  13503.      ║ Message Dir  . . *[M]msgd                                             ║
  13504.      ╚═══════════════════════════════════════════════════════════════════════╝
  13505.  
  13506.  
  13507.  
  13508.  
  13509.      Intellicomm v2.01               SCRIPT.DOC                            215
  13510.      
  13511.      
  13512.  
  13513.      ╔═╡ Bank Commands ╞═══════════════════╡ Bank Prompts ╞══════════════════╗
  13514.      ║ Access Bnk Menu> *[B]abnk           Bank Menu  . . . *[B]bmnp         ║
  13515.      ║ Deposit Bytes  . *[B]dbtc           Deposit Bytes  . *[B]dbtp         ║
  13516.      ║ Deposit Time . . *[B]dtmc           Deposit Time . . *[B]dtmp         ║
  13517.      ║ Withdraw Bytes . *[B]wbtc           Withdraw Bytes . *[B]wbtp         ║
  13518.      ║ Withdraw Time  . *[B]wtmc           Withdraw Time  . *[B]wtmp         ║
  13519.      ║ Leave Bank Menu  *[B]lbmc           Bank Pause . . . *[B]bpap         ║
  13520.      ║ Logoff Bank Menu *[B]gbmc           Bank More  . . . *[B]bmop         ║
  13521.      ╟─┤ BBS File List Details ├───────────┤ BBS File List Details ├─────────╢
  13522.      ║ Catalog to Use . *[B]catl           Year Position  . *[B]fysp         ║
  13523.      ║ D/L Priority   > *[B]tdup           Date separator . *[B]dase         ║
  13524.      ║ Default Lst Area *[B]dfar           Comment Start  . *[B]fcsp         ║
  13525.      ║ Filename Start . *[B]fnsp           Comment End  . . *[B]fcep         ║
  13526.      ║ Extension Start  *[B]fesp           Continue Comment *[B]fcca         ║
  13527.      ║ Size Position  . *[B]fssp           Continue Comment *[B]fccb         ║
  13528.      ║ Month Position . *[B]fmsp           New File Area  . *[B]fcat         ║
  13529.      ║ Day Position . . *[B]fdsp           COUNT File Areas *[B]fnum         ║
  13530.      ╚═══════════════════════════════════════════════════════════════════════╝
  13531.  
  13532.      ╔═╡ File Commands ╞═══════════════════╡ File Prompts ╞══════════════════╗
  13533.      ║ Access File Menu *[F]afil           File Menu  . . . *[F]fmnp         ║
  13534.      ║ Default BBS Area *[F]fare           File Pause . . . *[F]fpap         ║
  13535.      ║ Area Change  . . *[F]facc           File More  . . . *[F]fmop         ║
  13536.      ║ New Files  . . . *[F]nflc           Enter D/L Fname  *[F]efip         ║
  13537.      ║ File Search  . . *[F]fsrc           Enter U/L Fname  *[F]efup         ║
  13538.      ║ Download File[s] *[F]fdlc           Enter Protocol . *[F]fprp         ║
  13539.      ║ Upload File[s] . *[F]fulc           Duplicate File . *[F]fdup         ║
  13540.      ║ Descrip @SCRIPT  *[F]edsc           Enter Descrip. . *[F]edsp         ║
  13541.      ║ Chars per Line . *[F]fcmx           File Not Found . *[F]fnfp         ║
  13542.      ║ Max Lines  . . . *[F]flmx           No Time  . . . . *[F]fitp         ║
  13543.      ║ Files per D/L  . *[F]fpbt           No Bytes . . . . *[F]fibp         ║
  13544.      ║ Files per U/L  . *[F]fpul           File Accepted  . *[F]fokp         ║
  13545.      ║ Batch Full Answr *[F]fbfc           Batch Full . . . *[F]fbfp         ║
  13546.      ║ File Password  . *[F]fepc           <Enter Password  *[F]feep         ║
  13547.      ║ Leave File Menu  *[F]lfmc           Download File[s] *[F]fdlp         ║
  13548.      ║ Logoff File Menu *[F]gfmc           Upload File[s] . *[F]fulp         ║
  13549.      ║ Upload PATH  . . *[F]upld           Transfer Abort . *[F]fabp         ║
  13550.      ║ Download Dir . . *[F]dnld           Transfer Okay  . *[F]fsup         ║
  13551.      ╚═══════════════════════════════════════════════════════════════════════╝
  13552.  
  13553.      ╔═╡ Extra Commands ╞══════════════════╡ Extra Prompts ╞═════════════════╗
  13554.      ║ External Extra A *[E]exac           External A . . . *[E]exap         ║
  13555.      ║ External Extra B *[E]exbc           External B . . . *[E]exbp         ║
  13556.      ║ External Extra C *[E]excc           External C . . . *[E]excp         ║
  13557.      ║ External Extra D *[E]exdc           External D . . . *[E]exdp         ║
  13558.      ║ Message Extra A  *[E]mxac           Message A  . . . *[E]mxap         ║
  13559.      ║ Message Extra B  *[E]mxbc           Message B  . . . *[E]mxbp         ║
  13560.      ║ Message Extra C  *[E]mxcc           Message C  . . . *[E]mxcp         ║
  13561.      ║ Message Extra D  *[E]mxdc           Message D  . . . *[E]mxdp         ║
  13562.      ║ File Extra A . . *[E]fxac           File A . . . . . *[E]fxap         ║
  13563.      ║ File Extra B . . *[E]fxbc           File B . . . . . *[E]fxbp         ║
  13564.      ║ File Extra C . . *[E]fxcc           File C . . . . . *[E]fxcp         ║
  13565.      ║ File Extra D . . *[E]fxdc           File D . . . . . *[E]fxdp         ║
  13566.      ╚═══════════════════════════════════════════════════════════════════════╝
  13567.  
  13568.  
  13569.  
  13570.  
  13571.      Intellicomm v2.01               SCRIPT.DOC                            216
  13572.      
  13573.      
  13574.  
  13575.                    C.  MAIN SETUP VARIABLES (Advanced Users Only)
  13576.  
  13577.      The Icom Main Setup Variables are used in the same way as the BIF
  13578.      Variables outlined above.  You must precede the variable's 'tag' name
  13579.      with an asterisk, and are free to use it as a parameter in any script
  13580.      command that takes a parameter.  However, the Main Setup Variables do not
  13581.      require a [S]ection as the BIF Variables do.  You simply specify an
  13582.      asterisk (*) followed by one of the main setup tags listed below. 
  13583.      Example:
  13584.  
  13585.       ;*swpon (swap on) is the default 'swapping' setting which determines
  13586.       ; whether Icom will swap itself out of memory when calling external
  13587.       ; programs
  13588.  
  13589.       variable s          ;define a variable called 's'
  13590.  
  13591.       if *swpon = 2 assign s "whether connected or not"
  13592.       if *swpon = 1 assign s "only if not connected"
  13593.       if *swpon = 0 assign s "NEVER"
  13594.  
  13595.       print "Icom will swap out of memory " s   ;note 's' following the text
  13596.  
  13597.      This would print one of the strings below:
  13598.  
  13599.       Icom will swap out of memory whether connected or not
  13600.       Icom will swap out of memory only if not connected
  13601.       Icom will swap out of memory NEVER
  13602.  
  13603.      For all of the on/off, yes/no settings, 1 means YES or ON, and 0 means NO
  13604.      or OFF.  To turn a setting ON, you'd ASSIGN 1 to it:
  13605.  
  13606.       ASSIGN *swpon 1         ;turn swapping on
  13607.       ASSIGN *swpon 0         ;turn swapping off
  13608.  
  13609.      Make sure you read the notes in the summaries of each variable below
  13610.      before you think about changing any of these variables in your scripts. 
  13611.      In many cases you will not get the results you expect without knowing all
  13612.      the details.  For example, *swpon can be overridden by the DOS command to
  13613.      execute by preceding the command with SW: (swap on) or NS: (swap off). 
  13614.      So if you had defined your Mail Reader (*mread Main Setup Variable) as
  13615.      SW:DELUXE.EXE in the main setup, changing *swpon would have no effect:
  13616.  
  13617.       ASSIGN *swpon 0         ;turn swapping OFF
  13618.       DOS *mread              ;same as DOS "SW:DELUXE.EXE" 
  13619.  
  13620.      Icom would swap itself out regardless, due to the SW: preceding the
  13621.      command.  In other cases, you may change a Main Setup Variable and find
  13622.      that it has no effect at all.  In many cases, by changing a Main Setup
  13623.      Variable, all you've done is changed the DEFAULT setting.  You may not
  13624.      have changed the variable Icom itself is working with.  For example, the
  13625.      $MSG_DIR System Variable holds the current Message Directory.  The
  13626.      directory in this variable is EITHER the Main Setup Variable (*msgdir) OR
  13627.      the BIF Variable (*[M]msgd) since you can override the Main Setup
  13628.      Variable with a setting in the BIF.  To change the variable that Icom is
  13629.  
  13630.  
  13631.  
  13632.  
  13633.      Intellicomm v2.01               SCRIPT.DOC                            217
  13634.      
  13635.      
  13636.  
  13637.      working with, you would change neither *msgdir nor *[M]msgd ... you'd
  13638.      change the $MSG_DIR System Variable.  Where this is the case, it will be
  13639.      pointed out in the summaries below, so be sure to see all the details
  13640.      before you set out working with these variables.
  13641.  
  13642.      NOTE: As with the BIF Variables, if you change a Main Setup Variable it
  13643.      does not change the .INI (INItialization) file on-disk.  It only changes
  13644.      the setting in MEMORY.  To save changes to disk you must use SAVEINI. 
  13645.      The $INI_NAME System Variable holds the filename of the currently loaded
  13646.      .INI (without the .INI extension).
  13647.  
  13648.      If you CHANGE any of the Main Setup Variables, you change the data that
  13649.      Icom is working with for the duration of the session (or until another
  13650.      .INI is loaded).  To avoid potential problems, you can either
  13651.      save/restore original INI data as we did above with the System Variables,
  13652.      or can simply use LOADINI $INI_NAME when your script ends, to re-load the
  13653.      original .INI and thus reset ALL the Main Setup Variables to their
  13654.      original values.  Until you're experienced with the FORMAT of the Main
  13655.      Setup Variables it is recommended that you do NOT change any of the main
  13656.      setup information.  To gain experience, use the normal Icom main setup
  13657.      menu to see what options go with a given item, then use the PRINT command
  13658.      (or simply view the ICOM.INI file in the File Viewer) to see how the
  13659.      options are represented.  Many options use NUMBERS to represent various
  13660.      options (0 means one thing, 1 means another 2 means something else, etc.,
  13661.      or 0 represents OFF while 1 represents ON for toggle items).  
  13662.  
  13663.      Note that several main setup variables will have no effect if you change
  13664.      them, until a SAVEINI / LOADINI is performed.  For example, if you change
  13665.      the *ssize (Screen Size) variable, the actual screen size will not change
  13666.      until a SAVEINI / LOADINI is performed.  LOADINI actually does the work
  13667.      of resetting Intellicomm with new values, but if you change main setup
  13668.      variables and use LOADINI *without* using SAVEINI first, you'll lose any
  13669.      changes you made to the main setup variables.  If you don't want to over-
  13670.      write the ICOM.INI file, do something like this:
  13671.  
  13672.       variable oldini $INI_NAME    ;SAVE original main setup filename
  13673.       ASSIGN *somevariable "Some value"
  13674.       ...
  13675.  
  13676.       SAVEINI "$TEMP"              ;save new values to a temporary INI file
  13677.       LOADINI "$TEMP"              ;load the temporary INI file to reset Icom
  13678.  
  13679.       ...                          ;main body of script goes here
  13680.  
  13681.       LOADINI oldini               ;reset with the usual values
  13682.       DELETE $HOME_DIR "$TEMP.INI" ;you can delete the file before your script
  13683.                                    ; exits, as long as you load another INI
  13684.                                    ; file first
  13685.  
  13686.  
  13687.  
  13688.  
  13689.      Intellicomm v2.01               SCRIPT.DOC                            218
  13690.      
  13691.      
  13692.  
  13693.      ╔═╡ User Settings ╞═════════════════════════════════════╗
  13694.      ║ Alt-1  First Last Name : *uname                       ║
  13695.      ║ Alt-2  BBS Password    : $PASSWORD                    ║
  13696.      ║ Alt-3  Street Address  : *uaddr                       ║
  13697.      ║ Alt-4  City, State/Prov: *ucity                       ║
  13698.      ║ Alt-5  ZIP/Postal Code : *uzip                        ║
  13699.      ║ Alt-6  Business Phone #: *ubphn                       ║
  13700.      ║ Alt-7  Home Phone #    : *uhphn                       ║
  13701.      ║ Alt-8  Date of Birth   : *udtob                       ║
  13702.      ║ Alt-9  General Use     : *alt9                        ║
  13703.      ║ Alt-0  General Use     : *alt0                        ║
  13704.      ╚═══════════════════════════════════════════════════════╝
  13705.  
  13706.      ╔═╡ General Settings ╞══════════════════════════════════╗
  13707.      ║ Password Access Key . . . N/A                         ║
  13708.      ║ Base and Startup Area . . *sarea                      ║
  13709.      ║ TAB / Shift-TAB moves the *swptab                     ║
  13710.      ║ Put Overlays in XMS/EMS . *overlay                    ║
  13711.      ║ Enable Swapping . . . . . *swpon                      ║
  13712.      ║ Release Time Slices?  . . *rslice                     ║
  13713.      ║ Drop RTS on Disk I/O? . . *droprts                    ║
  13714.      ║ Mouse Settings  . . . . . *mouse (see below)          ║
  13715.      ║ Use PATH to Locate Files  *pathsch                    ║
  13716.      ║ File Renumber Mode  . . . *rmode                      ║
  13717.      ║ Usage Log Renumber Total  *usenum                     ║
  13718.      ║ Capture Renumber Total  . *capnum                     ║
  13719.      ║ Message Renumber Total  . *msgnum                     ║
  13720.      ║ Reply Renumber Total  . . *repnum                     ║
  13721.      ║ Auto-Open Usage Log . . . *useopen                    ║
  13722.      ║ Open Capture on Connect . *capopen                    ║
  13723.      ║ Stamp Date/Time Cap Open  *capstamp                   ║
  13724.      ║ Sound . . . . . . . . . . *sound                      ║
  13725.      ║ Pager . . . . . . . . . . *pager                      ║
  13726.      ║ Date Format . . . . . . . *date                       ║
  13727.      ║ Date Separator  . . . . . *datesep                    ║
  13728.      ║ Time Format . . . . . . . *time                       ║
  13729.      ║ Time Separator  . . . . . *timesep                    ║
  13730.      ╚═══════════════════════════════════════════════════════╝ 
  13731.  
  13732.      Mouse Mode : 0=Off 1=Righthanded 2=Lefthanded
  13733.      Mouse Speed: not adjustable from scripts.
  13734.                                                               
  13735.      ╔═╡ Filenames and Paths ╞═══════════════════════════════╗
  13736.      ║ Mail Reader> *mread                                   ║
  13737.      ║ Reply Dir  > *repdir                                  ║
  13738.      ║ Message Dir> *msgdir                                  ║
  13739.      ║ Main Unpack> *unpak1                                  ║
  13740.      ║ 2nd  Unpack> *unpak2                                  ║
  13741.      ║ Arc. Viewer> *zipview                                 ║
  13742.      ║ File Viewer  *flister                                 ║
  13743.      ║ Extnl Editor *editor                                  ║
  13744.      ║ Alt-N Hotkey *hkey1c                                  ║
  13745.      ║  Description *hkey1t                                  ║
  13746.      ║ Alt-O Hotkey *hkey2c                                  ║
  13747.  
  13748.  
  13749.  
  13750.  
  13751.      Intellicomm v2.01               SCRIPT.DOC                            219
  13752.      
  13753.      
  13754.  
  13755.      ║  Description *hkey2t                                  ║
  13756.      ║ BIF Dir  . . *lbif                                    ║
  13757.      ║ Catalog Dir  *dbfpath                                 ║
  13758.      ║ Filelist Dir *lstdir                                  ║
  13759.      ║ Upload PATH  *updir                                   ║
  13760.      ║ Download Dir *dldir                                   ║
  13761.      ║ Script Dir . *scrdir                                  ║
  13762.      ║ Usage Log  . *usefile                                 ║
  13763.      ║ Capture File *capfile                                 ║
  13764.      ║ Screen Cap . *scap                                    ║
  13765.      ║ Swap Dir . . *swpdir                                  ║
  13766.      ║ Printer  . . *prn                                     ║
  13767.      ╚═══════════════════════════════════════════════════════╝
  13768.  
  13769.      ╔═╡ Screen/Color Settings ╞═════════════════════════════╗
  13770.      ║ Menu Style/Colors . . . . (See below)                 ║
  13771.      ║ Default Screen Size . . . *ssize                      ║
  13772.      ║ Screen Write Mode . . . . *vmode                      ║
  13773.      ║ Blank Screen # Seconds  . *scrblank                   ║
  13774.      ║ Status Window Delay . . . *sdelay                     ║
  13775.      ╚═══════════════════════════════════════════════════════╝
  13776.  
  13777.      ╔═╡ Screen/Color Settings ╞═════════════════════════════╗
  13778.      ║ Menu Style            *bstyle                         ║
  13779.      ║ Border                *border                         ║
  13780.      ║ Selected/Hilit        *bar                            ║
  13781.      ║ Unselected/background *norm                           ║
  13782.      ║ Bold/Hotkey           *bold                           ║
  13783.      ║ Terminal              *tcolor                         ║
  13784.      ║ Status Line           *scolor                         ║
  13785.      ╚═══════════════════════════════════════════════════════╝
  13786.                                          
  13787.      ╔═╡ Debugging Log Settings ╞════════════════════════════╗
  13788.      ║ Debugging Level . . . . . *dbglevel                   ║
  13789.      ║ Debugging Log Filename. . *dbgfname                   ║
  13790.      ║ Log Renumber Total  . . . *dbgnum                     ║
  13791.      ╚═══════════════════════════════════════════════════════╝
  13792.  
  13793.      ╔═╡ Sysop Settings ╞════════════════════════════════════╗
  13794.      ║ Export D/L's to TEXT FILE *xfile                      ║
  13795.      ║ Export by ID/Conference?  *xconf                      ║
  13796.      ║ BIF Format for Export . . *xbif                       ║
  13797.      ║ Move files to Subdir  . . *msdir                      ║
  13798.      ╚═══════════════════════════════════════════════════════╝
  13799.                                             
  13800.      ╔═╡ Terminal Settings ╞═════════════════════════════════╗
  13801.      ║ Default Comm. Port      > *port                       ║
  13802.      ║ Default Port Settings   > *csettings                  ║
  13803.      ║ Software Flow Control   > *flowctrl (see below)       ║
  13804.      ║ Hardware Flow Control   > *flowctrl (see below)       ║
  13805.      ║ Initialize Modem String > *minit                      ║
  13806.      ║ Modem Hangup String     > *mhang                      ║
  13807.      ║ Confirm Hangup? . . . . . *hconfirm                   ║
  13808.      ║ Drop DTR to Hangup? . . . *dtrhangup                  ║
  13809.  
  13810.  
  13811.  
  13812.  
  13813.      Intellicomm v2.01               SCRIPT.DOC                            220
  13814.      
  13815.      
  13816.  
  13817.      ║ Init Modem at Startup?  . *istart                     ║
  13818.      ║ Init Modem if Connected?  *cdinit                     ║
  13819.      ║ Status Bar  . . . . . . . *statbar                    ║
  13820.      ║ Status Bar Displays . . . *statbarsp                  ║
  13821.      ║ Scrollback Size [Kbytes]  *sbsize                     ║
  13822.      ║ Receive Buffer Size [K] . *rxbuf                      ║
  13823.      ║ Transmit Buffer Size [K]  *txbuf                      ║
  13824.      ║ Echo  . . . . . . . . . . *echo                       ║
  13825.      ║ Add Line Feeds  . . . . . *addlf                      ║
  13826.      ║ Backspace Destructive?  . *bsdest                     ║
  13827.      ║ Send DEL as Backspace?  . *bsswap                     ║
  13828.      ║ Enable 16550 if Found?  . *16550fl                    ║
  13829.      ║ 16550 Receive Trigger . . *16550rx                    ║
  13830.      ║ 16550 Transmit Trigger  . *16550tx                    ║
  13831.      ║ ENQ Response/@SCRIPT  . . *enqstr                     ║
  13832.      ╚═══════════════════════════════════════════════════════╝
  13833.  
  13834.      *flowctrl: ADD the following values;
  13835.       0 = No flow control
  13836.       1 = XON/XOFF
  13837.       2 = XON=any char/XOFF
  13838.       4 = CTS/RTS
  13839.       8 = DSR/DTR
  13840.      EXAMPLES:
  13841.       ASSIGN *flowctrl 1   ;XON/XOFF only
  13842.       ASSIGN *flowctrl 4   ;CTS/RTS only
  13843.       ASSIGN *flowctrl 5   ;XON/XOFF and CTS/RTS (1 + 4)
  13844.      You must use a 'PORT $COM_PORT' command (re-open the current COM port)
  13845.      for changes to *flowctrl to take effect.
  13846.  
  13847.      ╔═╡ Dialer Settings ╞═══════════════════════════════════╗
  13848.      ║ Dial Prefix 1           > *dpre1                      ║
  13849.      ║ Dial Prefix 2 . . . . . . *dpre2                      ║
  13850.      ║ Dial Prefix 3 . . . . . . *dpre3                      ║
  13851.      ║ ! Dial Code . . . . . . . *dcode!                     ║
  13852.      ║ @ Dial Code . . . . . . . *dcode@                     ║
  13853.      ║ $ Dial Code . . . . . . . *dcode$                     ║
  13854.      ║ Dial Suffix . . . . . . . *dsuff                      ║
  13855.      ║ Dial Connected          > *dconnect                   ║
  13856.      ║ Minimum CONNECT Speed   > *minspeed                   ║
  13857.      ║ Auto Baud Adjustment    > *baudetect                  ║
  13858.      ║ Dial Busy/Retry 1       > *dagain1                    ║
  13859.      ║ Dial Busy/Retry 2       > *dagain2                    ║
  13860.      ║ Dial Busy/Retry 3       > *dagain3                    ║
  13861.      ║ Exclude Dialing 1       > *dabort1                    ║
  13862.      ║ Exclude Dialing 2       > *dabort2                    ║
  13863.      ║ Exclude Dialing 3       > *dabort3                    ║
  13864.      ║ Dial Timeout  . . . . . . *dtime                      ║
  13865.      ║ Stop Dialing  . . . . . . *dstop                      ║
  13866.      ║ Pause Between Dials . . . *dpause                     ║
  13867.      ║ Attempts per BIF/Cycle  . *dcycle                     ║
  13868.      ║ LD Service Phone Num  . . *ldnum                      ║
  13869.      ╚═══════════════════════════════════════════════════════╝
  13870.                                              
  13871.  
  13872.  
  13873.  
  13874.  
  13875.      Intellicomm v2.01               SCRIPT.DOC                            221
  13876.      
  13877.      
  13878.  
  13879.      ╔═╡ File Transfer Settings ╞════════════════════════════╗
  13880.      ║ POSTFILE.SCR Settings     (See below)                 ║
  13881.      ║ Move Old Downloads?     > *dlmove                     ║
  13882.      ║ Cancel D/L No Time/Bytes  *candl                      ║
  13883.      ║ Auto Zmodem Receive . . . *zauto                      ║
  13884.      ║ Auto Zmodem Protocol  . . *zprotocol                  ║
  13885.      ║ Zmodem Crash Recovery . . *zrresume                   ║
  13886.      ║ Filename Conversion . . . *fconv                      ║
  13887.      ║ Manage Duplicate Files  . *fmanage                    ║
  13888.      ║ Delete Aborted Transfers  *delabort                   ║
  13889.      ║ Disk Buffer Size [Kbytes] *xdbufsiz                   ║
  13890.      ║ ASCII Transfers . . . . . (See table below)           ║
  13891.      ╚═══════════════════════════════════════════════════════╝
  13892.  
  13893.      POSTFILE.SCR Settings: Settings for POSTFILE.SCR are stored in
  13894.      $SCRIPT_DIR\POSTFILE.INI.  This is a straight ASCII text file that stores
  13895.      one setting per line, and the file can be read and/or modified with a
  13896.      script if necessary.  See POSTINI.SCR for details; look for FOPEN, FGETS
  13897.      and FPUTS commands.  These read and write to POSTINI.SCR just as you can
  13898.      do in your own scripts.  Do not add any new settings to POSTFILE.INI,
  13899.      however, nor change the order in which the items are stored.
  13900.  
  13901.      ASCII Transfers:                                               
  13902.      ╔═╡ ASCII Transfer Details ╞════════════════════════════╗
  13903.      ║ Line Pacing/Delay [tenths] *alpace                    ║
  13904.      ║ Char Pacing/Delay [tenths] *acpace                    ║
  13905.      ║ Receive Timeout  [seconds] *atmout                    ║
  13906.      ╚═══════════════════════════════════════════════════════╝
  13907.                                                     
  13908.      ╔═╡ External Protocols ╞════════════════════════════════╗
  13909.      ║                                                       ║
  13910.      ║      Descrip  Hotkey  Receive  Send Cmd.  Ask?        ║
  13911.      ║                                                       ║
  13912.      ║  1.  *prot1n  *prot1k *prot1r  *prot1s    *prot1f     ║
  13913.      ║  2.  *prot2n  *prot2k *prot2r  *prot2s    *prot2f     ║
  13914.      ║  3.  *prot3n  *prot3k *prot3r  *prot3s    *prot3f     ║
  13915.      ║  etc... up to 8                                       ║
  13916.      ╚═══════════════════════════════════════════════════════╝ 
  13917.  
  13918.      ╔═╡ Host Mode Settings ╞════════════════════════════════╗
  13919.      ║ Sysop Name  . . . . . . . *hsysop                     ║
  13920.      ║ Host Download Dir . . . . *hdldir                     ║
  13921.      ║ Host Upload Dir . . . . . *huldir                     ║
  13922.      ║ Level 1 Password  . . . . (See below)                 ║
  13923.      ║ Level 2 Password  . . . . (See below)                 ║
  13924.      ║ DOS Shell Password  . . . (See below)                 ║
  13925.      ║ Abort Host Password . . . (See below)                 ║
  13926.      ║ Modem Init Host Command . *hminit                     ║
  13927.      ║ Modem Offhook Command . . *hoffhook                   ║
  13928.      ║ Modem Answer Command  . . *manswer                    ║
  13929.      ║ Modem OK Message  . . . . *mokay                      ║
  13930.      ║ Modem RING Message  . . . *mring                      ║
  13931.      ║ Answer on Ring #  . . . . *hrings                     ║
  13932.      ║ Main Setup File for Host  *hini                       ║
  13933.  
  13934.  
  13935.  
  13936.  
  13937.      Intellicomm v2.01               SCRIPT.DOC                            222
  13938.      
  13939.      
  13940.  
  13941.      ║ Level 1 can OVERWRITE?  . *hoverwrite (0=No; 1=Yes    ║
  13942.      ║ Level 1 EXTNL Protocols?  *hextp (0=No; 1=Yes)        ║
  13943.      ║ Direct CABLE Link?  . . . *hcable (0=Modem; 1=Cable)  ║
  13944.      ╚═══════════════════════════════════════════════════════╝ 
  13945.  
  13946.      The host passwords are stored separately in the file $HOME_DIR\HOST.PWD. 
  13947.      This is a straight ASCII text file and each password is stored on a
  13948.      separate line.  To read the passwords:
  13949.  
  13950.      variable pass1
  13951.      variable pass2
  13952.      variable dospass
  13953.      variable abortpass
  13954.      variable f $HOME_DIR "HOST.PWD"
  13955.  
  13956.      fopen f f "r"                  ;open in read mode
  13957.      fgets pass1 f                  ;Level 1 Password
  13958.      fgets pass2 f                  ;Level 2 Password
  13959.      fgets dospass f                ;DOS Shell Password
  13960.      fgets abortpass f              ;Abort Host Password
  13961.      fclose f                       ;close HOST.PWD
  13962.  
  13963.      To write new passwords to disk, replace "r" (read) in the FOPEN command
  13964.      with "w" (write), and replace the four FGETS commands with FPUTS.  Note
  13965.      that FPUTS reverses the order of the variable and the file handle:
  13966.  
  13967.      fputs f pass1                  ;file handle first
  13968.  
  13969.      ╔═╡ Comm Port Settings ╞════════════════════════════════╗
  13970.      ║ COM1 Base Address . . . . *com1b                      ║
  13971.      ║      IRQ Line . . . . . . *com1i                      ║
  13972.      ║ COM2 Base Address . . . . *com2b                      ║
  13973.      ║      IRQ Line . . . . . . *com2i                      ║
  13974.      ║ COM3 Base Address . . . . *com3b                      ║
  13975.      ║      IRQ Line . . . . . . *com3i                      ║
  13976.      ║ etc... up to 8                                        ║
  13977.      ╚═══════════════════════════════════════════════════════╝
  13978.  
  13979.      You must use a 'PORT' command (re-open the current COM port) for changes
  13980.      to *com?b / *com?i to take effect.
  13981.                                                               
  13982.      ╔═╡ File Tagger Settings ╞══════════════════════════════╗
  13983.      ║ File Transfer Speed [CPS] *acps                       ║
  13984.      ║ Tagger Screen Size  . . . *tssize                     ║
  13985.      ║ Description Lines Shown . *split                      ║
  13986.      ║ Auto Hilight Bar Lock . . *ahlock                     ║
  13987.      ║ View Date Filters Noted?  *fnote                      ║
  13988.      ║ Duplicate Checking  . . . *ckdupe                     ║
  13989.      ║ Use DOWNLOAD.NDX  . . . . *dndx                       ║
  13990.      ║ File .EXTensions in DNDX  *dndxext                    ║
  13991.      ║ DOWNLOAD.NDX Directories  Stored in file DNDX.DIR     ║
  13992.      ║ Filter Graphics Chars . . *fgraph                     ║
  13993.      ║ Replace Shorter Comments  *ckcmts                     ║
  13994.      ║ Extract NEWFILES / mail . *qwknew                     ║
  13995.  
  13996.  
  13997.  
  13998.  
  13999.      Intellicomm v2.01               SCRIPT.DOC                            223
  14000.      
  14001.      
  14002.  
  14003.      ║ Auto Import New Files . . *taguse                     ║
  14004.      ║ Keep an Upload Catalog  . *tagimpt                    ║
  14005.      ║ Purge Noted # Days Old  . *prgnote                    ║
  14006.      ║ Purge Untagged # Days Old *purge                      ║
  14007.      ║ Auto Pack when # Purged . *ppack                      ║
  14008.      ║ Auto Bookmark Update  . . *abook                      ║
  14009.      ║ Auto View Date Update . . *afdate                     ║
  14010.      ╚═══════════════════════════════════════════════════════╝
  14011.                                                         
  14012.      ╔═╡ Tagger Keywords ╞═══════════════════════════════════╗
  14013.      ║ Strip Comment Keywords  . Stored in file STRIP.KWD    ║
  14014.      ║ Replace Word(s) Keywords  Stored in file REPLACE.KWD  ║
  14015.      ║ Exclude File Keywords . . Stored in file EXCLUDE.KWD  ║
  14016.      ║ Note File Keywords  . . . Stored in file NOTE.KWD     ║
  14017.      ║ Auto Tag Remaining Files? *atag                       ║
  14018.      ╚═══════════════════════════════════════════════════════╝
  14019.  
  14020.  
  14021.  
  14022.  
  14023.      Intellicomm v2.01               SCRIPT.DOC                            224
  14024.      
  14025.      
  14026.  
  14027.                                   D.  COLOR CODES
  14028.  
  14029.  
  14030.      Using the codes below, you can create your own colors for use with the
  14031.      SCROLL (scroll or clear an area of the screen) and PRINTRAW commands
  14032.      (print directly to the screen in a specific color).  You can also assign
  14033.      custom colors to the color variables Icom uses: $NORM_COLOR, $BOLD_COLOR,
  14034.      $BORDER_COLOR, etc., to draw menus (BARMENU, etc) and boxes (BOX).
  14035.  
  14036.      If your script is going to be used by others (if you intend to upload it
  14037.      to a BBS later, etc.) it is recommended that you do NOT use custom colors
  14038.      in your script at all.  Laptop and monochrome displays cannot display all
  14039.      colors properly, so even if your script looks pretty on your screen, it
  14040.      is possible that it will be unreadable on someone else's screen.  By
  14041.      using $BAR_COLOR, $BORDER_COLOR, $NORM_COLOR, $TERM_COLOR, $STAT_COLOR
  14042.      (see the System Variables appendix above for details) you can use the
  14043.      colors that the USER has set up in Intellicomm.  This will give your
  14044.      script an integrated look with Intellicomm, and whenever the user changes
  14045.      colors in the Icom main setup, your script will also make use of the new
  14046.      colors!
  14047.  
  14048.      To create a custom color first pick your background color from the table
  14049.      below (the number of the color).  Background colors can be ONLY the
  14050.      colors listed in the first column of the table (0-7).  If you try to use
  14051.      a background color above 7, the foreground color will BLINK.  Once you
  14052.      have your background color, multiply it by 16, then add the foreground
  14053.      color.  Any of the 16 colors (0-15) may be used for a foreground color. 
  14054.      The formula to create a color (and the background color limitation of
  14055.      using only 0-7) has nothing to do with the script language; it's simply
  14056.      how IBM video adaptors work.  The formula is (with 'x' representing
  14057.      multiplication):
  14058.  
  14059.                         COLOR = background x 16 + foreground
  14060.  
  14061.                        0  Black               8 Dark Gray
  14062.                        1  Blue                9 Light Blue
  14063.                        2  Green              10 Light Green
  14064.                        3  Cyan               11 Light Cyan
  14065.                        4  Red                12 Light Red
  14066.                        5  Magenta            13 Light Magenta
  14067.                        6  Brown              14 Yellow
  14068.                        7  Light Gray         15 White
  14069.  
  14070.                                   +128  Blink
  14071.  
  14072.      For example, to display white foreground text on a red background you'd
  14073.      multiply 4 (Red) by 16, then add 15 (White).  The number you come up with
  14074.      (79) could then be used in PRINTRAW and SCROLL commands, or could be
  14075.      ASSIGNed to the various COLOR System Variables to change the colors Icom
  14076.      uses with the BOX, BOXGETS, MENUBAR, etc. commands.  With PRINTRAW the
  14077.      color is the 3rd parameter:
  14078.  
  14079.        PRINTRAW $SCRN_X $SCRN_Y 79 "White text on a red background"
  14080.  
  14081.  
  14082.  
  14083.  
  14084.      Intellicomm v2.01               SCRIPT.DOC                            225
  14085.      
  14086.      
  14087.  
  14088.      To make the foreground text blink on and off, just add 128 to the
  14089.      original color value (79 + 128 = 207):
  14090.  
  14091.       PRINTRAW 1 1 207 "White blinking text on a red background"
  14092.  
  14093.      D.1  Using Color Variables
  14094.  
  14095.      If you intend to use custom colors in your script, you still might want
  14096.      to use variables to specify colors, instead of specifying color values in
  14097.      individual SCROLL/PRINTRAW/CLS, etc. commands.  Example:
  14098.  
  14099.        VARIABLE color1 7  ;gray on black
  14100.        VARIABLE color2 23 ;light gray on blue
  14101.  
  14102.          ;now, use these color variables in the rest of the script
  14103.  
  14104.        PRINTRAW 1 1 color1 "Some text"
  14105.        CLS color2
  14106.        ...etc.
  14107.  
  14108.      Then, if you want to change the colors later all you'll have to do is
  14109.      change the color assigned to the variables (make one change), instead of
  14110.      having to change each individual color code in the commands themselves.  
  14111.  
  14112.      Alternatively, you can simply ASSIGN new color codes to the usual Icom
  14113.      color variables, then use BOXGETS, the MENUXXXX commands, WNDOPEN, PRINT,
  14114.      etc (which all use the regular $XXXX_COLOR variables).  Just make sure to
  14115.      save the old color values and restore them when your script exits:
  14116.  
  14117.       VARIABLE old_norm_color $NORM_COLOR  ;save existing color values
  14118.       VARIABLE old_border_color $BORDER_COLOR
  14119.  
  14120.       ASSIGN $NORM_COLOR 112   ;black on light gray (semi-paper white)
  14121.       ASSIGN $BORDER_COLOR 31  ;white on blue
  14122.  
  14123.       WNDOPEN "Window Border is White on Blue"
  14124.       PRINT "Text in window is Black on White"
  14125.  
  14126.       ASSIGN $NORM_COLOR old_norm_color      ;restore original values
  14127.       ASSIGN $BORDER_COLOR old_border_color
  14128.  
  14129.  
  14130.                                   E.  ASCII CODES
  14131.  
  14132.  
  14133.      ASCII stands for "American Standard Code for Information Interchange",
  14134.      and the ASCII character set is what lets our computers display things on-
  14135.      screen and print things such as this document.  Computers understand one
  14136.      thing, and one thing only: numbers.  They don't understand the letters
  14137.      numbers or symbols we humans use, so someone had to assign numbers to all
  14138.      the characters and symbols, so that computers could display and print
  14139.      characters that we humans use.  The ASCII codes listed below are the
  14140.      numeric equivalent of characters/symbols that most all personal computers
  14141.      use.
  14142.  
  14143.  
  14144.  
  14145.  
  14146.      Intellicomm v2.01               SCRIPT.DOC                            226
  14147.      
  14148.      
  14149.  
  14150.      E.1  How to Use the ASCII Table
  14151.  
  14152.      The numbers listed in the 'Num' column below are the ASCII codes for all
  14153.      the characters, and are for use only with the SENDKEY command.  SENDKEY
  14154.      32 is equivalent to SENDNC " " (send a space; SENDNC doesn't add a CR as
  14155.      SEND does).  SENDKEY 8 sends a backspace (BS) to the BBS, SENDKEY 65
  14156.      sends the letter "A" (see the extended keycodes in the next section for
  14157.      more).
  14158.  
  14159.      The characters listed in the 'Char' column are the character equivalents,
  14160.      which can be used in any script 'string' (between quotes).  To send a
  14161.      Ctrl-C to the BBS you'd use SENDNC "^C".  To send two ESC character you'd
  14162.      use SENDNC "^[^[", etc.  The "Name" column (control characters) is for
  14163.      reference only.  You cannot use SEND ESC to send an ESC character.
  14164.  
  14165.                 Num Char Name    Num Char     Num Char     Num Char
  14166.                 -------------    --------     --------     --------
  14167.                  0   ^@  NUL      32           64    @      96    `
  14168.                  1   ^A  SOH      33    !      65    A      97    a
  14169.                  2   ^B  STX      34    "      66    B      98    b
  14170.                  3   ^C  ETX      35    #      67    C      99    c
  14171.                  4   ^D  EOT      36    $      68    D     100    d
  14172.                  5   ^E  ENQ      37    %      69    E     101    e
  14173.                  6   ^F  ACK      38    &      70    F     102    f
  14174.                  7   ^G  BEL      39    '      71    G     103    g
  14175.                  8   ^H  BS       40    (      72    H     104    h
  14176.                  9   ^I  HT       41    )      73    I     105    i
  14177.                 10   ^J  LF       42    *      74    J     106    j
  14178.                 11   ^K  VT       43    +      75    K     107    k
  14179.                 12   ^L  FF       44    ,      76    L     108    l
  14180.                 13   ^M  CR       45    -      77    M     109    m
  14181.                 14   ^N  SO       46    .      78    N     110    n
  14182.                 15   ^O  SI       47    /      79    O     111    o
  14183.                 16   ^P  DLE      48    0      80    P     112    p
  14184.                 17   ^Q  DC1      49    1      81    Q     113    q
  14185.                 18   ^R  DC2      50    2      82    R     114    r
  14186.                 19   ^S  DC3      51    3      83    S     115    s
  14187.                 20   ^T  DC4      52    4      84    T     116    t
  14188.                 21   ^U  NAK      53    5      85    U     117    u
  14189.                 22   ^V  SYN      54    6      86    V     118    v
  14190.                 23   ^W  ETB      55    7      87    W     119    w
  14191.                 24   ^X  CAN      56    8      88    X     120    x
  14192.                 25   ^Y  EM       57    9      89    Y     121    y
  14193.                 26   ^Z  SUB      58    :      90    Z     122    z
  14194.                 27   ^[  ESC      59    ;      91    [     123    {
  14195.                 28   ^\  FS       60    <      92    \     124    |
  14196.                 29   ^]  GS       61    =      93    ]     125    }
  14197.                 30   ^^  RS       62    >      94    ^     126    ~
  14198.                 31   ^_  US       63    ?      95    _     127   DEL
  14199.  
  14200.      IBM enhanced the standard ASCII set and added the characters in the next
  14201.      table below.  To enter these characters in a "string" in a script, hold
  14202.      down your [Alt] key, then enter the number in the 'Num' column on the
  14203.      NUMERIC KEYPAD, and release the [Alt] key (don't use the numbers at the
  14204.  
  14205.  
  14206.  
  14207.  
  14208.      Intellicomm v2.01               SCRIPT.DOC                            227
  14209.      
  14210.      
  14211.  
  14212.      top of the keyboard... they don't work).  For example, to enter this
  14213.      command in a script:
  14214.  
  14215.      print "Ç"
  14216.  
  14217.      type 'print"', and while holding down the [Alt] key, press [1], [2], [8] 
  14218.      (character 128 is Ç) on the NUMERIC KEYPAD, release the [Alt] key (the Ç
  14219.      will then then be inserted), then enter the trailing quote (").
  14220.  
  14221.      To send extended characters out the COM port, either use the same
  14222.      technique above with SEND or SENCNC, or use the number of the character
  14223.      (the 'Num' column below) with SENDKEY.  E.g., SENDKEY 128 sends Ç.
  14224.  
  14225.      This table may not be printed properly if your printer can't handle
  14226.      extended ASCII characters:
  14227.  
  14228.                 Num Char     Num Char     Num Char     Num Char
  14229.                 --------     --------     --------     --------
  14230.                 128   Ç      144   É      192   └      208   ╨ 
  14231.                 129   ü      145   æ      193   ┴      209   ╤ 
  14232.                 130   é      146   Æ      194   ┬      210   ╥ 
  14233.                 131   â      147   ô      195   ├      211   ╙ 
  14234.                 132   ä      148   ö      196   ─      212   ╘ 
  14235.                 133   à      149   ò      197   ┼      213   ╒ 
  14236.                 134   å      150   û      198   ╞      214   ╓ 
  14237.                 135   ç      151   ù      199   ╟      215   ╫ 
  14238.                 136   ê      152   ÿ      200   ╚      216   ╪ 
  14239.                 137   ë      153   Ö      201   ╔      217   ┘ 
  14240.                 138   è      154   Ü      202   ╩      218   ┌ 
  14241.                 139   ï      155   ¢      203   ╦      219   █ 
  14242.                 140   î      156   £      204   ╠      220   ▄ 
  14243.                 141   Ä      157   ¥      205   ═      221   ▌ 
  14244.                 142   Ä      158   ₧      206   ╬      222   ▐ 
  14245.                 143   Å      159   ƒ      207   ╧      223   ▀ 
  14246.                 160   á      176   ░      224   α      240   ≡
  14247.                 161   í      177   ▒      225   ß      241   ±
  14248.                 162   ó      178   ▓      226   Γ      242   ≥
  14249.                 163   ú      179   │      227   π      243   ≤
  14250.                 164   ñ      180   ┤      228   Σ      244   ⌠
  14251.                 165   Ñ      181   ╡      229   σ      245   ⌡
  14252.                 166   ª      182   ╢      230   µ      246   ÷
  14253.                 167   º      183   ╖      231   τ      247   ≈
  14254.                 168   ¿      184   ╕      232   Φ      248   Φ
  14255.                 169   ⌐      185   ╣      233   Θ      249   Θ
  14256.                 170   ¬      186   ║      234   Ω      250   Ω
  14257.                 171   ½      187   ╗      235   δ      251   √
  14258.                 172   ¼      188   ╝      236   ∞      252    
  14259.                 173   ¡      189   ╜      237   φ      253   ²
  14260.                 174   «      190   ╛      238   ε      254   ■
  14261.                 175   »      191   ┐      239   ∩      255   
  14262.  
  14263.  
  14264.  
  14265.  
  14266.      Intellicomm v2.01               SCRIPT.DOC                            228
  14267.      
  14268.      
  14269.  
  14270.                                  F.  KEYBOARD CODES
  14271.  
  14272.      As with the characters computers display on the screen (see ASCII codes
  14273.      above), computers are unable to understand what an [A] or [B] is, since
  14274.      computers understand numbers and only numbers.  So again, someone had to
  14275.      assign numbers to all the keys on the keyboard, and the various
  14276.      combinations of key presses such as [Alt-A], [Shift-F1] so that the
  14277.      computer could understand various key presses, and separate one key from
  14278.      another.  Intellicomm's script processor does recognize text for the
  14279.      standard keys (you needn't deal with numbers to check for an [A] key
  14280.      press for example), but text equivalents are not available for most of
  14281.      the extended keys such as [Alt-A], [F1], etc.  The tables below list the
  14282.      text equivalents of various key presses (where available) or the NUMBER
  14283.      of the key press where a text equivalent is not available.  You'll need
  14284.      these keyboard codes for semi-advanced script projects where you need
  14285.      direct control over the keyboard.
  14286.  
  14287.      F.1  How to use the Keyboard Codes
  14288.  
  14289.      The tables below list all keys on a standard IBM XT or enhanced (101 key)
  14290.      AT keyboard.  Note that the [F11] and [F12] function keys are only
  14291.      available on AT keyboards, so avoid using these two keys if you'll be
  14292.      distributing your script to the general public.
  14293.  
  14294.      The 'Key' column lists the actual key, the 'Norm' column lists the code
  14295.      of the key when pressed alone (without [Shift], [Ctrl] or [Alt]), the
  14296.      'Shift' column lists the code of the key when pressed in combination with
  14297.      either the left or right [Shift] key, the 'Ctrl' column lists the code of
  14298.      the key when pressed in combination with either the left or right [Ctrl]
  14299.      key,  and the 'Alt' column lists the code of the key when pressed in
  14300.      combination with either the left or right [Alt] key.
  14301.  
  14302.      The most common use of these tables is for use with the INKEY, INKEYW
  14303.      INKEYT and SENDKEY commands, or with the $HOTKEY_? variables.  The
  14304.      numbers and/or characters in the tables below show you how to check or
  14305.      specify a given key press.  Examples follow.
  14306.  
  14307.      Regular key presses (with a value below 255... keys in the standard ASCII
  14308.      code set) are always specified as a regular character between double
  14309.      quotes ("A", "B", "C", etc).  Common control characters such as [Ctrl-A],
  14310.      [Ctrl-B], [Ctrl-C] are specified as a regular character preceded by a
  14311.      caret (^), between double quotes ("^A", "^B", "^C").  Extended key
  14312.      presses are always specified as a number WITHOUT double quotes ([Alt-A]
  14313.      for example is key code 7680).
  14314.  
  14315.      Note that if $KEY_CHECK is non-zero (non-zero means $KEY_CHECK is ON),
  14316.      Intellicomm's script processor and Icom's Terminal will 'eat' many
  14317.      extended key codes.  For example, [Alt-A] is the standard Icom key to
  14318.      enter the Text Editor; in order to use [Alt-A] in your script you should
  14319.      set the $KEY_CHECK variable to zero before using INKEY / INKEYW / INKEYT:
  14320.  
  14321.       variable code
  14322.       variable old_kcheck $KEY_CHECK     ;save original value
  14323.       assign $KEY_CHECK 0                ;set to 0 to check for extended key
  14324.  
  14325.  
  14326.  
  14327.  
  14328.      Intellicomm v2.01               SCRIPT.DOC                            229
  14329.      
  14330.      
  14331.  
  14332.                                          ; codes
  14333.       
  14334.       printnc "Press a key: "
  14335.       inkeyw code                        ;stores the key code in variable
  14336.                                          ; 'code'
  14337.  
  14338.       print "^M^JKey code is: " code
  14339.       assign $KEY_CHECK old_kcheck       ;reset to original value
  14340.  
  14341.      NOTE: Various references to "extended key codes" are made in this
  14342.      document. "Extended" key codes are NUMERIC key codes below that are not
  14343.      specified in double quotes.  A regular press of the [A] key, or [Shift-
  14344.      A], or [Ctrl-A] are NOT extended key codes (you can see this by looking
  14345.      at the table below, noticing that all of these [A] key codes are between
  14346.      double quotes; "a", "A", "^A").  Of the various [Al key combinations,
  14347.      only [Alt-A] is an 'extended' key code (extended key code # 7680).  For
  14348.      commands or variables which specify that you MUST use an extended key
  14349.      code (the $HOTKEY_? variables for example), you cannot use any of the
  14350.      codes listed in double quotes below.  This is not permitted:
  14351.  
  14352.       assign $HOTKEY_1 "A"  ;[A] is not an extended key code
  14353.  
  14354.      This is fine:
  14355.  
  14356.       assign $HOTKEY_1 7680 ;[Alt-A] is an extended key code
  14357.  
  14358.      F.2  Example of Usage
  14359.  
  14360.      You must use the same format as listed in the tables below to test for
  14361.      various key strokes.  The following example tests for all possible
  14362.      combination of the [A] key:
  14363.  
  14364.       variable code
  14365.       assign $KEY_CHECK 0   ;Necessary when checking for EXTENDED key codes
  14366.                             ; which Icom uses for some function.  Most
  14367.                             ; extended key codes ARE used by Intellicomm for
  14368.                             ; various functions.  Below we're checking for
  14369.                             ; [Alt-A], and since Icom uses [Alt-A] for "Text
  14370.                             ; Editor" we have to TELL Intellicomm not to
  14371.                             ; process any extended keys, or Icom will simply
  14372.                             ; enter the Text Editor if the user presses [Alt-
  14373.                             ; -A]
  14374.  
  14375.       printnc "Press [a], [Shift-a], [Ctrl-a], or [Alt-a]: "
  14376.       inkeyw code
  14377.       assign $KEY_CHECK 1   ;allow Icom to process extended key codes again
  14378.  
  14379.       if code = "a"  print "[a] was pressed"
  14380.       if code = "A"  print "[Shift-a] was pressed"
  14381.       if code = "^A" print "[Ctrl-a] or [Ctrl-A] was pressed"
  14382.       if code = 7680 print "[Alt-a] or [Alt-A] was pressed"
  14383.  
  14384.      Note that for [Ctrl] and [Alt] key combinations, [Alt-A] is the same as
  14385.      [Alt-a], and [Ctrl-A] is the same as [Ctrl-a] (case is not significant). 
  14386.  
  14387.  
  14388.  
  14389.  
  14390.      Intellicomm v2.01               SCRIPT.DOC                            230
  14391.      
  14392.      
  14393.  
  14394.      UPPERCASE/lowercase applies only to the 'Norm' and 'Shift' columns.
  14395.      If the [Caps Lock] is enabled, 'Norm' and 'Shift' will be reversed (i.e.
  14396.      a normal [a] keypress is "A" and a [Shift-a] keypress is "a").  In most
  14397.      cases, if you want to check for an [A] keypress, you'll check for both
  14398.      "a" and "A" so that the user can ignore the state of the [Caps Lock] key:
  14399.  
  14400.        variable key
  14401.  
  14402.        inkeyw key
  14403.        switch key
  14404.          case "A"
  14405.          case "a"
  14406.            ...      ;do something for either case, UPPER or lower
  14407.          endcase
  14408.          case "B"
  14409.          case "b"
  14410.            ...
  14411.          endcase
  14412.          ...etc
  14413.        endswitch
  14414.  
  14415.      The state of the [Num Lock] key also affects the keys on the numeric
  14416.      keypad, as discussed below.
  14417.  
  14418.      NOTE: Where "N/A" (not applicable) is listed below, it means that the
  14419.      keyboard hardware is not capable of returning a key code for a given
  14420.      state.  For example, [Ctrl-1] doesn't return any key code at all, and
  14421.      such a key press will not even been seen by INKEY, INKEYW, INKEYT.  N/A
  14422.      keys are a limitation of PC keyboard hardware and not of Intellicomm's
  14423.      script language.... just as the numbers returned by various keys are
  14424.      simply what PC hardware uses and are not assigned by the script language
  14425.      (the same numbers will work in a real program, or in any other script
  14426.      language that uses the regular keyboard scan codes).
  14427.  
  14428.      Key    Norm     Shift    Ctrl      Alt 
  14429.      ---------------------------------------------------------------
  14430.       A       "a"      "A"     "^A"     7680
  14431.       B       "b"      "B"     "^B"    12288
  14432.       C       "c"      "C"     "^C"    11776
  14433.       D       "d"      "D"     "^D"     8192
  14434.       E       "e"      "E"     "^E"     4608
  14435.       F       "f"      "F"     "^F"     8448
  14436.       G       "g"      "G"     "^G"     8704
  14437.       H       "h"      "H"     "^H"     8960
  14438.       I       "i"      "I"     "^I"     5888
  14439.       J       "j"      "J"     "^J"     9216
  14440.       K       "k"      "K"     "^K"     9472
  14441.       L       "l"      "L"     "^L"     9728
  14442.       M       "m"      "M"     "^M"    12800
  14443.       N       "n"      "N"     "^N"    12544
  14444.       O       "o"      "O"     "^O"     6144
  14445.       P       "p"      "P"     "^P"     6400
  14446.       Q       "q"      "Q"     "^Q"     4096
  14447.       R       "r"      "R"     "^R"     4864
  14448.  
  14449.  
  14450.  
  14451.  
  14452.      Intellicomm v2.01               SCRIPT.DOC                            231
  14453.      
  14454.      
  14455.  
  14456.       S       "s"      "S"     "^S"     7936
  14457.       T       "t"      "T"     "^T"     5120
  14458.       U       "u"      "U"     "^U"     5632
  14459.       V       "v"      "V"     "^V"    12032
  14460.       W       "w"      "W"     "^W"     4352
  14461.       X       "x"      "X"     "^X"    11520
  14462.       Y       "y"      "Y"     "^Y"     5376
  14463.       Z       "z"      "Z"     "^Z"    11264
  14464.       1       "1"      "1"      N/A    30720
  14465.       2       "2"      "2"      768    30976
  14466.       3       "3"      "3"      N/A    31232
  14467.       4       "4"      "4"      N/A    31488
  14468.       5       "5"      "5"      N/A    31744
  14469.       6       "6"      "6"      N/A    32000
  14470.       7       "7"      "7"      N/A    32256
  14471.       8       "8"      "8"      N/A    32512
  14472.       9       "9"      "9"      N/A    32768
  14473.       0       "0"      "0"      N/A    33024
  14474.       ,       ","      ","      N/A    13056
  14475.       .       "."      "."      N/A    13312
  14476.       /       "/"      "/"      N/A    13568
  14477.       ;       ";"      ";"      N/A     9984
  14478.       '       "'"      "'"      N/A    10240
  14479.       [       "["      "["     "^["     6656
  14480.       ]       "]"      "]"     "^]"     6912
  14481.       `       "`"      "`"      N/A    10496
  14482.       -       "-"      "-"     "^-"    33280
  14483.       =       "="      "="      N/A    33536
  14484.       \       "\"      "\"     "^\"    11008
  14485.  
  14486.      Key    Norm     Shift    Ctrl      Alt 
  14487.      ---------------------------------------------------------------
  14488.      F1     15104    21504    24064    26624
  14489.      F2     15360    21760    24320    26880
  14490.      F3     15616    22016    24576    27136
  14491.      F4     15872    22272    24832    27392
  14492.      F5     16128    22528    25088    27648
  14493.      F6     16384    22784    25344    27904
  14494.      F7     16640    23040    25600    28160
  14495.      F8     16896    23296    25856    28416
  14496.      F9     17152    23552    26112    28672
  14497.      F10    17408    23808    26368    28928
  14498.      F11    34048    34560    35072    35584
  14499.      F12    34304    34816    35328    35840
  14500.      Enter   "^M"     "^M"     "^J"     7168
  14501.      Ins    20992    20992    37376    41472
  14502.      Del    21248    21284    37632    41728
  14503.      Esc     "^["     "^["     "^["      256
  14504.  
  14505.      NOTE: The values in the table below assume that [Num Lock] is OFF.  If
  14506.      [Num Lock] is ON, and the numeric keypad [Home], [End], etc., keys are
  14507.      used, the 'Norm' and 'Shift' fields will be REVERSED.  I.e. if [Num Lock]
  14508.      is ON, [Home] will be key code "7" and [Shift-Home] will be key code
  14509.      18176.
  14510.  
  14511.  
  14512.  
  14513.  
  14514.      Intellicomm v2.01               SCRIPT.DOC                            232
  14515.      
  14516.      
  14517.  
  14518.      The extended cursor control keys on AT-type keyboards (the cursor keys
  14519.      that are separated from the numeric keypad) return the same value for
  14520.      both 'Norm' and 'Shift', regardless of the state of [Num Lock].  I.e.
  14521.      whether [Num Lock] is on OR off, the extended [Home] key will always
  14522.      return 18176, and [Shift-Home] will also return 18176.  Extended or
  14523.      "enhanced" (101 key) keyboard hardware DOES make a distinction between
  14524.      the extended cursor control key codes, and the numeric keypad cursor
  14525.      control key codes.  Intellicomm's keystroke handler simulates the same
  14526.      key code for either though (either the extended [Home] key or the numeric
  14527.      keypad [Home] key for example), to simplify keyboard handling.
  14528.  
  14529.      Key    Norm     Shift    Ctrl      Alt 
  14530.      ---------------------------------------------------------------
  14531.      Home   18176      "7"    30464    38656
  14532.      End    20224      "1"    29952    40704
  14533.      PgUp   18688      "9"    33792    39168
  14534.      PgDn   20736      "3"    30208    41216
  14535.      Up     18432      "8"    36096    38912
  14536.      Down   20480      "2"    37120    40960
  14537.      Left   19200      "4"    29440    39680
  14538.      Right  19712      "6"    29696    40192
  14539.      Tab     "^I"     3840    37888    42240
  14540.      BckSpc  "^H"     "^H"      " "     3584
  14541.      Kpad 5 19456      "5"    36608      N/A
  14542.      Grey *  "*"       "*"    38400      N/A
  14543.      Grey -  "-"       "-"    36352    18944
  14544.      Grey +  "+"       "+"    36864    19968
  14545.  
  14546.  
  14547.  
  14548.  
  14549.      Intellicomm v2.01               SCRIPT.DOC                            233
  14550.      
  14551.      
  14552.  
  14553.                         G.  SCRIPT ERROR MESSAGES/SOLUTIONS
  14554.  
  14555.      Error : "OPERATOR is an invalid operator; =, <>, <, <=, >, >= only"
  14556.      Reason: An invalid operator was specified in an IF or WHILE command. 
  14557.              Valid operators are =, <>, <, <=, >, >=.  See IF in the Detailed
  14558.              Command Summary for details.
  14559.  
  14560.      Error : "Parameter missing in IF/WHILE"
  14561.      Reason: An operator was specified (<, <=, =, >= >) but no parameter
  14562.              followed to carry out the comparison.  Add an argument after your
  14563.              operator.  E.g. 'IF X = ' is illegal, 'IF X = 1' is fine.
  14564.  
  14565.      Error : "No ']' in BIF Variable"
  14566.      Reason: *[ (the BIF variable *[X]tag prefix) was specified but no closing
  14567.              ']' was found.  Ensure that you have a closing bracket in the
  14568.              variable and that there are no spaces ('*[ X ]tag' is illegal;
  14569.              use '*[X]tag').
  14570.  
  14571.      Error : "Bad section [X] in BIF Variable"
  14572.      Reason: The section (*[X]tag) specified in a BIF Variable was unknown. 
  14573.              See BIF Variable Appendix for details.
  14574.  
  14575.      Error : "Bad tag [sTAG] in BIF Variable"
  14576.      Reason: The sTAG (*[X]sTAG) specified in a BIF Variable was unknown.  See
  14577.              BIF Variable Appendix for details.
  14578.  
  14579.      Error : "Bad tag [sTAG] in INI Variable"
  14580.      Reason: A bad main setup tag followed the asterisk in a variable
  14581.              specification (*tag).  See the Main Setup Variables appendix for
  14582.              valid tags.
  14583.  
  14584.      Error : "No command with WHEN"
  14585.      Reason: A prompt string was specified with WHEN, but no command was
  14586.              specified (the command to execute when the prompt is found).  Add
  14587.              a command after the prompt.
  14588.  
  14589.      Error : "cCOMMAND command/label not found"
  14590.      Reason: cCOMMAND is not a recognized command or label.  Check the
  14591.              command/label carefully for typing errors.
  14592.  
  14593.      Error : "LABELNAME label not found."
  14594.      Reason: The label following GOTO or GOSUB was not found in the script. 
  14595.              Check the label carefully for typing errors.
  14596.  
  14597.      Error : "cCOMMAND requires a VARIABLE as the first parameter"
  14598.      Reason: The first paremter following cCOMMAND was not a variable.  Script
  14599.              commands that assign or change data require a variable as their
  14600.              first parameter.  Either define a variable using the VARIABLE
  14601.              command, and specify the variable's name as the first parameter
  14602.              following cCOMMAND, or use a GlobalStr[] or read/write System
  14603.              Variable as the first parameter.
  14604.  
  14605.      Error : "cCOMMAND called before MENUDEFINE"
  14606.      Reason: MENUBAR, MENUBOXH, or MENUBOXV was executed before MENUDEFINE was
  14607.  
  14608.  
  14609.  
  14610.  
  14611.      Intellicomm v2.01               SCRIPT.DOC                            234
  14612.      
  14613.      
  14614.  
  14615.              used.  See MENUDEFINE in the Detailed Command Summary for
  14616.              details.
  14617.  
  14618.      Error : Menu item [nITEM] is invalid [no such item]
  14619.      Reason: An invalid menu item number was specified in a MENUHLP command. 
  14620.              See MENUHLP in the Detailed Command Summary for details.
  14621.  
  14622.      Error : "Bad GOTO/GOSUB; No label/variable name"
  14623.      Reason: GOTO or GOSUB was used, but no label name followed.  Specify a
  14624.              label to jump to after the GOTO or GOSUB command.
  14625.  
  14626.      Error : "Bad GOTO/GOSUB; Bad 1st character in label/variable name"
  14627.      Reason: The first character in the label name following the GOTO or GOSUB
  14628.              command is invalid.  The first character in a label name must be
  14629.              in the range a-z, A-Z or an underscore (_).  Numbers are not
  14630.              valid first characters in label names.
  14631.  
  14632.      Error : "Bad GOTO/GOSUB; Bad character [X] in label/variable name"
  14633.      Reason: An invalid character was used in a label name.  You may only use
  14634.              alphanumeric characters (a-z, A-Z, 0-9) and underscores (_) in
  14635.              script labels.
  14636.  
  14637.      Error : "Can't define vVARIABLE; No label/variable name"
  14638.      Reason: No variable label name was specified after the VARIABLE command. 
  14639.              You must specify a legal variable name after the VARIABLE command
  14640.              (see 'Bad 1st character' and 'Bad character' just below for
  14641.              information on valid variable names).
  14642.  
  14643.      Error : "Can't define vVARIABLE; Bad 1st character in label/variable
  14644.              name"
  14645.      Reason: The first character in the variable name following the VARIABLE
  14646.              command is invalid.  The first character in a variable name must
  14647.              be in the range a-z, A-Z or an underscore (_).  Numbers are not
  14648.              valid first characters in variable names.
  14649.  
  14650.      Error : "Can't define vVARIABLE; Bad character [c] in label/variable
  14651.              name"
  14652.      Reason: An invalid character was used in a variable name.  You may only
  14653.              use alphanumeric characters (a-z, A-Z, 0-9) and underscores (_)
  14654.              in script variable names.
  14655.  
  14656.      Error : "Can't define vVARIABLE; Max variables reached"
  14657.      Reason: The variable table is full.  No more than 35530 variables may be
  14658.              defined in any one script.  See the SCRIPT MEMORY LIMITS appendix
  14659.              below for possible solutions.  If you split your script up into
  14660.              two or more scripts, you can define more than 35530 variables
  14661.              total.
  14662.  
  14663.      Error : "Can't define vVARIABLE; No memory"
  14664.      Reason: The computer is out of memory and there was none left to allocate
  14665.              the variable.  Reduce the number of variables in your script by
  14666.              using global 'working' variables which you use throughout the
  14667.              script.  For example, if you need to count from 1 to 10 in ten
  14668.              different places in your script, use the same variable to do the
  14669.  
  14670.  
  14671.  
  14672.  
  14673.      Intellicomm v2.01               SCRIPT.DOC                            235
  14674.      
  14675.      
  14676.  
  14677.              counting instead of defining separate variables each time.
  14678.  
  14679.      Error : "Can't define vVARIABLE; Variable exists"
  14680.      Reason: The variable name following the VARIABLE command has already been
  14681.              defined elsewhere in the script.  Use a different variable name.
  14682.  
  14683.      Error : "Can't define vVARIABLE; Name duplicates a script COMMAND"
  14684.      Reason: To allow for future script enhancements, variable names cannot
  14685.              duplicate script commands.  For example, 'VARIABLE variable' is
  14686.              illegal since the variable name ('variable') duplicates the
  14687.              VARIABLE command.  Use another variable name.
  14688.  
  14689.      Error : "Can't assign data to vVARIABLE; no memory"
  14690.      Reason: The computer is out of memory and there was none left to allocate
  14691.              data to a defined variable.  Memory for variables is allocated
  14692.              based on the length of the data assigned to a variable, and the
  14693.              total number of variables.  Reduce the number of variables in
  14694.              your script by using global 'working' variables which you use
  14695.              throughout the script.  For example, if you need to count from 1
  14696.              to 10 in ten different places in your script, use the same
  14697.              variable to do the counting instead of defining separate
  14698.              variables each time.
  14699.  
  14700.      Error : "Undefined variable; vVARIABLE"
  14701.      Reason: A variable name was specified, but it does not exist.  Check the
  14702.              variable name carefully to ensure that you have defined it with
  14703.              the VARIABLE command (or see the BIF Variables / Main Setup
  14704.              Variables appendices if applicable).
  14705.  
  14706.      Error : "vVARIABLE variable is read only"
  14707.      Reason: You attempted to assign data to a read only $SYSTEM variable. 
  14708.  
  14709.      Error : "GlobalStr missing ]"
  14710.      Reason: 'GlobalStr[' was specified but no closing ']' was found.  Ensure
  14711.              that you have a closing bracket in the variable and that there
  14712.              are no spaces ('GlobalStr[ X ]' is illegal; use 'GlobalStr[X]').
  14713.  
  14714.      Error : "GlobalStr[nOFFSET] is out of bounds [0-9 only]"
  14715.      Reason: The offset specified between the GlobalStr brackets is invalid. 
  14716.              Valid offsets are numbers from 0-9 only.
  14717.  
  14718.      Error : "Invalid variable in GlobalStr; vVARIABLE"
  14719.      Reason: A variable name was specified as the GlobalStr offset (e.g.
  14720.              GlobalStr[variable_name]) but variable_name is invalid.  Only
  14721.              user-defined variables are valid as GlobalStr offsets.  Define
  14722.              the variable with the VARIABLE command before using it in
  14723.              GlobalStr.
  14724.  
  14725.      Error : "Not enough memory ... Can't perform function."
  14726.      Reason: All of the computer's memory has been used up.  This is a general
  14727.              purpose error message that can occur with many script commands,
  14728.              and the only solution is to reduce the size of your script (see
  14729.              the SCRIPT MEMORY LIMITS appendix below), or to increase the
  14730.              amount of memory on your computer (use MEMMAKER, QEMM, etc). 
  14731.  
  14732.  
  14733.  
  14734.  
  14735.      Intellicomm v2.01               SCRIPT.DOC                            236
  14736.      
  14737.      
  14738.  
  14739.              Note that memory above 640K is not useable by DOS programs or
  14740.              scripts, so the only way to make 'more' memory available is to
  14741.              move device drivers and TSR's out of conventional memory, and
  14742.              into upper memory.
  14743.  
  14744.      Error : "Division by zero"
  14745.      Reason: One of the parameters in the DIV(ide) command is zero.  Division
  14746.              by zero is invalid and you must change the offending parameter to
  14747.              a non-zero value.
  14748.  
  14749.      Error : "GOSUB stack overflow [16 GOSUB maximum]"
  14750.      Reason: GOSUB was executed more than 16 times before a RETURN was found. 
  14751.              When GOSUB's are executed, the script address (line number) to
  14752.              jump to when a RETURN is found is stored in an internal script
  14753.              'stack'.  This stack is only capable of holding 16 RETURN
  14754.              addresses.  You must simplify your script logic to solve the
  14755.              problem.
  14756.  
  14757.      Error : "FOPEN stack overflow [16 FOPEN maximum]"
  14758.      Reason: You attempted to FOPEN more than 16 files at a time.  Call FCLOSE
  14759.              to close one or more files before the offending FOPEN.
  14760.  
  14761.      Error : "FOPEN mode "%s" is invalid [r, w, a, r+, w+, a+ only]"
  14762.      Reason: The mode specified in the FOPEN command (3rd parameter) was
  14763.              invalid.  See FOPEN in the Detailed Command Summary for details.
  14764.  
  14765.      Error : "nHANDLE is an invalid file number"
  14766.      Reason: The file handle specified in a file-related command (FGETS,
  14767.              FPUTS, FCLOSE, etc) is invalid.  You must obtain a valid file
  14768.              handle with the FOPEN command before using file-related commands. 
  14769.              A given file handle is also invalid after FCLOSE is used on the
  14770.              file.
  14771.  
  14772.      Error : "cCOMMAND stack overflow."
  14773.      Reason: VPUSH was used more than 16 times before VPOP, WNDOPEN was used
  14774.              more than 16 times before WNDCLOSE, or WAITFOR was nested (likely
  14775.              via a 'WHEN "text" gosub subroutine' command where WAITFORs are
  14776.              used in the subroutine) more than 16 times.
  14777.  
  14778.      Error : "BREAK|CONTINUE|ENDWHILE without WHILE"
  14779.      Reason: BREAK CONTINUE or ENDWHILE was found, but no WHILE was specified.
  14780.  
  14781.      Error : "ELSE|ENDIF without IF"
  14782.      Reason: ELSE or ENDIF was found, but no IF was specified.
  14783.  
  14784.      Error : "DEFAULT|ENDCASE|ENDSWITCH without SWITCH"
  14785.      Reason: DEFAULT ENDCASE or ENDSWITCH was found, but no SWITCH was
  14786.              specified.
  14787.  
  14788.      Error : "Must COPEN a catalog before cCOMMAND"
  14789.      Reason: Attempted a catalog-related command (CGETREC, etc) but no catalog
  14790.              was open.  Use COPEN before the command.
  14791.  
  14792.      Error : "Catalog must be sorted [CSETSORT] before export"
  14793.  
  14794.  
  14795.  
  14796.  
  14797.      Intellicomm v2.01               SCRIPT.DOC                            237
  14798.      
  14799.      
  14800.  
  14801.      Reason: Attempted a CEXPORT on an unsorted catalog.  Use CSETSORT before
  14802.              the CEXPORT command.
  14803.  
  14804.      Error : "Invalid sort order"
  14805.      Reason: Tried to CSAVESORT with no sort order defined.  Use CSETSORT
  14806.              before calling CSAVESORT.
  14807.  
  14808.  
  14809.  
  14810.  
  14811.      Intellicomm v2.01               SCRIPT.DOC                            238
  14812.      
  14813.      
  14814.  
  14815.                               H.  SCRIPT MEMORY LIMITS
  14816.  
  14817.      To execute a script, Intellicomm first checks the filesize of the script
  14818.      file (as reported by the filesize you'd see in a DOS 'DIR' listing, and
  14819.      in the Script Manager to the right of the script filename).  If less than
  14820.      65530 bytes, Icom then attempts to allocate a memory buffer (the same
  14821.      size as the script filesize) to put the script into.  If enough memory is
  14822.      available, the script is read into the newly allocated memory buffer all
  14823.      in one shot with no stripping of comments, trailing spaces, or blank
  14824.      lines.  This is done mainly for speed, since many Icom scripts are used
  14825.      to enter a few characters quickly, or to enter a command from a BIF, or
  14826.      as a simple script for small custom jobs/logons, etc.  In these cases
  14827.      speed counts, and wasting memory isn't an issue since the scripts are
  14828.      small.
  14829.  
  14830.      H.1  Developing Large Scripts
  14831.  
  14832.      If you are developing a large script that won't load into memory due to
  14833.      the 64K (65530 byte) limit, a fairly easy solution is to split your
  14834.      script up into smaller scripts and use the SCRIPT command to call the
  14835.      smaller scripts if/when they're needed.  *Each* script is allowed 65530
  14836.      bytes of memory (up to the limit of available DOS memory -- usually
  14837.      640K).  By using multiple scripts you can use all the DOS memory
  14838.      available on the computer.  Here's an example of how it works:
  14839.  
  14840.      ;MAIN.SCR this is the main 'module' of your script program
  14841.      ; (you don't have to call it MAIN.SCR... it can be any name)
  14842.  
  14843.      ;here we call a series of other scripts to do what needs doing
  14844.      SCRIPT "LOGON.SCR"    ;LOGON.SCR might dial and logon the BBS
  14845.      OFFLINE GOTO done     ;if not connected, quit
  14846.  
  14847.      SCRIPT "DOWORK1.SCR"  ;perform some task with another script
  14848.      OFFLINE GOTO done     ;if not connected, quit
  14849.  
  14850.      SCRIPT "DOWORK2.SCR"  ;perform another task with another script
  14851.      OFFLINE GOTO done     ;if not connected, quit
  14852.       ...                  ;etc.
  14853.      done:
  14854.       return
  14855.  
  14856.      This is actually how many .EXE programs work as well, since there's
  14857.      usually no need to have ALL of the code in memory at the same time. 
  14858.      Whatever code is needed for the current task is loaded, and when that
  14859.      task finishes the code is unloaded, and the memory is freed up for use by
  14860.      the next task (which is exactly what happens when a script ends ... the
  14861.      memory it was using is freed up).  You need only a small control 'module'
  14862.      (the MAIN.SCR above) to swap other scripts in and out of memory as
  14863.      needed.  This technique also makes your code easier to follow and
  14864.      maintain, since it's easier to find things in smaller scripts.
  14865.  
  14866.      If you'd like to use this technique you should first refer to the
  14867.      SCRTUTOR.DOC sections: "Global Variables" and "Passing Parameters to
  14868.      Scripts" if you haven't already.  The Global Variables can be very useful
  14869.  
  14870.  
  14871.  
  14872.  
  14873.      Intellicomm v2.01               SCRIPT.DOC                            239
  14874.      
  14875.      
  14876.  
  14877.      for inter-script communication (telling the called script what to do). 
  14878.      As well you might consider using the $ERRORLEVEL System Variable to
  14879.      return various errorcodes to your main module.  You're free to ASSIGN an
  14880.      errorcode that would be meaningful to the main module prior to exiting
  14881.      the called script.  For example, $ERRORLEVEL 1 might mean the carrier was
  14882.      lost.  $ERRORLEVEL 2 might mean that a BBS event was scheduled, etc. 
  14883.      Just use ASSIGN $ERRORLEVEL x (where x is your return code) in the called
  14884.      script, then use IF $ERRORLEVEL = x (where x is the errorcode) or SWITCH
  14885.      $ERRORLEVEL to TEST for any abort codes when the called scripts return.
  14886.  
  14887.      You should also be aware of the difference between the EXIT and RETURN
  14888.      command as it applies to called scripts.  The EXIT command aborts ALL
  14889.      scripts (exits the script interpreter entirely), while RETURN simply ends
  14890.      the current script, returning control to the caller.  So, in the example
  14891.      above, if something went desperately wrong in the logon you could use an
  14892.      EXIT command in LOGON.SCR to cancel both LOGON.SCR *and* MAIN.SCR, and
  14893.      return to manual mode.  Alternatively the RETURN command simply exits the
  14894.      current script and returns control to the caller at the next line below
  14895.      the SCRIPT command.
  14896.  
  14897.      You can also specify 'errorcodes' after the EXIT and RETURN commands to
  14898.      tell Intellicomm what to do with the current automated job (if the
  14899.      original script was called from an automated job via a Custom Command or
  14900.      BIF).  EXIT or RETURN followed by a positive number (1, 2, etc) tells
  14901.      Icom to hangup and remove the current BIF from the job queue (useful if
  14902.      you encounter a BBS 'event' and you have no time online, etc).  EXIT or
  14903.      RETURN followed by a negative number (-1, -2, etc) causes Icom to abort
  14904.      ALL jobs, just as if the user had selected "Abort Job/Script" from the
  14905.      [Alt-Q] menu.  There are several considerations for using errorcodes with
  14906.      EXIT and RETURN, and more details can be found in section ?.
  14907.  
  14908.  
  14909.                     I.  CREATING SCRIPTS FOR PUBLIC DISTRIBUTION
  14910.  
  14911.      This section is for script "gurus" or prospective gurus who have a script
  14912.      project in-mind that they plan to distribute to the general public. 
  14913.      These are ONLY pointers... They are not 'rules', and you can feel free to
  14914.      ignore every one of them if you like.
  14915.  
  14916.      First off, some no-no's for public distribution:
  14917.  
  14918.       o Don't make the installation and setup unnecessarily complicated.  It
  14919.         not only turns people off right at that crucial "first impression"
  14920.         moment, but can cause you grief if you offer technical support.
  14921.  
  14922.       o Don't use your own custom colors in your script, no matter how nice it
  14923.         looks on your screen.  Monochrome and laptop displays cannot display
  14924.         all colors properly and if you hardcode in custom colors, your script
  14925.         may be useless to many people.  Use the various $xxxx_COLOR System
  14926.         Variables to specify colors to display with the colors the user has
  14927.         set up in the Icom main setup.  Better yet, use WNDOPEN, MSGOPEN,
  14928.         PRINT, etc., to display text on the screen, which automatically use
  14929.         the default Icom colors.
  14930.  
  14931.  
  14932.  
  14933.  
  14934.      Intellicomm v2.01               SCRIPT.DOC                            240
  14935.      
  14936.      
  14937.  
  14938.       o If you use an 'extended' (43 or 50) line video mode in the Icom main
  14939.         setup, make sure you set the display for standard 25 line mode and re-
  14940.         test your script before distribution.  You may have defined menus or
  14941.         other screens that will not fit on other people's video displays if
  14942.         you used an extended line mode when developing your script.
  14943.  
  14944.       o Try to make as many things as possible configurable (see the
  14945.         INTRODUCTION TO FILE INPUT / OUTPUT for information on storing data
  14946.         on-disk), and avoid hardcoding specific drives and directories.  Use
  14947.         the System Variables, BIF Variables, and Main Setup Variables to get
  14948.         the Icom data the USER has already set up where possible.
  14949.       
  14950.      Now some 'do's:
  14951.  
  14952.       o Create an @ICOM.SCR installation script and include it in your
  14953.         archive.  Icom's POSTFILE.SCR, which automatically decompresses and
  14954.         virus checks new downloads, also checks for a script called @ICOM.SCR. 
  14955.         If it's found (i.e. if you include it in your distribution archive),
  14956.         the user is given the option to execute it.  Thus, you can LIST
  14957.         "README.TXT", COPY or RENAME (move) your files to install them
  14958.         AUTOMATICALLY, get information from the user, etc., using @ICOM.SCR. 
  14959.         Basically anything that needs doing for installation and setup up of
  14960.         your product can be done automatically via @ICOM.SCR.
  14961.  
  14962.       o Test your script thoroughly before releasing it, attempting to look at
  14963.         it from a new user's perspective.
  14964.  
  14965.       o Document features that aren't obvious.  Implement online help were
  14966.         possible (the LIST command will allow you to display your
  14967.         documentation while your script is running, which is as good as online
  14968.         help).
  14969.  
  14970.       o You're free to support your scripts (and take complements on your
  14971.         work) in any of the online forums we use for Intellicomm.  Make
  14972.         yourself available for feedback, if possible.
  14973.  
  14974.       o If your script is has its own interface, or is otherwise "stand-
  14975.         alone", the best way to run it is via the DOS command line with the
  14976.         /scr: switch.  If you include a .BAT file with your script, you can
  14977.         have users start it right from DOS (or Windows/DESQview or a menu
  14978.         system) just as they would a regular program:
  14979.  
  14980.          Echo off
  14981.          rem MYSCRIPT.BAT starts MYSCRIPT.SCR from DOS
  14982.          ICOM.EXE /scr:myscript
  14983.  
  14984.       o Pass along your feedback as to where you'd like to see improvements or
  14985.         changes in the script language.  Implementing new script commands
  14986.         (particularly if you're a C programmer and you know that it's a
  14987.         standard library function) is usually very simple.  New script
  14988.         concepts and rules are more complicated to code (and particularly to
  14989.         implement, without rendering all scripts to date useless), but all
  14990.         suggestions will be considered.
  14991.  
  14992.  
  14993.  
  14994.  
  14995.      Intellicomm v2.01               SCRIPT.DOC                            241
  14996.      
  14997.      
  14998.  
  14999.                      J.  CHANGES FROM THE V1.00 SCRIPT LANGUAGE
  15000.  
  15001.      Listing all the changes from the Icom v1.00 script language would be
  15002.      pointless, since it would duplicate most of this manual to explain them
  15003.      all.  By reading the introductory material in SCRTUTOR.DOC, and looking
  15004.      at the SCRIPT COMMANDS AT A GLANCE section, you'll be able to pick up all
  15005.      the changes and new commands quickly.  This section covers only the
  15006.      changes that are relevant to existing v1.00 scripts.  All v1 script
  15007.      commands, other than those listed below, work the same with Icom v2 as
  15008.      they did with v1.
  15009.  
  15010.      J.1  Version 2 Syntax Changes
  15011.  
  15012.      Single quotes are no longer permitted around string constants.  With the
  15013.      v1 script language this was legal:
  15014.  
  15015.       PRINT 'This string has "double" quotes in it.'
  15016.  
  15017.      The problem with this is that you cannot use both single AND double
  15018.      quotes in a string.  With the addition of File I/O, where data is read
  15019.      from a text file (data which could contain both single and double quotes
  15020.      on a single line) this this is no longer practical.  Thus, you must use
  15021.      DOUBLE quotes around string constants, and if a double quote appears in
  15022.      the text, use a caret to escape it:
  15023.  
  15024.       PRINT "This string has ^"double^" quotes in it."
  15025.  
  15026.      J.2  Version 2 Command Changes
  15027.  
  15028.      EXIST, NOTEXIST, OFFLINE, ONLINE, and WHEN
  15029.      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15030.      These commands no longer force you to GOTO a script label.  You can now
  15031.      use any script command after any of these commands.  Examples:
  15032.  
  15033.       EXIST "somefile.ext" DELETE "somefile.ext"
  15034.       NOTEXIST "somefile.ext" GOTO done
  15035.       OFFLINE EXIT 
  15036.       ONLINE MSGWIND "You are online"
  15037.       WHEN "find this" SEND "command"
  15038.       WHEN "find that" GOSUB handle_find_that
  15039.       WHEN "Begin your Download" DOWNLOAD "Z" ""
  15040.  
  15041.      The addition of the GOSUB command, combined with the ability to use GOSUB
  15042.      in WHENs should be quite helpful in writing your scripts.  If you use a
  15043.      GOSUB in a WHEN, the script executes the subroutine (until a RETURN is
  15044.      encountered) then returns to the WAITFOR.  Thus you can handle much more
  15045.      complex tasks with WHEN/WAITFOR than you could with the v1 script
  15046.      language.
  15047.  
  15048.      Further, EXIST and NOTEXIST now search for read-only files as well as
  15049.      normal files (but not hidden files, subdirectories, DOS system files, or
  15050.      the volume ID).  Previously, EXIST and NOTEXIST found only files that
  15051.      were normal (not read-only).  You can now also access all the file
  15052.      attributes of files found with EXIST (if the file exists) including file
  15053.  
  15054.  
  15055.  
  15056.  
  15057.      Intellicomm v2.01               SCRIPT.DOC                            242
  15058.      
  15059.      
  15060.  
  15061.      size, file modification date and time, and file attributes via the System
  15062.      Variables $FSIZE, $FDAY, $FMONTH, $FYEAR, $FHOUR, $FMIN, $FSEC, and
  15063.      $FRDONLY.  You may also wish to replace some of your EXIST commands with
  15064.      the FINDFIRST command, which allows you to search for files with ANY
  15065.      attribute (including hidden files, subdirectories, DOS system files, and
  15066.      the disk volume ID).  Using FINDNEXT after a call to FINDFIRST allows you
  15067.      to obtain all filenames in a given wildcard (*.DBF, \ICOM\BIF\*.BIF,
  15068.      I???.*, etc), as well as the attributes of each file.
  15069.  
  15070.      EXIT
  15071.      ~~~~
  15072.      The EXIT command now exits the script processor entirely.  Previously if
  15073.      you used the SCRIPT command to call another script, and the called script
  15074.      performed an EXIT, it would simply return to the original script.  EXIT
  15075.      is now used to abort ALL scripts and return control to whatever called
  15076.      the original script (the automated job, or Script Manager, etc).  To exit
  15077.      only from the CURRENT script (i.e. to allow the calling script to
  15078.      continue running), use the RETURN command.  RETURN does take an optional
  15079.      exit code as EXIT does.  Please see section ? in SCRTUTOR.DOC and the
  15080.      Detailed Command Summaries of EXIT and RETURN above, for more details on
  15081.      usage.
  15082.  
  15083.      GOTOXY
  15084.      ~~~~~~
  15085.      A bug in the GOTOXY command was fixed for v2.0.  GOTOXY 1 1 went to
  15086.      screen position 2, 2 with Icom v1.00.  The v1 script conversion utility
  15087.      automatically decrements the screen coordinates in GOTOXY commands found
  15088.      in v1 scripts, to account for this bug fix.
  15089.  
  15090.      SCAPTURE
  15091.      ~~~~~~~~
  15092.      This command now takes a parameter that allows you to specify a
  15093.      D:\PATH\FILENAME.EXT to capture to, instead of forcing the screen capture
  15094.      to the default Icom screen capture file.  If no filename follows
  15095.      SCAPTURE, the usual screen capture file (\ICOM\CAP\SCREEN.CAP by default;
  15096.      defined on the main setup/Filenames and Paths screen) is used, as with
  15097.      the v1 script language.
  15098.  
  15099.      SEND/SENDNC
  15100.      ~~~~~~~~~~~
  15101.      The SEND and SENDNC commands now observe any "Response Delay" you have
  15102.      set in the BIF (screen 1):
  15103.  
  15104.      | Receive Mail . .                       Response Delay . 10
  15105.                                               ~~~~~~~~~~~~~~~~~~~
  15106.      Since SEND is normally used in combination with a WHEN command to respond
  15107.      to a BBS prompt, and is also used by Script Learn mode after WAITFORs to
  15108.      send responses in learned scripts, a configurable response delay in the
  15109.      BIF can be very useful with certain BBS software.  Some BBS software
  15110.      clears the COM input buffer after displaying prompts, and if your script
  15111.      had sent the response BEFORE the buffer was cleared (i.e. if the script
  15112.      answers BEFORE the prompt is fully displayed), it would be lost. If your
  15113.      SEND or SENDNC commands are not being processed by the BBS, adding a
  15114.      Response Delay to the BIF should remedy the situation.
  15115.  
  15116.  
  15117.  
  15118.  
  15119.      Intellicomm v2.01               SCRIPT.DOC                            243
  15120.      
  15121.      
  15122.  
  15123.      The equivalent commands to the v1.00 SEND and SENDNC (no delay) are
  15124.      SENDNP (NP for No Pause) and SENDNCP (NCP for No CR or Pause).
  15125.  
  15126.      SYSTEM
  15127.      ~~~~~~
  15128.      The SYSTEM command now takes two parameters.  Parameter 1 (a number from
  15129.      0-2) tells Intellicomm what to do if connected: SYSTEM 1 hangs up, SYSTEM
  15130.      2 stays connected, SYSTEM 0 (or no parameter) asks the user whether to
  15131.      disconnect, if connected.  The second optional parameter allows you to
  15132.      specify an ERRORLEVEL when exiting, which can be tested from a .BAT file
  15133.      or similar.  If you use SYSTEM 0 1, then errorlevel 1 is returned to DOS
  15134.      and could be tested:
  15135.  
  15136.      rem  A .BAT to run your script from the command line
  15137.      ICOM.EXE /scr:myscript
  15138.      if errorlevel 2 <do this>
  15139.      if errorlevel 1 <do this>
  15140.  
  15141.      ...where <do this> was a valid batch command (GOTO, DELETE, etc).
  15142.  
  15143.      WHEN
  15144.      ~~~~
  15145.      Aside from the previously mentioned change to WHEN, you can now also
  15146.      track up to nineteen BBS prompts using WHENs instead of seventeen, the
  15147.      v1.00 limit.
  15148.  
  15149.      J.3  Icom v1.00 Script Conversion
  15150.  
  15151.      Version 1 scripts are optionally converted when you install Intellicomm. 
  15152.      Aside from making sure that there are DOUBLE QUOTES around all strings
  15153.      (necessary now that variables have been introduced), all the conversion
  15154.      does is to place GOTOs in the ONLINE, OFFLINE, etc., commands listed
  15155.      above, which no longer force a GOTO.  The more subtle changes with EXIT
  15156.      and CAPTURE are not checked, as they would be difficult to convert
  15157.      automatically.  You should give your converted scripts a once-over just
  15158.      to make sure they're doing what you want.
  15159.  
  15160.      If you converted your scripts during Icom v2 installation and want your
  15161.      original v1 scripts back for some reason, you'll find them renamed to
  15162.      *.OLD in the \ICOM\SCR directory.
  15163.