DynaComm Connectivity Series® Script Language Reference
DCS © 2012 by FutureSoft, Inc. All rights reserved.
DynaComm Connectivity Series™ Script Language Reference
This manual, and the software described in it, is furnished under a license agreement. Information in this document is subject to change without notice and does not represent a commitment on the part of FutureSoft. The software may be used or copied only in accordance with the terms of the agreement.
No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose other than the purchaser’s personal use without the written permission of FutureSoft, Inc.
DynaComm, DynaComm Connectivity Series, DynaComm Client Option, and FutureSoft are registered trademarks of FutureSoft, Inc. All other trademarks are the property of their respective owners.
1986-2012 FutureSoft, Inc.
E-Edition 14-2012 Document #E-DCSR9200 013009
Written and designed at: FutureSoft, Inc.
(800) 989-8908 [email protected] http://www.futuresoft.com Contents
1 Introduction to the Script Language
...... 15 DCS Script Language Overview...... 16 Creating, Compiling, and Executing a Script ...... 17 Commands, Functions and Arguments...... 20 Command Blocks...... 22 Line Continuation...... 23 Comments...... 24 Labels...... 25 Strings...... 27 Numerics...... 37 Booleans...... 40 Special Argument Types...... 43 Variable Creation...... 47 Symbols...... 49 Operators...... 54 Scoping Rules ...... 59 Parameter Passing & Subroutines ...... 61 Tables, Records and Data Manipulation...... 64 Menus...... 71 DCS Windows & Window Handles...... 74 Event Handling - WAIT and WHEN Commands...... 76 Dynamic Data Exchange - DDE...... 78 Task Errors...... 82 Converting Scripts from Previous Versions of DCS...... 84
2 Functions
...... 87 Functions in Alphabetical Order...... 88 Table of Contents Functions by Category...... 92 ACTIVE...... 96 ATTRIBUTES...... 97 BAND...... 98 BNOT...... 99 BOOL...... 100
iii
Contents, continued
2 Functions Functions, continued
BOR...... 101 BUFFER...... 102 BUFFER, continued...... 103 BXOR...... 104 CHR...... 105 CONNECT...... 107 CONNECTMESSAGE...... 108 CONNECTRESULT...... 109 CURSOR...... 110 DATE...... 111 (DDE) ADVISE...... 112 DECRYPT...... 113 DEFAULTSESSIONHANDLE...... 115 (DIALOG) CHECKBOX...... 116 (DIALOG) EDITTEXT...... 117 (DIALOG) LISTBOX...... 118 (DIALOG) MESSAGEBOX...... 119 (DIALOG) RADIOGROUP...... 121 DIALOGHANDLE...... 122 DIRECTORY...... 123 DISKSPACE...... 125 ENCRYPT...... 126 EOF...... 127 ERROR...... 128 EXFLDATTR...... 129 EXISTS...... 134 FILESIZE...... 135 FILTER...... 136 FLDATTR...... 138 FLDATTREXPOS...... 140 FLDLEN...... 141 FLDNUM...... 142 FLDPOS...... 143 FLDTEXT...... 144 GETAPPCONFIG...... 145 DCS Script Language Reference GETCONNCONFIG...... 146 GETDISPLAYCONFIG...... 147 iv Table of Contents v 170 172 173 174 175 176 178 180 182 183 184 192 193 194 195 197 198 148 149 150 151 153 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 ...... continued ...... TASKLIST ROUTE SCREEN SEARCH SEARCHINRECT SECONDS SETTINGS STR SUBSTR SYSMETRICS SYSTEM TASKFILE PHONENUMBER POS POSITION POWER PRTMETRICS PUTPROFILEDATA RANDOM REAL RESULT ROUND ICONIC INT LENGTH (MENU) CHECKED (MENU) ENABLED NETID NEXT NUM ORD PASSWORD Functions, Functions, GETEMULCONFIG GETGENERALCONFIG GETPROFILEDATA GETXFERCONFIG HWNDLIST 2 Functions continued Contents, Contents,
Contents, continued
2 Functions Functions, continued
TASKNAME...... 199 TIME...... 200 TIMER...... 201 TRIM...... 202 TYPEDLIBRARYCALL...... 203 UPPER...... 205 USERID...... 206 VERSION...... 207 VISIBLE...... 208 WINDOW...... 209 WINDOWHND...... 210 WINDOWNAME...... 211 WNDCLASS...... 212 WNDFILE...... 213 WNDTITLE...... 214 ZOOMED...... 215
3 Commands
...... 216 Commands in Alphabetical Order...... 217 Commands by Category...... 227 APPCONFIG...... 240 ARGUMENTS...... 242 BEEP...... 243 BEGIN...... 244 BREAK...... 245 CANCEL...... 246 CLEAR...... 247 COLLECT...... 248 COLLECT, continued...... 249 COMPILE...... 251
DCS Script Language Reference CONCAT...... 252 CONNCONFIG...... 253 CONNECT...... 256 vi Table of Contents vii 286 291 293 294 296 300 301 303 304 305 307 309 310 311 312 313 315 258 259 260 262 263 264 265 266 268 269 270 271 273 275 276 278 280 281 283 284 ...... continued ...... DIALOG UPDATE DIALOG (DIALOG) EDITTEXT(DIALOG) GROUPBOX (DIALOG) ICON (DIALOG) ICONBUTTON (DIALOG) LISTBOX (DIALOG) MESSAGE (DIALOG) NEWLINE (DIALOG) PICTURE (DIALOG) RADIOBUTTON (DIALOG) RADIOGROUP (DIALOG) (DDE) WHEN REQUEST (DDE) WHEN TERMINATE DEBUG DECREMENT DIAL DIALOG BUTTON (DIALOG) CANCEL DIALOG CHECKBOX (DIALOG) CONTROL DIALOG DIMENSION (DIALOG) (DDE) POKE (DDE) REQUEST REPLY (DDE) TABLE REQUEST (DDE) TABLE SEND (DDE) TABLE SIGNAL (DDE) WAIT (DDE) WHEN ADVISE (DDE) WHEN EXECUTE (DDE) WHEN INITIATE (DDE) WHEN POKE Commands, CONTINUE DIRECTORY CREATE (DDE) ACCESS CANCEL (DDE) ACCESS (DDE) INSTRUCT 3 Commands continued Contents, Contents,
Contents, continued
3 Commands Commands, continued
DISCONNECT...... 318 DISPLAY...... 319 DISPLAYCONFIG...... 321 DROPDTR...... 323 EDIT COPY...... 324 EDIT COPYSPECIAL...... 325 EDIT CUT...... 328 EDIT FIND...... 329 EDIT GOTO...... 330 EDIT PASTE...... 331 EDIT REPLACE...... 332 EMULCONFIG...... 334 END...... 343 EXECUTE...... 344 FILE CLOSE...... 345 FILE COMPRESS...... 346 FILE COPY...... 347 FILE CREATENAME...... 348 FILE DECOMPRESS...... 351 FILE DECRYPT...... 352 FILE DELETE...... 353 FILE ENCRYPT...... 354 FILE OPENNAME...... 355 FILE PAUSE...... 357 FILE RECEIVE BINARY...... 358 FILE RENAME...... 361 FILE RESUME...... 362 FILE SEND BINARY...... 363 FKEYS...... 366 GENERALCONFIG...... 367 GOTO...... 369 HANGUP...... 370 IF...... 371 INCREMENT...... 372 KERMIT COPY...... 373 DCS Script Language Reference KERMIT DIRECTORY...... 374 KERMIT ERASE...... 375 viii Table of Contents ix 402 403 404 405 406 407 408 409 411 412 414 416 417 419 420 422 423 376 377 378 379 380 381 382 383 384 385 389 390 391 392 393 395 396 397 400 401 ...... continued ...... PRINT CANCEL MENU DELETE POPUP MENU INSERT ITEM MENU INSERT POPUP (MENU) ITEM (MENU) POPUP (MENU) SEPARATOR MENU UPDATE NOSHOW PARSE PERFORM LEAVE LEVEL CALL LIBRARY LOAD LIBRARY UNLOAD LIBRARY LINENUMBERS LOAD LOGTOFILE MENU MENU CANCEL MENU DELETE ITEM KERMIT NEWDIRECTORY KERMIT RENAME KERMIT TYPE KERMIT WHO KEY KEYBOARD LOAD KEYMAP RESET KEYMAP SAVE KEYMAP LAUNCH Commands, KERMIT FINISH KERMIT FREESPACE KERMIT HELP KERMIT LOGOUT KERMIT MESSAGE 3 Commands continued Contents, Contents,
Contents, continued
3 Commands Commands, continued
PRINT CLOSE...... 424 PRINT FILE...... 425 PRINT FONT...... 426 PRINT NEWLINE...... 427 PRINT NEWPAGE...... 428 PRINT OPEN...... 429 PRINT STRING...... 430 PRINT STYLE...... 431 PRINT TABS...... 432 PRINT TERMINAL...... 433 QUIT...... 434 RECORD FORMAT...... 435 RECORD READ...... 436 RECORD SCAN...... 438 RECORD WRITE...... 439 REMOVE DIRECTORY...... 441 RESETSERIAL...... 442 RESTART...... 443 RESUME...... 444 RETURN...... 445 SAVE...... 446 SCREEN...... 447 SCROLL DOWN...... 448 SCROLL LEFT...... 449 SCROLL RIGHT...... 450 SCROLL UP...... 451 SELECTION...... 452 SELECTION APPEND...... 453 SELECTION BUFFER...... 454 SELECTION PRINT...... 455 SELECTION SAVE...... 456 SELECTION SEND...... 457 SEND...... 458 SENDBREAK...... 463 SET...... 464 DCS Script Language Reference SET APPTITLE...... 465 SET ATTRIBUTES...... 466 x Table of Contents xi 490 491 492 494 495 496 497 498 499 500 501 502 503 504 505 506 507 467 468 469 470 471 472 474 475 476 477 478 480 481 482 483 484 485 486 487 488 ...... continued ...... SET STOPBITS SET OUTGOINGCR SET PARITY SET PASSTHROUGH SET PASSWORD SET PHONENUMBER SET RESULT SET RETRY SET RETRYDELAY SET SENDDELAY SET SIGNAL SET SOUND SET DDETIMEOUT SET DECIMAL SET DEFAULTSESSIONHANDLE SET DIRECTORY SET EMULATION SET FKEYSSHOW SET FLOWCONTROL SET KEEPPRINTCHANNELOPEN SET LOCALECHO SET NETID SET BINARYTRANSFERPARAMS SET BINARYTRANSFERS SET BUFFERLINES SET CARRIERDETECT SET COLUMNS SET CONNECTION SET CONNECTMESSAGE SET CONNECTRESULT SET CURSOR SET DATABITS Commands, SET AUTOSCROLLTOCURSOR SET AUTOSIZE SET BACKSPACEDESTRUCTIVE SET BACKSPACEKEY SET BAUDRATE 3 Commands continued Contents, Contents,
Contents, continued
3 Commands Commands, continued
SET TERMCLOSE...... 508 SET TERMFONT...... 509 SET USERID...... 510 SET WILDCARD...... 511 SET WINDOWTITLE...... 512 SET WORDWRAP...... 513 SET XCLOCK...... 514 SET XSYSTEM...... 515 SETTINGS...... 516 SHOW...... 517 SPAWN...... 518 SWITCH...... 519 SYSTEM...... 521 TABLE CLEAR...... 523 TABLE CLOSE...... 524 TABLE COPY...... 525 TABLE DEFINE...... 527 TABLE LOAD...... 529 TABLE SAVE...... 530 TABLE SORT...... 531 TASKERROR...... 532 TASKSTOP...... 534 TIMER RESET...... 535 TITLE...... 536 TOOLBARHIDE...... 537 TOOLBARSHOW...... 538 TRANSFERS...... 539 WAIT CHAR...... 544 WAIT CLOSE...... 545 WAIT DELAY...... 546 WAIT ECHO...... 548 WAIT EDIT...... 549 WAIT PROMPT...... 550 WAIT QUIET...... 551 WAIT RESUME...... 553 DCS Script Language Reference WAIT SCREEN...... 554 WAIT STRING...... 555 xii Table of Contents xiii 581 582 583 585 586 587 588 593 594 595 596 597 556 557 559 561 562 563 564 566 567 569 571 572 573 574 575 576 577 578 579 580 593 ...... continued ...... continued continued continued ...... Task Errors, Errors, Task Errors, Task XFERCONFIG Errors Task Errors, Task WINDOW CLOSE WINDOW DEFAULT WINDOW HIDE WINDOW MAXIMIZE WINDOW MESSAGE WINDOW MINIMIZE WINDOW MOVE WINDOW OPEN WINDOW RESTORE WINDOW STACK WINDOW UNHIDE WHEN ERROR WHEN INPUT WHEN QUIET WHEN SCREEN WHEN STRING WHEN TIMER WHEN WINDOW WHILE WINDOW ACTIVATE WINDOW ARRANGE Commands, UNTIL WAIT WHEN CANCEL WHEN COLLECT WHEN DISCONNECT WHEN ECHO ...... Appendices Errors Task A 3 Commands continued Contents, Contents,
Task Errors, continued...... 598 B New and Removed Commands and Functions...... 599
...... 599 New Commands and Functions...... 600 Removed Commands and Functions...... 601 C Quick Reference for Command and Function Syntax...... 603
...... 603
Index...... 619 DCS Script Language Reference
xiv 1 Introduction to the Script Language
DCS 16 DCS Script Language Reference organization. For example,you can: the automationoffrequently taskswhileallowing performed forcustomizingDCStotheneedsofyour The DCSScriptLanguageisoneofmostpowerful features oftheDCSConnectivity Series. It provides for DCS ScriptLanguageOverview Commands, Each DCSfunctionandcommandare discussedindetail includes: script filemanagementconcepts.The overview This chapterprovides ofDCSScriptLanguagecomponentsbeginningwith ageneral overview What You Will Learn
Send commandsanddatatoahostmachine. Present datafrom ahostmachinein Windows thatyou design. interface Simplify complexinteractionswiththehostmachine. Respond toqueriesfrom ahostmachine. Execute complexlogic. Access otherapplicationsusingDynamicData Exchange (DDE). Print datafrom ahostmachinelocally. Transfer files.
Script debugginganderror correction Information aboutbasicprogramming practices An explanationofargumentsandvariables A discussionoflabels,comments,functions,andcommands Script statementsyntax respectively. Chapter 2Functions and Chapter 3 1 Introduction to the Script Language 17 - Script selection on , and New New Edit , File . Script extension. extension. . New is to create the Source document. Use the document. Use the Source is to create menu, select . File File Scripts menu, select File File When DCS starts, a task file in the Futuresoft\DCSeries\scripts directory with the Futuresoft\DCSeries\scripts When DCS starts, a task file in the On the expanded On On the On file is created from the source file. It contains DCS internal machine language gener It contains file. source the from file is created
2 To create a new script create To 1
menu to create the script document. menu to create File File ated from the source file. It is not a human-readable file, and is the only type of file that DCS It is not a human-readable file. the source ated from a “.dct” given Task file is The can execute. The Source file is simply a text file containing all the script language commands necessary file containing all the script language file is simply a text Source to The but can using DCS editing capabilities, created can easily be purpose. It accomplish the script cannot be file, and is a human-readable It editor. using any type of program also be created a “.dcp” file is given Source The executed. Task The Source Source file file Task “autostrt.dcp”. executed is name “autostrt.dcp” To create a script that automatically executes whenever DCS opens, save the script with the name DCS opens, save whenever that automatically executes a script create To An empty script file opens in the DCS window. All commands are entered in this file. entered All commands are window. An empty script file opens in the DCS Figure 1.1 script New document Creating and Editing creating a new script The first step in the Scripts are created, edited, compiled, and executed in DCS with selections on the edited, compiled, and executed created, Scripts are menus. Creating, Compiling, and Executing a Script a Script and Executing Compiling, Creating, includes two files: An operational script a compiled language. Script Language is The DCS 18 DCS Script Language Reference dialog Script Compiler Figure 1.2 Creating, Compiling,andExecutingaScript, readable form(asource file)toamachine-readable form(ataskfile). Before ascriptcanbeexecuted, ascriptfrom itmustbecompiled.Compilingconverts ahuman- Compiling andExecuting To editascript,usetheoptionsavailable onthe the scriptissuccessfully compiledandsaved asataskfile withthe.dctextension.The While DCScompilesthescript, itchecksforsyntaxerrors. If nosyntaxerrors are encountered, option forincludinglinenumbers. appears intheDCSapplicationwindow. It includesthenameofsource fileandacheckbox The Script CompilerDialog If:
Script Compiler
ately appears. The script you are editinghasalready beensaved appears. file. Select thenameoffiletocompileandclick you are prompted withthe You are notcurrently editingascript,oriftheactive window isnotascriptwindow, The with the You are currently editingascriptthathasnotbeenpreviously saved, you are prompted 1 To compileascript On the Script Compiler Save As Script dialogisusedtocompileascriptdocument.TheScriptCompiler dialogtosave thescript.Enter anameforthescriptandclick menu, select dialogappears. Open Compile dialog toopenapreviously saved scriptsource (*.dcp) Edit . menu. , the OK Script Compiler . The continued Script Compiler dialogimmedi Script dialog Save . - 1 Introduction to the Script Language 19 - - to remove to remove menu before menu before Stop File File on the continued continued Save As Save are placed in the compiled script. If placed in the compiled script. If are . to jump to the error in the script. DCS shifts to jump to the error dialog , line numbers Go To Error To Go Script Compiler command
menu. The source script does not need to be available for the task file to script does not need to be available menu. The source Include Line Numbers Include dialog and return to the script window. dialog and return appears in the SHOW Script you will be unable to recover any previous versions of the script file. versions any previous will be unable to recover you When a script is compiled, any changes made to the script are automatically When a script is compiled, any changes made to the script are make major changes to a script, use you If saved. you do not, If name. file using a different the source compiling the script and save
dialog disappears. If DCS encounters a syntax error, a message identifying the type and a message identifying syntax error, DCS encounters a If dialog disappears. on the Also see: Note: Run Run Script Compiler -
When a script has been successfully compiled, the script can be executed at any time by select at any time by When a script has been successfully compiled, the script can be executed ing the Script Stop on or if is encountered the task file and stops if a task error DCS executes execute. menu is selected. If you enable (check) you If command is pro during compilation, the line number of the offending encountered are errors script. vided to help find the command in the click and to correct the error Highlight Click and places the cursor at the location of the error. focus to the script source the Compiler location of the error Figure 1.3 Script Compiler dialog with er listed rors Creating, Compiling, and Executing a Script, a Script, and Executing Compiling, Creating, 20 DCS Script Language Reference ment andacommandstatement. DCS ScriptLanguagestatementsrequire useofaspecificsyntax single operands,complexorexpressions ofthespecifiedtype. ofanassignmentstatement.Commandandfunctionarguments mands oraspart Functionsbe performed. are executable statements ments DCS ScriptLanguagestatementsare entered intoascriptdocument.Commandsare executable state Commands, Functionsand Arguments that perform specificactions. thatperform Most commandsaccept not. Notice toothatsomecommandargumentsare required whileothersare optional. Notice inFigure 1.5thatsomecommandargumentsare enclosedinparentheses whileothersare statements two Examples of Figure 1.5 not allcommandsincludeargumentsasseeninFigure 1.5below withthe Command statementsbeginwithacommandnameandtypicallyincludearguments.However, Command StatementSyntax ments are required andsomeare optional be includedinthestatement.AlsoFigure 1.4,the In Figure 1.4above, the statements two Examples of Figure 1.4 ments mustbeenclosedinparentheses. Function statementsbeginwithafunctionnameandmayincludearguments.Function argu Function StatementSyntax
function command
Function Name RADIOGROUP CANCEL FILTER (String,SearchChars, EOF ( Command Name EOF ) function doesnotincludeanyarguments.However, the()setmust ( x, y,w,h)Default Required . that return avalue, andtherefore maybeusedascom Optional arguments Arguments FILTER . Below are examplesofafunctionstate Arguments
statement illustratesthatsomeargu GroupName that specifyhow theactionsare to R eplaceChars Required Optional canbespecified by either CANCEL Command Optional ) command. - - - - - 1 Introduction to the Script Language 21 . . %val function can be %number ” to the variable ” to the variable DISKSPACE DISKSPACE . continued . The $name combined with the appropriate operator for appropriate combined with the command) assigns a value to a variable. Values Values variable. to a value command) assigns a SET %availSpace (200/25) + 8*15) ; Example Syntax in this chapter ” to the string variable ” to the string variable Tim ” (a single operand) to the integer variable ” (a single operand) to the integer variable (equivalent to the (equivalent 2400 Variable Creation Variable consist of a single or multiple operands consist of a single or %val = (200/25) + (8*15) $name = “Tim” %availSpace = DISKSPACE () Variable = Value %number = 2400 String Numeric Boolean Also see: This command: “ of the expression assigns the value This command: “ assigns the string value This command: to the integer variable assigns a value a numeric value. argument since it returns used to specify the value This command: “ assigns the value can be numerics or strings (depending on the type of variable), or can be functions or expressions expressions or can be functions or (depending on the type of variable), can be numerics or strings a value. which return Example Expressions Expressions available: are types of operands three Three the specified type. The assignment operator Commands, Functions and Arguments, Arguments, and Functions Commands, 22 DCS Script Language Reference depends onthetypeoflinetobecontinued. Several methodsare available tocontinueascriptlinethenextphysicalifneeded.Themethodused Command Blocks WHILE blocks canbeusedtospecifythe A commandblockisasetofcommands Command Blocks The commandblockisexecuted onlywhenthe These examplesshow twowaysofwriting thesamescriptfragment: command. separated by commas,thefirst commandintheblockmustbeonsamelineas If thecommandblockisusedtospecifya Command blocksconsistofeither: Example 2 Example 1 , or
END BEGIN WHEN QUIET“5” RESUME IF (%timeout_cnt>10) DISPLAY (0,0)“timeout:“|STR(%timeout_cnt) WHEN QUIET“5”INCREMENT%timeout_cnt a setofcommandspreceded by a a setofcommandsseparatedby commas,or DIALOG END BEGIN IF (%timeout_cnt>10) DISPLAY (0,0)“timeout:“|STR(%timeout_cnt) INCREMENT %timeout_cnt DISPLAY (1,0)“terminatingprocess” RESUME DISPLAY (1,0)“terminatingprocess” control command COMMAND . thatistreated asasinglelogicalcommand WHEN BEGIN argument WHEN QUIET command argumentandconsistsofcommands command andfollowed by an required by an commandisactivated. IF , ELSE , END WHEN . Command WHEN command , . 1 Introduction to the Script Language 23 - . The valid . The
“25”
= .
$day
“March”,
=
commands WHILE $month
or in an expression contains no command list, commands on the following contains no command list, commands on the following command can be continued to show logical structure. command can be continued to show ELSE , IF WHILE command or Extensive use of commas may make it difficult to locate specific state make it difficult to locate specific use of commas may Extensive blocks in the script. ments and command “03/25/2001”,
at the end of the line and continue on the next line. at the end of the line and continue on the ELSE = WHILE
, IF or Caution! DISPLAY (0,0) $name | “ - President” DISPLAY (0,0) $name | “ - Vice President” GOTO find_name DISPLAY (0,0) “Please wait.” $date
ELSE , ELSE BEGIN END . . . WHILE %time < 10 TABLE DEFINE 0 FIELDS CHAR 10 CHAR 20 INT 15 \ TABLE DEFINE 0 FIELDS CHAR INT 3 INT 15 IF $name = “Washington” %sum = %apple + %orange + %peach + %banana %sum = %apple + %orange + IF IF Example Example Example Example line are assumed to be a continuation of the line. line are If an an If Place a backslash (\) Place continue a line containing To The lines of an To continue a line between operands continue a line between To operator after the last operand and continue with the next operand on the appropriate Place valid operator for strings is the concatenation operator (|) line. The the following variables and for Boolean valid operators +, -, *, /, and %. The operators for numerics are AND and OR. are expressions middle of a command continue a line in the To To continue a line between script commands a line between continue To below use commas as shown than one command on a line, more place To
Line Continuation lines within a script. for continuing available methods are Several 24 DCS Script Language Reference of acommentandare ignored by thecompiler. purpose andimplementation.Allcharactersonalinefollowing a“;”(semicolon) Comments are non-executing statements Comments Example recommended waytodocumentascript. asasimpleandstraightforward Since commentsare ignored by thecompiler, theyare optional;however, theuseofcommentsis END WHILE NOTEOF() RECORD READ0AT ; ;the followingroutinedisplaysallphonenumberrecords BEGIN RECORD READ0 DISPLAY @R0.1 thatassistthereader ofascriptsource fileinunderstandingits ;read nextrecord ;stop ifendoffile ;read firstrecord are considered tobepart 1 Introduction to the Script Language 25 (scripts followed by a series of characters by followed
in this chapter that mark a location in a script to which the execution of a script can of a the execution in a script to which a location that mark Message “Unable to Connect” Message “Script terminating” Message “TR1 — No Connection” Message “Trying Secondary Number” Dialog Dialog End Wait Delay “2” Cancel End Dialog End Wait Delay “2 Perform SetNextNumber If SecondaryNumber Begin Dialog End Increment %NumTries If %NumTries = 5 Begin Goto ConnectService Return End . . . *SetNextNumber #SecondaryNumber=True Set PhoneNumber = “555-1212” Parameter Passing #SecondaryNumber=False *ConnectService Set PhoneNumber = “555-1221” %NumTries=0 Dial While(not Connect()) Begin Example 1 Also see: and is not case sensitive. If a label is the name of a subroutine, you can also include a list of arguments after can also include a list of arguments you is the name of a subroutine, a label If and is not case sensitive. a label on the same line. any other statements following the compiler ignores the label. However, branch. Labels allow you to employ structured programming techniques to create modular scripts create techniques to programming structured to employ you branch. Labels allow and debug, since each module of modules tend to be easier to expand Scripts composed with subroutines). purpose, single entrytypically has a single point, and single exit point. a script and consist of an asterisk (*) line in own Labels appear on their cannot contain any spaces, up to 32 characters long. A label and underscores), (alphanumeric characters Labels statements non-executing Labels are 26 DCS Script Language Reference Labels, ful, thescriptdisplaysanerror dialogandthenendsscriptexecution. Number aloop.The scriptsegmentin Example 1performs If itfailstoconnect,callsthe on thevalue ofthesubroutine variables. ( variables ( the After thesubroutine finishesitstasks,themain routine continuesatthecommandfollowing name ofthesubroutine (thelabel)andalistofthevariables thesubroutine shouldactupon. PERFORM If there are variables inthemainroutine ofthescriptthatsubroutine shouldacton,the Example 2containsamodule,orsubroutine. Astandard subroutine usuallyhas: $String PERFORM continued Example 2
one exitpoint(usuallythe point(thelabel,whichmayornothave arguments),and one entry Return ;respectively. ;the contentsof$Name,%NumHours,or!AvgDaily, ;replace thecontentsof$String,%Int,and!Realwith ;At theendofsubroutine,subroutinewill . . . ;and !AvgDailyhasthesamevalueas!Real. ;value as$String,%NumHourshasthesamevalue%Int, ;a subroutineInitiallythevariable$Namehassame *SubRoutine ($Name,%NumHours,!AvgDaily) Cancel . . . ;the restofthemainroutine ;with thelistofvariablesbetweenparenthesis. subroutine the of variables the of some or all to ;values ;The MainRoutinestartsasubroutineandgivesdefault Perform SubRoutine($String,%Int,!Real) . . . ;this sectionofthescript. ;The variables$String,%Int,and!Realaredefinedin ;Main Routine subroutine toattemptasecondnumber. If thesecondattempttoconnectisunsuccess $Name , command shouldexplicitlypassthevariables tothesubroutine by includingboththe %Int command which started thesubroutine. Becausecommand whichstarted thecontentsofsubroutine , %NumHours , and !Real ;resume executionafterPerform ;End ofthescript ), whenthesubroutine returns, themain routine variables take , and RETURN !AvgDaily command). ) are the sameasthemainroutine variables SetNext - - 1 Introduction to the Script Language 27 - - - , maxi $first_ in a string . Variable names . Variable and string expres and string
. The quotation marks . The quotation marks and an ASCII character. and an ASCII character. followed by a variable name a variable by followed commands to place data into and to retrieve commands to place data into and to retrieve maximum of 254 characters. . by using another variable to represent the variable name. the variable to represent using another variable by RECORD READ . in a string, alternate the use of single and double quotation marks in a string, alternate the use of single and $Monday and a three-digit octal code, or a caret (^) octal code, or a caret and a three-digit and is an existing variable and contains the value Monday, creating the variable the variable creating Monday, and contains the value is an existing variable $day can be represented by either “\033” or “^[“. A carriage return can be represented by by can be represented either “\033” or “^[“. A carriage return by can be represented is written as double quotes with nothing between them (“”) between is written as double quotes with nothing RECORD WRITE creates the variable the variable creates ) and are not case sensitive. As with string constants, a string variable may contain a As with string constants, a string variable not case sensitive. ) and are script has its own record buffer variable. buffer record script has its own A record buffer variable is a string that contains a record. A record is a sub-unit of a table. A table is record A record. variable is a string that contains a buffer A record Simi a file can be loaded. Contents of the file can then be manipulated. into which is a structure to a masses of data into a single location. The data is then saved a table collects and organizes larly, a variable may have buffer record file. A single manipulation is performed Record cannot be manipulated directly. Contents of a table record with the a table, it places the contents of the table from When DCS reads a table, respectively. data from variable for that table, and when DCS writes to a table, it places the buffer into the record record variable buffer record in the table. The record variable into a buffer record contents of the table’s by a Each table defined the contents of a table record. manipulate you where area is a preparation A named string variable consists of a dollar sign ($) A named string variable (for example, characters or underscores may contain a maximum of 32 alphanumeric name mum of 254 characters. indirectly can be referenced Variables example, if For $$day specific to represent available are system variables several addition to the named string variable, In types of string data. Record Buffer Variables marks, e.g., ‘string’ or “string.” String constants may contain a maximum of 254 characters. constants may contain a maximum String “string.” or e.g., ‘string’ marks, embed a quotation mark To can be embedded characters ASCII control or ‘^$P “routine_a”’. car” e.g., “Arnold’s including a backslash (\) by An ESCAPE either “\015” or “^M”. A null string do not appear when a null string is displayed. Named String Variables String Functions in to the list of string functions a string. Refer a function that returns A string function is simply Reference C Quick Appendix String Constants single or double quotation of a series of characters enclosed within A string constant consists are created by joining two or more strings with valid operators. strings with valid joining two or more by created are sions Strings strings string constant. Complex or a a string variable, be a string function, A string can 28 DCS Script Language Reference Strings, Record buffer variables have thefollowing syntax The syntaxofthe record buffer variabledependsonthetypeoftablewithwhichitisassociated. DCS hastwotypesoftables: the following types:character, integer, orreal. fields ofastructured table record withthe All record buffer variables andanyfields withinthem are strings. However, ascriptdefinesthe each field,the records inastructured tableare alwaysthe same size. Because(CHAR), real you numbers(REAL),and integernumbers(INT). determinethesize of associated withadatatypeandsize. Thedatatypes and therecord fieldsare similartothecellsin rows. In astructured tableeachfieldmustbe it composesstructured tablerecords offields. Table records are similarto rows inaspreadsheet, DCS handlestherecord buffer variables forstructured tablesdifferently from texttables,because ters thatwere assignedtothevariable These examplesillustratethatthe record buffer variable foratexttableonlycontainsthecharac Consider thefollowing assignments: the variable changeswiththecharactersassignedtoit. able onlycontainsthecharactersthathave beenassignedtoit,andthenumberofcharactersin DCS treats therecord buffer variable inatexttablesimilarlytonamedstring variable. The vari and theField argument mustbeanintegerfrom 1to255. cord buffer variable forastructured table.Astructured tablemayhave a integer from 0to15.Theoptional script. DCScanhave upto16tablesdefinedatonetime The table. a structured for variable buffer ;A record @RTable.Field @RTable ;Arecordbuffervariableforatexttable. Table continued
;characters plus15more. ;The variablenowcontainsitsprevious14 @R0 =|“Morecharacters” ;one space. ;The variablenowcontains14charactersincluding @R0 =“Numbers:12345” ;spaces. ;The variablecontains12charactersincludingtwo @R0 =“Thisistext” Structured tableswhichhave fixed-length records composedoffields. Text tableswhichhave variable-length records, and argument isanintegerindicatingtherecord buffer variable Field . argument TABLE DEFINE : forfieldsinastructured tableare character isanintegeridentifyingasubdivisionofre , andthe command Table foratabledefinedin . Eachfieldcanbeoneof argument mustbean maximum of255fields, - - -
1 Introduction to the Script Language 29 - indicate the
INT , and REAL , CHAR delineate the fields of the record for the record of the delineate the fields FIELDS command might appear in a script as follows: might appear in a script command TABLE DEFINE TABLE @R0.1 = “Text” characters: the word Text ;The variable contains ten ;and six trailing spaces @R0.1 = @R0 | “More characters” previous ten characters: ;The variable contains the ;Text and six trailing spaces @R0.1 = TRIM (@R0) | “More characters” ;The TRIM function deletes the trailing spaces and ;the variable now contains another set of ten ;characters: TextMore c TABLE DEFINE 0 FIELDS CHAR 10 REAL 6 INT 9 TABLE DEFINE 0 FIELDS CHAR zero ;creates structured table @R0.1 = “Numbers: 12345” characters: Numbers: 1 ;The variable contains ten TABLE DEFINE 0 FIELDS CHAR 10 REAL 6 INT 9 0 FIELDS CHAR 10 REAL 6 INT TABLE DEFINE continued .However, if a field has a numeric definition (INT or REAL), DCS right justifies the data in the if a field has a numeric definition (INT or However, If the numbers placed in a field spaces. field and pads the unassigned positions with preceding digits than a field has positions, DCS truncates the rightmost, or least signifcant, more have digits contains ten characters, the second field contains six characters, and the third field contains nine and the third the second field contains six characters, contains ten characters, assigned to the fields. you have are the same no matter what of the fields characters. The size define a field with space for a maximum of 254 characters. may you However, pads the unassigned posi does not fill the field, DCS record assign to a field in a the data you If For example, consider the are left justified. character data tions with spaces. The fields defined as assignments: following For example, the example, For and numbers after the word The keywords buffer record and the fields, has three in the table defined above Each record zero. table numbered The keywords the same structure. for this table has variable These respectively). real numbers, and integer numbers, field (characters, logical data type of the in a field you to deal with the data a part table to allow of the definition of a structured types are the fields. The first field of the size indicate numbers after the keywords in a logical fashion. The Strings, Strings, 30 DCS Script Language Reference Strings, Considerthefollowing examples: to fillthefielditsexactlength. Thisensures thatthecorrect dataisplacedintothecorrect field. spacecharacterstothe rightortheleftofdata characters thanthedefinedfieldlength,insert a stringoflengthequaltothecombinedlengthsfields. fewerIf thedatainafieldcontains To accessall ofthefields ing record buffer variables are possible: The record buffer variableforthistableis This commandcreates structured Table 6. It hasthree fields. Using RecordBufferVariables continued @R6.3 @R6.2 @R6 @R6 =“test12338” TABLE DEFINE ;placed inthevariable!RealNum ;numeric values.Theresultis998765499.543and ;The NUMfunctiontransformsthestringsinto !RealNum =Num(@R0.2)+(@R0.3) ;The characters194aretruncated ;The variablecontainsninecharacters:998765432. @R0.3 =“998765432194” ;and 12345 ;The variablecontainsninecharacters:fourspaces @R0.3 =“12345” ;The characters2and1aretruncated ;The variablecontainssixcharacters:67.543 @R0.2 =“67.54321” ;variable !RealNum ;values. Theresultis2.468andplacedinthe ;The NUMfunctiontransformsthestringintonumeric !RealNum =Num ;space and1.234 ;The variablecontainssixcharacters:onepreceding @R0.2 =“1.234” .1 accessesthefirstfield(CHAR10), accessesthethird field (INT5). accessesthesecondfield(INT3),and @R6 6FIELDSCHAR10INT35 (@R0.2)+Num , donotincludetheperiodandfieldnumber;rather, include @R6 . To accesseachfieldof Table 6directly, thefollow - 1 Introduction to the Script Language 31 , when referring to , when referring is the third record position, position, record the third is arguments AT 2 Field in this chapter and Table Table is treated like an 18-character string (the fields CHAR string (the fields like an 18-character is treated @R6 10, test, contains only four characters, thus six spaces are added four characters, thus six spaces are 10, test, contains only 3, 123, contains three characters, thus no spaces are added; and added; characters, thus no spaces are 3, 123, contains three to the added spaces are thus three 5, 38, contains two characters, %TableNum FIELDS INT 3 CHAR 10 CHAR 10 %field CHAR INT INT %TableNum “DATA.DCM” AS TEXT Tables, Records, and Data Manipulation and Data Records, Tables, %field <= 3 DISPLAY @R(%TableNum).%field | “^M^J” INCREMENT ;Places the contents of the file into the table. RECORD READ %TableNum %Field = 1 WHILE BEGIN END %TableNum = 7 TABLE DEFINE TABLE LOAD RECORD READ 6 AT 0 record ;read table six at the first DISPLAY @R6 @R6.2 = “55” RECORD WRITE 6 AT 2 The data in field to the right of test; The data in field The data in field left of 38.
Also see: continued Example record. displays each field of the current a loop which sequentially These commands create because the record positions start positions at 0 (zero). because the record for the a script to use integer variables DCS allows variables. buffer record These commands modify the contents of Table 6: These commands modify the contents of variable buffer record string 55 to the second field of the The first command assigns the character variable to buffer record the fields in 6. The second command writes all of the current Table for phrase The command position. record the third six and in table In the example on the previous page, page, the previous the example on In combined length of 18): a 5 have 10, INT 3, and INT the terminal window: Table 6 in of record first the entire These commands display Strings, Strings, 32 DCS Script Language Reference Strings, ing syntax: function keycommandmayhave a A Function KeyandTitle Variables mands thatacceptstringvariables. Function keyandfunctiontitlevariables maybeusedasargumentsinallfunctionsandcom ment musthave avalue from 1to9,with9indicating atitlechangeforthe“Level: n” key. to modifythetitleof“Level: n” key, whichchangesthefunctionkeylevel. Thusthe Key argu ment mayalsobespecified by anumeric variable containinga valid value. DCSalsoallows you creation ofeightfunctionkeys(numbered 1through 8)oneachoffourlevels. The The following syntax: key canhave a The tion keylevel isspecifiedusingthe The keys oneachoffourlevels maybedefined,the The function key variablefunction key Key titlevariablefunction key Key Key continued Also see: argument argument mayalsobespecified by anumeric variable containinga valid value. Thefunc argument isanumericspecifyingthenumberoffunctionkey. Since eightfunction ;Changes theLevelbuttontitletoitsdefault. @T9 =“” ;Changes thetitleofLevelbutton. @T9 =“NextLevel” @Tkey @Fkey maximum of18alphanumericcharacters LEVEL isanumericspecifyingthenumberoffunctionkey. DCSallows the accesses the string contents of the command portion ofafunctionkey. accessesthestringcontentsofcommandportion A command accessesthestringtitleofafunctionkey. Thetitleofafunction LEVEL maximum of42characters. command Key argument musttakeonavalue from 1to8. . . Function the keytitlevariables observe The variable observes thefollow The variable observes Key argu - - - - - 1 Introduction to the Script Language 33 - - myse addressing form for addressing
is defined. In this case, In is defined. far target %num and contains the string “ have analogous commands in the have and contains the string commands PASSWORD for the connected session as well as the special for the connected session as well NUMBER can pass parameters in the script language, but not commands must use the PERFORM , and EXECUTE EXECUTE and and must be within the valid range for the title and function key vari must be within the valid ”, which represents a phone number. a phone number. ”, which represents LEVEL , ”. %num . A copy of the script with the desired subroutine will be loaded and executed will be loaded and executed subroutine . A copy of the script with the desired PERFORM PERFORM EXECUTE , 17135552334 ^$B = BREAK ^$E = EXECUTE ^$L = LEVEL ^$P = PERFORM @F%num = “MAIL^M” 1 has the title The first key on Level “ 1 has the title The second key on Level cretcode variable by the integer 2, only the key specified Level For of the value ables. LEVEL 1 @T1 = “NUMBER” @F1 = “17135552334” @T2 = “PASSWORD” @F2 = “mysecretcode” LEVEL 2 SYSTEM” @T%num = “MAIL
continued define two titled function keys on Level 1 and one key on Level 2: Level 1 and one key on define two titled function keys on Level Example These commands: BREAK from a function key. from Also, the above a script subroutine Reference The syntax specified in this DCS Script Language to support the selected function key. should be used for these commands. A function key command can specify a string to send to the remote system or specify a special to send to the remote A function key command can specify a string keys META include valid can function. Strings to commands in the correspond special functions strings (^M and ^J). The following line control DCS script language: The script language. Strings, Strings, 34 DCS Script Language Reference Strings, maximum of42characters.ASettings thefollowing variable observes syntax: session file,anditscontentsdependontheloadedfile.A Settings variablemayholda The Settings Settings Variables variables. Settings variables maybeusedasargumentsinallfunctionsandcommandsthatacceptstring must besaved forthesettings variable toretain value. thenew time thesessionfileisloaded. If the value ischangedduringscriptexecution, thenthesessionfile If asettings variable issaved inasessionfile,thecontentsofthat variable are restored thenext fied by a numeric variable containinga valid value. be defined,the The n setting variables. variables. In thiscase,thevalues of fied sessionfiles. Inthesecondscript,setting variablenumbers are specified byinteger assign values tothesettingsvariables These scripts: Example 1 continued argumentspecifiesthedesired settings variable number. Since eightsettings variables may Script 2 Script 1 @S variable is similartothenamedstringvariable, except thatitisstored ofa aspart SAVE “houston” @S%pass =“password-2” @S%idnum =“17131234567” SAVE “chicago” @S2 =“password-1” @S1 =“13121234567” n n argument musttakeonavalue from 1to8.The %id @S1 num and and @S2 %pass . Those values are thensaved inthespeci mustbewithinthevalid rangefor n
argument mayalsobespeci - - 1 Introduction to the Script Language 35 - - loads the appropriate session file loads the appropriate contain the values January, 8, and 2001, January, contain the values command $year LOAD commands then use the values appropriate for that appropriate commands then use the values
contains the value “January 8, 2001”. “January contains the value , and SEND $day $date , and
. String expressions differ from complex strings only in that they differ from expressions . String DIAL $month
@S2 | “^M” LOAD EDITTEXT (1) CANCEL EDITTEXT “Enter City” EDITTEXT “Enter “OK” RESUME BUTTON DEFAULT $date = $month | “ “ | $day | “, “ | $year BEGIN END ELSE DIALOG CANCEL DIAL @S1 WAIT STRING “Password” SEND DIALOG DIALOG END WAIT RESUME (1)) (Settings) | EDITTEXT IF EXISTS (Directory continued If the string variables the If the string variable respectively, the number of concat If A maximum of 254 characters can be placed in a string variable. ignored. 254, additional characters are enated characters exceeds city. Example instructs DCS to dial a phone number and send a password string. The dialog box deter string. The dialog box instructs number and send a password DCS to dial a phone mines which city the user wants to call. A for the city chosen. The Example 2 Example This script: String Expressions strings with joining two or more by created containing multiple operands are expressions String the concatenation operator (|) operand is a single string and cannot be used as arguments where not enclosed in parentheses are expected. Strings, Strings, 36 DCS Script Language Reference Strings, operand isexpected. and enclosedinparentheses. Acomplexstringmaybeusedasanargumentwhere asinglestring A complexstringconsistsofmultipleoperandsjoinedby theconcatenationoperator Complex Strings Example between eachstringisincluded). contains Washington, the numeric variable if thestringvariable In thisexample: continued %length =LENGTH $firstname ($firstname|“$lastname) contains“George”, andthestringvariable
%length containsthevalue 17(thespace $lastname (|) , 1 Introduction to the Script Language 37 - - . A real . A real , or from a real to an integer. to an integer. a real , or from or by directly assigning a real or assigning a real directly or by , followed by a variable name a variable by followed evaluates to 23. evaluates It converts a numeric to its opposite value, converts a numeric to its opposite value, It followed by a variable name. Variable names Variable name. a variable by followed functions %num
is an existing variable, and contains the value 1, and contains the value is an existing variable, , - INT -23 and %order contains REAL REAL
for a list. creates the variable !1. the variable creates num %
a numeric type from an integer to a real a numeric type from !%order 32 alphanumeric characters or underscores (for example, %bytes, !cash), and %bytes, (for example, 32 alphanumeric characters or underscores consists of a numeric function, a numeric variable, or a numeric constant preceded preceded a numeric constant or a numeric variable, a numeric function, consists of -%num with valid operators. DCS supports both integer and real numeric operands. supports operators. DCS with valid both integer and real variable consists of an exclamation point (!) consists of an exclamation variable Example the numeric variable If Appendix C Quick Reference C Quick Appendix There is one valid numeric modifier: the unaryvalid numeric modifier: the is one There minus. one). -1 (negative to multiplying the numeric by and is equivalent is possible to convert It truncated, not rounded. all decimal places are is converted to an integer value, value When a real can be converted using the Values type. variable to the desired integer value A numeric constant consists of an integer or real number, such as 25 or 3.14. Decimal numer 25 or 3.14. Decimal such as number, consists of an integer or real A numeric constant 0xn (for as represented numerics are (for example, 234). Hexadecimal as n represented ics are as \nnn (for example, \033). represented numbers are example, 0x3D). Octal Named Numeric Variables sign (%) consists of a percent An integer numeric variable numeric can contain up to to repre using another variable by indirectly variables may reference You not case sensitive. are if example, name. For sent the variable the variable creating Numeric Functions of numeric functions to the grouping that is a numeric. Refer a value returns A numeric function in Numeric Constants by an optional modifier. Complex numerics and numeric expressions are created by joining two or more by joining two or more created are numerics and numeric expressions Complex an optional modifier. by numeric operands Numerics operand A numeric 38 DCS Script Language Reference Numerics parentheses andcannotbeusedasargumentswhere asinglenumericoperandisexpected. /, %).Numeric expressions differfrom complexnumericsonlyinthattheyare notenclosedin Numeric expressions are created Numeric Expressions ing the result ofallnumericoperationsisareal toanintegereitherby numeric,butcanbeconverted us can beusedtoalterthisprecedence. Themodulusoperationisnotdefinedfor realnumerics.The modulus operatorstakeprecedence over theadditionandsubtractionoperators,butparentheses addition, subtraction,multiplication,division,andmodulus The valid numericoperatorsare: + A complexnumericvariable Complex NumericVariables Example numerics precise tothe15thdecimalplace. the real numericvariable In thisexample: variable containsthevalue 3. an integernumericvariable. The real result is,therefore, andtheintegernumeric truncated even thoughtheresult oftheoperation10/3isareal value, thiscommandstores theresult in In thisexample: Example 1 the integervariable In thisexampleofmodulusdivision: the integernumericvariable In thisexample: , INT continued !percentage =10/3 %integer =10/3 %remain =25%7 %sum =%wheat+%corn!rice function, orby storingtheresult asanintegernumericvariable. %remain consists ofmultiplenumericoperandsjoinedby avalid operator.
!percentage by joining twoormore numericswithavalid operator %sum , - issetto4,theremainder ofthemodulusdivisionoperation. , * , / issettothesumofthree numericvariables. , % . Theseoperatorscorrespond totheoperationsof containsthevalue 3.333333333333333.Real . Themultiplication,division,and
(+, -,*, - 1 Introduction to the Script Language 39 contains a random number contains a random number %number contains the value 10, contains the value %range %number = RANDOM (%range - 1) %number = RANDOM continued A complex numeric variable may be used as an argument where a single numeric operand is a single numeric as an argument where may be used numeric variable A complex expected. this example: In if the integer variable to 8 inclusive. 0 from generated in the range Numerics, Numerics, 40 DCS Script Language Reference Boolean operands with anoptionalmodifier. ComplexBooleanandexpressions are created by joiningtwoormore A Booleanmaybeafunction Booleans A Booleanfunctionreturns thevalue TRUE orFALSE. Examples ofBooleanfunctionsare: Boolean Functions There isone valid Booleanmodifier: NOT. aBooleantoitslogicalopposite. Itconverts lowing relational operators: A relational expression iscreated by comparingtwostringsornumericsusingoneofthefol Relational Expressions #%x name. For example,if sensitive. Variables canbereferenced indirectly by usinganothervariable torepresent thevariable contain up A Booleanvariable consistsof a numbersign(#) Named BooleanVariables within quotationmarks asinthe caseofastringconstant. A Booleanconstantisspecified by thekeyword TRUE or FALSE. Thekeyword isnotenclosed Boolean Constants Refer totheBooleanFunctions group in creates theBooleanvariable #5. withvalid operators.
>= <= != <> == = > < Operator Relationship ZOOMED ERROR CONNECT to 32alphanumericcharactersorunderscores (forexample, #state)andare not case
%x isanexistingvariable andcontains thevalue 5,creating thevariable Equal to Greater than Less than Greater thanorequalto Less thanorequalto Not equalto Not equalto Equal to , aBooleanvariable Chapter 2Functions , aBooleanconstant followed by avariable name foralistofallBooleanfunctions. , orarelational expression . Variable namescan - 1 Introduction to the Script Language 41 AND No proft is the relational expression evaluated. If it evaluates to it evaluates If evaluated. expression is the relational contains a string other than TEXAS. contains a string other than TEXAS or FLORIDA. contains any string other than function returns FALSE. function returns contains a numeric value less than or equal to 100. contains a numeric value ” is displayed. contains any numeric value other than those within the range 25- contains any numeric value EOF %1 $state %num $state (0, 0) “No profit made this quarter” (0, 0) “No profit %income > %net DISPLAY (0, 0) STR (%income - %net) | “dollars earned” DISPLAY %income > %net $state <> “TEXAS” AND $state <> “FLORIDA” %1 < 25 OR %1 > 50 NOT EOF () $state <> “TEXAS” %num <= 100 IF ELSE continued , evaluates to TRUE if TRUE to evaluates This Boolean expression: if TRUE to evaluates This Boolean expression: if TRUE to evaluates 50, inclusive. evaluates to TRUE if the TRUE to evaluates This Boolean expression: if TRUE to evaluates This Boolean expression: Example This Boolean expression: Example this example, In message “ FALSE, the to it evaluates If is displayed. of profit the amount TRUE, made this quarter Boolean Expressions using the Boolean operators created operands are containing multiple Boolean expressions and OR. Boolean AND over be used as an operator and has precedence may also and OR. NOT and may not enclosed in parentheses in that they are complex Booleans differ from expressions functions or no are Boolean operand is expected. There a single not be used as arguments where complex Booleans and Boolean operands; therefore, commands that expect only single Boolean may be used interchangeably. expressions Booleans 42 DCS Script Language Reference Booleans, dence over theORoperator, butparentheses canbeusedtoalterthisprecedence. by ORis TRUE ifanyinclusive associatedoperandsare TRUE. TheANDoperatortakesprece is TRUE ifallassociatedoperandsare TRUE. AcomplexBooleanconsistingofoperandsjoined Boolean operatorsare ANDandOR.AcomplexBooleanconsistingofoperandsjoinedby AND A complexBooleanconsistsofmultipleoperandsjoinedby avalid operator. The valid Complex Booleans $state evaluates to TRUE ifboth This Booleanexpression: Example continued (%1 <100AND%2100)OR($state=“FLORIDA”) containsthestring“ %1 and FLORIDA %2 containnumericvalues thatare lessthan100,or ”, orifbothstatementsare true. - 1 Introduction to the Script Language 43 - - Chapter 3 Com and : .ext in this chapter. Chapter 2 Functions filename.ext
filename drive: \path\ path\...\ filename.ext must be a numeric operand (constant, variable, expression, or function) expression, must be a numeric operand (constant, variable, drive: \path\ path\...\ . Therefore, you must be careful when specifying path and file names that you must be careful . Therefore, drive: \path\ path\...\ “G:\\123W\\123W.EXE” Tables, Records, and Data Manipulation and Data Records, Tables, LAUNCH %Table = Numeric Source = Destination = Filename = String String variables String expressions Complex strings String String constants to launch Lotus 1-2-3 from G:\123W\123W.EXE. to launch Lotus 1-2-3 from For example, you would specify: example, you For and file names may be represented in the DCS Script Language by: in the DCS Script Language represented and file names may be Table Arguments Table arguments observe Table numeric arguments used to specify a table number. arguments are Table syntax: the following Numeric argument The information about more For structures. table to one of the available 0 to 15, corresponding from tables, see A sequence of characters consisting of a backslash (\) followed by three octal digits is interpreted octal digits is interpreted three by (\) followed A sequence of characters consisting of a backslash character as a control numerals, a double backslash (\\) three specify a path that begins with To begin with numerals. numerals must be used. the three by followed File name arguments can be further specified as either Source or Destination arguments. A Source Source A Destination arguments. or Source be further name arguments can specified as either File the data to be exported.argument specifies a file name containing Destination argument A Destination arguments observe and the Source imported. specifies a file name into which data is syntax: following Path and File Names Path File Names name acceptable to the operat string arguments used to specify any file name arguments are File syntax observe name arguments the following ing system. File . as arguments for the commands and functions defined in as arguments for the mands Special Argument Argument Special Types frequently argument types appear types. These of the defined argument forms refers to several This section 44 DCS Script Language Reference Target argumentsare usedtoreference alabelinanexecutable scriptfile.Atargetargumentcanbeeithera: Types,Special Argument A neartargetreferences alabelwithinthecurrent script.Theneartargetargument Near Targets ror occursduringcompilationifthedesignatedneartargetisnotdefinedinscript. Near targetsare resolved atcompile time,andtherefore execute fasterthanfartargets.Asyntaxer and where where case ofastringconstant.Near targetargumentsusethefollowing syntax: acters thatspecifythedesired label.Thecharactersare notenclosedinquotationmarks asinthe Far target Far target Near Note: COMMAND
GOTO PERFORM EXECUTE COMMAND Label Label mand). script andthelabel(even ifthe labeliswithinthesamescriptas target mustalwaysbeinfarformatandincludeboththenameof When a is astring. is oneofthefollowing commands: Also see: PERFORM KEY Key VariablesFunction continued command or EXECUTE command isassignedtoafunctionkey, the inthischapter isasetofchar KEY com - - - 1 Introduction to the Script Language 45 , - Script *end_read argument is not in Label command. A record is read from Table Table from is read command. A record PERFORM . continued Script 0 at 0 @R0 returns TRUE and execution branches to the line labeled and execution TRUE returns “Script*Label” end_read is one of the following commands: is one of the following
not EOF () Record Read 0 Display function is the full file name of a compiled script, and is a label found in EXECUTE PERFORM GOTO COMMAND End Perform . . . Cancel *end_read Display “End of table reached” Return ;end of script execution *ReadLoop RECORD READ loop ;beginning of While Begin
EOF COMMAND Script *Label near targets are used as arguments for the used as arguments for the near targets are reached, When the end of file is in the terminal window. then displays that record It 0 (zero). the is terminated. a closing message is printed and script execution where Example this example: In cluded, execution begins at the first line in the specified script. cluded, execution where where where where the If as noted below. A far target must include at least one of the two arguments, except the script. If argument is not included, DCS defaults to the current Far Targets script or a label within the current so they can reference during execution, resolved targets are Far specifying an optional script is a string expression within another script. The far target argument is generated during script the designated far target is undefined, a critical error name and label. If syntax: target arguments observe the following Far execution. Special Argument Types, Argument Special Types, 46 DCS Script Language Reference Targets, Example an error occursduringtherecord read, execution branchestothelinelabeled all records from Table 0(zero) are read andthenthescript“ In thisexample: Example the script displays aclosingmessage.Execution thenbranches tothelinelabeled terminal window. If theendoftableisreached, the message box from anotherscript.Arecord isread from Table 0andthendisplayed inthe This scriptaccomplishesthesametaskasneartargetexample,butisnow a continued Note: CANCEL DISPLAY “ErrorEncountered^M” *error CANCEL ;endscriptafterexecuting“TABLE.DCT” PERFORM “table.dct”;callanotherscript END BEGIN WHILE NOTEOF() ;end ofscriptexecution Cancel Perform “Dialog*ReadComplete” Display “Endoftablereached” End Begin While notEOF() ;Beginning ofLoop RECORD READ0at *readloop IF ERROR RECORD READ0 Record Read0 Display @R0 Dialog and thelabel(even ifthelabeliswithinsamescriptas must alwaysbeinfartargetformat,andincludeboththenameofscript function key(seebothvariables andthe In caseswhere you wishto assigna GOTO anduponreturn thisscriptends. error ;errorisaneartarget () PERFORM EOF or TABLE.DCT function EXECUTE KEY returns TRUE, and command ),thetarget ReadComplete KEY command toa ” is performed. If ” isperformed. *error command). . in 1 Introduction to the Script Language 47 are are variables @R, @F, @T, @T, @R, @F, command, and can and Boolean COLLECT COLLECT system variables (other than the (other than command.
) before they are used. are they ) before DISPLAY may also be used to assign an initial value to a variable. It assigns the It to a variable. may also be used to assign an initial value is created during the execution of the during the execution is created command (=) $DataIn $DataIn command COLLECT DISPLAY $DataIn $name = “Lucy” Assignment operator (=) ARGUMENTS SET ARGUMENTS COLLECT PARSE FILE CREATENAME FILE OPENNAME WHEN ECHO WHEN INPUT SET
(DDE) REQUEST
Examples this example: In the variable the subsequently be used by All other commands and functions using variables as arguments must use variables that were that were as arguments must use variables All other commands and functions using variables commands. using one of the above created previously The assignment operator of the equal sign: to the left on the right of the equal sign to the variable value Numeric commands. using any of the above created are variables String using: created Direct Variables that variable. created to have is considered to a variable an initial value A command that assigns variables: commands can create Several @S, ConnectMessage, ConnectResult, DefaultSessionHandle, NetID, Password, Phonenumber, Result, Result, Phonenumber, Password, NetID, DefaultSessionHandle, ConnectResult, @S, ConnectMessage, a value (assigned must be created and UserID) Variable Creation Variable variables and string Boolean variables, variables, Numeric 48 DCS Script Language Reference Variable Creation, users. can makeiteasiertomaintaining ascript,orallow thescripttorespond toinputfrom different able isreflected throughout thecode, thuschangingany variable withwhichitisassociated. This Indirect variables provide flexibilityincodingascript.Achangethe value ofanindirect vari @s(%index=“secret” key titles,functionassignments,andrecord variables. For example,if Integer numericvariables mayalsobeusedtocreate indirect variables forsystem,function numeric andBooleanvariables. ABooleanvariable String andintegernumericvariables maybeusedtocreate indirect variable namesforstring, $varname=“x” by placingthevariable typesignifieratthebeginningofexisting variable. For example,if Indirect variable namesare created usinginteger(%)orstring($)variable types.Thisisdone are known asindirect variables. Variable creation canalsobeaccomplishedby usingexistingvariables tocreate ones.These new Indirect Variables This script: used by the ous scriptby creating thevariable because the In thisscript: value by a for the causes anexecution error because End Begin While notEOF() Record Read0AT %count =0 End Begin While notEOF() Record Read0At INCREMENT RecordRead0 Display “Record“|STR(%count)=@R0\ Increment Record Read0 Display “Record“|STR(%count)=@R0“^M” Increment %count SET INCREMENT INCREMENT and command ortheassignmentoperator. Thefollowing script corrects theerror. continued %$varname=1
command. To correct thiserror, | “^M” %count , then command. command doesnotcreate variables, thisscriptcorrects theprevi @s3 %count %count willbeassignedthestringsecret. , thenthevalue of wasnotcreated before beingusedasanargument usingtheassignmentoperator(=)before itis cannotbeusedtocreate anothervariable. %count %x willbe1. mustbegiven aninitial %index=3 and - - 1 Introduction to the Script Language 49 - is set to
function ERROR ” if the Error # (number sign) ? ( ) (parentheses) mark) (question “ (quote, double) function is used to select any file that has the DCP (*.dcp) and displays “ ROUTE ” is displayed, and script execution is terminated. and script execution ” is displayed, *error OK . Labels indicate subsections and subroutines in a script. . Labels indicate subsections and subroutines Display (%Row, 0) $File | “^M” Increment %Row $File = Next () PERFORM Error %Row = 0 $File = Route (directory(task)|”*.DCP”) While not Error () Begin End BEGIN END DISPLAY “OK” | “^M” CANCEL *Error DISPLAY “Error” | “^M” CANCEL IF ERROR () extension. characters. In this example: characters. In (*) used in The wildcard displayed. directory working are files in the current all script source the path argument of the execution branches to execution otherwise, “ TRUE; arbitrary or more 0 (zero) character used to represent also the default wildcard Asterisks are Examples this example: In \ (backslash) ^ (caret) $ (dollar sign) ! % (exclamation point) (percent sign) . ‘ (period) (quote, single) ; (semicolon) * (asterisk) @ (at sign) : (colon) , (comma) * (asterisk) Asterisks signal a label Symbols symbols include: Available are used to indicate a special condition or to indicate a particular variable type. Many symbols also func a particular a special condition or to indicate used to indicate type. Many variable are tion as operators. Symbols example) which (punctuation, for numerical characters than alphabetical or characters other are Symbols 50 DCS Script Language Reference Symbols “At” signsare usedtoindicatespecificsystemstring variables. @ (atsign) Colons are usedafterthedrive letterdesignationinDOSpathnames: : (colon) Carets are usedtoembedASCII control characters ^ (caret) Backslashes \ (backslash) Examples carets are usedtoassignastring containing anescapeandacarriagereturn toafunctionkey. In thisexample: , continued
$path =ROUTE(“C:\DCSERIES\*.*”) @F3 $file =ROUTE($path|“*.*”) $path =“C:\DCSERIES\SCRIPTS\” Separate drive designations,directories, andfile namesinDOSpathnames: %octal =\067 Indicate octalnumerics CHAR 20INT153 TABLE DEFINE0FIELDSCHAR10\ Continue acommandfrom one linetothenext ;Settings Variable @S4 =“Remote” ;Function KeyTitleVariable @T3 =“Number” ;Function KeyVariable @F3 =“555-2327” ;Record BufferVariable @R6.2 =“Tuesday” are usedto: =“^[LOGON^M” : inastring. : 1 Introduction to the Script Language 51 - END and BEGIN : : evaluates to 43.5, due to the use of paren evaluates : !num2 : as in this example: in function calls. evaluates to 43.4, but evaluates a command block from one line to the next without using a one line a command block from (0, 3, 20, “Texas”) $month “March”, !num1 SET SET $day “25”, SET $year “1994” SEARCH is evaluated in which an expression the order Control !num1 = 3 + 4 / 10 + 8 * 5 !num2 = ((3 + 4) / 10 + 8) * 5 !pi = 3.1415926535897 #selected = TRUE function arguments Enclose Separate parameter lists Separate 1) $Last = substr ($last, 1, $state = “Texas” pair: IF $date = “03/25/94”
Continue continued In this example, In evaluation. of theses to change the order # (number sign) used to indicate Boolean variables signs (or pound signs) are Number ( ) (parentheses) used to: are Parentheses $ (dollar sign) signs indicate a named string variable Dollar ! (exclamation point) numeric variable points indicate a real Exclamation , (comma) used to: Commas are Symbols, Symbols, 52 DCS Script Language Reference Symbols, . (period) Percent signsindicateanintegernumericvariable % (percentsign) will containastringthatiscomposed ofthealphabeticcharactersandsinglequoteenclosed in gle quote.On theotherhand,script linecontaining two singlequotes;however, thestring double quotesare unbalanced. Thecharacters In thisexample,thescriptlinecontaining In thisexample, within astring,alternatesingleanddoublequotes: Both singleanddoublequotationmarks are usedtoenclosestrings. To usequotationmarks ” (quotationmark,double) extension beginswith“DC”andisthree lettersinlength. The Question marks are thedefaultwildcard character ? (questionmark) Periods alsospecifyatablefieldin record buffer variable Periods are alsousedasDOSfileextensionseparators Periods indicatethedecimalplaceina(decimal)real numericoperand ? wildcard usedinthepathargumentof continued $quote2 =‘“‘|“Y’allcomeandseeus!” |‘“‘ $quote1 =‘“Y’allcomeandseeus!”’ $state =“Texas” End Begin While notError() $File =Route(directory(task)|“*.DC?”) %Row =0 @R12.4 =“1001” $file =ROUTE(“LOGON.DCT”) !number =342.77 %row =3 $File =Next() Increment %Row Display(%Row, 0)$File|“^M” $state contains thecharacters , ‘(quotationmark,single) all comeandseeus! $quote1 “Y (adoublequoteandacapital are enclosedbyY) : ROUTE usedtorepresent character: anysinglearbitrary Texas wouldnotcompile,sincethe single and : $quote2 : function . isusedtoselectanyfilewhose willcompile,and endswithadoubleandsin : $quote2
- 1 Introduction to the Script Language 53 ;returns name of file ;Script File Finder ;Script File ; (“*.DC?”) $file = ROUTE continued double quotes (“Y’all enclosed by line, the double quotes are the script In come and see us!”). concatenation. with the main string by single quotes and joined ; (semicolon) script). All characters on a line (useful for internally documenting a begin a comment Semicolons the compiler: by ignored a semicolon are following Symbols, Symbols, 54 DCS Script Language Reference variable and isequivalent tothe operations ontheoperandswithinanexpression; plustheassignmentoperator, whichcreates ormodifiesa Operators Operators Available operationsymbolsandBooleansyntaxinclude: Division operationsare evaluated before additionandsubtractionoperationsinan expression. The slashisthedivisionmathoperator / (divide) sion. Multiplication operationsare evaluated before additionandsubtractionoperations inanexpres The asteriskisthemultiplicationmathoperator * (multiply) It negative operator: canalsobeusedastheunary The minussignisthesubtractionmathoperator: - (subtract) The plussignistheadditionmathoperator: + (add) are eitherasinglecharacterorgroup ofcharactersthatrepresents arithmetic,stringorlogical ad = sin | concatenate | assign = add + dvd O =getrta reult <= less thanorequalto greater thanorequalto >= greaterthan > NOT equal to == OR divide \ AND multiply * subtract - !result =27.2/18 !result =27.2*18 %num =-1 %sum =34-123 %sum =34+123 SET command . : : modulus % lessthan < <> not equalto - 1 Introduction to the Script Language 55 by . You . You . is greater is greater %num1 $sysop $logon $source is less than 2. command): to the value of to the value SET SET %sessions is equivalent to the string in is equivalent $target : $user before addition and subtraction operations in an expression. and subtraction operations in an expression. addition before ; both set the variable ; both set the variable 2 ($logon) > 3300 ((%session_time - 3300) / 60) \ variable contains the whole number remainder of the division of number remainder contains the whole variable “You have less than” | \ STR | “minutes left ^M” DISPLAY (0,0) \ DISPLAY (0, 0) “administrator online ^M” DISPLAY (0, 0) “administrator DISPLAY (0,0) “new user online ^M” SET $target $source $target = $source continued IF SECONDS IF $user = $sysop IF %sessions < 2 1 2 %remainder = %num1 % %num2 %remainder = . is equivalent to line is equivalent 1 %remainder > (greater than) relational operator: than than sign is the greater The greater by This example displays a message if the elapsed time since the time specified than 55 minutes. This example displays a message if the string This example displays a message if the string can also use == for equal to. < (less than) operator: relational The less than sign is the less than This example displays a message if the integer numeric = (assign) to the (equivalent The equal sign is the assignment operator Line = or == (equal to) relational operator: The equal sign is also the equal to % (modulus) modulus math operator sign is the The percent The %num2 evaluated operations are Modulus real numbers. not defined for whole numbers, or integers, are The modulus operations Operators, Operators, 56 DCS Script Language Reference Operators, order (<=and=
IF $password = “newuser” \ CANCEL TABLE DEFINE TABLE LOAD RECORD READ 0 > “1998” IF @R0.1 = “Jan” AND @R0.2 ELSE RECORD READ 0 WHILE NOT EOF END Boolean operator is used in complex Boolean expressions. The expression evaluates to evaluates The expression Boolean operator is used in complex Boolean expressions.
relations are evaluated before before evaluated are relations OR AND NOT $userid TRUE if any of the associated operands are TRUE: if any of the associated operands are TRUE This example displays a message if and This example defines a table, and loads the This example defines a table, and loads match, the If the fields match the expected format. record that the first two fields in the first displays file” or incomplete If they do not match, “Old remote system. buffer is sent to the record stops. and script execution AND parentheses. OR The This example displays each record in Table 0 until reaching the end of the file. reaching the Table 0 until in record each This example displays AND The TRUE: if all associated operands are TRUE NOT The BEGIN Operators, Operators, 58 DCS Script Language Reference Operators, The vertical baristheconcatenationstringoperator: The vertical | (Concatenate) from lefttoright. The following tableliststh Operator Precedence function returns thevalue 5,anddisplaysthestring“You have lessthan5minutesleft”. string. For example,iftheintegernumeric In thisexample,concatenationoperatorsare adynamicvalue intothedisplayed usedtoinsert Lowest = OR AND = > + * NOT Highest Precedence IF SECONDS($logon)>3300 continued | “minutesleft” STR ((%session_time-3300)/60)\ “You havelessthan“|\ DISPLAY (0,0)\ e precedence formathandrelational operators ( ) Operators / >= - (assign) (equal to) - == %session_time %
(unary minus) <> <
containsthevalue 3600,the != <= . Alloperatorsassociate STR 1 Introduction to the Script Language 59
- PER A child routine . when they are assigned are when they . Any script or routine can . Any script or routine *Main . This scheme, however, imposes some imposes . This scheme, however, command is considered a child of the command is considered command. The routine containing the routine containing command. The are children of children are WHEN *No and PERFORM *Yes a child of another. command it interrupted. and WAIT WAIT
$Name = “*Yes” $Name = “*No” command is the parent; the called routine is the child. the called routine command is the parent; Else Perform $Name Cancel *Yes Display “Connection established” Return *No Display “ No connection established” Return *Main If Connect () is the parent routine. Both routine. is the parent and makes them available only to the routine in which they were created. This prevents the prevents This created. in which they were to the routine only and makes them available FORM the command list of a from executed A routine containing the routine it created routine that a child of the A dialog definition is considered to one routine be a parent A child routine can be called with a can be called with A child routine
*Main Example this example: In is created in one of three ways: one of three in is created an initial value and dispose of variables create having to explicitly script writer from is defined. Scoping a variable which rules make it necessary which restrictions over to consider the range define this range. routine. a child above level routine on a is defined as a parent branches, a script execution If Scoping Rules Scoping variables creates scheme automatically management Language variable DCS Script 60 DCS Script Language Reference Scoping Rules ables created inachildroutine The scopeofa variable these rules. Subroutines withinthesamescriptfilewhichare called by a parent routine. are executed. Anerror messagedisplays,indicatinganundefined variable was referenced by the An execution error occurswhenthe DCP. known onlytoCHILD2.DCPanditschildren. It isnotknown inPARENT.DCP orCHILD1. and itschildren. It isnotknown inPARENT.DCP orCHILD2.DCP. Likewise, and modify. However, since and The parent routine PARENT.DCP intheabove examplecreates the variables $city Example Also see: Return $street=“CloverLane” $city= “Dallas” Display $time CHILD2.DCP Return $name=“Smith” $time =TIME() Display $date CHILD1.DCP Cancel Display $street Display $city Display $name Perform “child2” Perform “child1” $city =“Chicago” $time =“” $date =Date() PARENT.DCP whichthechildroutines CHILD1.DCP andCHILD2.DCPcansuccessfullyaccess , continued Parameter Passing &Subroutines ARGUMENTS istheroutine inwhichitwascreated andanychildofthatroutine. Vari $name donotexistinitsparent routine. command iscreated inCHILD1.DCP, itisknown onlyinthisscript DISPLAY $name
;not visibletoparent ;created inparent ;created inparent ;not visibletoparent ;created inparent ;created inparent sectioninthischapter and PERFORM DISPLAY $street command donotfollow $date $street , commands $time is , - 1 Introduction to the Script Language 61 - - - - -
, sub1 it created it created %int command . A parameter command. all variable param all variable command. The parent command. The parent PERFORM ARGUMENTS to the routine labeled to the routine PERFORM 25.00 , and %age , or Boolean variable to the child routine, the child rou to the child routine, or Boolean variable $name . , numeric, it may be desirable to extend the limitations imposed by the scop extend the limitations imposed by it may be desirable to , . This mapping allows the passage of data back and forth the passage par between . This mapping allows !real (%int, $string, !real, #bool) , and #bool , , a parameter list must be specified by both the parent and child routines child and by both the parent , a parameter list must be specified PERFORM sub1 ($name, %age, 25.00) ;to a label in this script file PERFORM “Child1*sub1” ($name, %age, 25.00) ;to a label in the Child1 file *sub1 (%int, $string, !real, #bool) *sub1 (%int, $string, !real, *sub2 ARGUMENTS tine can use the initial value of the variable and can modify the variable. The parent routine can The parent and can modify the variable. of the variable tine can use the initial value These two examples: to pass the parameters illustrate how routine passes or to another script file). The parent (either to a local subroutine value. it is passed by the parameter is constant or an expression, If reference. eters by passes a string When the parent defines a child routine, which specifies a parameter list containing the local variables routine, which specifies a parameter list containing the local defines a child $string using a routine a parent can only be passed by Parameters by including a parameter list after the specifies the parameters to pass Example Example Each of these command fragments: script applications, promoting modular, structured script development. structured modular, script applications, promoting pass parameters To parameter list The child can specify the desired routine in either of two ways. list can be defined for a child starton the same line as the label indicating the or in an of the child routine, the label. included immediately following ing rules. DCS provides a parameter passing scheme that allows data from a parent routine to be mapped routine a parent from data that allows a parameter passing scheme ing rules. DCS provides in a child routine into local variables routine parent in the created variables protects of local variables creation while the ent and child routines, routine. by the child being unintentionally modified from routines that can be called from utility of generalized groups the script writer to create allow These features down to any of its child routines, but do not allow a child routine to pass the value of a variable to pass the value routine a child allow but do not to any of its child routines, down it level, on the parent created variable routine modifies a also specify that if a child They back to its parent. modifi from protection no have routine in the parent variables created also; level parent is modified on the variables. is the default scope of This within a child routine. cation from scripts modular or structured create To Parameter Passing & Subroutines & Subroutines Passing Parameter be passed routine to in a parent created variables section allow previous The scoping defined in the rules 62 DCS Script Language Reference Parameter Passing&Subroutines, expressions orvariables intheparent routine. child routine, thechildroutine canuseormodifythisvalue, butmodifyingitwillnotaffect When theparent passesastring,numeric,orBooleanexpression need notbethesame,butvariables mustbeofthesametype. then usethemodified value inthe variable. The variablenamesusedinthetwoparameterlists protect variables intheparent routine whichbearthesamenamefrom modification. disposed ofwhencontrol branchesbacktotheparent routine. Since theyare localvariables, they cannot bepassedtoorfrom them.Theyare local variables tobeused by thechild routine thatare MENTS Additional localvariables canbecreated foruseby thechildroutine by specifyingan routines. routine. Aparameterlistallows you between tomakeawell-defined theparent interface andchild passed by reference tothechildroutine orifthevariable nameisthesameinaparent andachild cal variable inachildroutine canmodifyavariable inaparent routine iftheparent variable is Specifying aparameterlistforchildroutine creates localvariables forthechildroutine. Alo list. parameter intheparent’s parameterlistintothecorresponding variable inthechild’s parameter parameters mustbeofthesametype:string,numeric,orBoolean dence between parametersinthe parameterlistoftheparent andthat ofthechild.Corresponding When passingparametersbetween tworoutines, there iscustomarilyaone-to-onecorrespon Example ence to passed by reference tothevariable three parametersare passedfrom theparent tothechild.The value stored in In thisexample: Example can modifythesevariables, value passing thenew backtotheparent routine. the variables are passedby reference; thechildroutine usesthevariables’ initialvalues, and In thisexample: command *sub1 ($String,%Years,!Salary) . . . PERFORM sub1($name,%age,25.00) PERFORM sub1($name,%number) %Years inadditiontotheparameterlist.These variables are notparameters; values . The value 25.00 $String ispassedto . The value stored in continued !Salary (notsimplevariables) tothe . . DCSplacesthevalue ofeach %age ispassedby refer $name ARGU is - - - - 1 Introduction to the Script Language 63 are assigned null are in the routine in the routine %Bracket %Bracket and , and $Date $Date , continued continued are parameters and therefore receive initial values initial values receive parameters and therefore are %age , %age $name and $name . The variables . The $name = “Arnold Wilson” $name = “Arnold %age = “34” ($name, %age) PERFORM sub1 %age) *sub1 ($name, %Bracket) ARGUMENTS ($Date, four local variables are created: created: are four local variables sub1 while the local variables the calling routine, from initial values. Example this example: In Parameter Passing & Subroutines, & Subroutines, Passing Parameter 64 DCS Script Language Reference the tablewillhave textrecords orstructured records. records orstructured records, butnotamixture ofboth. When atableisdefined, you mustspecifywhether A tableconsistsofoneormore records inwhichthedesired dataismaintained. Tables containeithertext from 0through 15. to afileatanytimeforpermanentstorage. and are therefore destroyed whenscriptexecution terminates. You can,however, save thecontentsofatable Tables structures usedtoimplementrandomaccessfileoperations. are temporary Tables existinmemory, incoming andoutgoingdatacanbeprocessed sessions. Tables facilitatetheautomationprocess by providing astructured mechanismthrough which featuresOne ofthe mostimportant oftheDCSScriptLanguageisautomationcommunications Tables, RecordsandDataManipulation when working outofmemory. withtableslargerthan64K toavoid running fileand swaps asneeded. recordsin atemporary in andoutofglobalmemory Use thisoption initsentirety.maintained inglobalmemory The The optional ofdata.The and export The datainatableisstored asastring,Thelogicaldatatypeis retainedtofacilitatetheimport fields andare definedaccording totypeandlength.Eachfieldargumentincludes: structured table. Text tablesdo nothave fields.The The structured tableisdefinedwiththefollowing command 555-6521 A structured tableconsistsoffixed-length records 7708Maple Avenue number) 555-2233 555-7899 Each row comprisesonerecord. Eachrecord consistsofthree fields(name,address, andphone 4435SouthLakeStreet Zeller, Henry 1232MainStreet Thomas,Cindy Smith, Arnold book asastructured table: record; eachcomponentisreferred toasafield etc.) andcanbeaccessedasagroup orindividually. Eachgroup ofcomponentsisreferred toasa eral organized components.These componentsmaybeofdifferent datatypes(character, integer, A structured tableismostoftenusedtomaintaindataofauniformformatwhichconsistssev Structured Tables Table .
An integerfrom 1to254thatspecifyiesthelengthofeachfield real numberrespectively), and A typekeyword; either CHAR,INT, orREAL(specifyingcharacter, integernumber, or TABLE DEFINE Table FIELDSf1...fi argument FILE keyword specifiesthetableidentifier(from 0to15).The TABLE DEFINE isusedforstructured tablesonly. By default,astructured table is Up to16tablescanbecreated .
command determinesthenumberoffieldsina record. withintherecord. To illustrate,consideraphone FILE FILE madeupofaspecifiednumberfields.A f1 through keyword : fi stores thespecifiedtableondisk argumentsspecifythedesired , eachidentified by anumber FIELDS . clause indicatesa - 1 Introduction to the Script Language 65 and record and record continued Exports the entire contents of a table to a file. Performs a table sort based on specified criteria. Clears all data from the table. Removes the specified table from memory. Copies the contents of one table to another. Creates a table. Imports a set of data records from a file into a table. 1 FIELDS CHAR 20 CHAR 50 CHAR 8 1 FIELDS CHAR Chapter 3 Commands TABLE SAVE SAVE TABLE SORT TABLE Command Description CLEAR TABLE CLOSE TABLE COPY TABLE DEFINE TABLE LOAD TABLE TABLE DEFINE Also see: designated as eight characters long to hold seven numbers and a hyphen. numbers seven designated as eight characters long to hold Example in page could be defined on the previous Book data shown the Phone A table used to hold way: the following fields. The first field holds table with three Table 1 as a structured This command defines past longer than 20 characters, all letters contain names any records name. If the person’s Again, all characters address. the 20th will be truncated. the person’s The second field holds This field was field holds the phone number. truncated. The third are past the 50th character Table operations treat the table as a unified entity. They to operate on the table as a whole, but do the table as a unified entity. operations treat Table tables: on structured table operations can be used The following not access individual records. A table to hold the Phone Book entryA table to hold the Phone The ways. be defined in a number of different data could drop for first and last name. The phone number could name could be split into two separate fields to define the fields of When deciding how integer fields. in two separate the hyphen and be stored the data will be used. The purpose of defining a table is consider how table, carefully a structured to facilitate data manipulation. types of operations can be performed table: table operations on a structured Two operations. Operations Table Tables, Records and Data Manipulation, and Data Manipulation, Records Tables, 66 DCS Script Language Reference Tables, RecordsandDataManipulation, of therecords inthetable,reflecting thefields created. DCSaccessesthe record buffer byusinga through the record buffer. A record bufferexistsforeachtabledefined,andisanexacttemplate Data contained inatablecannotbeaccesseddirectly, butmustbeaccessedonerecord atatime record individually. Record operationstreat eachrecord asaseparateentity, andallow you tooperateuponeach Record Operations sequentially. Thedata read canthen beaccessedthrough the record buffer variable. table. Thefirst record inatableisnumber0 (zero). Allsuccessive record reads are thenperformed ing randomaccess.If the record buffer. The record atwhichtobegin readingcanbespecifiedwiththe The mands builtuponthebasicreadingshortcuts andwritingoperations.For details,see RECORD FORMAT DCS allows thefollowing you toperform record operations: 3. @R3.5 definesa record buffer variableforthefifthfieldof record bufferassociated with Table @R3 definesa record buffer variablefortheentire record bufferassociatedwithtable three; example: a periodandspecifiesfieldwithinthe record buffer variable,allowing accesstoasinglefield. For The Table argumentspecifiesthenumberof table.Theoptional @RTable. record buffer variable. Astructured record buffer variable RECORD READ end ofthefile, in your terminalwindow (assumingtable sixhasbeendefined). with thenumberthree since thefirst record isnumbered zero) andcontinuingthrough tothe establish aloopwhichdisplays therecords in Table 6,beginningwithrecord four(specified The following commands: Example 1 . End Begin While NotEOF() Record Read6AT3 RECORD WRITE RECORD READ Record Commands Record Read6 Display @R6 Field and operationreads onerecord from thespecifiedtableintocorresponding ;which table=[0...15],whichfield[1...n] RECORD SCAN AT clauseisnotincluded,DCSbeginsreading atthefirst record inthe Writes onerecordofdatatothespecifiedtable. Reads onerecordofdatafromthespecifiedtable. Action commandsare alsoavailable, buttheyare advanced ;read nextrecord ;display recordcontents ;while notatendoffile ;read atrecord3 observes thefollowing observes syntax: continued Field argument ispreceded by AT Chapter 3Com clause,allow - - 1 Introduction to the Script Language 67
- - - - argu TABLE SAVE TABLE FileName clause to allow random clause to allow AT , where each character com , where continued A text table must be used to store data of an A text table must be used to store 1 to maintain unstructured data which consists of sequential lines of data to maintain unstructured operation writes one record from the record buffer to the corresponding buffer to the corresponding the record from writes one record operation
specifies the table identifier (from 0 to 15). specifies the table identifier (from indicates to DCS that a text table is being defined. Text tables do not have Text tables do not have indicates to DCS that a text table is being defined. @R1.3 = Time (), Record Write operations write data from the record buffer to the table structure, not to your not to buffer to the table structure, the record operations write data from Record Read 1 If @R1.3 = “” keyword argument clause is not included, DCS begins writing at the last record in the table. All successive in the table. All successive DCS begins writing at the last record clause is not included, TABLE DEFINE Table TEXT FileName TEXT DEFINE Table TABLE His name is Arnold Smith. His name is He lives at 1232 Main Street. His phone number is 555-2233. While Not EOF () Begin End AT perform both reads and writes to table one. Each record is read from the table and exam from is read and writes to table one. Each record perform both reads field. This is time is written to that current the is empty, record field of the the third ined. If reached. until the end of the file is sequentially performedrecords on all Example commands: The following Table Table TEXT RECORD WRITE RECORD fields. Unlike structured tables, text tables are always maintained on disk. The are tables, text tables Unlike structured fields. Each row comprises one record; there are no fields. are there comprises one record; Each row length. or variable unknown long up to 254 bytes records A text table consists of variable-length and line feed characters. A carriage return delimited by in a text table are Records prises one byte. syntax: text table is defined with the following The The RECORD WRITE a must execute data written to a table, you want to permanently save you disk. If the contents of the table to a file. command to save Tables Text A text table is most often used To illustrate, tables, text tables do not contain fields of multiple data types. structured text. Unlike unformatted text as a text table: consider the following The can be specified with the at which to begin writing record table. The access. the If the corre to the table through The data is passed then performed sequentially. writes are record variable. buffer sponding record Tables, Records and Data Manipulation, and Data Manipulation, Records Tables, 68 DCS Script Language Reference Tables, RecordsandDataManipulation, file doesnotexist,the Ifthespecified ment specifiesthenameoffileuponwhichtableoperationswillbeperformed. the previous record inthetabletoendofrecord where thepointerpresently is,butwith from anypositioninthetable. Without the position oftheread pointer inarecord inthe tableandallows copying thecommandtostart pointer, therest ofarecord intothecorresponding record buffer. The The DCS allows thefollowing you toperform record operations: buffer variable forthe record bufferassociatedwithtablethree. lowed inatexttable,the The tables usingtherecord buffer variable. Atext record thefollowing buffer variableobserves syntax: Record operationsoperateuponindividualrecords. Record operationsare ontext performed Record Operations formed ontexttables: Table operationstreat thetableasaunifiedentity. Thefollowing tableoperationscanbeper Table Operations table definitiondoesnotallow thetypeofflexibilityassociated withastructured table. Since atexttableconsistsoflinesdelimitedby carriagereturn andlinefeedcharacters,the RECORD READ Table A tableusedtoholdtheunformattedtextabove couldbe definedinthefollowing way: Example the file upon This commanddefinestableoneasatexttable.Alloperationswillbeperformed RECORD WRITE RECORD READ C @RTable TABLE DEFINE TABLE COPY TABLE CLOSE TABLE CLEAR Command Action TABLE DEFINE1TEXT“MYDATA.TXT” argument specifiesthenumberoftable. Since there are nofielddesignationsal ommand MYDATA.TXT
commandcopiesonerecord, ordependingonthepositionofread TABLE DEFINE Field . argument isnotincluded.For example, Writes onerecordofdatatothespecifiedtable Reads onerecordofdatafromthespecifiedtable Action Creates atable Copies thecontentsofonetabletoanother from memory Saves thetable’s contentstodiskandremovesthespecifiedtable Clears alldatafromthetable commandcreates thefile. AT AT clause, thecharactersare copied from theendof continued AT AT @R3 clause specifiesthe byte definesa record - - 1 Introduction to the Script Language 69 - - clause to AT RECORD READ 0 AT continued from this record you would specify: would you this record from only the name ;read first record ;while not at end of file ;display record contents ;read next record clause is not included, DCS reads until it encounters clause is not included, DCS reads LENGTH clause is not included, this position is, by default, at the beginning clause is not included, this position is, by clause. If a clause. If LENGTH DISPLAY @R6 RECORD READ 6 LENGTH RECORD READ 6 AT 0 WHILE NOT EOF () BEGIN END His name is Arnold Wilson. 13 RECORD READ 5 AT 12 LENGTH His name is Arnold Wilson. . clause the characters are copied from the position in a record indicated by the the by indicated position in a record the from copied characters are clause the establishes a loop which displays all the records in Table 6 in your terminal window (assum terminal window 6 in your Table in establishes a loop which displays all the records defined). 6 has been Table ing is the first record in Table 5 (five), to read to Table 5 (five), in record is the first example: The following This text record: This text this and one line feed). If one carriage return long (26 characters and spaces plus is 28 bytes “A” in Arnold, specify reading at the begin to record, is the first 12 below: the record If AT of the next line of text. After a record read is performed, the read pointer is positioned at the character following the last pointer is positioned at the character following is performed, the read read After a record the If character read. DCS does not prevent you from reading multiple text lines if the length you specify encompasses text lines if the length you multiple reading from you DCS does not prevent variable is 254 char buffer the maximum length of a record and line feeds. Since carriage returns length, remember read When calculating the may not specify a length larger than 254. acters, you each. The one byte and line feeds that appear at the end of a line count as that the carriage returns variable. buffer record the corresponding can then be accessed through data read Since the records in a text table can vary in length, you can also specify the number of bytes to table can vary in a text can also specify the number of bytes in length, you the records Since with the read feed character. character and then a line a carriage return the the end of the record. in a table, reading byte number at which to begin table is specified as a The position in a text position in a table is considered tables. The first position number as in structured not a record when it a record and line feed characters that end carriage return DCS includes the 0 (zero). to consist of were text table For example, if a record. bytes in a table or a number of the figures 12 the table to have DCS considers that record, to bytes to assign ten were and if you one record to 11). 0 the table (from positions in characters or byte Tables, Records and Data Manipulation, and Data Manipulation, Records Tables, 70 DCS Script Language Reference Tables, RecordsandDataManipulation, Since therecords inlength,you canalsospecifythenumberofbytes inatexttablecanvary for clause isnotincluded,DCSbeginswritingattheendoftable. byte isconsidered byte 0(zero). Carriagereturns andlinefeedscountasonebyte each.If the This positionisspecifiedasthe byte(notlinenumber)atwhichtobeginwriting,where thefirst The positionatwhichtobeginwritingcanbespecifiedwiththe The Chapter 3Commands used tocreate andmanipulatedatastored inatable,seethe you oftheirpurposeanduse. For withanoverview amore detailedexplanationofthecommands Tables are the mechanismthrough which DCS accessesfileobjects.Thissectionhas provided ning ofthenextlinetext. character written.If the After arecord thewritepointerispositionedatcharacterfollowing writeisperformed, thelast that thecarriagereturns andlinefeedsthatappearattheendofacountasonebyte each. acters, you cannotspecifyalength largerthan254. When calculatingthewritelength,remember carriage returns andlinefeeds.Since themaximumlengthofarecord buffer variable is254char DCS doesnotprevent you from writingmultipletextlinesifthelengthyou specifyencompasses “insert”). the endoftable,DCSwritesover alltextthatiscurrently inthespecifiedposition(itdoesnot and alinefeedcharacterattheendoftextwritten.If you specifyawritepositionthatisnotat DCS towritewiththe RECORD WRITE window andwritesthem,lineby line,to Table 6(assuming Table 6hasbeendefined). establishes aloopwhichcontinuallycollectsalllinesofdatathatcomeintoyour terminal The following example: Example End Begin While True Increment Record Write6 Collect @R6 operationwritesonerecord from therecord buffertothespecifiedtable. LENGTH . LENGTH %Count clause. If not included,DCSplacesacarriagereturn character clause isnotincluded,thispositionis,by default,atthebegin TABLE continued AT AT clause toallow randomaccess. and RECORD commands in AT AT - - 1 Introduction to the Script Language 71 command MENU command, DCS issues feature or through the the or through feature definition until the script MENU command. MENU ) which are displayed when a DCS when a DCS displayed ) which are SESSION command for details. MENU CANCEL , and command, are valid only after a valid command, are MENU SCRIPT MENU , command. The assumption is that the script wants to have wants to have command. The assumption is that the script command. command controls the DCS command controls command while there is a script defined menu in place causes is a script defined command while there MEMO , (see programming considerations below) allowing multiple sessions allowing considerations below) (see programming MENU MENU command without canceling the previous command without canceling the previous MAIN becomes the one and only menu regardless of document type until the script of document type until becomes the one and only menu regardless MENU CANCEL MENU CANCEL command to automatically terminate the previous menu definition. menu previous command to automatically terminate the MENU MENU commands. Changes made through the MENU EDITOR are permanent and become the permanent are the MENU EDITOR made through commands. Changes MENU CANCEL All script menu functions are valid with any menu. This is because they do not modify the menu valid All script menu functions are the status of the menu item. but only return The defined exits or performs a a Any script that executes is important that the It and the command will not be executed. a run-time to be returned error the See with the script execution. proceeding condition before script writer check for this error MENU command for details. the All script menu commands, except has been performed otherwise and the command they will cause a run-time to be returned error is important condition before that the scriptwriter check for this error It will not be executed. the See with the script execution. proceeding The first script to execute a The first script to exits or performs a the script of the what the user has access to during the duration of the script. If total control another executes a MENU 5. 2. 3. 4. 1. There will be times that the scriptwriter will want to use the default menu definitions or combination of There the use of SYSTEM menu numbers. for this through definitions as the starting definition. DCS allows If the for user selection. relate the DCS default definitions for easy identification These SYSTEM numbers to the default DCS definitions and not to any script writer uses one of the SYSTEM numbers it is related feature. the MENU EDITOR modifications made through and scripts to be executing at the same time. Because the menus are considered application-level resources resources application-level considered are the menus at the same time. Because and scripts to be executing applied when the MENU commands rules are the following and most scripts operate at the session level, used: are script user to the allow does of that type. The MENU EDITOR that menu for all windows default definition of temporary back to a script are to DCS defaults. Changes made through the menu and menus revert reset a exits or executes their default definition when the script MDI application Windows DCS is a document (window) of the corresponding type is active. Furthermore, the four menus are associated at the menus are the four Furthermore, type is active. of the corresponding document (window) menu set will be This means, for example, the SESSION session level. not at the DCS application level, DCS child no open are if there MAIN menu set is displayed The is active. window used when any session windows. the DCS MENU EDITOR through modified (customized) These menus may be Menus ( default menu sets DCS has four 72 DCS Script Language Reference script editorwindow. application window. SESSIONrefers tosessionwindows, MEMOtomemowindows, andSCRIPTtoa dependingonwhichtypeofwindow*The visiblemenus isactivevary (infocus).MAIN refers totheDCS The following SYSTEMnumbersare defined: Menus, YTM4 dt SESSION MEMO,SCRIPT SESSION,SCRIPT, MEMO Edit MAIN Edit File SYSTEM 4 File SYSTEM 3 SYSTEM 2 SYSTEM 1 System Example 1 MEMO SESSION Insert MAIN,MEMO,SCRIPT, SESSION MEMO,SCRIPT, SESSION Session SYSTEM 12 MEMO,SCRIPT Window Help SYSTEM 11 MAIN,SESSION Tools MAIN,MEMO,SCRIPT, SESSION SYSTEM 10 Tools SYSTEM 9 MAIN,MEMO,SCRIPT, SESSION View SYSTEM 8 Script SYSTEM 7 SYSTEM 6 SYSTEM 5 continued formed. CANCEL group, andthe group, the the menubardefinitionismadeupof In thisexample: PERFORM receive_files MENU CANCEL PERFORM setup MENU END MENU POPUP “Help”SYSTEM9 POPUP “Windows”SYSTEM10 POPUP “Session”SYSTEM11 POPUP “Edit”SYSTEM3 POPUP “File”SYSTEM2
command restores theseoptions before the Edit eu Activewindowtype* Menu Help menu oftheMEMO/SCRIPTgroup, the“Session menuoftheSESSION menu oftheMAIN/MEMO/SCRIPT/SESSIONgroups. The File menu oftheMEMO/SCRIPT/SESSION receive_files routine isper MENU - 1 Introduction to the Script Language 73 menu and a new popup menus. Session Session Help Help and Windows Windows “Windows” SYSTEM 10 “Windows” SYSTEM “NewItem” PERFORM new_item_routine “NewItem” PERFORM POPUP “MyMenu” POPUP “Help” SYSTEM 9 PERFORM receive_files POPUP “File” SYSTEM 2 POPUP “File” SYSTEM 3 POPUP “Edit” SYSTEM 11 POPUP “Session” POPUP and item inserted the between ITEM “MyItem” PERFORM my_routine MENU END PERFORM setup MENU CANCEL MENU SEPARATOR ITEM is the same as Example 1 with a new item added to the is the same as Example menu Example 2 Example This example: continued Menus, Menus, 74 DCS Script Language Reference DCS Windows &Window Handles open windows. dimmed) titlebarandwindow border. Theactive window almostalwayslaysontopofanyother An active window isthewindow whichhasfocus.It appearswithahighlighted(asopposedto DCS Windows handle usingthe If you donotknow thewindow window, handle ofaparticular you canretrieve thewindow determine thecurrent variable setting. used withthecommandorfunction.The When setallfunctionsorcommandseffectthespecifiedwindow unlessa DEFAULTSESSIONHANDLE when thescriptisexecuted theDEFAULTSESSIONHANDLE variable isNOT set.The handle oftheactive window whenthescriptisexecuted. If there isnoDCSchildwindow active Each scripthasaDEFAULTSESSIONHANDLE WinHandle A window handleisaninteger, and in mostcasesisspecifiedafunctionorcommand by the To window, specifyaparticular itswindow handlemustbeincludedinthecommandsyntax. sion window, DCSchildwindow, editwindow, etc.)asthetargetofafunctionorcommand. In manyfunctionsandcommands,you window have theoptionofspecifyingaparticular (ses window isdeterminedby usingthe: Window window Handles specifyaparticular asthetargetofafunctionorcommand DCS Window Handles active session, andcommandsmaybesenttotheactive session If awindow ishidden,itnotvisible.However, ahiddensessionwindow HIDE “ the In thisexample: Example Session1 3) 2) 1) WINDOWHND
WINDOW HIDE%hnd %hnd =WINDOWHND(“Session1”) Active window Script’s DefaultSessionHandle WinHandle also infocus. An active sessionwindow An active sessionisunderstoodtobeacurrently incontactwitharemote system. commandtohidethe“Session1” window. argument. HWNDLIST ”. Thehandleisstored in the variable argument function isusedtoretrieve thewindow handleforthewindow titled
or commandcanbeusedtochange/setthisvariable forthescript. ofthefunctionorcommand WINDOWHND isasessionwhichbothincontactwithremote hostand DEFAULTSESSIONHANDLE functions, orthe variable %hnd . This variable issettothewindow . and usedwiththe CONNECT function WinHandle can stillcontainan
command. canbeusedto WINDOW argumentis . Thetarget SET - 1 Introduction to the Script Language 75 - - - - - func SPAWN SPAWN ). For example, if ). For DEFAULTSESSIONHANDLE . The , and in this case each script may have a dif , and in this case each script may have continued , command . An arbitrary number of instances of DCS, each running sessions concurrently. several One instance of DCS runningOne one session. instance of DCS running sessions concurrently. One several An arbitrary of instances of DCS, each running number a single session. SET DEFAULTSESSIONHANDLE SET
FAULTSESSIONHANDLE, the script has no default window. Instead, each command and Instead, window. the script has no default FAULTSESSIONHANDLE, at the time the command or function is is active window by default, whichever function affects, window). a different (unless the command or function specifies executed at the same time than one script may be active More its default window or reset, A script may set, or the same default window. default window ferent with the default window. the current tion returns newthe to the with script, window default a assign scripts, and other execute may Scripts command Before writing scripts which take advantage of the Windows MDI interface, MDI should under you Windows of the writing scripts which take advantage Before DCS scripts operate in this environment. stand how at the active its functions and commands affect the session window When a script is executed, default (sets the DEFAULTSESSIONHANDLE by time the script is executed which may specify any command or function when the script is executed, is active “A” Window “A” (unless the command or function specifies a Window will always affect a particular window window). different and the script does not set the DE when the script is executed is active no session window If Programming Considerations Programming arbitrary an MDI interface.This allows number of emulations, con Windows DCS supports the arbitrary An number of instances and sessions to run concurrently. windows nectors, and editing upon the machine and system capabilities. Depending the user’s only by is also possible, limited could be: needs, the environment user’s DCS Windows & Window Handles Window & DCS Windows 76 DCS Script Language Reference vents the interrupted vents theinterrupted To terminatethecurrent waitstate vated duringawaitstate WAIT commands inthecommandlistwhenconditionsevent clauseare met. Both Two typesofcommandsare available fordetectingevents Event Handling WAIT commands are activated whentheevent clausebecomes TRUE. are executed. whileDCSiswaiting,the comes true script execution takesplaceduringthe WAIT are manytypesof Four To accommodatethissystem,you couldusethefollowing script: When thepassword issent,thesystemsendsoneofthree responses: Imagine you are connectedtoasystemexpectingpassword tobesentbefore accessisapproved. Example
and WHEN as awaitstate. WAIT WAIT multiple events. thewaitstateiftheirconditionsareinterrupt met.Thiscapabilityallows ascripttowaitfor fied condition WHEN WHEN . It DCStowaituntilitreceives instructs toresume theinstruction execution. No other WHEN CANCEL WAIT RESUME WHEN TIMER WHEN STRING2“oldpassword”PERFORMup_passwd, RESUME WHEN STRING1“passwordinvalid”CANCEL WHEN STRING old password,pleaseupdate password invalid password ok Password Response commands pausescriptexecution untilaspecifiedevent becomes TRUE. Thisisknown commands commands commands branchscriptexecution toanindicatedcommand blockwhenaspeci WAIT criteria are firstestablished,andthena
commands are followed by anevent clauseandacommandlist.DCS executes the —if theevent clausebecomes TRUE before orduringthecurrent waitstate. - become TRUE. WAIT from regaining control whenthecommandlistisexecuted. WAIT commands, butthe , includea 0“passwordok”PERFORMget_info,RESUME “30” PERFORMtime_out,RESUME and WHEN RESUME WHEN WHEN WAIT commands executed priortothecurrent waitstatewill . If theevent clauseofany WAIT RESUME is activated, andthecommandsincommandlist
command inthe : Commands WAIT RESUME WHEN could beconsidered a“generic” WHEN
Commands are onlyacti command executes. There WHEN command list.Thispre command be - - - - 1 Introduction to the Script Language 77 - . When get_info continued statement. If “password invalid” is received, is received, invalid” “password statement. If Commands, Commands, WAIT WAIT . WHEN WHEN time_out and . If none of these three responses is received within 30 seconds, execution execution within 30 seconds, is received responses none of these three . If WAIT WAIT - In the example on the previous page, DCS waits 30 seconds for a response from the remote sys the remote from response page, DCS waits 30 seconds for a the example on the previous In labeled routine branches to the execution is received, ok” “password tem. If returns to the control is finished, that routine labeled branches to the routine execution is received, password” “old terminates. If execution update_password labeled branches to the routine Event Handling Event 78 DCS Script Language Reference ported DDEcommands,see ported DDEwithScriptLanguagecommands.Forapplications. DCSsupports acompletelistingofthesup Dynamic Data Exchange (DDE)allows theexchange ofinformationbetween twoindependent Windows Dynamic DataExchange-DDE cation thatinitiatesaconversation istheapplicationthatanswers andmakesrequests. Theserver There are inanyDDEconversation: aclientandserver. twoparticipants Theclient is theappli DDE Concepts file orprintitout. table. Since itwillbesentdirectly totheapplicationsthatneedit, there isnoneed to save ittoa permitting). Yougraphics applications(memory thengatherthedataasusual, andstore itina This procedure couldbegreatly simplified usingDDE. runboththe Youfirst spreadsheet and threeto sequentiallyrun applications,printoutthedata,andenterdataintotwoapplications. thedata. agraphicspackageto chart pleted, you run To accomplishthisyou have takenthetime application usingthedatatoupdateappropriate cellsonthespreadsheet. When thisiscom the dataintoatable,save itinafile,andgetprintoutofthedata. run aspreadsheetYou then Imagine thatyou useDCStogatherweekly salesdatafrom aremote computersystem. You read To illustrate the advantages ofDDE,consider thefollowing example: There are three stagesinaDDEconversation: ning onyour computeratthesametime. run applicationmustbe the clientandfillsits requests. Boththeclientapplicationandserver Termination Transaction Initiation dows terminatemessage.Theotherapplicationthenanswers withaterminatemessage. canendthe conversationAt by anytime,eithertheclientorserver sendinga Win quests: responds to The server requests from theclient.Theclientcansendfourtypesof re tion couldbeestablished. responds sage. Theserver by informingtheclientwhetherornot requested conversa The client requests aconversationby sendinga withtheserver Windows initiate mes Execute message Poke message Advise message Request message Message Type Chapter 3Commands Requests thattheserverexecutespecifiedcommands Requests thattheserverreceivespecifieddataitem data item Requests continuousupdatesfromtheserveronaspecified Requests aspecifieddataitemfromtheserver Action . ------1 Introduction to the Script Language 79 ------command, the current script is command, the current WAIT RESUME WAIT continued command, the initiation fails. . If DCS is the client, you must establish, from an application’s docu an application’s must establish, from DCS is the client, you . If WAIT RESUME WAIT you must specify one of the three following DCS topics: the name of your DCS server DCS topics: the name of your following must specify one of the three you script, a null topic, or SYSTEM. server a If script is specified as the topic (the file extension need not be included), the no script is running, DCS state. If depends on current establishment of the conversation If another script is begins. and the conversation the specified server script is executed is paused at a running and execution is If another script closed, and the specified serverrunning and execu script is executed. tion is not at a SYSTEM topic is specified, no script need be the the If running for DCS to answer no script is running, if any client DCS will be unable to process initiation. However, A DDE conversation begins when the client establishes a conversation with a server. The with a server. establishes a conversation begins when the client A DDE conversation Win another the name to which the server If will respond. know client must, therefore, using DCSERIES as to all initiate requests application is the client, DCS responds dows the server name applications use some form mentation, the server Most name to which it will respond. to responds Excel example, Microsoft of their application name as their server name. For the server name EXCEL. a topic. The topic describes something in the server must also have A DDE conversation application is the client, Windows another application that the client wants to access. If Topic Server Name DDE is a quick and easy way for multiple applications to share data. DDE also allows the ex allows data. DDE also easy way for multiple applications to share DDE is a quick and with another applications. DCS can only conduct a DDE conversation between change of control application that supports DDE. Windows DDE Implementation performed DCS is to be the client, a using script commands. If DCS, all DDE functions are In DCS is to be the DCS will make. If all the DDE requests client script must be written containing con To DCS to handle incoming requests. a server be written which prepares script must server, upon the following need to agree both applications in the conversation duct a DDE conversation, elements: You then execute a DDE script. This script initiates a conversation with the spreadsheet, sending sending spreadsheet, with the conversation script initiates a a DDE script. This execute then You a con and initiates then terminates this conversation cells. It data to the appropriate the required conversa then terminates this data. It package, sending it the required with the graphics versation execution. tion and cancels script with just the data automatically updated each application running have a single script, you By continuously send updated DCS. The script may be modified to exiting it needed, without ever to system. DCS can also send commands the remote from as it is received data to each application instructingthe other applications them to draw a chart or print a spreadsheet. Dynamic Data Exchange - DDE, - DDE, Data Exchange Dynamic 80 DCS Script Language Reference Dynamic DataExchange-DDE, QUEST usingthe the server SEND usingthe poke datatotheserver ing asingledataitem,orby processing anentire tablecontainingmultipledataitems.DCScan When actingasaDDEclient,DCScansendorreceive dataineitheroftwoways:by process Single/Multiple DataItems conversation. requests shouldreference thischannelnumbertoinsure thattheyare directed tothedesired DDE the DDEconversation isestablished.If multipleDDEconversations are takingplace, all DDE of the obtained duringtheinitiateprocess. In DCS,a that allow multipleDDEchannelshave amechanismthrough whichthechannelnumber not onlytotheproper application, butalsothrough theproper DDEchannel.Allapplications applications. If multipleDDE conversations are takingplace,DDErequests mustbedirected toanyofthese permitting).DCScanbeclientorserver any numberofapplications(memory DCS canprocess upto16DDE conversations Multiple DDEChannels ACCESS commandtosendtheentire contentsofthespecifiedtable.DCScan request datafrom commandtorequest multipleitemstobestored inatable. Item Name Item Microsoft Excel canusearow andcolumnreference asanitem. you mustestablishthetypeofitemnamesotherapplicationrequires. For example, command.If DCSistheclient, string itemnamethatisestablishedinaDCSserver same itemname.If another Windows applicationistheclient,DCSresponds toany responseformat ofanitemname,butbothclientrequest mustreference andserver the merely tomatchaclientrequest dictatesthe response. totheproper Theserver server Each DDErequest mustreference anitem.Themainpurposeofthisitemnameis extension), ortheSYSTEMtopic. tion. For example,Microsoft Excel recognizes thenameofanyopendocument(with If DCSis the client,you mustestablishthetopicnamesrequired by theotherapplica of DCS. requests. For thisreason, theSYSTEMtopicshouldonlybeusedtotestforexistence
and REQUEST WHEN INITIATE command torequest asingledataitem,orusingthe POKE commands.This variable receives a channelnumberwhen command tosendasingledataitem,orusingthe continued
at thesametime.Theconversations caninvolve ChannelVar argumentisincludedinthesyntax TABLE RE is TABLE - - - 1 Introduction to the Script Language 81 . - %ch_num C:\EXCEL\ command syntax is in the format DCS as Server WHEN EXECUTE Response WHEN INITIATE WHEN POKE INSTRUCT INSTRUCT continued command directs Excel to open the Excel command directs
WHEN ADVISE REPLY TABLE SEND TABLE INSTRUCT worksheet. Notice that the Notice worksheet. ‘Excel’ ‘System’ %ch_num IF ERROR () DISPLAY ‘No access’, CANCEL IF ERROR () DISPLAY ‘No access’, INSTRUCT ‘[OPEN(“C:\\EXCEL\\SURVEY.XLS”)]’ REQUEST REQUEST TERMINATE REQUEST TABLE ACCESS CANCEL WHEN REQUEST TERMINATE WHEN REPLY TABLE ACCESS DDE Message ADVISE DCS as Client EXECUTE INITIATE INSTRUCT POKE ACCESS a DDE conversation is established with Microsoft Excel, using the SYSTEM topic. The Excel, is established with Microsoft a DDE conversation in the variable stored is conversation channel number associated with this DDE win in the terminal message is displayed cannot be established, an error the conversation If terminates. and execution dow, it is established, the If SURVEY.XLS Excel. expected by Example this example: In The commands in the DCS as Client column send the DDE message to the serverThe commands in the DCS as Client column application. a the DDE message from receive DCS to Server column prepare The commands in the DCS as to the client message. replies DCS Response column indicates how client application. The Syntax below. commands supportedThe syntax of the DDE by DCS is summarized Dynamic Data Exchange - DDE, - DDE, Data Exchange Dynamic 82 DCS Script Language Reference errors: Task errors Task Errors occur when DCS cannot carry outthetasksastheyare presented. occurwhenDCScannotcarry There are fourtypesoftask Fatal Errors Fatal Run-TimeErrors WarningErrors Errors Critical from thecommand inwhichtheerror wasencountered. For example,executing a explanation oftheerror. Afatalerror indicatesthatDCSisnotabletoproceed inexecution When DCSencountersafatalerror, the occurrence. The error.run-time DCScontinuesexecution errors, withoutinformingyou pastrun-time oftheir topositiontheread pointertoa positionpasttheendofatablegenerates example, trying typically programming errors. Theyare meanttobeused by ascripttosetstatusflags. For error,When DCSencountersarun-time nodialogisdisplayed. Run-time errors are not Cancel of execution. To continueexecution, clickthe When awarningerror isencountered, DCSwillallow eithercontinuationortermination from anundefinedtablewouldgeneratewarningerrors. encountered, todoso. ifinstructed For orattemptingtoread example,violatingscopingrules ming error. DCSisabletoproceed with execution ofthe commandinwhichtheerror was along withabriefexplanationoftheerror. Awarningerror indicatesalessserious program When DCSencountersawarningerror, adifferent typeof button. tion. To continueexecution, clickthe When acriticalerror isencountered, DCSallows eithercontinuationorterminationofexecu would generateacriticalerror. the error wasencountered, todoso. ifinstructed For outofglobalmemory example,running logic oftherest ofthescript.DCSisabletoproceed inexecution from thecommandinwhich explanation oftheerror. A criticalerror indicatesaseriouserror whichwilllikelyimpairthe When DCSencountersacriticalerror, the execution, clickthe When afatalerror isencountered, DCSallows execution terminationonly. To terminate command withatargetscriptthatdoesnotexistgeneratesfatalerror. button. ERROR OK button.
function canbeusedtotestfortheoccurrence error. ofarun-time OK Fatal TaskError button. To terminateexecution, clickthe Task Error OK button. To terminateexecution, clickthe dialog isdisplayed alongwith a brief dialogisdisplayed alongwithabrief Task Error dialogisdisplayed PERFORM Cancel - - 1 Introduction to the Script Language 83 command with levels and codes, displays slightly different dialogs and codes, displays slightly different command with levels commands are used to test for the occurrence of run time errors. to test for the occurrence used commands are
IF TASKERROR TASKERROR continued TABLE DEFINE 0 CHAR 10 CHAR 15 INT 8 FILE TABLE DEFINE CANCEL ‘Could not create table^M’, IF ERROR () DISPLAY ‘DATA.DCM’ AS TEXT TABLE LOAD 0 CANCEL ‘Could not load data^M’, IF ERROR () DISPLAY RECORD READ 0 Using the Using than those described above. command, the Example this example: In of the previous is dependent on the successful execution command since each successive Note: Task Errors, Task 84 DCS Script Language Reference have changed general, themajorityofscriptinglanguagesyntaxhasnotchanged.However, there are keyareas that DCS Asynchronous) mustbereviewed forcompatibilitywiththeDCSConnectivitySeries (DCS).In a version of theDCSScriptLanguagepriorto7.0(withsuchFutureSoft products asDCS/Elite or Scripts writtenwithDCS7.0or8.0(allversions) are compatiblewithDCS9.Scriptswritten Converting Scripts
Configuring Sessions Configuring Addressing Multiple Sessions FIG For sessiondisplayoptions GENERALCONFIG For generalsessionconfigurationoption, FIG For filetransferconfiguration FIG For connectorconfiguration FIG For emulationconfiguration selected inthe to theemulation,connector, orfiletransferprotocol. In mostcases,anyfeature which maybe have changed.Once thesehave beenset,you mayspecifyconfiguration optionsappropriate CONNECTION Specifying anemulation,connector, orfiletransferisstilldoneviathe configurationcommandsandfunctions. only withthenew featuresbut new andfunctionalityinallemulations,connectors,filetransfers mands toconfigure asession.Thesecommands are still available forbackward compatibility, Previous versions ofthescriptinglanguageused before writingscriptsdesignedtooperatesimultaneously. multiple sessionwindows are open. Be sure toread theProgramming Considerationssection Event timingmustbeexaminedcarefully, especiallyifmultiplescriptsare executing while You multiplescriptssimultaneouslywithintheDCSConnectivitySeries canrun (DCS). Multiple, Simultaneous Scripts current sessions. DCS Windows & Window Handles sectionbefore writingscriptswhichaffectmultiplecon many commandsandfunctionsmayusea Window Handle argument.Be sure toread the A scriptcanaddress andaffectmultiplesessions. To distinguishbetween andamongsessions, : function. function. function. function. Session Properties , and fromPreviousVersions ofDCS function. SET BINARYTRANSFERS , seethe
options, seethe options, options dialogmayalsobeconfigured viascript. DISPLAYCONFIG seethe , seethe seethe CONNCONFIG EMULCONFIG XFERCONFIG GENERALCONFIG commands,butsomeofthekeywords may SETTINGS command andthe command and command and command and function andthe command and SET EMULATION GETDISPLAYCON GETEMULCON GETCONNCON GETXFERCON SET are available GET com , - SET ------1 Introduction to the Script Language 85 command continued in this chapter, in this chapter, APPCONFIG in Chapter 3 for details. Menus Menus Menu and Toolbar Commands Toolbar and Menu can be configured via script. See See via script. can be configured function. and toolbars in Chapter 2 and , Menu and Toolbar Configuration Toolbar and , Menu GETAPPCONFIG GETAPPCONFIG Appendix B Additions and Deletions B Additions Appendix Application-level configuration options may be configured using the may be configured configuration options Application-level and addition, menus In Functions Menu Application Also see: Converting Scripts from Previous Versions of DCS, Versions from Previous Scripts Converting 86 DCS Script Language Reference 2 Functions
DCS 88 DCS Script Language Reference Functions in Alphabetical Order Note: ATTRIBUTES ACTIVE —A— DISKSPACE DIRECTORY (DIALOG) RADIOGROUP (DIALOG) MESSAGEBOX (DIALOG) LISTBOX (DIALOG) EDITTEXT (DIALOG) CHECKBOX DEFAULTSESSIONHANDLE DECRYPT (DDE) ADVISE DATE —D— CURSOR CONNECTRESULT CONNECTMESSAGE CONNECT CHR —C— BUFFER BXOR BOR BOOL BNOT BAND —B—
Commands orfunctionsflaggedwithanasteriskdonotapplytotheIBM TN3270emu lation.
*
*
Returns thetextfrom ascreen bufferfield. Returns thecontentsofspecifiededittextcontrol Returns thebitwiseexclusive ORofitsarguments Returns thecurrent forthespecifieddata working directory Indicates thata Returns thehandlenumberofactive window Indicates whichiteminthespecifiedlistbox isselected Returns the decrypted value of the specified encrypted string valueReturns ofthespecifiedencrypted thedecrypted Converts anumerictoitsANSIcharactervalueConverts Returns theconnectionstatewithremote system Converts anintegernumerictoitsbooleanvalueConverts Returns acurrent orderived dateasastring Indicates whichradiobuttoninagroup isselected file type vated a Returns thefileattributesofspecified Returns thebitwisecomplementofitsargument Returns thelastdialstatusofamodemsenttocomputer Returns thecurrent cursorposition Returns thehandleofscript’s defaultsessionwindow Displays amessagebox Returns thebitwiseORofitsarguments Returns thelastdialstatusofamodemsenttoDCS Returns thenumberofbytes free onthespecifieddrive Determines ifthespecifiedcheckbox ischecked Returns thebitwiseANDvalue ofitsarguments WHEN ADVISE DDE ADVISE command or UNADVISE messageacti - - 2 Functions 89 - continued Returns text from a screen field. a screen text from Returns Returns the extended field attributes of the specified field the extended field Returns Indicates whether an error occurred during script execution occurred whether an error Indicates Indicates if the end of the table has been reached if the end of the table Indicates Returns the length of the specified field Returns the field number of the specified field Returns of the speci the absolute position of the beginning Returns fied field options a string identifying general application Returns connector setting a string identifying current Returns the display settings of a session window Returns emulation setting a string identifying current Returns a string identifying general session options Returns a string associated with an INI entryReturns file transfer setting a string identifying current Returns the handle numbers of all child windows Returns is minimized whether a window Determines Returns the number of bytes in the specified file the number of bytes Returns specific characters in the specified string Replaces the field attributes of the specified string Returns and column row Determines whether the specified file exists whether the Determines Returns extended field attributes of the field at the specified extended field attributes of the field Returns Converts a numeric to an integer numeric Returns an encrypted the specified string of Returns equivalent Returns the number of characters in the specified string Returns
—H— HWNDLIST —I— ICONIC INT —L— LENGTH —G— GETAPPCONFIG GETCONNCONFIG GETDISPLAYCONFIG GETEMULCONFIG GETGENERALCONFIG GETPROFILEDATA GETXFERCONFIG FILESIZE FILTER FLDATTR FLDATTREXPOS FLDLEN FLDNUM FLDPOS FLDTEXT —E— ENCRYPT EOF ERROR EXISTS EXFLDATTR —F— Functions in Alphabetical Order, Order, Alphabetical in Functions 90 DCS Script Language Reference Functions in Alphabetical Order, —N— (MENU) ENABLED (MENU) CHECKED —M— SETTINGS SECONDS SEARCHINRECT SEARCH SCREEN —S— ROUTE ROUND REAL RESULT RANDOM —R— PUTPROFILEDATA PRTMETRICS POWER POSITION POS PHONENUMBER PASSWORD —P— ORD —O— NUM NEXT NETID
*
*
*
Returns thephonenumbersetby thecurrent Phone Book Returns thestateofadisabledorenabledmenuitem Returns thecurrent values ofthesettingsoptions Returns acurrent orderived dateandtimeasanumeric rectangular screen area inasessionwindow Returns thepositionofspecifiedstringina dow Returns thepositionofspecifiedstringinasessionwin Retrieves alineofscreen dataatthespecifiedposition Creates alistoffilesmatchingthespecifiedfile type Rounds areal numerictothespecifieddecimalplaces anumeric toarealConverts numeric Returns thecontentsofresult string Returns arandomnumber Creates orupdatesanINIentry Returns thecurrent printparameters Returns thebaseargumentraisedexponentially Returns thesize andpositionofthespecifiedwindow Returns thepositionofagiven stringinthespecified entry astringtoitsANSInumericvalueConverts astringtoitsnumericvalueConverts Returns thenextfilenamefrom thelistcreated by entry Returns thenetwork IDsetby thecurrent Phone Book Returns thestateofacheckedoruncheckedmenuitem Returns thepassword setby thecurrent Phone Bookentry continued ROUTE - 2 Functions 91 - - continued Returns the user ID set by the current Phone Book entry Phone the current the user ID set by Returns Converts a string to its uppercase equivalent Converts a string to its uppercase is hidden whether the specified window Indicates number DCS version the current Returns is a child of the DCS window if the window Indicates by name specified the handle of the DCS window Returns by specified the full name of the DCS window Returns handle type of the specified window the DCS window Indicates the disk name of the file associated with the speci Returns fied window the title of the specified window Returns is maximized whether the specified window Indicates Converts a numeric to a string a portion of the specified string Returns parameters system the current Returns a string time as or derived a current Returns the last timer reset the elapsed time since Returns the specified string string from a given Removes of a DLL func value a return a string representing Returns tion call Returns information about the current environment the current information about Returns
* * WNDTITLE —Z— ZOOMED VERSION —W— WINDOW WINDOWHND WINDOWNAME WNDCLASS WNDFILE TRIM TYPEDLIBRARYCALL —U— UPPER USERID —V— VISIBLE STR SUBSTR SYSMETRICS SYSTEM —T— TIME TIMER Functions in Alphabetical Order, Order, Alphabetical in Functions 92 DCS Script Language Reference Functions byCategory Note: BNOT BAND Boolean Functions SEARCHINRECT SEARCH SCREEN BUFFER Data SearchingandCapturingFunctions UPPER STR REAL ORD NUM INT CHR BOOL Conversion Functions GETXFERCONFIG GETGENERALCONFIG GETEMULCONFIG GETDISPLAYCONFIG GETCONNCONFIG GETAPPCONFIG Configuration Functions(Details) BXOR BOR BOOL
Commands orfunctionsflaggedwithanasteriskdonotapplytotheIBM TN3270emu lation.
Returns astringidentifyinggeneralapplicationoptions Returns astringidentifyingcurrent connector setting Returns astringidentifyingcurrent file transfersetting Returns thedisplaysettingsofasessionwindow Returns astringidentifyinggeneralsessionoptions Returns astringidentifyingcurrent emulation setting Returns thebitwiseANDvalue ofitsarguments Returns thepositionofspecifiedstringina Returns thebitwiseexclusive ORofitsarguments Converts astringtoitsnumericvalueConverts Returns thepositionofspecifiedstringinasession Retrieves alineofscreen dataatthespecifiedposition Converts astring toitsuppercaseConverts equivalent Converts anintegernumerictoitsbooleanvalueConverts Converts anumerictoitsANSIcharactervalueConverts rectangular screen area inasessionwindow window Returns thetextfrom ascreen bufferfield. Converts anumerictoaninteger Converts Converts astringtoitsANSInumericvalueConverts Converts anintegernumerictoitsbooleanvalueConverts Converts anumerictostring Converts Converts anumerictorealConverts numeric Returns thebitwisecomplementofitsargument Returns thebitwiseORofitsarguments - 2 Functions 93 - - - - ROUTE message acti UNADVISE or command DDE ADVISE WHEN ADVISE Determines if the specified check box is checked is check box if the specified Determines Returns a string representing a return value of a DLL func value a return a string representing Returns Returns the number of bytes free on the specified drive free the number of bytes Returns Returns text from a screen field. a screen text from Returns Returns the window handle of the specified dialog box handle of the specified the window Returns Returns the next file name from the list created by the list created the next file name from Returns Displays a message box Displays Returns the extended field attributes of the specified field the extended field attributes of the specified Returns Returns the number of bytes in the specified file the number of bytes Returns Returns the length of the specified field Returns the file attributes of the specified file Returns Creates a list of files matching the specified file type a list of files matching the specified Creates the disk name of the file associated with the speci Returns fied window row and column row fied field file type vated a vated tion call Determines whether the specified file exists Determines Indicates which radio button in a radio group is selected in a radio group which radio button Indicates Returns the absolute position of the beginning of the speci the absolute position of the beginning Returns Returns extended field attributes of the field at the specified extended field attributes of the field Returns Returns the field number of the specified field Returns Indicates which item in the specified list box is selected specified list box which item in the Indicates Returns the field attributes of the specified string Returns Indicates that a Indicates Returns the current working directory working specified data for the the current Returns Returns the contents of the specified edit text control the contents of the Returns continued
DISKSPACE EXISTS FILESIZE NEXT ROUTE WNDFILE FLDLEN FLDNUM FLDPOS FLDTEXT File Functions ATTRIBUTES DIRECTORY Dynamic Data Exchange Functions (DDE) ADVISE TYPEDLIBRARYCALL Field Functions EXFLDATTR FLDATTR FLDATTREXPOS Dialog Functions (DIALOG)HANDLE (DIALOG) CHECKBOX (DIALOG) EDITTEXT (DIALOG) LISTBOX (DIALOG) MESSAGEBOX (DIALOG) RADIOGROUP Functions by Category, by Category, Functions 94 DCS Script Language Reference Functions byCategory, BXOR BOR BNOT BAND Math Functions SETTINGS SECONDS RESULT PUTPROFILEDATA PRTMETRICS GETPROFILEDATA ERROR DATE CURSOR System Functions USERID UPPER TRIM SUBSTR POS PHONENUMBER PASSWORD NETID LENGTH FILTER ENCRYPT DECRYPT String Functions (MENU) ENABLED (MENU) CHECKED Menu Functions ROUND RANDOM POWER
*
*
*
*
continued Returns ofthespecifiedstring aportion Returns thenumberofcharactersinspecifiedstring Returns thepositionofagiven stringinthespecified Returns an encrypted equivalentReturns ofthespecifiedstring anencrypted string valueReturns ofthespecifiedencrypted thedecrypted Returns theuppercase equivalent ofthespecifiedstring Replaces specificcharactersinthespecifiedstring Returns thenetwork IDsetby thecurrent Phone Bookentry Returns thepassword setby thecurrent Phone Bookentry Removes agiven stringfrom thespecifiedstring Returns theuserIDsetby thecurrent Phone Bookentry Returns thephonenumbersetby thecurrent Phone Book Creates orupdates anINIentry Returns astringassociatedwithanINIentry Returns acurrent orderived dateandtimeasanumeric Returns acurrent orderived dateasastring Returns thestateofadisabledorenabledmenuitem entry Returns thestateofacheckedoruncheckedmenuitem Returns thecurrent cursorposition Returns thecurrent printparameters Indicates whetheranerror occurred duringscriptexecution Returns thecontentsofresult string Returns thecurrent values ofthesettings options Returns thebitwiseexclusive ORofitsarguments Rounds areal numerictothespecifieddecimalplaces Returns arandomnumber Returns thebaseargumentraisedexponentially Returns thebitwisecomplementofitsargument Returns thebitwiseORofitsarguments Returns thebitwiseANDvalue ofitsarguments 2 Functions 95 - Returns the size and position of the specified window the size Returns Returns the last dial status of a modem sent to DCS the last dial status of a modem sent to Returns Returns the full name of the DCS window specified by specified the full name of the DCS window Returns Returns the handle of the script’s default session window the handle of the script’s Returns Returns the last dial status of a modem sent to the computer the last dial status of a modem sent to Returns Indicates if the end of the table has been reached if the end of the table Indicates Returns the disk name of the file associated with the speci Returns Determines whether a window is minimized whether a window Determines handle fied window Returns the handle numbers of all child windows Returns Indicates if the window is a child of the DCS window if the window Indicates Returns the connection state with the remote system the connection state with the remote Returns Returns the current system parameters system the current Returns number version DCS the current Returns Indicates whether the specified window is hidden whether the specified window Indicates Returns a string identifying current connector setting a string identifying current Returns is maximized whether the specified window Indicates Returns a current or derived time as a string time as or derived a current Returns Returns the handle of the DCS window specified by name specified the handle of the DCS window Returns Returns the title of the specified window Returns Returns the elapsed time since the last timer reset the elapsed time since Returns Indicates the DCS window type of the specified window the DCS window Indicates Returns information about the current environment the current information about Returns window the handle number of the active Returns continued
*
*
*
WNDFILE WNDTITLE ZOOMED HWNDLIST ICONIC POSITION VISIBLE WINDOW WINDOWHND WINDOWNAME WNDCLASS Telecommunications Functions Telecommunications CONNECT CONNECTMESSAGE CONNECTRESULT GETCONNCONFIG Functions Window ACTIVE DEFAULTSESSIONHANDLE SYSMETRICS SYSTEM TIME TIMER VERSION Functions Table EOF Functions by Category, by Category, Functions 96 DCS Script Language Reference ACTIVE The ACTIVE () ACTIVE Arguments Example Comments Result The window handle. can thenbeusedasawindow handleparameter foranycommandorfunctionthatcallsa the variable In thisexample: script window). mands andfunctionsrequire thewindow handleofasessionwindow (ratherthanamemoor While the window isopen,theresult is0(zero). The result isanintegerexpression specifyingthehandleofactive childwindow. If nochild ACTIVE function returns thewindow handle %WindowHND =ACTIVE() ACTIVE %WindowHND function takesnoarguments. function returns thewindow handle ofanyDCSchildwindow, mostcom containsthewindow handleoftheactive window. The variable numberoftheactive childwindow. - 2 Functions 97 - - AT argument ATTRIBUTES ATTRIBUTES function. If function. If FileName . ATTRIBUTES ATTRIBUTES returns TRUE and the and the TRUE returns drive) has the attributes Read-Only, has the attributes Read-Only, drive) %attrib C: function assumes the value 32. assumes the value of the specified file. argument for the ERROR %attrib FileName Compressed File Read-Only File Hidden File System File Subdirectory Archived File function obtains the path of the default location for session files, which is an archived file, is an archived argument is a string specifying the name of a file. The argument is a string (located in the root directory (located in the root of the function assigns the sum to the variable function assigns the sum to the variable function returns the file attributes the function returns $PATH = DIRECTORY (SETTINGS) %attrib = ATTRIBUTES ($PATH | “fsebbs.ses”) 64 %attrib = ATTRIBUTES (“C:\MSDOS.SYS”) Value Value 1 File Attribute 2 4 16 32 FileName DIRECTORY DIRECTORY Hidden File and System File. The sum of the values of these attributes is 7 (1+2+4). The The sum of the File. and System File Hidden TRIBUTES this example: In the is then included as a part of the fsebbs.ses If the specified file does not exist, the If one). -1 (negative function returns this example: In MSDOS.SYS If the file exists, the result is an integer which is the sum of the values of its attributes. File at values of its attributes. is the sum of the result is an integer which the file exists, the If numeric values: the following tributes have FileName The your system. for file name must specify a valid Comments Example Arguments Result ATTRIBUTES ATTRIBUTES ATTRIBUTES (FileName) ATTRIBUTES The ATTRIBUTES 98 DCS Script Language Reference BAND The BAND (Source,Mask) BAND Arguments Example Comments Result Source turned off). contents of which usesthehexadecimalrepresentation 0xFFFFFFFE asamask, In thisexample: The used. unmodified. Any representation ofthenumber(binary, decimal,octal,orhexadecimal) canbe Use a fied by the The result isanintegerequivalent tothe The Mask The function performs abitwise function performs BAND Mask Source Mask %result =BAND(%source,0xFFFFFFFE) Mask Result Source 1 1 0 1 10 0 0 0 argument isanintegerexpression. Mask function returns a32-bitvalue. %source argument containingazero foreachbittoturnoffandaoneleave argument isanintegerexpression. argument: , buttheleastsignificantbitin AND operation onthe Source argument, butwithbitsturnedoffasspeci %result Source argument. willbe0(zero -thebitis %result containsthe - 2 Functions 99 - origi %source argument: variable. If If variable. (binary binary become ones, zeroes Numeric %source assumes the value 0xFFFFFF00 after DCS assumes the value %result function. argument is an integer expression. argument is an integer BNOT BNOT function returns a 32-bit value. function returns function returns the complement of the the complement of the function returns 0 -1 1 -2 %result = BNOT (%source) BNOT Result BNOT BNOT Numeric BNOT BNOT function performs a bitwise complement operation In this example: In the 0x000000FF, nally contains the value performs the The result is an integer that is the complement of the The The Numeric The Comments Example Arguments Result BNOT BNOT BNOT (Numeric) The on its argument. ones become zeroes) BNOT 100 DCS Script Language Reference BOOL The BOOL (Integer) BOOL Arguments Example Result Integer value TRUE. If theintegervariable FALSE. if theintegervariable In thisexample: (zero), theresult isFALSE; theresult is otherwise TRUE. The result isaBoolean value corresponding tothe The function returns aBooleanvalue Integer #nonzero =BOOL(%product) argument specifiestheinteger value toconvert. %product %product hasavalue of0(zero), hasavalue otherthan0(zero), corresponding toaspecifiedinteger. Integer #nonzero argument. If theintegerequals0 #nonzero assumesthevalue assumesthe 2 Functions 101 will contain the contents of argument. %result argument, but with bits turned on as will be 1 (one - the bit is turned on). Source Source %result operation on the OR argument: Mask argument is an integer expression. argument is an integer argument containing a 1 (one) for each bit to turn on and a 0 (zero) for each bit for each to turn on and a 0 (zero) argument containing a 1 (one) for each bit , but the least significant bit in argument is an integer expression. argument is an integer function returns a 32-bit value. function returns 1 1 1 0 0 0 0 1 1 1 0 1 %result = BOR (%source, 0x00000001) Source Mask Result Mask BOR Mask Source function performs a bitwise using the binary representation 0x00000001 as a mask, using the binary representation %source Use a Use decimal, octal, or of the number (binary, representation You may use any unmodified. to leave hexadecimal). The this example: In The to the value equivalent result is an integer The by the specified Source The Mask Comments Example Result Arguments BOR BOR (Source, Mask) BOR (Source, The BOR 102 DCS Script Language Reference BUFFER buffer. Thisfunction retrieves thetext even whenthefieldishidden. The BUFFER (Row,
BUFFER Arguments perform asexpected. perform include the If you usethe remainder ofthelineiscollected. data. If the The optional Length default columnoffsetof zero isassumed. data. Thefirstcolumnisconsidered column zero. If the The optional Column and bottomstatuslinesby using thefollowing integersinthe For thoseemulationswhichdisplaydatainastatusline,thecanbecaptured from thetop considered row zero. The Row This functionappliesonlyto3270or5250emulations. but not or Row BUFFER (1,,5) BUFFER (1,3) BUFFER (1,3,5,0x4BD3) Integer Status Line function retrieves ofalinedataatthespecifiedpositioninscreen alineorportion Bottom -2 Top -1 argument isanintegerspecifyingtherow numberofthedesired data.Thefirst row is Column Length Column Length Column Length argument isnotincluded,orif , argument, thescriptwillcompile,but argument isanumericspecifyingthelength(incharacters)ofdesired Length argument, you mustalsoincludethe argument isanintegerspecifyingthecolumnnumberofdesired
, WinHandle (incorrect usage) (Row &Columnargumentsonly) (Row, Column,Length,& WinHandle arguments) ) Length Column exceeds thelengthofline, Column Row BUFFER argument isnotincluded,a argument: argument. If you donot function maynot 2 Functions 103 argument is not valid. WinHandle WinHandle assumes the string value of seven characters of buffer data, starting of seven assumes the string value argument is an integer specifying a particular window in DCS. The specifying a particularargument is an integer window assumes the string value of the first line of data in the buffer. assumes the string value argument is not included in this function, DCS uses the window handle of DCS uses the window argument is not included in this function, $chars $T function returns TRUE if the TRUE function returns WinHandle WinHandle $chars = BUFFER (1,3,7) $T = BUFFER (0) WinHandle WinHandle ERROR continued the string variable the string variable and fourth column. at the second row If the If session window. the active The this example: In the string variable this example: In WinHandle The optional a particular a string from session in DCS to retrieve a script allows inclusion of this argument of DCS. window area. the specified containing the buffer data within value a string result is The Examples Result Comments BUFFER, BUFFER, 104 DCS Script Language Reference BXOR The BXOR (Source,Mask) BXOR Arguments Example Comments Result Source The result contains0x00F(hexadecimal) or15(decimal). the variable In thisexample: octal, orhexadecimal)canbeused. The is theinteger1(one): (zero); ifoneoftheargumentscontainsazero bit,andtheothercontainsaoneresult If boththe The Mask The function performs abitwise function performs BXOR Mask Source %result =BXOR(0x005,0x00A) Mask Result Source 10 1 01 1 1 0 0 0 argument isanintegerexpression. Source function returns a32-bitvalue. Anyrepresentation ofthenumber(binary, decimal, %result argument isanintegerexpression. and containsanintegerwhere thefourleastsignificantbits become ones. Mask arguments containtheidenticalbit,result istheinteger0 exclusive ORoperation onthe Source argument. 2 Functions 105 - , see the function returns the function returns CHR argument. argument. Numeric Numeric command then sends the string, followed by a by command then sends the string, followed SEND assumes the value A. assumes the value argument by 256 and uses the remainder (the modulus) as the numeric (the modulus) as the remainder 256 and uses the argument by $letter function returns the Escape character, and the second the Escape character, function returns argument is the value to be converted. If the value is greater than 255, DCS than 255, is greater the value to be converted. If argument is the value For more information on numeric representations of ASCII characters of ASCII on numeric representations information more For Reference. section in the DCS 9 Online “Character Sets” Numeric function returns the delete character (the character the [DELETE] key sends), and the delete character (the function returns command replaces the character the [BACKSPACE] key sends with the delete char key sends with the character the [BACKSPACE] command replaces CHR SEND CHR (27) | CHR (43) $letter = CHR (65) KEY Back CHR (127) Tip: Numeric CHR KEY function returns the string representation of its string representation the function returns The first concatenated (joined) together into a string Plus characters are The Escape and character. Plus with the concatenation operator (|). The system. to a remote character, carriage return the string variable the string variable this example: In the the acter. this example: In The result is the ASCII representation of the value of the of the representation result is the ASCII The this example: In Numeric The divides the value. Result Comments Example Arguments CHR CHR (Numeric) The CHR 106 DCS Script Language Reference CHR, continued In thisexample: decimal 0A). in thesessionwindow, followed by acarriagereturn (hexadecimal0D)andalinefeed(hexa These commandsshow aloopthatdisplaystheuppercase alphabet(from hexadecimal values) DISPLAY CHR(0x0D)|(0x0A) END WHILE %index<=0x5A %index =0x41 BEGIN INCREMENT %index DISPLAY CHR(%index) - 2 Functions 107 - of function always returns function always returns argument is not valid. CONNECT CONNECT WinHandle returns FALSE and control branches to the line and control FALSE returns CONNECT CONNECT , where TRUE indicates that the session connection is active and connection is active indicates that the session TRUE , where returns TRUE if the TRUE returns . By using this function to check for an active connection, the script can this function to check for an active using . By argument is not included in this function, DCS uses the window handle DCS uses the window argument is not included in this function, function long as a port is found. With the ComTAPI (Modem) connector, there will be a there connector, (Modem) the ComTAPI With long as a port is found. delay. a connection. whether or not the session has established TRUE, DCS waits until a connection is made before returning a value. When the Com a value. returning DCS waits until a connection is made before almost immediately as is returned connector is used, the result (Serial) Direct If you are connected to a COM port, the are you If function are followed by parentheses (even if empty). (even parentheses by followed function are
function indicates whether a session is connected. function indicates whether the_end Note: IF NOT CONNECT () GOTO the_end Note: WinHandle ERROR labeled a host connection. of commands which require the execution prevent In this example: In if no connection is detected, If the If session window. the active The all uses of the DCS, make sure of version compiling a script written for a previous are you If CONNECT This function requires no arguments. requires This function value a Boolean result is The is not active. indicates that the session connection FALSE Example Comments Arguments Result CONNECT CONNECT CONNECT ( ) CONNECT The CONNECT 108 DCS Script Language Reference CONNECTMESSAGE The CONNECTMESSAGE () CONNECTMESSAGE Arguments Example Comments Result Note: This function requires noarguments. active sessionwindow. if thelastmodemdialstatusmessageis In thisexample: Compare withthe The result isastring representing thecurrent value oftheConnectMessage system variable This functiondoesnotapplytotheIBM TN3270emulation. DISPLAY “awshucks” IF CONNECTMESSAGE()=“BUSY” SET CONNECTMESSAGE function returns thecurrent value oftheConnectMessage system BUSY , DCSdisplaysthetext“ command. aw shucks ” inthe variable. . 2 Functions 109
- . “We are there!” command. command for a list of possible result values. command for a list of possible result
is an integer identifying a particular DCS session window. a particular is an integer identifying DCS session window. ) argument SET CONNECTRESULT SET function returns the current value of the ConnectResult system variable of the ConnectResult value current the function returns
WinHandle SET CONNECTRESULT SET WinHandle WinHandle CONNECTRESULT () = 0 IF DISPLAY “We are there!” This function does not apply to the IBM TN3270 emulation. not apply to the IBM This function does Also see: n this example: I in the active session window. in the active if the last modem dial status number is 0 (zero), DCS displays the text (zero), if the last modem dial status number is 0 lar session. variable. system value of the ConnectResult the current representing result is an integer The with the Compare WinHandle The optional of a particuscript in DCS to check the status message a argument allows The inclusion of this Note: Result Comments Example Arguments CONNECTRESULT CONNECTRESULT ( CONNECTRESULT The CONNECTRESULT 110 DCS Script Language Reference CURSOR The CURSOR ( CURSOR Arguments Example Comments Result WinHandle ( above, asfollows: (1*80)+4=84.Thenexttwolinesdecodethe width is80,thevariable if thecursorisonsecondline(row one)atthefifthcolumn(columnfour),and In thisexample: with theremote systemusingthesession’s mousesettings. can usethemousecursortodeterminewhere you are makingaselection,andyou caninteract Windows desktop(suchasotherwindows orotherapplications). In thesessionwindow, you is thelocalmousecursor. Thiscursorshows where your mouseispresently pointingonthe window isdeterminedby theremote systemto whichDCSisconnected.Thesecondcursor Session windows displaytwocursors.One cursoristhehostcursor. Its positioninthesession The the active childwindow. If the The first row is row 0 (zero) andthefirstcolumnis0 (zero). The result isaninteger, calculatedusingthefollowing formula: window.cursor inaparticular dow The optional %row (row *columnwidth)+ . Theinclusionofthisargumentallows ascriptinDCSto find thepositionofhost ERROR WinHandle WinHandle %column =%pos%80 %row =%pos/80 %pos =cursor() =1)andcolumn( function returns thehostcursorposition WinHandle function ) argument isnotincludedinthisfunction,DCSusesthewindow handlefor returns TRUE ifthe %pos %column argument is an integer that identifies a particular DCSchildwin argument isanintegerthatidentifiesaparticular assumesthevalue 84.This value isderived usingtheformula =4). WinHandle inawindow’s work space. argument isnotvalid. %pos variable intotherow - 2 Functions 111
argument, and Seconds might assume the string value argument, DCS returns the current system the current argument, DCS returns $date and is formatted according to the format you format you to the and is formatted according Seconds function argument is an integer specifying a number of seconds. DCS uses specifying a number of seconds. DCS argument is an integer SECONDS Seconds ) $date = DATE () Also see: function returns a date string, formatted according to the date format you have chosen via have the date format you to string, formatted according a date function returns month/day/year Seconds In this example: In 3, 2001, machine date is November if the current system configuration). 11/03/2001 (depending on your returns a date. If you do not include the do not you If a date. returns date. result is a string which specifies a date The the following example, the date might have For Panel. Control Windows selected in the have format: Seconds The optional adds the seconds), 1, 1904 as a base (or zero 12:00:00 A.M. January Result Example Arguments DATE DATE DATE ( DATE The Panel. Control Windows the DATE 112 DCS Script Language Reference (DDE) ADVISE (DDE) command wasactivated inresponse toanadvisemessageorunadvisemessage. The ADVISE () (DDE) ADVISE Arguments Example Result The returns FALSE, control branchestothelinelabeled If In thisexample: FALSE indicatesanunadvisemessagewasreceived. The result isaBoolean value ADVISE
(DDE) ADVISE *unadvisesub . . *advisesub . . END PERFORM unadvisesub ELSE PERFORM advisesub IF ADVISE() BEGIN WHEN ADVISE0“item0” returns TRUE, control branchestothelinelabeled functionindicateswhetherthemostrecently activated functiontakesnoarguments. where TRUE indicatesanadvisemessage *unadvisesub *advisesub (DDE) WHEN ADVISE (DDE) wasreceived and . . If ADVISE
2 Functions 113 - func function. ENCRYPT ENCRYPT ENCRYPT ENCRYPT ENCRYPT ENCRYPT . EncryptedString function argument contains the string produced by the by string produced argument contains the ENCRYPT ENCRYPT argument is a string containing the same string used as a key by the string used as a key by argument is a string containing the same function returns the original characters of a string encrypted the function returns with the Table Save 0 To “C:\Balnc\” | $filename as Text ;Saves names and balances to a file . . . Table Define 0 Fields Char 64 Char 48 Table Define 0 Fields Char . . . @R0.1 = $Name @R0.2 = Encrypt ($Balance, $Key) Record Write 0 ;Begins a loop to gather names and balances Also see: Key EncryptedString In this example: In The the string contained in tion to produce original string. value containing the result is a string The The encryption encrypted an scheme in DCS can produce fcantly string which contains signi characters than the original string. more EncryptedString The Key Example Result Comments Arguments DECRYPT DECRYPT DECRYPT (EncryptedString, Key) (EncryptedString, DECRYPT The function. DECRYPT 114 DCS Script Language Reference DECRYPT, decrypt the encrypted string.The theencrypted decrypt the scriptmustdeleteanyspacesfrom theendoffieldbefore the However, string), sincethesecondfieldislargerthan theoriginalstring(orthanencrypted Later, thescriptreads arecord thesecondfieldof record. from thetableanddecrypts about three orfourtimeslargerthanthenumberofcharactersinoriginalstring. string intothesecondfieldofa record. Thenumberofcharactersallowed inthesecondfieldis thecontentof The scriptencrypts looping structures. on usingthecontentsofafieldand sensitive information issaved inthesecondfieldofastructured table.Theexamplefocuses Note: . . . Wait Delay“5” Dialog End Message Decrypt(Trim(@R0.2,,”“),$Key) Message @R0.1 Dialog ;Begins alooptodisplaynamesandbalances Record Read0 continued
If thescriptdoesnotallow enoughcharacterpositions inafieldforallofthe DCS will not decrypt thestring. DCS willnotdecrypt into thefield. If charactersare discarded string, from, oraddedto,anencrypted string,DCSdiscards thecharactersthatcannotfit characters intheencrypted TRIM $Balance DECRYPT function removes theextraspaces. variable and then places the encrypted variable andthenplacestheencrypted function and,therefore, doesnotcontain DECRYPT function will 2 Functions 115 of the command section for more information about the default information about the section for more function takes no arguments. handle of the default integer window the function returns function returns an integer identifying the window handle integer identifying the window an function returns Windows & Window Handles Window & Windows session window. DEFAULTSESSIONHANDLE SET %SessionHandle = DefaultSessionHandle () %SessionHandle = DefaultSessionHandle Also see: DEFAULTSESSIONHANDLE DEFAULTSESSIONHANDLE
session window for this script. If no default session handle is defined, a -1 (negative one) is a -1 (negative no default session handle is defined, for this script. If session window returned. The The Comments Example Arguments Result DEFAULTSESSIONHANDLE DEFAULTSESSIONHANDLE () DEFAULTSESSIONHANDLE The default session window. DEFAULTSESSIONHANDLE 116 DCS Script Language Reference (DIALOG) CHECKBOX abled) checkbox inthedialog. The CHECKBOX ( (DIALOG) CHECKBOX Arguments Example Comments Result ControlNum read_file Ifdetermine whichsubroutine thethird toperform. checkbox inthedialogischecked, These commands: function isinvalid. (DIALOG) CHECKBOX This function returns invalid results ifthe (negative one). and 0(zero) indicatesunchecked.If thecheckbox control isinvalid, thisfunctionreturns -1 The result isanumeric value, where 1(one)indicatesthatthecheckbox control ischecked of zero isused. contains thecheckbox totest. If the The optional DialogIndex ists inthedialog,useof box, where The optional Also see: PERFORM write_file ELSE PERFORM read_file IF CHECKBOX(3)=1 ControlNum, DialogIndex n is performed. If itisunchecked, isperformed. isthenumberofcheckbox controls inthedialogbox. If onlyonecheckbox ex DialogIndex ControlNum (DIALOG) CHECKBOX functionisusedwiththe function.Thatis,ifthedialogbox nolongerexists,the result ofthis
argument isaninteger(from 0to15)indicatethedialogthat argument containsavalue, from 1to ControlNum DialogIndex ) command
DIALOG CANCEL argument isnotrequired. write_file DIALOG argument isnotincluded,thedefaultvalue command toindicateaselected(en isperformed. commandisexecuted before the n , toidentifyaspecificcheck - - 2 Functions 117 - - - DialogIn ) specifying an edit text control, control, ) specifying an edit text n argument is not included, command. It returns the current con the current returns command. It argument is not required. DIALOG DialogIndex command ) ControlNum assumes the value of the characters in the second edit text assumes the value command). That is, if the dialog box no longer exists, the result no longer exists, the command). That is, if the dialog box argument is a value (from 1 to (from argument is a value argument is an integer (from 0 to 15) that indicates the dialog that 0 to 15) that indicates the dialog argument is an integer (from
function returns a result only while the dialog box is still active is still active only while the dialog box a result function returns function is used with the function is used with
$answer_2 (DIALOG) EDITTEXT DialogIndex ControlNum DIALOG CANCEL is the number of edit text controls in the dialog box. If only one edit text control ex only one edit text control If the dialog box. in text controls is the number of edit n ControlNum, DialogIndex ControlNum, $answer_2 = EDITTEXT (2) defaults to zero (0). defaults to zero Also see: (DIALOG) EDITTEXT the string variable the string variable control. The (prior to a of this function is invalid. this example: In ists in the dialog, inclusion of the ists in the dialog, inclusion DialogIndex The optional the to test. If contains the edit text control dex If contents of the specified edit text control. current value containing the result is a string The a null string. result is does not exist, the the specified edit text control ControlNum The optional where Example Result Comments Arguments (DIALOG) EDITTEXT EDITTEXT ( EDITTEXT The edit text control. tents of the specified (DIALOG) EDITTEXT (DIALOG) 118 DCS Script Language Reference (DIALOG) LISTBOX LISTBOX ( Arguments Example Comments Result ControlNum box itemis selected. The command toretrieve thedatastored inrecord two. the value 2(records are numbered from 0to if thethird iteminthe specified listbox hasbeenselected, thenumeric variable In thisexample the result ofthisfunctionisinvalid. active (priortothe The not existisspecified,the result isalso-1(negative one). box item.If noitemisselected,theresult is-1(negative one).If alistbox control thatdoes The result isanintegernumeric value corresponding tothe record numberoftheselectedlist default contains thelistbox totest.If you donotincludethe The optional DialogIndex ment ifthere isonlyonelistbox inthedialogbox. the numberoflistboxes inthedialogbox. You donotneedtoincludethe The optional
(DIALOG) LISTBOX (DIALOG) LISTBOX Also see: ControlNum, DialogIndex RECORD READ0AT%1 IF (%1<>-1) %1 =LISTBOX(1) DialogIndex DialogIndex ControlNum (DIALOG) LISTBOX
DIALOG CANCEL value ofzero (0). functionisusedwiththe functionreturns aresult onlywhilethespecifieddialogbox isstill argument isaninteger(from 0to15)indicatingwhichdialog argument isavalue (from 1to ) command command).Thatis,ifthedialogbox nolongerexists, n ‑ 1).DCScanthenexecute a DIALOG DialogIndex n ) specifyingalistbox, where command toindicatewhichlist argument, DCSusesthe ControlNum
RECORD READ %1 assumes n argu is
- 2 Functions 119 dialog box in the specified style with the supplied in the specified style dialog box 1 3 4 5 32 48 64 16 Style Value argument is a string variable containing the message to be displayed in the the message to be displayed containing variable argument is a string function displays a message argument is an integer value that describes the style of the message dialog box. The that describes the style of the message dialog box. argument is an integer value argument is a string variable containing the title to be displayed in the title bar of the in the title containing the title to be displayed argument is a string variable QUESTION ICON ICON WARNING ICON INFORMATION Description OK 0 OK - CANCEL - IGNORE – RETRY ABORT YES – NO - CANCEL 2 YES - NO - CANCEL RETRY – ERROR ICON STOP Title Title Style Message the Message. dialog box. Title The dialog box. Style The can be added together to be used in combination. values defined values define the text and number of buttons to display below first six the the table below, In left of to the values define the ICON symbol that will be displayed The last four the Message. Message The Arguments MESSAGEBOX MESSAGEBOX (Message, Title, Style) Title, (Message, MESSAGEBOX The (depending on the selected for the selected user action the integer value returns title and message and style). (DIALOG) MESSAGEBOX (DIALOG) 120 DCS Script Language Reference (DIALOG) MESSAGEBOX, Return values Results Examples Comments is usedtodeterminetheactionbetaken. The result isaninteger value corresponding tothestylebuttonselected by theuser. This value CANCEL “ displays amessagedialogwiththe This example: ICON isdisplayed. as the displays aMessage dialogwiththe This example: The Test Message2 ERROR If %ret=2GOTOCANCEL_Process If %ret=1GOTOOK_Process ICON”, 17) %ret =messagebox(“TestMessage2”,“2 ButtonBoxwith If %ret=2GOTOCANCEL_Process If %ret=7GOTONO_Process If %ret=6GOTOYES_Process %ret =messagebox(“TestMessage”,“3ButtonBox”,3) ReturnValue Description Message NO 7 YES IGNORE RETRY ABORT CANCEL 2 OK 1 , andtheSTOP/ERROR ICONisdisplayed. function issetto TRUE ifthemessagebox cannotbedisplayed foranyreason. text, three buttonsbelow themessagelabeled ” asthemessagetext,twobuttonsbelow themessagelabeled 6 5 4 3
continued Title Title
set to“ set to“3Button Box”, the 2 ButtonBoxwithICON YES String , NO and “ Test Message CANCEL ”, the OK String , andno and ” 2 Functions 121
- n
%rad2 ControlNum argument, DCS
DialogIndex command. It indicates which radio command. It ) specifying a radio group, where where ) specifying a radio group, n DIALOG command). That is, if the dialog box no longer command). That is, if the dialog box ) command function retrieves a result only while the specified dialog box only while the specified dialog box a result function retrieves value of zero. value
DialogIndex , argument is a value (from 1 to (from argument is a value argument is an integer (from 0 to 15) indicating which dialog con 0 to 15) indicating which dialog argument is an integer (from
DIALOG CANCEL function is used with the function is used with DialogIndex (DIALOG) RADIOGROUP DialogIndex ControlNum ControlNum %rad2 = RADIOGROUP (2) Also see: (DIALOG) RADIOGROUP if the third radio button in radio group two has been selected, the numeric variable two has been selected, the numeric variable group radio button in radio if the third 3. assumes the value The (prior to the is still active of this function is invalid. exists, the result this example: In argument if there is only one radio group in the dialog box. only one radio group is argument if there DialogIndex The optional do not include the you want to test. If you tains the radio group uses the default to the number of the selected radio value corresponding result is an integer numeric The group does not exist, this function If the specified radio button in the specified radio group. one). -1(negative returns ControlNum The optional do not need to include the You in the dialog box. groups is the number of radio Comments Example Result Arguments (DIALOG) RADIOGROUP RADIOGROUP ( RADIOGROUP The selected. is radio group button in the specified (DIALOG) RADIOGROUP (DIALOG) 122 DCS Script Language Reference DIALOGHANDLE The DIALOGHANDLE ( DIALOGHANDLE Arguments Comments Results Index If thewindow handlecannotbereturned, the result isawindow handleofzero (0). The result isanintegerspecifyingthewindow handleof thewindow. If anerror occurs,the (0) willbeusedifnoindexisprovided. The optional Index Index function returns thewindow handleofthespecifieddialogbox. argument is an integer (0 to 15) identifying a particular dialogbox. Zeroargument isaninteger(0to15)identifyingaparticular ) ERROR function issetto TRUE . 2 Functions 123
- - - - com tab of the SET DIRECTORY SET C:\PROGRAM FILES\FU SET DIRECTORY SET File Locations File for the specified type of file. for the specified type Default Path* tab. C:\PROGRAM FILES\FUTURESOFT …MEMOS\ …SESSION\ …UPLOAD\ dialog. directory Default Path Options Options ). Also, each time DCS executes a ). Also, each time DCS executes File Locations File tab of the Options > Tools Tools File Locations File C:\WINNT\PROFILES\username\PERSONAL\… function returns the path of default the function returns argument is one of the following keywords: keywords: following argument is one of the dialog ( Keyword WINDOWS Directory Windows WINSYS Main directory System directory C:\WINDOWS\ C:\WINDOWS\SYSTEM\ or C:\WINNT\System32 DNLOAD DYNASYS Download directory Executables/DLLs directory ICONPATH FILES\FUTURESOFT\DCSERIES C:\PROGRAM Icon files directory MEMO …DNLOAD\ SCRIPT Memo directory SETTINGS Script-text directory Settings directory TASK TRACEPATH files directory Trace …SCRIPTS\ Compiled script directory UPLOAD …SCRIPTS\ Upload directory …TRACE\ Keyword Directory DCS Type Type command or change them in the The result is a string value containing the current default directory for the type of file as de value containing the current result is a string The fined in the in The default directory for a file type is originally specified during installation and is stored values can be viewed and set using the These registry. Windows the Options mand, DCS changes the default directory for a file type to the specified directory. WIN DYNASYS, found with the does not apply to the directories The comment above cannot change these paths with the You keywords. WINSYS and DOWS, *The default path for WIN95/98 users on all directories begins with WIN95/98 users on all directories *The default path for TURESOFT\DCSERIES\… DYNASYSE and ICONPATH) (except WIN/NT users on all directories *The default path for begins with Type The Result Comments Arguments DIRECTORY DIRECTORY DIRECTORY (Type) DIRECTORY The DIRECTORY 124 DCS Script Language Reference DIRECTORY, Example PROGRAM FILES\FUTURESOFT\DCSERIES\MEMOS ondrive C:, if amemowaslastopenedinthedefaultMEMOdirectory In thisexample: $path =DIRECTORY(MEMO) continued . $path contains C:\ 2 Functions 125 argument must specify a valid drive for your system. If the drive is not the drive If system. for your drive a valid argument must specify argument is a string specifying the desired drive (the trailing colon is drive specifying the desired argument is a string function returns the number of bytes free on the specified drive. free number of bytes the function returns ) Drive Drive Drive %free = DISKSPACE (“C:”) DISKSPACE DISKSPACE The result is an integer value indicating the number of bytes of free storage on the specified of free bytes number of value indicating the result is an integer The drive. The Drive The optional optional). The drive. working is the current specified, the default Result Example Arguments DISKSPACE ( DISKSPACE DISKSPACE 126 DCS Script Language Reference ENCRYPT The ENCRYPT (OrigString,Key) ENCRYPT Arguments Example Comments Result OrigString is given tothe DISPLAY key.is theencryption The first string containedin the In theexamplebelow: thestringto tion keyusedtoencrypt To decodetheresult ofthisfunction,you mustprovide stringandtheencryp theencrypted characters thantheoriginalstring. stringwhichmighthave significantlymore schemeproduces anencrypted The encryption The result isastring variable containingtheencoded version oftheoriginalstring. The Key The ENCRYPT Key OrigString Also see: DISPLAY (1,0)DECRYPT($save,“secret”) DISPLAY (0,0)$save $save =ENCRYPT(“ArnoldWilson”,“secret”) function encodes a specified string using a specified encryption key.function encodesaspecifiedstringusingencryption argument is a string which the function will use as an encryption key.argument isastringwhichthefunctionwilluseasanencryption command displaysthestring DECRYPT function encodesthecontentsofstring DECRYPT argument containsthestringtoencode. $save function. function willbearnoresemblance totheoriginalstring.Thestringsecret DISPLAY Arnold Wilson command displays the encrypted string.Thesecond command displaystheencrypted DECRYPT function. Arnold Wilson , since the correct encryption key , sincethecorrect encryption , suchthatthe - 2 Functions 127 - - com END function returns TRUE, then the result of then the result TRUE, function returns EOF command to indicate whether the script has at command to indicate RECORD READ evaluates to TRUE. Execution then branches past the Execution TRUE. to evaluates is displayed in the session window. is displayed EOF Done function takes no arguments. End Display “Done” Record Read 1 at 0 While not EOF() Begin Display @R1 Record Read 1 EOF function is used with the function is used with DCS attempts to read the contents of table one. Each record is displayed as it is read. If the If as it is read. is displayed one. Each record the contents of table DCS attempts to read reached, end of file is mand, and the text FALSE indicates the read was successful. If the was successful. If indicates the read FALSE will not be valid. a read this example: In The and the end of the table has been passed, indicates TRUE value, where a Boolean result is The Example Arguments Result EOF EOF ( ) The the end of a table. past tempted to read EOF 128 DCS Script Language Reference ERROR The ERROR () ERROR Arguments Example Result The copy operationsucceedsandthescriptisterminated. bak DCS attemptstocopyafile. If DCSisunabletocopy In thisexample: ecution, andFALSE indicatesthatanerror didnotoccurduringscriptexecution. The result isaBoolean value, where TRUE indicatesthatanerror occurred duringscriptex ERROR Also see: , the function indicateswhetheranerror occurred duringscriptexecution. End Cancel Display (0,0)“Unabletocopyfile” Begin If Error() File Copy“c:\config.sys”to“c:\config.bak” ERROR function takesnoarguments. RESULT function returns TRUE andanerror the messageisdisplayed. Otherwise, function c:\config.sys to c:\config. - 2 Functions 129 - - - . The integer is BXOR , and BOR , function. BNOT , FLDNUM BAND ) argument is an integer and identifies a window in DCS. This argu window argument is an integer and identifies a WinHandle function indifies the normal and extended field attributes for a field. normal and extended field attributes for function indifies the argument is an integer and identifies a field in a session window. For informa and identifies a field in a session window. argument is an integer WinHandle WinHandle function is only valid with IBM TN3270, IBM TN5250 or Tandem 6530 emulator Tandem TN5250 or TN3270, IBM with IBM function is only valid 0 = normal (keyboard) 1 = upshift 2 AID = AID) Any device (keyboard, 4 = 6 = reserved 0 = Free entry 1 = Alpha 2 = Numeric 3 = Aphanumeric 4 = Full numeric 5 = Full numeric w/space Alpha w/space 6 = Alpha numeric w/space 7 = bit 7 - Protected/Unprotected (1 = protected) bits 3 - 4 - extended data type bit 6 - uses enhanced color (1 = on) bits 0 - 2 - entry type EXFLDATTR EXFLDATTR FieldNum WinHandle The optional the field in a particular a script to check the attributes of a session, not merely ment allows session window. active into the result must resolve you However, integer. is an emulation the result Tandem the For its description with the bitwise functions: significance in determining the attri Each of the bit positions have composed of two bytes. butes for a field. FieldNum The see the field number, tion on acquiring the Result Arguments EXFLDATTR EXFLDATTR EXFLDATTR (FieldNum, (FieldNum, EXFLDATTR The sessions. The EXFLDATTR 130 DCS Script Language Reference EXFLDATTR, tributes forafield. is composedoftwobytes. Eachofthebitpositionshave significanceindeterminingtheat into itsdescriptionwiththebitwisefunctions: For theIBM TN3270 emulationtheresult isaninteger. However, you must resolve theresult Low Byte High Byte = Reversevideo =Blink NoBlink 1 = = 1 0 Underscore NoReverse video = = Bit 0: 1 0 HighIntensity NoUnderscore = = Bit 1: 1 0 NormalIntensity White(neutral) = Bit 2: = Yellow 111 0 = Turquoise 110 Bit 3: = Green 101 = Pink 100 = Red 011 = Blue 010 = 001 Transparent = Defaultcolor 1 Opaque = = 000 Bits 6,5,4: 0 Modified Bit 7: = 1 Extendedfieldattributesspecified Notmodified = = 1 0 Noextendedfieldattributes Nodisplay, andLightpennotdetected = Bit 0: = 11 Highintensitydisplay, andLightpendetected 0 = 10 Normaldisplay, andLightpendetected Bit 1: = 01 Numeric = Normaldisplay, andLightpennotdetected 1 = Protected Alphanumeric 00 = = Bits 3,2: 1 0 Unprotected = Bit 4: Notused 0 Notused x Bit 5: x Bit 6: Bit 7: continued BAND , BNOT , BOR , and BXOR . Theinteger - 2 Functions 131 - . The integer is BXOR , and BOR , BNOT , BAND Comments 110 110 = 111 = Right adjust, blank fill Mandatory fill 1 = operator-entered letters to uppercase Translate 1 = Is a mandatory enter field 101 = Right adjust, zero fill 111 111 = Signed numeric 1 = 1 Auto enter = Field exit key is required 1 = 1 this field Duplication is allowed in = 001 Field has been modified = 010 = Alphabetic only 011 = Numeric shift 100 = Numeric only 101 = Katakana shift Digits only (5294) 1 = Bypass field continued
Bit 4: Bit 3: 0 Bits 2,1, 0: = 000 = = Reserved Not a mandatory enter field No adjust specified = 001 Reserved = 010 Reserved = 011 Reserved = 100 Reserved = 110 I/O Bit 7: 0 Bit 6: = 0 Bit 5: No auto enter = 0 Field exit key is not required = Accept lowercase letters Bit 4: 0 Bit 3: = 0 Bits 2,1,0: Duplication not allowed in this field 000 = = Field has not been Modified Alphabetic shift Bits 7,6: Bit 5: 01 0 = Not a Bypass field Low Byte High Byte For the IBM TN5250 emulation the result is an integer. However, you must resolve the result the result resolve must you However, is an integer. the result TN5250 emulation the IBM For the bitwise functions: into its description with attri significance in determining the the bit positions have Each of composed of two bytes. butes for a field. EXFLDATTR, EXFLDATTR, 132 DCS Script Language Reference EXFLDATTR, Example This script: from the windowfor aparticular mayberetrieved withthefunctions rent sessionwillbeusedasthewindow handleargumentinthefunction.Thewindow handle If the tion performs an OR operation on a binary numberintheformofahexadecimal numberto anORoperationonabinary tion performs were usedasamask, itwouldcover over allthe bitsoftheattributesnumber. The the initialmask,whichisnegative oftheintegerforfieldattributes. If thisinitialmask and inthiscasethescriptisonlyinterested The inbitpositionthirteen. Amask iscreatedbit positionthirteen. tocover over thebitsthatscriptisnotinterested in, By usingthebitwisefunctionsinsuccessive order, thescriptisabletodetermine thevalue of only displaysadialogindicatingitsfinding. termines whetherthefieldisprotected orunprotected. For purposesofillustration, thescript looks atafieldlocatedonthefifth row and twentieth columnofthesession WinHandle Return Wait Resume Dialog End Dialog “Results” *DisplayDialog ($String) ;******************************************************** Return “ isprotected.”) Else “ isuprotected.”) If %MaskAttrs=0 %MaskAttrs =BAnd(%FieldAttrs,%MaskAttrs) %MaskAttrs =BOr(%MaskAttrs,0x2000) ; Inbinary,0x2000is0010.0000.0000.0000 %MaskAttrs =BNot(%FieldAttrs) %FieldAttrs =ExFldAttr(%FieldNum,%WinHandle) %FieldNum =FldNum(5,20,%WinHandle) %WinHandle =WindowHnd(“Scr1”) CONNECT continued Button “OK”Resume Message $String Perform DisplayDialog (“Field “ | Str (%FieldNum) | “ |Str(%FieldNum) (“Field DisplayDialog Perform | “ |Str(%FieldNum) (“Field DisplayDialog Perform
argument isnotincludedinthisfunction,thewindow handleforthecur command. HWNDLIST BNOT or WINDOWHND Scr1 function creates BOR andde func - , or - - 2 Functions 133 - function makes sure that bit position thirteen that bit position in the mask is 1 sure function makes BOR function performs attributes num an AND operation on the original BAND continued the mask. In this case, the this In the mask. (one). Then the is not or a number that could only be 0 (zero) result of this process ber with the mask. The protected. the field is zero, result is not If the is unprotected. the field is zero, the result If zero. EXFLDATTR, EXFLDATTR, 134 DCS Script Language Reference EXISTS The EXISTS (FileName) EXISTS Arguments Example Comments Result The FileName TRUE, andthefileis renamed If thefile In thisexample: tory. If you donotspecifyapathwiththefilename,defaultisDCS’s defaultinstallationdirec The result isaBoolean value, where TRUE indicatesthespecifiedfileexists. must specifyavalid filenamefor your system. FileName function indicateswhetherthespecifiedfileexists. FILE RENAMEDIRECTORY(MEMO)|“MEMO.TXT”\ IF EXISTS(DIRECTORY(MEMO)|“MEMO.TXT”) MEMO.TXT argument isastringspecifyingthenameoffile.The TO DIRECTORY(MEMO)|“MEMO.BAK” existsinthedefault MEMO.BAK MEMO . directory, the EXISTS FileName function evaluates to argument - 2 Functions 135 argument FileName function returns TRUE and the result is -1. and the result TRUE function returns ERROR argument is a string specifying the name of a file. The argument is a string function returns the number of bytes in the specified file. number of bytes the function returns %size = FILESIZE (“EXCHANGE.PST”) FileName The result is a numeric value indicating the size of the specified file in bytes. file in of the specified size value indicating the result is a numeric The the file does not exist, the If the default is the DCS 9 default installation do not specify a path with the file name, you If directory. FileName The your system. for file name must specify a valid Comments Example Arguments Result FILESIZE FILESIZE (FileName) FILESIZE The FILESIZE 136 DCS Script Language Reference FILTER The FILTER (String,SearchChars, FILTER Arguments Example Comments Result String deleted. with Zcharacters,allXcharacters are replaced withncharacters,andall0(zero) charactersare the stringvariable In thisexample: string variable the In thisexample: Both the The result isastring value containingthemodifiedstring. ment thatdonothave corresponding charactersinthe in the Characters specifiedinthe fied inthe replace foundcharacters.There isaone-to-onecorrespondence between thecharactersspeci The optional ReplaceChars not charactersequences. If more thanonecharacterisspecified,DCSsearches for eachindividualcharacterspecified, The SearchChars The FILTER SearchChars String function replaces charactersfoundinthespecifiedstring. $string =FILTER(“ABCAX0AX234”,“AX0”, “Zn”) $file =FILTER(“\TEST\USER\FILE”,“\”, “:”) ReplaceChars SearchChars SearchChars argument specifiesthestringtosearch. function was used to convert aDOSfilenameto function wasusedtoconvert Macintosh filename.The ReplaceChars $file
$string argument isastringspecifyingoneormore charactersforwhichtosearch. assumesthevalue
argument are deleted.Charactersspecifiedinthe
and the
argument andthe SearchChars
ReplaceChars assumesthevalue ZBCZnZn234.AllAcharactersare replaced argument isastringspecifyingoneormore characterswhichwill ReplaceChars :TEST:USER:FILE
argument thatdonothave corresponding characters ReplaceChars )
arguments are case-sensitive. SearchChars
argument. .
argument are ignored. ReplaceChars
argu - - 2 Functions 137 contains the value BC234. All A, X and 0 (zero) characters are characters are A, X and 0 (zero) BC234. All contains the value deleted. spaces are ABCD. All contains the value $string $string $string = FILTER (“ABCAX0AX234”, “AX0”) $string = FILTER (“A B C D”, “ “, “”) $string = FILTER continued In this example: In the string variable deleted. this example: In the string variable FILTER, FILTER, 138 DCS Script Language Reference FLDATTR sessions. It returns thefieldattributesforspecifiedinasessionwindow. The FLDATTR (Field, FLDATTR Arguments Comments Result Field The the active sessionwindow. If the (decimal 32–64).This value corresponds totheIBM TN5250 screen attribute(fullcolor). For theIBM TN5250 emulationtheresult isanintegervalue between hex0x20and0x3F attributes: For theIBM3270emulationThe result isaninteger value specifyingoneofthefollowing field attributes: For the Tandem emulationtheresult isanintegervalue specifyingoneofthefollowing field DCS. The optional WinHandle The Field ERROR WinHandle Note: FieldAttribute Value FieldAttribute Value function isonlyvalid withIBM TN3270, IBM TN5250, and Tandem 6530emulation 48 32 16 0 32 Protected 0 Unprotected argument isanumericidentifyingthefield.
WinHandle If ERROR issetto TRUE, a-1(negative one)isreturned. WinHandle function returns TRUE ifeither argument isnotincludedinthisfunction,DCSusesthewindow handleof Numeric (protected) Protected (alphanumeric) Numeric (unprotected) Normal (alphanumeric,unprotected) argument is an integer specifying a particular sessionwindowargument isanintegerspecifyingaparticular in ) Field or WinHandle is invalid. 2 Functions 139 - assumes the %attrib contains numeric pro %winhnd assumes the value 48. assumes the value %attrib %attrib = FLDATTR (3) %attrib = FLDATTR (2, %winhnd) %attrib = FLDATTR continued if the second field in the session specified by the variable by the if the second field in the session specified tected data, the integer variable In this example: In variable data, the integer numeric unprotected contains if field three 16. value this example: In Example FLDATTR, FLDATTR, 140 DCS Script Language Reference FLDATTREXPOS for afieldatspecificposition. emulation sessions.The The FLDATTREXPOS (Row, Column, FLDATTREXPOS Arguments Example Comments Result rather thanfieldnumberusedinthe TR See theexamplefor from the windowfor aparticular mayberetrieved withthefunctions rent sessionwillbeusedasthewindow handleargumentinthefunction.Thewindow handle If the sixteen bitpositionshave significance indeterminingtheattributesforafield. operators (AND,NOT, OR,andXOR). Theintegeriscomposedoftwo bytes. Eachofthe The result isaninteger. However, you must resolve the result intoitsdescriptionwithbit-wise ment allows sessionwindow. ascripttochecktheattributesoffieldinparticular The optional WinHandle is considered column0(zero). The Column ered row 0(zero). The Row ; themajordifference istheuseofa row andcolumninthe Column Row Also see: WinHandle CONNECT argument isanintegerspecifyingtherow numberofafield.Thefirst rowisconsid argument isanintegerspecifyingthecolumnnumberofafield.Thefirst WinHandle EXFLDATTR function isonlyvalid withIBM TN3270, IBM TN5250, and Tandem 6530 FLDATTREXPOS argument isnotincludedinthisfunction,thewindow handleforthecur command. EXFLDATTR argument isanintegerandidentifiesawindow inDCS.Thisargu
tables WinHandle function indicatesthenormalandextendedfieldattributes EXFLDATTR function, substituting ) function. HWNDLIST FLDATTREXPOS FLDATTREXPOS or WINDOWHND for function, EXFLDAT , or - - - - 2 Functions 141 argument WinHandle WinHandle argument or the Field assumes the value 171. assumes the value argument is an integer specifying a particular session window in argument is an integer specifying a particular session window ) is set TRUE a negative one (-1) is returned. a negative TRUE is set argument is not included in this function, DCS uses the window handle of DCS uses the window argument is not included in this function, %length_3 ERROR function returns TRUE if either the TRUE function returns WinHandle WinHandle If WinHandle argument is a numeric identifying the field. argument is a numeric function is only valid with IBM3270, IBM5250, and Tandem 6530 emulator sessions. Tandem IBM5250, and with IBM3270, function is only valid %length_3 = FLDLEN (3) Note: WinHandle WinHandle ERROR Field The is invalid. this example: In at the tenth column (column nine) and ends zero) (row begins on the first line if field three two) at the 19th column (column 20), and the column width is 80, the line (row on the third numeric variable The optional DCS. length in characters of the specified field. value indicating the result is a numeric The the If session window. the current Field The WinHandle Example Result Comments Arguments FLDLEN FLDLEN (Field, FLDLEN The specified field in a session window. the length of the returns It FLDLEN 142 DCS Script Language Reference FLDNUM sessions. The The FLDNUM (Row, Column, FLDNUM Arguments: Example Comments Result Row See theexamplefor or from the windowfor aparticular mayberetrieved withthefunctions, rent sessionwillbeusedasthewindow handleargumentinthefunction.Thewindow handle If the If The result isanintegerfieldnumber. The terminal window currently infocus. ment allows session,notmerely ascripttochecktheattributesoffieldinparticular the The optional WinHandle is considered column0(zero). The Column ered row 0(zero). The ERROR ERROR Column Row FLDNUM WinHandle function isonlyvalid withIBM TN3270, IBM TN5250, and Tandem 6530emulator argument isanintegerspecifyingtherow numberofafield.Thefirst rowisconsid is set TRUE anegative one(-1)isreturned. CONNECT argument isanintegerspecifyingthecolumnnumberofafield.Thefirst WinHandle function returns TRUE ifthe function returns thefieldnumber, oridentifier, ofafieldinsessionwindow. argument isnotincludedinthisfunction,thewindow handleforthecur WinHandle EXFLDATTR command. argument isanintegerandidentifiesawindow inDCS.Thisargu ) function. WinHandle argument isinvalid. HWNDLIST or WINDOWHND , - - - 2 Functions 143 argument = 9). WinHandle WinHandle %column argument or the assumes value 89. The next two lines assumes value Field = 1) and column ( %pos3 %row argument is an integer identifying a particular window containing a argument is an integer identifying a particular window
) argument is not included in this function, DCS uses the window handle of DCS uses the window argument is not included in this function, variable into the row ( into the row variable function returns TRUE if either the TRUE function returns WinHandle WinHandle %pos is set TRUE a negative one (-1) is returned. a negative TRUE is set argument is a numeric identifying the field. argument is a numeric function is only valid with IBM TN3270, IBM TN5250, and Tandem 6530 emulation Tandem TN5250, and TN3270, IBM with IBM function is only valid %row = %pos3 / 80 %column = %pos3 % 80 %pos3 = FLDPOS(3) (row * column width) + column WinHandle WinHandle ERROR Field ERROR if field 3 (three) starts on the second line (row one) at the tenth column (column nine), and one) at the tenth column (column starts on the second line (row if field 3 (three) the column width is 80, the numeric variable decode the If the If session window. the current The is invalid. this example: In The optional session in DCS. formula: the following value calculated using result is a numeric The (zero). and the first column is column 0 (zero) row 0 The first line is If Field The WinHandle Comments Example Result Arguments FLDPOS FLDPOS (Field, FLDPOS The field in a session window. position of the beginning of the specified the absolute returns sessions. It FLDPOS 144 DCS Script Language Reference FLDTEXT returns thetextforspecifiedfieldinasessionwindow. The FLDTEXT (Field, FLDTEXT Arguments Example Comments Result Field where thefieldbeginsandends. The variable $Twillcontainallthetextfrom thefield around row 2,column12 regardless of In thisexample: is invalid. The the current sessionwindow. If the The result isatextstring. session inDCS. The optional WinHandle The ERROR Field WinHandle $T =FLDTEXT(%N) %N =FLDNUM(2,12) function isonlyvalid withIBM TN3270 andIBM TN5250 emulationsessions.It argument isanumericidentifyingthefield. WinHandle WinHandle function returns TRUE ifeitherthe argument isnotincludedinthisfunction,DCSusesthewindow handleof
argument is an integer identifying a particular windowargument isanintegeridentifyingaparticular containinga ) Field argument orthe WinHandle argument 2 Functions 145 - ), or com command. Options > APPCONFIG Tools Tools APPCONFIG option. If the setting is checked option. If dialog (select argument is invalid. Options Options function are listed in the function are KeyString command for a list of valid strings which may be used as command for a list of valid Show Background Bitmap Background Show GETAPPCONFIG GETAPPCONFIG . function returns a string representing the current state of the setting the current a string representing function returns function will return a string identifying the current state of that setting. a string identifying the current function will return command. APPCONFIG KeyString function returns a string identifying the current state of a specified application- state of a specified identifying the current a string function returns recommended that the code check for both conditions (if $retval = TRUE or TRUE = that the code check for both conditions (if $retval recommended problems. possible logic flow = “1 …) to avoid $retval In some instances DCS will return a 1 for TRUE and a 0 for FALSE. It is It and a 0 for FALSE. TRUE a 1 for some instances DCS will return In argument must be a key string which is valid for the key string which is valid argument must be a function returns TRUE if the TRUE function returns
is set to TRUE, a null string is returned. TRUE, is set to arguments. APPCONFIG $bitmap = GETAPPCONFIG (“ShowBkgrdBitMap”) If $bitmap = “TRUE” APPCONFIG “ShowBkgrdBitMap=FALSE” Note: ERROR GETAPPCONFIG GETAPPCONFIG KeyString GETAPPCONFIG ERROR checks the current setting of the checks the current it is disabled. (active), If The configuration may be set using the Application with the This script segment: The values returned by the returned values The mand. Also see the KeyString The by the specified KeyString The The Comments Example Result Arguments GETAPPCONFIG GETAPPCONFIG GETAPPCONFIG (KeyString) GETAPPCONFIG The setting. level GETAPPCONFIG 146 DCS Script Language Reference GETCONNCONFIG for thedefaultsessionwindow. The GETCONNCONFIG (KeyString, GETCONNCONFIG Arguments Example Comments Result KeyString If thescriptdoesnothave adefaultsessionwindow, DCSreturns anullstring. value ofthestring,whichinthiscaseis numericalvalue 8. string 8isassignedto Assuming thatthedefaultsession’s connectoriscurrently usingadatabitsettingof8(eight), TRUE. If eitherthe session window. If Properties The connectorsettingforasessionwindow isspecifiedonthe If setting forthesessioninscript’s defaultsessionwindow. The The optional WinHandle See the example, CONNCONFIG The WinHandle ERROR GETCONNCONFIG KeyString %NumBits =Num($ConnDataBits) $ConnDataBits =GETCONNCONFIG(“DataBits”) Set DefaultsessionhandleActive() Note: CONNCONFIG GETCONNCONFIG is set TRUE anullstringisreturned. dialog, orwiththe
KeyString WinHandle
isnotspecified,DCSappliestheconnectorconfigurationsettingstoactive argument mustbeakeystringrecognized by theconnector. The In someinstancesDCSreturns a1for TRUE anda0forFALSE. It isrecom = “1…)toavoid possiblelogic flow problems. mended thatthecodecheckforbothconditions(if$retval = TRUE or$retval function returns astringrepresenting thecurrent stateofthatsetting.For function returns astringidentifyingthecurrent stateofaconnectorsetting $ConnDataBits or command foralistofkeystrings. function returns astringidentifyingthecurrent stateofaconnector WinHandle argument is an integer identifying a particular sessionwindow.argument isanintegeridentifyingaparticular WinHandle CONNCONFIG (“DataBits”) wouldreturn eitherthestring7or8. argument isinvalid, the . The variable ) command. %NumBits Connectors ERROR isassignedthenumerical function returns tab inthe GET - Session - 2 Functions 147
- - for the Session Properties Session argument is invalid. tab in the WinHandle WinHandle or Displays Displays Field ) command. command WinHandle function returns a string representing the current settings of a the current a string representing function returns argument is an integer identifying a particular session window of argument is an integer identifying a particular session window function returns a string identifying the current display settings identifying the current a string function returns command for a list of keywords and possible return values. and possible return keywords command for a list of DISPLAYCONFIG DISPLAYCONFIG 1, BLOCK DISPLAYCONFIG DISPLAYCONFIG mended that the code check for both conditions (if $retval = TRUE or $retval or $retval TRUE = (if $retval mended that the code check for both conditions problems. possible logic flow = “1 …) to avoid In some instances DCS returns a 1 for TRUE and a 0 for FALSE. It is recom It and a 0 for FALSE. TRUE a 1 for some instances DCS returns In argument must be a keyword recognized by DCS for session windows. See the See session windows. DCS for by recognized keyword argument must be a is not specified, DCS retrieves the display settings for the active session window. the display settings for the active retrieves is not specified, DCS function returns TRUE if either the TRUE function returns WinHandle WinHandle
is set TRUE a null string is returned. a null string TRUE is set $Cursor = GetDisplayConfig (“CursorVisible”) | GetDisplayConfig“, “ (“Cursor $DisplayInfo $Cursor | = Type”) Note: Also see: ERROR GETDISPLAYCONFIG GETDISPLAYCONFIG KeyString ERROR WinHandle might return a string similar to the following: a string similar to the following: might return and is a block character. This string indicates the cursor is displayed If set on the are The display settings for a session window dialog, or with the If The This script line: WinHandle The optional DCS. The session window. KeyString The DISPLAYCONFIG Comments Result Arguments GETDISPLAYCONFIG GETDISPLAYCONFIG GETDISPLAYCONFIG (KeyString, (KeyString, GETDISPLAYCONFIG The default session window. GETDISPLAYCONFIG 148 DCS Script Language Reference GETEMULCONFIG for thesessioninscript’s defaultsessionwindow. The GETEMULCONFIG (KeyString, GETEMULCONFIG Arguments Example Comments Result KeyString numerical value ofthestring,whichinthiscaseisnumerical value 132. The string“132”isassignedto assuming thatthedefaultsession’s emulationiscurrently usingacolumnwidthsettingof132, In thisexample: invalid. The sion Properties The emulationsettingsforasessionwindow are specifiedonthe session window. If If setting forthesessioninscript’s defaultsessionwindow. The The optional WinHandle See the GETEMULCONFIG CONFIG The WinHandle ERROR ERROR GETEMULCONFIG KeyString %NumColumns =NUM($EmulCols) $EmulCols =GETEMULCONFIG(“Columns”) Note: EMULCONFIG function returns astringrepresenting thecurrent stateofthatsetting.For example, is set TRUE anullstringisreturned.
WinHandle function returns TRUE ifeitherthe is notspecified,theemulationconfigurationsettings are appliedtotheactive argument mustbeakeystringrecognized by theemulation.The In someinstancesDCSreturns a1for TRUE anda0forFALSE. It isrecom = “1…)toavoid possiblelogic flow problems. mended thatthecodecheckforbothconditions(if$retval = TRUE or$retval dialog,orwiththe function returns astringidentifyingthecurrent stateofanemulationsetting (“Columns”) mightreturn eitherthestring80or132. command foralistofkeystrings. function returns astringidentifyingthecurrent stateofanemulation argument is an integer identifying a particular sessionwindow.argument isanintegeridentifyingaparticular WinHandle $EmulCols EMULCONFIG ) . The variable KeyString command. %NumColumns or WinHandle Emulations argument is isassignedthe tab inthe GETEMUL Ses - - -
2 Functions 149 - - com Session Session argument is tab in the GENERALCONFIG GENERALCONFIG WinHandle WinHandle General General or command. KeyString (“DisplayErrorInformation”) returns a string returns (“DisplayErrorInformation”) ) function returns a string representing the current state the current representing a string function returns dialog for the active session. dialog for the active WinHandle . GENERALCONFIG function returns a string representing the current state of the the current a string representing function returns GENERALCONFIG command for a list of key strings. argument is an integer identifying a particular session window. KeyString function returns a string identifying which options have been configured been configured identifying which options have a string function returns Session Properties Session argument must be a key string which is valid for the key string which is valid argument must be a is not specified, the configuration settings are applied to the active session to the active are applied is not specified, the configuration settings function returns TRUE if either the TRUE function returns WinHandle mended that the code check for both conditions (if $retval = TRUE or $retval = or $retval TRUE = (if $retval mended that the code check for both conditions problems. possible logic flow “1 …) to avoid In some instances DCS returns a 1 for TRUE and a 0 for FALSE. It is recom It and a 0 for FALSE. TRUE a 1 for some instances DCS returns In
GETGENERALCONFIG GETGENERALCONFIG is set to TRUE a null string is returned. TRUE is set to dialog, or with the GENERALCONFIG tab of the $Autoconnect = GETGENERALCONFIG (“AutoConnect”) If $Autconnect “TRUE” = GENERALCONFIG “AutoConnect=FALSE” Note: ERROR GETGENERALCONFIG KeyString ERROR WinHandle The invalid. This script segment: it is the setting is checked (active), Connect option. If setting of the Auto checks the current disabled. If If window. on the specified are The general settings for a session window Properties of that setting. For example, of that setting. For or FALSE. TRUE of either value the See WinHandle The optional The by the setting specified KeyString The mand. The General General Example Comments Result Arguments GETGENERALCONFIG GETGENERALCONFIG GETGENERALCONFIG(KeyString, GETGENERALCONFIG(KeyString, The in the GETGENERALCONFIG 150 DCS Script Language Reference GETPROFILEDATA The GETPROFILEDATA (Section,KeyName,INIFile) GETPROFILEDATA Arguments Example Comments Result Section $File equal sign,thevariable searched forthetext the functionsearches the In thisexample Windows documentation. For moreinformation aboutthestructure andcontentsofinitializationfiles, refer to Microsoft contains anullstring: the quotes.For example,afterthefollowing scriptlineisexecuted thevariable An emptyornullstringisusuallydenotedby aleftandrightquotewith nothingbetween 0 (zero). result isanulloremptystring.If anerror occurs,theresult isastringcontainingthecharacter the otherwise, ment, theresult isastringcomposedofthetextonrightsideanentry; If textintheinitializationfileisfoundthatmatchescontained which DCScollectstext. The INIFile contains thetextin the The KeyName section names. tion filefrom whichDCSgatherstext. In aninitializationfile,square brackets([])surround The Section INIFile KeyName Section Also see: $File =GETPROFILEDATA (“Child0”,“IconFile”,“app.ini”) $Section =“” containsanull string. argument isastringvariable that specifiesthenameofinitializationfile from argument from whichtocollect text. Text iftheentry iscollectedfrom anentry argument isastringvariable thatspecifiesthesectionnamewithinaninitializa argument is a string variable that specifies the entry inthesectionspecified by argument isastringvariable that specifiestheentry PUTPROFILEDATA function retrieves text associated with an entry inaninitializationfile. function retrieves textassociatedwithanentry “IconFile” $File KeyName app.ini containsthetexttorightof theequalsign.If notfound, argument ontheleftsideofequalsigninentry. function initializationfile.Allentriesin thesection . If an entry containsthesearch texttotheleftof . If anentry KeyName $Section Child0 argu are
- - 2 Functions 151 - - tab in the argument is File Transfers File WinHandle WinHandle or command. KeyString ) XFERCONFIG WinHandle (“BlockSize”) might return either the string “256” or the string either the string “256” or return might (“BlockSize”) argument is an integer identifying a particular child window of argument is an integer identifying a particular child window function returns a string identifying the current state of a file transfer current a string identifying the function returns command for a list of key strings. function returns a string representing the current state of that setting. For state of that setting. For the current representing a string function returns dialog, or with the function returns a string identifying the current state of a file transfer proto state of a file transfer identifying the current a string function returns argument must be a key string recognized by the file transfer protocol. The the file transfer protocol. by key string recognized argument must be a is not specified, DCS applies the file transfer protocol configuration settings to protocol configuration is not specified, DCS applies the file transfer (KeyString, (KeyString, function returns TRUE if either the TRUE function returns WinHandle WinHandle mended that the code check for both conditions (if $retval = TRUE or $retval = or $retval TRUE = (if $retval mended that the code check for both conditions problems. possible logic flow “1 …) to avoid In some instances DCS will return a 1 for TRUE and a 0 for FALSE. It is recom It and a 0 for FALSE. TRUE a 1 for some instances DCS will return In
is set to TRUE a null string is returned. TRUE is set to GETXFERCONFIG XFERCONFIG Note: ERROR GETXFERCONFIG KeyString ERROR WinHandle Session Properties Session The invalid. If If session window. the active are specified on the protocol settings for a session The file transfer example, “Auto”. the See WinHandle The optional DCS. The session window. default setting for the session in the script’s protocol KeyString The GETXFERCONFIG Comments Result Arguments GETXFERCONFIG GETXFERCONFIG GETXFERCONFIG The session window. col setting for the default GETXFERCONFIG 152 DCS Script Language Reference GETXFERCONFIG, Example In thisscript: If thescriptdoesnothave adefaultsession window, anullstringisreturned. the stringisshown intheactive sessionwindow. cal value of thestring,whichinthiscaseisnumericalvalue 256.If thestringis the string“256”isassignedto assuming thedefaultsession’s filetransferprotocol iscurrently usingablocksize settingof256, Else Display(0,0)$XFerBlock %Block =Num($XFerBlock) If $XFerBlock<>“Auto” $XFerBlock =GETXFERCONFIG(“BlockSize”) continued $XFerBlock . The variable %Block isassignedthenumeri “Auto” - , 2 Functions 153 function to change the string to NUM command, its handle is not available via command, its handle is not available
argument returns a string of all child window a string of all child window argument returns argument returns a string of the application window window a string of the application argument returns WINDOW HIDE NumWin NumWin NumWin NumWin argument is an integer expression specifying the number of window specifying the number of window expression argument is an integer ) function returns the window handles for all of the child windows of the DCS windows handles for all of the child the window function returns NumWin NumWin function returns a string containing the window handles of all open child windows. containing the window a string function returns NumWin $wins = HWNDLIST (-1) DISPLAY $wins HWNDLIST HWNDLIST In this example In the application window. DCS might display the string When the display command is executed, 0x3084,0x8D88,0x30D8 in the session window. A value of 0 (zero) in the of 0 (zero) A value a returns of zero is open, a value no child window is open in DCS. If handle if a child window null string. must use the is a string, you returned the value Because with other functions as a numeric value the result wish to use if you a numeric representation or commands. the is hidden by child window a If this function. The result is a string composed of the handles of DCS child windows. The first handle is the result is a string composed of the handles of DCS child windows. The and so on. The activated, the next most recently by followed window, activated most recently form of handle and has the generalized Window of a string is a hexadecimal representation E, the set (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, an asterisk is a character from 0x****, where a by string, is followed in the resulting for the last handle handle, except F). Each window’s comma. one) in the of -1 (negative A value value. handles. This is the default NumWin The optional the by the integer one, is specified window activated the most recently where handles to return, on. by the integer two, and so specified are windows activated two most recently Example Comments Result Arguments HWNDLIST HWNDLIST HWNDLIST ( HWNDLIST The HWNDLIST 154 DCS Script Language Reference HWNDLIST, Example In thisexample: or command. retrieved by the for the meric value withthe %WinHnd the hexadecimalvalues ofallwindows are assignedto Window Activate%WinHnd %WinHnd =NUM(SUBSTR($AllWindows,1,(%Comma-1))) %Comma =POS($AllWindows,“,”1) $AllWindows =HWNDLIST(-1) WINDOW ACTIVATE continued isassignedanumericvalue by changingasubstringof HWNDLIST NUM function. Thisallows DCStouse function cannotbeusedasanumericvalue inanotherfunction command. Without theuseof $AllWindows %WinHnd NUM $AllWindows function, thestring . Theinteger variable asthewindow handle intoanu - 2 Functions 155 - - argument is not valid.
WinHandle argument is a numeric expression specifying a particular window. specifying a particular window. expression argument is a numeric
function evaluates to TRUE and the DCS application window is maxi and the DCS application window TRUE to function evaluates argument is not included in this function, DCS uses the window handle of DCS uses the window argument is not included in this function, argument of zero (0) to specify the DCS application window. (0) to specify the argument of zero
) function returns TRUE if the TRUE function returns WinHandle ICONIC %h = NUM (hwndlist (0) IF ICONIC (%h) WINDOW MAXIMIZE (%h) WinHandle WinHandle function indicates whether a child window or the DCS application window is mini DCS application window or the a child window function indicates whether ERROR contains the handle for the DCS application window. If DCS is running If in a minimized window. contains the handle for the DCS application WinHandle In this example: In %h the window, mized. The result is a Boolean value, where TRUE indicates the window is minimized, and FALSE and is minimized, indicates the window TRUE value, where result is a Boolean The is not minimized. indicates that the window the If session window. the current The WinHandle The optional a Use Result Comments Example Arguments ICONIC ICONIC ( The mized. ICONIC 156 DCS Script Language Reference INT The INT (RealNum) INT Arguments Example Comments Result RealNum window. ittoaninteger.function isusedtoconvert Thestring3willbedisplayed intheactive session the This commanddirects DCStodisplaythestring representation oftheinteger returned by In thisexample: the numericvariable %numassumes thevalue 23. In thisexample: rounded. or areal numbermaybespecified.Alldecimalplacesina real numberare not truncated, a This functionismostusefulforconverting real value toaninteger, althougheitheraninteger argument. The result isaninteger value corresponding ofthe tothewholenumberportion The function converts arealfunction converts numericvalue orexpression toanintegervalue. INT RealNum DISPLAY (0,0)STR(INT(10/3)) %num =INT(23.6) function. Since theresult oftheintegerdivisionisareal number(3.33333),the
argument containsthereal numericvalue orexpression tobeconverted. RealNum INT
2 Functions 157 - - as %len contains the string “HOUSTON, TEXAS”, the numeric variable TEXAS”, the numeric variable contains the string “HOUSTON, contains the string “TEXAS”, the numeric variable $name $name argument specifies the string whose length is to be determined. argument specifies the function returns the number of characters in the specified string. number of characters in the specified the function returns assumes the value “14”. assumes the value %len = LENGTH ($name) String if the string variable if the string variable “5”. sumes the value the string variable If %len The result is an integer value indicating the number of ASCII characters, including spaces, in value indicating the number of ASCII result is an integer The the specified string. a maxi a maximum length of 254 characters, this function returns a string may have Since of 254. mum value this example: In String The Comments Example Arguments Result LENGTH LENGTH (String) LENGTH The LENGTH 158 DCS Script Language Reference (MENU) CHECKED The CHECKED (Popup,Item) (MENU) CHECKED Arguments Example Result Popup MENU UPDATE the In thisexample: TRUE. If eitherthe indicates thattheitemisunchecked. The result isaBoolean value, where TRUE indicatesthattheitemischecked and FALSE specified by theinteger“12”. counted. For example,thelastiteminamenucontainingtenitemsandtwoseparators is argument. Thefirstitemisspecified bytheinteger1(one)andbothitemsseparators are The Item (one). menu isspecified by theinteger0(zero) andthefirstpopupmenuisspecified bytheinteger1 The (MENU) CHECKED Item Popup MENU UPDATE21CHECKED ELSE MENU UPDATE21UNCHECKED IF CHECKED(2,1) argument isanintegerspecifyingiteminthemenuspecified by the argument isanintegerspecifyingapopupmenu,where theapplicationcontrol Popup commandtogglesthestatebetween checkedandunchecked. functionindicateswhetherthespecifiedmenuitemischeckedorunchecked. argument or functionreturns thestateoffirstiteminsecond menu.The Item argument isinvalid, the ERROR function returns Popup 2 Functions 159 - - argu MENU MENU UP Popup function returns function returns ERROR function returns TRUE), the TRUE), function returns argument is invalid, the argument is invalid, Item (MENU) ENABLED function returns the state of the second item in the second menu. If item in the second menu. If the state of the second function returns argument or function indicates whether the specified menu item is enabled or disabled. the specified menu item is enabled function indicates whether function returns the state of the second item in the second menu. The function returns Popup argument is an integer specifying a popup menu, where the application control the application control specifying a popup menu, where argument is an integer command toggles the menu item between an enabled and disabled state. command toggles the menu item between argument is an integer specifying an item in the menu specified by the by the in the menu specified argument is an integer specifying an item
IF ENABLED(2,2) MENU UPDATE 2 2 GRAYED ELSE MENU UPDATE 2 2 ENABLED IF ENABLED (2, 2) MENU UPDATE 2 2 GRAYED command disables the menu item. Item Popup ENABLED (MENU) ENABLED the UPDATE In this example: In the the menu item is enabled (the DATE this example: In The are counted. both items and separators by the integer one and ment. The first item is specified by two separators is specified example, the last item in a menu containing ten items and For the integer “12”. indicates that the menu item is enabled and TRUE value, where result is a Boolean The indicates that the menu item is disabled. FALSE either the If TRUE. Popup The by the integer 1 (one). the first menu is specified and 0 (zero) by the integer menu is specified Item Example Result Arguments (MENU) ENABLED ENABLED (Popup, Item) ENABLED The (MENU) ENABLED (MENU) 160 DCS Script Language Reference NETID The NETID () NETID Result Example Comments numeric characters. The result isthecurrent value ofthe NetworkID system variable work? the result stringofthe In thisexample: received through the the result stringofthe In thisexample: Compare withthe function returns thecurrent value oftheNetworkID systemvariable. END SEND NETID() BEGIN WAIT STRING“Network?” SEND NETID() WHEN STRING“@” ” isreceived through the SET NETID COM NETID NETID port ofthecomputer.port function issenttotheremote systemwhenthestring“ function issenttotheremote systemwhenthestring command. COM port ofthecomputer.port . Thestringcancontainalpha “@” Net is - - 2 Functions 161 function returns TRUE and the TRUE function returns ERROR function. function takes no arguments. ROUTE NEXT NEXT function retrieves the next file name from the most recent list of files established using the recent list of files the most file name from the next function retrieves function. If the route is empty or has not been defined, the is empty or has not been defined, the route If is a null string. result the See The route. current containing the next file name in the value a string result is The Comments Example Arguments Result NEXT NEXT NEXT ( ) The ROUTE NEXT 162 DCS Script Language Reference NUM The NUM (String) NUM Arguments Example Result String fore, ofthevalue istruncated. thefractionalportion function returns areal numeric,inthisexampleitisstored inanintegernumericand,there the integernumericvariable In thisexample: the real numericvariable In thisexample: The result isa real numeric value corresponding tothenumeric value ofthe The function returns thereal numericvalue ofthespecifiedstring. String %int =NUM(“123.67”) !real =NUM(“111.89”) argument contains the string to be converted toanumeric. argument containsthestringtobeconverted !real %int assumesthevalue “111.89”. assumesthenumericvalue “123”. Althoughthe String argument. NUM - 2 Functions 163 - ; the sum of this expression is ; the sum of this expression argument. String assumes the value “65”. assumes the value %num argument specifies the string to be converted. If multiple characters are specified, If multiple characters are string to be converted.argument specifies the ORD (“A”) + ORD (“B”) + ORD (“C”) ORD (“A”) + ORD (“B”) + ORD function returns the sum of the ordinal values of the characters. of the values sum of the ordinal the function returns %num = ORD (“A”) %num_sum = ORD (“ABC”) String ORD function converts the characters specified in the string to an integer numeric value. function converts to an integer numeric the characters specified in the string the numeric variable the numeric variable this example: In as the same value the returns “198”. It %num_sum assumes the value the numeric variable expression “65+66+67”, or “198”. The result is an integer numeric value corresponding to the sum of the ASCII numeric equiva to the sum of the ASCII numeric value corresponding result is an integer numeric The lents of the characters in the in the appendix titled “Character Sets” see on character representations, information more For Reference. the DCS 9 Online this example: In String The the Comments Example Arguments Result ORD ORD (String) The ORD 164 DCS Script Language Reference PASSWORD The PASSWORD () PASSWORD Result Example Comments Note: The result isthecurrent value ofthe Password system variable. Thestringmaycontainalpha the string“ In thisexample: numeric characters. Also see: This functiondoesnotapplytotheIBM TN3270emulation. DISPLAY “shhhh” IF PASSWORD()=“secret” function returns thecurrent value ofthePassword systemvariable. shhhh SET PASSWORD ” isdisplayed ifthePassword systemvariable issetto"secret". command - 2 Functions 165 . command assumes the value of the PhoneNumber system variable. of the PhoneNumber assumes the value $oldNum function returns the current value of the PhoneNumber system variable of the PhoneNumber value current the function returns SET PHONENUMBER SET
$oldNum = PHONENUMBER () Also see: In this example: In the string variable The result is the current value of the PhoneNumber system variable. The string may contain variable. The string may contain system PhoneNumber value of the the current result is The alphanumeric characters. Example Result Comments PHONENUMBER PHONENUMBER ( ) PHONENUMBER The PHONENUMBER 166 DCS Script Language Reference POS The POS (String,Keyword, POS Arguments Example Result String The numeric variable In thisexample: within thestring.If thestring does notcontainthekeyword, theresult isthevalue zero. The result isanumeric value indicatingthepositionoffirstcharacterkeyword search defaultstothefirstcharacterinstring. fied string(from 1to The optional Start The Keyword The function returns thepositionoffirstcharacterakeyword withinaspecifiedstring. Keyword String %position =POS(“DYNACOMM”,“A”) argument specifiesthestringinwhichtosearch forthekeyword. Start argument isastringcontainingthecharactersforwhichtosearch. argument isanumericspecifyingthecharacterpositionwithinspeci Start n %position ) atwhichtobeginsearching. If the ) assumesthenumericvalue “4”. Start argument isnotincluded,the - 2 Functions 167 - - - speci function. The represents the posi represents POSITION “$place” function returns TRUE and the result is and the result TRUE function returns , is converted to an integer and the ERROR “$winString” ) commands make use of window position coordinates. commands make use of window argument causes the function to return the position of the window the position of the window argument causes the function to return Boolean , is used as the window handle argument in the , is used as the window argument is not valid, the argument is not valid,
argument is a numeric expression specifying a particular window. The handle The specifying a particular window. expression argument is a numeric
is a window handle which has been parsed from a string returned by the by a string returned handle which has been parsed from is a window Boolean WINDOW function. The string, . function returns a string containing the position and dimensions of the window containing the position and dimensions a string function returns %winnum %winnum = NUM ($winstring) $place = POSITION (%winnum) DISPLAY $place | “^m” WinHandle WinHandle x,y,w,h $winstring HWNDLIST integer, The string with a carriage return. string is displayed resulting frame. tion of the window’s where (x,y) are the coordinates of the top left corner of the specified window, (w) is the win (w) is the of the specified window, of the top left corner the coordinates (x,y) are where height. width, and (h) is the window’s dow’s the If a null string. of the Many this example In Boolean The optional the window’s the position of TRUE, to evaluates When it to FALSE. frame when it evaluates FALSE. The default state is is returned. client area of the specified position and dimensions value listing the coordinate result is a string The form: in the window, WinHandle The zero. handle by the is specified window of the DCS application WinHandle Comments Example Result Arguments POSITION POSITION (WinHandle, (WinHandle, POSITION The by fied POSITION 168 DCS Script Language Reference POWER The POWER (Base,Exponent) POWER Arguments Example Result Base the real numericvariable In thisexample: the numericvariable In thisexample: The result isa real numeric value corresponding tothe The Exponent The Exponent Base function raisesthebasetospecifiedpower. !sqrt =POWER(%num,.5) %num =POWER(3,2) argument isanumericspecifyingthemathematicalbase. argument isanumericspecifyingthepower towhichthebasewillberaised. %num !sqrt assumes thevalue 9. assumesthevalue equaltothe square root of Base raised totheExponent. %num . 2 Functions 169 PRINT PRINT returns a null string. returns returns the current print parameters (see the the current returns PRTMETRICS PRTMETRICS PRTMETRICS PRTMETRICS function takes no arguments. assumes the string value “80,66,Courier,12”. assumes the string value $prt function returns the current print parameters. current the function returns command).
$prt = PRTMETRICS () PRTMETRICS PRTMETRICS Columns,Lines;Font,PointSize if the print parameters include a page size of 80 columns and 66 lines, with a 12 point Courier if the print parameters include a page size printer font, If a print channel is open, If OPEN no print channel is open, If this example: In The format: in the following value a string result is The Comments Example Arguments Result PRTMETRICS PRTMETRICS PRTMETRICS () PRTMETRICS The PRTMETRICS 170 DCS Script Language Reference PUTPROFILEDATA tion fileand returns astring value toindicatewhetherthissucceeded. The PUTPROFILEDATA (Section,KeyName,Data,File) PUTPROFILEDATA Arguments Result Section to closetheinitializationfile. One possibleerror mightbeafileerror (suchas Disk Full), whichcouldoccurwhenDCS tries ing thecharacter1.If anerror occurs,theresult isastringcontainingthecharacter0(zero). If DCSwasabletochangeorcreate textintheinitializationfile, result isastringcontain DCS willcreate orchangetext. The File willhave thefollowingthe entry format: Data The Data the textfrom the in the the The KeyName tion name. file towhichDCSwritestext. In aninitializationfile,square brackets( [])surround asec The KeyName =Data Section File Data KeyName Section Also see: argument appearstotherightofequalsigninanentry. When DCScreates anentry, KeyName argument isastringvariable specifying thenameofinitializationfileinwhich argument isastringvariable specifying thetextforanentry. Thecontentsofthe argument to change or create. DCS changes an entry if an entry containsthetext ifanentry argument tochangeorcreate. DCSchangesanentry argument isastringvariable containingthesectionnamewithinaninitialization argument is a string variable specifying which entry inthesectionindicatedby argument isastringvariable specifying whichentry GETPROFILEDATA argument ontheleftsideofequalsigninentry. If DCScannotfind KeyName function creates a new entry or changes an existing entry withinaninitializa orchangesanexistingentry function creates entry anew argument inanentry, DCSwillcreate entry. anew function - - - 2 Functions 171
- in the $Section “Magic_Number” . If the operation was successful, the . If $Status continued contains the character “1” (one). If the initialization file is not changed, the initialization file contains the character “1” (one). If . If the text is found, the characters “42” are written on the right side of the the text is found, the characters “42” are . If contains the character “0” (zero). $Status Child0 $Status = PUTPROFILEDATA (“Child0”, “Magic_Number”, “42”, “”) $Section = “” Magic_Number=42 searches the default application initialization file for the text the default application initialization searches section is not found, an entry the text is created: If similar to the following equal sign of the entry. placed in returns a string which is The function variable $Status An empty or null string is usually denoted by left and right quotation marks with nothing be left and right quotation marks is usually denoted by An empty or null string the variable script line is executed, example, after the following them. For tween will contain a null string: This script example: Comments Example PUTPROFILEDATA, PUTPROFILEDATA, 172 DCS Script Language Reference RANDOM The RANDOM (Range) RANDOM Arguments Example Result Range the numericvariable In thisexample: The result isaninteger value. random numberisgenerated. The Range %number =RANDOM(50)+1 function returns arandomnumberfrom 0(zero) to(Range-1),inclusive. argument isanintegerspecifyingtheupperlimitofrangefrom whichthe %number assumesarandomvalue from 1-50,inclusive. 2 Functions 173 argument specifies the numeric value to be converted.value numeric argument specifies the !num = REAL (10) DISPLAY (0,0) STR (!num, 4) Numeric function returns a real value corresponding to the specified numeric. to the specified corresponding value a real function returns These commands direct DCS to display the string “10.0000” in the session window. DCS to display These commands direct The result is a real numeric value corresponding to the specified numeric value. specified numeric to the value corresponding real numeric result is a The value, although either an real value to a This function is most useful for converting an integer may be specified. value integer or a real this example: In Numeric The Comments Example Arguments Result REAL REAL REAL (Numeric) REAL The REAL 174 DCS Script Language Reference RESULT The RESULT () RESULT Arguments: Example Comments Result The variable. a. The DCStocopytableonetherecordsinstructs from tablezero thatbeginwiththecharacter This setofcommands: assigned avalue equivalent totheerror message. assign avalue totheResult systemvariable the commandreference, you willalsoseenotationsofcommands,suchas RESULT The contentsofthe The result isastring value corresponding tothecontentsof RESULT Also see: DISPLAY “Morerecords” IF NUM(RESULT())>0 TABLE COPY0TO1INCLUDE“a” function returns thecontentsofResult systemvariable TABLE COPY command maybeusedtoassignavalue totheResult systemvariable. Throughout function takesnoarguments. ERROR SET RESULT Result commandassignsthenumberofcopiedrecords tothe function system variable maybemodified by several methods.The command
. If ataskerror occurs,theResult systemvariable is Result . system variable. TABLE COPY Result system SET , that 2 Functions 175
- Places argument evaluates to evaluates SET DECIMAL SET Boolean Boolean function is rounded down to the second decimal down function is rounded argument is not included, DCS rounds the real nu the real argument is not included, DCS rounds ROUND command has been executed, the default value of the the default value command has been executed, Places
) assumes the value “3.14”. assumes the value argument specifies whether to round or truncate the specified real round or truncateargument specifies whether to the specified !pi evaluates to TRUE, the numeric is rounded. If If the numeric is rounded. TRUE, to evaluates argument is a numeric specifying the number of decimal places to which specifying the number of decimal places argument is a numeric argument in the Boolean , SET DECIMAL SET REAL REAL Places Boolean Boolean Places argument is a real numeric specifying the number to be rounded. numeric argument is a real !pi = ROUND (3.141592654, 2, TRUE) function rounds the decimal places in the specified real numeric. in the specified the decimal places function rounds Real a copy of the place, and the variable The result is a real numeric value rounded to the specified decimal place. rounded to value real numeric result is a The of 5, decimal values For down. 3, and 4, the numeric is rounded of 0, 1, 2, decimal values For up. 6, 7, 8, and 9, the numeric is rounded this example: In The optional the numeric. If the real to round recently executed in the most meric to the number of decimal places specified no command. If argument is zero. Boolean The optional numeric. If the of the numeric is truncated. not included, the default value If FALSE, is TRUE. Real The Places Result Comments Example Arguments: ROUND ROUND (Real, ROUND The ROUND 176 DCS Script Language Reference ROUTE The ROUTE (FileSpec, ROUTE Arguments Result FileSpec function. attributes describedinthe The result isastring value specifying thefirstfilenameinargument included intheroute. the resulting onlythosefiles whoseattributeshave route. beenspecifiedwillbe Otherwise, If the To specifymultipleattributes,usethesumofallattributevalues asthe argument isanumericspecifyingthefileattributes(seealso The optional ATTRIBUTES Type string position. that stringposition.The(*)wildcard indicatesthat zero ormore characterscanoccupythat wildcard characters(?)and(*).Thewildcard indicatesthatanysinglecharactercanoccupy A FileSpec The FileSpec FileSpec = FileSpec function creates alistoffileswhichmatchthefilespecification. ATTRIBUTES Note: FileAttribute Value 64 32 no 16 Subdirectory 4 2 1 argument syntax: argument must contain at least one of the parts shownargument mustcontainatleastoneoftheparts above, andcancontainthe script. you willneedtoaddthevalues ofthestandard filestoany written underDCSAsynchronous, DCS/Elite oraDCSOpenConnect product, included whetherornottheirattributeswere specified. If you are usingascript This difersfrom previous versions ofDCS,inwhichstandard files were also ATTRIBUTES
argument isastringspecifyingthetypeoffilestoincludein route. drive:\path...\FileName.extension ATTRIBUTES Type clause isnotincluded,orzero, onlystandard fileswillbeincludedin opesdFl yes Compressed File Archived File System File Hidden File Read-Only File ATTRIBUTES clause indicateswhichfilestoincludeinthe route. The ) clause. Succeeding filesmaybefoundwiththe Standard File Standard yes no no yes ATTRIBUTES Type FileSpec Type arguments inthe function). with the argument. Type NEXT 2 Functions 177 function returns TRUE and the result is a null string. is a and the result TRUE function returns function ERROR display “^M” | “ =>” display $nextfile $nextfile = NEXT() BEGIN END NEXT NEXT While ($nextfile != “”) argument and includes the values of all standard files), and displays their names. The files), and displays their names. The of all standard argument and includes the values loop is designed to continue displaying the next file until the route is empty. route is next file until the loop is designed to continue displaying the $nextfile = NEXT() $pathname = “C:\” | ‘*.*’, 127) $nextfile = ROUTE($pathname Also see: Type Type continued establishes a route through all the directories and files in the root directoryroot and files in the (the sum 127 is all the directories through establishes a route the WHILE If no files match, the If This set of commands: Comments Example ROUTE, ROUTE, 178 DCS Script Language Reference SCREEN window. The SCREEN (Row, SCREEN Arguments Row window ofDCS. inclusion ofthisargumentallows ascriptinDCStoretrieve session astringfrom aparticular The optional WinHandle asexpected. perform include the If you usethe remainder ofthelineiscollected. data. If the The optional Length default columnoffsetof zero isassumed. data. Thefirstcolumnisconsidered column zero. If the The optional Column and bottomstatuslinesby usingthefollowing integersinthe For thoseemulationswhichdisplaydatainastatusline,thecanbecaptured from thetop considered row zero. The but not or Row SCREEN (1,,5) SCREEN (1,3) SCREEN (1,3,5,0x4BD3) Integer Status Line function retrieves ofalinedataatthespecifiedpositioninsession alineorportion Bottom -2 Top -1 argument isanintegerspecifyingtherow numberofthedesired data.Thefirst row is Column Length Column Length Column WinHandle Length argument isnotincluded,orif , argument, thescriptwillcompile,but argument isanumericspecifyingthelength(incharacters)ofdesired Length argument, you mustalsoinclude the argument isanintegerspecifyingthecolumnnumberofdesired argument is an integer specifying a particular windowargument isanintegerspecifying aparticular inDCS.The
, WinHandle (incorrect usage) (Row &Columnargumentsonly) (Row, Column,Length,& WinHandle arguments) ) Length Column exceeds thelengthofline, Column Row SCREEN argument isnotincluded,a argument: argument. If you donot function maynot 2 Functions 179 argument is not valid. WinHandle WinHandle assumes the string value of seven characters of screen data, starting data, characters of screen of seven assumes the string value assumes the string value of the first line of data on the screen. assumes the string value argument is not included in this function, DCS uses the window handle of in this function, DCS uses the window argument is not included $line $chars function returns TRUE if the TRUE function returns $line = SCREEN (0) $chars = SCREEN (1, 3, 7) WinHandle WinHandle continued ERROR In this example: In the string variable this example: In the string variable and fourth column. at the second row The result is a string value containing the window data within the specified area. data within the specified containing the window value a string result is The the If session window. the active The Result Comments Examples SCREEN, SCREEN, 180 DCS Script Language Reference SEARCH specified sessionwindow. The SEARCH ( SEARCH Arguments ato! Thisfunctioniscasesensitive. Caution! expected. If theyare notincluded,thescriptcompiles,but If you usethe characters inthewindow are examined. window tobeincludedinthesearch. If the The optional Length If you usethe columnofthesearch. column willbethestarting sition. Thefirstcolumnis0 (zero). Ifthe The optional Column ment isnotincluded,thefirst row row willbethestarting ofthesearch. from Thefirst which thesearch isperformed. row isconsidered row 0 (zero). Ifthe The optional Row but not or or Row (incorrect usage) SEARCH (1,,5,“Texas”) (Row, Column,&String argumentsonly) SEARCH (1,3,“Texas”) (Row, Column,Length,String, & WinHandle arguments) SEARCH (1,3,5,“Texas”,0x3AFF) (String argumentonly) SEARCH (“Texas”) function returns theabsolutepositionoffirstcharacterspecifiedstringin , Column Length Column Row Length Column argument isanintegerspecifyingtherow position offsetforthestarting , argument isanintegerspecifyingthenumberofcharactersin Length argument, you mustalsoinclude the argument is an integer specifying the column offset for the starting po argument isanintegerspecifyingthecolumnoffsetforstarting argument, you mustalsoinclude the
, String,
WinHandle
Length Column argument isnotincluded,allremaining SEARCH )
argument isnotincluded,thefirst Row Row function may not perform as function maynotperform and argument. Column arguments. Row argu - - 2 Functions 181 valid. not argument is assumes the value “84”. This value is derived value is derived “84”. This assumes the value WinHandle WinHandle %Position search the status line. search not argument is an integer identifying a particular window in DCS. The identifying a particularargument is an integer window begins on the second line (row one) at the fifth column (column begins on the second line (row argument is not included in this function, DCS uses the window handle for DCS uses the window argument is not included in this function, function does function returns TRUE if the TRUE function returns WinHandle WinHandle USER ID: argument specifies the string value for a case-sensitive search. a case-sensitive value for string argument specifies the %position = SEARCH (0, 0, “USER ID:”) %position = SEARCH (0, 0, WinHandle WinHandle continued SEARCH ERROR String (row * column width) + column In this example: In if the string four), and the column width is 80, (1 * 80) + 4 = 84. as follows: using the formula above The first row is row zero and the first column is column zero. If the string is not found, the If the string is not found, the zero. first column is column and the zero row row is The first is -1. result the If session window. the active The The String The WinHandle The optional a particular in DCS to search a script window. allows inclusion of this argument formula: value that is calculated using the following an integer result is The Example Comments Result SEARCH, SEARCH, 182 DCS Script Language Reference SEARCHINRECT area. It thenreturns thepositionoffirstcharacterstring. The SEARCHINRECT SEARCHINRECT Arguments Example Result TopRow, BottomRow, LeftCol,RightCol width of132,thefunctionreturns 1511,ormathematically, (11*132)+59. sixtieth column(column59)of thesessionscreen, andiftheterminalemulationhasacolumn column 80.If thefirstcharacterofstring a rectangular screen area issearched beginning atrow 10,column40,andendingatrow 15, In thisexample: (negative one). inthearea),defined by thefunction(orifstringisonlypartially thefunction returns -1 The first row is row zero andthefirstcolumnis zero. Ifthestringisnotin area of thefirstcharacter. Thepositioniscalculatedusingthefollowing formula: When thefunctionfindswholestringindefined area, thefunction returnstheposition inclusion ofthisargumentallows window. ascriptinDCStosearch aparticular The optional WinHandle The String mulation RightCol mulation the value oftheargument.Similarly, ifa a and columnsfortheemulation( the lower rightcharacterposition ofthescreen isspecified by themaximum numberof rows of thesessionscreen, where 0,0istheupperleftcharacterpositionofscreen, andwhere The TopRow (row *columnwidth)+ String TopRow SEARCHINRECT (10,15,40,80,”UserID:”) , thefunctionwilluse as thevalue oftheargument. argument isgreater than argument ora argument isthespecifiedstringforwhichDCStosearch. (TopRow, BottomRow, LeftCol,RightCol,String, , WinHandle BottomRow function searches foraspecifiedstringwithin rectangularscreen LeftCol argument is an integer identifying a particular windowargument isanintegeridentifyingaparticular inDCS.The , LeftCol MaxRowsInEmulation MaxRowsInEmulation argument thatislessthanzero, thefunctionwillusezero as MaxColsInEmulation , and RightCol BottomRow User ID: arguments are integersthatdefinea region argument isgreater than as thevalue oftheargument,andif , , thefunctionwilluse MaxColsInEmulation isinthetwelfth line(row 11)atthe WinHandle ). If you supply MaxColsInE MaxRowsInE ) - - 2 Functions 183 - - Date - function $to DATE DATE and then 1904. If you include the you 1904. If 1, $target_date functions. function also provides the time in the the function also provides function returns the current date. The the current function returns TIME function also provides the date in the proper the date in the proper function also provides TIME arguments. and DATE DATE argument must be in the time format indicated by the time format indicated by argument must be in DATE DATE Date DATE DATE argument. argument must be in the date format specified in your in argument must be in the date format specified Time Time and assumes the string value of the date, exactly 24 hours from of the date, exactly 24 hours from assumes the string value Time Time Date argument, DCS will use 00:00:00 AM (midnight). argument, DCS uses January Time Time Time Time Date ) argument is a string specifying the time to which the function should specifying the time to which the function argument is a string argument is a string specifying the date to which the function should calcu argument is a string specifying the date to $tomorrow 1, 1904 and the January number of seconds between the function returns Date Date Time Time , function then converts this date to seconds. The number of seconds from the function then converts this date to seconds. The number of seconds from the Finally, function is added to the number of seconds in one day. . Time IF SECONDS (DATE ()) >= SECONDS ($target_date) PERFORM update $tomorrow = DATE (SECONDS (TIME(),DATE ()) + 3600 * 24) $tomorrow = DATE (SECONDS (TIME(),DATE ()) + 3600 * SECONDS compares the current date with the target date specified by date with the target date specified the current compares accordingly. branches execution The string variable The string The innermost when the script line executes. SECONDS SECONDS to transforms the summation of seconds to the date of the next and assigns the result morrow This command: The result is an integer representing number of seconds elapsed from 12:00:00 AM, Janu number of seconds elapsed from representing result is an integer The and due to the ary be a large integer, result may 1, 1904 to the specified time and date. The in result of the function is best used The number. sign extension, it may display as a negative comparisons or as an argument for the this example: In your Windows initialization file or registry. The registry. initialization file or Windows your format. proper do not include the you If Date The optional late the number of seconds. The The registry. initialization file or Windows format. do not include the you If must include the argument, you The the by time and date indicated Time The optional of seconds. The calculate the number Result Example Arguments SECONDS ( SECONDS SECONDS 184 DCS Script Language Reference SETTINGS The SETTINGS (Keyword, SETTINGS Arguments Keyword The Keyword KERMIT BINARYTRANSFERPARAMS BAUDRATE BACKSPACEKEY Keyword function returns values ofthecurrently selectedsessionproperties. argument mustbeoneofthekeywords below.
WinHandle
)
Returns thecurrentsettingforbaudrateasanumeric For useonlywiththeVT Seriesemulation. ( [ Description this function. turned. Parametersforthisprotocolcannotbeobtainedby If thecurrentprotocolisKermit,ERRORstringre binary transferprotocolyouhaveselected. string. Default setting:Delete( Returns either TRUE orFALSE, indicatingwhetherthe Returns astring. The syntaxofthestringdependsonwhich BACKSPACE] FALSE ) orBackspace( keyisconfiguredtooperateasDelete TRUE FALSE ). ) - 2 Functions 185 . File dialog ZModem tab > ZModem Settings File Transfers > Properties > Session If the current protocol is ZModem, a string is returned where If the current protocol to a each string element refers this dialog, open DCS and select display To control. > of this dialog. Figure 2.1 shows an example continued Description Keyword continued BINARYTRANSFERPARAMS, BINARYTRANSFERPARAMS, ZModem -
Figure 2.1 ZMo General dem settings SETTINGS, SETTINGS, 186 DCS Script Language Reference SETTINGS, Where: ZModem, BINARYTRANSFERPARAMS, continued Keyword Description Enabled Exist Yield Cons Max Error Timing Description Packet String Word START Enabled RETRIES MaxMAXConsCONS; YIELD Yield; ExistEXISTING; AUTO ZMODEM; PACKETSIZE Packet; TIMING Timing; ERRORCHECKError; Returned String: continued continued Valid values:ENABLED, DISABLED sending systeminitiatesatransfer. Indicates to/nottoautomaticallytransferfileswhena RENAME Valid values:RESUME, PROMPT, OVERWRITE, SKIP, transfer matchesafilenameonthereceivingsystem. Represents theactiontotakewhenfilename Windows’ resources. The higherthenumericvalue,longerDCScontrols Valid values:Numericcharacterstring ing tootherWindowsprocesses. Represents thenumberofpackettosendbeforeyield Valid values:Numericcharacterstring allow. Indicates the maximum numberof consecutive retries to Valid values:Numericcharacterstring Represents themaximumnumberofretriestoallow. Valid vaues: AUTO, CRC32,CRC16 Represents theERRORcheckingmethod. Valid values:STANDARD, TIGHT, LOOSE Represents time-outoption. Valid values:1K,512,256,128, AUTO Represents sizeoftransferpacket. -
- 2 Functions 187 - Ses > . File XYModem XYModem tab > File Transfers > dialog control. To see this dialog, select see this dialog, To dialog control. Properties > XModem or YModem is YModem, a string is XModem or If the current protocol element refers to a returned where each string Settings sion continued continued Description Keyword BINARYTRANSFERPARAMS, -
Figure 2.2 XYMo General dem settings SETTINGS, SETTINGS, 188 DCS Script Language Reference SETTINGS, Where: BINARYTRANSFERPARAMS, continued Size Yield Cons Max Error Timing Packet Option String Word TRIES MaxMAXConsCONS; YIELD Yield; Size Option; PACKETSIZE Packet; TIMING Timing; ERRORCHECKError; RE Returned string: or YMODEM, XMODEM continued Keyword Description YMODEM-G characters) NOKEEPSIZE (padthelastpacketoffilewithnull KEEPSIZE (maintainthesizeoforiginalfile) Valid values: Specifies to/nottopadthelastfilepacket. Windows’ resources. The higherthenumericvalue,longerDCScontrols Valid values:Numericcharacterstring ing tootherWindows’ processes. Specifies thenumberofpacketstosendbeforeityield Valid values:Numericcharacterstring to allow. Specifies themaximumnumberofconsecutiveretries Valid values:Numericcharacterstring Specifies themaximumnumberofretriestoallow. Valid values:CRCorCHECKSUM Specifies theERRORcheckingmethod. Valid values:STANDARD, TIGHT, LOOSE Specifies thetime-outoption. Valid values:1K,128, AUTO Specifies thesizeoftransferpacket. Valid values:XMODEM, YMODEM, YMODEM251, Specifies theXModemor YModemprotocoloption. Description continued
- - 2 Functions 189 - - Returns the current column to which text is wrapped for LOGTOFILE. Returns the current column to which text is wrapped for LOGTOFILE. Returns the current send delay units (measured in sixtieths of a Returns the number of buffer lines as a string. buffer Returns the number of Returns the current font and size of the session window in the form: fontname;fontsize. value of 0 indicates that no wrapping is performed. A bits in the communications parameters. one of the following Depending on the current emulation, returns IBM3270*, ATT4425*, ATT705, values: ADDSVP60, ANSI, ATT605, Tvi925, Tvi950, IBM3287*, IBM5250*, SCOANSI, TN6530-8*, TTY, (* only Wyse60. VT320, VT420, VT220, VT100, VT101, VT102, VT52, available as a client option) or NONE, depending on the HARDWARE, Returns either XONXOFF, current settings of the communications parameters. parameters. the current value of parity in the communication string can contain alphanumeric characters. Returns the line numbers selected in a session window by the SE LECTION command. second). bits in the Direct Serial parameters. Description Batch, or ZModem. (*only YModem XModem, IND$file*, IXF*, Kermit, option) available with a client of the current emulation (80, 132, or 180, Returns the column width for example). COM2, COM3, COM4; COM5, COM6, Returns NONE, COM1, (where the op COM7, COM8, or COM9; COMBIOS port extension UBNETCI port (where tional extension can be null, or ETHERTERM); is the name of a port is either 1 or 2); DEVICE name (where name device to use). the current value of data Returns either 4, 5, 6, 7, or 8, depending on Returns either 1, 1.5, or 2, depending on the current value of stop Depending on the current file transfer protocol selected, returns: Depending on the current Returns the current phone number used by the DIAL command. The command. the DIAL Returns the current phone number used by Returns the current retry delay in units of seconds. Returns either NONE, ODD, EVEN, MARK, or SPACE, depending on depending or SPACE, Returns either NONE, ODD, EVEN, MARK,
continued SENDDELAY STOPBITS TERMFONT WORDSWRAP FLOWCONTROL PARITY PHONENUMBER RETRYDELAY SELECTION DATABITS EMULATE Keyword BINARYTRANSFERS BUFFERLINES COLUMNS CONNECTOR SETTINGS, SETTINGS, 190 DCS Script Language Reference SETTINGS, Comments Result The the active sessionwindow. If the keyword listabove. The keywordresult isastring value, dependingontheparticular argument, as describedinthe The optional WinHandle ERROR WinHandle SOUND RETRY PASSTHROUGH OUTGOINGCR LOCALECHO LINEWRAP FKEYSSHOW CARRIERDETECT FALSE. The followingkeywordsreturnastringvalue,where1issaidtobe TRUE and0issaidtobe Keyword continued
WinHandle function returns TRUE ifthe
argument isnotincludedinthisfunction,DCSusesthewindow handlefor
argument is an integer and identifies a particular windowargument isanintegerandidentifiesaparticular inDCS. Returns 1ifincominglinesarewrappedpasttheendofsetting Returns 1ifthefunctionkeysarevisible,otherwiseitreturns0. Returns 1iflinefeedsareaddedtooutgoingcarriagereturns,other Returns 1ifcarrierdetectisenabled,otherwiseitreturns0. Returns 1ifretryisenabled,otherwiseitreturns0. where 0representsFALSE (ifitisnotenabled). driver supportsRawPassthroughMode,anditisenabled), wise itreturns0. returns 0. for columns,otherwiseitreturns0. Description Returns 1ifsoundisenabled,otherwiseitreturns0. Returns astringvalue,where1represents TRUE (ifyourprinter Returns 1iflocalechoofoutgoingcharactersisenabled,otherwiseit WinHandle argument isnotvalid. - 2 Functions 191 continued ZMODEM; PACKETSIZE 1K; TIMING LOOSE; ZMODEM; PACKETSIZE 1K; TIMING AUTOSTART ENABLED ERRORCHECK AUTO; SKIP EXISTING; DISPLAY SETTINGS (PASSTHROUGH) DISPLAY SETTINGS (BINARYTRANSFERPARAMS) DISPLAY SETTINGS the session window displays text that describes the parameters set for the current file transfer displays text that describes the parameters set for the current the session window in is displayed a string similar to the following is ZModem, protocol current the If protocol. the session window: In this example: In is enabled, or 0 Mode if Raw Passthrough is 1(one) window in the session displayed the value if not enabled. (zero) this example: In Example SETTINGS, SETTINGS, 192 DCS Script Language Reference STR The STR (Numeric, STR Arguments Example Comments Result Numeric window. the In thisexample: (zero) andDCSwouldonlydisplaythestring25insessionwindow. been specified,thenumberofdecimalplacestobeincluded inthestringwouldhave been0 If theoptional Note thatthe Precision be provided tothe The directs DCStodisplaythestring12345.000000insessionwindow. This command The The result isthestring value representation ofthe specified, thedefaultis zero. precision isthatspecified by the by the the stringrepresentation ofthe The optional Precision The function returns thestringvalue ofthespecifiednumeric. STR ROUND Precision Numeric DISPLAY (0,2)STR(DISKSPACE ()) DISPLAY (0,1)STR(!measurement,3) !measurement=ROUND(25.2314325,3) DISPLAY (0,0)STR(12345,6) SET function returns thestring value of Precision argument toaccuratelydisplaytherounded measurement tothree decimalplaces. DECIMAL Precision function returns thevalue 25.231,buttodisplaythisreal numberastringmust argument specifiesthenumerictobeconverted. Precision Precision argument canalsobeastringusinganyvalid Clanguageformatstring. DISPLAY command.If the ) argument indicatesthenumberofdecimalplacestobeincludedin argument matchesthatusedwiththe argument hadnotbeenspecified,andifno command. Therefore, the Numeric SET DECIMAL Precision argument. It overrides thecurrent formatspecified DISKSPACE command.If no Numeric argument isnotincluded,thedefault STR whichisdisplayed inthesession argument. function isusedwiththeoptional ROUND SET
SET DECIMAL function DECIMAL hasbeen had 2 Functions 193 - argument. String ”. ”. bcd cdefg ) assumes the string value “ assumes the string value “ assumes the string value argument is an integer specifying the desired length of the substring. If the substring. If length of argument is an integer specifying the desired Length $sub $sub Length argument is not included, the substring contains all characters from the start the all characters from argument is not included, the substring contains posi argument specifies a string from which the substring is obtained. which a string from argument specifies argument is an integer specifying the position of the character with which to begin specifying the position of the character argument is an integer function returns a portion of the specified string. function returns $sub = SUBSTR (“abcdefg”, 2, 3) $sub = SUBSTR (“abcdefg”, 3) $sub = SUBSTR (“abcdefg”, Start String Length In this example: In the string variable this argument: In the string variable The the substring. Length The optional the tion to the end of the string. to the specified portion of the value corresponding result is the string The String The Start Result Example Arguments SUBSTR SUBSTR (String, Start, SUBSTR The SUBSTR 194 DCS Script Language Reference SYSMETRICS The SYSMETRICS () SYSMETRICS Arguments Example Comments Result The that shows: returns theresult: In thisexample: The [ProductCode] isDCSeries. The result isastring value inthefollowing format: LocalFreeMemory,[WindowsMajorVersion][ProductCode] TotalDiskSpace,FreeDiskSpace;PercentMemoryInUse,GlobalFreeMemory, HorizontalDisplayResolution,VerticalDisplayResolution; SYSMETRICS and theproduct codeisDyna32. the current version of Windows is Windows 95; hasabout372Kfree; the localmemory hasabout32MBfree; is100%inuse,theglobalmemory memory the defaulthard drive hasabout 85MB offree diskspace; the defaulthard drive hasabout1.3GBofdiskspace; the displayresolution is1024by 768; 100,32985088,372736;[WIN95][DCSeries] 1275559936,84672512; 1024,768; $res =SYSMETRICS() function returns thecurrent systemparameters.
function takesnoarguments.
2 Functions 195 - - -
below for specific parameters and syntax. below command $current_task = SYSTEM (0x0001) $scriptpath = SYSTEM (0x0950) $exepath = SYSTEM (0x0951) This function returns the fully qualified path name of this script, without the file In the following example, the $scriptpath variable will contain the path of the This function returns the command line of the executing application. In the fol lowing example, the $exepath variable contains the path of the executable. This function creates two temporary zero-length files and returns a string con taining the file names separated by a comma. Definition The function returns the file name of the currently executing script. In the following example, the $current_task variable will contain the name of the executing script. name. currently executing script. arguments are specified by one or more integers or strings. See each entry or strings. integers in by one or more specified arguments are
Example SYSTEM n
P argument is specified by a hexadecimal value from the table below. value from by a hexadecimal argument is specified function returns a string describing information about operating system-level param system-level describing information about operating a string function returns 0x0950 0x0951 0x8000 SysNum 0x0001 This function does not apply to the IBM TN3270 emulation. not apply to the IBM This function does Also see: SysNum and are subject to change without notice. and are each entrySee in the table for an example of syntax. P1, P2, … The optional the table under result is always a string. The However, the most up-to-date. always document are The parameters listed in this electronic of DCS versions between universal not are please note that the parameters for this function SysNum The Note: Example Result Comments Arguments SYSTEM SYSTEM (SysNum P1, P2) SYSTEM The variables. eters and environment SYSTEM 196 DCS Script Language Reference SYSTEM, and usedinadialogroutine. In filenamesare thefollowing parsedfrom the example,thetemporary result ofthisfunction continued cancel file delete$tmp2 file delete$tmp1 wait resume dialog end dialog(,,250,100) “SYSTEM(0x8000)” parse $return$tmp1‘,’$tmp2 $return =system(0x8000) button (105,80,40,14)default“OK”resume edittext(10,50,200,14) “Filename2“$tmp2 edittext(10,30,200,14) “Filename1“$tmp1 $return edittext(10,10,200,14) “ReturnValue” 2 Functions 197 ) taskID $whoIam $whoIam = TASKLIST(-1) DIALOG $whoIam MESSAGE TASKFILE(NUM($whoIam)) MESSAGE "OK" RESUME BUTTON END DIALOG RESUME WAIT the path/filename of the running script. Displays Use the menu option Script: Status... to see a list of running scripts. the menu option Script: Status... Use command. also the SPAWN See command. TASKSTOP also the See function. TASKLIST also the See function. TASKNAME also the See taskID number. specifying teh script is an integer expression The taskID argument path/filename. A string containing the Comments Example: Arguments Result TASKFILE ( TASKFILE taskID. the path/filename of the given a string containing Returns TASKFILE 198 DCS Script Language Reference TASKLIST The TASKLIST function running scripts. returns alistofall TASKLIST ( Arguments Example: Comments Result The optional NumFlag of-1 returns onlythetaskIDofcurrent script. If noparameteris NumFlag Example Script2.dcptotest Script W DIALOG END BUTTON "OK" RESUME DIALOG (5,5)"Script2" 0x17FC,0x030C and0x17FC running scripts. runs anotherscript(Script2)andthendisplaysthelistof This For example: WAIT RESUME DIALOG END BUTTON "OK"RESUME MESSAGE $allScripts MESSAGE $whoIam DIALOG "Script1" = TASKLIST()$allScripts = TASKLIST(-1)$whoIam SPAWN "Script2" See alsothe TASKNAME function. See alsothe TASKFILE function. See alsothe TASKSTOP command. See alsotheSPAWN command. Use themenuoptionScript:Status... scripts. toseealistofrunning or commands. a numericrepresentation ifyou wishtousetheresult asanumericvalue withotherfunctions Because thevalue returned isastring,you must usetheNUMfunctiontochangestring the lasthandleinresulting string,willbefollowed by acomma. character from theset(0,1,2, 3,4,5,6,7,8,9,A,B,C,D,E,F).Eachnumber, except for representation ofeachscriptandhasthegeneralized formof0x****,where anasteriskisa The running scripts.Thestringisahexadecimal result isastringcomposedofthetaskIDall taskIDnumbersisreturned.given, alist ofallrunning AIT RESUME -1 ) 1 2 Functions 199 ) taskID $whoIam $whoIam = TASKLIST(-1) DIALOG $whoIam MESSAGE TASKNAME(NUM($whoIam)) MESSAGE "OK" RESUME BUTTON END DIALOG RESUME WAIT the filename of the running script. Displays Use the menu option Script: Status... to see a list of running scripts. the menu option Script: Status... Use command. also the SPAWN See command. TASKSTOP also the See function. TASKFILE also the See function. TASKLIST also the See taskID number. specifying the script is an integer expression The taskID argument path/filename. A string containing the Comments Example: Arguments Result TASKNAME ( TASKNAME taskID. the path/filename of the given a string containing Returns TASKNAME 200 DCS Script Language Reference TIME Windows Control Panel. The TIME ( TIME Arguments Example Result Seconds Seconds If thesystemtimeis13:45:18, the Windows Control Panel. For example,thetimemighthave thefollowing format: The result isastringcontainingthetimeinformatspecified by thetimeformatchosenvia onds midnight, January 1,1904(seethe The optional function returns thetime,formattedaccording tothetimeformatyou have chosenviathe Hour:Minutes:Seconds argument, DCSreturns thecurrent systemtime. $time =TIME() ) Seconds argument isanintegerspecifyinganumberofseconds,where zero is $time SECONDS assumesthestringvalue 1:45:18 PM. function). If you have notincludedthe Sec - 2 Functions 201
function uses the system timer. TIMER argument is a numeric (from zero to three) specifying the desired timer. timer. specifying the desired to three) zero (from argument is a numeric assumes the string value 11:22:33. assumes the string value Index argument has a value greater than 3, the greater argument has a value ) $interval = TIMER (2) Index function returns the elapsed time since the last timer reset. DCS has access to four internal internal four to access has DCS reset. timer last the since time elapsed the returns function Hours:Minutes:Seconds Index If 11 hours, 22 minutes and 33 seconds have elapsed since the last reset of timer two, last reset elapsed since the 11 hours, 22 minutes and 33 seconds have If $interval The result is a string in the following format: result is a string in the following The the If Index The optional (0). zero to the value initialized All internal timers are Result Comments Example Arguments TIMER TIMER ( The a script). through timers (accessible only TIMER 202 DCS Script Language Reference TRIM The TRIM (String, TRIM Arguments Example Result String the tained alowercase “ the variable In thisexample: the stringvariable remove thefive trailingspacesandputtheleadingspace the string neither the the string“ In thisexample: Post The result isastring value corresponding tothe value ofthe characters. If you donotincludethe the endof The optional Post the characters. If you donotincludethe front ofthe The optional Pre The function removes charactersfrom thespecifiedstring. Pre Pre String character sequencesremoved. $newstring =TRIM(“ABCXXXXYZ”,“ABC”“XYZ”) $Str =TRIM(“Houston,Texas“) and argument andnothingistrimmedfrom thefront ofthe Pre Houston,Texas argument specifiesthestringtobetrimmed. Pre String $newstring Post Post , Post Pre String Post or argument isacase-sensitive stringspecifyingcharacterstodiscard from the argument andspacesare trimmedfrom theendof argument stringscontainonlyuppercase characters). $Str Post argument. Thisargumentspecifiesacharactersequence,notindividual argument isacase-sensitive stringspecifyingcharacterstodiscard from a ) ” argument. Thisargumentspecifiesacharactersequence,notindividual
and alowercase “ arguments are suppliedtothecommand, . assumesthestringvalue Pre Post y argument, anullstringisusedasthedefaultvalue of ” hasonespacebefore andfive spacesafterit. Since ”, argument, thespacecharacterisusedasdefault $newstring String XXX argument withthespecified . However iftheoriginalstringcon containstheoriginalstring(since String TRIM Houston,Texas argument. String function will argument. Pre and in - 2 Functions 203 , - , - TypeString TypeString TypeString TypeString n argument. Also, the parameters are argument. Also, the parameters are TypeString TypeString part of the arguments will be type cast according to the arguments will be type cast according n n that the calling convention be correct or unpredictable results will results or unpredictable be correct that the calling convention ParamType ParamType function returns a string representing the return value from a Dynamic from value the return string representing a function returns (LibName, ProcName, TypeString, Param1, Param2, ..., Param1, Param2, TypeString, (LibName, ProcName, argument is a string listing the type of the value that the library value argument is a string listing the type of the function argument is a string specifying the name of a function or procedure in the of a function or procedure argument is a string specifying the name argument is a string specifying the complete path name to the library. argument is a string specifying the complete function call. This function may be used to call functions from the Windows API Windows the may be used to call functions from function call. This function argument has the following general format: argument has the following very important name. If the name has an underscore as the first character (“_”), the C programming C programming as the first character (“_”), the underscore the name has an name. If is used. Otherwise,language convention will be called using the standard the function convention). to as the Pascal (sometimes referred (WINAPI) convention API Windows is It i.e., the application may crash. occur, The calling convention of the library of the routine The calling convention by the function being used is determined Param1, Param2, ...,Param ProcName TypeString LibName Param1, Param2, ..., Param ProcRetType=ParamType1, ParamType2, ..., ParamType ParamType2, ProcRetType=ParamType1, ) n separated by commas. separated by and then used as the parameters to the DLL function call. These parameters have a one-to-one and then used as the parameters to the DLL function call. These parameters have to the correspondence uses any parameters, then you must add an equal sign to the string followed by the types of the by must add an equal sign to the string followed uses any parameters, then you any of you may specify are types that the parameters with a comma. The parameters. Separate LPBYTE, LPD LONG, BYTE, types (BOOL, DWORD, SDK API Windows the standard as described in WORD) and VOID, UINT, LPSTR, LPWORD, LPLONG, LPINT, WORD, of these types can specify the type of and C language types (char and int). All WINDOWS.H, can specify the type of a parameter for a library function. VOID and all except value, a return information about these types. SDK for more Windows the See The The library. TypeString The The and the types of any parameters that the libraryreturns function requires. or the call may fail. The and parameters, in order, value return must match the DLL function’s TypeString If the DLL function ProcRetType. in all cases is required The only element of the string that is LibName The ProcName Note: Arguments TYPEDLIBRARYCALL TYPEDLIBRARYCALL TYPEDLIBRARYCALL Param The Link Library (DLL) name extension DLL, some of the DLLs the file have that while most DLLs other DLLs. Note or from De Software Windows Refer to the extension EXE. the file name have API Windows the that provide Link Libraries. of Dynamic information on the use and development more Kit (SDK) for velopment TYPEDLIBRARYCALL 204 DCS Script Language Reference TYPEDLIBRARYCALL, Examples Result Dynamic Link Library (DLL)functioncall. Dynamic LinkLibrary The script languagevariable with“the value is365”. eters andone“ parameters, andalsoaLONG inthiscase,sothe eString which isin This exampleusesthe‘C’callconvention tocallthe Windows API function This examplecallsthe Windows API function MessageBeep, whichisinUSER32.dll. TYPEDLIBRARYCALL %ld”, %value)) printf”, \ %Length =Num(TypedLibraryCall(“user32.dll”,“_ws “Bool=UINT, 0) \ “MessageBeep, (“user32.dll”, = TypedLibraryCall $Result indicates an“int” return type.TheAPI functionexpectstwolong pointerstostringsas USER32.dll LONG “int=LPSTR, LPSTR,LONG”,$Output,“thevalueis ”, separatedby commas.If %value is365,theAPI willfillthe
. TheAPI function returns aClanguageinteger value, sothe continued function returns astringrepresenting thereturn value from a TypeString indicates two“ LPSTR wsprintf $Output ” param - Typ , - -
2 Functions 205 argument, with all characters converted String assumes the string value “HOUSTON, TEXAS”. “HOUSTON, assumes the string value $city argument specifies the string to be convertedargument specifies the to uppercase. $city = UPPER (“Houston, Texas”) function returns the specified string with the characters converted to their uppercase specified string with the characters converted the to their uppercase function returns String The result is a string value corresponding to the value corresponding result is a string The to uppercase. this example: In the variable String The Example Arguments Result UPPER UPPER (String) The equivalents. UPPER 206 DCS Script Language Reference USERID The USERID () USERID Result Example Comments Note: The result isthecurrent value ofthe UserID system variable. Thestringcancontainalphanu sion window, DCSsendsthestringcontained intheUserID systemvariable tothehost. When thehostsendsusernameprompt andthestringUserName: isdisplayed intheses assumes theUserID systemvariable hasbeengiven avalue usingthe This example: Compare withthe meric characters.
function returns thecurrent value oftheUserID systemvariable. This functiondoesnotapplytotheIBM TN3270emulation. SEND UserID() WAIT STRING“UserName:” SET USERID command. SET USERID command. - - 2 Functions 207 function takes no arguments. function returns the current DCS version number. DCS version current the function returns dialog “ | version () message “Current version is: button “OK” resume dialog end wait resume VERSION In this example: In in a dialog box. of DCS is displayed version the current The running currently version number of the release containing the value a string result is The DCS program. Example Arguments Result VERSION VERSION ( ) VERSION The VERSION 208 DCS Script Language Reference VISIBLE DOW HIDE The VISIBLE (WinHandle) VISIBLE Arguments Example Comments Result WinHandle variable visible. If thewindow isvisible,theresult ofthe employs the This scriptexample: The the active childwindow. If the hidden by the A window isalwaysconsidered visible, even ifcompletelyobscured by otherwindows, unless window isvisible.If thefunctionevaluates toFALSE, thewindow ishidden. The result isaBoolean value indicatingifthewindow isvisible. If itevaluates to TRUE, the application window hasthehandlenumberzero. The command). ERROR WinHandle WinHandle function indicates whether a particular windowfunction indicateswhetheraparticular isvisible(ornothiddenwiththe $where =Position(%wnd) IF VISIBLE(%wnd) $where VISIBLE function returns TRUE ifthe WINDOW HIDE argument isanintegerexpression window. specifyingaparticular TheDCS . argument isnotincludedinthisfunction,DCSusesthewindow handlefor function todetermineifawindow designatedby thevariable command. WinHandle POSITION argument isnotvalid. function isplacedinthestring %wnd WIN is - 2 Functions 209 - argument is not valid. is a child window of the DCS application is a child window WinHandle %wnd argument is not included in this function, DCS uses the window handle for DCS uses the window argument is not included in this function, argument is an integer expression specifying a particular window handle. specifying a particular window expression argument is an integer function returns TRUE if the TRUE function returns function indicates whether a particular window is a child of the main DCS window. is a child of the main a particularfunction indicates whether window IF WINDOW (%wnd) WINDOW MINIMIZE %wnd WinHandle ERROR WinHandle if the window designated by the variable the variable designated by if the window bottom will be located near the window The icon for the minimized minimized. it is window, of the DCS application window. The result is a Boolean value, where TRUE indicates that the specified window is a child win that the specified window indicates TRUE value, where result is a Boolean The indicates that it is not. and FALSE of the main DCS window, dow the If child window. the active The this script example: In WinHandle The Comments Example Arguments Result WINDOW WINDOW (WinHandle) WINDOW The WINDOW 210 DCS Script Language Reference WINDOWHND Name The WINDOWHND (WinName) WINDOWHND Arguments Example Comments Result argument. WinName the window handleofthewindow titled“ In thisexample: (e.g., found willbereturned. If there are windows openwiththesamenamebutofadifferent type If there are multiplewindows openwiththesamename,window handleforthefirstone The The result isaninteger, whichisthewindow handleofthewindow. .dct, .dcm).Thisargumentcanbeinputwithorwithoutthefiletypeextension. title asdisplayed inthewindow titlebar, towhichDCSappendsthefiletypeextension(.ses, The ERROR WinName bbs.ses %hnd =WINDOWHND(“tr1”) function returns thehandleofwindow whosetitleisspecified by the function returns TRUE ifthe argument isastringexpression window specifyingaparticular title.Thisisthe and bbs.dcm ), thewindow handleforthefirstonefound willbe returned. tr1 WinName ” isassignedtothevariable argument isnotvalid. %hnd . Win - 2 Functions 211 argument. WinHandle ” is assigned to the variable ” is assigned to the variable 0xB4A argument is not valid. WinHandle argument is an integer and identifies a particular window in DCS. and identifies a particularargument is an integer window function returns the title of the window specified by the specified title of the window the function returns function returns TRUE if the TRUE function returns . $name = WINDOWNAME (0xB4A) ERROR WinHandle the path name of the window with the window handle “ with the window the path name of the window $name The result is a string, which is the name of the window. The in name is the fully qualified path name of session, script or memo files, and null The window the case of an untitled window. The this example: In WinHandle The Comments Example Arguments Result WINDOWNAME WINDOWNAME (WinHandle) WINDOWNAME The WINDOWNAME 212 DCS Script Language Reference WNDCLASS The WNDCLASS (WinHandle) WNDCLASS Arguments Example Comments Result WinHandle assigns anintegertothe This scriptexample: The The the result is-1(negative one). The result isaninteger value thatcorresponds tothewindow type. If The ERROR WinHandle WinHandle %WinType =WNDCLASS(%WND) Window Type Value 4 3 1 0 function returns theDCSwindow typeofaspecifiedwindow. function returns TRUE ifthe argument mustbeincludedwhenusingthisfunction. argument isanintegerexpression window. specifyingaparticular Memo window Script window Session window DCS mainwindow %WinType variable. Thisinteger represents thewindow type. WinHandle argument isnotvalid. ERROR is setto TRUE, 2 Functions 213 argument is not valid. WinHandle argument is an integer expression specifying a particular window. expression argument is an integer function returns TRUE if the TRUE function returns function retrieves the disk file name associated with the specified window. file name associated with the specified the disk function retrieves ERROR WinHandle The result is a string value that is the disk file name of the window. value result is a string The The WinHandle The Comments Arguments Result WNDFILE WNDFILE (WinHandle) WNDFILE The WNDFILE 214 DCS Script Language Reference WNDTITLE The WNDTITLE (WinHandle) WNDTITLE Arguments Example Comments Result WinHandle assigns thetitleofwindow designatedby thevariable This scriptsegment: Compare withthe The The result isastring value thatisthewindow title. The ERROR WinHandle $TITLE =WNDTITLE(%WND) function retrieves thewindow title. function returns TRUE ifthe argument isanintegerexpression window. specifyingaparticular SET WINDOWTITLE command. WinHandle argument isnotvalid. %WND tothevariable $TITLE . 2 Functions 215 - Win argument is not valid. WinHandle function evaluates to TRUE, and the window is is and the window TRUE, to function evaluates ZOOMED argument is not included in this function, DCS uses the window handle for DCS uses the window argument is not included in this function, argument is an integer expression specifying a particular window. Use a Use specifying a particular window. expression argument is an integer
function returns TRUE if the TRUE function returns of 0 (zero) to specify the main application window. to specify the main of 0 (zero) function indicates whether a particular window is maximized. a particularfunction indicates whether window IF ZOOMED (%WND) WINDOW RESTORE (%WND) WinHandle ERROR WinHandle In this example: In the is zoomed, if the window state. to its previous restored The result is a Boolean value, where TRUE indicates that the specified window is maximized, is maximized, indicates that the specified window TRUE value, where result is a Boolean The indicates that it is not. and FALSE the If child window. the active The WinHandle The Handle Comments Example Arguments Result ZOOMED ZOOMED (WinHandle) ZOOMED The ZOOMED 3 Commands
DCS 3 Commands 217 or loop is received ADVISE WHILE request is received request request is received request DDE REQUEST request is received request request is received request DDE ADVISE DDE EXECUTE DDE INITIATE DDE POKE Activates when a when Activates Sends a string of commands to the DDE server Sends Activates when a when Activates Requests data in the specified format from the DDE server data in the specified format from Requests Requests a single data item from the DDE server a single data item from Requests Specifies local variables to be created by a child routine by a child variables to be created local Specifies Activates when a when Activates Activates when a when Activates Sends the specified table to the DDE server Sends Sounds the default system .wav file a number of times the default system Sounds Sends a break signal to the remote system signal to the remote a break Sends Stores incoming characters in the specified string Stores Clears the screen and the historyClears the screen buffer REQUEST Cancels script execution Conditionally branches execution from a from Conditionally branches execution Establishes a connection with a remote system Establishes a connection with a remote Compiles the specified DCS script Creates the specified directory Creates Sends a table to a DDE client in response to an a table to a DDE client in response Sends Sets a connector parameter for the active session a connector parameter for the active Sets Specifies parameter used to configure the DCS application parameter used to configure Specifies Pauses execution until the next until the next execution Pauses Specifies the beginning of a command block the beginning of a command Specifies Sends a single data item to the DDE server Sends Concatenates two or more strings Concatenates two or more Terminates the active DDE conversation the active Terminates Initiates a DDE conversation Initiates
*
*
*
Commands flagged with an asterisk do not apply to the IBM TN3270 emulation. to the IBM do not apply flagged with an asterisk Commands
*
(DDE) TABLE REPLY (DDE) TABLE REQUEST (DDE) TABLE SEND (DDE) TABLE SIGNAL (DDE) WAIT (DDE) WHEN ADVISE (DDE) WHEN EXECUTE (DDE) WHEN INITIATE (DDE) WHEN POKE CONNECT CONTINUE DIRECTORY CREATE —D— (DDE) ACCESS (DDE) ACCESS CANCEL (DDE) INSTRUCT (DDE) POKE (DDE) REQUEST BREAK —C— CANCEL CLEAR COLLECT COMPILE CONCAT CONNCONFIG —A— APPCONFIG ARGUMENTS —B— BEEP BEGIN Note: Commands in Alphabetical Order Alphabetical in Commands 218 DCS Script Language Reference Commands in Alphabetical Order, DIAL DECREMENT DEBUG WHEN TERMINATE(DDE) (DDE) WHENREQUEST EDIT CUT EDIT COPYSPECIAL EDIT COPY —E— DROPDTR DISPLAYCONFIG DISPLAY DISCONNECT DIALOG UPDATE (DIALOG) RADIOGROUP (DIALOG) RADIOBUTTON (DIALOG) PICTURE (DIALOG) NEWLINE (DIALOG) MESSAGE (DIALOG) LISTBOX (DIALOG) ICONBUTTON (DIALOG) ICON (DIALOG) GROUPBOX (DIALOG) EDITTEXT (DIALOG) DIMENSION DIALOG CONTROL (DIALOG) CHECKBOX DIALOG CANCEL (DIALOG) BUTTON DIALOG *
*
*
*
Creates anedittextcontrol inadialogbox Writes allscriptcommandstothespecifiedfileasthey Implements the Displays atextmessageindialogbox Creates aradiobuttoncontrol inadialog box Displays thespecifiedpicture inadialog box Specifies thesize andpositionofacontrol inadialogbox Creates alistbox control inadialogbox Dials thespecifiednumberusingmodem Copies thespecifiedstringtoclipboard Holds theDTRlinelow forthecurrent serialport Positions thenextdialogcontrol onthenextlineof Creates adialogbox Cuts thecurrent selectionintheactive editwindow tothe Removes theactive dialogbox from thescreen Activates whena Defines agroup ofradiobuttoncontrols inadialogbox clipboard for thesessionwindow inthescriptlanguage string toaremote system) dialog box execute Decreases thevalue ofanintegervariable by one Changes thevisualcharactersofasessionwindow Updates apreviously defineddialogbox Terminates aconnectionwithremote system Updates theattributesofapreviously defineddialogcontrol Activates whenthecurrent DDEconversation isterminated Creates agroup box control inadialogbox Creates abuttoncontrol inadialogbox Creates aniconbuttoncontrol inadialogbox Displays astringinthesessionwindow (doesnotsendthe Displays thespecifiediconinadialogbox Creates acheckbox control inadialogbox continued Copy Special DDE REQUEST selectiononthe isreceived Edit menu 3 Commands 219 -
- - LOGTO LOGTO FILE PAUSE continued command command Disconnects the telephone line on the modem Disconnects Suspends the current text transfer initiated by a text transfer initiated by the current Suspends Positions the cursor at the beginning of the specified line the cursor at the beginning of the specified Positions Decrypts the specified encrypted readable to be file Encryptsunreadable the specified file to be Sets an emulator parameter for the active session for the active an emulator parameter Sets Copies the contents of the source file to the destination file Copies the contents of the source Sends the specified binary remote system Sends file to the Specifies the end of a command block the end of a command Specifies Specifies parameters for general session configuration op Specifies Renames the specified file Renames the the text transfer suspended by Resumes Prompts you for the name of a file to create for the name of you Prompts Branches execution to the specified target execution Branches binary format FILE command tions. another string FILE Searches the active edit window for the specified string edit window the active Searches Searches an edit window for a string and replaces it with for a string and replaces an edit window Searches Prepares DCS to receive the specified binary DCS to receive file Prepares Pastes text from the clipboard in the active edit window in the active the clipboard text from Pastes Starts a script and does not return to the calling script does not return a script and Starts Terminates the text transfer process initiated by a by initiated process the text transfer Terminates the specified file or directoryDeletes Converts a file from a seven data-bit ASCII format to a data-bit ASCII a seven Converts a file from Converts a binary data-bit ASCII format to a seven file a file to open for the name of you Prompts
*
*
*
*
FILE SEND BINARY —G— GENERALCONFIG GOTO —H— HANGUP FILE DECRYPT FILE DELETE FILE ENCRYPT FILE OPENNAME FILE PAUSE FILE RECEIVE BINARY FILE RENAME FILE RESUME —F— FILE CLOSE FILE COMPRESS FILE COPY FILE CREATENAME FILE DECOMPRESS EDIT FIND EDIT GOTO EDIT PASTE EDIT REPLACE EDIT EMULCONFIG END EXECUTE Commands in Alphabetical Order, Order, Alphabetical in Commands 220 DCS Script Language Reference Commands in Alphabetical Order, KERMIT COPY —K— INCREMENT IF —I— LOGTOFILE LOAD LINENUMBERS LIBRARY UNLOAD LIBRARY LOAD LIBRARY CALL LEVEL LEAVE LAUNCH —L— KEYMAP SAVE KEYMAP RESET KEYMAP LOAD KEYBOARD KEY KERMIT WHO KERMIT TYPE KERMIT RENAME KERMIT NEWDIRECTORY KERMIT MESSAGE KERMIT LOGOUT KERMIT HELP KERMIT FREESPACE KERMIT FINISH KERMIT ERASE KERMIT DIRECTORY
* * * *
* *
* *
* * * * Sends messagetoanaccountontheremote ashort system Removes thespecifiedDLLfrom memory Changes thecurrent onaremote working directory system Loads thespecifiedDLLintomemory Starts anotherapplication Sends aKermit logoutpackettotheremote Kermit server Issues the Changes thenameofafileon remote system Conditionally executes acommandblock Loads asessionfile Copies afileon remote hosttoanotherplaceonthe re Remaps agiven keycombinationtothespecified definition onaremoteLists thecontentsofadirectory system Increases thevalue ofaninteger variable by one Specifies agiven functionkeylevel Determines whetherornotkeystrokes are transmittedtothe local orremote system tion mote host Displays thecontentsofafilefrom the remote system Branches execution tothespecifiedDLLprocedure Saves thespecifiedkeymap Loads thespecifiedkeymap Saves incomingdatatoaspecifiedfile. Inserts linenumbersintoacompiledscript Sends aKermit finishpacket tothe remote Kermit server Displays thenumberoffree bytes ontheremote system Displays a summary ofatopicontheremoteDisplays system’s asummary opera Branches execution from acommandblock Deletes ona a file from directory remote system Locks andunlocksthekeyboard KERMIT WHO continued commandtotheremote system - - 3 Commands 221 - command) RECORD SCAN continued Removes a popup menu from the menu bar the menu from a popup menu Removes Changes the active print character characteristics Changes the active Defines a virtual record template for session window data template for session window record a virtualDefines Closes the open print channel and terminates any active any active Closes the open print channel and terminates Removes a menu item from a popup menu a popup a menu item from Removes Prints the specified string the specified Prints Adds a new popup menu to the menu bar Adds Terminates active print jobs active Terminates Adds a menu item to a popup menu a menu item to a popup Adds Updates a previously defined menu option, or group of op defined menu option, or group a previously Updates fields (used with the Adds a menu item separator to a popup menu Adds the string and succeeding characters from to the specified target execution Branches print jobs tions Sends the incoming session window data to the printer the incoming session window Sends Inserts a popup menu on the menu bar a Inserts Removes a script menu Removes Creates or modifies a menu or menu item or modifies Creates Inserts a menu item on a popup menu a Inserts Prints a file Prints Opens a print channel Opens Cancels all script execution and terminates the DCS session Cancels all script execution Sends a carriage return and line feed to the printer a carriage return Sends Locates a substring in another string, and stores preceding preceding stores Locates a substring in another string, and Suspends script command trace display Suspends Changes the active print font Changes the active Specifies the print tab width Specifies Sends a form feed to the printer Sends
*
RECORD FORMAT PRINT OPEN PRINT STRING PRINT STYLE PRINT TABS PRINT TERMINAL PRINT —Q— QUIT —R— PERFORM CANCEL PRINT CLOSE PRINT FILE PRINT FONT PRINT NEWLINE PRINT NEWPAGE PRINT (MENU) POPUP (MENU) SEPARATOR MENU UPDATE —N— NOSHOW —P— PARSE —M— MENU MENU CANCEL (MENU) DELETE ITEM (MENU) DELETE POPUP ITEM (MENU) INSERT POPUP (MENU) INSERT (MENU) ITEM Commands in Alphabetical Order, Order, Alphabetical in Commands 222 DCS Script Language Reference Commands in Alphabetical Order, RECORD WRITE RECORD SCAN RECORD READ SET BACKSPACEDESTRUCTIVE SET AUTOSIZE SET AUTOSCROLLTOCURSOR SET ATTRIBUTES SET APPTITLE SET SENDBREAK SEND SELECTION SEND SELECTION SAVE SELECTION PRINT SELECTION BUFFER SELECTION APPEND SELECTION SCROLL UP SCROLL RIGHT SCROLL LEFT SCROLL DOWN SCREEN SAVE —S— RETURN RESUME RESTART REMOVE DIRECTORY
*
*
*
* Sends abreak signaltotheremote system Displays thespecifiedstringinapplication’s titlebar Scroll up a specified number of lines in session history buffer Scroll upaspecifiednumberoflinesinsessionhistory Determines whetheremulationscrolling follows thecursor Retrieves datafrom thesessionwindow intoatabledefined Reads datafrom astructured ortexttableintoitsrecord Determines whetherthebackspacekeyis destructive Writes thecontentsofrecord buffertoastructured or Sends thecurrent selectiontotheremote system Specifies thesize andpositionofthesessionwindow (shows Scroll left a specified number of lines in session history buf Scroll leftaspecifiednumberoflinesinsessionhistory Saves thecurrent settingsfile Scroll down aspecifiednumberoflinesinsessionhistory Resumes scriptexecution pastthecurrent Determines thestatusof on the buffer fer buffer and hidesterminal;turnsonoffupdating) text table by the buffer Saves thecurrent selectiontothespecifiedfile Appends thecurrent selectiontothespecifiedfile Branches execution tothefirstlineofexecuting script Scroll right a specified number of lines in session history Scroll rightaspecifiednumberoflinesinsessionhistory Selects ablockinthesessionwindow Prints thecurrent selection Selects buffer theentire contentsofthehistory Deletes the specifieddirectory Assigns avalue tothespecified variable Modifies thefileattributesofspecified Resumes scriptexecution pastthecurrent Sends thespecifiedstringto remote system RECORD FORMAT Display continued tab ofthe Session Properties command Automatically Size PERFORM WAIT dialog checkbox - 3 Commands 223 - - - command DIAL DIAL string RESULT RESULT continued Appends line feed characters to outgoing carriage returns Appends Specifies the number of decimal places for string representa the number of decimal places for string Specifies Sets the timeout period for DDE commands Sets Changes the settings for a binaryChanges the settings transfer protocol Relinquishes Windows print channel Windows Relinquishes Sets the function keys to appear when file opened Sets the default phone number for the Specifies Shows and hides local keystrokes Shows Sets the directory of file location for a type Sets Sets the current binary the current or host environ transfer protocol Sets Specifies the amount of time to wait between transmitting the amount of time to wait between Specifies Sets the Raw Passthrough Mode for a printer Mode the Raw Passthrough Sets Specifies the character sent when the [Backspace] key is sent when the [Backspace] the character Specifies Specifies the number of columns in the session window Specifies Sets the carrier detect flag Sets Sets the delay time between dial attempts the delay time between Sets characters tions of real numbers tions of real sion pressed ment history buffer parties third Assigns a value to the Assigns a value redialing until connection whether to continue Specifies Changes the baud rate of the selected communications portChanges the baud rate Changes the value of the ConnectResult variable of the ConnectResult Changes the value Specifies the type of parity to be used during data transmis Specifies Loads the specified terminal emulation DLL Loads the specified terminal emulation system variable Changes the characters of the Password Specifies a handle for the default session window Specifies Sets the shape of the cursor and turns display on and off the shape of the cursor and turns display on Sets Specifies the number of lines in the session window and its session window the number of lines in the Specifies Book the Phone Changes the connection message from Specifies the desired flow control method control flow the desired Specifies Changes the characters of the NetID system variable Changes the characters of the NetID Sets the number of data bits to be used during transmission the number of data bits to be used during Sets Specifies a communications connector, including those from including those from a communications connector, Specifies
*
*
* * * * * *
* *
*
*
* * *
*
* * * SET SENDDELAY SET SET OUTGOINGCR SET PARITY SET PASSTHROUGH SET PASSWORD SET PHONENUMBER SET RESULT SET RETRY SET RETRYDELAY SET SET DEFAULTSESSIONHANDLE SET DIRECTORY SET EMULATION SET FKEYSSHOW SET FLOWCONTROL SET KEEPPRINTCHANNELOPEN SET LOCALECHO SET NETID SET SET CARRIERDETECT SET COLUMNS SET CONNECTION SET CONNECTMESSAGE SET CONNECTRESULT SET CURSOR SET DATABITS SET DDETIMEOUT SET DECIMAL SET SET BACKSPACEKEY SET BAUDRATE SET BINARYTRANSFERPARAMS SET BINARYTRANSFERS SET BUFFERLINES SET Commands in Alphabetical Order, Order, Alphabetical in Commands 224 DCS Script Language Reference Commands in Alphabetical Order, SET TERMFONT SET TERMCLOSE SET STOPBITS SET SOUND SET SIGNAL TRANSFERS TOOLBARSHOW TOOLBARHIDE TITLE TIMER RESET TASKERROR TABLE SORT TABLE SAVE TABLE LOAD TABLE DEFINE TABLE COPY TABLE CLOSE TABLE CLEAR —T— SYSTEM SWITCH SPAWN SHOW SETTINGS SET XSYSTEM SET XCLOCK SET WORDWRAP SET WINDOWTITLE SET WILDCARD SET USERID
*
*
*
*
*
*
Sets thenumberofstopbitsusedduringserialtransmissions Specifies parametersforfiletransferswitha3270command Allows ordisallows you toclosethesessionwindow Performs aspecialized systemoperation Specifies how longtowaitforan XCLOCK hostmessageto Exports thecontents ofthespecifiedtabletoafileor Exports Imports datafrom afileortheclipboard tothespecified Sets thecharactersrepresenting characters anyarbitrary Allows thesystembelltosoundwhenaconnectionismade Resumes commandauditinitiatedby Controls whether warningbellsfrom thehostare enabled Displays thespecifiedtoolbar. Clears anyexistingdatafrom thespecifiedtable Displays thespecifiedstringinactive window’s titlebar Specifies thefontdisplayed inthesessionwindow Specifies thecolumnatwhichtowrapincomingtext Starts current anindependentscriptwithoutinterrupting Closes thespecifiedtable processor file clipboard table script to clearbefore generatinganexecution error duringasend clear before generatinganexecution error during asend Changes thecharactersofUserID systemvariable Performs onthespecifiedtableusinggiven criteria asort Prepares atableforrandomaccessfileoperations Closes thespecifiedtoolbar. Assigns atitle,displayed intheapplicationtitlebar, toatask Resets thespecifiedtimer Allows you tomodifyoptionsona Copies thecontentsofagiven tabletothespecified Branches execution tomultiplecommandblocks Calls DCS’s internalexecution error handlingroutine Specifies how longtowaitforanXSYSTEMhostmessage continued Session Properties DEBUG command
tab 3 Commands 225 - - - WHEN WIN accesses a file command is executed commands RESUME LOGTOFILE LOGTOFILE WHEN continued command to the default handler for a window Activates when the specified screen region is modified the specified screen when Activates Pauses execution until a execution Pauses Conditionally continuously executes a logical command Conditionally continuously executes Hides the application window and its child window application window the Hides Maximizes the specified window Maximizes Closes the specified window Pauses execution until DCS receives a character until DCS receives execution Pauses until the specified time of day execution Pauses DOW nated ted received the specified string is when Activates RESUME character transmission terminal window Pauses script execution until specified character is received until specified character is script execution Pauses Activates when any character is received Activates Pauses execution while execution Pauses Passes a Windows message intercepted by the by message intercepted Windows a Passes Pauses execution until an amount of time elapses without execution Pauses Activates when the communications connection is termi when the communications connection is Activates is encountered error when an execution Activates Filters out Windows messages to child windows Windows out Filters Opens a memo window and pauses execution a memo window Opens received until a number of characters are execution Pauses received until the specified string is execution Pauses Pauses execution until after a specified amount of time or until after a specified amount of execution Pauses Activates after time elapses without character transmission Activates Activates storing screen data to a string storing screen Activates Brings the specified window into focus the specified window Brings Activates when a keystroke-generated character is transmit when a keystroke-generated Activates Cancels the specified Activates after the specified amount of time has elapsed after Activates Pauses execution until remote host changes the data in the until remote execution Pauses Tiles all open document windows Tiles
*
*
*
*
WHEN WINDOW* WHILE WINDOW ACTIVATE WINDOW ARRANGE WINDOW CLOSE WINDOW DEFAULT WINDOW HIDE WINDOW MAXIMIZE WHEN DISCONNECT WHEN ECHO WHEN ERROR WHEN INPUT WHEN QUIET WHEN SCREEN WHEN STRING* WHEN TIMER WAIT QUIET WAIT RESUME WAIT SCREEN WAIT STRING WAIT UNTIL WAIT WHEN CANCEL WHEN COLLECT —W— CHAR WAIT CLOSE WAIT DELAY WAIT ECHO WAIT EDIT WAIT PROMPT WAIT Commands in Alphabetical Order, Order, Alphabetical in Commands 226 DCS Script Language Reference Commands in Alphabetical Order, WINDOW RESTORE WINDOW OPEN WINDOW MOVE WINDOW MINIMIZE WINDOW MESSAGE XFERCONFIG —X— WINDOW UNHIDE WINDOW STACK
Sets asanicon DCStorun Opens window, anew oronecontaininganexistingfile Restores theDCSapplicationwindow toitspriorstate Sets afiletransferparameterfortheactive session Displays theapplicationwindow anditschildwindow Sends a Windows messagetothespecifiedwindow Stacks allopenwindows incascadefashion Moves andresizes thespecifiedwindow continued 3 Commands 227 loop is received WAIT PERFORM WHILE accesses a file is received request is received request request is received request DDE REQUEST request is received request request is received request LOGTOFILE DDE INITIATE DDE POKE DDE REQUEST DDE ADVISE DDE EXECUTE Resumes script execution past the current past the current script execution Resumes Branches execution to multiple command blocks execution Branches Branches execution from a command block from execution Branches Assigns a value to the specified variable to the specified Assigns a value Activates when a Activates Activates when a Activates Activates when the current DDE conversation is terminated DDE conversation when the current Activates Specifies local variables to be created by a child routine by a child variables to be created local Specifies Pauses script execution until specified character is received until specified character is script execution Pauses Specifies the end of a command block Specifies Activates when a Activates Pauses execution while execution Pauses Branches execution to the first line of the executing script to the first line of the executing execution Branches Branches execution to the specified DLL procedure execution Branches Branches execution to the specified target execution Branches Pauses execution until a character is received until a character execution Pauses RESUME Branches execution to the specified target execution Branches script Activates when a Activates Assigns a value to a RESULT string to a RESULT Assigns a value Starts an independent script without interrupting current interrupting an independent script without current Starts Activates when a Activates Conditionally branches execution from a from Conditionally branches execution Resumes script execution past the current past the current script execution Resumes Pauses execution until after a specified amount of time or until after a execution Pauses Starts a script and does not return to the calling script to the a script and does not return Starts Conditionally executes a command block Conditionally executes Suspends the current text transfer the current Suspends Pauses execution until the next execution Pauses Starts another application Starts Specifies the beginning of a command block the beginning of a command Specifies
Commands flagged with an asterisk do not apply to the IBM TN3270 emulation. TN3270 with an asterisk do not apply to the IBM Commands flagged
WAIT ECHO WAIT RESUME RETURN SPAWN SWITCH CHAR* WAIT CLOSE* WAIT DELAY WAIT END EXECUTE FILE PAUSE* GOTO IF LAUNCH LEAVE CALL LIBRARY PERFORM RESTART BEGIN CONTINUE SIGNAL (DDE) WAIT (DDE) WHEN ADVISE (DDE) WHEN EXECUTE (DDE) WHEN INITIATE (DDE) WHEN POKE (DDE) WHEN REQUEST (DDE) WHEN TERMINATE Note: Assignment Commands SET RESULT SET and Conditional Commands Branching, Subroutine, ARGUMENTS Commands by Category Commands 228 DCS Script Language Reference Commands byCategory, WAIT RESUME WAIT QUIET WAIT PROMPT* WAIT EDIT SET BINARYTRANSFERS GENERALCONFIG EMULCONFIG DISPLAYCONFIG CONNCONFIG APPCONFIG Configuration Commands END BEGIN Command BlockCommands WHILE WHEN WINDOW* WHEN TIMER WHEN STRING* WHEN SCREEN WHEN QUIET WHEN INPUT WHEN ERROR WHEN ECHO WHEN DISCONNECT WHEN COLLECT WHEN CANCEL WAIT UNTIL WAIT STRING* WAIT SCREEN
continued Pauses execution untilremote hostchangesthedatain Specifies thebeginningofacommandblock Activates afterthespecifiedamountoftimehaselapsed Specifies parameterusedtoconfigure theDCSapplication. Cancels thespecified Activates whenakeystroke-generated characteristransmit Sets aconnectorparameterfortheactive session Activates storingscreen datatoastring Activates aftertimeelapseswithoutcharactertransmission Filters out Windows messagestochildwindows Opens amemo window andpausesexecution Activates whenanexecution error isencountered Activates whenthecommunicationsconnectionistermi Pauses execution untiltimeelapseswithoutcharactertrans Activates whenanycharacterisreceived ment Sets transferprotocol orhost environ thecurrent binary tions Specifies parametersforgeneralsessionconfigurationop Activates whenthespecifiedstringis received ted nated terminal window Pauses execution untila mission Pauses execution untilthespecifiedtimeofday Pauses execution untilthespecifiedstringis received Pauses execution untilanumberofcharactersare received Changes thevisualcharactersofasessionwindow Specifies theendofacommandblock Conditionally continuouslyexecutes alogicalcommand Sets anemulatorparameterfortheactive session Activates whenthespecifiedscreen region ismodified WHEN RESUME commands command isexecuted - - - - - 3 Commands 229 -
- FILE PAUSE command to the remote system command to the remote KERMIT WHO KERMIT Sends the specified string to the remote system the specified string to the Sends Resumes the text transfer suspended by the the text transfer suspended by Resumes Stores incoming characters in the specified string Stores Changes the settings for a binary transfer protocol Saves incoming data to a specified file. incoming Saves Sends the specified binary remote system Sends file to the Lists the contents of a directory on a remote system Lists the contents of a directory on a remote Copies a file on a remote host to another place on the re place on the remote host to another Copies a file on a Sets a file transfer parameter for a session a file transfer parameter Sets Terminates the current text transfer being performed the current Terminates Loads the specified terminal emulation DLL Loads the specified Changes the name of a file on a remote system Changes the name of a file on a binary format command mote host system on the remote bytes the number of free Displays tion remote system the the contents of a file from Displays parties format to a data-bit ASCII a seven Converts a file from Issues the Issues Sends a Kermit logout packet to the remote Kermit server Kermit logout packet to the remote a Kermit Sends Prepares DCS to receive the specified binary DCS to receive file Prepares Changes the current working directory on a remote system directory working on a remote Changes the current Specifies a communications connector, including from third third including from a communications connector, Specifies Sends a short message to an account on the remote system a short message to an account on the remote Sends Sends the current selection to the remote system selection to the remote the current Sends Suspends the current text transfer being performed the current Suspends Deletes a file from a directory on a remote system a directory a file from on a Deletes Displays a summary of a topic on the remote system’s opera a summary system’s Displays of a topic on the remote Sends a Kermit finish packet to the remote Kermit serverremote finish packet to the a Kermit Sends Converts a binary data-bit ASCII format to a seven file Converts a binary data-bit ASCII format file to a seven continued
KERMIT LOGOUT* KERMIT MESSAGE* KERMIT NEWDIRECTORY* KERMIT RENAME* KERMIT TYPE* KERMIT WHO* KERMIT LOGTOFILE SELECTION SEND SEND BINARYTRANSFERPARAMS SET FILE SEND BINARY COPY* KERMIT DIRECTORY* KERMIT ERASE* KERMIT FINISH* KERMIT FREESPACE* KERMIT HELP* KERMIT COLLECT* FILE CLOSE* FILE COMPRESS FILE DECOMPRESS FILE PAUSE* FILE RECEIVE BINARY FILE RESUME* SET CONNECTION* SET EMULATION* SET XFERCONFIG Conversion Commands FILE COMPRESS Commands Data Transfer Commands by Category, by Category, Commands 230 DCS Script Language Reference Commands byCategory, SET PARITY* SET OUTGOINGCR* SET DATABITS* SET BINARYTRANSFERS DIALOG UPDATE (DIALOG) RADIOGROUP (DIALOG) RADIOBUTTON (DIALOG) PICTURE (DIALOG) NEWLINE (DIALOG) MESSAGE (DIALOG) LISTBOX (DIALOG) ICONBUTTON (DIALOG) ICON (DIALOG) GROUPBOX (DIALOG) EDITTEXT (DIALOG) DIMENSION DIALOG CONTROL* (DIALOG) CHECKBOX DIALOG CANCEL (DIALOG) BUTTON DIALOG Dialog Commands WAIT CLOSE* TRANSFERS SET XSYSTEM SET XCLOCK SET STOPBITS* SET SENDDELAY
continued Creates anedittextcontrol inadialogbox Specifies parametersforfiletransferswitha3270command Displays atextmessageindialogbox Appends linefeedcharacterstooutgoingcarriagereturns Creates aradiobutton control inadialogbox Displays thespecifiedpicture inadialogbox Specifies how longtowaitforan XCLOCK hostmessageto Creates alistbox control inadialogbox Specifies thesize andpositionofacontrol inadialogbox Specifies thenumberofstopbitstobeusedduringacon Sets thenumberofdatabitstobeusedduringserialtrans Creates adialogbox Positions thenextdialogcontrol onthenextlineof Removes theactive dialogbox from thescreen Defines agroup ofradiobuttoncontrols inadialogbox dialog box Displays thespecifiediconinadialogbox Creates acheckbox control inadialogbox processor to clearbefore generatinganexecution error duringasend clear before generatinganexecution error during asend nection characters mission ment Specifies theamountoftimetowaitbetween transmitting Specifies thetypeofparitytouseduringdatatransmission Sets transferprotocol orhostenviron thecurrent binary Updates apreviously defineddialogbox Pauses ascriptwhilethe Creates agroup box control inadialogbox Creates abuttoncontrol inadialogbox Creates aniconbuttoncontrol inadialogbox Updates theattributesofapreviously defineddialogcontrol Specifies how longtowaitforanXSYSTEMhostmessage LOGTOFILE commandaccessafile - - - 3 Commands 231 or menu ADVISE Edit Edit is received request is received request request is received request request is received request selection on the request is received request DDE EXECUTE DDE POKE DDE REQUEST DDE ADVISE DDE INITIATE Copy Special Positions the cursor at the beginning of the specified line the cursor at the beginning Positions Sets the timeout period for DDE commands Sets Activates when a Activates Sends a string of commands to the DDE server a string of commands Sends Requests data in the specified format from the DDE server data in the specified format from Requests Activates when the current DDE conversation is terminated DDE conversation when the current Activates Requests a single data item from the DDE server from a single data item Requests Activates when a Activates Activates when a Activates Sends the specified table to the DDE server Sends Branches execution to the specified DLL procedure execution Branches Loads the specified terminal emulation DLL another string Activates when a Activates in the script language for the session window to the edit window selection in the active the current Cuts clipboard REQUEST Searches the active edit window for the specified string for edit window active the Searches Activates when a Activates Searches an edit window for a string and replaces it with for a string and replaces edit window an Searches Copies the specified string to the clipboard Pastes text from the clipboard in the active edit window in the active the clipboard text from Pastes Implements the Implements Sends a table to a DDE client in response to an in response a table to a DDE client Sends Pauses a script until a client receives another DDE request a script until a client receives Pauses Starts another application Starts Loads the specified DLL into memory Sends a single data item to the DDE server a single data item to Sends Terminates the active DDE conversation the active Terminates Removes the specified DLL from memory the specified DLL from Removes Initiates a DDE conversation Initiates continued
EDIT COPY EDIT COPYSPECIAL* EDIT CUT EDIT FIND EDIT GOTO EDIT PASTE EDIT REPLACE EDIT LAUNCH DDETIMEOUT SET Dynamic Link Library Commands CALL LIBRARY LOAD LIBRARY UNLOAD LIBRARY EMULATION* SET Edit Commands (DDE) TABLE REQUEST (DDE) TABLE SEND (DDE) TABLE SIGNAL (DDE) WAIT (DDE) WHEN ADVISE (DDE) WHEN EXECUTE (DDE) WHEN INITIATE (DDE) WHEN POKE (DDE) WHEN REQUEST (DDE) WHEN TERMINATE Dynamic Data Exchange (DDE) ACCESS (DDE) ACCESS CANCEL (DDE) INSTRUCT (DDE) POKE (DDE) REQUEST REPLY (DDE) TABLE Commands by Category, by Category, Commands 232 DCS Script Language Reference Commands byCategory, SELECTION BUFFER SELECTION APPEND SELECTION PARSE SELECTION APPEND SAVE REMOVE DIRECTORY* PRINT FILE LOGTOFILE LOAD FILE SENDBINARY FILE RESUME* FILE RENAME FILE RECEIVEBINARY FILE PAUSE* FILE OPENNAME FILE ENCRYPT FILE DELETE FILE DECRYPT FILE DECOMPRESS FILE CREATENAME FILE COPY FILE COMPRESS FILE CLOSE* EDIT COPYSPECIAL* CREATE DIRECTORY* File Commands WAIT EDIT TABLE SORT SET WILDCARD*
continued Prompts you forthenameofafiletoopen filetoaseven data-bitASCIIformat abinary Converts Suspends atexttransfercommanduntil Converts afilefromConverts aseven data-bitASCIIformattoa Locates asubstringinanotherstring,andstores preceding Saves thecurrent settingsfile Deletes thespecifiedfileordirectory Implements the Loads asessionfile Prints afile Prepares file DCStoreceive abinary Opens amemo window andpausesexecution untilitis Sets thecharactersrepresenting characters anyarbitrary command executes format binary VIEW TEXT FILE closed and succeedingcharactersfrom thestring Terminates by a atexttransferperformed Appends thecurrent selectiontothespecified file Creates thespecifieddirectory Appends thecurrent selectiontothespecifiedfile Performs onthespecifiedtableusinggiven criteria asort Prompts you forthenameofafiletocreate Selects ablockinthesessionwindow Renames thespecifiedfile Selects buffer theentire contentsofthehistory Sends the specified binary filetotheSends remotesystem thespecifiedbinary Saves incomingdatatoaspecifiedfile. Copies thecontentsofsource filetothedestination Encrypts thespecifiedfiletobeunreadable Encrypts filetobe readable thespecifiedencrypted Decrypts Resumes thetexttransfersuspendedby the Deletes thespecifieddirectory Copy Special command selectiononthe FILE RESUME LOGTOFILE FILE PAUSE Edit menu or
3 Commands 233 - closes its file LOGTOFILE Inserts a menu item on a popup menu Inserts Modifies the file attributes of the specified file the file attributes of the Modifies Hides a specified toolbar a specified Hides Adds a new popup menu to the menu bar Adds Pauses execution until execution Pauses Sets the directory location for a type of file Sets a menu item to a popup menu Adds Decreases the value of an integer variable by one by of an integer variable the value Decreases Updates a previously defined menu option, or group of op defined menu option, or group a previously Updates Closes the specified window and prompts you to save any you to save and prompts Closes the specified window Saves the current selection to the specified file selection to the current Saves Adds a menu item separator to a popup menu Adds parties Removes a popup menu from the menu bar a popup menu from Removes tions a specified toolbar Displays Prepares a table for random access file operations a table for random Prepares table clipboard changes Removes a script menu Removes a popup menu a menu item from Removes Increases the value of an integer variable by one by of an integer variable the value Increases or modifies a menu or menu item Creates Opens a memo window and pauses execution a memo window Opens Changes the characters of the NetID variable Changes the characters of the NetID Specifies a communications connector, including from third third including from a communications connector, Specifies Imports data from a file or the clipboard to the specified to the specified a file or the clipboard data from Imports Exportsa file or the the contents of the specified table to Opens a new window, or one containing an existing file a newOpens window, Inserts a popup menu on the menu bar a popup menu on the Inserts continued
(MENU) SEPARATOR MENU UPDATE TOOLBARHIDE TOOLBARSHOW Network Commands CONNECTION* SET NETID* SET Menu & Toolbar Commands Menu & Toolbar MENU MENU CANCEL MENU DELETE ITEM MENU DELETE POPUP ITEM MENU INSERT POPUP MENU INSERT (MENU) ITEM (MENU) POPUP WAIT CLOSE* WAIT EDIT WAIT WINDOW CLOSE WINDOW OPEN Math Commands DECREMENT INCREMENT SELECTION SAVE ATTRIBUTES SET DIRECTORY SET DEFINE TABLE LOAD TABLE SAVE TABLE Commands by Category, by Category, Commands 234 DCS Script Language Reference Commands byCategory, PRINT CLOSE PRINT CANCEL EDIT COPYSPECIAL* Print Commands TASKERROR SPAWN SHOW SET RESULT RESTART QUIT PERFORM NOSHOW LINENUMBERS EXECUTE DEBUG COMPILE CANCEL Script ControlCommands SET PASSTHROUGH* SET KEEPPRINTCHANNELOPEN SELECTION PRINT PRINT TERMINAL* PRINT TABS PRINT STYLE PRINT STRING PRINT OPEN PRINT NEWPAGE PRINT NEWLINE PRINT FONT PRINT FILE
continued
Sends aformfeedtotheprinter Writes allscriptcommandstothespecifiedfileasthey Specifies theprinttabwidth Changes theactive printfont Suspends scriptcommandtracedisplay Resumes commandauditinitiatedby Sends acarriagereturn andlinefeedtotheprinter Cancels allscriptexecution andterminatestheDCSsession Opens aprintchannel Implements the Starts ascriptanddoesnotreturn tothecallingscript Prints thespecifiedfile Compiles thespecifiedDCSscript Cancels scriptexecution Starts current anindependentscriptwithoutinterrupting script Assigns avalue totheRESULT systemvariable TURN Starts ascriptandreturns tothecallingscript whena execute Prints thespecifiedstring print jobs Branches execution tothefirstlineofexecuting script Sends theincomingsessionwindow datatotheprinter Terminates active printjobs Prints thecurrent selection Relinquishes Windows printchannel Inserts linenumbersintoacompiledscript Sets theRawPassthrough Mode foraprinter Closes theopenprintchannelandterminatesanyactive Changes theactive printcharacter characteristics Calls DCS’s internal execution error handlingroutine executes Copy Special selectiononthe DEBUG command Edit menu RE - 3 Commands 235 - menu check box check box command Edit Edit dialog DEBUG selection on the Automatically Size Automatically Session Properties Session Copy Special tab of the Display Display Activates when the specified screen region is modified the specified screen when Activates Displays a string in the session window (does not send the a string in the session window Displays Displays a string in the session window (does not send the (does not window a string in the session Displays Stores incoming characters in a specified string Stores Loads the specified keymap Loads the specified Determines the status of the Determines Scroll right a specified number of lines in session history right a specified number of lines in session Scroll Changes the visual characters of a session window Changes the visual characters Clears the screen and the history and Clears the screen buffer Specifies the number of columns in the session window Specifies string to the remote system) string to the remote buffer fer buffer on the history buffer the column at which to wrap incoming text Specifies string to a remote system) string to a remote the specified keymap Saves and hides terminal; turns on and off updating) Specifies the font displayed in the session window the font displayed Specifies Determines whether the backspace key is destructive Determines Scroll down a specified number of lines in session history a specified number of lines in session down Scroll Implements the Implements Suspends command audit initiated by command audit initiated by Suspends Scroll left a specified number of lines in session history left a specified number of lines in session Scroll buf Specifies a handle for the default session window Specifies Specifies the size and position of the session window (shows (shows of the session window and position the size Specifies Sets the shape of the cursor and turns display on and off Sets Specifies the number of lines in the session window and its the number of lines in the session window Specifies Determines whether emulation scrolling follows the cursor follows whether emulation scrolling Determines Scroll up a specified number of lines in session history up a specified number of lines in session Scroll buffer Concatenates two or more strings Concatenates two or more Allows or disallows you to close the session window you or disallows Allows continued
*
SET TERMCLOSE SET TERMFONT SET WORDWRAP* SET WHEN SCREEN String Commands COLLECT* CONCAT DISPLAY SCROLL UP SCROLL AUTOSCROLLTOCURSOR SET AUTOSIZE* SET BACKSPACEDESTRUCTIVE SET BUFFERLINES SET COLUMNS SET CURSOR SET DEFAULTSESSIONHANDLE SET NOSHOW SCREEN DOWN SCROLL LEFT SCROLL RIGHT SCROLL Session Window Commands Session Window CLEAR DISPLAY DISPLAYCONFIG COPYSPECIAL* EDIT LOAD KEYMAP SAVE KEYMAP Commands by Category, by Category, Commands 236 DCS Script Language Reference Commands byCategory, WAIT STRING* SET DECIMAL PRINT STRING PARSE RECORD SCAN RECORD READ RECORD FORMAT TABLE(DDE) SEND TABLE(DDE) REQUEST TABLE(DDE) REPLY Table Commands TITLE TIMER RESET SYSTEM* SET USERID* SET PASSWORD* SET NETID* SET FKEYSSHOW SET CONNECTRESULT* SET CONNECTMESSAGE* LEVEL KEYMAP RESET KEYBOARD KEY FKEYS BEEP* System Commands WHEN STRING*
continued Retrieves datafrom thesession window intoatabledefined Reads datafrom astructured ortexttableintoitsrecord Sends atabletoDDEclientinresponse toan Locates asubstringinanotherstring,andstores preceding Performs aspecialized systemoperation Remaps agiven keycombinationtothespecified definition Shows andhidesthefunctionkeys Changes theconnectionmessagefrom thePhone Book Specifies agiven functionkeylevel Determines whetherornotkeystrokes are transmittedtothe by the buffer fields (usedwiththe REQUEST file Resets thespecifiedtimer Changes thecharactersofNetID systemvariable Changes thevalue oftheConnectResult variable local orremote system Locks andunlocksthekeyboard Activates whenthespecified string is received tions ofreal numbers and succeedingcharactersfrom thestring Changes thecharactersofPassword systemvariable Pauses execution untilthespecifiedstringis received Sends thespecifiedtabletoDDEserver Sets thefunctionkeystoappearwhenfileopened Prints thespecifiedstring Requests datainthespecifiedformatfrom theDDEserver Changes thecharactersofUserID systemvariable Specifies thenumberofdecimalplacesforstring representa Defines a virtual Defines avirtual record templateforsessionwindow data Assigns atitle,displayed inthe applicationtitlebar, toatask Sounds thedefaultsystem.wavfileanumberoftimes RECORD FORMAT RECORD SCAN command command) ADVISE or - 3 Commands 237 - - command to the remote system command to the remote KERMIT WHO KERMIT Copies the contents of a given table to the specified table of a given Copies the contents Sends a break signal to the remote system signal to the remote a break Sends Displays the contents of a file from the remote system the the contents of a file from Displays Terminates a connection with a remote system with a remote a connection Terminates Prepares a table for random access file operation a table for random Prepares Holds the DTR line low for the current serial port for the current the DTR line low Holds Dials the specified number using the modem Dials Copies a file on a remote host to another place on the re place on the remote host to another Copies a file on a Performs a sort a criteria on the specified table using the given Performs Changes the name of a file on a remote system Changes the name of a file on a Sets an emulator parameter for the active session an emulator parameter for the active Sets mote host system Lists the contents of a directory on a remote tion system directory working on a remote Changes the current text table clipboard Closes the specified table Closes the specified Issues the Issues Sends a Kermit logout packet to the remote Kermit server Kermit logout packet to the remote a Kermit Sends Establishes a connection with a remote system Establishes a connection with a remote Clears any existing data from the specified table the specified from Clears any existing data Determines whether the backspace key is destructive Determines Sends a break signal to the remote system signal to the remote a break Sends Sends a short message to an account on the remote system a short message to an account on the remote Sends Disconnects the telephone line on the modem Disconnects Sets a connector parameter for the active session a connector parameter for the active Sets Writes the contents of the record buffer to a structured or or to a structured buffer contents of the record the Writes Imports data from a file or the clipboard to a table a file or the clipboard data from Imports Exportsa file or the the contents of the specified table to Deletes a file from directory on a remote system directory a file from on a Deletes Displays a summary of a topic on the remote system’s opera a summary system’s Displays of a topic on the remote Displays the number of free bytes on the remote system on the remote bytes the number of free Displays Sends a Kermit finish packet to the remote Kermit serverremote finish packet to the a Kermit Sends continued
*
KERMIT LOGOUT* KERMIT MESSAGE* KERMIT NEWDIRECTORY* KERMIT RENAME* KERMIT TYPE* KERMIT WHO* KERMIT SENDBREAK* BACKSPACEDESTRUCTIVE SET DROPDTR* EMULCONFIG HANGUP* COPY* KERMIT DIRECTORY* KERMIT ERASE* KERMIT FINISH* KERMIT FREESPACE* KERMIT HELP* KERMIT TABLE SORT TABLE Commands Telecommunications BREAK* CONNCONFIG CONNECT DIAL* DISCONNECT RECORD WRITE CLEAR TABLE CLOSE TABLE COPY TABLE DEFINE TABLE LOAD TABLE SAVE TABLE Commands by Category, by Category, Commands 238 DCS Script Language Reference Commands byCategory, SET BINARYTRANSFERS SET BINARYTRANSFERPARAMS SET BAUDRATE* SET BACKSPACEKEY* WAIT STRING* WAIT SCREEN WAIT QUIET WAIT PROMPT* WAIT ECHO SETTINGS SET XSYSTEM SET XCLOCK SET STOPBITS* SET SOUND SET SIGNAL* SET RETRYDELAY* SET RETRY* SET PHONENUMBER* SET PARITY* SET OUTGOINGCR* SET NETID* SET LOCALECHO* SET FLOWCONTROL* SET EMULATION* SET DATABITS* SET CONNECTRESULT* SET CONNECTMESSAGE* SET CONNECTION* SET CARRIERDETECT*
*
continued Specifies thedefaultphonenumberfor Pauses execution untilremote hostchangesthedatain the Appends linefeedcharacterstooutgoingcarriagereturns Specifies how long towaitforan XCLOCK hostmessageto Changes the settings for a binary transferprotocol Changes thesettingsforabinary Controls whetherwarningbellsfrom thehostare enabled Specifies acommunicationsconnector, includingfrom third Sets thenumberofstopbitsusedduringserialtransmissions Sets thenumberofdatabitstobeusedduringtransmission Changes thecharactersofNetID systemvariable Specifies thedesired flow control method Pauses execution untilanamount oftimeelapseswithout Changes theconnectionmessagefrom thePhone Book Allows thesystembelltosoundwhenaconnectionismade terminal window character transmission Pauses execution untilanumber ofcharactersare received to clearbefore generatinganexecution error duringasend clear before generatinganexecution error duringasend sion parties ment pressed Loads thespecifiedterminalemulationDLL Pauses execution untilDCS receives acharacter Specifies thetypeofparitytobeusedduringdatatransmis Sets transferprotocol orhostenviron thecurrent binary Pauses execution untilthespecifiedstringis received Changes thevalue oftheConnectResult variable Specifies whethertocontinue redialing untilconnection Changes thebaudrateofselectedcommunicationsport Sets thedelaytimebetween dialattempts Sets thecarrierdetectflag Specifies thecharactersentwhen[Backspace] keyis Shows andhideslocalkeystrokes Allows you tomodifyoptionsona Specifies how longtowaitforanXSYSTEMhostmessage Session Properties DIAL command tab - - 3 Commands 239 - - - WHEN WIN command to the default handler for a window Moves and resizes the specified window resizes and Moves Hides the application window and its child window the application window Hides Sends a Windows message to the specified window message Windows a Sends in cascade fashion all open windows Stacks Changes the visual characters of a session window Changes the visual characters of a session Displays the application window and its child window the application window Displays Maximizes the specified window the specified Maximizes Sets a file transfer parameter for a session a file transfer parameter Sets Brings the specified window into focus the specified window Brings Closes the specified window DOW nated ted received is when the specified string Activates Activates when any character is received when any character is Activates Passes a Windows message intercepted by the by message intercepted Windows a Passes Activates when the communications connection is termi when the communications Activates Displays the specified string in the active window’s title bar window’s the specified string in the active Displays Filters out Windows messages to child windows Windows out Filters Activates after time elapses without character transmission after time elapses without Activates Restores the DCS application window to its prior state the DCS application window Restores Activates when a keystroke-generated character is transmit character when a keystroke-generated Activates Displays the specified string in the application’s title bar the specified string in the application’s Displays Opens a new window, or one containing an existing file a new Opens window, Sets DCS to run as an icon Sets Tiles all open document windows all Tiles continued
WINDOW UNHIDE WINDOW DEFAULT WINDOW HIDE WINDOW MAXIMIZE WINDOW MESSAGE WINDOW MINIMIZE WINDOW MOVE WINDOW OPEN WINDOW RESTORE WINDOW STACK Window Commands Window DISPLAYCONFIG APPTITLE SET WINDOWTITLE SET WHEN WINDOW* WINDOW ACTIVATE WINDOW ARRANGE WINDOW CLOSE WHEN DISCONNECT WHEN ECHO WHEN INPUT WHEN QUIET WHEN STRING* XFERCONFIG Commands by Category, by Category, Commands 240 DCS Script Language Reference APPCONFIG apply totheentire DCSapplication. The APPCONFIG String APPCONFIG Arguments DCS application. a valid setting. Together, thekeyword andthesettingare usedtoconfigure theoptionsfor The String String UserFontDir UserDisplayDir UserFileTransferDir UserEmulationDir UserConnectorDir UserMapDir UserMemoDir UserUpLoadDir UserDownLoadDir UserScriptDir UserSessionDir DefaultSesFileTransfer DefaultSesConnector DefaultSesEmulation Keywords forFileLocationstab EnableOLEStatusBar EnableOLEToolbar EnableOLEMenu ShowBkgrdBitMap Use SessionWizard ShowErrorMessages SaveAppPosition ConfirmMessages ShowSplashScr Keywords forGeneraltab command isusedtosetthevalue ofaparameterusedtoconfigure optionswhich argument represents asinglekeyword followed by theassignmentoperator(=)and
Valid Setting(s) string ofvalidpath string ofvalidpath string ofvalidpath string ofvalidpath string ofvalidpath string ofvalidpath string ofvalidpath string ofvalidpath string ofvalidpath string ofvalidpath string ofvalidpath indfile, kermit,wixfdll,zmodem comdir, comtapi,fmidll,merdnlat,telnet ibm3270,ibm5250, tandem,vt420 addsvp60, ansi,att605,att4425, Valid Setting(s) true,false 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false)
3 Commands 241 tabs of File Location File and General General keyword is invalid. keyword String function GETAPPCONFIG Changes made via scripting to application options remain in effect even after in effect even to application options remain Changes made via scripting DCS. closing and restarting
function returns TRUE if the TRUE function returns dialog . This command, therefore, allows you to set these parameters through the through you to set these parameters allows therefore, dialog . This command, continued APPCONFIG “UseSessionWizard=false” APPCONFIG “UserSessionDir=p:\public\usersess” APPCONFIG “UserDownloadDir=c:\windows\profiles\user1\download” Note: Also see: ERROR Options Options In this example: In is disabled, the default session file directory a mapped network is set to the session wizard folder on a local directory is set to a specific user’s location, and the default file download drive drive. The keywords correspond to parameters available in the available to parameters correspond The keywords the rather than using the dialog . DCS script language The Example Comments APPCONFIG, APPCONFIG, 242 DCS Script Language Reference ARGUMENTS The ARGUMENTS (Parameter, ...) ARGUMENTS Arguments Example Comments The (Parameter, ...) receive parametersfrom, norpassparametersto,aparent routine). null parameterlist(indicatingthevariables are nottobeusedasparameters,andwillneither In thisexample,DCScreates three localvariables. Thefirst In thisexample,DCScreates three localvariables thatmayalsobeusedtopassparameters. parameters toandfrom theparent routine. MENTS You maydefinemore thanone the parent routine, allvariables created by the be usedasparameterstopassvalues toandfrom aparent routine. When execution returns to If the more string,numeric,orBooleanvariables. (Parameter, ...) ARGUMENTS ARGUMENTS ($str1,$str2,%index) ARGUMENTS () *subroutine ARGUMENTS ($name,%amount,!value) *subroutine commands maybeusedtocreate variables, butonlythefirstonespecifiedmaypass command specifiesthenamesoflocal variables ascript routine uses.
argument specifiesthelocal variables ina routine. It consistsof zero or command isthefirstinchild routine, these variables may ARGUMENTS ARGUMENTS command inasingleroutine. All ARGUMENTS command are destroyed. command carriesa ARGU - 3 Commands 243 - from the PC’s speaker. the PC’s from in the active session win in the active OK drive, DCS displays drive, C: argument is not included, the system bell will ring once. argument is not included, argument is an integer specifying the number of times DCS will ring the specifying the number of times DCS argument is an integer Num resides at the root of the at the root resides Num This command does not apply to IBM TN3270 emulations. not apply to IBM This command does Display “OK” Else Beep 3 If Exists (“C:\TEXT.TXT”)
command rings the default system bell one or more times. default system bell one or more command rings the TEXT.TXT if times. the file is not found, the bell rings three If dow. If a sound driver is loaded, this command plays the default sound (or WAV file) through the file) through WAV is loaded, this command plays the default sound (or a sound driver If have or if you multimedia capability, computer does not have your If multimedia speaker. PC’s the default PC system bell will ring disabled the multimedia capability, this example: In Num The optional the system bell. If Num Note: Comments Example Argument BEEP BEEP BEEP BEEP The BEEP 244 DCS Script Language Reference BEGIN the commandblock. The BEGIN BEGIN Arguments Example The labeled string “ The commandblockexecutes afterthe BEGIN command specifiesthebeginningofablock.AnENDmustfollow END PERFORM no_carrier DISPLAY (0,0)“Connectionterminated” BEGIN WHEN DISCONNECT Connection terminated no_carrier command takesnoarguments. . The END command specifiestheendofblock.
WHEN DISCONNECT ” inthesessionwindow theroutine andthenperforms command.DCSdisplaysthe 3 Commands 245 - argu DelayUnits argument is an integer specifying the length of the breaksignal, specifying the length of the breaksignal, argument is an integer DelayUnits 2 30 Short Break (0.233 seconds) Long Break (3.5 seconds) SEND “password” BREAK 30 Delay Units Signal This command does not apply to IBM TN3270 emulations. not apply to IBM This command does command sends the break signal. break command sends the DelayUnits DCS sends the string password to the remote system, followed by a long break. by system, followed to the remote DCS sends the string password ment, DCS uses a default value of two (specifying a shortment, DCS uses a default value break). are: signals break the standard for representations The this example: In DelayUnits The optional do not include the you unit equals 117 milliseconds. If one delay where Note: Comments Example Arguments BREAK BREAK The BREAK 246 DCS Script Language Reference CANCEL The CANCEL CANCEL Arguments Example Comments The execution doesnotcontinueifcriticalscriptcommandsdoexecute asintended. script execution atthatpoint.Using the if eithererror occursduringscriptexecution, the In thisexample: launched by thestoppedscript. The CANCEL CANCEL END CANCEL DISPLAY “Tablenotloaded” BEGIN IF ERROR() ;session windowandterminatesthescript ;displays anerrormessageinthecurrent ;DCS wasabletofilltable0,andifnot, ;the followingerrorroutinecheckstoseeif ; TABLE LOAD0FROM“DATA”ASSYLK ;fill structuredtable0withdata ; END CANCEL DISPLAY “Tablenotdefined” BEGIN IF ERROR ;session windowandterminatesthescript ;displays anerrormessageinthecurrent ;DCS wasabletocreatetable0,andifnot, ;the followingerrorroutinecheckstoseeif ; TABLE DEFINE0FIELDSCHAR20INT510 ;create structuredtable0 command stopsscriptexecution. command stopsonlyonescript;itwillnotstopanyotherscript,even those command takesnoarguments. CANCEL CANCEL command inthismannerensures thatscript command directs DCStocancel 3 Commands 247 - - - - argument. WinHandle WinHandle keyword and the keyword WINDOW argument is not included, the entire history the entire argument is not included, buffer of Screen argument is unnecessary no history since such sessions have buffer. clause includes the argument directs DCS to clear only the portion DCS of the historyargument directs buffer vis Screen argument is an integer identifying a particular window in DCS. argument is an integer identifying a particular window clause is not included in the command, the script clears the screen of the cur script clears the screen clause is not included in the command, the clause clears the screen or history buffer of the session window specified by the or history specified clause clears the screen buffer of the session window WINDOW Screen argument. Including this clause allows a script to clear any DCS window con a script to clear any DCS window this clause allows argument. Including WINDOW WinHandle WINDOW
CLEAR ELSE CANCEL . . . DIAL . . . IF CONNECT () WINDOW command clears the session window screen. session window command clears the WinHandle WinHandle WINDOW Screen the script dials the phone number saved in the properties of the current session window. If the If session window. in the properties of the current the script dials the phone number saved and corresponding DCS to connect, the contents of the session window system allows remote the the connection to occur, remote system does not allow historyIf the deleted. buffer are script stops. rent session. rent con the entire in the clause is the handle of a script or memo window, handle the window If tents of the file will be deleted! this example: In The optional The The WinHandle tents. the If The optional the If ible in the session window. a from with paged terminal information clearing a session window When the session is cleared. the system, remote Example WINDOW WinHandle Comments Arguments Screen CLEAR CLEAR The CLEAR 248 DCS Script Language Reference COLLECT string variable untilDCSreceives acarriagereturn orlinefeed. The NOTERMINAL WINDOWWinHandle COLLECT COLLECT Arguments Note: tionality ofaterminalemulation toincludeprocessing foracustomized remote command. minal emulationforprocessing by default.The If you donotusethe they are alsonotdisplayed inthesessionwindow. terminal emulationforprocessing. Asthecharactersare notpassedtotheterminalemulation, The optional NOTERMINAL will stopcollectingtextwhenitreceives acarriagereturn. continue collectingtextwhenitreceives acarriagereturn. If based ontheBooleanvalue of the The optional SAVECR SBoolean can work together(DCSstops collectingcharacterswheneitherconditionismet). number ofcharactersequaltotheintegerin The optional LIMIT Num The String3 acters untilitencountersalinefeed,carriagereturn, orthetextin String2 The optional EXCLUDE String2 contain wildcard characters. decimal 0x0D)oralinefeedcharacter(^Jhexadecimal0x0A).The contained inthe The optional UNTIL String1
String3 UNTIL String1EXCLUDEString2 Note: This commanddoesnotapplytoIBM TN3270emulations. command stores amaximumof254incomingcharactersfrom asessionwindow intoa argument from thecharacters it collects.DCScontinuestocollectandexclude char
argument isastringvariable in whichDCSstores thecharactersitcollects. SAVECR LIMIT EXCLUDE UNTIL NOTERMINAL might belost. the The String1 COLLECT NOTERMINAL clause directs DCStostopcollectingcharactersafterithasreceived a clause directs DCStostopcollectingcharactersifitreceives thetext NOTERMINAL clause directs DCStostore carriagereturns inthecollectionstring argumentpriortoreceiving acarriagereturn character(^Morhexa clause directs DCStoexclude anycharacterscontainedinthe keyword directs DCSnottopassthecollectedcharacters command is known. Otherwise, important terminal commands command isknown. important Otherwise, SBoolean keyword shouldbeused onlyincaseswhere theinputto keyword, DCSpassesthecollectedcharacterstoter argument. If String3 NOTERMINAL Num argument. The LIMITNumSAVECR SBoolean SBoolean SBoolean keyword canextendthefunc LIMIT String1 String1 is a true value, DCSwill is atrue is afalsevalue, DCS and argument. argumentmay UNTIL clauses - - - - 3 Commands 249 - - WinHan argument. contains the argument must assumes the value assumes the value WinHandle WinHandle $0 $Data String2 command. DCS will not execute command. DCS will not execute keyword and the keyword command until the conditions of the WAIT WAIT clause, and the WINDOW COLLECT COLLECT EXCLUDE clause in the command, DCS collects characters in the clause in the command, command implicitly like a WINDOW clause includes the argument is an integer identifying a particular window in DCS. identifying a particularargument is an integer window COLLECT COLLECT clause directs DCS to collect characters in the session specified by the to collect characters in the session specified DCS clause directs WINDOW command are met. command are continued COLLECT $0 COLLECT UNTIL “.” $data WinHandle WinHandle WINDOW argument. The inclusion of this clause allows a script in DCS to collect characters from the from a script in DCS to collect characters of this clause allows argument. The inclusion if the incoming string is Arnold Wilson (713) 555-1234, the variable the variable (713) 555-1234, Wilson if the incoming string is Arnold (713) 555-1234. Wilson Arnold this example: In .713.555.1234, the variable Wilson if the incoming string is Arnold “. This string contains a space immediately after Arnold and im Wilson characters “Arnold mediately after Wilson. active session window. active feed characters in want to include line you If the line feed character. default, DCS excludes By the must employ the collected text, you contain a null string (“”). the DCS treats the any commands or functions following COLLECT this example: In The optional The The dle specified session. do not include the you If Example WINDOW WinHandle WINDOW Comments COLLECT, COLLECT, 250 DCS Script Language Reference COLLECT, In thisexample: mal 0D)isreceived, butdoesnotpassthesecharacterstotheterminalemulation. DCS thencollectsallcharactersintothestringvariable the & o all charactersare passedtotheterminalemulationfornormalprocessing untilthe‘ In thisprocedure: 5:00 P.M. At thattime,thetableisclosedandsaved tothetextfile DCS collectseachlineofdatacomingintothesessionwindow andwritesittotablezero until WHEN STRING ’ (hexadecimal1B266F)sequencehasbeenreceived. When thissequenceisreceived, RETURN . . . COLLECT $recv_charsNOTERMINAL ;process $recv_chars WAIT RESUME WHEN STRING‘^[&o’RESUME *GETCHARS TABLE CLOSE0 END RECORD WRITE0 COLLECT @R0 BEGIN WHILE SECONDS(DATE(),TIME())<%donetime SET %donetimeSECONDS(DATE(),17:00:00) TABLE DEFINE0TEXT“MYFILE” continued commandistriggered, andexecution passestothe $recv_chars MYFILE COLLECT untilaCR(hexadeci . ESCAPE statement. - 3 Commands 251 - . is TRUE, is TRUE, command until is TRUE, is TRUE, the TUTORIAL.DCT is FALSE, or is not is FALSE, Display Make COMPILE Display only if it has been modified since the last argument. commands. Make TUTORIAL.DCP LINENUMBERS argument is specified by a Boolean operand. If by a Boolean operand. argument is specified and argument is specified by a Boolean operand. If by a Boolean operand. argument is specified is FALSE, or is not included, the specified script is compiled regardless of regardless or is not included, the specified script is compiled is FALSE, . Make Display Make Display Make DEBUG argument is a string specifying the name of the script to compile. You do not need You specifying the name of the script to compile. argument is a string argument, you must also use the argument, you command compiles a DCS script. command compiles COMPILE “tutorial” TRUE COMPILE “tutorial” Script TUTORIAL.DCT This command: DCS to compile the file directs a task file named time it was compiled. A successful compilation creates DCS will not execute any commands or functions following the any commands or functions following DCS will not execute file. DCS completely compiles the script text also the See This command: a task file named DCS to compile the tutorial script. A successful compilation creates directs The optional script has been modified since the last compila specified script is compiled only if the source tion date. If compilation. whether it has been modified since the last Display The optional compilation. If the normal compile dialog will appear during use the you If displaying the compile dialog box. included, the script will be compiled without Display Script The file extension. to include the DCP Make Comments Example Arguments COMPILE COMPILE Script COMPILE The COMPILE 252 DCS Script Language Reference CONCAT result intheexistingstringvariable. The CONCAT StringVar String CONCAT Arguments Example StringVar variable string. DCSassignstheresulting string, This exampleconcatenatesthestring variable Succeeding stringsmaybeeitherstringvariables orstringliterals. String … StringVar quotes). At leastonestringmust beincludedasanargumentinthiscommandadditionto The String content ofanyattachedstrings. variable specified asthe it willnotbecreated by the will beattached.This variable mustexistbefore itisusedasanargumentinthiscommand; The String StringVar CONCAT $A$name“Howareyou?” $name =“Larry,“ $A =“Hello,“ command concatenates(joins)anexistingstringwithadditionalstrings,placingthe $A . argument maybeeitheranotherstringvariable oraliteralstring(textwithin . argument isastringvariable containingthecharacterstowhichother StringVar String CONCAT … argumentwillcontainbothitsoriginalcontentsandthe command. Afterthe Hello, Larry,Howareyou? $A , thestringvariable CONCAT $nam command executes, the e, andaliteral , tothestring 3 Commands 253 -
Valid Setting(s) Valid string 1 (true), 0 (false) Valid Setting(s) Valid 1, 1.5, 2 odd, even, mark, space, none software, hardware, none 4, 5, 6, 7, 8 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200 COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9 1 (true), 0 (false) 1 (true), 0 (false) string Valid Setting(s) Valid
WINDOW WinHandle WINDOW
Configuration keywords for connectors shipped with client options, such as for connectors shipped with client options, Configuration keywords SNA Server, are available only if the client option has been installed. available are SNA Server,
command is used to set the value of a parameter used in the connector configura of a parameter used in the connector set the value command is used to
argument represents a single “keyword” followed by the assignment operator (=) the assignment by followed a single “keyword” argument represents Keywords for Meridian LAT32 SERVICENAME NODE string string PASSWORD PORT BLOCKIO Keywords for Direct Serial STOPBITS PARITY FLOWCONTROL DATABITS BAUDRATE COMMPORT PARITYCHECK DROPDTR Note: Keywords for Modem AREACODE string PHONENUMBER string string COUNTRYCODE MODEMTYPE string String for the active session. for the active String The the connector used to configure are and the setting the keyword Together, setting. and a valid Arguments CONNCONFIG CONNCONFIG String CONNCONFIG The session. tion for the active CONNCONFIG 254 DCS Script Language Reference CONNCONFIG, Comments the active sessionwindow. If the Window Handle isnotspecified,DCSappliestheconnectorconfigurationsettingsto The script languageratherthanusingthedialogbox. erties The keywords correspond toparametersavailable inthe session window. The The The optional WINDOW WinHandle WINDOW WinHandle ERROR dialog.Thiscommand,therefore, allows you tosettheseparametersthrough theDCS Note: SSHLEVEL Keywords forSSH BYPASS_TIMEWAIT NETWORKTYPE BREAKTYPE SERVICENAME SOCKETPORT CRPAIRING WAITDATAMARK TERMTYPE AUTORECONNECT TERMCUSTOM BINARYMODE LINEMODE PORT HOSTNAME Keywords forTelnet
WINDOW function returns TRUE ifthe continued clause directs DCStoapplytheconnectorconfigurationsettingsaparticular sion Properties Although the Trace Play connectorisshown onthe argument is an integer identifying a particular childwindow. argumentisanintegeridentifyingaparticular
clause includesthe
dialog,itcannotbeconfigured viascript. WINDOW string indicatingsecuritylevel(2and1,2only, 1only) Valid Setting(s) 1 (true),0(false) TCP, SPX interrupt, telnet string ofservicename integer valueofsocketport NULL, CRLF, NONE yes, no string ofterminaltype yes, no none, selected,custom yes, no yes, no 23 string ofhostname,includingnodeandsocket Valid Setting(s) WinHandle keyword andthe or Connectors String keyword isinvalid. Connectors tab ofthe WinHandle Session Prop tab ofthe argument. Ses - - 3 Commands 255 - continued SET CONNECTION "OPENSSH" CONNCONFIG "HOSTNAME=BUBBA" CONNCONFIG "SSHLEVEL=2ONLY" CONNECT %WINH = ACTIVE() %WINH SET DEFAULTSESSIONHANDLE “WINSOCK” SET CONNECTION CONNCONFIG “BINARY=YES” ERRORS=NO” CONNCONFIG “DISPLAY CONNCONFIG “PORT=19” security only. configured: binaryconfigured: messages is disabled, and the connec is enabled, display error negotiation tion port is set to 19. this example: In "2" set to use level SSH level is set to SSH with the session window the connector of the active In this example: In options are Winsock and several Winsock, is set to window session active the connector of the Example Example CONNCONFIG, CONNCONFIG, 256 DCS Script Language Reference CONNECT The CONNECT CONNECT Arguments Example Comments The optional SessionFile the sessionspecified by the this case,thedefaultsessionhandle mustbespecified.The the sessionfile In thisexample: use the script, donotusetheSessionFile argumentwiththe LOAD commandandthenusethe specified inthe SessionFile argument. However, if you wishtoopenasessionfilewiththe The will becometheactive window. the When DCSperforms The late anyofthesessions. environment ofDCS,thewindow handlesofsessionscanbeusedinaDCSscripttomanipu mand assignsthewindow handlevalue oftheactive sessionwindow. In themulti-session The optional WINDOW WinHandleVar CONNECT ERROR SessionFile WINDOWWinHandleVar CONNECT SET DEFAULTSESSIONHANDLE%whnd %whnd=WINDOWHND(“TSOSEND1”) LOAD “TSOSEND1.SES” Note: Note: SET DEFAULTSESSIONHANDLE command establishesaconnectionwithhost.
WinHandleVar SessionFile function returns TRUE ifDCScannotestablishtheconnection. TSOSEND1.SES keywords) priortoissuingtheCONNECTcommand. itly enablethemby usingtheDISPLAYCONFIG command(withappropriate before thevariable isusedinthe The To enablesessionbuttonsandthestatusbar(toporbottom),you mustexplic command, whenusedalone,willbothopenandconnecttothesessionfile WinHandleVar CONNECT argument isastringspecifyingthepathnameofsessionfile. SET DEFAULTSESSIONHANDLE argumentisanintegervariable towhichthe isloadedbefore DCSattemptstoconnectthehost.In variable mustnothave beenpreviously assignedavalue CONNECT command onaconnectedsession,thatsession’s window commandtospecifythetargetsession. command toconnectthesessionlaterin CONNECT CONNECT CONNECT command. command. command. Instead, you must command willconnect CONNECT com - - - 3 Commands 257 continued ;makes window of $Session1 the active window ;makes window $Session1=”C:\DCSERIES\SETTINGS\MAIN.SES” to session file path ;sets $Session1 Window %SessionHandle CONNECT $Session1 configured in MAIN.SES ;starts session . . . other windows... ;script uses CONNECT $Session1 shows a method of activating a session window after a connection has been established and after a connection has a session window a method of activating shows other operations performed. This example: CONNECT, CONNECT, 258 DCS Script Language Reference CONTINUE ates theBooleanargument. The CONTINUE CONTINUE Arguments Example Comments The again tested,andthenextrecord isdisplayed if TINUE record numberiseven (themodulusof DCS reads tenrecords from Table 0(zero) anddisplaysonlytheoddnumbered records. If the In thisexample: the firstcommandofblock. out executing thecommandblock.If theBooleanevaluates to TRUE, execution resumes at If theBooleanevaluates toFALSE, execution branchespasttheendof WHILE The CONTINUE CONTINUE END DISPLAY “Record“|STR%ctr@R0 CONTINUE IF %ctr%2=0 INCREMENT %ctr RECORD READ0 BEGIN WHILE %ctr<10 SET %ctr0 commandbranchesexecution backtothe loop. command branchesexecution tothe command mayonlybeexecuted from withinthecommandblockofa command takesnoarguments. %ctr withrespect totwoequalszero), the WHILE %ctr WHILE islessthanten. command ofa command. TheBooleanargumentis WHILE WHILE loop, andevalu loop with CON - - - 3 Commands 259 CREATE CREATE drive and then sets the drive C: . function TRUE. returns directory already exists, the directory already directory. ERROR directory on the TASK TASK DCSERIES command fails and the command creates the specified directory the command creates directory n the command does not create a command does not create directorythe does not exist or if TASK argument is a string specifying the path of the directoryargument is a string to be created. directory as the default directory for the storage of script task files. However, if the However, directory as the default directory for the storage of script task files. $TASKDIR = “C:\DCSERIES\TASK” CREATE DIRECTORY $TASKDIR SET DIRECTORY TASK $TASKDIR Path DCSERIES DIRECTORY If the directory already exists, or if the subdirectories leading to the directory the do not exist, exists, or if the subdirectories the directoryIf already DIRECTORY CREATE This script segment: the creates TASK Path The Example Arguments Comments CREATE DIRECTORY CREATE CREATE DIRECTORY Path DIRECTORY CREATE The CREATE DIRECTORY CREATE 260 DCS Script Language Reference (DDE) ACCESS (DDE) application (includinganotherinstanceofDCS). The ACCESS ServerTopic (DDE) ACCESS Arguments Comments Server The contain anullstring. nel1, channel2,...” If if DCSreceives multipleresponses ( The optional DDEList conversation. refer toaproper channelnumbertoensure thattheyare communicatinginthecorrect DDE sation atatime.If multipleDDE conversations are takingplace,allDDEcommandsmust If you donotincludethe table: channel identifier. The resultassignedtothis variableisinterpreted according tothefollowing The optional ChannelVar sation. The Topic The Topic Server ERROR n -n -1 0 Result Indication argument isastring,intheserver’s terms,specifyingthetopicforDDEconver argument is a string specifying the name of the server application. argument isastringspecifyingthenameofserver commandinitiatesaDDEconversation between DCSandanother Windows DDEList ChannelVar function returns TRUE ifDCScouldnotestablishaDDEconversation. ChannelVar DDEList ChannelVar A singleconversation established,andn(aninteger)isthechannelidentifier n multipleresponseswerereceived An erroroccurredinestablishingtheconversation No response argument isastringvariable intowhicheachchannelnumberisstored ChannelVar argumentisanintegervariable intowhichDCSstores aDDE containsavalue of0,-1,orn,the ChannelVar argument,DCScanmaintainonlyoneDDEconver =-n).It isinthefollowing format:“chan DDEList argument will - - - 3 Commands 261 - work work EXPENSES.XLS = 0, -1, or -n), the string “Cannot establish = 0, -1, or -n), the string “Cannot establish is performed. %Channel dde_begin continued ACCESS “EXCEL” “EXPENSES.XLS” %channel ACCESS “EXCEL” IF %channel <=0 BEGIN “Cannot establish conversation”, DISPLAY (0,0) CANCEL END PERFORM dde_begin DCS attempts to initiate a DDE conversation with Excel, using the with Excel, DCS attempts to initiate a DDE conversation the attempt fails ( sheet as the topic. If the attempt is suc cancels. If and execution in the session window is displayed conversation” labeled cessful, the routine In this example: In Example (DDE) (DDE) ACCESS, 262 DCS Script Language Reference (DDE) ACCESS CANCEL ACCESS (DDE) The ACCESS CANCEL (DDE) ACCESS CANCEL (DDE) ACCESS Arguments Example Comments The optional Channel channel isterminatedbefore anotherDDEchannelisinitiated. that request datafrom, andpokedatato,Excel. When theseroutines are complete,theDDE a DDEconversion isinitiatedwithExcel. If theinitiationissuccessful,routines are performed In thisexample: spawned by thescriptcontaining thiscommand. DCS terminatesallDDEconversations. However, DCSterminatesonlythoseconversations If the conversation istakingplace. (DDE) ACCESS Channel ACCESS “EXCEL”“SYSTEM” ACCESS CANCEL PERFORM dde_poke PERFORM dde_request END CANCEL DISPLAY (0,0)“CannotAccessExcel” BEGIN IF ERROR() ACCESS “EXCEL”“EXPENSES.XLS” Channel Channel argument isnotincludedduringasessionwithmultipleDDEconversations, command.DCSdoesnotrequire the argument isanintegerspecifyingthechannelvalue returned by the commandterminatestheactive DDEconversation. Channel argument ifonlyoneDDE 3 Commands 263 argument if only one DDE argument if only one Channel argument is an integer specifying the channel value returned by the by returned specifying the channel value argument is an integer Command, ... Command, command. DCS does not require the not require command. DCS does argument is a string specifying a list of instructions in the server’s terms for the argument is a string specifying a list of instructions in the server’s command sends a string of commands to a DDE server. Once the commands the commands Once of commands to a DDE server. command sends a string function returns TRUE if the server could not perform the request. TRUE function returns Channel ACCESS “EXCEL” “SYSTEM” INSTRUCT ‘[OPEN(“C:\BUDGET.XLS”)]’ Channel Channel Command ERROR a DDE conversation is established with Excel that accesses the system. Excel then opens the Excel that accesses the system. is established with Excel a DDE conversation sheet. work BUDGET.XLS conversation is taking place. conversation Command, ... The server to perform. The this example: In Channel The optional (DDE) ACCESS Comments Example Arguments (DDE) INSTRUCT INSTRUCT INSTRUCT The for acknowledgment. been sent, DCS waits have (DDE) INSTRUCT (DDE) 264 DCS Script Language Reference (DDE) POKE waits foracknowledgment. The POKE DataTO (DDE) POKE Arguments Example Comments Data Excel spreadsheet a lineofdatacomingintothesessionwindow iscollectedandsenttorow 1,columnofthe In thisexample: sending asingledataitem. You canusethe The require the teger specifyingthechannelvalue returned by the The TO contains multiplefieldsofdata,theyshouldbetabdelimited. The Channel Item TO Data ACCESS CANCEL%channel POKE $dataTO%channel“R1C1” ACCESS “EXCEL”“EXPENSES.XLS”%channel COLLECT $data clause specifiesthedestinationofdata.Theoptional argument isastringspecifyingthedesired dataitem. argument isastringspecifyingthedatatosend,inserver’s terms.If the string command sends the specified data to the server inaDDEconversation andthen commandsendsthespecifieddatatoserver Channel Channel Item (DDE) POKE EXPENSES.XLS argument ifonlyoneDDEconversation istakingplace. Item commandinsteadofthe . (DDE) ACCESS (DDE) TABLE(DDE) SEND Channel command.DCSdoesnot argument isanin commandwhen - 3 Commands 265 - - com com argument are written to are command. DCS Channel BUDGET.XLS (DDE) TABLE REQUEST (DDE) TABLE (DDE) TABLE REQUEST (DDE) TABLE (DDE) ACCESS from a server be from conversation in a DDE command instead of the Item argument if only one DDE conversation is taking place. argument if only one DDE conversation Channel Channel Channel Item (DDE) REQUEST command requests that data received command requests argument is a string variable into which the requested data is stored. which the requested into variable argument is a string clause specifies the source of the requested data. The optional of the clause specifies the source argument is a string identifying a data item. Channel ACCESS “EXCEL” “BUDGET.XLS” %channel ACCESS “EXCEL” “BUDGET.XLS” “R1C1” REQUEST $totals FROM %channel SET @R0 $totals RECORD WRITE 0 FROM Item DataVar Table 0 (zero). Table During a DDE session between two instances of DCS, the a DDE session between During via tables. to requests DCS replies data because mand must be used to request this example: In spreadsheet one, column one, of the Excel the contents of row The the by returned is an integer specifying the channel value the does not require Item The may use the You mand when only a single data item is needed. DataVar The FROM Example Comments Arguments (DDE) REQUEST REQUEST DataVar FROM FROM DataVar REQUEST The then waits for acknowledgment. variable, placed in the specified (DDE) REQUEST (DDE) 266 DCS Script Language Reference (DDE) TABLE REPLY request (eitheranadviseorarequest) fordatafrom theclient,andthenwaitsforacknowledgment. The TABLE REPLY StrucTableNum TO (DDE) TABLE(DDE) REPLY Arguments Example Comments StrucTableNum service a service These commands: The The conversation istakingplace. WHEN INITIATE tional The TO tured tablecontainingthedatatobesent. The Channel ERROR Item TO StrucTableNum END WAIT SIGNAL BEGIN WHILE TRUE END TABLE REPLY0TO“POKE1” BEGIN WHEN POKE0TABLE“item1” Channel clause specifiesthedestination(inclient’s data.Theop terms)oftheexported (DDE) POKE argument isastringidentifyingtherequested dataitem. function returns TRUE iftheoperationisunsuccessful. Item argument isanintegerspecifyingthechannelvalue returned by the command. DCSdoesnotrequire the commandsendsthecontentsofastructured tableinresponse toaDDE argumentisaninteger(from 0to15)specifyingthenumberofastruc from aDDEclientonthetopic Channel Item Channel POKE1 . argument ifonlyoneDDE (DDE) - - 3 Commands 267 Request , DCS displays “ item0 continued ” in the session window, then loads the necessary data into structured Table 0 Table then loads the necessary data into structured ” in the session window, TABLE REPLY 0 TO “item0” TABLE REPLY 0 END WHEN REQUEST 0 “item0” WHEN REQUEST BEGIN “Request Activated” DISPLAY (0,0) FROM “DATA1” AS SYLK TABLE LOAD 0 IF ERROR () BEGIN load table” DISPLAY “Can’t CANCEL END when DCS receives a data request from the DDE client on the DDE from a data request when DCS receives Activated and sends the data to the client. (zero) In this example: In (DDE) TABLE REPLY, REPLY, TABLE (DDE) 268 DCS Script Language Reference (DDE) TABLE REQUEST structured table,andthenwaitsforacknowledgment. The TABLE REQUESTStrucTableNum FROM (DDE) TABLE(DDE) REQUEST Arguments Example Comments StrucTableNum work sheetusing DCS initiatesaDDEconversation withExcel andrequests datafrom the In thisexample: The is specified by oneofthefollowing keywords: The AS Format The only oneDDEconversation is takingplace. INITIATE Channel The FROM tured tableintowhichdataisplaced. The ERROR AS Item FROM StrucTableNum DISPLAY (0,5)“RequestSuccessful” ELSE DISPLAY “Requestdenied” IF ERROR() TABLE REQUEST0FROM“item0”ASSYLK DISPLAY (0,0)“DATAREQUEST0:“ ACCESS “EXCEL”“BUDGET.XLS” DIF clause specifiestheformatinwhichtostore data.The theimported Channel and argument isastringidentifyingtherequested dataitem. argument isanintegerspecifyingthechannelvalue returned by the(DDE) clause specifiesthesource ofthe requested data(intheserver’s terms).Theoptional function returns TRUE therequest. couldnotperform iftheserver (DDE) ACCESS item0 Item argumentisaninteger(from 0to15)specifyingthenumberofastruc commandrequests datafrom theDDEserver, placesthedataintoa SYLK asthetopic. commands.DCSdoesnotrequire the Channel TEXT Item AS Format Item AS Channel BUDGET.XLS Format argument if argument WHEN
- 3 Commands 269
- - - ment. (DDE) ACCESS argument if only one DDE conversation is argument if only one DDE conversation Item AS Format Channel Channel Channel SYLK TEXT argument is an integer (from 0 to 15) specifying the number of a struc 0 to 15) (from argument is an integer command allows DCS to act as a DDE client. The command sends the con the sends command The client. DDE a as act to DCS allows command Item function returns TRUE if the server could not perform the request. TRUE function returns argument is an integer specifying the channel value returned by the by returned value argument is an integer specifying the channel argument is a string identifying the requested data item. argument is a string identifying the requested clause specifies the destination, in the server’s terms, of the exported data. The optional clause specifies the destination, in the server’s clause specifies the standard data format in which to send the exported data. The For in which to send the exported data format data. The clause specifies the standard DIF ERROR Item AS StrucTableNum TO Channel The TO The Channel the command. DCS does not require taking place. The AS Format The keywords: by one of the following mat argument is specified StrucTableNum The the data to be sent. table containing tured Comments Arguments (DDE) TABLE SEND (DDE) TABLE TABLE SEND StrucTableNum TO TO StrucTableNum SEND TABLE The table to the servertents of a structured and then waits for acknowledg a DDE conversation in (DDE) TABLE SEND TABLE (DDE) 270 DCS Script Language Reference (DDE) WAIT SIGNAL from aclient. The WAIT SIGNAL (DDE) WAIT SIGNAL Arguments Example Comments The message from theclient. either the established sothatDCSwaitstoreceive anincoming prepare anincoming DCStoservice These commands: with thiscommand. Any seriesof ing DDErequest, DCSdisablesallincomingDDErequests whileexecuting thiscommand. In order toprocess theentire current DDErequest from thenextincom without interruption (DDE) WAIT SIGNAL WAIT SIGNAL WHILE TRUE END CANCEL DISPLAY “(0,0)DDElinkterminated” BEGIN WHEN TERMINATE, PERFORM poke1 WHEN POKE1TABLE“item1” PERFORM poke0 WHEN POKE0TABLE“item0” poke0 (DDE) WHEN or commandpausesscriptexecution untilDCSreceives thenextDDErequest poke1 commandtakesnoarguments. commands intended to fulfill a DDE service request mustend commandsintendedtofulfillaDDEservice routines. Execution terminateswhenDCSreceives aterminate (DDE) POKE from theDDEclient.Aninfiniteloopis POKE each timeexecution returns from - 3 Commands 271 - command. argument if only one message is found, the message, it will look Channel ADVISE is set to FALSE), and the data item is set to FALSE), WHEN ADVISE (DDE) TABLE REPLY (DDE) TABLE ADVISE command executes the logical command. command executes command was activated by an advise or an un by command was activated commands active at the same time. at the same commands active argument. Item function. Script commands issued to fulfill an advise request function. Script commands issued to fulfill an advise commands to be active at the same time. DCS may have a time. DCS may have at the same commands to be active Item Command string specified with the command. For example, the script line: string specified with the command. command is activated when DCS receives either an advise message when DCS receives command is activated (DDE) WHEN ADVISE command. DCS does not require the the command. DCS does not require Item ADVISE argument is an integer specifying the channel value returned by the by returned value argument is an integer specifying the channel (DDE) WHEN ADVISE command prepares DCS to service to send continuous a DDE request command prepares Channel Channel (DDE) ADVISE WHEN argument specifies a logical command (either a single command or a command Channel argument is an integer (from 0 to 16) specifying the command identifier. It allows It allows specifying the command identifier. 0 to 16) (from argument is an integer is set to TRUE) or an unadvise message ( TRUE) is set to argument is a string identifying, in the client’s terms, the requested data item. terms, the requested argument is a string identifying, in the client’s (DDE) ADVISE WHEN argument 16 is a unique index. When DCS receives an When DCS receives argument 16 is a unique index. WHEN ADVISE 16 $item DISPLAY “ADVISE—Unknown item, \ WHEN ADVISE 16 $item DISPLAY “ | $item | “^M” Item Index (DDE) WHEN ADVISE Command ADVISE The ( of the matches the value requested DCS determines if the advise message with the should be disabled when an unadvise message is received. for data should be fulfilled using the Client requests The optional (DDE) WHEN INITIATE is taking place. DDE conversation Item The Command The of the block). Activation maximum of 16 Index If no corresponding 15 first. 0 through indexes through message is placed in the not found in the first 16 message, displaying only those which were signals any unknown 15). (0 through indexes Channel Index The multiple Comments Arguments (DDE) ADVISE WHEN WHEN ADVISE WHEN ADVISE Index The updates on a particular a wait state to service data item. DCS must be in a request. (DDE) (DDE) ADVISE WHEN 272 DCS Script Language Reference (DDE) WHEN ADVISE, (DDE) Example In thisexample: client command. When DCSreceives anunadvisemessage,thestring“ ing thatthere isupdatedinformationtosendtheclientwith In region thisexample,thescriptlooksforaparticular ofthescreen tobemodified,indicat should besent. the specifieddataitemismodified. Youmustestablish criteriatodeterminewhenanupdate by executing an RETURN END TABLE REPLY3TO“item0” PERFORM grabItem0(3) BEGIN WHEN SCREEN0(24101) END RETURN WHEN CANCELSCREEN0 DISPLAY (0,0)“Advisecanceledbyclient” BEGIN IF NOTADVISE *advise WAIT SIGNAL WHILE TRUE PERFORM advise WHEN ADVISE0“item0” TABLE DEFINE3FIELDSCHAR20 ” isdisplayed inthesessionwindow andthe ADVISE command, theclientrequests DCStosendanupdatewhenever continued WHEN SCREEN Advise canceledby (DDE) TABLE(DDE) REPLY commandiscanceled.
- 3 Commands 273 argument for only Channel command executes the logical command. command executes argument. command. DCS does not require the not require command. DCS does (DDE) WHEN EXECUTE CommandVar Command CommandVar argument is an integer variable specifying the channel value returned by by returned specifying the channel value variable argument is an integer command prepares DCS to service an execute request from the DDE from DCS to service request an execute command prepares argument is a string variable which stores the command specified by the the command specified which stores argument is a string variable argument specifies a logical command (either a single command or a command argument specifies a logical command (either CommandVar Channel Channel Channel CommandVar Command (DDE) WHEN INITIATE Since DCS’s script language is compiled, the DDE client cannot directly add functionality to add directly script language is compiled, the DDE client cannot DCS’s Since the server script. Routines a compiled script. Commands sent from must be parsed through to the command sent. according should be established that will branch execution one DDE conversation. CommandVar The client. Command The of the block). Activation result to the according should branch execution The command established in this argument in the returned Channel The optional the Comments Arguments (DDE) WHEN EXECUTE WHEN EXECUTE WHEN EXECUTE The in a wait state to serviceclient. DCS must be the request. (DDE) WHEN EXECUTE (DDE) 274 DCS Script Language Reference (DDE) WHENEXECUTE, Example In thisexample: tents ofthe a seriesofnested RETURN ELSE LAUNCH “PAINT.EXE” IF $command=“LAUNCH‘PAINT.EXE’” ELSE CLEAR SCREEN IF $command=“CLEARSCREEN” ELSE WINDOW STACK IF $command=“WINDOWSTACK” DISPLAY $command *dde_parse_cmd CANCEL WAIT SIGNAL WHILE TRUE END RETURN DISPLAY ‘DDEended’ BEGIN WHEN TERMINATE PERFORM dde_parse_cmd WHEN EXECUTE%ch$command WHEN INITIATE%chPERFORMdde_initiate $command IF commands determine which action is performed, dependingonthecon commandsdeterminewhichactionisperformed, variable. continued - 3 Commands 275 - command, routine and then routine command, waiting for a DDE dde_advise (DDE) WAIT SIGNAL (DDE) WAIT when a DDE conversation is estab when a DDE conversation command and before the condition of command and before command executes the logical command. command executes WAIT WAIT (DDE) WAIT SIGNAL (DDE) WAIT dde_initiate command until the DDE conversation is terminated. command until the DDE conversation Command argument is a numeric variable into which DCS will store a DDE into which DCS will store variable argument is a numeric (DDE) WHEN INITIATE command is activated when DCS is in a wait state and a new when DCS DDE command is activated argument specifies a logical command (either a single command or a command argument specifies a logical command (either (DDE) WAIT SIGNAL (DDE) WAIT ChannelVar ChannelVar ChannelVar ChannelVar command is fulfilled. WHEN INITIATE PERFORM dde_initiate WHEN ADVISE PERFORM dde_advise ended’, RETURN WHEN TERMINATE DISPLAY ‘DDE WHILE TRUE WAIT SIGNAL Command WAIT WAIT returns to the returns DCS prepares to perform the routine DCS prepares at the lished. DCS then pauses execution to the returns execution received, initiate message. Once an advise message. while DCS waits to receive an advise message, it performs the Each time DCS receives Command The of the block). Activation a DCS is in a wait state after DCS has executed the this example: In ChannelVar The optional by the client. channel identifier generated Comments Example Arguments (DDE) WHEN INITIATE WHEN INITIATE WHEN INITIATE The is established. conversation (DDE) WHEN INITIATE (DDE) 276 DCS Script Language Reference (DDE) WHENPOKE placed inthespecifiedtable. therequest.to receive Received dataitem.DCSmustbeinawaitstatetoservice aparticular datais The WHEN POKEIndexTABLE Table (DDE) WHENPOKE Arguments block). Activation ofthe The Command The Item DDE conversation istakingplace. (DDE) WHENINITIATE The optional Channel integer (from 0to15)specifying thetablenumber. The TABLE Table statements, you caneffectively handlemore than16messages. See the Since the With Index 16,the indexes (0through 15). signals anyunknown message,displaying onlythosewhichwere notfoundinthefirst16 message isplacedinthe through indexes 0through 15first. If nocorresponding Index time. DCSmayhave amaximumof16 multiple The Index Command TABLE Index Item |$item“^M” WHEN POKE16$itemDISPLAY“POKE—Unknownitem,“\ argument 16isauniqueindex. When DCSreceives a (DDE) WHENPOKE argument isastringidentifying,intheclient’s terms,therequested dataitem. SWITCH argument isaninteger(from 0to16)specifyingthecommandidentifier. It allows clause specifiesthetableinwhichtoplacedata.The Channel argument specifiesalogicalcommand(eithersingle oracommand commandprepares aDDErequest message from theclient DCStoservice command compares theswitchvariable toanunlimitednumberofcase Item argument isanintegerspecifyingthechannelvalue returned by the Item command.DCSdoesnotrequire the (DDE) WHENPOKE string maybeusedastheswitchvariable forthe string specifiedwiththecommand. For example,thescriptline: commandstobeactive andtoaccessthesametableat Channel (DDE) WHENPOKE Item Command commandexecutes thelogicalcommand. WHEN POKE POKE commandsactive atonetime. Channel message, itwilllook Table DDE Server messageisfound,the argument ifonlyone SWITCH argument isan example. command. 3 Commands 277 command is activated. command. continued (DDE) WHEN POKE (DDE) WAIT SIGNAL (DDE) WAIT When DCS receives a poke message, and the data item requested matches the value of the the value matches poke message, and the data item requested a When DCS receives argument, the Item the See Comments Example (DDE) WHEN POKE, WHEN POKE, (DDE) 278 DCS Script Language Reference (DDE) WHENREQUEST item. DCS must be in a wait state to service thisrequest. item. DCSmustbeinawaitstatetoservice The WHEN REQUESTIndex (DDE) WHENREQUEST Arguments Comments Index TABLE REPLY of the DCS isinawaitstateafterhasexecuted a Item argument,the When DCSreceives arequest message,and thedataitemrequested matchesthevalue of the block). Activation ofthe The Command The Item DDE conversation istakingplace. (DDE) WHENINITIATE The optional Channel indexes (0through 15). signals anyunknown message,displaying onlythosewhichwere notfoundinthefirst16 line: the messageisplacedin through indexes 0through 15first. If nocorresponding Index maximum of16 multiple The Command Item Index “ |$item“^M” WHEN REQUEST16$itemDISPLAY“REQUEST—Unknownitem,\ argument 16isauniqueindex. When DCSreceives an WAIT (DDE) WHENREQUEST argument isastringidentifying,intheclient’s terms,therequested dataitem. argument isaninteger(from 0to16)specifyingthecommandidentifier. It allows command isfulfilled.Client requests fordatashouldbefilledusingthe Channel command. argument specifiesalogicalcommand(eithersingleor (DDE) WHENREQUEST (DDE) WHENREQUEST Channel commandprepares aDDErequest data foraparticular DCStoservice argument isanintegerspecifyingthechannelnumberreturned by the command.DCSdoesnotrequire the (DDE) WHENREQUEST Item Item Command string specifiedwiththecommand. For example,thescript commandstobeactive atthesametime.DCSmayhave a commandsactive atonetime. commandisactivated. WAIT commandexecutes thelogicalcommand. command andbefore thecondition WHEN REQUEST REQUEST Channel argument ifonlyone message, itwilllook messageisfound, (DDE) 3 Commands 279 - com (DDE) TABLE REPLY (DDE) TABLE command. (DDE) WAIT SIGNAL (DDE) WAIT continued DISPLAY (1,0) “Reply failed” DISPLAY (1,0) END END WHILE TRUE WAIT SIGNAL TABLE DEFINE 0 FIELDS INT 10 INT 10 TABLE DEFINE 0 “item0” WHEN REQUEST BEGIN “Request activated” DISPLAY (0,0) TO “item0” TABLE REPLY 0 IF ERROR () BEGIN DCS prepares to service a request from the client. When the request is received, a message is is received, When the request to service the client. from a request DCS prepares request using the DCS fills this in the session window. displayed to the returns mand and execution In this example: In Example (DDE) WHEN REQUEST, WHEN REQUEST, (DDE) 280 DCS Script Language Reference (DDE) WHENTERMINATE client. It isactivated whenDCSisinawaitstateandthecurrent DDEconversation isterminated. The WHEN TERMINATE (DDE) WHEN TERMINATE(DDE) Arguments Example Channel See the block). Activation ofthe The Command versation is takingplace. (DCS actingasaclient).DCSdoesnotrequire theChannelargumentifonlyoneDDEcon (DDE) WHENINITIATE The optional Command (DDE) WAIT SIGNAL Channel argument specifiesalogicalcommand(eithersingleor Channel argument isanintegerspecifyingthechannelnumberreturned by the command (DCS acting as a server) or command(DCSactingasaserver) command is used when DCS is acting as a DDE server oraDDE commandisusedwhenDCSactingasaDDEserver (DDE) WHEN TERMINATE(DDE) Command command. commandexecutes thelogicalcommand. (DDE) ACCESS command - 3 Commands 281 - - - command and command fol command, and DEBUG SHOW command. You can strategi You command. NOSHOW SHOW argument, and if the command writes the command or function to a command writes the ). commands in a script to allow you to debug portions you of commands in a script to allow FileName command it encounters in a script. It ignores any subse ignores command it encounters in a script. It DEBUG DEBUG NOSHOW command, DCS will delete the previous contents of the file before contents of the file before command, DCS will delete the previous and c:\debug.txt command, DCS will enter step mode. While in step mode, DCS displays the displays DCS mode, step in While step mode. enter will DCS command, DEBUG commands in the script, or in the subroutines the script may execute. the script may commands in the script, or in the subroutines SHOW argument is a string naming the file to which DCS writes the output. The file naming the file to which DCS writes the argument is a string DEBUG DEBUG FileName DCS stops placing text in the debug file, when it encounters the DCS stops placing text in the debug file, writing text to the file when it encounters the will resume cally place the a script rather than all of it. only the first DCS executes quent and must specify a valid file name for your system. For best results, create the debug file in a create results, For best system. your for file name and must specify a valid directoryroot (e.g., executes the it the file before the file does not exist, DCS will create If If the file exists prior to the script. will place the file into the task directory the executing of of the execution the command. executing (?) for the use a question mark you If the lows Stop dialog. This dialog also contains a command in the Script Compiler executing currently button. or Resume button and a Pause FileName The and extension) long (including the path, name, period characters name may be up to twelve Comments Arguments DEBUG FileName DEBUG the function executes, As each command or a script. with you in solving problems file to aid DEBUG 282 DCS Script Language Reference DEBUG, Example In thisexample: written to debug file.The label. Thescriptline debug file. Whentheend ofthefileis reached,script execution branchestothe and theline each scriptlineto mand executes, DCSbeginscollectingthecommandsandfunctionsastheyexecute, copying the continued DEBUG CANCEL NOSHOW DISPLAY “Endoffilereached” *end_read PERFORM end_read END RECORD READ0 DISPLAY @R0.1|“[email protected] BEGIN WHILE NOTEOF() RECORD READ0at *begin_read SHOW DEBUG “DATAREAD.BUG” BUGFILE DISPLAY @R0.1|“ [email protected] command willwriteitsoutputtothefile NOSHOW BUGFILE DISPLAY “Endoffilereached” . command executes, commandsexecuted andanyfurther are not . Eachtimethecommandsbetween thelabel BUGFILE execute, DCSaddsthemtothe executes andiswrittentothe . When the . When *begin_read SHOW *end_read com -
3 Commands 283 is used as a counter so that exactly ten records are read read are is used as a counter so that exactly ten records DECREMENT %num command decreases the value of the specified numeric variable by one. variable of the specified numeric the value command decreases argument specifies the integer variable to be affected. variable integer argument specifies the SET %num 10 WHILE % num > 0 BEGIN RECORD READ 0 DISPLAY (%num, 0) @R0 DECREMENT %num END IntVar IntVar the command and displayed. An integer variable must be specified (a real variable will generate a syntax error). real (a must be specified An integer variable this example: In IntVar The Example Arguments Comments DECREMENT DECREMENT DECREMENT IntVar DECREMENT The DECREMENT 284 DCS Script Language Reference DIAL on the The DIAL DIAL Arguments Comments Note: PhoneNum RETRY RetriesDELAY RetryDelay Session DCS hasconnectedtoanother computer, executing the DCS treats the command forthevalid keyword parametersfortheModem connector. command andthenusethe codeandphone numberusingthe these problems, setthearea code,country defined inthe TAPI configuration,andthenalsodefinedinthe codeparametersarefor dialing),problems mayarisewhenthearea codeand/orcountry Due totheway Windows TAPIrules operates(withitsparametersseparatedandspecific temporarily overrides thesesettings,butdoesnotmodifythesessionfile. If different phonenumbersettingsare specifiedintheactive sessionfile,the If you includethe numeric specifyingthedelayinseconds. by theactive sessionfile,where the default value is30seconds.The cessful connectionbefore delayisdetermined todial.If itisnotincluded,theretry retrying The optional DELAY RetryDelay connection ismade. dial. Setting thevalue of the active sessionfile.The tion isinitiallyunsuccessful.If itisnotincluded,thephonenumberredialed according to The optional RETRY Retries executed DCSwillreturn anerror (sinceitdoes nothave aphonenumbertodial). the last number isspecifiedintheactive sessionfile,themodemdialsphonenumberspecifiedin included, themodemdialsphonenumberspecifiedinactive sessionfile. Ifnophone The optional PhoneNum command directs themodemtodialaphonenumber. It isequivalent toselecting The menu whenusingtheModem (TAPI) connector. SET PHONENUMBER DIAL DELAY RETRY PhoneNum DIAL command doesnotapplytoIBM TN3270 emulations. DELAY command liketheConnectoption intheSession menu.For example,if clause determinestheamountoftimeforDCStowaitmakeasuc clause directs DCStoredial thespecifiedphonenumberifconnec Retries argumentisastringspecifyingthephonenumbertodial.If itisnot Retries clause, you mustalsoincludethe DIAL command.If no to -1directs DCStocontinuouslyredial untilasuccessful command withoutanyparameters.See the argument isanumericspecifyingthenumberoftimesto SET PHONENUMBER DIAL RETRY command willhave noeffect. DIAL RetryDelay clause. command. Toavoid commandhasbeen DIAL CONNCONFIG CONNCONFIG argumentisa command Connect - - 3 Commands 285 . DCS then checks to see if it is presently . DCS then checks to see if it is presently COMPUSER.SES SEND NOCR “^M” WAIT STRING “ID:” SEND “secretid” LOAD “COMPUSER.SES” IF CONNECT () BEGIN SEND “/off” HANGUP END DIAL “555-1234” RETRY 3 WAIT STRING “>” WINDOW OPEN SETTINGS “” %HWND WINDOW OPEN SETTINGS %HWND SET DEFAULTSESSIONHANDLE “TAPI” SET CONNECTION CONNCONFIG “AREACODE=281” CONNCONFIG “PHONENUMBER=555-5555” DIAL DCS loads a session file named waits DCS then dials the specified phone number, up. connected and, if so, logs off and hangs and sends the necessaryfor the expected prompts responses. directs DCS to set the areacode and phone number parameters in the session file and then dial. parameters in the session file and then and phone number to set the areacode DCS directs this example: In This example: continued Examples DIAL, 286 DCS Script Language Reference DIALOG of thedialogbox definitionandmustfollow the more dialogoptionsmayfollow the The DIALOG END FBoolean DIALOG DIALOG Arguments Note: DialogIndex a nullstring(“”),thedialogbox appearswithablanktitlebar. move thedialogbox around thescreen by draggingthetitlebar. If the (or atitle)forthedialogbox. When you definedialog boxes withthe SYSMENU clausewithafalse Booleanvalue asitsargument),DCSwillnotdisplay atitlebar the DCS willalsoincludeaControl, orSystem, menuwiththetitlebar. If you donotinclude The optional Title of adialogondifferent typesofmachinesandmonitors. terms ofsystemcharacterandlinewidths,insteadpixels. Thisallows forthebestappearance Dialog box coordinates are intended tobemachine-independentandare, therefore, definedin placement. specifies widthonly). If you donotincludeacoordinate set,DCSassignsadefaultsize and If thecoordinate setisincluded,onetofourcoordinates canbespecified(forexample,(,,40,) window, whichis(0,0). The (x,y)coordinates foradialogbox are relative tothetopleftcornerofapplication logical units: It indicatesthetopleftcorner(x,y),width(w),andheight(h).Thecoordinates are specifiedas The optionalcoordinate set (x, y, w, h) (x, y, w, h)Title SYSMENUSBooleanMODAL MBooleanNOFOCUS Title
command creates customdialogboxes prompting your interactionwithDCS.One or Vertically, there are eightlogicalunitsperline. Horizontally, there are fourlogicalunitspercharacter Option… Option as aresult, belargerthandialogboxes displayed when Windows isusingSmall Fonts. the displaysettingsare settoLargeFonts, scripteddialogboxes willuselargefontsand, Windows willalsoaffectthosedialogscreated withthescriptlanguage. For example,if Therefore,(Windows 95/98/NT). settingswhichaffectthedisplayofdialog boxes in Dialog boxes inthescriptlanguageare governed inmostcases by theoperatingsystem argument anddonotincludethe Title argument isastringwhichwillappearinthetitlebarofdialog box. (x, y, w, h) DIALOG command. A specifiesthedesired positionandsize ofthedialogbox. DIALOG SYSMENU command andthedialogoptions. DIALOG END clause(orifyou have includedthe command indicatestheend Title Title argument, you can argument contains 3 Commands 287 - -
- - - argument SYSMENU SBoolean MBoolean FBoolean SBoolean command will define a clause must follow the clause must follow clause, or if clause and is a Boolean DIALOG MODAL MODAL NOFOCUS SYSMENU argument evaluates to a false Boolean argument evaluates clause. The optional clause. The optional , you are allowed to select options outside allowed are , you clause, the argument can make a dialog box either ap argument can make a dialog box clause, the MBoolean clauses are order-dependent; however, you do not do you however, order-dependent; clauses are
MODAL MODAL MODAL MODAL MODAL MODAL argument with the MBoolean clause, you are not allowed to select any options outside of the to select any options outside not allowed are clause, you NOFOCUS , and clause determines whether the dialog box will become the active will become the active clause determines whether the dialog box SBoolean clause controls the display of the dialog box’s control menu. The control dialog box’s the display of the clause controls argument is a Boolean value. If you do not include the you If argument is a Boolean value. MODAL MODAL argument and it evaluates to a false Boolean value, the dialog box will the dialog box to a false Boolean value, argument and it evaluates clause allows you to specify whether a dialog box is a non-modal or a to specify whether a dialog box you clause allows argument or when the box has an error in its logic, the Program Manager (and other applica Manager in its logic, the Program has an error box clause will create an application modal dialog box when you do not in when you an application modal dialog box clause will create MODAL MODAL clauses, but not the , argument is an optional argument to the clause will create a system modal dialog box when you include the when you a system modal dialog box clause will create clause and its optional FBoolean NOFOCUS MODAL MODAL SYSMENU clause. with the clause is incompatible SBoolean
MODAL MODAL MBoolean MODAL MODAL MODAL MODAL MBoolean SYSMENU NOFOCUS continued title bar and border; other open windows or dialogs will have dimmed title bars and borders. dimmed title bars and borders. or dialogs will have windows other open title bar and border; The optional clude the in the portion has an error If of the script dealing with an application modal dialog box value. its logic, the Script menu (and other DCS menus) might become inaccessible. The the portion to a true If of the script dealing with a argument and it evaluates value. Boolean system modal dialog tions) might become inaccessible. The optional it has a highlighted is active, When a dialog or window when initially displayed. window ally, you must interact with some option in the dialog box in order to cancel the dialog. in order must interact with some option in the dialog box you ally, The is an application- the dialog box plication modal or system modal. If not allowed are to interact with other applications, but you allowed are you modal dialog box, the dialog box If the script cancels the dialog box. to interact with other options in DCS, until other application or any to interact with any not allowed are is a system-modal dialog, you the dialog box. other option in DCS, until the script cancels The The value. If you do not include the you If you menu. If with a control a dialog box to a true DCS will create evaluates Boolean value, include the menu. a control not have The optional do not include the you modal dialog. If is non-modal When a dialog box non-modal dialog. How applications). Windows in DCS or other (like the menus or windows of the dialog box include the if you ever, Usu (or possibly in any other application), until the script cancels the dialog box. dialog box The include the if you example, clauses in the command. For to include all three have and SYSMENU The optional SYSMENU is a Boolean value. NOFOCUS FBoolean MODAL MBoolean MODAL SYSMENU SBoolean DIALOG, DIALOG, 288 DCS Script Language Reference DIALOG, Comments DialogIndex window. When you clickthemousebuttonindialogbox, DCSwill makethedialogbox theactive Booleanvalue,ment evaluates thedialogbox toatrue created willnotbetheactive window. and makeittheactive window. When you includethe argument, orifitevaluates toafalseBooleanvalue, the When you create adialog box with the currently displayed. the script,or when ascriptencountersoneof thefollowing: the DCS candisplaymore than onedialogbox atatime.DCS willstopdisplayingadialogbox fewer than255. of interactingwithadialog)mightlimitthenumbercontrols you putintoadialogbox to inyour computeranddesignconsiderations(such asthepracticalityandease able memory You mayincludea The following limitationsapplytodialogbox controls: DCS treats active dialogbox controls like interactive. Thefollowing are the valid scriptcommands fordialogboxes: in adialogbox, butnotastatic control. Static controls onlydisplayinformation;theyare not command. Dialog controls are eitheractive orstatic. You are allowed toselectanactive control Each Option favor created ofa newly dialogbox. same scripthave anidentical dialog box. If itisnotincluded,DCSuseszero asthedefaultvalue. If twodialogboxes inthe The optional continued Option Total RadioGroups Total Pictures Total ListBoxes Total Edit Text Boxes Total CheckBoxes Total Buttons,Wide &IconButtons Total ControlsinaDialog Box Control EDITTEXT CHECKBOX BUTTON ICON argument isactuallyanotherscriptcommandwhichspecifiesadialogcontrol or DialogIndex
DIALOG maximum of255controls GROUPBOX PICURE ICONBUTTON MESSAGE argument is an integer (from 0 to 15) identifying a particular argumentisaninteger(from 0to15)identifyingaparticular command usinga DialogIndex DIALOG WHEN value, DCS willdestroy anexistingdialogbox in DialogIndex perdialogbox; however, theamountofavail LISTBOX command, you canclosethedialoginanum commands. DIALOG CANCEL Maximum Quantity FBoolean NOFOCUS identicaltothatofadialogbox 128 255 16 10 64 16 1 argument, andtheargu clause willcreate adialog WIDEBUTTON RADIOGROUP RADIOBUTTON command, theendof - - - 3 Commands 289 - - - SYS SBool SYSMENU . However, if you if you . However, argument or the Title Title Cancel RESUME argument as a null string (“”) or include the Title Title argument. Title Title “The Title of the Dialog Box” “The Title of the Dialog CANCEL “Cancel” clause (the SYSMENU keyword only or the keyword with a true for the value only or the keyword clause (the SYSMENU keyword DIALOG END WAIT RESUME DIALOG CANCEL DIALOG BUTTON DIALOG END Wait Resume DIALOG CANCEL DIALOG SYSMENU Button CANCEL “Cancel” Resume DIALOG Resume Button “Cancel” DIALOG END WAIT RESUME DIALOG CANCEL argument); however, if you want the control menu in the dialog box, but you do not want but you menu in the dialog box, want the control if you argument); however, continued text in the title bar, compose the text in the title bar, clause without the In these examples, you can close the dialog box by selecting the Cancel button in the dialog selecting the Cancel by can close the dialog box these examples, you In entering the [ESC] key (adding the key combination, by entering the [ALT]+[F4] by box, selecting the Close option in the to use the [ESC] key), by you allows CANCEL keyword menu. double-clicking on the control or by menu of the title bar, control you include the menu will only appear in a dialog if The control MENU ean the buttons that you define for the dialog box. The following script segments are based on the script segments The following define for the dialog box. the buttons that you script sample: previous or ber of ways. Consider the following script segment: Consider the following ber of ways. click the button titled you when will disappear This dialog box key combina the [ALT]+[F4] menu or through its control through box want to close a dialog to one of and must add the CANCEL keyword bar to the dialog box must add a title tion, you DIALOG, DIALOG, 290 DCS Script Language Reference DIALOG, Example This scriptsegment: For otherexamples,seeeachindividualdialogbox commandfollowing thissection. displays adialogbox thatrequires aresponse before otheractionsonthePC. performing continued DIALOG CANCEL WAIT RESUME DIALOG END BUTTON DEFAULT“&OK”RESUME TRUE MESSAGE“Pleaserespond!!” DIALOG “Hello”SYSMENUFALSEMODALTRUENOFOCUS\ 3 Commands 291 - - - command to DIALOG specifies the top left corner (x, y), width (w), and specifies the top left argument by an ampersand (&) causes the character to ap argument by Command Title Title (x, y, w, h) h) w, (x, y, argument specifies a logical command (either a single command or Title Title pressed, unless another button is highlighted. when the [ESC] key is Causes the button to be automatically clicked pressed, regardless of which button is highlighted. Allows the button to be automatically clicked when the [RETURN] key is Allows the button to be automatically clicked argument is specified by one of the following two keywords: by one of the following argument is specified dialog control command displays a button control in a dialog box. a button control command displays dialog control
Command Default argument is a string specifying the characters to display on the button. CANCEL Keyword Action DEFAULT Title Title (x, y, w, h) Default w, (x, y, the key of the underlined character simultaneously. Command The optional a command is not the logical command. If a command block). Clicking the button executes included, clicking the button has no effect. buttons (including buttons, may include a maximum of 128 You control. A button is an active icon buttons, and wide buttons) in a single dialog box. A default button is displayed in the dialog box with a black border. Only one DEFAULT but one DEFAULT Only with a black border. in the dialog box A default button is displayed ton may be specified per dialog box. Title The a character in the Preceding key and the [ALT] by pressing pear underlined on the button. The button can then be clicked tive to the dialog box which contains the button. The top left corner of the dialog box is (0,0). dialog box the button. The top left corner of the which contains to the dialog box tive (for example, (,,40,) can be specified one to four coordinates set is included, the coordinate If and set, DCS assigns a default size you do not include a coordinate If specifies width only). placement. Default The optional (x, y, w, h) w, (x, y, set The optional coordinate See the logical units. in are The coordinates height (h) of the button. rela are system. The (x, y) coordinates dimensions for your logical unit determine the proper Comments Arguments (DIALOG) BUTTON BUTTON BUTTON The (DIALOG) BUTTON (DIALOG) 292 DCS Script Language Reference (DIALOG) BUTTON, Example DIALOG CANCEL Wait Resume Dialog End BUTTON BUTTON CHECKBOX Dialog (,,38,15) (,,38,15)“1stButton” 0“InitiallyUnchecked” continued DEFAULT “Default” RESUME RESUME 3 Commands 293 - command will remove all existing dialogs command will remove DIALOG CANCEL argument is an integer (from 0 to 15) identifying a particular 0 to 15) (from argument is an integer dialog command removes the dialog box from the screen before the text trans before the screen from the dialog box command removes command. command removes the active dialog box from the screen. from dialog box the active command removes DialogIndex DialogIndex BUTTON DEFAULT “Continue” RESUME BUTTON DEFAULT “Continue” BUTTON CANCEL “Abort” CANCEL DIALOG END WAIT RESUME DIALOG CANCEL PERFORM text_receive DIALOG Capture...” MESSAGE “Preparing for Text DIALOG CANCEL the session window. to see the entire fer begins, enabling you created by the script in which the command appears. the script in which the command by created a ends, or upon executing when script execution the screen from a dialog box DCS removes DIALOG CANCEL this example: In DialogIndex The optional default value. as the uses zero it is not included, DCS If box. of -1, the specify a value you If Comments Example Arguments DIALOG CANCEL DIALOG CANCEL CANCEL DIALOG The DIALOG CANCEL DIALOG 294 DCS Script Language Reference (DIALOG) CHECKBOX The CHECKBOX (DIALOG) CHECKBOX Arguments Comments The optionalcoordinate set (x, y, w, h) CHECKBOX A checkbox isanactive control. You canobtainthestateofacheckbox usingthe command isnotincluded,changingthestateofcheckbox hasnoeffect. a commandblock).Changingthestateofcheckbox executes thelogicalcommand.If a The optional Command right ofthecheckbox. The CheckBoxText If thedefaultargumentisnotincluded,stateunchecked. The optional Default placement. specifies widthonly). If you donotincludeacoordinate set,DCSassignsadefaultsize and If thecoordinate setisincluded,onetofourcoordinates canbespecified(forexample,(,,40,) contains thecheckbox. Thetopleftcornerofthedialogbox is(0,0). unit dimensionsforyour system.The(x,y)coordinates are relative tothedialogbox which to thedisplayofcheckbox. See the not actuallychangethesize ofthecheckbox, butwillrestrict orenlargethespaceallocated height (h)ofthecheckbox (box andtext).Specifying awidthandheightforcheckbox will CheckBoxText oe Indicatesitischecked Indicatestheinitialstateisunchecked InitialState 1 (one) 0 (zero) Integer (x, y, w, h)Default function. You mayincludeamaximumof16checkboxes inasingledialogbox. Default Command argumentisastringdescribingthecheckbox option.It isdisplayed tothe dialogcontrol commanddisplaysacheckbox control inadialogbox. argument isanintegerspecifyingtheinitialstateofcheckbox: argument specifiesalogicalcommand(eithersingle or (x, y, w, h) CheckBoxText DIALOG specifies thetopleftcorner(x,y),width(w),and Command command todeterminetheproper logical (DIALOG) 3 Commands 295
RESUME RESUME “OK” continued 1 “My Life as a Dog” 1 “My Life as 0 “A Boy’s Life” His Dog” 0 “A Boy and Go to Heaven” 0 “All Dogs CheckBox3 DEFAULT END “Cancel” Checkbox (3) = 1 and CheckBox (2) = 0 Checkbox (3) = 1 and CheckBox IF PERFORM ELSE CANCEL DIALOG CANCEL Return Dialog CHECKBOX CHECKBOX CHECKBOX CHECKBOX BUTTON BUTTON DIALOG WAIT RESUME Example (DIALOG) CHECKBOX, CHECKBOX, (DIALOG) 296 DCS Script Language Reference DIALOG CONTROL dialog control. been created. The This commandallows the you toaltertheappearanceandbehaviorofdialogboxes aftertheyhave DIALOG CONTROL Arguments Note: which normallyprecede thesekeywords have beenomittedforclarity. specific syntaxforeachkeyword isgiven below. The The effectofthe Update BOX the integer1(one)to type isspecified by theinteger one. To specifythefirstbuttonorlist box inadialog box, assign The ControlNum ing keywords: The Control log box. If itisnotincluded,DCSuseszero asthedefaultvalue. The optional DialogIndex ControlNum Control . EDITTEXT CHECKBOX ICON BUTTON This commanddoesnotapplytoIBM TN3270emulations. DIALOG CONTROL argument indicateswhichcontrol toupdate DialogIndex
DialogIndex Update argumentisanintegerspecifyingthedesired control; thefirstcontrol ofeach ICONBUTTON RADIOBUTTON GROUPBOX LISTBOX argument varies, dependingupon whichkeyword isspecified.The ControlNum argument is an integer (from 0 to 15) identifying a particular dia argumentisaninteger(from 0to15)identifyingaparticular commandalsoupdatestheattributesofapreviously defined Control ControlNumUpdate argumentfollowing thekeyword MESSAGE Control andisspecified by oneofthe follow and ControlNum WIDEBUTTON RADIOGROUP BUTTON arguments or LIST - - - 3 Commands 297 - - before invoking the MOVE keyword. The coordinate set (x, before invoking the MOVE keyword. the control. y) specifies where in the dialog box to place proper logical See the DIALOG command to determine the (x, y) are The coordinates unit dimensions for your system. The top related to the dialog box which contains the control. left corner of the dialog box is considered (0,0). a dialog box as a default control. hidden control The SHOW keyword directs DCS to make a visible. to set the color of the text keyword directs DCS TEXT The The rval, in list boxes, messages, and titles of group boxes. green and gval and bval values represent the level of red, The color level is a number from 0 to blue, respectively. of the 255, where 255 represents the greatest saturation color. Description directs DCS to set the back The BACKGROUND keyword in dialog boxes, the text of list boxes ground color for icons The rval, titles of group boxes. and messages, and the the level of red, green, and gval and bval values represent to 255, number for a color level can range from 0 The blue. the greatest saturation of the color. where 255 represents directs DCS to make the control The DISABLE keyword inactive (it appears dimmed). directs DCS to make the control The ENABLE keyword active (it appears highlighted). specified The HIDE keyword directs DCS to remove the control should be hidden before invok A control from view. ing the MOVE keyword. control to a The MOVE keyword directs DCS to move the control should be hidden A new location in the dialog box. a control in The SETFOCUS keyword directs DCS to select continued
SHOW gval, bval) (rval, TEXT HIDE MOVE (x, y) SETFOCUS Keyword gval, bval) BACKGROUND (rval, DISABLE ENABLE DIALOG CONTROL, CONTROL, DIALOG 298 DCS Script Language Reference DIALOG CONTROL, Example In thisexample: the commandhighlightsfirstbuttonindialog. In thisexample: After adelayofsixseconds,thescriptremoves thedialogbox from thescreen. the edittextfieldchangestoblue,andmessageupdatesdisplay“ The scriptmakesthetextofeditfield green. When youclick the scriptdrawsadialogbox withanedittextfield,amessage(initiallyblank),andbutton. Dialog ControlButton1SetFocus Dialog Cancel Wait Delay“6” Dialog ControlMessage1Text(255,0,0);Red Dialog UpdateMessage1“Thanks!!” ;Blue Background Dialog ControlEdittext1Background(0,0,255) Wait Resume Dialog ControlEditText1Text(0,255,0);Green Dialog End Button Default“&OK”Resume Message (,,80)“ EditText (,,80)“Name:“ Dialog “ColorText” continued OK Thanks!! , thebackground of ” inred. 3 Commands 299 “&Ok” continued “1” “1” “1” (,,140) “New File Name” (,,140) “New “DeleteFile” “Select” File” (,,80) “Delete #Boolean Boolean = True DIALOG CONTROL BUTTON 2 SETFOCUS WAIT DELAY End BUTTON DEFAULT BEGIN #Boolean = False RESUME END Dialog End WHILE BEGIN DIALOG CONTROL BUTTON 1 SETFOCUS WAIT DELAY SETFOCUS DIALOG CONTROL EDITTEXT 1 WAIT DELAY # DIALOG EDITTEXT BUTTON BEGIN #Boolean = False PERFORM RESUME END DCS shifts the focus from one control to another until one of the buttons in the dialog box is the buttons in the dialog box to another until one of one control DCS shifts the focus from selected. In this script segment: In DIALOG CONTROL, CONTROL, DIALOG 300 DCS Script Language Reference (DIALOG) DIMENSION the coordinate setofacontrol. when theoptionalcoordinate setisnotincluded. You mayusethiscommandifyou have notspecified The DIMENSION Control Attribute Value (DIALOG) DIMENSION Comments Value Arguments Note: ing. Thedimensionsare reset to thesystemdefaultswhenanew The your system. specified Item. See the The The Attribute The Control Attribute Control (DIALOG) DIMENSION Value EDITTEXT CHECKBOX ICON BUTTON GROUPBOX
RIGHTMARGIN, LEFTMARGIN HTAB, VTAB WIDTH, HEIGHT Keyword Description and are largerthandialogboxes displayed whenusingSmall Fonts. example, ifdisplaysettingsare settoLargeFonts, scripteddialogboxes uselargefonts boxes in Windows alsoaffectdialogscreated withtheDCSScriptLanguage. For Therefore,system (Windows 95/98/NT). settingswhichaffectthedisplayofdialog Dialog boxes inthescriptlanguageare governed inmostcases by theoperating argument isanumericspecifyingthedesired dimension,inlogicalunits,ofthe argument isspecified by one of thefollowing keywords: argument isspecified by one of thefollowing keywords: commandspecifiesthedesired positionandsize ofacontrol. It isused
DIALOG ICONBUTTON RADIOBUTTON commandaffectsonlycontrols inthedialogbox you are defin command todeterminetheproper logicalunitdimensionsfor margin ofthedialogbox. These keywordslocateaControlfromtherightorleft type. cal distancebetweenspecifiedControlsofthesame These keywordsdefinethedesiredhorizontalandverti the specifiedControl. These keywordsdefinethedesiredwidthandheightof MESSAGE LISTBOX DIALOG RADIOGROUP
command isstarted. - - 3 Commands 301 - PASSWORD PASSWORD specifies the top left corner (x, y), width (w), and specifies the top left Text LIMIT NumChars PASSWORD LIMIT NumChars Text (x, y, w, h) w, (x, y, keyword directs DCS to display an asterisk for each character you you DCS to display an asterisk for each character directs keyword Prompt argument. DCS will initially include as many asterisks as the number of clause limits the number of characters DCS will initially display when it dialog control command displays an edit text control (both prompt charac (both prompt an edit text control command displays dialog control argument is a string specifying the text DCS initially displays in the text argument is a string specifying the text DCS clause, you may enter a maximum of 254 characters in the text box. clause, you argument is an integer specifying the width of the text box. If you do not you If of the text box. argument is an integer specifying the width Text Text command to determine the proper logical unit dimensions for your system. system. for your logical unit dimensions command to determine the proper argument, DCS assigns a default width. argument is not included, an empty text box is created. box argument is not included, an empty text argument is an integer specifying the number of characters. If you do not you argument is an integer specifying the number of characters. If PASSWORD PASSWORD Text Text LIMIT Box argument is a string specifying the character or text which will appear to the left argument is a string specifying the character LIMIT Box Text Text DIALOG (x, y, w, h) Box w, (x, y, NumChars Prompt characters you place in the Text argument. Text place in the characters you creates the text box, as well as limiting the number of characters you may enter in the text box. may enter in the text box. as limiting the number of characters you as well the text box, creates The include the PASSWORD The optional you to allows text. This keyword instead of displaying the entered enter into the edit text box, or authorization codes). information (like passwords sensitive protect as display as well the text box, want DCS to display asterisks when it initially creates you If must include both the you in the text box, entered asterisks after characters are and the keyword Prompt The specify a null string (“”). do not want a prompt, you If of the text box. Text The optional the If box. LIMIT NumChars The optional only the height of the text box, not the prompt. text box, only the height of the the See The edit text control. which contains the to the dialog box relative are The (x, y) coordinates (0,0). is considered top left corner of the dialog box example, (,,40,) For one to four coordinates. can specify set, you include the coordinate you If and set, DCS assigns a default size you do not include a coordinate If specifies the width only. placement. Box The optional include the (x, y, w, h) w, (x, y, set The optional coordinate modifies The height (h) coordinate and text box). (prompt text control height (h) of the edit Arguments (DIALOG) EDITTEXT EDITTEXT EDITTEXT The box. in a dialog ters and a text box) (DIALOG) EDITTEXT (DIALOG) 302 DCS Script Language Reference (DIALOG) EDITTEXT, Comments Example box. The control is an active control. The the sessionwindow. the edittextbox into sume text box inthisexampleis100dialogunitswide. When you selectthe DCS’s scriptlanguageallows you toenteramaximumof254charactersinthetextbox. The display adialogbox. These commands: You mayincludeamaximumof64edittextcontrols inasingledialogbox. (DIALOG) EDITTEXT Prompt option onthe DIALOG CANCEL DISPLAY $Text $Text =EDITTEXT(1) WAIT RESUME DIALOG END BUTTON (165,5,,) EDITTEXT 100“Prompt:”“DefaultText” DIALOG argument ofanedittextcontrol isastaticcontrol. Thetextbox ofanedittext Script $Text continued functionallows you togatherthecharactersyou enterintothetext menu, the . The DISPLAY DEFAULT (DIALOG) EDITTEXT command thenshows thecontentsof “OK” RESUME functionwillcopythetextfrom OK button orthe $Text Re in - 3 Commands 303 - - argu Message
RESUME RESUME “OK” command to determine the proper logical unit logical the proper command to determine specifies the top left corner (x, y), width (w), and specifies the top left DIALOG DEFAULT h) w, (x, y, Message CheckBox3 command displays a group box control in a dialog box. in a control box group command displays a (30,30) 1 “My Life as a Dog” (30,45) 0 “A Boy’s Life” (30,60) 0 “A Boy and His Dog” (30,75) 0 “All Dogs Go to Heaven” (20, 12, 120, 80) “Which Do You Like?” (20, 100,,) (80, 100,,) “Cancel” argument is a string specifying the message to display in the top left corner of argument is a string specifying the message PERFORM CANCEL Checkbox (3) = 1 and CheckBox (2) = 0 h) w, (x, y, DIALOG CANCEL CHECKBOX CHECKBOX CHECKBOX CHECKBOX BUTTON BUTTON DIALOG END WAIT RESUME IF ELSE Dialog GROUPBOX Message You may include a maximum of 255 messages in a single dialog box. may include a maximum of 255 You Since a should explicitly define the coordinates. set is optional, you Although the coordinate accurately pick a default size it encloses, DCS cannot is independent of the controls box group box. and placement for a group with no embedded text, use a null string (“”) for the box specify a group To ment. tains the group box. The top left corner of the dialog box is (0,0). corner of the dialog box The top left box. tains the group (for example, (,,40,) can be specified one to four coordinates set is included, the coordinate If and set, DCS assigns a default size you do not include a coordinate If specifies width only). placement. Message The box. the group a static control. is box A group h) w, (x, y, set The optional coordinate the See box. height (h) of the group which con to the dialog box relative are (x, y) coordinates system. The dimensions for your Example Comments Arguments (DIALOG) GROUPBOX GROUPBOX GROUPBOX The (DIALOG) GROUPBOX (DIALOG) 304 DCS Script Language Reference (DIALOG) ICON The ICON (DIALOG) ICON Arguments Example Comments (x, y, w, h) The optionalcoordinate set (x, y, w, h) attractive. These iconsdonothave anyotherfunctioninthedialog thantomakethedialogmore In thisexample,thescriptdisplaysiconsbasedon keywords suppliedtothe You mayincludeamaximumof255iconsinsingledialogbox. An iconisastaticcontrol. The IconId placement. specifies widthonly). If you donotincludeacoordinate set,DCSassignsadefaultsize and If thecoordinate setisincluded,onetofourcoordinates canbespecified(forexample,(,,40,) corner ofthedialogbox isat(0,0). The (x, y)coordinates are relative tothedialogbox whichcontainstheicon.Thetopleft See the size ofthe icon,butwillrestrict orenlargethespaceallocatedtodisplayoficon. height (h)oftheicon.Specifying awidthandheightforaniconwillnotactuallychangethe IconId Dialog Cancel Wait Resume Dialog End Button “Cancel”Resume Button Default“OK”Resume Icon Stop Icon Note Icon DCS ICON CAUTION DIALOG DYNACOMM CAUTION NOTE DIALOG argumentisspecified by one of thefollowing keywords: Note: commanddisplaysthespecifiediconcontrol inadialogbox. IconId command todeterminetheproper logicalunitdimensionsforyour system.
You mustencloseaniconIDwithinquotationmarks. (x, y, w, h) QUESTION “ specifiesthetopleftcorner(x, y),width(w),and STOP icon library resource ID ” ICON command. 3 Commands 305 - ” icon library resource ID resource icon library STOP Title Command Title
specifies the top left corner (x, y), width (w), and specifies the top left Default “ QUESTION h) w, (x, y, argument specifies a logical command (either a single command or Causes the icon button to be automatically clicked when the [ESC] key is Causes the icon button to be automatically clicked when the [RETURN] key is pressed, unless another button is highlighted. pressed, regardless of which button is highlighted. IconId command displays an icon button control. An icon button control is a An icon button control icon button control. command displays an argument is specified by one of the following keywords: by one of the following argument is specified You must enclose an icon ID within quotation marks. must enclose an icon ID within You argument is a string specifying the characters to display beneath the icon
is not included, no title is displayed beneath the icon button. is not included, no title is displayed command to determine the proper logical unit dimensions for your system. system. for your logical unit dimensions command to determine the proper
Command Title Title Default Note: Title Title argument is specified by one of the following keywords: by one of the following argument is specified h) w, (x, y, DIALOG CANCEL NOTE CAUTION DYNACOMM Keyword Action DEFAULT IconId Command The optional A default button is displayed in the dialog box with a black border. You may specify only one You with a black border. in the dialog box A default button is displayed button per dialog box. DEFAULT Title The optional a button. If Default The optional ally change the size of the icon button, but will restrict or enlarge the space allocated to the or enlarge the button, but will restrict of the icon ally change the size display of the icon button. the See The top which contains the icon button. to the dialog box relative are The (x, y) coordinates is at (0,0). left corner of the dialog box (for example, (,,40,) can be specified one to four coordinates set is included, the coordinate If and set, DCS assigns a default size you do not include a coordinate If specifies width only). placement. IconId The h) w, (x, y, set The optional coordinate not actu a width and height for an icon button will button. Specifying height (h) of the icon Arguments (DIALOG) ICONBUTTON ICONBUTTON ICONBUTTON The of an icon. button in the shape (DIALOG) ICONBUTTON (DIALOG) 306 DCS Script Language Reference (DIALOG) ICONBUTTON, Comments Example You mayincludeamaximumof128buttonsinsingledialogbox. An iconbuttonisanactive control. not included,clickingtheiconbuttonhasnoeffect. a commandblock).Clickingtheiconbuttonexecutes thelogical command.If acommandis retrieved from DCS’s iconlibrary, FSEICONS.DLL. This exampleissimilartotheprevious example. However, theiconforfirstbuttonis played inthisscriptare referred toby theirkeywords. shown inthe This exampleshows iconbuttonswhich, inadditiontoproviding anattractive qualityas Icon buttonscannotbeactivated by acceleratorkeysorkeyboard shortcuts. Dialog Cancel Wait Resume Dialog End Button “Cancel”Resume Button Default“OK”Resume Iconbutton Stop“Stop”Resume Iconbutton Note“Note”Resume Iconbutton DCS“DCS”Resume Iconbutton “_BinXfers”“Transfers”Resume DIALOG Dialog Cancel Wait Resume Dialog End Button “Cancel”Resume Button Default“OK”Resume Iconbutton Stop“Stop”Resume Iconbutton Note“Note”Resume Iconbutton DCS“DCS”Resume ICONBUTTON CAUTION“ DIALOG ICON command example,alsofunctionlikeanydialogbutton.Theiconsdis continued Caution ” RESUME - 3 Commands 307 - - command to ensure that command to ensure DIALOG UPDATE DIALOG UPDATE command to determine the proper logical unit di logical the proper command to determine specifies the top left corner (x, y), width (w), and specifies the top left argument is included, no record is initially selected. You You is initially selected. argument is included, no record DIALOG parameter reconstructs the list box into a drop-down list of items. into a drop-down the list box parameter reconstructs (x, y, w, h) w, (x, y, Record argument specifies a logical command (either a single command or a Record INVERT COMBOBOX Command COMBOBOX Record INVERT keyword lists the records in reverse order. in reverse lists the records keyword argument is an integer (from 0 to n) specifying which record number 0 to n) specifying which record argument is an integer (from command displays a list box control in a dialog box. in control list box command displays a Table Table COMBOBOX INVERT Command Record argument is an integer (from 0 to 15) identifying the table containing the desired containing the desired 0 to 15) identifying the table argument is an integer (from Table Table (x, y, w, h) w, (x, y, COMBOBOX The optional The other items appear when the down DCS displays the selected item in the combo box. of the fully must specify the size used for this type of list box The coordinates is selected. arrow open box. DCS initially selects. If no DCS initially selects. If number of -1, or use the may specify a record compiler the the number to prevent around put parentheses is best to It is selected. no record table = table (-1)). (for example, the expression misinterpreting from INVERT The optional Command The optional a com If the logical command. executes an item in the list box command block). Selecting item has no effect. mand is not included, selecting a list box the list box. The top left corner of the dialog box is at (0,0). of the dialog box The top left corner the list box. (for example, (,,40,) can be specified one to four coordinates set is included, the coordinate If and set, DCS assigns a default size you do not include a coordinate If specifies width only). placement. Table The data. Record The optional (x, y, w, h) w, (x, y, set The optional coordinate the See box. height (h) of the list which contains to the dialog box relative are (x, y) coordinates system. The mensions for your Arguments (DIALOG) LISTBOX LISTBOX LISTBOX The (DIALOG) LISTBOX (DIALOG) 308 DCS Script Language Reference (DIALOG) LISTBOX, Comments Example A listbox is anactive control. list box to bedisplayed inafixed-width font. the listbox andusethe If alistbox inadialogbox containsonlycolumnsofdata,associatethestructured tablewith played (inreverse order) inthelistbox. The datastored inthefilenamed You mayincludeamaximumoftenlistboxes inasingledialogbox. You canobtainthenumberofselectedrecord usingthe also clicked. If thelist box itemisselectedby double-clickingthemouse,defaultbutton(ifincluded)is Table Close0 Dialog Cancel Display @R0|“^M” Record Read0AtListbox() Wait Resume Dialog End Button “Cancel”Resume Button Default“OK”Resume Listbox 05Invert Dialog TABLE LOAD0FROM“ Table Define0FieldsChar12File continued SYSTEM TABLE.TXT command withthe0x0803parametertoforce thetextin C:\DCSERIES\Memo\Table.TXT isloadedinto Table 0(zero) andthendis (DIALOG) LISTBOX ” ASTEXT function. - 3 Commands 309 - ” AS TEXT in a dialog box. specifies the top left corner (x, y), width (w), and specifies the top left C:\DCSERIES\Memo\Table.TXT h) w, (x, y, Text command displays a message control command displays a command to determine the proper logical unit dimensions for your system. system. for your logical unit dimensions command to determine the proper argument is a string or string variable specifying the message to display. specifying the message argument is a string or string variable DIALOG Button “Cancel” Resume Dialog End Wait Resume Record Read 0 At Listbox () Dialog Cancel ;Manipulate the record ; ; Table Close 0 Table Define 0 Fields Char 12 File Table Define 0 Fields Char TABLE LOAD 0 FROM “ Dialog Message “Select a record from the file:” Listbox 0 5 Invert Button Default “OK” Resume h) w, (x, y, Text Text A message is a static control. messages in a single dialog box. may include a maximum of 255 You sage. the See The top left which contains the message. to the dialog box relative are the (x, y) coordinates is (0,0). corner of the dialog box (for example, (,,40,) can be specified one to four coordinates set is included, the coordinate If and set, DCS assigns a default size you do not include a coordinate If specifies width only). placement. Text The h) w, (x, y, set The optional coordinate change and height for a message will not actually a width Specifying height (h) of the message. to the display of the mes or enlarge the space allocated but will restrict of the message, the size Comments Example Arguments (DIALOG) MESSAGE MESSAGE MESSAGE The (DIALOG) MESSAGE (DIALOG) 310 DCS Script Language Reference (DIALOG) NEWLINE the dialogbox. The NEWLINE (DIALOG) NEWLINE Arguments Example Comments The message, andplacesthe the In thisexample: optional coordinate set. This commandmaybeusedtoplacedialogbox controls onsuccessive lines,withoutusingthe (DIALOG) NEWLINE (DIALOG) NEWLINE DIALOG CANCEL WAIT RESUME DIALOG END BUTTON “OK”RESUME NEWLINE NEWLINE MESSAGE “Thedateis:“|DATE() NEWLINE MESSAGE “Thetimeis:“|TIME() DIALOG commandplacesthenextspecifieddialogbox control onthenextlineof OK (DIALOG) NEWLINE commandtakesnoarguments. commandplacesthedatemessageonelinedown from thetime button twolinesdown from thedatemessage. controls placementonly. vertical 3 Commands 311 ” Resume in a dialog box. specifies the top left corner (x, y), width (w), and height specifies the top left C:\Graphics\Shuttle.BMP (x, y, w, h) w, (x, y, PictureId dialog control command displays a picture command displays dialog control command to determine the proper logical unit dimensions for your system. system. for your logical unit dimensions command to determine the proper argument is a string specifying the path and file name of a .bmp file (a device argument is a string specifying the path and DIALOG Dialog Cancel Return Dialog (, , 77, 145) PICTURE (5, 5, , ) “ “OK” Button (2, 125, , ) Default Button (43, 125, , ) “Cancel” Resume Dialog End Wait Resume PictureId h) w, (x, y, A picture is a static control. A dialog box can display only one picture. can display only one A dialog box is a static control. A picture See the See The top left picture. which contains the to the dialog box relative are The (x, y) coordinates is (0,0). corner of the dialog box (for example, (,,40,) can be specified one to four coordinates set is included, the coordinate If and set, DCS assigns a default size you do not include a coordinate If specifies width only). placement. PictureId The of the file format. extension must include the proper You independent bitmap format). (x, y, w, h) w, (x, y, set The optional coordinate the size will not actually change and height for a picture a width Specifying (h) of the picture. allocated to the display of the picture. or enlarge the space will restrict but of the picture, Comments Example Arguments (DIALOG) PICTURE PICTURE PICTURE The (DIALOG) PICTURE (DIALOG) 312 DCS Script Language Reference (DIALOG) RADIOBUTTON The RADIOBUTTON (DIALOG) RADIOBUTTON Arguments Example Comments The optionalcoordinate set (x, y, w, h) See the mand. You may includeamaximumof255radiobuttonsinsingledialogbox. A A radiobuttonisanactive control. pressing the[ALT] keyandtheofunderlinedcharactersimultaneously. will appearunderlinedintheradiobuttonname.Thecanthenbeselected by If anycharacterinthe right oftheradiobutton. The ButtonName placement. specifies widthonly). If you donotincludeacoordinate set,DCSassignsadefaultsize and If thecoordinate setisincluded,onetofourcoordinates canbespecified(forexample,(,,40,) left cornerofthedialogbox is(0,0). The (x, y)coordinates are relative tothedialogbox whichcontainstheradiobutton.Thetop See the display theradiobutton. actually changethesize oftheradiobutton,butwillrestrict orenlargethespaceallocatedto height (h)oftheradiobutton.Specifying awidthandheightforradiobutton willnot (DIALOG) RADIOBUTTON ButtonName DIALOG (DIALOG) RADIOGROUP (x, y, w, h) command todeterminetheproper logicalunitdimensionsforyour system. argumentisastringdescribingtheradiobuttonoption.It isdisplayed tothe ButtonName commanddisplaysaradiobuttoncontrol inadialogbox. ButtonName (x, y, w, h) commandmustfollow a command. argumentispreceded by anampersand(&),thecharacter specifiesthetopleftcorner(x, y),width(w),and (DIALOG) RADIOBUTTON com - 3 Commands 313
- -
(DIALOG) RADIOGROUP ] key and the key of the under ALT ) within a radio group. The radio but ) within a radio group. n Command specifies the top left corner (x, y), width (w), and specifies the top left argument is preceded by an ampersand (&), the character an ampersand (&), by argument is preceded GroupName GroupName h) w, (x, y, argument specifies a logical command (either a single command or a command defines a group of radio buttons in a dialog box. of group command defines a GroupName argument is not included, no radio button is initially selected. argument is not included, no radio button argument is an integer specifying which radio button DCS initially argument is an integer specifying which argument is a string specifying the title of the radio group, which is displayed which is displayed the radio group, argument is a string specifying the title of command to determine the proper logical unit dimensions for your system. system. for your logical unit dimensions command to determine the proper Default Command Default h) Default w, (x, y, DIALOG GroupName You may include a maximum of 16 radio groups in a single dialog box. may include a maximum of 16 radio groups You included, selecting a radio button has no effect. is a static control. A radio group 1 to sequentially (from numbered Radio buttons are to in which they appear in the script, not according to the order according numbered tons are their placement on the screen. can obtain the number of the radio button selected using the You function. GroupName The the radio group. above any character in the If the [ title. Pressing appears underlined in the radio group control. active the nearest lined character simultaneously highlights Command The optional a command is not the logical command. If a radio button executes command block). Selecting to display the radio button title. to display the radio button the See The top which contains the radio buttons. to the dialog box relative are The (x, y) coordinates is (0,0). left corner of the dialog box (for example, (,,40,) can be specified one to four coordinates set is included, the coordinate If and set, DCS assigns a default size you do not include a coordinate If specifies width only). placement. Default The optional the selects. If h) w, (x, y, set The optional coordinate and height for a radio button will not a width Specifying title. group height (h) of the radio space allocated or enlarge the radio button title, but will restrict of the actually change the size Comments Arguments (DIALOG) RADIOGROUP RADIOGROUP RADIOGROUP The (DIALOG) RADIOGROUP (DIALOG) 314 DCS Script Language Reference (DIALOG) RADIOGROUP, Example RETURN DIALOG CANCEL CANCEL ELSE PERFORM IF (RadioGroup(1)=3)and (2)=1) WAIT RESUME DIALOG END BUTTON BUTTON RADIOBUTTON RADIOBUTTON RADIOBUTTON RADIOBUTTON RADIOGROUP RADIOBUTTON RADIOBUTTON R RADIOBUTTON RADIOGROUP DIALOG Dialog Cancel Cancel Else Perform RadioGroup1 If RadioGroup(1)=1 Wait Resume Dialog End Button (80,100,,)“Cancel”Resume Button (20,100,,)Default“OK”Resume RadioButton (30,75)“AllDogsGotoHeaven” RadioButton (30,60)“ABoyandHisDog” RadioButton (30,45)“ABoy’sLife” RadioButton (30,30)“MyLifeasaDog” RadioGroup (30,15)“SelectOne” Dialog ADIOBUTTON (80,100,,)“Cancel” (20,100,,)Default“OK” (,,250,) SubCrazy (140,15)“SelectOneHereAlso” (30,15)“SelectOneHere” (140,75)“ALioninWinter” (140,60)“TheWindandtheLion” (140,45)“GonewiththeWind” (140,30)“Goin’South” (30,75)“AllDogsGotoHeaven” (30,60)“ABoyandHisDog” (30,45)“ABoy’sLife” (30,30)“MyLifeasaDog” continued RESUME RESUME 3 Commands 315 - - - - argu PIC ControlNum RADIOGROUP RADIOBUTTON WIDEBUTTON MESSAGE Updates the contents of the specified edit text box using box text edit specified the of contents the Updates specifying the new text to be displayed to the right of the check box. argument. the Text Updates the embedded text of the specified group The Message argument is a string specifying the box. replacement for the current message string. Directs DCS to update the title of the specified button. argument is a string specifying the updated Title The button title. Directs DCS to update the state of the check box and update the text displayed to the right of the specified must specify either the Default or the You check box. The Default argument is an argument, or both. Text integer (either zero or one) specifying a new default status of the check box; zero specifies unchecked, and Text argument is a string The one specifies checked. Control ControlNum Update Control ControlNum argument is an integer (from 0 to 15) identifying a particular 0 to 15) (from argument is an integer dia argument varies, depending upon which control attribute keywords attribute keywords depending upon which control argument varies, GROUPBOX LISTBOX ICON PICTURE ICONBUTTON
argument is an integer specifying the control; the first control of each type is of each type the first control argument is an integer specifying the control; the except argument keyword, each Control argument must follow Update TEXT
command updates a previously defined dialog control. previously command updates a DialogIndex DialogIndex DialogIndex argument indicates which control to update and is specified by one of the follow by one of the to update and is specified argument indicates which control EDITTEXT EDITTEXT GROUPBOX Message Keyword Action Title BUTTON Text CHECKBOX Default BUTTON CHECKBOX EDITTEXT keyword. Control ControlNum ControlNum TURE Update The effect of the text. The in the following is given is specified. The syntax for each keyword ment has been omitted for clarity. The ing keywords: ControlNum The by the integer 1 (one). specified The DialogIndex The optional the default value. as DCS uses zero it is not included, If log box. Control Arguments DIALOG UPDATE DIALOG UPDATE DIALOG UPDATE UPDATE DIALOG The DIALOG UPDATE DIALOG 316 DCS Script Language Reference DIALOG UPDATE, RADIOBUTTON ButtonName PICTURE FileName MESSAGE Text LISTBOX ICONBUTTON IconId Title ICON IconId Keyword Action continued New Table:New tion inasinglerecord. specify eitheranewtabletobeloaded,ormodifica the followingarguments: ton. The ICONBUTTON keywordrequiresoneorbothof specifying theIDofnewicontobedisplayed. sists ofonetheavailableiconkeywords,orastring radio button. specifying thenewtexttoappear totherightof radio button. The ButtonNameargumentisastring Updates thetextdisplayedto rightofthespecified the pathandnameofpicture. ment withthePICTUREkeyword.FileNamespecifies the adialogbox.DonotincludeControlNumargu Changes theBMP orWMFimagecurrentlydisplayedin string replacingthecurrentmessagestring. Updates thespecifiedmessage. The Text argumentisa Modify Record: Updates thedatainspecifiedlistbox. You may Updates thetitleandiconofspecifiedbut Updates thespecifiedicon. TheIconIdargumentcon
Title IconId TABLE number keyword mayhaveoneortwoarguments: If asinglerecordistobemodified,theLISTBOX Record Text may havethreearguments: If anewtableistobeloaded,theLISTBOXkeyword
the replacementdataforspecifiedrecord. The secondkeyword, is modified. cord integer specifyingwhichrecordtomodify. If The optionalfirstkeyword, rects DCStodisplaytherecordsinreverseorder. The optionalthirdkeyword, by default. ger specifyingtherecordnumbertobeselected The optionalsecondkeyword, ber ofthetablecontainingnewdata. The firstkeyword, TABLE, isfollowedbythenum beneath theiconbutton. A stringthatspecifiesthenewtexttoappear ID ofthenewicon;and An iconkeywordorastringthatspecifiesthe is notincluded,thecurrentlyselectedrecord Record INVERT Text , isastringspecifying Record INVERT Record , isanoptional , whichdi , isaninte Re ------3 Commands 317 - - is updated to dis . ” “Merry Christmas!” within the radio group is to be selected initially; and within the radio group pear above the radio group. Default, an integer specifying which radio button Default, an integer specifying the new title to ap GroupName, a string specifying
edittext1 Updates the default radio button and the title of the Updates the default radio keyword The RADIOGROUP specified radio group. the following arguments: requires one or both of Title The specified wide button. Updates the title of the the new title. argument is a string specifying GIFT LIST continued ” followed by the contents of by ” followed DIALOG END WAIT RESUME DIALOG CANCEL CANCEL *update “ | edittext(1) DIALOG UPDATE MESSAGE 1 “Thanks RETURN DIALOG (,,260,100) “ MESSAGE (,,400) “Merry Christmas!” EDITTEXT 100 “Enter Name:” NEWLINE Gift:” EDITTEXT 120 “Enter Desired BUTTON “Enter” PERFORM update BUTTON “Exit” RESUME Action Keyword Default GroupName RADIOGROUP Title WIDEBUTTON Thanks when the Enter button is clicked, the message when the Enter play “ In this example: In Example DIALOG UPDATE, UPDATE, DIALOG 318 DCS Script Language Reference DISCONNECT The DISCONNECT DISCONNECT Arguments Example The optional WINDOW WinHandle disconnects from thehost,terminating thesession. DCS loadsasessionfileandconnectstothehost.Aftertransferiscomplete, In thisexample: ment. If the The ment. The WINDOW DISCONNECT DISPLAY “Filenotsent” IF ERROR() FILE SENDBINARY“DATA.TXT”“”“secret”AS“data1” CANCEL IF ERROR()orNOTCONNECT CONNECT LOAD “HOST7” WINDOW WinHandle WinHandle WINDOW command terminatestheconnectionwithhost. WINDOW clause terminatesthesessioninwindow specified by the argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular clause isnotincluded,allconnectedsessionswillbeterminated. clause includesthe WINDOW keyword andthe WinHandle WinHandle argu argu - - 3 Commands 319 - - - - - DIS WIN command argument. DISPLAY DISPLAY WinHandle argument in the cur argument. If the argument. If String clause causes DCS to display the WinHandle keyword and the keyword command to display carriage returns as command to display carriage returns WINDOW DISPLAY DISPLAY WINDOW have 254 characters each, the following script lines 254 characters each, the following have $String2 CRONLY WINDOW WinHandle CRONLY coordinate set indicates the row and column in the session window and column in the session window set indicates the row coordinate and clause includes the String argument is an integer identifying a particular session window. The CRONLY keyword is not applicable to 3270 emulations. keyword The CRONLY command only displays text in a session which is connected to a host. strategically placed occur, errors command can help todebug a script. If example, con command displays a maximum of 254 characters at a time. For WINDOW (Row, Col) (Row, $String1
argument contains the characters to display. command writes a sequence of characters into a connected session window, but it does window, of characters into a connected session command writes a sequence argument in the session window specified by the specified argument in the session window commands might pinpoint which command is generating the error (see the second commands might pinpoint which command is generating the error clause is not included, DCS displays the contents of the Note: DISPLAY DISPLAY DISPLAY DISPLAY WinHandle String (Row, Col) (Row, sider that if String DOW highlighted and connected session window. rently The The PLAY example). The CRONLY the causes keyword The optional CRONLY the it is not included, line feeds). If by only (not followed carriage returns in the string. displays a line feed character after every character displayed carriage return WINDOW WinHandle The optional The the session is connected in a session window, a If zero. cursor posi DCS displays the string starting at the current do not include coordinates, you If tion. or columns in the session is larger than the number of rows which a coordinate provide you If the between bar (the area either in the status (e.g., 75, 75), the string is displayed window position 0,0. or at and the toolbar or bottom of the DCS application window) session window particularThe display location is dependent on the emulation. String The (Row, Col) (Row, The optional and the first column is column zero, row is row the first string, where in which to display the Comments Arguments DISPLAY DISPLAY DISPLAY DISPLAY The system. the remote not send the text to DISPLAY 320 DCS Script Language Reference DISPLAY, Example will onlydisplay displayed inthe sessionwindow mightpointtotheproblem. help determinewhichcommand isnotexecuting asexpected.If anerror occurs,themessages and assumingaconnectedsession, the In thisexample: the (zero). DCSreads eachrecord andallows you toexaminetheminthesessionwindow using and assumingaconnectedsession,DCSdefinesloadsan Excel spreadsheet into Table 0 In thisexample: DISPLAY continued END BEEP1 DISPLAY “Table0not loaded” BEGIN IF ERROR() TABLE LOAD0FROM“DATA”ASSYLK END BEEP1 DISPLAY “Table1notdefined” BEGIN IF ERROR() TABLE DEFINE1TEXT“MYFILE” END BEEP1 DISPLAY “Table0notdefined” BEGIN IF ERROR() TABLE DEFINE0FIELDSCHAR2040 END INCREMENT %1 DISPLAY (%1,0)@R0 RECORD READ0 BEGIN WHILE NOTEOF() SET %10 TABLE LOAD0FROM“BUDGET.XLS”ASSYLK TABLE DEFINE0FIELDSCHAR10INT5 ;line above),since$String1has254characters ;cursor willbeinthesameplaceasscript ;DCS willnotdisplay$String2(theterminal DISPLAY ;characters ;in thesessionwindow),since$String1has254 ;terminal cursorwillremainattheendof$String1 ;carriage return,afterdisplaying$String1(the ;DCS willnotdisplaytheControl-M,a DISPLAY command. $String1 $String1|$String2 $String1|“^M” : DISPLAY command isusedasadebugging toolto 3 Commands 321 - - is an integer indicat is an integer indicat h h is an integer indicating the width in w , where h , Value(s) On, Off Blink, Steady 1 (true), 0 (false) 0 to 9999 1 (true), 0 (false) 1 (true), 0 (false) Value(s) 1 (true), 0 (false) Value(s) 1 (true), 0 (false) w is an integer indicating the width in h, where w, pixels of the font, and where ing the height in pixels of the font. w pixels of the font, and where ing the height in pixels of the font. 1 (true), 0 (false) The name of a monospace or fixed pitch font on your system. 1 (true), 0 (false) 1 (true), 0 (false) 2 (on) 0 (auto), 1 (off), 2 (on) 0 (auto), 1 (off), 1 (true), 0 (false) 1 (true), 0 (false) 1, 2, 3, 4, 5 dialog. Boolean Type String String Block String Boolean Integer Boolean Boolean Type Boolean String Boolean String Type Boolean Boolean String String Boolean Boolean Integer Session Properties Session WINDOW WinHandle WINDOW tab of the command sets display parameters for a session window. These settings are These settings are parameters for a session window. command sets display argument is composed of a keyword followed by the assignment operator (=) and a the assignment operator (=) by followed of a keyword argument is composed Displays Displays Blinking Keywords Cursor Tab CursorVisible CursorType CursorBlink AutoScrollToCursor HistorySize ReverseHistory SaveClearedScreen Font Tab Keywords Font Tab AutoSizeFont FontSize MinFontSize String UseEmulationFont FontFaceName General Tab Keywords General Tab TopStatusLine BottomStatusLine HorizontalScrollbarMode VerticalScrollbarMode ShowSessionButtons TerminalBorder MaximumScrollRate String The keywords and the their values are in the table below: values are and the their The keywords String The setting. valid Arguments DISPLAYCONFIG DISPLAYCONFIG String DISPLAYCONFIG The on the available DISPLAYCONFIG 322 DCS Script Language Reference DISPLAYCONFIG, Comments Example The The optional The optional WINDOW WinHandle character inthesessionwindow. affect thecurrently highlightedsessionwindow. Theyturnonthesessioncursorasablock These scriptlines: highest setting,andrequire DCStoautomaticallyresize fontsasthesessionwindow isresized. affect theactive sessionwindow. Theyturnontheterminalborder, setsthescroll ratetothe These scriptlines: ERROR Also see: DisplayConfig “CursorType=Block” DisplayConfig “CursorType=On” DisplayConfig “AutoSizeFont=True” DisplayConfig “MaximumScrollRate=16” DisplayConfig “TerminalBorder=True” WinHandle WINDOW function returns TRUE ifthe
GETDISPLAYCONFIG continued clauseincludesthe argument is an integer identifying a particular childwindow. argumentisanintegeridentifyingaparticular command WINDOW WinHandle keyword andthe or String keyword isinvalid. WinHandle argument. 3 Commands 323 - argument is an integer specifying the length of time the DTR line is to be held specifying the length of time the DTR argument is an integer command directs DCS to hold low the DTR line of a session’s serial port for a speci the DTR line of a session’s to hold low DCS command directs This command does not apply to IBM TN3270 emulations. not apply to IBM This command does *hangup SEND “logout” DROPDTR 300 DelayUnits
DCS sends the logout command to the remote system, then drops the DTR line low for 300 the DTR line low system, then drops DCS sends the logout command to the remote the connection. to break milliseconds in order low, where one delay unit equals one millisecond. one delay where low, valid only for the serial portsThis command is and modems. this example: In DelayUnits The Note: Comments Example Arguments DROPDTR DROPDTR DelayUnits DROPDTR The fied number of milliseconds. DROPDTR 324 DCS Script Language Reference EDIT COPY is equivalent toselecting The EDIT COPY EDIT COPY Arguments Example Comments String %Session1Hnd copies anytextselectedinthesessionwindow specified by thewindow handlecontainedin This example: places acopyofthetextintoclipboard. in thevariable the In thisexample: your mouseorcursorkeys. BUFFER The String clause andthe rent selectionintheactive editwindow iscopied. However, ifyou includeboththe If the dle The dle The optional WINDOW WinHandle DCS childwindow, DCSwillnotaffecttheclipboard contents. window. If you have notincludedthe the The optional argument. argument.The SCREEN String EDIT COPY WINDOW WINDOW EDIT COPYWindow%Session1Hnd EDIT COPYSCREEN(0,0,,%WnHnd) String WINDOWWinHandle argument only. commandcopiescharacterstotheclipboard. Executing the commands(invisibleselections),butworks withvisibleselectionsyou makewith argument, DCSwillcopythevisibleselectionmadeincurrently active child WINDOW String function provides thefirstlineofawindow (whosewindow handleiscontained clausespecifiesthecurrent selectioninthewindow identified bythe String %WnHnd clauseandthe command does not work in concert withthe commanddoesnotwork inconcert Copy . WinHandle argument specifiestexttocopytheclipboard. If you have notincluded argument inthecommand,commandwilldefaulttocopying on the clauseiscomposedofboththe ) tothe Edit argument is an integer identifying a particular childwindow. argumentisanintegeridentifyingaparticular String EDIT COPY menu. String argument are notincludedinthecommand,cur command.The argument andnocharactersare selectedina WINDOW EDIT COPY SELECTION keyword andthe EDIT COPY commandthen or SELECTION command WINDOW WinHan WinHan - - -
3 Commands 325 - . - - , you FileName The CLIPBOARD keyword is valid with all of the formats allowed for this If you want to send text from a session window to the printer, you must use you must use to the printer, If you want to send text from a session window If you want to copy a graphical capture of a session to the clipboard If a session window is active, this command captures the entire DCS ap plication window and places it in the clipboard (regardless of whether the script has made a selection in the session window). is the active window. keyword as the Format argument (see the Format argu include the BITMAP ment below). window and sends it to the command captures the entire DCS application made a selection in the session printer (regardless of whether the script has window). to a file, you must use the If you want to save text from a session window keyword as the TEXT the FILE phrase as the Destination argument and The FILE phrase is below). Format argument (see the Format argument string argument, composed of the keyword FILE and an optional made a selection in the ses The FILE phrase assumes that the script has and also assumes that the sion window with the SELECTION command session window is the active window. or TEXT command (see the Format argument below). When you include the keyword makes the same assumptions keywords, the CLIPBOARD TABLE as the PRINTER keyword, but copies the text to the clipboard. keyword as the Format argument (see the Format must include the BITMAP argument below). Once copied to the clipboard, the image may be pasted it into an open file in an application which supports the bitmap format (such as Windows Paint). the PRINTER keyword as the Destination argument and the TEXT keyword TEXT and the the PRINTER keyword as the Destination argument The PRINTER below). as the Format argument (see the Format argument selection in a session window keyword assumes that the script has made a that the session window with the SELECTION command and also assumes you must session to the printer, If you want to send a graphical capture of a The window is active. The PRINTER keyword assumes that a session command copies text to a destination. command copies text
argument is specified by one of the following keywords: of the following by one argument is specified
The EDIT COPYSPECIAL command does not apply to the IBM TN3270 emulation. TN3270 command does not apply to the IBM The EDIT COPYSPECIAL
FILE FileName CLIPBOARD Keyword Action PRINTER Destination
Destination The Note: Arguments EDIT COPYSPECIAL EDIT EDIT COPYSPECIAL Destination Format WINDOW WinHandle WinHandle Format WINDOW Destination EDIT COPYSPECIAL The EDIT COPYSPECIAL 326 DCS Script Language Reference EDIT COPYSPECIAL, Comments The Format TION When copyingtext,the The integer specifyingasessionwindow. The WINDOW WinHandle ERROR WINDOW Format orS TABLE BITMAP TEXT Keyword Availability ELECTION BUFFER
argument maybeoneofthefollowing keywords: function issetto TRUE ifDCScannotcompletethiscommand.
clause and EDIT COPYSPECIAL continued Available onlywiththeCLIPBOARDkeyword. Available onlywiththeCLIPBOARDandPRINTERkeywords. above). Available forallthreedestinationkeywords(seetheDestinationargument WinHandle commands. argument mustbeincluded.Thewindow handleisan command works in concert withthe commandworks inconcert SELEC - 3 Commands 327 %TermWinHnd loop, the script searches the script searches loop, WHILE function to retrieve a list of function to retrieve TEXT WINDOW HWNDLIST HWNDLIST “Ed1.TXT” (%Ptr < Length ($WHnd)) (%Ptr < Length and uses the AND “Ed1.TXT” %TermWinHnd Main continued 0 5 #Found WndTitle(Num ((Substr ($WHnd, %Ptr, %ChrNHnd))))= \ ((Substr ($WHnd, %Ptr, %ChrNHnd))))= WndTitle(Num SELECTION EDIT COPYSPECIAL FILE WINDOW OPEN MEMO Cancel IF $Set BEGIN #Found = True ($WHnd, %Ptr, %ChrNHnd)) %TermWinHnd = Num (Substr END Else BEGIN %Ptr = %Ptr + %ChrNHnd + 1 END END WINDOW ACTIVATE $Set = “Main” %ChrNHnd = 6 () $WHnd = HWndList #Found = False %Ptr = 1 WHILE NOT BEGIN assumes the active session is assumes the active in the Next handles of the open DCS child windows. window When the script finds the handle, it activates handle of the session window. for the window to a memo copies the lines selects the first six visible lines in the window, the session window, and then opens the memo window. window, This script: Example EDIT COPYSPECIAL, EDIT COPYSPECIAL, 328 DCS Script Language Reference EDIT CUT and thendeletestheselectionfrom thewindow. The EDIT CUT EDIT CUT Arguments Example Comments WINDOW WinHandle from thedocument. DCS searches theactive documentwindow forthestringversion In thisexample: Cut In scriptandmemowindows, executing the BUFFER The deleted from thesessionwindow. handle ofasessionwindow, theselection isonlycopiedtotheclipboard; theselectionisnot edit window iscopied,andthendeleted, from thewindow. If the If the dle The The optional The optional argument. WINDOWWinHandle EDIT CUT WINDOW on the WINDOW EDIT CUT EDIT FIND“version4.70” commandcopiesthecurrent selectionfrom theactive child window totheclipboard commands,butdoeswork with selectionsyou makewithyour cursorkeysormouse. Edit WinHandle WINDOW command does not work in concert withthe commanddoesnotwork inconcert clause specifiesthecurrent selectioninthewindow identified bythe menu. clause isnotincludedinthecommand,current selectionintheactive clause includesthe argument is an integer identifying a particular childwindow.argument isanintegeridentifyingaparticular WINDOW EDIT CUT keyword andthe commandisequivalent toselecting SELECTION 4.70 WinHandle andcutstheselection WinHandle or argumentisthe SELECTION WinHan argument. - 3 Commands 329 ” - - argument. argument. New version WinHandle ” is displayed. function returns function returns WinHandle ERROR keyword and the keyword Old version WINDOW in the window, the in the window, String keyword directs DCS to search the text backward from the current the current from the text backward to search DCS directs keyword clause includes the keyword directs DCS to perform a case-sensitive search. If it is not in If DCS to perform search. a case-sensitive directs keyword clause is not included in the command, DCS will search the active edit win the active will search clause is not included in the command, DCS argument is an integer identifying a particular child window. clause directs DCS to search a window specified by the specified a window DCS to search clause directs CASE REVERSE WINDOW WinHandle WINDOW CASE REVERSE REVERSE WINDOW CASE argument specifies the string for which to search. argument specifies the command searches a child window for a string and, if found, selects it. for a string a child window command searches EDIT FIND “DCS version 4.0” IF ERROR () DISPLAY “Old version” ELSE DISPLAY “New version” WINDOW WinHandle WINDOW String DCS searches the document window for the specified string. If it is found, “ for the specified string. the document window DCS searches it is not found, “ If in the session window. is displayed If the If dow. DCS cannot find the contents of If TRUE. this example: In cluded, the search is performed without regard to the capitalization of the specified string. to the capitalization is performedcluded, the search regard without REVERSE The optional is performed the current it is not included, the search forward from document position. If position. WINDOW WinHandle The optional The The String The CASE The optional Comments Example Arguments EDIT FIND EDIT EDIT FIND String EDIT FIND The EDIT FIND 330 DCS Script Language Reference EDIT GOTO dow. The EDIT GOTO Line EDIT GOTO Arguments Example Comments Line document window. DCS placesthecursoratbeginningofeachlineasitnumbers thefirst20linesin In thisexample: specified, DCSwillpositionthecursoratlastlineofdocument. active editwindow. If a If the Handle The The The optional WINDOW WinHandle The WINDOW WinHandle Line WINDOW END INCREMENT %line EDIT PASTE EDIT COPYSTR(%line)|“ EDIT GOTO%line BEGIN WHILE %line<=20 %line =1 argument. commandpositionsthecursoratbeginningofspecifiedlineinachildwin argument isanintegerspecifyingthelinenumberofcursor. WINDOW WinHandle WINDOW clause directs DCStopositionthecursorinawindow specified by the clause isnotincludedinthecommand,DCSwillpositioncursor argument is an integer identifying a particular childwindow.argument isanintegeridentifyingaparticular Line clause includesthe argument largerthanthenumberoflinesindocumentis WINDOW keyword andthe WinHandle argument. Win - - 3 Commands 331 - on the argument. Paste Paste increases, the increases, %line WinHandle WinHandle keyword and the keyword command is equivalent to selecting command is equivalent WINDOW argument. EDIT PASTE EDIT WinHandle WinHandle clause includes the are copied to the clipboard and then pasted into the edit window. copied to the clipboard are argument is an integer identifying a particular argument is an integer child window. clause is not included in the command, DCS will paste the text into the ac clause is not included in the command, DCS clause directs DCS to paste the contents of the clipboard as a text selection in a to paste the contents of the clipboard DCS clause directs WINDOW %line command copies text from the clipboard to the current selection in a DCS child to the current the clipboard from command copies text WINDOW WinHandle WINDOW %line = 1 WHILE %line <= 20 BEGIN EDIT GOTO %line “ EDIT COPY STR (%line) | “ EDIT PASTE INCREMENT %line END WINDOW menu. WINDOW WinHandle WinHandle the first 20 lines in the document window are numbered. As the value of As the numbered. are the first 20 lines in the document window contents of The by the specified window the If edit window. tive the executing edit windows, In Edit this example: In WINDOW WinHandle The optional The Comments Example Arguments EDIT PASTE EDIT EDIT PASTE EDIT PASTE The window. EDIT PASTE 332 DCS Script Language Reference EDIT REPLACE String2 The EDIT REPLACEString1String2 EDIT REPLACE Arguments Comments . String1 The instance of Each execution ofthe ing In scriptormemowindows, executing the script ormemowindow. If the ment. The The The optional WINDOW WinHandle tion. If from forward itisnotincluded,thesearch thecurrent isperformed position. The optional REVERSE withoutregardperformed tothecapitalizationofspecifiedstring. The optional CASE The String2 The Replace WINDOW WinHandle String2 String1 ERROR WINDOW String1 argumentspecifiesthetextwhichisto replace theindicatedstring. argument specifiesthestringforwhichtosearch. on the WINDOW REVERSE CASE commandsearches ascriptormemowindow for function returns TRUE if clause replaces clause isnotincludedinthecommand,DCSwillreplace argument is an integer identifying a particular childwindow.argument isanintegeridentifyingaparticular thatitfinds. Edit keyword acase-sensitive search. performs If itisnotincluded,thesearch is EDIT REPLACE clause includesthe menu. keyword searches thetextbackward from thecurrent document posi String1 CASE REVERSEWINDOWWinHandle inawindow, whichisspecified by the commandsearches forandreplaces onlythefirst String1 EDIT REPLACE WINDOW isnotfound. keyword andthe commandisequivalent toselect String1 andreplaces itwith WinHandle String1 WinHandle intheactive argument. argu - - - 3 Commands 333 ” in dog ” is replaced by the word “ the word by ” is replaced cat continued EDIT GOTO 1 () WHILE NOT ERROR “cat” “dog” EDIT REPLACE These commands: each instance of the string “ establish a loop whereby edit window. the active Example EDIT REPLACE, EDIT REPLACE, 334 DCS Script Language Reference EMULCONFIG tion fortheactive session. The EMULCONFIG String EMULCONFIG Arguments String settings forindividualclientoptionsthatare purchased installedseparately. for theemulationsprovided inthebaseproduct. The remaining tableslistkeywords and valid The firstsixtablesappearingbelow andonthenexttwopageslistkeywords and validsettings tive session. setting. Together, thekeyword andthesettingare usedtoconfigure theemulation fortheac The String SCREENROW CODEPAGE850 LOCALECHO DESTBACKSPACE LINEWRAP MODE Keywords for ANSI LINETERMINATOR AUTOLINEFEED AUTOSCROLL LOCALECHO Keywords for ADDS Viewpoint Note: argument includesakeyword followed by theassignmentoperator(=)andavalid
command isusedtosetthevalue ofaparameterusedintheemulatorconfigura Tandem 6530and TN3270, are valid onlyiftheclientoptionhasbeeninstalled. Configuration keywords foremulationsshippedwithclientoptions,suchas
WINDOW WinHandle
24, 25 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) ansi, tty, scoansi Valid Setting(s) none, cr, creot,cretx 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) Valid Setting(s) - - 3 Commands 335 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) vt52, vt100, vt101, vt102, vt220, vt320, vt420 24, 25, 36, 48 80, 132 7, 8 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) Setting(s) Valid pcat2 att605, att705, pcxt, pcat1, 7, 8 1 (true), 0 (false) 24, 25 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 80, 132 1 (true), 0 (false) 1 (true), 0 (false) (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) usascii, frenchcanadian Setting(s) Valid
continued NEWLINE NUMPADAPPLICATION CURSORKEYAPP LIGHTSCREEN MODE SCREENROW COLUMNS BITCONTROL DESTRUCTIVEBS ANSWERBACK string GISEXTENSION DISPLAYCONTROLSMODE LOCALECHO LINEWRAP LINEWRAP NUMPADAPPLICATION LIGHTSCREEN DISPLAYCONTROLS NRCMODE NRCLANG Keywords for Digital VT Keywords for AT&T 605/705 AT&T for Keywords MODE BITCONTROL DELETE SWAP SCREENROW NEWLINE LOCALECHO DESTRUCTIVEBS COLUMNS EMULCONFIG, EMULCONFIG, 336 DCS Script Language Reference EMULCONFIG, ANSWERBACK string MARGINBELL SOUNDS AUTOSCROLL RECEIVECR LINEWRAP LOCALECHO CLEARONWIDTHCHANGE COMMMODE ENDOFBLOCK MODE Keywords forWYSE LOCALEDITKEYS DISPLAYCONTROLS LIGHTSCREEN ANSWERBACK string MODEL NUMBEROFPAGES COLUMNS LINESPERPAGE MODE Keywords forTVI925/950
continued
1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) full, block,half,halfblock uscr, crlfetx wyse50, wyse60 Valid Setting(s) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) TV925, TV950 1, 2,4 80, 132 24, 48,96 Full Duplex,HalfBlock,Local Valid Setting(s) 3 Commands 337
1 – 80 line, page 1 (true), 0 (false) tab, return, enter US, EUR all, fields 0 – 9 all, modified N, L, T N, L, T N, L, T 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) HP700/92, HP700/94 80, 132 Valid Setting(s) Valid CRLF CR, LF, 80, 132 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) Setting(s) Valid 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false)
continued
STARTCOL LINEPAGE BLOCKMODE NUMPADTAB 700/94 only) (HP DECIMALTYPE PRINT 700/94 only) IMPDECDIGITS (HP 700/94 only) (HP TRANSMIT ATTRF1 ATTRF2 ATTRF3 AUTOLF TABSPACES WARNINGBELL LOCALECHO SPOW INHHNDSHK ESCXFER RETURNENTER MODEL COLUMNS DISABLEAUXPRINTMODE 700/94 Keywords for HP BELL INVERSEBACKGROUND XMITFNCTN INHEOLWRP INHDC2 AT&T4425 Keywords for RETURNKEYSENDS COLUMNS LOCALECHO AUTOWRAP string ANSWERBACK NEWLINEONLINEFEED If the HP 700/94 Client Option is installed, these keywords are available: are is installed, these keywords the HP 700/94 Client Option If If the AT&T 4425 Client Option is installed, these keywords are available: are keywords is installed, these Client Option 4425 the AT&T If EMULCONFIG, EMULCONFIG, 338 DCS Script Language Reference EMULCONFIG, * (on-screen functionkey) REMOTEMODE (on-screen functionkey) MODIFYALL* (on-screen functionkey) MEMORYLOCK* (on-screen functionkey) LINEMODIFY* (on-screen functionkey) KEYBOARDLOCK* (on-screen functionkey) FORMATMODE* (on-screen functionkey) DISPLAYFUNCTIONS (on-screen functionkey) BLOCKMODE (on-screen functionkey) AUTOLF STRINGF8 string STRINGF7 string STRINGF6 string STRINGF5 string STRINGF4 string STRINGF3 string STRINGF2 string STRINGF1 string LABELF8 LABELF7 LABELF6 LABELF5 LABELF4 LABELF3 LABELF2 LABELF1 ATTRF8 ATTRF7 ATTRF6 ATTRF5 ATTRF4 Keywords forHP 700/94 is notconnected thesekeywordswillalwaysreturn “ screen keyscanonlybecorrectly returnedwhenthesessionisconnected; when usingthesekeywordswith the GETEMULCONFIGfunction,stateoftheseon- continued 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) string (0–16characters) string (0–16characters) string (0–16characters) string (0–16characters) string (0–16characters) string (0–16characters) string (0–16characters) string (0–16characters) L, T N, L, T N, L, T N, L, T N, L, T N, Valid Setting(s)
FALSE” ,
continued
, evenifsetto“ TRUE” . 3 Commands 339 - -
1 (true), 0 (false) lic_8, or Greek_8 1 (true), 0 (false) UK_7, Swedish_7, Danish_7, Norwegian_7, Belgian_7, Portuguese_7 file, device none, printer, File name or device name (up to 256 charac ters) Valid Setting(s) Valid 1 (true), 0 (false) 1 (true), 0 (false) 0 (disables) 1 (true), 0 (false) 1 (true), 0 (false) 1-80 1 (true), 0 (false) del_symbol_ no_response, error_msg_only, del_symbol_and_error_msg only, known as Latin_1_8), Cyril (also Westeurp_8 USASCII, French_7, German_7, Spanish_7, continued AUX1 or AUX2 AUX1 or AUX2DEVICE AUX1_DEVICE or EM3270_MODE LOCAL_TRANSMIT_COLUMN BLOCK_TYPE_AHEAD CI_ERROR_RESPONSE NATIONAL_LANGUAGE_SUPPORT_8_BIT LANGUAGE_8 NATIONAL_LANGUAGE_SUPPORT_7_BIT LANGUAGE_7 Keywords for Tandem 6530 Keywords for Tandem EXEC_FUNCTION RETURN_FUNCTION BELL_COLUMN 1-80 ALLOWHOSTCOLORS If the Tandem 6530 Client Option is installed, the following keywords and valid settings are are settings and valid keywords the following is installed, 6530 Client Option Tandem the If available: EMULCONFIG, EMULCONFIG, 340 DCS Script Language Reference EMULCONFIG, available: If theIBM TN3270 ClientOption isinstalled,thefollowing keywords andvalid settingsare FS3270_TLS FS3270_GraphicalOIA FS3270_RespectNumeric FS3270_DisplayNulls FS3270_ConvertNulls FS3270_AutoSkip FS3270_Uppercase FS3270_CharacterSet FS3270_LUName FS3270_LongName FS3270_TypeAhead FS3270_Notify FS3270_Sound FS3270_AltSize FS3270_OEMReply FS3270_ExtAttrib FS3270_TermModel FS3270_TermType Keywords forTN3270 continued
describe thesessionanditsconnection. yes (enabled) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) German CECP French, Swiss FrenchCECP, Swiss German,Swiss Speaking CECP, Swedish,Swedish CECP, Swiss CECP, Spanish CECP, Speaking,Spanish Spanish Norwegian, Norwegian CECP, Portuguese,Portuguese Italian, Italian CECP, Netherlands,Netherlands CECP, CECP, Finnish,Finnish CECP, French,French CECP, CECP, English‑US C370CECP English‑ US,US (Old),C370 lingual CECP, Danish,Danish CECP, English‑UK, Belgian CECP, Canadian Bilingual,Bi Austrian/German, Austrian/German CECP, Belgian, should matchthenamesinlistbox. This stringisnotcasesensitive,butthecharacters Microsoft SNA Serverconnector. name isnotrequired,unlessDCSconnectingviathe percent %,dollars$,number#,andatsign@). This and specialcharacters(suchasthefollowingsymbols: sitive, andcanconsistofnumbers,uppercaseletters, be uniqueamongotherlogicalunitnames,iscasesen A sequenceof up toeightcharacters. The namemust String, A sequenceofuptoeightcharacters,which 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 2, 3,4,5 IBM3278, IBM3279 Valid Setting(s)
V2,English‑US - -
3 Commands 341
- - argument. V2, English‑ US WinHandle
keyword and the keyword C370 English‑ US, English‑ US (Old), English‑ US English‑ US C370 CECP CECP, French, French CECP, Finnish, Finnish CECP, CECP, Netherlands, Netherlands CECP, Italian, Italian CECP, Portuguese, Portuguese Norwegian, Norwegian CECP, Spanish Speaking, Spanish Spanish CECP, CECP, Swiss Swedish, Swedish CECP, Speaking CECP, Swiss German, Swiss French, Swiss French CECP, German CECP 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) Valid Setting(s) Valid 2, 5 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) characters, which sequence of up to eight A String, its connection. describe the session and This string is not case sensitive, but the characters should match the names in the list box. Belgian, Austrian/German CECP, Austrian/German, Bi Canadian Bilingual, Canadian Belgian CECP, English‑ UK, Danish, Danish CECP, lingual CECP, WINDOW
clause includes the argument is an integer identifying a particular session window. clause applies the emulation configuration settings to a particular session win continued WINDOW FS5250_UpperCase FS5250_DisplayNulls FS5250_GraphicalOIA FS5250_CharacterSet Keywords for TN5250 FS5250_TermModel FS5250_Sound FS5250_Notify FS5250_TypeAhead FS5250_LongName WINDOW WinHandle The dow. WINDOW WinHandle The optional The If the IBM TN5250 Client Option is installed, the following keywords and valid settings are settings are and valid keywords the following is installed, Client Option TN5250 the IBM If available: EMULCONFIG, EMULCONFIG, 342 DCS Script Language Reference EMULCONFIG, Comments Example tive session window. If the script languageratherthanusingthedialogbox. erties The keywords correspond toparametersavailable onthe the commandsetsemulatorscreen columnwidthto80. In thisexample: The ERROR WinHandle EMULCONFIG “Columns=80” dialog. Thiscommand,therefore, allows you tosettheseparametersthrough theDCS function returns TRUE ifthe continued isnotspecified,theemulationconfigurationsettings are appliedtotheac WinHandle or Emulations String keyword isinvalid. tab ofthe Session Prop - - 3 Commands 343 - command. BEGIN command earlier in the script. In command earlier in the script. In command is TRUE. commands are used to define a block of com used to define a block commands are WHILE END TABLE DEFINE TABLE and command BEGIN BEGIN
command takes no arguments. END . . . Also see: . . . RECORD READ 0 WHILE NOT EOF () BEGIN DISPLAY @R0 | “^M” RECORD READ 0 END command specifies the end of a command block. command specifies assumes a table has been defined with the assumes a table has been defined with the the this script segment shown, as long as the repeatedly mands that execute This script example: The by a command block must be preceded The commands in the Example Arguments Comments END END The END 344 DCS Script Language Reference EXECUTE stopped thescriptandselected The EXECUTE Target EXECUTE Arguments Example Comments Target label target if thethird radiobuttonin In thisexample: execution (variables, tables,etc.). The execution ofan or afartarget(usuallyanotherscriptroutine inanotherscript). The Target add_values EXECUTE “values*add_values” IF RADIOGROUP(1)=3 values*add_values command restarts scriptexecution withascriptorroutine (asifyou had argument isspecified by eitheraneartarget(usually routine inthecurrent script) EXECUTE . Execute RADIOGROUP command clearsanyexistingresources created duringscript on the . Thiscausesexecution to resume inthescript values atthe Script 1 (one)isselected,execution branchesto thefar menu). 3 Commands 345 - and com argument. WinHandle ONLINE.TXT LOGTOFILE LOGTOFILE keyword and the keyword WINDOW command saves the data in the file command saves clause includes the FILE CLOSE argument is an integer identifying a particular child window. WINDOW command terminates the text transfer process initiated by a initiated by the text transfer process command terminates WINDOW WinHandle WINDOW DIAL ‘5552222’ PERFORM login_sequence LOGTOFILE ‘ONLINE.TXT’ PERFORM get_data FILE CLOSE This command does not apply to IBM TN3270 emulations. not apply to IBM This command does WinHandle WinHandle has been received, the has been received, then closes the file. The this example: In When all the data incoming data. to capture DCS logs onto the dial-up service and prepares WINDOW WinHandle The optional Note: Example Arguments FILE CLOSE FILE CLOSE The mand. FILE CLOSE 346
DCS Script Language Reference FILE COMPRESS byte file. The FILE COMPRESSFileName FILE COMPRESS Arguments Example Comments FileName See the the fileifit: The seven databits. filetoanASCIItextfile,allowing ittobetransferreda binary bya protocol thatutilizes only carriage returns) are toASCIIcharacters converted The linelengthislimitedtoamaximumof130characters,andallcontrol characters(except ment mustspecifyavalid filenamefor your system. The ERROR FileName
If eitheraread orwriteerror occurs during thecompression. Cannot replace thecontentsoforiginalfile(forexample,ifis read-only), hard drive) file(forexample,ifthere isnotenoughfreeCannot openatemporary spaceon your Cannot openthefile(forexample,ifdoesnotexist) FILE ENCRYPT function returns TRUE ifDCScannotcompress thefile.DCS will notcompress argumentisastringspecifyingthefiletobecompressed. The command converts aneight-data-bits-per-byte commandconverts fileintoaseven-data-bits-per- andthe FILE DECOMPRESS . The commands. FILE COMPRESS command converts command converts FileName argu - 3 Commands 347 ), a file. The clause $SourceFile Source ), and copies the source files to ), and copies the source #Erase argument. Destination argument to be specified for the APPEND and the ), and a Boolean flag ( is not included, DCS clears the content of the existing file before of the existing file before is not included, DCS clears the content TO subroutine takes a source file specification ( takes a source subroutine the contents of the source file to the destination file, creating the to the destination file, file the contents of the source Destination keyword causes the data to be appended to the existing contents of the causes the data to be appended to the existing contents of the keyword APPEND $DestPath argument is a string specifying the file to which the data is to be copied. The argument is a string specifying the file to function returns TRUE if the source file does not exist. if the source TRUE function returns APPEND argument is a string specifying the file containing the data to be copied. The specifying the file containing the data to argument is a string argument must specify a valid file name for your system. file name for argument must specify a valid command copies clause allows the clause allows argument must specify a valid file name for your system. your for file name a valid argument must specify BEGIN FILE COPY $NextFile TO $DestPath IF #Erase FILE FILE DELETE $DestPath $NextFile = Next () END *moveFiles ($SourceFile, $DestPath, #Erase) ARGUMENTS ($NextFile) $NextFile = ROUTE ($SourceFile) WHILE NOT ERROR () ERROR TO Destination Source WHILE NOT ERROR the destination path ( the specified directory file). (with an option to delete the source copying the contents of the source file. copying the contents of the source The this example: In TO The is composed of the keyword Destination The Destination APPEND The optional If destination file. Source The Source Comments: Example Arguments FILE COPY FILE COPY Source TO Destination TO Source FILE COPY The does not exist. destination file if it FILE COPY 348
DCS Script Language Reference FILE CREATENAME for thenameoffiletocreate. Thefilenameisstored inastring variable. The FILE CREATENAME FileName FILE CREATENAME Arguments in thecommand. file opendialogbox displayed forthiscommand, if you have notincluded the The and similarlywith the charactersfrom lect thetextfrom todisplayinthe which filenamesinadirectory list box. A The textcontainedina and that FilterSpec follow each Spec Each elementofthisstringmustendwithanumbersign(#) The ment isastringthatspecifiesthetypeoffilestolist. this command.If you donotincludethis clause,DCSlistsfilesofalltypes.The The optional TYPE Type characters from thefileusing the NOCREATE does notaskyou whetheritshould deletethecontentsofpreviously existingfiles. With the However, ifyou have includedtheoptional click the deletes theprevious contentsofthefileandplacenamein FileName variable. If you replace thecontentsoffilelocatedindirectory. If you clickthe If you enterafilenamewhichexistsinthecurrent directory, DCSasks you whetheritshould in thecurrent working directory. ously exist,DCSstores filenameinthe thenew Save As The FileName TYPE FileName FilterSpec1 n “FileDescription1#FilterSpec1#FileDescription2#FilterSpec2#…” are theelementsofstring,anda dialogbox displayed forthiscommand.If you enterafilenamewhichdidnotprevi FileDescription2 No No n FilterSpec argument musthave thefollowing format: elementsformaunit,suchthat FileDescription keyword, DCSopensthefiletoallow you toappendcharactersordelete button, DCSputsanullcharacterintotheFileName variable. TYPE argumentisastringvariable inwhichDCSstores thefilenameentered inthe elementwillbecomethedefault textforthe FileDescription1 commanddisplaysthe FileDescription2 FilterSpec1 clause lists only files of a particular typeinthe clause listsonlyfilesofaparticular n elementiscomposedofcharactersDCSusesasacriterionto determine FileDescription TYPEType DEFAULT StringTITLETitleText NOCREATE
is associatedwith n elementanditsnumeralsign.The todeterminewhichfilesshow inthe TABLE inthe , DCSusesthecharactersfrom n
element appearsina and List ofFiles of Type Save As FilterSpec NOCREATE FilterSpec2 FileDescription1 RECORD File Name FileName dialoglistingtheavailable files,andprompts n elementanditsnumeralsignmust , andsoon. commands. keyword withthiscommand,DCS argumentandcreate anemptyfile listbox. For example,whenyou se . isassociatedwith File Name FileDescription List ofFiles of Type drop-down listbox, DCSuses FileDescription Save As FilterSpec2 Yes edittextbox inthe File Name button, DCS dialog displayed for n DEFAULT
, andsoon. and n FilterSpec1 TYPE
and the listbox, drop-down Filter argu - clause , - - - 3 Commands 349 - File File might n argument in element from element from argument NOCREATE NOCREATE argument is a
FilterSpec String TitleText dialog for this command. FileSpec1 TitleText function TRUE. returns Save As Save ERROR argument. clause in the command) or will leave the clause in the command) or will leave String argument must be a valid file name for your file name for argument must be a valid keyword with this command, DCS does not ask keyword element must be valid for your system. Wildcard Wildcard system. for your be valid element must n TYPE commands. clause, DCS will display the String dialog DCS displays, or if you select a file name that exists dialog DCS displays, or if you FilterSpec NOCREATE Open Open RECORD DEFAULT DEFAULT dialog displayed for this command. The dialog displayed and Displays all of the file names whose extension start with D. Displays all of the file Displays all file names which begin with L and have five characters after the L and have five which begin with Displays all file names start with DC. and whose extensions L Displays all text file names which start with M. Displays all text file names clause directs DCS to display the contents of the DCS clause directs continued Open Open clause directs DCS to display the contents of the DCS to display the contents clause directs TABLE TABLE button in the edit text box when DCS initially displays the edit text box function returns TRUE if you decide not to create a file. For example, if you se For example, if a file. not to create decide if you TRUE function returns DEFAULT DEFAULT TITLE
clause (if you have included the have clause (if you
Cancel Cancel *.D* M*.TXT L?????.DC* edit text box empty initially. The empty initially. edit text box ERROR File Name File TYPE A file name and its path may have a maximum of 256 characters. A file name and its path may have NOCREATE include the optional have you If With the files. existing previously whether it should delete the contents of you append characters to or to delete characters from you to DCS opens the file to allow keyword, the file using the The lect the the file, the in a directory choose not to overwrite and you The optional the not included the have you If the Name in the characters not place wildcard system. Do TITLE TitleText The optional in the title bar of the string specifying the text for the title bar. The format of the characters in a of the characters in The format example, acceptable. For are and the question mark, characters, the asterisk be one of the following: String DEFAULT Comments FILE CREATENAME, FILE CREATENAME, 350
DCS Script Language Reference FILE CREATENAME, Example This command: name isstored inthestringvariable in thecurrent directory. filenamehasbeenentered,When afileisselected,ornew thefile opens a This command: variable. selected inthe you havename basedonthecharactersinedittextbox, fileinthedirectory placesthenew Name title ofthedisplayed displays thefilenameswithaDAT extensioncontainedinthecurrent working directory. The of Type displays theSave Asdialog.By default,DCSselectsData Files ( edittextbox andthenselectthe FILE CREATENAME$fileTYPE“*.DCP” Task)#*.DC*#” TITLE“DCS’sFiles” *.DAT#Mail Files(TXT)#M*.TXT#Scripts(Text&\ FILE CREATENAME$FileNameTYPE“DataFiles(*.DAT)#\ drop-down listbox, displaysthetext Save As Directories dialogwhichdisplaysalistbox containingallfileswithaDCPfileextension Open continued list box, andthenplacesthenameoffilein dialog box isDCSFiles. When you placeafilenameinthe $file OK . button, DCScreates anemptyfileandgives ita *.DAT inthe File Name *.DAT edittextbox, and ) inthe $FileName List Files File
3 Commands 351 - - argu command FileName FILE COMPRESS command. command restores a file compressed with the a file compressed command restores argument is a string specifying the file to be decompressed. The specifying the file to be decompressed. argument is a string function returns TRUE if DCS cannot decompress the file. DCS will not decom if DCS cannot decompress TRUE function returns FILE ENCRYPT Cannot open the file (for example, if the file does not exist) Cannot open the file (for example, if the your space on Cannot open a temporary is not enough free if there file (for example, drive) hard read-only) file (for example, if the file is the contents of the original Cannot replace occurs during the decompression. or write error a read If
FileName ERROR See the See The the file if it: press FileName The your system. name for file valid ment must specify a Example Comments Arguments FILE DECOMPRESS FILE DECOMPRESS FileName FILE DECOMPRESS The to its original state. FILE DECOMPRESS 352
DCS Script Language Reference FILE DECRYPT The FILE DECRYPT FileNameKey FILE DECRYPT Arguments Example Comments FileName See the The the The Key ment mustspecifyavalid filenamefor your system. The Key ERROR Key FileName
DCS cannotoverwrite theoriginalfile(forexample,ifis read-only). A read orwriteerror occursduringthedecryption file DCS cannotcreate atemporary ENCRYPT.DLL cannot load (forexample,ifyour computerhaslittlefree memory) The password isincorrect The filedoesnotexist The fileisnotencrypted FILE ENCRYPT argument inthe argument is a string used for file decryption. argument isastringusedforfiledecryption. It mustbethesamestringspecifiedas function returns TRUE if: command modifies the contents of the specified encrypted filetobe readable. command modifiesthecontentsofspecifiedencrypted argument is a string specifying the file to be decrypted. The argumentisastringspecifyingthefiletobedecrypted. command. FILE ENCRYPT command. FileName argu - 3 Commands 353 - File command. argument is a string specifying the file (or directory) argument is a string The to be deleted. function returns TRUE if the file does not exist. TRUE function returns command deletes the specified file or directory. command deletes the FILE COPY argument must specify a valid file name for your system. your for file name a valid argument must specify ERROR FileName The the See FileName The Name Example Arguments Comments FILE DELETE FILE DELETE FileName FILE DELETE The FILE DELETE 354
DCS Script Language Reference FILE ENCRYPT unreadable unless decrypted usingthe unreadable unlessdecrypted The FILE ENCRYPT FileNameKey FILE ENCRYPT Arguments Example Comments FileName script file,itmustfirstbedecompressed andthendecrypted. transfer. Later, atthe toencodeitscontentsand compressed soitcanbesentusinga text a scriptfileisencrypted In thisexample: The CRYPT The Key ment mustspecifyavalid filenamefor your system. The ERROR Key FileName
FILE DECRYPT“MYFILE.DCP”“secretcode” FILE DECOMPRESS“MYFILE.DCP” FILE RECEIVEBINARY“MYFILE.DCP” . . . FILE SENDBINARY“MYFILE.DCP” FILE COMPRESS“MYFILE.DCP” FILE ENCRYPT“MYFILE.DCP”“secretcode” DCS cannotoverwrite theoriginalfile(forexample,ifis read-only). A read orwriteerror occursduringtheencryption file DCS cannotcreate atemporary ENCRYPT.DLL cannot load (forexample,ifyour computerhaslittlefree memory) The filedoesnotexist command in order to decrypt thefile. commandinorder todecrypt argument isastring,whichmustbeusedasthe commandmodifiesthecontentsofspecifiedfile,makingitappeartobe function returns TRUE if: argument is a string specifying the file to be encrypted. The argumentisastringspecifyingthefiletobeencrypted. FILE RECEIVE FILE DECRYPT command,thehostreturns thefile. For DCStousethe command. Password argument ofa FileName FILE DE argu - - 3 Commands 355 , - , argu clause - File File might drop- n Type Type Filter Open Open FilterSpec2 and the FilterSpec1 n and DEFAULT DEFAULT n FilterSpec drop-down list drop-down dialog displayed for dialog displayed edit text box in the edit text box list box. For example, For list box. Open Open List of Files of Type of List of Files FileDescription FileDescription File Name File is associated with File Name File , and so on. element and its numeral sign must List of Files of Type of List of Files n , DCS uses the characters from , DCS uses the characters from to determine which files to show in the to determine which files to show in the element must be valid for your system. Wildcard Wildcard system. for your element must be valid FileDescription1 number sign (#). FilterSpec2 n FilterSpec element will appear in a n FilterSpec1 FileDescription2 FilterSpec FileDescription1 element is composed of characters DCS uses as a criterion to element is composed of characters DCS element and its numeral sign. The n n TYPE Type DEFAULT String TITLE TitleText String TITLE DEFAULT TYPE Type is associated with Displays all file names which begin with L and have five characters after the Displays all file names which begin with Displays all of the file names whose extension start with D. L and whose extensions start with DC. L Displays all text file names which start with M. FileDescription clause lists only files of a particular type in the
FilterSpec element will become the default text for the command displays a file open dialog box listing the available files and prompts files and listing the available file open dialog box command displays a argument is a string variable that stores the file name entered in the in the the file name entered stores that variable argument is a string TYPE
FileDescription elements form a unit, such that n argument must have the following format: the following argument must have
FileDescription2 are the elements of the string, and a are *.D* M*.TXT L?????.DC* list box, and similarly with list box, n FilterSpec1 Type Type FileName “FileDescription1#FilterSpec1#FileDescription2#FilterSpec2#…” file open dialog box displayed for this command, if you have not included the you have for this command, if displayed file open dialog box in the command. The format of the characters in a example, acceptable. For are characters, the asterisk and the question mark, be one of the following: FilterSpec and that The text contained in a A list box. down determine which file names in a directoryto display in the select the text from when you DCS uses the characters from box, Name and so on. The TYPE Type The optional do not include this clause, DCS will list files of all types. The you this command. If for DCS to list. ment is a string specifying the type of files The a Each element of this string must end with Spec each follow FileName The for this command. dialog displayed Arguments FILE OPENNAME FILE OPENNAME FileName FileName FILE OPENNAME The variable. in a string the file name to open. The command then stores for the name of a file you FILE OPENNAME 356
DCS Script Language Reference FILE OPENNAME, Example Comments If you wantthecontentsof have included the the edit textbox whentheFile Open dialogdisplaysforthiscommand.If you have notincluded The optional DEFAULT String $FileName in the The titleofthe File Name drop-down listbox, displaysthetext*.DAT inthe displays an This command: command. The string specifyingthetextfortitlebar. in thetitlebarof The optional TITLE TitleText which todisplayfiles. If the String DEFAULT ERROR String Default “*.DAT”TITLE“DataFiles” \ *.DAT#” (*.*)# Files “Data TYPE $FileName OPENNAME FILE File Name argument mustbeavalid filenameandshouldnotcontainanywildcard characters. listbox thefileswithaDAT extensioncontainedinthecurrent working directory. Open TITLE DEFAULT argument contains a valid path, DCS uses that path as the default directory fromargument containsavalid path,DCSusesthatpathasthedefaultdirectory function returns TRUE whenyou cancelthe variable. clause, DCSwilldisplaythe Open edittextbox andthenselect dialog. By default,DCSselectsData Files ( TYPE continued clause directs DCStodisplaythecontentsof Open dialog thatDCSdisplaysis“Data Files”. When you enterafilename clause displaysthecontentsof clause inthecommand)orwillleave theedittextbox emptyinitially. dialog displayed forthiscommand. The String argument toappearinthe FileSpec1 OK File Name , DCSplacesthenameoffilein elementfrom the Open String *.DAT edittextbox, anddisplaysin the dialog DCSdisplaysforthis File Name argument inthe TitleText ) inthe TitleText TYPE edittextbox, the List Files of Type argumentisa clause (ifyou argument File Name
3 Commands 357
- . LOGTOFILE VACATION.TXT menu is selected. File File on the . New New command executes, DCS resumes recording recording DCS resumes command executes, VACATION.TXT FILE RESUME command is executed, or command is executed, subroutine, DCS stops recording the session and executes the the session and executes DCS stops recording subroutine, OAG command takes no arguments. command takes no FILE RESUME command temporarily suspends the text transfer initiated by the active the active suspends the text transfer initiated by command temporarily ;performs commands that retrieve new mail from host sys ;performs commands that retrieve tem FILE RESUME ;resumes the test file transfer PERFORM hotel hotel information from ;performs commands that retrieve the hosts system FILE CLOSE “VACATION.TXT” ;terminates the file transfer DIAL PERFORM login to remote system ;connects and performs login LOGTOFILE “VACATION.TXT” the file VACATION.TXT ;captures data from host to PERFORM OAG data from OAG System ;perform commands that retrieve FILE PAUSE ;pause the text file transfer PERFORM checkmail This command does not apply to IBM TN3270 emulations. not apply to IBM This command does FILE PAUSE the session until it saves and closes the session until it saves DCS logs onto an online system and begins saving the session in the file After performing the When the checkmail subroutine. In this example: In The Note: Arguments Example FILE PAUSE FILE PAUSE The command, until a FILE PAUSE 358
DCS Script Language Reference FILE RECEIVEBINARY transfer protocol specifiedinthe Session oftheactiveProperties session. The NEITHER APPEND WINDOWWinHandle FILE RECEIVE FILE RECEIVEBINARY Arguments had ontheremote system. when you donotincludethe transferprotocol. binary When theKermit protocol isnotconfigured forasessionwindow, or you have alsoconfigured theactive sessionwindow tousethe Kermit transferprotocol asits When DCSemulatesanon-3270terminal,thecommandonly recognizes thisclausewhen valid filenameon your system. specifying thenameunderwhichreceived fileisstored. The under anamedifferent from thenameon remote system.The but isrequired fortransfersinvolving 3270emulations.Thisclause allows you tosave thefile The AS Dest string (“”),notawildcard string(*.*). batch transfer. To receive multiplefiles, you shouldsetthe The Kermit, YModem, andZModem transfersofmultiplefiles,or transferprotocols support mit protocol only. You mayrename thefileon your PCusingthe The The FileName The BINARY FileName word For theKermit protocol, modethenyou iftheremote mustusethekey systemisinserver NARY transfer protocol mustbespecifiedforthesessionbefore executing the Kermit onanon-3270remote GET commandtoaKermit host.The server Kermit binary The optional REMOTE AS FileName FileName FileName REMOTE TSO: HostFileNameHostMemberNamePassword CMS: HostFileNameHostFileType HostFileMode commandwiththe clause isanoptionalargumentfortransfersinvolving non-3270terminalemulations, argumentmustspecifyavalid filenamefor your system. REMOTE REMOTE argumentmustbethesameasfilenameon remote systemforthe Ker argumentmightbeinoneofthefollowing formats: argumentisastringspecifyingthefileinwhichtostore theincomingfile.The . BINARY FileName commandprepares file DCStoreceive thespecifiedfileusingbinary keyword causesthe REMOTE AS clause, DCSsaves thefileundersamenamethat keyword. FILE RECEIVEBINARY AS Dest
ASCII BINARY CRLFNOCRLF FileName Dest AS Dest Dest argumenttoanempty commandtoissuethe argumentmustspecifya FILE RECEIVEBI argumentisastring clause. - - - 3 Commands 359 - argument. command is WinHandle keyword and the keyword WINDOW FILE RECEIVE REMOTE BINARY continued command. clause includes the keyword is for IND$File transfers only. This keyword causes DCS to causes This keyword only. transfers is for IND$File keyword keyword is for IND$File transfers only. This keyword specifies an This keyword transfers only. is for IND$File keyword keyword is for IND$File transfers only. This keyword directs DCS to re DCS to directs This keyword transfers only. is for IND$File keyword clause is not included in the command, the file is received through the current current the through received is file the the command, in included not is clause argument is an integer identifying a particular child window. Kermit GET clause directs DCS to receive a file using the file transfer configuration of a a file using DCS to receive clause directs function returns TRUE if you abort the transfer, or if DCS aborts the transfer, or if DCS aborts the transfer, abort if you the transfer, TRUE function returns APPEND WINDOW ASCII CRLF WINDOW WinHandle WINDOW ERROR due to too many transmission errors. When there is an error, DCS places text describing the is an error, When there due to too many transmission errors. system variable. in the Result error the If session. The The particular session. DCS aborts system does not begin sending the specified file within 30 seconds, the remote If indicating it abortedthe transfer and displays a dialog box the transfer. the protocol, systems using the Kermit For to a equivalent The If you do not include this keyword, end of record marks are removed and not replaced. removed are marks record end of do not include this keyword, you If APPEND The optional record override the contents of the specified file and to append the incoming file to the existing the existing contents If it is not included, DCS clears specifications. format length and record TSO a option is used only when transferring files to This received. the file is of the file before command processor. VM/CMS or WINDOW WinHandle The optional ASCII The optional on the local computer. a text file is stored for text files before EBCDIC to ASCII translation is Do not include this option if the file the file is not translated. the option is not included, If format. in ASCII already CRLF The optional a line feed character. by character followed with a carriage return marks place all end of record Comments FILE RECEIVE BINARY, BINARY, FILE RECEIVE 360
DCS Script Language Reference FILE RECEIVEBINARY, Example DCS prepares toreceive allincomingfilesviaZModem, andthendownload thefile In thisexample: (“”) standsforthe dataset(thehostfile hasnomembername)anullstring the hostfileisnotfrom apartitioned ronment. Thecommanddirects DCS receives thehostfileandstores itin In thisexample,DCSprepares toreceive afilefrom a running theremote system TSO envi ment. DCSreceives thespecifiedhostfileandstores itin In thisexample,DCSprepares toreceive afilefrom a remote systemwiththeCMSenviron and thestringEXITcausesremote systemtoexittheKermit application. on your PC.The to sendthefile or transferringfiles,onthe remote system. the In thisexample,DCSinstructs remote system operations,suchasviewing mode,yourKermit systemcansendcommandstoperform server theremote mode. DCS instructs systemtoenterKermit server When theremote systemisin In thisexample: TXT . File ReceiveBinary“datfile”“”“pass”AS“datfile.tx” FILE RECEIVEBINARY SEND “EXIT” KERMIT FINISH FILE RECEIVEREMOTEBINARY“LOG.COM”AS“LOG.TXT” WAIT STRING“COMMAND” SEND “SERVER” WAIT STRING“KERMIT-32>” SEND “KERMIT” SET BINARYTRANSFERKERMIT FILE RECEIVEBINARY“MEMO.TXT” SET BINARYTRANSFERSZMODEM LOG.COM KERMIT FINISH HostMemberName . The continued AS LOG.TXT command instructs theremote mode, commandinstructs systemtoleave server “File”“data”“A1”AS“data.TXT” argument. clausedirects DCStorename thereceived file DATA.TXT . datfile.tx MEMO. . Since - - 3 Commands 361 - be argument argument must OLDDATA to the name specified to the name specified Source Destination Source is protected by renaming the file to renaming by is protected MYDATA argument is a string specifying a newThe file name. function returns TRUE if the source file does not exist or if the destination file file does not exist or if the destination if the source TRUE function returns argument is a string specifying the file to be renamed. The specifying the file to be argument is a string command changes the name of the file specified by name of the file specified command changes the FILE DELETE “OLDDATA” . IF EXISTS (“OLDDATA”) FILE RENAME “MYDATA” TO “OLDDATA” FILE RECEIVE BINARY “MYDATA” Destination ERROR Source the current contents of the file the current a binary receiving file of the same name. fore Destination The your system. file name for must specify a valid The exists. already this example: In Source The your system. file name for specify a valid Comments Example Arguments FILE RENAME Destination FILE RENAME Source TO Destination Source TO FILE RENAME The by FILE RENAME 362
DCS Script Language Reference FILE RESUME affects onlytheactive The FILE RESUME FILE RESUME Arguments Example Comments Note: See the until DCStransfersthespecifiednumberoflinesortransferiscompleted. If theactive dle The optional WINDOW WinHandle argument.The This commanddoesnotapplytoIBM TN3270emulations. FILE PAUSE WINDOW commandrestarts thetexttransfersuspendedby a LOGTOFILE WINDOW LOGTOFILE WinHandle command.
WinHandle clause iscomposedofboththe command is performed inlinecountmode,scriptexecutioncommand isperformed pauses command. argument is an integer identifying a particular childwindow. argumentisanintegeridentifyingaparticular WINDOW FILE PAUSE keyword andthe command.It WinHan - 3 Commands 363 - KER REMOTE command argument must FileName command to issue the command to issue the keyword specifies an EBCDIC specifies an EBCDIC keyword keyword directs DCS to replace DCS to replace directs keyword FILE SEND BINARY ASCII BINARY CRLF ASCII BINARY clause is an optional argument for
ASCII CRLF AS argument must specify a valid file name for the argument must specify a valid argument is a string specifying the name to give to give argument is a string specifying the name FILE SEND BINARY AS Hostname Hostname Hostname clause, the remote system will save the file under the same name system will save clause, the remote AS keyword causes the keyword keyword. For the Kermit file transfer protocol, you must use the file transfer protocol, the Kermit For keyword. command directs DCS to send the specified file using the binary to send the specified file using the DCS command directs transfer BINARY FileName BINARY clause with the Kermit protocol. The protocol. clause with the Kermit argument might be in one of the following formats: argument might be in one of the following argument is a string specifying the file to send. The argument is a string specifying the file to AS REMOTE command to a Kermit server on a remote host. The Kermit binary server host. The command to a Kermit a remote on protocol transfer REMOTE clause, DCS saves the file using its current file name. the file using its current clause, DCS saves REMOTE CMS: HostFileName HostFileType HostFileMode CMS: HostFileName HostFileType TSO: HostFileName HostMemberName Password Hostname FileName AS each end of line delimiter (a carriage return character followed by a line feed character) with an by character followed each end of line delimiter (a carriage return mark. end of record If you do not include the you If PC. it had on your ASCII The optional transfers only. This option is for IND$File it is not included, the file is not translated. to ASCII translation. If CRLF The optional transfers only. This option is for IND$File transfers involving non-3270 terminal emulations, but is required for transfers involving 3270 for transfers involving non-3270 terminal emulations, but is required transfers involving system under a name different remote the file on the you to save emulations. This clause allows file name. The the current from remote system. The the file on the system. remote this clause when the command only recognizes When DCS emulates a non-3270 terminal, protocol. file transfer Kermit as its to use session window the active also configured have you you do not include or when for a session window, is not configured protocol When the Kermit the The MIT PUT MIT the executing before must be specified for the session window with the system is in server if the remote mode. keyword FileName BINARY The your system. file name for specify a valid AS Hostname use the Only REMOTE The optional Arguments FILE SEND BINARY FILE SEND WINDOW WinHandle APPEND NOCRLF The settings. by the active specified protocol FILE SEND BINARY FILE SEND 364
DCS Script Language Reference FILE SENDBINARY, Example Comments system witha TSO or VM/CMS commandprocessor. of thefilebefore receiving thefile.Thisoptionisincludedwhentransferringfilesto aremote length andrecord formatspecifications. If itisnotincluded,DCSclearstheexistingcontents append theoutgoingfiletoexistingcontentsofspecifiedand overridethe record This optionisforIND$File transfersonly. Theoptional APPEND drive C:thathave a fileextensionwillbesent. TXT DCS sendsseveral filesvia YModem on inbatchmode.AllfilestheDCSERIESdirectory In thisexample: send thefile TEST.FIL tothehostandstore itinthefile TESTFILE A1. running aCMSenvironment. ThecommanddirectsDCS sendsafileto3270host DCSto In thisexample: session. If the the error intheResult systemvariable. due totoomanytransmissionerrors. When there isanerror, DCSwillplace textdescribing The equivalent toa For systemsusingtheKermit protocol, the thefiletransfer.display adialogbox indicating thatitaborted If theremote systemdoesnotrespond toyour transmissionwithin30seconds,DCSwill The The The optional WINDOW WinHandle ERROR WINDOW WinHandle WINDOW FILE SENDBINARY“C:\DCSERIES\*.TXT” SET BINARYTRANSFERSYMODEM FILE SENDBINARY“TEST.FIL”AS“TEST”“FILE”“A1” WINDOW function returns TRUE thetransfer, ifyou abort thetransfer orifDCSaborts clause directs DCStosendafileasconfigured inaspecificsession. KERMIT PUT clause isnotincludedinthecommand,filesentthrough thecurrent argument is an integer identifying a particular sessionwindow.argument isanintegeridentifyingaparticular continued clause includesthe command. FILE SENDREMOTEBINARY WINDOW keyword andthe APPEND keyword causesDCSto WinHandle commandis argument. 3 Commands 365 -
- string causes KERMIT FINISH KERMIT EXIT EXIT to the remote sys to the remote HostMember . The LOGIN.TXT LOGIN.GDT to the remote system, stores it in the file named system, stores to the remote “datafile.TXT” AS “datafile” “” “pass” “datafile.TXT” AS “datafile” continued DATAFILE.TXT , and uses the password pass. The null string (“”)is used for the pass. , and uses the password argument since the host file is not from a partitioned argument since the host file is not from data set (it has no member name). FILE SEND BINARY SET BINARYTRANSFERS KERMIT SEND “KERMIT” WAIT STRING “KERMIT-32>” SEND “SERVER” WAIT STRING “COMMAND” AS “LOGIN.GDT” FILE SEND REMOTE BINARY “LOGIN.COM” KERMIT FINISH SEND “EXIT” SET BINARYTRANSFERS XMODEM SET BINARYTRANSFERS 14400 SET BAUDRATE CONNECT PERFORM login “DCDATA.TXT” FILE SEND BINARY or transferring files, on the remote system. DCS sends the file or transferring files, on the system to name the file to tem, and instructs the remote server Kermit mode, and the system to leave command instructs the remote application. system to exit the Kermit the remote this example: In The command directs TSO environment. remote system running the DCS sends a file to a DCS to send the file DATAFILE Name In this example: In system is in When the remote server system to enter Kermit DCS instructs mode. the remote server to perform system can send commands Kermit mode, your operations, such as viewing In this example: In binary after the appropriate been transfer settings have DCDATA.TXT DCS sends the file selected. FILE SEND BINARY, BINARY, FILE SEND 366
DCS Script Language Reference FKEYS The FKEYS Display FKEYS Arguments Example Comments The Display during theonlinesessionthatfollows, andthenhiddenwhenthesessioniscompleted. DCS loadsthesessionfile In thisexample: quence. You maystillaccesshiddensessiontoolbarbuttonsby using the proper acceleratorkeyse remove thefunctionkeydisplay. SHOW Display command controls whetherthesessiontoolbarisdisplayed inasessionwindow. FKEYS HIDE PERFORM OnlineSession FKEYS SHOW LOAD “LOGON.SES” keyword directs DCStodisplaythesessiontoolbar. The argument isspecified by oneofthefollowing keywords: LOGON.SES . Thesessiontoolbarbuttonsare displayed foruse HIDE SHOW keyword directs DCSto or HIDE . The - 3 Commands 367 - - Session Proper Session keyword is invalid. keyword tab of the String
General General or WinHandle 1 (true), 0 (false) 1 (true), 0 (false) Valid Setting(s) Valid 1 (true), 0 (false) 1 (true), 0 (false) string of valid path of a compiled script file 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) function WINDOW WinHandle GETGENERALCONFIG command sets the value of a parameter used to configure general session op used to configure of a parameter command sets the value Because scripting tasks receive a lower processing priority than other application priority than other processing a lower scripting tasks receive Because to autoconnect may do so upon configured a session which is already activity, a script to disable the autoconnect from the command it receives opening before feature. function returns TRUE if the TRUE function returns argument represents a single “keyword” followed by the assignment operator (=) the assignment by followed a single “keyword” argument represents Note: Also see: DisplayErrorInformation Sound Keywords for General tab AutoConnect SaveWindowPosition StartupScript DisplayDisconnectConfirmation DisplaySaveConfirmation DisplayConnectInformation ERROR String dialog. This command, therefore, allows you to set these parameters through the DCS set these parameters through you to allows dialog. This command, therefore, The keywords correspond to parameters available on the to parameters available correspond The keywords ties box. script language rather than using the dialog The or specified session and Changes made via scripting to these options apply only to the active unless the session is saved. not saved are and a valid setting. Together, the keyword and the setting are used to configure the general used to configure are and the setting the keyword Together, setting. and a valid session. properties of the active String The Comments Arguments GENERALCONFIG GENERALCONFIG String GENERALCONFIG The tions. GENERALCONFIG 368
DCS Script Language Reference GENERALCONFIG, Example In thisexample: saved. once thesessionopens.Finally, thesave confirmation dialogisdisabledandthesession (which canbeusedtospecifythehostsystemandinitiateconnection)isspecifiedstart sessionisloadedandconfigureda new withtheautoconnectoptionturnedoff.Aloginscript SAVE “vax1.ses” GENERALCONFIG “DisplaySaveConfirmation=false” vaxlogin.dct” GENERALCONFIG “StartupScript=p:\public\scripts\ GENERALCONFIG “AutoConnect=false” LOAD continued 3 Commands 369 - command branches to an error handling rou command branches to an error GOTO GOTO argument can be specified by a near target (usually a routine in the local script) or a a near target (usually a by argument can be specified . . *error_display . . . SET %listbox LISTBOX () IF %listbox < 0 GOTO error_display ELSE BEGIN RECORD READ 0 AT %listbox DIAL @R0.2 RETRY 1 DELAY 45 END . Target Target command causes script execution to branch to the specified target. to branch execution command causes script if no item is selected in the list box, the if no item is selected in the list box, tine. In this example: In Target The in another script). or a routine far target (another script, Example Arguments GOTO GOTO GOTO Target GOTO The GOTO 370
DCS Script Language Reference HANGUP The HANGUP HANGUP Arguments Example Comments Note: tempting toconnectusinganotherphonenumber. if DCSiscurrently connected,thesecommandsdirect DCStodisconnectthelinebefore at In thisexample: of theactive sessionwindow. If the The The The optional WINDOW WinHandle WINDOW WinHandle WINDOW WinHandle WINDOW This commanddoesnotapplytoIBM TN3270emulations. DIAL ‘5551234’ HANGUP IF CONNECT() command directs themodemtodisconnecttelephoneline. WINDOW clause directs DCStodisconnectthephonelineforaspecificsession. clause isnotincludedinthecommand,DCSwilldisconnectphoneline argument is an integer identifying a particular sessionwindow.argument isanintegeridentifyingaparticular clause includesthe WINDOW keyword andthe WinHandle argument. - 3 Commands 371 - Boolean . If neither . If command, it must IF command list if the no_response . ELSE launch_app argument specifies a logical command (either a argument specifies a logical command (either clause appears on the same line as the Command ELSE clause executes the commands in the clause executes ELSE Command argument specifies a logical command (either a single command or a com argument specifies a logical command (either argument specifies the Boolean to be evaluated. argument specifies the ELSE IF EDITTEXT (1) = “” OR EDITTEXT (2) = “” PERFORM no_response ELSE PERFORM launch_app RECORD READ 0 at 0 WHILE (TRUE) BEGIN IF EOF () BEGIN LEAVE END RECORD READ 0 END DISPLAY “PROCESS COMPLETE^M” CANCEL Command Boolean if the end of the file is reached, DCS displays the specified string in the window and the script reached, DCS displays the specified string in the window if the end of the file is terminates. this example: In DCS performs the subroutine if either edit text field is empty, DCS performs the subroutine field is empty, In this example: In The mand block). ELSE Command The optional the If argument is FALSE. a comma. The by be preceded single command or a command block). Boolean The Command command evaluates the specified Boolean argument, executing the command list if the Boolean the command list if the Boolean Boolean argument, executing the specified command evaluates Example Arguments IF IF Boolean Command IF Boolean The argument is TRUE. IF 372
DCS Script Language Reference INCREMENT The INCREMENT IntVar INCREMENT Arguments Example IntVar tents oftherecord inthesessionwindow. the In thisexample: be specified,nota real variable. Specifying a real variable causesasyntaxerror. The INCREMENT IntVar END RECORD READ0 INCREMENT %index DISPLAY (%index,0)“Record“|STR(%index)@R0 BEGIN WHILE NOTEOF() RECORD READ0at %index =0 argumentspecifiestheinteger variable tobeincremented. Aninteger variable must command increases thevalue ofthespecifiednumeric variable by one. command isusedasacountertodisplaytherecord numberandthecon - 3 Commands 373 - argument. . argument is a string WinHandle NEWFILE.C . The clause is composed DestinationFile SourceFile keyword and the keyword command is performed the active upon WINDOW WinHandle WINDOW WINDOW argument. The KERMIT COPY KERMIT DestinationFile is created on the remote system and named on the remote is created clause includes the argument is an integer identifying a particular session window. argument is a string specifying the file to copy on the remote system and must remote system and specifying the file to copy on the argument is a string WINDOW keyword and the keyword OLDFILE.C clause specifies the file name for the copy of the clause specifies the file name for the copy TO KERMIT COPY “OLDFILE.C” TO “NEWFILE.C” This command does not apply to IBM TN3270 emulations. not apply to IBM This command does TO WinHandle SourceFile a copy of You must specify the Kermit binary performing must specify the Kermit for the session before protocol file transfer You The system in the session window. the remote from this operation. DCS displays all responses server system must be in Kermit mode. remote is specified, the handle no window If session. this example: In be a valid file name on that system. be a valid DestinationFile TO The of the valid file remote system and must be a file on the specifying the file name of the copy of the name on that system. WINDOW WinHandle The optional The SourceFile The Note: Comments Example Arguments KERMIT COPY SourceFile TO DestinationFile TO SourceFile COPY KERMIT (server)remote system must sup packet to the remote copy command system. The the Kermit Sends portserver Kermit mode. KERMIT COPY KERMIT 374
DCS Script Language Reference KERMIT DIRECTORY Kermit server mode. Kermit server Sends system.The commandtotheremote theKermit directory remote systemmustsupport (server) KERMIT DIRECTORY DirectoryName Arguments Example Comments Note: tory ontheremote system. tory the In thisexample: active session. If nowindow handleisspecified,the remote mode. systemmustbeinKermit server this operation.DCSdisplaysallresponses from theremote systeminthesessionwindow. The You filetransferprotocol forthesessionbefore mustspecifytheKermit performing binary The The optional WINDOW WinHandle will belisted. The DirectoryName KERMIT DIRECTORY WinHandle DirectoryName This commanddoesnotapplytoIBM TN3270emulations. KERMIT DIRECTORY“Documnts” WINDOW argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular argument is a string specifying the directory nameforwhichthecontents argument isastringspecifyingthedirectory clauseincludesthe commandlistsallofthefilescontainedin WINDOWWinHandle KERMIT DIRECTORY WINDOW keyword andthe command is performed uponthe commandisperformed WinHandle DOCUMNTS argument. direc - 3 Commands 375 argument. WinHandle from the remote system. the remote from command is performed the active upon keyword and the keyword FAX.DAT WINDOW KERMIT ERASE KERMIT WINDOW WinHandle WINDOW clause includes the command deletes the file argument is an integer identifying a particular session window. argument is a string specifying the name of the file to be deleted from the from specifying the name of the file to be deleted argument is a string WINDOW KERMIT ERASE “FAX.DAT” This command does not apply to IBM TN3270 emulations. not apply to IBM This command does WinHandle FileName KERMIT ERASE KERMIT session. this example, In the remote system. remote WINDOW WinHandle The optional The binary performing must specify the Kermit for the session before protocol file transfer You The system in the session window. the remote from this operation. DCS displays all responses server system must be in Kermit mode. remote is specified, the handle no window If FileName The Note: Example Comments Arguments KERMIT ERASE FileName KERMIT from a a file Kermit erase command deletes system. The to a remote erase command the Kermit Sends system must supportremote Kermit server system. The directory mode. on the remote KERMIT ERASE KERMIT 376
DCS Script Language Reference KERMIT FINISH system must support Kermit server mode. Kermit server system mustsupport The KERMIT FINISH KERMIT FINISH Arguments Example Comments Note: DCS sendsaKermit finishpacket tothe afterdisplayingadirectory.remote Kermit server In thisexample: session. If nowindow handleisspecified,the mode. system mustbeinKermit server mand. DCSdisplaysallresponses from theremote systeminthesessionwindow. The remote You filetransferprotocol forthesessionbefore mustselecttheKermit usingthiscom binary The The optional WINDOW WinHandle WinHandle This commanddoesnotapplytoIBM TN3270emulations. KERMIT FINISH KERMIT DIRECTORY SEND “KERMIT” WINDOWWinHandle WINDOW commandsendsaKermit finishpackettothe remote Kermit server. The remote argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular clauseincludesthe KERMIT FINISH WINDOW keyword andthe command is performed upontheactive commandisperformed WinHandle argument. - 3 Commands 377 argument. WinHandle command is performed the upon keyword and the keyword WINDOW KERMIT FREESPACE KERMIT clause includes the command displays the number of free bytes on the remote system. The system. The on the remote bytes number of free command displays the WINDOW WinHandle WINDOW argument is an integer identifying a particular session window. WINDOW KERMIT FREESPACE This command does not apply to IBM TN3270 emulations. not apply to IBM This command does WinHandle In this example: In system in a session window. on the remote bytes DCS displays the number of free The binary performing must specify the Kermit for the session before protocol file transfer You The system in the session window. the remote from this operation. DCS displays all responses server system must be in Kermit mode. remote is specified, the handle no window If session. active WINDOW WinHandle The optional Note: Comments Example Arguments KERMIT FREESPACE KERMIT KERMIT FREESPACE KERMIT The must support system server Kermit remote mode. KERMIT FREESPACE KERMIT 378
DCS Script Language Reference KERMIT HELP tem’s mode. operation.The Kermit server remote systemmustsupport The KERMIT HELP HelpTopic KERMIT HELP Arguments Example Comments Note: DCS displaysthehelptextconcerningfiledeletionon remote systeminasessionwindow. In thisexample: session. If nowindow handleisspecified,the remote mode. systemmustbeinKermit server this operation.DCSdisplaysallresponses from theremote systeminthesessionwindow. The You filetransferprotocol forthesessionbefore mustspecifytheKermit performing binary The The optional WINDOW WinHandle remote system. The HelpTopic WinHandle HelpTopic This commanddoesnotapplytoIBM TN3270emulations. KERMIT HELP“DELETE” command displays a brief summary of instructions onatopicoftheremote ofinstructions sys commanddisplaysabriefsummary WINDOW isastringspecifyingthenameoftopicincludedinonlinehelp argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular WINDOWWinHandle clauseincludesthe KERMIT HELP WINDOW command is performed upontheactive commandisperformed keyword andthe WinHandle argument. - 3 Commands 379 argument. WinHandle command is performed the upon keyword and the keyword WINDOW KERMIT LOGOUT KERMIT clause includes the argument is an integer identifying a particular session window. command sends a Kermit logout packet to the remote Kermit server. The The server. Kermit packet to the remote logout command sends a Kermit WINDOW WinHandle WINDOW WINDOW SET BINARYTRANSFERS KERMIT FILE SEND BINARY REMOTE “MEMO.TXT” KERMIT LOGOUT This command does not apply to IBM TN3270 emulations. not apply to IBM This command does WinHandle DCS sends a Kermit logout packet to the remote system after completing the file transfer. logout packet to the remote DCS sends a Kermit The binary performing must select the Kermit this for the session before protocol file transfer You Kermit server in remote system must be mode. operation. The is specified, the handle no window If session. active this example: In WINDOW WinHandle The optional Note: Comments Example Arguments KERMIT LOGOUT KERMIT KERMIT LOGOUT KERMIT The must support system server Kermit remote mode. KERMIT LOGOUT KERMIT 380
DCS Script Language Reference KERMIT MESSAGE remote system must support Kermit server mode. remote Kermit server systemmustsupport The KERMIT MESSAGEReceiverNameMessageText KERMIT MESSAGE Arguments Example Comments Note: DCS sendsthemessage“ In thisexample: active session. If nowindow handleisspecified,the remote mode. systemmustbeinKermit server this operation.DCSdisplaysallresponses from theremote systeminthesessionwindow. The You filetransferprotocol forthesessionbefore mustspecifytheKermit performing binary The The optional WINDOW WinHandle The MessageText The ReceiverName WinHandle MessageText ReceiverName This commanddoesnotapplytoIBM TN3270emulations. KERMIT MESSAGE“ WINDOW argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular command sends a short messagetoanaccountontheremote commandsendsashort system.The is thestringsenttousernameonremote system. is astringspecifyingvalid usernameontheremote system. clauseincludesthe Hello FARRELLT ” totheuser KERMIT MESSAGE WINDOW ” “ FARRELLT HELLO WINDOWWinHandle keyword andthe ” command is performed uponthe commandisperformed on theremote system. WinHandle argument. 3 Commands 381 argument. . WinHandle LETTERS command is performed keyword and the keyword ” WINDOW WINDOW WinHandle WINDOW LETTERS KERMIT NEWDIRECTORY KERMIT command changes the current working directory on the remote directory working on the remote current command changes the clause includes the argument is a string specifying the new working directory on the remote directoryspecifying the newargument is a string working on the remote argument is an integer identifying a particular session window. WINDOW KERMIT NEWDIRECTORY “ This command does not apply to IBM TN3270 emulations. not apply to IBM This command does WinHandle DirectoryName If no window handle is specified, the handle no window If session. upon the active this example: In directory working to the directory the command changes the current system. WINDOW WinHandle The optional The binary performing must specify the Kermit for the session before protocol file transfer You The system in the session window. the remote from this operation. DCS displays all responses server system must be in Kermit mode. remote DirectoryName The Note: Example Comments Arguments KERMIT NEWDIRECTORY NEWDIRECTORY KERMIT KERMIT NEWDIRECTORY DirectoryName NEWDIRECTORY KERMIT The system must supportremote Kermit server The mode. system to a new directory. KERMIT NEWDIRECTORY KERMIT 382
DCS Script Language Reference KERMIT RENAME The remote system must support Kermit server mode. The Kermit server remote systemmustsupport The KERMIT RENAMEOldFileNameTO NewFileName KERMIT RENAME Arguments Example Comments Note: the file In thisexample: active session. If nowindow handleisspecified,the mode. system mustbeinKermit server operation. DCSdisplaysallresponses from theremote systeminasessionwindow. The remote You filetransferprotocol forthesessionbefore this mustspecifytheKermit performing binary The The optional WINDOW WinHandle nameforthefileon specifying thenew remote system. of the The TO NewFileName system. The OldFileName WinHandle TO OldFileName This commanddoesnotapplytoIBM TN3270emulations. KERMIT RENAME“DATA2A”TO“STCKQUOT” TO TO DATA2A clause specifiesthenametowhichfilewillbe renamed.The keyword andtheargument, WINDOW commandchangesthenameofafileon name. remote systemtoanew argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular isrenamed argument isastring,specifyingthenameoffiletochangeon remote clauseincludesthe STCKQUOT KERMIT RENAME NewFileName on theremote system. WINDOW WINDOWWinHandle . The keyword andthe command is performed uponthe commandisperformed NewFileName WinHandle TO TO is astringargument, clause iscomposed argument. 3 Commands 383 argument. WinHandle keyword and the keyword command is performed the active upon in the session window. TEXT1 WINDOW KERMIT TYPE KERMIT clause includes the WINDOW WinHandle WINDOW argument is an integer identifying a particular session window. argument is a string specifying a file on the remote system. specifying a file on the argument is a string WINDOW command displays the contents of a file located on the remote system. The remote The remote system. contents of a file located on the command displays the KERMIT TYPE “TEXT1” This command does not apply to IBM TN3270 emulations. not apply to IBM This command does WinHandle FileName session. this example: In DCS displays the contents of the file named WINDOW WinHandle The optional The binary performing must specify the Kermit this for the session before protocol file transfer You remote The system in a session window. the remote from operation. DCS displays all responses serversystem must be in Kermit mode. is specified, the handle no window If FileName The Note: Example Comments Arguments KERMIT TYPE KERMIT KERMIT TYPE FileName KERMIT The system must support server Kermit mode. KERMIT TYPE KERMIT 384
DCS Script Language Reference KERMIT WHO system must support Kermit server mode. Kermit server system mustsupport The KERMIT WHO KERMIT WHO Arguments Example Comments Note: DCS displaysalistofallthepersonsloggedintoremote systeminthesessionwindow. In thisexample: session. If nowindow handleisspecified,the mode. Kermit server who commandmaybedifferent from onesystemtothenext.The remotesystemmustbein fromThe systemtosystem.Theimplementationoftheresults ofthiscommand Kermit vary operation. DCSdisplaysallresponses from theremote systeminasessionwindow. You filetransferprotocol forthesessionbefore this mustspecifytheKermit performing binary The The optional WINDOW WinHandle person ontheremote system. argument isincluded,thecommanddisplaysamessageindicatingstatusofparticular mand, thecommanddisplaysnamesofallpeopleloggedintoremote system.If the The UserName WinHandle UserName This commanddoesnotapplytoIBM TN3270emulations. KERMIT WHO UserName WINDOWWinHandle commandissuestheKermit whocommandtotheremote system.The remote WINDOW argument isanoptionalstringargument.If itisnotincludedinthecom argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular clauseincludesthe KERMIT WHO WINDOW command is performed upontheactive commandisperformed keyword andthe WinHandle argument. - 3 Commands 385 argument consists of any valid string (literal, variable, string (literal, variable, argument consists of any valid WINDOW WinHandle WINDOW Definition argument is specified by one or more of the following keywords: ALT, ALT, keywords: of the following or more by one argument is specified SET RESULT SET WAIT DELAY WAIT argument can be specified as a string. Embedded control characters must begin the string or be the only characters in characters must begin the string or control Embedded the string. Modifier1 Key1 Definition Key1 Definition argument specifies a valid key name. Valid keys are letters (A through Z), digits (0 letters (A through Valid keys are valid key name. argument specifies a ^$P PERFORM ^$P ^$R Note: String Command String ^$B BREAK ^$C DIAL ^$D ^$E EXECUTE ^$H HANGUP LEVEL ^$L Key1 Definition command remaps a key (or key combination) to a new a The definition can be a definition. command remaps When a remapped key is pressed in an active script or memo window, the string is inserted in script or memo window, active in an key is pressed When a remapped cursor location. the script or memo at the current Key1 The the table below. 9), or one of the key names listed in through Definition The String a string is specified, the If When a remap a key to send a string rather than a character. you may function, etc). Thus, system. the string is sent to the remote window, session in an active key is pressed remapped Modifier1 The optional or SHIFT. RIGHTSIDE, CTRL, LEFTSIDE, Modifier1 Modifier1 Arguments KEY KEY KEY KEY The meta key or a string. KEY 386
DCS Script Language Reference KEY, continued 189 188 187 186 Up Tab Subtract Space ShiftKey Separator Select ScrLock Right Return Reset Prior Print Pause NumPad9 through NumPad0 NumLock Next Multiply Left Insert Home F16 through F1 Escape End Down Divide Delete Decimal CtrlKey Clear Capital Cancel Back Alt Add Key Name
Hyphen andUnderlineKey Comma andLess Than Key Equals andPlusKey Semicolon andColonKey Key Up Arrow Tab Key Minus Key(NumPad) Space Bar Shift Key Comma Key(NumPad) Select Key Scroll LockKey Key Arrow Right Return (orEnter)Key Reset Key Prior Key Print Key Pause Key Nine Key(NumPad) Zero Key(NumPad) Num LockKey Next Key Asterisk Key(NumPad) Key Left Arrow Insert Key Home Key Function KeySixteen Function KeyOne Escape (Esc)Key End Key Key Arrow Down Slash Key/(NumPad) Delete Key Period Key(NumPad) Control Key Clear Key Cap LockKey Cancel Key Backspace Key Alternate Key Plus Key(NumPad) Indicated Key 3 Commands 387 - argument. WinHandle is inserted at the current is inserted at the current GOTO keyword and the keyword WINDOW Period and Greater Than Key Period and Greater Key Slash and Question Mark Key Tilde Grave and Key Left Bracket and Left Brace Backslash and Bar Key Brace Key Right Bracket and Right Key Quote and Double Quote Indicated Key clause includes the argument is an integer identifying a particular session window. clause is not included in the command, the remapping is applied to the cur the remapping clause is not included in the command, clause directs DCS to apply the keyboard remapping to a key map attached to a remapping DCS to apply the keyboard clause directs command changes the character that the [BACKSPACE] key sends to the delete command changes the character that the [BACKSPACE] WINDOW function returns the delete character (the character that the [DELETE] key sends), the delete character (the character that the [DELETE] key sends), function returns KEY KEY KEY Back CHR (127) KEY SHIFT G “GOTO” KEY SHIFT SPACE “^$B” Key Name 190 191 192 219 220 221 222 WINDOW WinHandle WINDOW CHR In this example: In the and the character. In this example: In when the [SHIFT]+[G] the string key combination is pressed, insertion point. this example: In system. is sent to the remote a break key combination is pressed, when the [SHIFT]+[SPACE] and behavior. length The host system determines the break The optional The The particular session window. the If session. rent WINDOW WinHandle Comments Example continued KEY, KEY, 388
DCS Script Language Reference KEY, continued screen. When VT-100 isthesession’s current emulation,thischaractersequenceerasestheterminal this commandassignstheescapesequence^[[2Jtomiddlecursorcluster[INSERT] key. In thisexample: label, after thisscriptisexecuted, whenthe[G] keyispressed, executing thescriptwillstart atthefar In thisexample: assigns a^G(bell)charactertothekeypad[5]key. In thisexample: [PF1]. 220 emulationisactive forasession, thischaractersequencemakesthe[HOME]keyactlikea this commandassignstheescapesequence^[[OPtokeypad[HOME]key. When a VT- In thisexample: *ring RETURN DISPLAY “^G” *ring WAIT RESUME KEY G“^$P‘ringtest*ring’” KEY NUMPAD5“^G” KEY RIGHTSIDEHOME“^[OP” Also see: KEY LEFTSIDEINSERT“^[[2J” , inthe specific Client Option Help. Escape sequencesforyour emulationintheDCS9Online Reference or RINGTEST script. 3 Commands 389 - argument. WinHandle keyword and the keyword WINDOW tem. is executed. command UNLOCK, KEYBOARD ECHO, or WAIT Description until a KEYBOARD LOCK, KEYBOARD keystrokes Directs DCS to buffer is executed. UNLOCK, or KEYBOARD ECHO command system only. Directs DCS to transmit keystrokes to the local the local nor the remote sys Directs DCS to transmit keystrokes to neither local and remote systems. Directs DCS to transmit keystrokes to both the until a KEYBOARD LOCK, KEYBOARD keystrokes Directs DCS to buffer clause includes the argument is an integer identifying a particular session window. clause is not included in the command, the keyboard state is changed for the clause is not included in the command, the keyboard
WINDOW WinHandle WINDOW clause directs DCS to change the keyboard state for a particular session. DCS to change the keyboard clause directs WINDOW
argument is specified by one of the following keywords: keywords: of the following by one argument is specified command determines whether keystrokes are transmitted to the local or remote transmitted to the local or remote are whether keystrokes command determines LOAD “TRANSET” KEYBOARD LOCK FILE SEND BINARY “SCRIPT1.DCP” KEYBOARD UNLOCK BUFFER ECHO LOCK UNLOCK WAIT Keyword WINDOW WinHandle WINDOW State In this example: In the file transfer is performed. is locked while the keyboard WINDOW WinHandle The optional The The the If session. active State The Example Comments Arguments KEYBOARD KEYBOARD State KEYBOARD The system. KEYBOARD 390
DCS Script Language Reference KEYMAP LOAD The KEYMAP LOADFileName KEYMAP LOAD Arguments Comments FileName To loadthedefaultkeymapforemulation,use The argument mustspecifyavalid filenamefor your system. The ERROR FileName commandloadsthekeymapfilespecified bythefilename. function returns TRUE ifthespecifiedfiledoesnotexist. argument isastringspecifyingthekeymapfiletobeloaded.The KEYMAP RESET command. FileName 3 Commands 391 command takes no arguments. command takes no command returns the keyboard and keymapping to the default settings for the and keymapping the keyboard command returns KEY SHIFT SPACE “^$B20” KEY SHIFT SPACE KEY ALT L “Login” PERFORM “login.dcp *label” KEYMAP RESET KEYMAP RESET KEYMAP In this example, the [SHIFT]+[SPACE] and [ALT]+[L] key combinations are modified. After key combinations are and [ALT]+[L] this example, the [SHIFT]+[SPACE] In to and both key combinations return is reset performing the target script branch, the keyboard their default settings. The Arguments Example KEYMAP RESET KEYMAP KEYMAP RESET KEYMAP The emulation. KEYMAP RESET KEYMAP 392
DCS Script Language Reference KEYMAP SAVE The KEYMAP SAVE FileName KEYMAP SAVE Arguments Comments FileName file name. The filecannotbesaved tothedefaultkeymap;asaved keymapmustalwaysbegiven aspecific ment mustspecifyavalid filenamefor your system. The FileName commandsaves thecurrent keymapfilewithaspecifiedname. argument isastringspecifyingthekeymapfiletobesaved. The FileName argu - 3 Commands 393 - - - argument indicates whether DCS should launch the application argument indicates whether DCS should If you include the SYNCHRONOUS keyword in the command, DCS If you include the SYNCHRONOUS keyword pauses the script while the application is running. ASYNCHRONOUS keyword in the command, DCS If you include the continues the script after starting the application. argument is a string specifying a list of command line instructionsargument is a string specifying a list of command argument is not included, the script continues after startingargument is not included, the script continues the ap Command, ... ContinueScript argument is a string specifying the file to launch. The file must have a com must specifying the file to launch. The file argument is a string Command ContinueScript command starts the specified program as a separate application running under Win command starts as a separate application the specified program running under Keyword Description SYNCHRONOUS ASYNCHRONOUS ContinueScript Application path in AUTOEXEC.BAT. If the If plication. must specify the complete path to the application or list the launch the application, you To Command, ... The optional terms must be in the launched application’s sent to the specified application. The commands commas. and separated by ContinueScript The optional the script, or launch the application and halt the script until the target and continue executing keywords: one of the following requires application closes. It Application The or BAT). the operating system (such as EXE , COM, to mand extension appropriate Comments Arguments LAUNCH LAUNCH Application The dows. LAUNCH 394
DCS Script Language Reference LAUNCH, Example This scriptsegment: LAUNCH thetargetapplicationandcontinueswithscriptcommandfollowingDCS starts the script withthecommandfollowing the to pausethescript. DCScontinuesthe When thetargetapplicationisnolongerrunning, theequivalent ofa theapplicationandthenperforms DCS starts a messageintheactive sessionwindow, beepsthesystembellonce,andstopsscript. Excelstarts it.If Excel andthentestswhetherDCSwasabletostart DCSplaces didnotstart, continued LAUNCH $appnameASYNCHRONOUS LAUNCH $appnameSYNCHRONOUS End IF ERROR() LAUNCH “EXCEL.EXE” command. CANCEL BEEP 1 DISPLAY “Can’tlaunchExcel”, BEGIN LAUNCH command. WAIT RESUME command 3 Commands 395 or WHILE command branches execution to the line following the to the line following command branches execution LEAVE LEAVE command takes no arguments. command block of a within the from command may be executed loop. INCREMENT %counter END DISPLAY “No More Records” SET %counter 0 WHILE %counter < 10 BEGIN RECORD READ 0 IF EOF () LEAVE DISPLAY (%counter, 0) @R0 command. command branches execution past the last command in the currently executing command executing the last command in the currently past execution command branches LEAVE LEAVE LEAVE DCS is directed to read and display ten records from table zero. If the end of the file is reached the end of the file is If table zero. from and display ten records to read DCS is directed the read, are ten records before END SWITCH this example: In The The Example Arguments Comments LEAVE LEAVE LEAVE The block. LEAVE 396
DCS Script Language Reference LEVEL The LEVEL KeyLevel LEVEL Arguments Example Comments KeyLevel ured, thescriptdisplaystoolbar. configures three buttons:twoonlevel oneandonlevel two. Afterthebuttonsare config In thisexample,DCShidesthesessiontoolbarbuttonsforactive sessionwindow andthen In thisexample: and action. DCS maintainsfourlevels onatoolbar. Eachlevel contains eight buttonsconsistingofthetitle The KeyLevel command selectsalevel onasessiontoolbar. FKEYS SHOW @T1 =“MyFavorite” @F1 =“GoFavorite^M” LEVEL 2 @T2 =“UserID” @F2 =“MyName^M” @T1 =“password” @F1 =“Today’sPass^M” LEVEL 1 FKEYS HIDE Note:
This commanddoesnotapplytothe AT&T 605emulation. argumentisanumeric(from 1to4)specifyingthetoolbarlevel. - 3 Commands 397 - - - - (C) command. If the DLL refer command. If LPINT LPINT LPLONG see below (int far *) (long far *) LPSTR (double far *) (char far *) (Parameter, …) (Parameter, LIBRARY LOAD LIBRARY Chapter 1 Introduction command loads, uses, and then unloads the specified command loads, uses, and then unloads argument specifies one or more strings, numerics, or Booleans, argument specifies one or more # % ! $ LIBRARY CALL LIBRARY argument specifies the library The argument procedure. containing the argument is a string specifying the name of the procedure to perform, as it of the procedure argument is a string specifying the name Parameter Passing section in Passing Parameter (Parameter, …) (Parameter, command branches execution to the specified Dynamic Link Library to execution command branches (DLL) All variables are passed by reference. passed by are All variables Also see: syntax: the following variable types follow The Type Boolean Prefix in Script Variable Integer Real SDK String i.e. the application will crash. i.e. the application will The calling convention of the library of the routine The calling convention by the function being used is determined the ‘C’ program as the first character (“_”) then underscore the name has an name. If Otherwise, is used. ming language convention using the stan the function will be called VERY is It convention). to as the Pascal (sometimes referred convention WINAPI dard will occur, results or unpredictable be correct that the calling convention IMPORTANT Procedure LibraryReference 1. 2. The appears in the DLL. …) (Parameter, The optional The passed commas, to be passed to the procedure. and separated by enclosed in parentheses Param the DLL procedure. to the parameter types expected by parameters should correspond only. reference passed by eters are rules: to the following passed according script, the parameters are When calling DLLs from LibraryReference The variable or a numeric file containing the procedure, is either a string specifying the name of the the by returned value containing the reference enced is not loaded, the library. Procedure Note: Comments Arguments LIBRARY CALL LIBRARY LIBRARY CALL LibraryReference Procedure LibraryReference CALL LIBRARY The procedure. LIBRARY CALL LIBRARY 398
DCS Script Language Reference LIBRARY CALL, Example Also see: close thelibrary. thanthefirstmethod. Thismethod useslessmemory command oncetoopen(referring totheDLLby theDLL’s filename),toaccess,and thento script accessesonlyoneprocedure in When thescriptuses DLL outofmemory. edly withthe many times,thismethoduseslesstimesincethescriptdoesnothave toopentheDLLrepeat CALL LOAD accesses three procedures in the scriptaccessesfourprocedures intwoDLLswithdifferent methods. Since thescript In thisexample: 4. 3. commandrefers totheDLLby thevariable %lib1. When ascriptneedstoaccessDLL LIBRARY UNLOAD%lib1 ;above commandsperformfunctionsofthelibrary LIBRARY CALL%lib1“saveProc”($file) LIBRARY CALL“lib2.DLL”“printProc”($file) LIBRARY CALL%lib1“deleteProc”($file,%size) LIBRARY CALL%lib1“addProc”($file,%size) ;loads DynamicLinkLibrary LIBRARY LOAD“lib1.DLL”%lib1 tion andcopiesthebytes intotheResult systemvariable. The return value expectsa LONG value. DCStakesthefour bytes returned by afunc tion istheusualmethodforcalling Windows functions. it willbecalledwiththePascal convention. Please notethatthePascal callingconven score asthefirstcharacter(“_”)thenitwillbecalledusingCconvention. Otherwise, Pascal orCcallingconvention isdeterminedby theroutine name.If ithasanunder Windows SDK.TheSDKdoesnothave adefinitionfordoublefar*. LPINT, LPLONG, andLPSTRare definedasshown by the WINDOWS.H fileinthe commandandthenusestheDLLwith TYPEDLIBRARYCALL function development ofDynamicLinkLibraries(DLLs). Windows Software Development Kit(SDK)formore informationontheuseand LIBRARY CALL continued LIB2.DLL LIB1.DLL command.Finally, the , itisusinganothermethodofaccessingaDLL.Since the LIB2.DLL , thescriptopensDLLoncewith , thescriptusesonly LIBRARY CALL LIBRARY UNLOAD command.The commandtakesthe LIBRARY CALL LIBRARY LIBRARY -
- - - 3 Commands 399 RESULT RESULT function function then ORD SUBSTR “C:\WINDOWS\MyDLL.DLL” “MyFunction” \ “C:\WINDOWS\MyDLL.DLL” “MyFunction” continued LIBRARY CALL $String) (#Boolean, %Integer, !Real, 1,1) + \ %r = Ord (Substr (Result (), * 0x100 + \ Ord (Substr (Result (), 2,1) * 0x10000+ \ Ord (Substr (Result (), 3,1) * 0x1000000 Ord (Substr (Result (), 4,1) typedef double far *LPDOUBLE typedef double MyFunction (LPINT lpiBoolean, long FAR PASCAL LPLONG lpiInteger, LPDOUBLE lpdReal, LPSTR lpszString) { *lpiInteger); return ((long) } converts the substring to an integer. The integer is then placed in the integer variable %r. The integer is then placed in the integer converts the substring to an integer. To call the DLL function, you might employ the following script command which: the following might employ the DLL function, you call To The $String). !Real, parameters (#Boolean, %Integer, calls the DLL function and passes it four The variable. system result which is placed in DCS’s value, a LONG DLL returns to the script. The of the DLL available value function makes the return The of the number. representation extracts the first four digits of the string The following is a C language function extracted from a DLL: extracted from a C language function is The following LIBRARY CALL, CALL, LIBRARY 400
DCS Script Language Reference LIBRARY LOAD reference theDLL. also return anumericvalue whichthe The LIBRARY LOADLibraryName LIBRARY LOAD Arguments Example Comments See the no longerneeded. You mayloaduptothree DLLsconcurrently. the routines itcontains.Normally, the This commandallows acommonlyused DLLtobeloadedbefore multiplecallsare madeto able toloadthelibrary. If thenumberstored inthevariable islessthanzero orasmall(2digit)number, DCSwasnot specifying thefilenameoflibrary. library. If itisnotincluded,allreferences mustbemadewithastring totheloadedlibrary LIBRARY UNLOAD numeric reference value returned by the The optional LibraryReference specify avalid filenamefor your system. The LibraryName LibraryName LIBRARY CALL LibraryReference command loads the specified Dynamic Link Library (DLL)intomemory. commandloadsthespecifiedDynamicLinkLibrary It may argument specifiesthenameoffilecontainingdesired DLL. Itmust commandsmaythenusethisreference variable torefer totheloaded command. LibraryReference LIBRARY CALL argumentisanumericvariable intowhichDCSstores a LIBRARY UNLOAD LIBRARY LOAD and LIBRARY UNLOAD command.All commandisusedwhentheDLL commandscanuseto LIBRARY CALL and
3 Commands 401 - command. command. argument specifies the library to be unloaded. It is either a string speci libraryargument specifies the to be unloaded. command removes the specified Dynamic Link Library memory. (DLL) from command removes LIBRARY CALL LIBRARY LIBRARY LOAD LIBRARY LibraryReference See the See LibraryReference The returned value libraryfying the name of the reference variable containing the file, or a numeric the by Example Arguments LIBRARY UNLOAD LIBRARY LIBRARY UNLOAD LibraryReference LIBRARY The LIBRARY UNLOAD LIBRARY 402
DCS Script Language Reference LINENUMBERS compiled script.Thenumbersindicatethelinewhere acommandinscripttextfileislocated. The LINENUMBERS LINENUMBERS Arguments Example Comments the DCS includeslinenumberinformation. Thisscriptsegmentissimilartochecking(enabling) This scriptsegmentcausesDCS tocompile script precedes eachcommanditplacesinthefilewith command’s linenumber. ates thefile the Include LineNumbers check box intheCompiledialog box). itcreWhen thescriptruns, DCS willautomaticallyplacelinenumbersinthecompiledscript(you donotneedtocheck When you compileascriptcontainingthesecommands: See alsothe tion inthe The command ratherthantheindex. debugging file,andanyscripterror dialogswilldisplaythelinenumberofoffendingscript commands inthescript, script withthe number informationinacompiledscriptmayhelpyou debugascript. When you compilea The The Include LineNumbers LINENUMBERS LINENUMBERS LINENUMBERS . . . Compile “MYSCRIPT.DCP” LineNumbers . . . Show Debug “DBG0131.TXT” LineNumbers Compile DBG0131.TXT COMPILE command isacompilerdirective whichdirects DCStoincludenumbersina LINENUMBERS dialog. command doesnotaffectthestatusof command takeseffectonlywhenDCScompilesascript.Theline command takesnoarguments. command andthe optionbefore thecompilationof a script. you start DEBUG andwriteseachexecuting commandandfunctiontothefile.The command, andifyou have includedthe command willwritethelinenumberinformationtoa DEBUG MYSCRIPT.DCP command. . AsDCScompilesthescript, Include LineNumbers DEBUG and SHOW op - - 3 Commands 403 - -
File Open Open SET TERMCLOSE SET . command has a false argument, command, you do not need to include command, you before performing the login sequence. If the before LOAD argument, DCS loads a new session file contain SET TERMCLOSE SET argument. SESSNAME FileName argument as a question mark (?), DCS will display the (?), DCS mark argument as a question FileName argument is a string specifying the session file to be loaded. The specifying the session file to be loaded. argument is a string FileName function returns TRUE if the specified file does not exist. TRUE function returns FileName command does not execute if the Boolean argument of the command does not execute argument must specify a valid file name for your system. your for file name a valid argument must specify END PERFORM login_sequence LOAD “SESSNAME” IF ERROR () BEGIN DISPLAY “Could not load session file” CANCEL ERROR LOAD command loads the session file specified by the optional file namey session file specified command loads the FileName DCS attempts to load the session file and cancels the session window message in session file cannot be loaded, DCS displays an error execution. command evaluates to FALSE. When the to FALSE. command evaluates you file implies that or loading a session Opening may not close an open session window. you want to close an open session file or window. this example: In dialog, allowing you to select a session file during script execution. you dialog, allowing do not include the optional you If ing the default settings. The only session files can be loaded using the Since the SES file extension in the The FileName The optional Name specify the you If Example Comments Arguments LOAD LOAD The LOAD 404
DCS Script Language Reference LOGTOFILE the commanddirects DCStostoploggingdataandclosethefile. The LOGTOFILE FileName LOGTOFILE Arguments Comments FileName Use the Use thecommandasecondtimetostoploggingincomingdataandclosefile. This commandhasthesameeffectasselecting If nowindow handleisspecified,thiscommand applies totheactive sessionwindow. The optional The optional WINDOW WinHandle specified nologwillbewritten. will belogged. You mustenterafilename;DCSwillnotprompt foroneandifnonameis The FileName FILE PAUSE command activates theoptiontologincomingdataafile.Asecondinstanceof WinHandle WINDOW argument isastringspecifyingthenameoffiletowhichincomingdata WINDOWWinHandle and clauseincludesthe argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular FILE RESUME commandstopauseandresume filelogging. WINDOW Session > keyword andthe Log Incoming Data WinHandle > Log toFile argument. . 3 Commands 405 command, or upon the MENU CANCEL command, indicating the end of the menu command, indicating command is followed by one or more menu options. menu one or more by command is followed MENU END MENU arguments with a argument is not included, only the DCS application control menu is shown. menu is shown. application control argument is not included, only the DCS Option argument is any of the following menu commands: argument is any of the following ITEM SEPARATOR POPUP Option Option command is used to reconfigure a DCS application menu, allowing for the addition or for allowing a DCS application menu, reconfigure command is used to end of script execution. each individual menu option command. See Option The the If in the upper left hand corner System menu and is located menu is also called the (The control of the window.) a menu bar upon executing its standard DCS restores Example Comments Arguments MENU MENU Option Option... MENU END The menu options. The available of restriction the must follow You definition. MENU 406
DCS Script Language Reference MENU CANCEL menu bar. The MENU CANCEL MENU CANCEL Arguments Example Comments The CANCEL the menubardefinition removes the In thisexample: end ofscriptexecution. DCS restores itsstandard menubaruponexecuting a MENU CANCEL PERFORM receive_files MENU CANCEL PERFORM setup MENU END POPUP “Help”SYSTEM9 POPUP “Windows”SYSTEM10 POPUP “View”SYSTEM6 POPUP “Session”SYSTEM11 POPUP “Edit”SYSTEM4 POPUP “File”SYSTEM2 MENU commandrestores theseoptionsbefore thereceive_files routine isperformed. commandremoves themenubarcreated by ascript,restoring DCS’s standard commandtakesnoarguments. Tools and Script MENU CANCEL menus from themenubar. The command,oruponthe MENU 3 Commands 407
Clear Screen menu (popup menu 2) function TRUE. returns Edit Edit menu immediately moves up menu immediately moves ) are removed from the second from removed ) are Edit Edit ERROR Clear Screen item in the and command, the Send Send MENU Clear Screen command removes an item from a popup menu. an item from command removes ) . The first line of the script removes from the removes ) . The first line of the script Edit argument is an integer expression indicating the popup menu from which the indicating the popup menu from expression argument is an integer argument is an integer expression indicating the position of the item to be deleted. argument is an integer expression selection (item 3). The MENU DELETE ITEM 2 3 MENU DELETE ITEM 2 3 IntItem IntPopup Send Send one position and becomes the third menu selection. Therefore, to remove the remove to menu selection. Therefore, one position and becomes the third the from menu selection the third from selection, the second line of the script again removes second popup menu . items four and five immediately move up one position in the menu, becoming items three and up one position in the menu, becoming items three immediately move items four and five four. this script segment: In and fourth menu selections ( the third popup menu ( the IntItem The or numbering items, be sure When counting 1 (one). The first item in the popup menu is item to count both menu items and separators. is no menu defined via the there If up one position in the the deleted item move an item is deleted, all items following Once is deleted, items and item three if a popup menu contains five example, popup menu. For IntPopup The item will be deleted. menu 1 (one). on the left side of the menu bar is popup The first popup menu Example Comments Arguments MENU DELETE ITEM MENU DELETE ITEM IntPopup IntItem ITEM IntPopup MENU DELETE The MENU DELETE ITEM MENU 408
DCS Script Language Reference MENU DELETEPOPUP The MENU DELETEPOPUP IntPopup MENU DELETEPOPUP Arguments Example Comments IntPopup the secondlineofscriptagainremoves thethird popupmenu, moves onepositiontotheleftandbecomesthird popupmenuonthebar. Therefore, removes the the third popupmenus, andfourth In thisscriptsegment: bar, becomingpopupmenusthree andfour. menu three isdeleted,menusfourandfive immediatelymove leftonepositiononthemenu position onthemenubar. For example,ifapopupmenucontainsfive popupmenusand Once apopupmenuisdeleted,allmenusfollowing thedeletedmenumove leftone If there isnomenudefinedviathe The firstpopupmenuontheleftsideofbaris1(one). The IntPopup MENU DELETEPOPUP3 MENU DELETEPOPUP3 Session argument isanintegerexpression indicatingthepopupmenutobedeleted. menu (popup3)from the menubar. The commandremoves apopupmenufrom themenubar. MENU Session command, the and Script , are removed. Thefirstlineofthescript ERROR Script function returns TRUE. function Script . menu immediately 3 Commands 409
- Actio&n Command function TRUE. returns ] with an ampersand (&). to indicate the menu item key to indicate that the menu item ERROR CHECKED ENABLED Enabled Checked Enabled command, the MENU argument uses the keyword argument uses the keyword argument uses the keyword argument uses the keyword ’ and the menu item is selected with the [Alt] + [N] key combination. ’ and the menu item is selected with the n command adds an item to a popup menu. command adds an item argument is a command, or block of commands, indicating the DCS com argument is an integer expression indicating the popup menu into which the indicating the popup menu into expression argument is an integer Enabled Checked argument is string indicating the name of the menu item. To assign an [Alt] + assign To the menu item. argument is string indicating the name of argument is an integer expression indicating the item’s position in the menu. The indicating the item’s argument is an integer expression Command IntItem StrText IntPopup ] combination to the menu item, precede the letter of the [ ] combination to the menu item, precede key The the user. or checked by when the menu item is selected mand or function executed is no menu defined via the there If one position in the down inserted the an item is inserted, item move Once all items following items and item is inserted example, if a popup menu contains five as item popup menu. For one position in the menu, down immediately move and five four, existing items three, three, and six. five, becoming items four, Enabled The optional is not specified in the command, this keyword dimmed), and can be selected. If (not is active the menu item will not be enabled. Checked The optional is not this keyword If is checked and any command associated with the menu item is active. specified in the command, the menu item will appear unchecked. Command IntItem The to items, be sure When counting or numbering first item in the popup menu is item 1 (one). count both menu items and separators. StrText The [ For example, the string of the menu item. The letter appears underlined in the text underlines the letter ‘ IntPopup The item will be inserted. menu 1 (one). on the left side of the menu bar is popup The first popup menu Comments Arguments MENU INSERT ITEM MENU INSERT MENU INSERT ITEM IntPopup IntItem StrText IntItem StrText ITEM IntPopup MENU INSERT The MENU INSERT ITEM MENU 410
DCS Script Language Reference MENU INSERTITEM, Example the sessionfile item ofthethird popupmenu.It appearsinthemenuasenabled. When selected,DCSloads In thisexample,themenuitem“ “LIBCONG” MENU INSERTITEM34“LibraryofCongress”ENABLEDLOAD LIBCONG continued . Library ofCongress ” is added as the fourth menu ” isaddedasthefourth 3 Commands 411 function TRUE. returns ] with an ampersand (&). key ERROR ” is added as the fourth popup menu on the menu command, the ’ and the menu item is selected by the [Alt] + [B] ’ and the menu item is selected by b MENU command adds a popup menu to the menu bar. command adds a popup Online Libraries will underline the letter ‘ argument is an integer expression indicating the popup menu to be added to the indicating the popup menu to be expression argument is an integer argument is string indicating the name of the popup menu. To assign an [Alt] + To the popup menu. argument is string indicating the name of MENU INSERT ITEM 4 3 “Univ. of &Michigan” ENABLED LOAD MENU INSERT ITEM 4 3 “Univ. of &Michigan” ENABLED LOAD “UOFM” LOAD MENU INSERT ITEM 4 4 “Library of Con&gress” ENABLED “LIBCONG” MENU INSERT POPUP 4 “Online Li&braries” MENU INSERT ITEM 4 1 “NYP&L” ENABLED LOAD “NYPL” MENU INSERT ITEM 4 2 “Univ. of &Houston” ENABLED LOAD “UOFH” StrText StrText IntPopup ] combination to the menu item, precede the letter of the [ ] combination to the menu item, precede key the popup menu “ also added to menu items are can be selected with the [Alt] + [B] key combination. Four It bar. this menu, which displays when the new menu is selected. right one position on the menu bar. For example, if the menu bar contains five popup menus example, if the menu bar contains five For right one position on the menu bar. immediately and five four, existing menus three, and a popup menu is added as menu three, and six. five, menus four, becoming right one position on the menu bar, move this example: In StrText The [ For example, the string text of the popup menu. The letter will appear underlined in the Li&braries key combination. is no menu defined via the there If the added menu move all menus following a popup menu is added to the menu bar, Once IntPopup The menu bar. menu 1 (one). on the left side of the menu bar is popup The first popup menu Example Comments Arguments MENU INSERT POPUP MENU INSERT MENU INSERT POPUP IntPopup StrText IntPopup POPUP MENU INSERT The MENU INSERT POPUP MENU 412
DCS Script Language Reference (MENU) ITEM The ITEM Text (MENU) ITEM Arguments Comments Text You mayincludeamaximumof200itemsinmenu definition. key oftheunderlinedcharactersimultaneously. underlined. Themenuoritemcanthenbeselected by pressing the[ALT] keyandthe If acharacterinthe mand block).Selecting themenuitemexecutes thelogicalcommand. The Command, ... The optional Checked The optional Enabled The Command Text Enabled Checked UNCHECKED CHECKED Keyword GRAYED DISABLED ENABLED Keyword Description argument isastringspecifyingthecharacterstodisplayonmenuitem. commandaddsamenuitemtothemostrecently addedpopupmenu. Checked Enabled
argument specifiesalogicalcommand(eithersingleorcom Text argument isspecified by oneofthefollowing keywords: argument isspecified by one of thefollowing keywords: menu Directs DCStoremoveacheckmarkprecedingthespecifieditemin Directs DCStoplaceacheckmarkbeforethespecifiediteminmenu Description in gray(ordimmed)type Directs DCStodisallowselectionofthespecifieditemanddisplay Directs DCStodisallowselectionofthespecifieditem Directs DCStoallowselectionofthespecifieditem argument ispreceded by anampersand(&),thecharacterappears Command, ... - 3 Commands 413 ] key combination. subroutine. Through the keyboard, you can the keyboard, Through subroutine. ALT]+[A add_name performs the menu item by pressing the [ pressing menu item by Add… continued Add… MENU POPUP “&Names” PERFORM add_name ITEM “&Add...” MENU END WAIT RESUME access the In this script segment: In the menu item Example (MENU) ITEM, (MENU) 414
DCS Script Language Reference (MENU) POPUP The POPUP Text (MENU) POPUP Arguments Comments Text The definedSYSTEMmenus are: menu bar. The If theclause isnotincluded,theaddedpopupmenubarcontainsnoitemsfrom thesystem The optional SYSTEM Pos The Text * Insert SYSTEM 12 Session SYSTEM 11 Window Help SYSTEM 10 Tools SYSTEM 9 Tools SYSTEM 8 View SYSTEM 7 Script SYSTEM 6 Edit SYSTEM 5 Edit SYSTEM 4 File SYSTEM 3 File SYSTEM 2 Menu SYSTEM 1 System SYSTEM Pos MEMO tomemowindows, andSCRIPTtoascripteditorwindow. MAIN refers totheDCSapplicationwindow. SESSIONrefers tosessionwindows, dependingonwhichtypeofwindowThe visiblemenus isactivevary (infocus). argument isastringspecifyingthenameofpopupmenutodisplay. SYSTEM commandaddsapopupmenutothebar. Pos argument isanumericspecifyingthepredefined menuasdefinedbelow. clause takestheaddedpopupmenufrom DCSdefaultdefinedmenus. MEMO SESSION MEMO, SCRIPT, SESSION MAIN, MEMO,SCRIPT, SESSION MEMO, SCRIPT MAIN, SESSION MAIN, MEMO,SCRIPT, SESSION MAIN, MEMO,SCRIPT, SESSION SESSION MEMO, SCRIPT SESSION, SCRIPT, MEMO MAIN Active windowtype* 3 Commands 415 continued MENU SYSTEM 1 POPUP “File” SYSTEM 3 POPUP “Edit” MENU END In this script segment: In menus. Edit File and defined containing only DCS’s a custom menu bar is Example (MENU) POPUP, POPUP, (MENU) 416
DCS Script Language Reference (MENU) SEPARATOR the popupmenu. The SEPARATOR (MENU) SEPARATOR Arguments Example The display_name Delete when In thisscriptsegment: SEPARATOR Add WAIT RESUME MENU END ITEM “Di&splay”PERFORMdisplay_name SEPARATOR ITEM “&Delete...“PERFOMdelete_name ITEM “&Add...“PERFORMadd_name POPUP “&Names” MENU is selected,the is selectedonthe routine isperformed. command takesnoarguments. commandaddsamenuitemseparator, displayed asahorizontal line,to delete_name Names menu, the routine is performed. routine isperformed. When add_name routine is performed. routine isperformed. When Display is selected,the 3 Commands 417 argument replaces the name argument replaces Text Text argument applies the same state to all argument applies the same state to all items argument becomes the text for the menu argument becomes the text for the menu Text Text Checked Enabled , the contents of the arguments change the state of each menu item. arguments change the state of each menu argument, the Checked Item directs DCS to place a check mark before the specified item in the menu directs DCS to remove a check mark preceding the specified item in the menu. Directs DCS to allow selection of the specified item Directs DCS to allow selection of the specified item Directs DCS to disallow selection of the specified Directs DCS to disallow selection of the specified item and display the item in gray (or dimmed) type. Item argument and argument is specified by one of the following keywords: by one of the following argument is specified argument is specified by one of the following keywords: by one of the following argument is specified Item Text Enabled Checked Item Text argument is an integer specifying a menu item to update within a popup. item to update within a popup. argument is an integer specifying a menu argument is a string specifying the replacement text for a menu or item. If text for a menu or item. If argument is a string specifying the replacement Enabled command updates a previously defined menu option, or group of options. defined menu option, or group previously command updates a Checked Enabled Item Text argument is a numeric specifying which popup menu is to be updated. The control updated. The control specifying which popup menu is to be argument is a numeric argument is not specified, the argument is not specified, the Keyword Description CHECKED UNCHECKED Keyword Description ENABLED DISABLED GRAYED Item Item Popup items in the menu. If the the If in the menu. Checked The optional the If Enabled The optional The optional items in a menu, include both are numbering you When item one. The first item is considered may only update menu items, not separators. you menu items and separators; however, do not include the you If name, and the Text The optional do not included the you of the menu. Popup The zero. by the integer menu is specified Item Arguments MENU UPDATE MENU UPDATE Popup MENU UPDATE The MENU UPDATE MENU 418
DCS Script Language Reference MENU UPDATE, Example Comments In thisscriptsegment: If there isnomenudefinedviathe (selects) the the selection WAIT DELAY“9” MENU UPDATE27CHECKED WAIT DELAY“9” MENU END ITEM “checkme”UncheckedDISPLAY“Checkme!” SEPARATOR POPUP “Script”system5 POPUP “File”system1 MENU checkme checkme continued item. isaddedtothe MENU Script command, the menu. Afternineseconds,thescriptchecks ERROR function returns TRUE. function 3 Commands 419 - com DEBUG and command and removes the command and removes SHOW SHOW command command SHOW DEBUG command takes no arguments. command takes no in conjunction with the command can be used command is a compiler directive which cancels the directive command is a compiler Also see: NOSHOW NOSHOW mands to control which command lines are written to a debug file. written to a which command lines are mands to control The The Arguments Comments NOSHOW NOSHOW The status bar in the DCS application window. the from display of a script command NOSHOW 420
DCS Script Language Reference PARSE the keyword are stored inthesecondstringvariable. all characterspreceding thekeyword are stored inthefirststring variable, andallcharactersfollowing The PARSE StringStringVar1 KeywordStringVar2 PARSE Arguments Example Comments assigns thestring“ the keyword isacomma(,).DCSassignsthestring“ In thisexample: The that appearafterthekeyword. The StringVar2 The Keyword string preceding thekeyword. The StringVar1 The String ERROR StringVar2 Keyword StringVar1 String command locatesthekeyword inthespecifiedstring. If thestringcontainskeyword, PARSE ‘EVANSTON,IL60202’$city‘,’$rest argument containsthestringinwhichDCSsearches forthekeyword. function returns TRUE ifthestringdoesnotcontainkeyword. argument specifiesthestringforwhichtosearch. argumentspecifiesastring variable inwhichtostore allcharactersinthestring argumentspecifiesastring variable inwhichDCSstores allcharactersinthe IL 60202 ” tothevariable $rest EVANSTON . ” tothevariable $city , and 3 Commands 421 ;child handles [email protected] $str3 PARSE $str1 $str2 “break” @r1.2=$str2 @r1.3=$str3 LEAVE END END IF #Found = “ | str (%thnd) | “^M” DISPLAY “Session window Handle ELSE not found. ^M” DISPLAY “Session window Handle #Found = FALSE (-1) $hnd = hwndlist “ “ WHILE $hnd != BEGIN “ , “ $hnd parse $hnd $h %thnd = num ($h) = 1 IF WNDCLASS (%thnd) BEGIN #Found = TRUE continued In this example, two table variables (@r1.2 and @r1.3) provide the strings that precede and that precede the strings (@r1.2 and @r1.3) provide this example, two table variables In the first by for in a string supplied that is searched (“break”) the keyword respectively, folow, (@r1.1). table variable the list of open child window handles is returned and parsed into individual handles. DCS handles is returned the list of open child window determines the handle of the session window. this example: In In this example: In PARSE, PARSE, 422
DCS Script Language Reference PERFORM define asubroutine. executes a current scriptresumes atthecommandfollowing the The PERFORM Target PERFORM Example Comments Arguments The DCS creates abatchcompileofallscriptfilesinthecurrent aroutine thatperforms directory. In thisexample: identified by the The optional (Parameter, ...) (usually anotherscriptoraroutine inanotherscript). The Target RETURN Target PERFORM RETURN END $Source =NEXT() COMPILE $Source#Make BEGIN WHILE NOTERROR() $Source =ROUTE($Scripts) ARGUMENTS ($Source) *CompileAll ($Scripts,#Make) . . . PERFORM CompileAll(“c:\dcseries\script\*.DCP”,TRUE) Also see: command causesscriptexecution tobranchthespecified target. Execution ofthe argument specifieseitheranear(usually routine inalocalscript)orfartarget command. When usedinthisway, the (Parameter, ...) (Parameter, ...) command passestwoparametersby value totheroutine Target Parameter Passing argument. It consistsofoneormore strings,numerics, or Booleans. argumentspecifiestheparameterstobepassed routine in Chapter 1Introduction PERFORM PERFORM command whenthetargetscript and RETURN *CompileAll commands . 3 Commands 423 command does not close the currently open print channel. close the currently command does not command takes no arguments. command takes no PRINT CANCEL PRINT command terminates the active print jobs. print the active command terminates PRINT CANCEL PRINT The the Executing Arguments Comments PRINT CANCEL PRINT PRINT CANCEL The PRINT CANCEL PRINT 424
DCS Script Language Reference PRINT CLOSE The PRINT CLOSE PRINT CLOSE Arguments Example The See the PRINT CLOSE PRINT OPEN commandclosestheopenprintchannel,terminatinganyactive printjobs. commandtakesnoarguments. command. 3 Commands 425 argument must FileName command automatically opens a print channel and command automatically opens a print channel , is printed. PRINT FILE PRINT MYFILE.TXT LF keyword adds line feeds to all outgoing carriage returns. If it is not included, If adds line feeds to all outgoing carriage returns. keyword argument is a string specifying the file to print. The argument is a string function returns TRUE if the file does not exist, or if DCS cannot open the print TRUE function returns LF command prints the specified file. command prints the FILE RECEIVE BINARY “MYFILE.TXT” PRINT FILE “MYFILE.TXT” ERROR FileName In this example: In file, the newly received The optional only. printed as carriage returns are carriage returns If no print parameters of the open print channel. active to the The file is printed according open, the channel is currently uses the default print parameters. The channel and print the file. FileName The your system. file name for specify a valid LF Example Comments Arguments PRINT FILE PRINT PRINT FILE FileName PRINT FILE The PRINT FILE PRINT 426
DCS Script Language Reference PRINT FONT The PRINT FONT PRINT FONT Arguments Example Font See the it isnotincluded,thecurrent pointsize isused. The optional Point included, thecurrent fontisused. The optional PRINT OPEN Font Point commandchangestheactive printfont. Point Font argument isastringspecifyingvalid fontfaceforyour printer. If itisnot argument isanumericspecifyingvalid pointsize forthespecifiedfont. If command. 3 Commands 427 - command to print a blank line between the header (contain command to print a blank line between command takes no arguments. command takes no command sends a carriage return and line feed to the printer. return command sends a carriage PRINT NEWLINE PRINT PRINT OPEN ‘ | TIME () PRINT STRING DATE () | ‘ at PRINT NEWLINE PRINT TERMINAL ON PERFORM get_info PRINT TERMINAL OFF PRINT CLOSE PRINT NEWLINE PRINT DCS uses the data. ing the data and time) and the incoming The this example: In Arguments Example PRINT NEWLINE PRINT PRINT NEWLINE The PRINT NEWLINE PRINT 428
DCS Script Language Reference PRINT NEWPAGE The PRINT NEWPAGE PRINT NEWPAGE Arguments Example The DCS sendsaformfeedbetween eachfileprinted. In thisexample: PRINT NEWPAGE PRINT CLOSE PRINT FILE‘script3.dcp’ PRINT NEWPAGE PRINT FILE‘script2.dcp’ PRINT NEWPAGE PRINT FILE‘script1.dcp’ PRINT FONT‘helv’12 PRINT OPEN commandsendsaformfeedtotheprinter. commandtakesnoarguments. 3 Commands 429
- - argument is a dialog while print argument is a argument is a string MYSCRIPT.DCP Driver clause is not includ Port Type Type Abort TYPE clause is not included, DCS uses command). DRIVER clause is not included, DCS uses the default port.clause is not included, PRINT FILE PRINT PORT clause allows you to specify the printer driver. The to specify the printer driver. you clause allows keyword directs DCS to display the Windows Windows to display the DCS directs keyword clause allows you to specify the printer port. to specify the printer you The clause allows clause allows you to specify the printer type. The you clause allows command (except the command (except UNC standards must be used when specifying a network printer. For example, For printer. must be used when specifying a network UNC standards “\\\\primeserver\financehp” denotes use of the printer called “financehp” on the printer called “financehp” denotes use of the “\\\\primeserver\financehp” used to indicate the server that four backslashes are Notice system. “primeserver” them as a single backslash used, DCS interprets two backslashes are When name. to required are The first two backslashes which indicates that a file name follows. indicate that a system name follows. TYPE ABORT DRIVER PORT command opens a print channel. DCS must open a print channel before it may it may before channel. DCS must open a print channel command opens a print PRINT PRINT PORT Port DRIVER Driver TYPE Type ABORT TYPE Type DRIVER Driver PORT Port Note: PRINT OPEN PORT “LPT1:” PRINT FONT “helv” 10 PRINT STYLE BOLD PRINT STRING “MYSCRIPT AS OF #” | DATE () PRINT NEWLINE PRINT STYLE NORMAL PRINT FILE “MYSCRIPT.DCP” PRINT CLOSE
In this example: In a print channel is opened, a font is specified, and a header is printed. After is printed, the print channel is closed. TYPE Type The optional If the printer type for the specified driver. string specifying a valid ed, DCS uses the default type. ABORT The optional you to cancel a print job in progress. ing. This allows DRIVER Driver The optional the If string specifying any installed printer driver. the default driver. PORT Port The optional printer port. the specifying a valid If Example Arguments PRINT OPEN PRINT PRINT OPEN PRINT OPEN The any other execute PRINT OPEN PRINT 430
DCS Script Language Reference PRINT STRING parameters intheopenprintchannel. The PRINT STRINGString PRINT STRING Arguments Example String See the The String PRINT OPEN argument specifiesthestringtobeprinted. commandprintsthecontentsofspecifiedstringaccording toactive print command. 3 Commands 431 This keyword directs DCS to eliminate all previously defined attributes and This keyword directs DCS to eliminate all previously rule drawn through the This keyword prints each character with a horizontal middle of the character. This keyword prints characters boldface type. This keyword prints characters This keyword prints characters in italic type. DCS ignores all attributes prints characters according to the default style. command. STYLE in a PRINT specified after NORMAL type. This keyword prints characters in letter quality with a horizontal rule. This keyword prints each character as underscored command.
command sets the print character attributes. command sets the print PRINT OPEN PRINT BOLD ITALIC NORMAL QUALITY STRIKEOUT UNDERLINE Keyword Description See the See Attribute ... keywords: of the following one or more by is specified Attribute argument The Example Arguments PRINT STYLE PRINT PRINT STYLE Attribute ... PRINT STYLE The PRINT STYLE PRINT 432
DCS Script Language Reference PRINT TABS The PRINT TABS Width PRINT TABS Arguments Example Width the In thisexample: value ofthe The PRINT TABS Width PRINT CLOSE PRINT FILE‘script1.dcp’ PRINT TABS5 PRINT STYLE‘courier’12 PRINT OPEN argumentspecifiestheprintedtabwidth. argument isanumericspecifyingthenumberofspacespertab. Themaximum Width commandspecifiesaprintedtabwidthoffive spaces. argument is20. 3 Commands 433 - argument. command WinHandle command directs DCS to toggle command directs keyword and the keyword PRINT TERMINAL OFF TERMINAL PRINT command automatically opens a print chan WINDOW PRINT TERMINAL PRINT PRINT TERMINAL PRINT session window to the printer until a PRINT TERMINAL RESUME command TERMINAL session window to the printer until a PRINT is executed. command. PAUSE TERMINAL a PRINT This keyword directs DCS to send all data received in the session window to This keyword directs DCS to send all data received the printer. in the session window This keyword directs DCS not to send data received to the printer. of data received in the This keyword directs DCS to suspend the sending suspended by ON command TERMINAL This keyword resumes the PRINT clause includes the command is issued until the argument is specified by one of the following keywords: of the following by one argument is specified argument is an integer identifying a particular session window. command redirects the data appearing in a session window to the printer. window the data appearing in a session command redirects State WINDOW WinHandle State WINDOW WINDOW State argument is not included, the PERFORM login PRINT TERMINAL ON PERFORM get_prices PRINT TERMINAL OFF Keyword Description ON OFF PAUSE RESUME This command does not apply to IBM TN3270 emulations. not apply to IBM This command does State WinHandle executes. If a window handle is not included, the active session window is printed. session window handle is not included, the active window a If this example: In the moment the the communications session and sends it to the printer from DCS captures ON TERMINAL PRINT If the If ON and OFF. state between the current WINDOW WinHandle The optional The If no print of the open print channel. parameters to the active The file is printed according open, the channel is currently nel and uses the default print parameters. State The optional Note: Example Comments Arguments PRINT TERMINAL PRINT PRINT TERMINAL PRINT TERMINAL The PRINT TERMINAL PRINT 434
DCS Script Language Reference QUIT The QUIT QUIT Arguments Example The the userisgiven thechoiceof either stoppingscriptexecution orquittingDCS. In thisexample: command stopsallscriptexecution andterminatestheDCS application. QUIT WAIT RESUME DIALOG END BUTTON ‘QuitDCS’QUIT BUTTON ‘QuitScript’CANCEL END RESUME PERFORM dde_quit BEGIN BUTTON ‘QuitExcel’ END RESUME PERFORM launch_xl BEGIN BUTTON ‘LaunchExcel’ DIALOG ‘SystemCoordinator’ command takesnoarguments. 3 Commands 435 - - com argument. coordinate is coordinate Row command will use. WinHandle RECORD FORMAT RECORD SCAN command extracts field data from command extracts field data from ) WINDOW WinHandle ) WINDOW n keyword and the keyword coordinate is a numeric specifying the column of is a numeric coordinate field definitions specify the relative positions in relative field definitions specify the WINDOW ) n Col RECORD SCAN Col n ) n Col command. n clause includes the (Row1 Col1) ... (Rown Col (Row1 Col1) command defines a record template the template the record command defines a argument is an integer identifying a particular session window. clause is not included in the command, the record template is defined for the the record clause is not included in the command, clause directs DCS to define a record template for a particular session window. record DCS to define a clause directs (Row1 Col1) ... (Row WINDOW argument is an integer specifying the number of terminal lines between the begin between specifying the number of terminal lines argument is an integer RECORD SCAN WINDOW WinHandle WINDOW Lines If no field definitions are included, the field definitions no If for by searching DCS locates fields using an auto-scan algorithm in which the session window spaces). consecutive tabs (two or more columns delimited by the See The The the If session. current by the table definition, the the length of each field is specified Since You may specify mand needs only to specify the starting position, not the length, of each field. a maximum of 255 field definitions. nings of consecutive data records (from the first line of record one to the first line of record record of one to the first line record of the first line (from data records nings of consecutive two, etc.). (Row1 Col1) ... (Row The optional Each record. data fields for each field in a of the desired template the record row the first data field, where of the starting position of desired an integer specifying the row Each zero. is row template in the record zero. the first column is column data field, where the starting position of desired WINDOW WinHandle The optional Lines The Example Comments Arguments RECORD FORMAT RECORD FORMAT Lines FORMAT RECORD The table to and in which window, position of data fields in the session relative the This template specifies place the scanned data. RECORD FORMAT RECORD 436
DCS Script Language Reference RECORD READ responding record buffer variable, @R Data contained inatablecannotbedirectly accessed;onerecord atatimeisaccessedthrough thecor The RECORD READTable RECORD READ Arguments read isdeterminedby adelimiter(acarriagereturn characterfollowed by alinefeedcharacter). cluded ineachdatablock.If the bytes (upto254).The The optional LENGTH Bytes The Table Table Text Tables Text Tables Structured next character(orline). After arecord read foratexttable,theread isperformed pointerispositionedat the sequentially. READ where thefirst record is record zero. If the READ ting theread positiontothespecifiedfilebefore the performing The optional AT Position at thenextrecord. After arecord read forastructured table,theread isperformed pointerispositioned begins reading atrecord zero, andsuccessive reads are sequentially. performed cord isrecord zero. If the The to thespecified record numberbefore the performing The optional AT Record argument isanumericspecifyingthetablecontainingdata. LENGTH Record commandreads datafrom thespecifiedtabletocorresponding record buffer. commandbeginsreading atrecord zero, andsuccessive reads are performed command.The AT Record AT PositionLENGTHBytes argument isanumericspecifyingtheread position,where thefirst re AT AT AT Bytes clause directs DCStoinputadatablockofthespecified numberof clause allows randomaccessofthedatablocks(nottextlines)by set clause allows randomaccessofrecords by settingtheread position argument isanumericspecifyingthenumberofbytes tobein n , where Position LENGTH AT AT clause isnotincluded,the n isatablenumber. argument isanumericspecifyingtheread position, clause isnotincluded,thelengthofdatablock AT AT clause isnotincluded,the RECORD READ RECORD READ command. RECORD RECORD command - - - - 3 Commands 437 , starting at position 200, then displays the MYDATA continued function is set to TRUE if an attempt is made to read beyond the end of the file. beyond if an attempt is made to read TRUE function is set to RECORD READ 0 AT 200 LENGTH 254 RECORD READ 0 AT 200 LENGTH DISPLAY @R0 RECORD READ 0 at 0 RECORD READ 0 WHILE NOT EOF () BEGIN DISPLAY (%1, 0) @R0 INCREMENT %1 RECORD READ 0 END TABLE DEFINE 0 TEXT “MYDATA” TABLE DEFINE 0 FIELDS CHAR 10 CHAR 5 REAL 5 0 FIELDS CHAR 10 CHAR 5 REAL TABLE DEFINE FROM “DATA” AS SYLK TABLE LOAD 0 SET %1 0 EOF DCS reads 254 bytes of data from the file of data from 254 bytes DCS reads data in the session window. DCS reads all records from table 0 (zero) and displays them in the session window until it and displays them in the session window table 0 (zero) from all records DCS reads the end of the file. reaches this example: In The this example: In Comments Example RECORD READ, RECORD 438
DCS Script Language Reference RECORD SCAN the desired table. sion window containingthedata;andthird, usethe record templateforthedata;second,use This entire process requires three steps:first,usethe mands, extractsdatafrom thesessionwindow andplacesitdirectly intoapredefined tablestructure. The RECORD SCANTable RECORD SCAN Example Comments Arguments The name,age,andaccounttotal foreach record istransferred to table0(zero). In thisexample: If the spaces). which DCSlocatesfields by searching forcolumnsdelimited by tabs(twoormore consecutive SCAN If nofielddefinitions are specified bythe each group oflines. Lines argumentofthe If thenumberoflineswithinselectionrangeexceeds thenumberoflinesspecified by the commands. venient methodofacquiringstructured terminaldatathanusingthe template orselectionrange.Using the screens, you canusethe If theplacementofdatainsessionwindow isthesameforseveral records ononeormore The The The optional WINDOW WinHandle does notcleartheexistingcontentsoftablebefore data. addingnew The Table WINDOW WinHandle Table WINDOW RECORD SCAN0 SELECTION 616 RECORD FORMAT4(05) (025)(346) TABLE DEFINE0FIELDS CHAR20INT3REAL7 commandextractsfielddatafrom thesessionwindow usinganauto-scanalgorithmin argument isanintegerspecifyingthetableintowhichDCSstores thedata.DCS WINDOW command,inconjunctionwiththe clausedirects sessionwindow. DCStoscanaparticular clauseisnotincludedinthecommand,current sessionwillbescanned. argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular WINDOW WinHandle RECORD FORMAT clauseincludesthe RECORD SCAN SELECTION RECORD SCAN RECORD FORMAT commandrepeatedly withoutrespecifying therecord command,DCScopiesarecord tothetablefor WINDOW RECORD FORMAT RECORD SCAN RECORD FORMAT command tospecifytheregion oftheses keyword andthe commandisafasterandmore con commandtotransferthedata command,the command to define a virtual commandtodefineavirtual COLLECT and WinHandle SELECTION RECORD and PARSE argument. com - - - 3 Commands 439 - -
RECORD command. RECORD WRITE clause is not included, the AT Y RECORD WRITE clause is not included, the clause is not included, the length of the data AT is a table number. argument is a numeric specifying the desired write argument is a numeric specifying the desired n LENGTH , where , where AT Position LENGTH Bytes Position LENGTH AT
n Position argument is a numeric specifying the number of bytes to be argument is a numeric specifying the number of bytes command begins writing at the end of the table, and successive table, and successive command begins writing at the end of the clause allows random access of the data blocks (not text lines) by set (not text lines) by random access of the data blocks clause allows clause allows random access of records by setting the write position by random access of records clause allows Bytes clause directs DCS to output a data block of the specified number clause directs AT AT argument is a numeric specifying the desired write position, where the where write position, argument is a numeric specifying the desired AT Record AT command. The command writes the contents of the record buffer to the corresponding table. to the corresponding buffer contents of the record command writes the Record LENGTH argument is a numeric specifying the table to which DCS writes the data. specifying the table to which DCS writes argument is a numeric AT Position AT The optional performing the position before ting the write position to the specified file WRITE If the 0 (zero). record is record the first position, where RECORD WRITE performedsequentially. writes are write, the write pointer is positioned at the next charac After DCS performs a record ter (or line). AT Record AT The optional performing the number before record to the desired The If the 0 (zero). record is record first performed writes are table, and successive command begins writing at the end of the sequentially. write, the write pointer is positioned at the next record. After DCS performs a record Text Text Tables Structured Tables Table Table LENGTH Bytes The optional (up to 254). The of bytes the included in each data block. If a line feed by character followed the delimiter (a carriage return block written is determined by character). Table The Arguments RECORD WRITE RECORD WRITE Table WRITE Table RECORD The the at a time through it must access one record contained in a table directly; DCS cannot access data variable, @R buffer record corresponding RECORD WRITE RECORD 440
DCS Script Language Reference RECORD WRITE, Example In thisexample: text fieldiswrittentotable0(zero). a dialog,prompting foraname,isdisplayed. When anameisentered, thecontentsofedit RECORD WRITE0 @R0 =EDITTEXT(1) WAIT RESUME DIALOG END BUTTON (50,50)“OK”Resume EDITTEXT (20,10,144,10)“EnterName:” DIALOG (50,50,200,75)“Edit” TABLE DEFINE0FIELDSCHAR20 continued 3 Commands 441 . . function TRUE. returns C:\DCSERIES\TEMP command deletes the specified directory command deletes the ERROR argument is a string specifying the path of the directoryargument is a string to be removed. REMOVE DIRECTORY “C:\DCSERIES\TEMP” The directory is not empty valid for the computer The path is not The path does not end with a directory name directory. working The directory is the current This command does not apply to IBM TN3270 emulations. not apply to IBM This command does
Path This command: the directory removes This command fails under the following conditions: This command fails under the following each case, the In Path The Note: Comments Example Arguments REMOVE DIRECTORY REMOVE DIRECTORY Path DIRECTORY REMOVE The REMOVE DIRECTORY REMOVE 442
DCS Script Language Reference RESETSERIAL The RESETSERIAL RESETSERIAL Arguments Example Comments The DCS resets the communications port after receiving the binary filefromDCS resets the afterreceiving thecommunicationsport remote system. thebinary In thisexample: port. The tions withsomeremote hosts. toreset aftercommunicationstransac thecommunicationsport On occasion, itisnecessary ERROR RESETSERIAL RESETSERIAL FILE RECEIVEBINARY“LONGFILE.TXT” commandresets ofthedefaultsessionwindow. theserialcommunicationsport function returns TRUE ifthecommandcannotreset theserialcommunications commandtakesnoarguments. - 3 Commands 443 button is clicked. command does not clear any existing resources created during created any existing resources command does not clear OK RESTART RESTART command takes no arguments. command causes the execution of a script to branch to the first line of the executing executing a script to branch to the first line of the of execution command causes the PERFORM set_up PERFORM get_data DIALOG MESSAGE “Repeat Procedure?” BUTTON “OK” RESTART BUTTON “NO” CANCEL DIALOG END RESTART RESTART the script is restarted if the the script is restarted script execution (variables, tables, etc.). (variables, script execution this example: In The of a The execution Example Arguments Comments RESTART RESTART RESTART The script. RESTART 444
DCS Script Language Reference RESUME cently executed The RESUME RESUME Arguments Example Comments The SUME after the In thisexample: RESUME WAIT RESUME DIALOG END BUTTON (110,50)“CANCEL”CANCEL BUTTON (50,50)“OK”PERFORMlaunch,RESUME EDITTEXT (20,40,140)“FileName:“ EDITTEXT (20,10,140)“Application:“ DIALOG (20,40,200,60)“LAUNCH” Also see: command causesscriptexecution toresume atthecommandfollowing themostre command branchesexecution beyond the WAIT OK button ispressed theroutine labeled command. command takesnoarguments. tion Event Handling - WAIT and WHEN Commands WAIT RESUME *launch is performed. Then,the isperformed. command. in Chapter 1Introduc RE - - - 3 Commands 445 - - com command command PERFORM PERFORM RETURN commands, when used together, together, commands, when used command. RETURN CANCEL CANCEL and PERFORM command without having previously executed a executed command without having previously command operates as the RETURN command. The command takes no arguments. RETURN command causes script execution to resume at the command following the most recent at the command following to resume execution command causes script . . . *errorRoutine ($errorMessage) DIALOG (20, 20, 100, 60) MESSAGE $errorMessage BUTTON “OK” RESUME DIALOG END WAIT RESUME RETURN IF ERROR BEGIN more data”) PERFORM errorRoutine (“No CANCEL END RETURN PERFORM that called the routine. a generic error routine is created. Whenever the routine executes, the executes, the routine Whenever is created. routine a generic error the to branch back to the line immediately following causes execution If DCS executes a DCS executes If mand, the this example: In The Example Arguments Comments RETURN RETURN The ly executed define a subroutine. RETURN 446
DCS Script Language Reference SAVE file name. The SAVE FileName SAVE Arguments Example Comments FileName two settingswere modifiedandsaved assessionfile In thisexample: the current settingsare saved asthesessionfile In thisexample: The sion file. If nosessionfileiscurrently active, thiscommandwillhave noeffect. If you donotincludethe you toenterthenameofafileinwhichsave thesessionduringscriptexecution. The the “.ses” fileextension. If you donotspecifyafileextensioninthe system. configuration information.The The optional command saves theactive session’s configurationtothesession filespecified bytheoptional ERROR FileName SAVE “ANSIUSER” SET PHONENUMBER“5551234” SET EMULATION“ANSI” SAVE “CIS” FileName function returns TRUE ifaninvalid filenameisspecified. argument mayalsobespecifiedasaquestionmark (?).DCSwillthen prompt argument isastringspecifyingthesessionfileinwhichtosave the FileName FileName argument, DCSsaves theconfiguration totheactive ses argument mustspecifyavalid filenamefor your FileName CIS.SES ANSIUSER.SES argument, thefileisautomaticallygiven . . - 3 Commands 447 s argument. WinHandle keyword and the keyword WINDOW terminal screen with received data if it is dimmed. entire client area. window to its previous size. This keyword restores a maximized session This keyword hides a session window. is hidden, and updates the This keyword displays a session window if it screen updating. This keyword turns off fill the application window’ This keyword expands a session window to coordinate set specifies the desired position and size of a session of size position and set specifies the desired coordinate clause includes the argument is specified by one of the following keywords: keywords: by one of the following argument is specified argument is an integer identifying a particular session window. WINDOW Display (x, y, w, h) w, (x, y, command controls the size and display of a session window. and display of the size command controls SCREEN HIDE DIAL “5551234” PERFORM login LOGTOFILE “INDATA.TXT” FILE CLOSE SCREEN SHOW RESTORE Keyword Description HIDE SHOW DIM MAXIMIZE WinHandle (x, y, w, h) Display WINDOW WinHandle h) Display WINDOW w, (x, y, If a window handle is not included, the command affects the active session window. handle is not included, the command affects the active window a If this example: In is captured. is hidden while the incoming text the session window WINDOW WinHandle The optional The is fully functional. A hidden session window are eight logical units per line. are Display The optional (x, y, w, h) w, (x, y, The optional are (x, y), width (w), and height (h). The coordinates indicates the top left corner It window. there vertically, units per character: four logical are there units; horizontally, specified in logical Example Comments Arguments SCREEN SCREEN The SCREEN 448
DCS Script Language Reference SCROLL DOWN session window). scrollonly whenthevertical barisdisplayed (indicatingthattheentire hostscreen isnotvisibleinthe buffer.history It isthesameasclickingondown arrow scroll onthe bar.vertical It isapplicable The SCROLL DOWNRows SCROLL DOWN Comments Arguments This commanddoesnotchangethepositionofcursorinsessionwindow. scrolling stopsatthelastrow. cal scroll bar. If thenumberofscroll down linesexceeds thelower buffer, limitofthehistory The result ofthiscommandisthesameasif you hadclickedonthedown arrow onthe verti buffer.history The Rows Rows argument isanintegerspecifyingthenumberoflinestoscroll down through the commandscrolls down aspecifiednumberoflinesintheactive sessionwindow - 3 Commands 449 - argument is an integer specifying the number of single character positions to specifying the number of single character argument is an integer command directs DCS to scroll left in the active session window. It is the same as It session window. left in the active to scroll DCS command directs Columns scroll left. scroll on the horizontal the left arrow you had clicked result of this command is the same as if The the left mar exceeds the number of columns to scroll If bar at the bottom of the screen. scroll zero). stops at the leftmost column (column scrolling gin limit of the history buffer, of the cursor in the session window. This command does not change the position Columns The Comments Arguments SCROLL LEFT SCROLL SCROLL LEFT Columns SCROLL The scroll only when the horizontal is applicable It bar. scroll on the horizontal clicking on the left arrow session window). is not visible in the host screen entire (indicating the bar is displayed SCROLL LEFT SCROLL 450
DCS Script Language Reference SCROLL RIGHT scroll bar is displayed (indicatingtheentire hostscreen isnotvisibleinthesessionwindow). as clickingontherightarrow onthehorizontal scroll bar. It isapplicableonlywhenthehorizontal The SCROLL RIGHTColumns SCROLL RIGHT Arguments Comments This commanddoesnotchangethepositionofcursorinsessionwindow. buffer,margin limitofthehistory scrolling stopsattherightmostcolumn. scroll baratthebottomofscreen. If thenumberofcolumnstoscroll exceeds therightmost The result ofthiscommandisthesameasif you hadclickedtherightarrow onthehorizontal scroll right. The Columns Columns commanddirects DCStoscroll rightintheactive session window. It isthesame argument isanintegerspecifyingthenumberofsinglecharacterpositionsto 3 Commands 451 - - argument is an integer specifying the number of lines to scroll up through the his up through specifying the number of lines to scroll argument is an integer command directs DCS to scroll up a specified number of lines in the active session active up a specified number of lines in the to scroll DCS command directs Rows The tory buffer. vertical bar. in the scroll the up arrow you clicked result of this command is the same as if The stops scrolling the upper limit of the history up exceeds buffer, the number of lines to scroll If at the top row. of the cursor in the session window. This command does not change the position Rows Comments Arguments SCROLL UP SCROLL SCROLL UP Rows UP SCROLL The It is ap vertical bar. on the scroll up arrow It is the same as clicking on the history buffer. window’s is not visible in screen host (indicating the entire bar is displayed verticalplicable only when the scroll the session window). SCROLL UP SCROLL 452
DCS Script Language Reference SELECTION selects theblock,blockwillnotappearhighlightedinwindow. The SELECTION StartLineEndLine SELECTION Arguments Example Comments StartLine See the window isselected. If you donotincludethe The selectionblockincludesallcolumnsoftheselected rows. selection. DCSdoesnotmakeadefaultselectioninthewindow. and window andthepossiblevalues ofthe (for example,themodelina3270emulation)determinesnumberoflinessession When you wanttomakeaselectioninsessionwindow, thenumberofrows inanemulation The The The The optional WINDOW WinHandle The EndLine block, where thefirst row inawindow isconsidered row zero. The EndLine StartLine WINDOW WinHandle EndLine StartLine RECORD SCAN command selectsablockofrows inasessionwindow. Althoughthecommand WINDOW arguments are largerthantherangeallowed for awindow, DCSwillnotmakea argument isanumericspecifyingthenumberoflastrow ofthedesired block. and argument isanumericspecifyingthenumberoffirst row ofthedesired clause selects a block in a particular sessionwindow.clause selectsablockinparticular argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular EndLine clause includesthe command. WINDOW arguments mustnotexceed thenumber ofrows forawindow. WINDOW WinHandle clause inthecommand,ablockactive session StartLine WINDOW and EndLine keyword andthe arguments. If boththe WinHandle argument. StartLine 3 Commands 453 - . - argument. DATAFILE.TXT WinHandle keyword and the keyword WINDOW TABLE WINDOW WinHandle WINDOW TABLE clause includes the keyword saves the data in a tabular format. All data separated by two or the data in a tabular format. All data separated by saves keyword argument must specify a valid file name for your system or a null string your for file name a valid argument must specify command appends the current selection in a session window to the exist selection in a session window the current command appends clause is not included in the command, the selection is appended from the selection is appended from clause is not included in the command, the argument is an integer identifying a particular session window. clause appends the selection from a particularclause appends the selection from session window. argument is a string specifying the name of the file in which to save the selec to save specifying the name of the file in which argument is a string TABLE TABLE WINDOW FileName SELECTION BUFFER SELECTION APPEND “DATAFILE.TXT” WINDOW WinHandle WINDOW FileName If the If session window. active this example: In contents of the historyDCS adds the current buffer to the end of the file (“”). If a null string is specified, a prompt appears during script execution to enter the name of appears during script execution a prompt a null string is specified, (“”). If the selection. a file in which to save TABLE The optional spaces will be tab delimited. consecutive more WINDOW WinHandle The optional The The FileName The tion. The Comments Example Arguments SELECTION APPEND SELECTION APPEND SELECTION FileName The file. ing contents of the specified SELECTION APPEND SELECTION 454
DCS Script Language Reference SELECTION BUFFER nal. This commandisnotforemulationswithscreens composedaspages,suchanIBM TN3270termi as ablockoftext.Aswiththe The SELECTION BUFFER SELECTION BUFFER Example Comments Arguments See the from theactive sessionwindow. is selected.If the buffer,The entire contentsofthehistory displayed onthescreen, whichincludestheportion The The optional WINDOW WinHandle WinHandle SELECTION APPEND WINDOW argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular WINDOW WINDOW WinHandle commandselectstheentire contentsofthesessionwindow’s buffer history SELECTION clause includesthe clause isnotincludedinthecommand,selectionwillbemade command. command, thiscommandmakesaninvisibleselection. WINDOW keyword andthe WinHandle argument. - 3 Commands 455 or - SE argument. SELECTION function is used arguments, and if WinHandle EndLine ”) WINDOWHND and SCR1 (“SCR1”) keyword and the keyword command on an open window, the command on an open window, StartLine . WINDOW SCR1 SELECTION WINDOW WINDOWHND command the proper command the proper for window for window clause includes the command prints a blank page. command prints the current selection as established by the selection as established by current command prints the clause is not included in the command, the selection in the active session session selection in the active clause is not included in the command, the argument is an integer identifying a particular argument is an integer session window. WINDOW WinHandle WINDOW commands. SELECTION clause directs DCS to print the selection in a particular DCS to print the selection session window. clause directs WINDOW WinHandle SELECTION 0 23 WINDOW WINDOWHND (“ SELECTION 0 23 WINDOW WINDOWHND SELECTION PRINT WINDOW WINDOW WinHandle In this example: In The sent to the printer. are all 24 lines in the session window the to return The the gave you If the executed DCS has not previously LECTION PRINT the If will be printed. window WINDOW WinHandle The optional The Comments Example Arguments SELECTION PRINT SELECTION PRINT SELECTION The SELECTION BUFFER SELECTION PRINT SELECTION 456
DCS Script Language Reference SELECTION SAVE works only withaselectionmadethe The SELECTION SAVE FileName SELECTION SAVE Arguments Example Comments FileName DCS saves theentire contentsofthesessionwindow tothefile In thisexample: If awriteerror occurs,theResult systemvariable containsastringdescribingtheerror. window issaved tothefile. If the The The The optional WINDOW WinHandle rated by twoormore consecutive spaces willbesaved astabdelimited. The optional TABLE (“”) isspecified,aprompt forafilenameappears. tion. The The WINDOW WinHandle FileName WINDOW SELECTION SAVE“TERMDATA.TXT” SELECTION 024 FileName WINDOW TABLE argument isastringspecifyingthenameoffileinwhichtosave theselec clause directs sessionwindow. DCStosave aselectionmadeinparticular argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular commandsaves thecurrent selectiontothespecifiedfile.Thiscommand clause isnotincludedinthecommand,selectioncurrent session argument mustspecifyavalid filenamefor your system. If anullstring keyword directs DCStosave thedataintabularformat.Allsepa clause includesthe TABLE WINDOWWinHandle SELECTION WINDOW or SELECTION BUFFER keyword andthe TERMDATA.TXT WinHandle commands . argument. . - - 3 Commands 457 - com argument. WinHandle SELECTION BUFFER or keyword and the keyword SELECTION WINDOW clause includes the clause directs DCS to send the selection in a particular session window DCS to send the selection in a particular session window clause directs command sends the selected text to the active DCS session window. This DCS session window. selected text to the active command sends the clause is not included in the command, the selection in the current window window selection in the current clause is not included in the command, the argument is an integer identifying a particular argument is an integer session window. WINDOW WinHandle WINDOW WINDOW WINDOW SELECTION 0 0 SELECTION SEND WINDOW WinHandle the first line of data in the window is sent to the remote system. is sent to the the first line of data in the window The The optional system connected to that session. to the remote the If system. will be sent to the remote this example: In WINDOW WinHandle The optional Comments Example Arguments SELECTION SEND SELECTION SEND SELECTION The made with the only with a selection command works mands. SELECTION SEND SELECTION 458
DCS Script Language Reference SEND The WinHandle SEND SEND Arguments (Row, Col) ment asasinglenetwork packet. The optional ONEPACKET string shouldonlybeusedinspecialsituations. the screen buffer. Thisdoesot requires thehostto readbackthemodified protectedfields.This The optionalNOPROTECT keyword ignores protected areas ofthescreen textto andinserts NOPROTECT The String optional A carriagereturn isautomaticallysentfollowing thecontentsof NOCR ized orcomplexinteractions. These coordinates are especiallyusefulwhenconnectingto remote systems requiring special included inthecommand,textisplacedwindow atthecurrent starting cursorposition. the window isrow 9(zero), andthefirstcolumnis0(zero). If coordinates are not set indicatestherow andcolumnofwhere toplacethetextinawindow. Thefirst row in These argumentsapplyonlytoblockmodeemulations.Theoptional (Row, Col)NOCR command sendstexttoanopenDCSsessionwindow. String Note: Note: Also see: Note: NOCR argument containsthetexttosendawindow.
ONEPACKET This stringisapplicableonlyforIBM3270/5250emulations. apply. For IBM TN3270 emulations,theoptional remove the{NEWLN}. {NEWLN} totheendofalineinplacecarriagereturn. Use For IBM TN3270 emulations, keyword directs DCSnottoappendacarriagereturn tothe Rules forSending Special Strings attheendofthiscommanddescription. String keyword requires DCStosendthecontentsofString argu NOPROTECT ONEPACKET WAITECHO WINDOW the SEND command automaticallyappends ONEPACKET String (Row, Col) keyword doesnot argument. The String NOCR coordinate argument. to - - 3 Commands 459 - - , 2) d argument. , and c , b , a WinHandle keyword does not ap keyword . argument are sent. argument are h WAITECHO WAITECHO String , and keyword and the keyword g , f , e WINDOW command transmits 1) the letters SEND keyword sends the string argument one character at a time, waiting sends the string argument one character keyword clause includes the clause is not included, the text is sent to the active session window. clause is not included, the text is sent to the active argument is an integer identifying a particular session window. clause sends the string to the window of a particular remote system. of a particular remote clause sends the string to the window For IBM TN3270 emulations, the optional TN3270 emulations, IBM For ply. WAITECHO WAITECHO WINDOW command sends the text to the active window, just as though you had typed the just as though you window, command sends the text to the active $String = “abcd^@efgh” Send $String Send NoCR “^@” Note: WINDOW SEND WinHandle WINDOW If a null character is embedded in a string, the null character is sent with the other characters a null character is embedded in a string, the If sequence of script commands: consider the following example, in the string. For The The the keyboard. text string from letters and 3) then, the then, the null character, the If The The follows: must transmit a null character as You repre The string ^@ return. without a carriage This script example transmits a null character sents a null character. WAITECHO The optional the next character in the sending echoes back each character before system until the remote until all characters in the continues string. This process WINDOW WinHandle The optional continued Comments SEND, SEND, 460
DCS Script Language Reference SEND, Example continued plus character. TheEscapeand Plus charactersare concatenated(joined)togetherintoastring the first In thisexample: followed by an{ENTER}key. in thecurrently active sessionwindow. When itappears,thestring“ After the pended toanylinetransmittedwiththe the remaining characters.Note that with aremote system.DCSwaitsfortheremote system tobecomeready againbefore sending {WAITXC}The string {WAITXC} isaspecialstringinDCS. inastringindicatestransmission waits fortheXClock todisappearatwhichoccurrence another{ENTER}keyissent. a connectiontoremote IBM3270systemismade,an{ENTER} keyissent,andthescript In thisexample: When thestringappears,“ the scriptwaitsforstring“ the specifiedphonenumberisdialed,a[Ctrl]+[C]withoutcarriage return issent,andthen In thisexample: string. Aftersendingthecharacterstring,inputmodereturns toitsprevious setting. metakeyensuresthe {insertoff} before thattheinputmodeisOvertype sendingthecharacter In thisexample: sends thestring,followed by acarriagereturn character, toaremote system. barorpipesymbol).The with theconcatenationoperator(thevertical SEND NOCR“secretcode{ENTER}” WAIT STRING“Enterpassword:“ SEND NOCR“{ENTER}{WAITXC}{ENTER}” CONNECT SEND “secretcode” WAIT STRING“Enterpassword:“ SEND NOCR“^C” DIAL “5551234” SEND “{insertoff}18934 SEND CHR(27)|(43) CHR SEND function returns theescapecharacter, andthesecond command, thescriptwaitsforstring“ Enter password: NOCR secretcode SEND suppresses theautomatic{NEWLN} normallyap command. ” followed by acarriagereturn issent. ” toappearinthesessionwindow. Enter password: CHR secretcode SEND function returns the command then “toappear ” issent, - 3 Commands 461 ] character, and then ] character, ENTER is sent to the host starting at from ID 1 is made. The user’s 1 is made. The user’s ] character, a user’s password, an [ password, a user’s ] character, SCR TAB ] character to the remote system. ] character to the remote ENTER SEND (2,12) NOCR "text" NOPROTECT SEND (1,%row);column 1 row 2 SEND (1,%row);column 1 row %row=%row+1 or INCREMENT %row 3 SEND (1,%row);column 1 row %row=%row+1 or INCREMENT %row | $Password | \ “{ENTER} SEND NOCR $UserID | “{TAB}” {WAITXC}PROFS{ENTER}” %row=1 SEND (1,%col) SEND (1,%col+1) SEND (1,(%col+1)) %row=1 1 SEND (1,%row);column 1 row %row=%row+1 or INCREMENT %row CONNECT “SCR1” %hwnd CONNECT “SCR1” %hwnd “userid{ENTER}” WINDOW SEND NOCR (20,10) Password: “ WAIT STRING “Enter WINDOW %hwnd SEND NOCR “password{ENTER}” In this example: In area. if this is a protected buffer at position 2,12, even A text string is inserted in the screen In this example: In ID, a [ DCS sends a user’s command sending the PROFS that information before system to process waits for the remote and an [ When referencing a row or column, a variable or constant must be used, i.e., an expression must be used, i.e., an expression or constant or column, a variable a row When referencing example: cannot be used. For re-written as: could be is not supported. above The example In this example: In session A connection to host DCS sends the password for a password, system prompts the remote 20, column 10. After position. cursor starting the current from with a carriage return continued SEND, SEND, 462
DCS Script Language Reference SEND, continued or perform actions.Thefollowingor perform tablesummarizes theavailable specialstringsoractions: Use specialstringsenclosedinbraces{}orpreceded by acaret (^)symboltosendspecifickeys Rules forSendingSpecialStrings wait forhostreadystate turn off Insertmode specific key set theresultstring launch anapplication {^$Pscript.dct} launch ascript ^ { or Action Key
sends theremainderofcharacters. DCS waitsfortheremotesystemtobecomereadyagainbeforeit Use thespecialstring{WAITXC} “{insertoff}character string internal spacesmustbepreserved. The keylabelyouencloseinbracesisnotcasesensitive,but be enclosedwithinbraces{}andsentasametakey. mapping optionsarea. Any stringlistedinthe tab. Clickthe erties To obtainthekeylabelfor aspecifickey, openthe “{key label} string onlyforthatscript.Itdoesnotaffect anyotherscript. Setting theresultstringviaaSENDcommandaffects theresult {^$Rresult string} ‘^$Rresult string‘ {^$Xapplication.exe parameters} ‘^$Xapplication.exe parameters‘ ‘^$Pscript.dct ‘ {^$Escript.dct} ‘^$Escript.dct ’ “^^ “{{“ String dialog.Selectanemulationandthenselectthe Note: Edit or or or Tandem 6530emulations. Applies onlytoBlockModesforIBM TN3270 and or
or button andthenselectthe or Terminal Terminal Session Prop Keyboard tab inthe tab may - 3 Commands 463 argument is a numeric specifying the length the break is to be sent, where one is to be sent, where specifying the length the break argument is a numeric
command sends the break signal for a specified number of milliseconds. signal for a specified number of break command sends the SEND “password” SENDBREAK 30 This command does not apply to IBM TN3270 emulations. not apply to IBM This command does DelayUnits In this example: In system after sending the password. is sent to the remote a 30 millisecond break DelayUnits The millisecond. delay unit equals one Note: Example Arguments SENDBREAK SENDBREAK DelayUnits SENDBREAK The SENDBREAK 464
DCS Script Language Reference SET The SET Variable Source SET Arguments Example Comments Variable numeric ( are equivalent. Thenumeric variable These twoexamples: the stringvariable $nameisassigned thestringArnold Wilson. In thisexample: The able. Source argumentmustbeofthesametype(string,numeric,orBoolean)asspecified vari The Source numeric variable, orBooleanvariable) tobeassigned. The command assignsthevalue ofthe SET Source Variable %yearprofits =(%income-%expenses)*12 SET %yearprofits(%income-%expenses)*12 SET $name“ArnoldWilson” command isequivalent tothe assignment (=)operator. %income -%expenses argument specifiestheexpression whosecontentsare assignedtothe variable. The argument specifiesthenameandtypeof variable (eitherastring variable, Source %yearprofits ) multipliedby 12. argument tothespecified variable. is assignedthevalue ofthecomplex - 3 Commands 465 -
command is a true SET WINDOWTITLE SET command end when the script SET APPTITLE SET SET APPTITLE SET command overrides the default title and displays the character sequence the default title and displays command overrides command, the effects of the command, which is a compiler directive and requires a literal string (char and requires command, which is a compiler directive command sets the title caption bar of the application window. command sets the title TITLE argument is a string specifying the text to display in the title bar of the application argument is a string specifying the text to TITLE SET APPTITLE “Mail System for “ | $username SET APPTITLE “Mail System For scripts that produce multiple session windows in a single execution of the DCS of the DCS in a single execution multiple session windows scripts that produce For use the multiple application windows, application rather than re-sized. are title is lost when session windows command. Otherwise, the session window Name SET APPTITLE SET In this example: In the (The default title of the title bar. in the application window Corporation” Acme System “Mail is DCS.) application window The window. the Unlike the not a string variable), acters within quotation marks, any format. of expression script command and can accept a string As with the to the default. reverts window When the script ends, the title of the application terminates. Name Note: Comments Example Arguments SET APPTITLE SET SET APPTITLE SET APPTITLE Name The SET APPTITLE 466
DCS Script Language Reference SET ATTRIBUTES The SET ATTRIBUTESFileName Attributes SET ATTRIBUTES Arguments Example FileName 3 (three)), DCSsetstheattributestoHidden andSystem (thesum oftheirvalues is6(six)). In thisexample,iftheattributesof In thisexample: Specifying an You mayspecifythe The Attributes must specifyavalid filenamefor your system. The Attributes FileName SET ATTRIBUTES$file6 IF ATTRIBUTES($file)=3 64 32 16 Subdirectory 4 FileAttribute 2 1 Value Attributes argument isanumericspecifyingthefileattributesasshown onthetablebelow. argument isastringspecifyingthenameoffile.The commandmodifiesthefileattributesofspecifiedfile. Attributes Compressed File Archived File System File Hidden File Read-only File argument of0(zero) removes allattributesfrom thefile. argument asasumofthevalues oftheattributeslistedbelow. $file are read-only andhidden(thesumoftheirvalues is FileName argument 3 Commands 467 - argu option option is Boolean Autoscroll Autoscroll dialog. Autoscroll to Cursor Autoscroll Session Properties Session command instead of this command. tab of the command determines whether to scroll the session window the session window whether to scroll command determines Displays Displays argument evaluates to TRUE, scrolling occurs automatically when the occurs automatically when scrolling TRUE, to argument evaluates DISPLAYCONFIG tab of the Boolean argument is a Boolean value specifying whether or not the specifying value argument is a Boolean Cursor sub Cursor SET AUTOSCROLLTOCURSOR TRUE Boolean - Where possible use the Where enabled. If the enabled. If the If outside the visible part of the session window. emulation cursor is moved is turned off. of the session window scrolling automatic to FALSE, ment evaluates visible in bars are scroll is applicable only when the appropriate scrolling or horizontal Vertical the session window. or unchecking the This command has the same effect as checking on the Boolean The
Example Comments Arguments SET AUTOSCROLLTOCURSOR SET SET AUTOSCROLLTOCURSOR Boolean SET AUTOSCROLLTOCURSOR The part outside of the visible of the session position each time the cursor moves to the emulation cursor window. Auto Scroll to Cursor option SET AUTOSCROLLTOCURSOR Figure 3.1 of sub-tab Cursor tab in the Displays Proper the Session ties dialog 468
DCS Script Language Reference session window Autosize fonttofit dialog Session Properties Displays tabinthe Font sub-tabofthe Figure 3.2 SET AUTOSIZE fit sessionwindow The Boolean SET AUTOSIZE SET AUTOSIZE Arguments Comments
Note: Where possibleusethe Font The Boolean Boolean isenabled.If theexpression evaluates toFALSE, This commanddoesnotapplytoIBM TN3270emulations. checkbox onthe commandhasthesameeffectascheckingorunchecking argument isaBooleanexpression. If theexpression evaluates to TRUE, DISPLAYCONFIG Displays tab ofthe commandinsteadofthiscommand. Session Properties Autosize Font isdisabled. dialog. Autosize Font to Autosize 3 Commands 469 key to move key to move [BACKSPACE] evaluates to TRUE). If the remote the remote If TRUE). to evaluates OFF command causes the [BACKSPACE] key to erase, or delete, key to erase, [BACKSPACE] command causes the #HostSupPortsDestructBack key is pressed. key to a non-destructive mode, allowing the key to a non-destructive mode, allowing key erases, or deletes, characters as the cursor moves from right to left. If the to left. If right from moves key erases, or deletes, characters as the cursor argument is a Boolean expression. If the expression evaluates to TRUE, the TRUE, to evaluates the expression If expression. argument is a Boolean BackSpaceDestructive If #HostSupportsDestructBack SET This command does not apply to IBM TN3270 emulations. not apply to IBM This command does Boolean [BACKSPACE] [BACKSPACE] [BACKSPACE] [BACKSPACE] [BACKSPACE] system does support a destructive backspace, DCS uses the Boolean value OFF ( FALSE) to set system does support OFF ( FALSE) a destructivethe Boolean value backspace, DCS uses the without deleting them. characters over the cursor backward expression evaluates to FALSE, the cursor moves over characters without deleting them when over the cursor moves to FALSE, evaluates expression the this example: In supports system checking to see if destructive backspaces (by DCS checks to see if the remote the Boolean variable Boolean The Note: Example Arguments SET BACKSPACEDESCTRUCTIVE SET SET BACKSPACEDESTRUCTIVE Boolean SET BACKSPACEDESTRUCTIVE The right to left. from moves characters as the cursor SET BACKSPACEDESTRUCTIVE 470
DCS Script Language Reference SET BACKSPACEKEY when thebackspacekeyispressed, orinsteaddeletesthecharacteratcurrent cursorlocation. The SET BACKSPACEKEY Keyword SET BACKSPACEKEY Arguments Example Note: while the the charactersentby pressing the In thisexample: The Keyword Keyword This commanddoesnotapplytoIBM TN3270emulations. SET BACKSPACEKEYBACKSPACE PERFORM gather_data SET BACKSPACEKEYDELETE LOAD “MAILSET” DELETE BACKSPACE Keyword Action gather_data argument isspecified by oneofthefollowing keywords: commanddetermineswhetherthecursormoves from righttoleftsent Directs DCStosendadeletecharacterwhenthebackspacekeyispressed. pressed. Directs DCStosendabackspacecharacterwhenthekeyis routine isperformed. [BACKSPACE] keyischangedtoadeletecharacteronly 3 Commands 471 command changes the baud rate of the selected communications port. baud rate of the selected communications command changes the argument is a numeric specifying the desired baud rate. specifying the desired argument is a numeric 28800 38400 57600 115200 SET BAUDRATE 19200 DIAL “5551234” 110 300 600 1200 2400 4800 9600 14400 19200 This command does not apply to IBM TN3270 emulations. not apply to IBM This command does Rate In this example: In dialing the phone number. the baud rate is set to 19200 before The following baud rates are available : available baud rates are The following Rate The Note: Example Arguments SET BAUDRATE SET SET BAUDRATE Rate SET BAUDRATE The SET BAUDRATE 472
DCS Script Language Reference SET BINARYTRANSFERPARAMS file transferprotocol. The ActionKeyWord… SET BINARYTRANSFERPARAMS OptionKeyWord ActionKeyWord SET BINARYTRANSFERPARAMS Arguments Note: defines thesettingforaparameterindicated by the transferprotocol. The the nameofaparameterinsettingsdialogforbinary The OptionKeyWord ActionKeyWord OptionKeyWord ZEXISTING ZmodemFileExists ZERRORCHECK ZmodemErrorCheck ZAUTOSTART ZmodemAutoStart Keyword Action Note: This commanddoesnotapplytoIBM TN3270emulations.
Though allofthefollowing keywords are optional,theSET clauses (inanyorder): FERPARAMS and ActionKeyWord commandrequires atleastoneormore ofthefollowing keyword commandsetstheparametersforactive session’s binary argumentsformaclause. Exists groupboxoftheZModem Settings dialogbox. the sameeffect asselectingaradio buttonintheIfFile PROMPT, OVERWRITE, SKIP. clause has This keyword should beoneofthefollowingkeywords:RESUME, DCS istransferring. The ZmodemFileExists argument of afileonthereceivingsystemmatchesthat handle afileonreceivingsystem,whenthename The optionalZEXISTINGclausetellsDCShowto box. group boxoftheZModemSettingsdialog Checking the sameeffect asselectingaradiobuttonintheError keywords: CRC32,orCRC16. This keywordclausehas mErrorCheck argumentshouldbeoneofthefollowing checking methodforZModemtransfers. The Zmode The optionalZERRORCHECKclausesetstheerror Session Propertiesdialog). ZModem dialog(foundintheFile Transfers tabofthe effectopposite oftheDisable AutoStart checkboxinthe SEND BINARY command. This keywordclausehasthe option intheSessionmenuorascriptcontainsFILE will transferafileonlywhenyouactivatetheSendFile value. IfZmodemAutostartevaluatestoFALSE, DCS OFF, NO,andFALSE evaluatetoafalseBoolean download auto-startsequence. The Booleankeywords fers afileautomaticallywhenitreceivesZModem If ZmodemAutostartevaluatesto TRUE, DCStrans ON, YES, and TRUE evaluatetoatrueBooleanvalue. Boolean expressionorkeyword. The Booleankeywords The ZmodemAutostartargumentshouldevaluatetoa load auto-startsequencefromtheremotesystem. transfer afilewhenDCSreceivesZModemdown optional ZAUTOSTART clause indicateswhetherto When DCSisapplyingtheZModemprotocol, OptionKeyWord . OptionKeyWord OptionKeyWord BINARYTRANS ActionKeyWord relates to - - - -
3 Commands 473 continued ACTION clause sets the time-out options The optional ZTIMING argument The ZmodemTiming for ZModem transfers. keywords: STANDARD, should be one of the following as has the same effect This keyword clause or LOOSE. Constraints group Timing in the selecting a radio button dialog box. box of the ZModem Settings command instead of this command. command instead of XFERCONFIG
SET BINARYTRANSFERPARAMS ZEXISTING OVERWRITE SET BINARYTRANSFERPARAMS ZEXISTING KEYWORD ZTIMING ZmodemTiming This example: ZModem. receiving system, when transferring files via on a exists a file that already overwrites Wherever possible, use the possible, Wherever Example Comments SET BINARYTRANSFERPARAMS, SET BINARYTRANSFERPARAMS, 474
DCS Script Language Reference SET BINARYTRANSFERS for asession. The SET BINARYTRANSFERS Protocol SET BINARYTRANSFERS Arguments Example Comments Protocol ZModem isestablishedasthefiletransferprotocol before afiletransfer. performing In thisexample: command. To configure theparametersforspecifiedfiletransfer protocol,usethe sion window. If the The The optional WINDOW WinHandle The The WinHandle Protocol Protocol WinHandle FILE SENDBINARY“SESCRIPT.DCT” SET BINARYTRANSFERSZMODEM KERMIT ZMODEM YMODEM XMODEM IXF IND$File WINDOW argument isspecified by oneofthefollowing keywords: transferprotocol.argument isakeyword specifyingthebinary argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular argumentisnotincluded,thetransferprotocol isappliedtotheactive ses clause includesthe command sets the binary filetransferprotocol orhostenvironment commandsetsthebinary WINDOW WinHandle WINDOW keyword andthe WinHandle XFERCONFIG argument. - 3 Commands 475 - command instead of this command. DISPLAYCONFIG DISPLAYCONFIG command specifies the total number of 80-column lines to be reservedbe the total number of 80-column lines to command specifies for argument is an integer specifying the number of lines to reserve.argument is an integer DCS always SET BUFFERLINES 200 Lines In this example: In a history buffer consisting of 200 lines is established. value of 25 is used. value The default history is 100 lines. buffer size is not enough memory DCS includes as many size, there If to allocate a buffer of the desired the buffer size You may increase memory allocating available lines as possible by to the buffer. to a maximum of 9,999 lines. His the number of historyThis command has the same effect as selecting buffer lines in the dialog. Properties tory section of the Session tab in the Displays possible, use the Wherever Lines The a number less than 25 is specified, a default If in the session window. displays at least 25 lines Example Comments Arguments SET BUFFERLINES SET SET BUFFERLINES Lines SET BUFFERLINES The in block mode. not It only applies to emulations that are and historythe session window buffer. SET BUFFERLINES 476
DCS Script Language Reference SET CARRIERDETECT The SET CARRIERDETECTBoolean SET CARRIERDETECT Arguments Example Comments Note: DCS establishesthemodemtypeandcarrierdetectflagbefore attemptingtodial. In thisexample: is lostandthecarrierdetectflag FALSE, DCSmusthangupbefore dialingagain. DCS willautomaticallydetectcarrierlossonlyiftheflagis TRUE. If thecarrier present. carrier ispresent. If theBooleanevaluates toFALSE, DCSlogicallydeterminesifthecarrieris If theBooleanevaluates to TRUE, DCSusesthemodem’s carrierstatustodetermineifthe evaluate to FALSE. words ON, YES, and TRUE evaluate to TRUE. TheBooleankeywords OFF, NO,and FALSE The Boolean Boolean DIAL “5551234” SET CARRIERDETECTTRUE SET MODEMHAYES This commanddoesnotapplytoIBM TN3270emulations. argument isspecified by aBooleanexpression orkeyword. TheBooleankey commandsetsthecarrierdetectflag. - 3 Commands 477 - routine is performed. routine The display_data command specifies the number of columns in the session window, where there is there where the number of columns in the session window, command specifies argument must be a valid column width value for the emulation. The value is typi for the emulation. The width value column valid argument must be a SET COLUMNS 132 PERFORM display_data SET COLUMNS 80 Integer standard 80-column mode is then restored. 80-column standard This command applies to all emulations that supportThis command applies to all emulations variable column width. this example: In the DCS switches to 132-column mode while Integer The 132. cally the integer 80 or Comments Example Arguments SET COLUMNS SET SET COLUMNS Integer SET COLUMNS The one character per column. SET COLUMNS 478
DCS Script Language Reference SET CONNECTION tact FutureSoft. information aboutthird DLLsandaboutcreating party acommunicationsconnectorforDCS,con connects toaremote system.ThiscommandcanalsoloadaDLLcreated by athird party. For further This commandallows you tospecifywhichtypeofcommunicationsconnectorDCSuseswhenit SET CONNECTIONConnector Arguments Note: string. For example,ifaconnector neededthree that setting,butthe tor each of theaddress, you mustuseacharacterotherthanperiod(possibly asemicolon)toseparate oftheaddress.rate parts Theaddress couldbea address ofanodeon TELNET network commonlyincludesnumberswithperiodstosepa ic, anddoesnotappearinany In thecommandstringdescription, CommandPhrase SeparatorSeparator... rator character: Each commandstringconsistsofaphraseornumberphrases separatedby auniquesepa specific tothecommunicationsconnectoranditsDLL. be passedtothecommunicationsconnectorduringitsinitialization.Thesecommandsare The optional Command table: DCS are by default. locatedintheConndirectory Valid stringsare shown inthefollowing The argumentcanalsospecifyaDLLcontaining valid DCSconnector. ConnectorDLLsfor The Connector must follow each Connector CommandPhrase * Microsoft SNA Server* Telnet Meridian LAT32 Modem Direct Serial Connector String This commanddoesnotapplytoIBM TN3270emulations. available onlyinappropriateClientOptionpackage Command argument isastringspecifyingthenameofcommunicationsconnector. Separator CommandPhrase from other argument isastringspecifyinganyoptionalcommandsthatshould Command WINDOWWinHandle CommandPhrase for that FMIDLL* or TELNET WINSOCK MERDNLAT COMTAPIor TAPI COMDIR Separator CommandPhrases CommandPhrase
. If you omitaphrase,DCSusesdefaultvalue for
is asinglecharacter, whichisnotalphanumer CommandPhrase CommandPhrases specifiedforaconnector. For example,the
inthecommandstring.A muststillappearinthecommand , but since a period is part , butsinceaperiodispart , butyou wanttousea Separa - - - - - 3 Commands 479 - - - ” us Not Avail n argument. Command MYHOST argument might argument WinHandle argument is an integer n Command Command may be 1, 2, 3, 4, 5, 6, 7, 8, or 9. If n , the keyword and the keyword which specifies a communications port. The which specifies a communications port. value of DCS the port is not valid for your computer, displays the message “COM Port able” in a dialog box. host name located in your Hosts file or the In ternet protocol address of the remote system. The Port argument is an integer specifying to connect. port to which you wish TCP/IP the Unless you are connecting to a specialized device, the port should be set to 23. The COM clause directs DCS to use a serial The COM clause directs DCS to use a serial communications port as the communications The connector. The HostAddr argument indicates either a WINDOW command (rather than the optional CommandPhrase . CONNCONFIG Separator clause includes the continued argument is an integer identifying a particular child window. WINDOW n SET CONNECTION “WINSOCK” “MYHOST;23;”
Action CommandPhrase COM WINSOCK “HostAddr Separator Port Separator” In this example: In “CommandPhrase1;;ComandPhrase3;” a semicolon is the WinHandle Wherever possible use the Wherever you specify with this command. the connector argument) to configure this example: In system named “ WINSOCK and connects to the remote the connector is set to ing port 23. WINDOW WinHandle The optional The session window. handle is not specified, the command affects the active window a If Below is a list of valid command phrases and keywords. is a list of valid Below default or previous setting for the second setting for previous default or appear as follows: you If a maximum of 254 characters. like all strings in DCS may have The command string, unpredictable. are this limit, the results exceed Comments Example SET CONNECTION, SET CONNECTION, 480
DCS Script Language Reference SET CONNECTMESSAGE ConnectMessage systemvariable. The SET CONNECTMESSAGEText SET CONNECTMESSAGE Arguments Example Comments Note: comes theargumentfor DCS placesthetextSuccess inthe In thisexample: Compare withthe The Text Text SET $NewMessage =“ This commanddoesnotapplytoIBM TN3270emulations. argument isthestringdisplayed whenaconnectionismadetoremote system. ConnectMessage$NewMessage CONNECTMESSAGE commandchangesthecharactersinmessagecontained SET CONNECTMESSAGE SUCCESS $NewMessage ” function. stringvariable. Thestring variable be command. - 3 Commands 481 command changes the value of the ConnectResult system variable. the ConnectResult of value command changes the No Carrier Modem Error No Dial Tone No Answer User-defined Error ConnectResult () “EndScript” “CallAgain” ConnectResult 99 argument is an integer which the command places into the ConnectResult system which the command places into the ConnectResult argument is an integer Switch End Dial SWITCH Case 6: SET PERFORM Case 7: PERFORM LEAVE Value Value 0 Success 3 Modem State 4 6 7 Busy 8 99 This command does not apply to IBM TN3270 emulations. not apply to IBM This command does Num DCS checks the ConnectResult system variable after dialing. If the value of the variable is six variable of the the value after dialing. If system variable DCS checks the ConnectResult and ends the script; however, error to a user-defined ConnectResult (no dial tone), DCS resets (the line was busy), DCS calls the number again. is seven of the variable if the value In this example: In a specific modem state. Num The to corresponds below, values listed in the table which must be one of the The integer, variable. Note: Example Arguments SET CONNECTRESULT SET SET CONNECTRESULT Num SET CONNECTRESULT The SET CONNECTRESULT 482
DCS Script Language Reference SET CURSOR The SET CURSORDisplay SET CURSOR Arguments Example Comments Display DCS changestheshapeofcursortoablock. In thisexample: Wherever possibleusethe SOR ON character, butdoesnotturnthedisplaytoON.Thismustbedonewithaseparate If thecursorissettoOFF, settingtheshapetoBLOCK orUNDERLINEchangesthecursor The Display SET CURSORBLOCK Setsthecursor shapetoanunderscorecharacter UNDERLINE BLOCK OFF ON Keyword Action command. commandsetstheshapeandstateofcursorinasessionwindow. argument isspecified by oneofthefollowing keywords: Sets thecursorshapetoablock Turns off thecursordisplay Turns onthecursordisplay DISPLAYCONFIG commandinsteadofthiscommand. SET CUR - 3 Commands 483 . argument may be Integer UTILITY.DCT command sets the number of data bits DCS uses during serial transmission. of data bits DCS uses during serial command sets the number argument specifies the desired number of data bits. The desired argument specifies the 4 5 6 7 8 SET DATABITS 7 ;connect to a remote system SET PARITY EVEN ;configure the remote system SET BINARYTRANSFERS KERMIT kermit transfer protocol ;to receive a file via the FILE SEND BINARY “UTILITY.DCT” This command does not apply to IBM TN3270 emulations. not apply to IBM This command does Integer communications settings are established before sending the file established before communications settings are In this example: In Integer The values: one of the following Note: Example Arguments SET DATABITS SET SET DATABITS Integer SET DATABITS The SET DATABITS 484
DCS Script Language Reference SET DDETIMEOUT struct The SET DDETIMEOUT SET DDETIMEOUT Arguments Comments , Request Seconds The above commandstocomplete.Thedefault value is20seconds. The optional ERROR , Table Reply Seconds function issetto TRUE iftheDDEcommandtimesout. S commandsetsthetimeoutperiodforfollowing DDEcommands: econds , Poke argument isanintegeridentifyingthetimeperiodtowaitfor , Table Poke In - 3 Commands 485 - function.
STR command in conjunction with the
argument specifies the desired number of decimal places. desired argument specifies the
command specifies the number of places for string representations of real numer of representations the number of places for string command specifies DECIMAL SET DECIMAL 2 DISPLAY STR (1000*.0875) Numeric This command does not affect the internal precision of the real numerics, only the format. real numerics, only the of the precision This command does not affect the internal the Use this example: In in the session window. the string 87.50 is displayed Numeric The Example Arguments Comments SET DECIMAL SET SET DECIMAL Numeric SET DECIMAL The ics. SET DECIMAL 486
DCS Script Language Reference SET DEFAULTSESSIONHANDLE system variable. The SET DEFAULTSESSIONHANDLE WinHandle SET DEFAULTSESSIONHANDLE Arguments Example Comments WinHandle it isnow thedefaultsessionforanycommandwhichdoesnottargetaspecificwindow. is the defaultsessionwindow handleforthis scriptissettothehandleofwindow whosetitle In thisexample: active sessionwindow). which donottargetaspecificsessionwindow (ratherthanhavingthosecommands targetthe however, you maywishto specifyadefaultsessionwindow asthetargetofthosecommands In manycases,thedefaultsessionwindow istheactive sessionwindow. With multiplesessions, session window. The VT220 WinHandle SET DEFAULTSESSIONHANDLE%SessHandle %SessHandle =WINDOWHND(“VT220”) . In thisexample, VT220 mayornotbethecurrently active session.Regardless, argument isanintegerexpression specifyingthewindow handleofthedefault commandassignsanintegertotheDefaultSessionHandle 3 Commands 487 - - UPLOAD function directory on function returns function returns TASK for the specified file for the specified file ERROR
ERROR DCSERIES\TASK function returns TRUE if the specified TRUE function returns ERROR keyword is included, the keyword command to create a directory that doesn’t exist by includ exist by a directory that doesn’t command to create Path CREATE CREATE keyword directs DCS to create the specified directory if it does not to create DCS directs keyword CREATE CREATE argument must specify a valid directory system. argument must specify a valid for your keyword. This allows you to create a directory direc and make it the default you to create This allows keyword. SET DIRECTORY SET keyword is not included, the keyword command specifies where to maintain the file directory where command specifies Path CREATE CREATE argument specifies the file type. It is specified by one of the following keywords: the following by one of It is specified file type. argument specifies the argument is a string specifying the path in which to maintain the indicated type of argument is a string specifying the path in . If this directory does not exist, DCS creates it. this directory . If does not exist, DCS creates CREATE CREATE SET DIRECTORY TASK CREATE “C:\DCSERIES\TASK” $TASKDIR = “C:\DCSERIES\TASK” CREATE DIRECTORY $TASKDIR SET DIRECTORY TASK $TASKDIR DNLOAD MAPS MEMO SETTINGS SCRIPT CREATE CREATE C: Path Type Type DCS is directed to maintain all executable scripts in the scripts in to maintain all executable DCS is directed drive this example: In and then sets the directory as the default storage the directory C:\DCSERIES\TASK creates location for script task files. directory the does not exist. If If the directory exists. already or if it already if the specified directory cannot be created TRUE the directory leading to do not exist, the exists or if the subdirectories TRUE. returns can use the You ing the tory with a single command. this example: In CREATE The optional exist. Path The The directory. the If Type The Example Comments Arguments SET DIRECTORY SET SET DIRECTORY Type Type SET DIRECTORY The type. SET DIRECTORY 488
DCS Script Language Reference SET EMULATION The SET EMULATION Emulation SET EMULATION Arguments Note: If awindow handle isnotspecified,thecommandaffectsactive sessionwindow. The The optional WINDOW WinHandle are transferred emulation. tothenew The emulationisloadedwithdefaultsettings;noneofthesettings intheprevious emulation are installed. Valid stringsforthe includethosewhich byin theEmul default.Theemulationsfoundinthisdirectory directory also specifyaDLLcontainingvalid DCSemulation.Emulation DLLsforDCSare located The Emulation Emulation WinHandle * Client OptionEmulations Base ProductEmulations This commanddoesnotapplytoIBM TN3270emulations. Use theEMULCONFIGcommandtospecifyexactmodel. TN5250 IBM5250 IBM3287 TN3287 (printsession)* TN3270 IBM3270 Tandem 6530 HP 70092/94 AT&T 4425 Emulation Wyse 50/60 ATT605 Televideo*TV950 ANSI VT Series* AT&T 605/705* ADDSVP60 ANSI/TTY* ADDS Viewpoint/60 Emulation WINDOW commandselectsaterminalemulation. argument isastringspecifyingthenameofemulation.Thecan argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifying aparticular clause includesthe WINDOW WinHandle Emulation Tandem HP70094 ATT4425 String WYSE VT420 String WINDOW argument are shown inthefollowing table: keyword andthe
WinHandle argument. 3 Commands 489 - - function is used specifies which ses ACTIVE( ) command, or the session’s win command, or the session’s command. The SET EMULATION SET SET DEFAULTSESSIONHANDLE SET SET EMULATION SET continued command is used to specify the VT220 model type. command is used to specify the LOAD SET DEFAULTSESSIONHANDLE (ACTIVE()) SET EMULATION “VT420” EMULCONFIG “MODEL=vt220” SET EMULATION “VT420” SET EMULATION EMULCONFIG the DEC VT420 emulation is loaded for the current session. VT420 emulation is loaded for the current the DEC this example: In the script loads a new session. The sion will be the target of the Series, and the VT handle of the new is set to session. The emulation to obtain the window If the session whose emulation type you wish to set was loaded via script, a default session wish to set was loaded via script, a default type you the session whose emulation If using the before handle must be specified handle must be specified. dow this example: In Comments Example SET EMULATION, SET EMULATION, 490
DCS Script Language Reference SET FKEYSSHOW session properties file. session properties The SET FKEYSSHOWBoolean SET FKEYSSHOW Arguments Example Comments Boolean when thesessionfileisloaded,functionkeysare notautomaticallydisplayed. In thisexample: If the display thekeys(F1through F8) atthebottomofsessionwindow. By theuseofsessionfunctionkeyswillautomatically default,anyemulationwhichsupports evaluate to FALSE. words ON, YES, and TRUE evaluate to TRUE. The The Boolean Boolean load “session.ses” set fkeysshowoff argument isspecified by aBooleanexpression orkeyword. The evaluates to TRUE, DCSautomaticallydisplaysthesessiontoolbarbuttons. commandautomaticallydisplaysthesessiontoolbarbuttonswhenyou loada Boolean keywords OFF, NO,andFALSE Boolean key - 3 Commands 491 . send_data NONE command specifies the desired flow control method. control flow the desired command specifies argument is specified by one of the following keywords: of the following by one argument is specified SET FLOWCONTROL XONXOFF PERFORM send_data This command does not apply to IBM TN3270 emulations. not apply to IBM This command does HARDWARE XONXOFF Type Type HARDWARE flow control is equivalent to the RTS/CTS flow control. flow RTS/CTS to the is equivalent control flow HARDWARE this example: In performingroutine the before XON/XOFF is set to control the flow Type The Note: Comments Example Arguments SET FLOWCONTROL SET SET FLOWCONTROL Type SET FLOWCONTROL The SET FLOWCONTROL 492
DCS Script Language Reference SET KEEPPRINTCHANNELOPEN dows printchannelwhentheremote systemclosesanactive printjob. The SET KEEPPRINTCHANNELOPENKBoolean SET KEEPPRINTCHANNELOPEN Arguments Example Comments KBoolean mands sendsprinting control commands totheemulationand DCS. When thedataenterssession window, thecommandblockof WHEN STRING loads theDEC VT-220 emulationandopenstheprintchannel.Thescript thensetsupthree This example: keep allclosed,orsomeopenandothersclosed. you cankeeptheprintingchannelopenorclosedonasessionperbasis:allopen, considers theprintrequests from eachsessionasseparate Windows printingtasks;therefore, have more thanonesessionwindow, andifthe remote systemineachsessionisprinting,DCS requests from aremote systemtoappearasoneprintingrequest to Windows. However, ifyou The time theremote systemopenedorclosed print channel.In thiscase,ifDCSwere toopen andclose When aremote systemsendsprintercommandstoDCS,itmayrepeatedly ous printjob. printer resource, Windows issuesaformfeed to clearoutanyresidual printingfrom theprevi resource, useit,andthenrelinquish itto Windows. Between theclosingandopeningof The Windows printerisashared resource. Usually, Windows applicationsopentheprinter quishes the Windows printchannelwhenever theremote systemclosesitsprintjob. remote systemhascloseditsactive printjob. If theBooleanevaluates toFALSE, DCSrelin If theBoolean evaluates to TRUE, DCSkeepsthe Windows printchannelopeneven afterthe FALSE. YES, and TRUE evaluate to TRUE. TheBooleankeywords OFF, NO,and FALSE evaluate to The SET KEEPPRINTCHANNELOPEN KBoolean WAIT RESUME WHEN STRING3“ClosingPrint”PRINTCLOSE WHEN STRING2“StoppingPrint”DISPLAY “^[[4i” WHEN STRING1“StartingPrint”DISPLAY “^[[5i” SET KEEPPRINTCHANNELOPENON EMULCONFIG “MODE=VT220” SET EMULATION“VT420.DLL” argument isaBooleanexpression orkeyword. TheBooleankeywords ON, commandstowatchforincoming datafrom theremote system. commandspecifieswhetherDCSwill relinquish the Win commandmakesitpossibleforseparateprinting
the printchannel,you wouldwaste paper.
the Windows printerresource every WHEN STRING
open andclosethe com - - - - 3 Commands 493 - from the remote system, the script sends system, the script the remote from string ^[[4i (hexa , the script sends the , the script closes the Windows printer printer Windows , the script closes the continued Starting Print Starting Stopping Print Closing Print resource. When DCS receives the string receives When DCS and to the emulation. 1B 5B 35 69) to the session window the string ^[[5i (hexadecimal, emulation to send the requires sequence which escape VT-220 is the This character sequence system to a printer. the remote from data it is receiving string the When DCS receives escape VT-220 and to the emulation. This to the session window decimal, 1B 5B 34 69) data to the printer. sending from sequence stops the emulation string the When DCS receives SET KEEPPRINTCHANNELOPEN, SET KEEPPRINTCHANNELOPEN, 494
DCS Script Language Reference SET LOCALECHO The SET LOCALECHOBoolean SET LOCALECHO Arguments Example Comments Note: local echoisturnedonifaconnectionmade. In thisexample: ting. If theemulationallows you toturnonandofflocalecho,this commandwillaffectthatset The effectofthiscommanddependsontheterminalemulation youhave selectedforasession. strokes totheremote systemonly. as sendingthemtotheremote system.If theBooleanevaluates toFALSE, DCSsendskey If theBooleanevaluates to TRUE, DCSdisplayskeystrokes inthelocalsessionwindow aswell evaluate to FALSE. words ON, YES, and TRUE evaluate to TRUE. TheBooleankeywords OFF, NO,and FALSE The Boolean Boolean SET LOCALECHOTRUE IF CONNECT() DIAL $number This commanddoesnotapplytoIBM TN3270emulations. argument isspecified by aBooleanexpression orkeyword. TheBooleankey commandcontrols thedisplayoflocalkeystrokes. - - - 3 Commands 495 - command places into the NetID system vari the NetID command places into SET NETID SET subroutine to access sections of a network with the same to access sections of a network subroutine function. Call “NetUS” NETID “Hangup” “Call” “Call” argument is the string the argument is the string command changes the contents of the NetID system variable. system contents of the NetID command changes the . PERFORM SET NETID PERFORM . . . Set NetID “NetWorld” PERFORM . . This command does not apply to IBM TN3270 emulations. not apply to IBM This command does Text Text changes the NetID system variable before it connects to remote system. Changing the NetID system. Changing the NetID it connects to remote before variable system changes the NetID the allows system variable script commands. Compare with the Compare This script segment: Text The ID. examples of a network are or “Telenet” able. The strings “Tymnet” Note: Comments Example Arguments SET NETID SET SET NETID Text SET NETID The SET NETID 496
DCS Script Language Reference SET OUTGOINGCR ing carriagereturns. The SET OUTGOINGCROption SET OUTGOINGCR Arguments Note: The Option Option RF DirectsDCStoaddlinefeedsalloutgoingcarriagereturns. CR CRLF Keyword Action This commanddoesnotapplytoIBM TN3270emulations. argument isspecified by eitherofthefollowing keywords: commandspecifieswhetherlinefeedcharactersshouldbeaddedtooutgo Directs DCSnottoaddlinefeedsoutgoingcarriagereturns. - 3 Commands 497 - with no bit used for parity. Directs DCS to set the parity bit to make the overall parity of the character Directs DCS to set the parity bit to make the packet even. overall parity of the character Directs DCS to set the parity bit to make the packet odd. Directs DCS to set the parity bit to one. Directs DCS to set the parity bit to zero. used for data transmission, Directs DCS to expect all of the databits to be argument designates the type of parity to be used. It is specified by one of the follow by one of the is specified the type of parity to be used. It argument designates SET PARITY EVEN Keyword Action EVEN ODD MARK SPACE NONE This command does not apply to IBM TN3270 emulations. not apply to IBM This command does Type Type If you choose a binary data bits, and the parity is not set eight you requiring If transfer protocol setting during the transfer without permanently to NONE, DCS automatically adjusts this modifying it. This command: sets the parity option to even. Type The ing keywords: Note: Comments Example Arguments SET PARITY Type SET PARITY PARITY parity type. sets the desired command The SET SET PARITY 498
DCS Script Language Reference SET PASSTHROUGH driver. The SET PASSTHROUGH State SET PASSTHROUGH Arguments Example Comments Note: the Windows printerdriver. PSCRIPT.TXT In thisexample: Not allprinterdrivers are capableofpassthrough printing. expression mayalsobeused. The State State PRINT FILE“ SET PASSTHROUGH“TRUE” AUTO FALSE TRUE String Action Note: This commanddoesnotapplytoIBM TN3270emulations. argument mustbeoneofthefollowing strings:AUTO, 0(false).Astring 1(true), The State containsPostScript codewhichissentdirectly totheprinter, ratherthanto commanddetermineswhetherDCSsendsdatadirectly totheprinter argument, whichisastring,mustbeenclosedinquotes. If AUTO, thepassthroughmodewillbedeterminedasneeded. mand. The stringsNOorOFFmayalsobeused. printer selectedinthePrinterSetupdialogorPRINT OPENcom which formatsthefileforatypeofprinterandthensendsto If FALSE, DCSwillsendprintjobstothecurrentWindowsprinterdriver, used. if theprinterdriversupportsthismode. The strings YES orONmayalsobe If TRUE, DCSsends theprintjobstoprinterdriverinpassthroughmode, PSCRIPT .TXT” - 3 Commands 499 - and the NetID and the NetID SET NETID SET command places into the Pass command places into SET PASSWORD SET function. PASSWORD PASSWORD command changes the characters of the Password system variable. characters of the Password command changes the argument is the string which the argument is the string This command does not apply to IBM TN3270 emulations. not apply to IBM This command does Text Text This command and its system variable are similar in nature to the similar in nature variable are This command and its system with the Compare variable. Text The system variable. word Note: Comments Arguments SET PASSWORD SET SET PASSWORD Text SET PASSWORD The SET PASSWORD 500
DCS Script Language Reference SET PHONENUMBER session usesaphoneline. The SET PHONENUMBERPhoneNumber SET PHONENUMBER Arguments Examples Comments Note: made, andthensendstheaccesscode the modemdialsphonenumberfirst,waitssixseconds while theaccesscode request is DCS allows dialingthrough alongdistancesystem thatrequires anaccesscode. When dialed, In thisexample: is determinedby thecontents of thesettingsvariable @S1. the sessionfile In thisexample: Direct Serial connector; itcannotbeusedwiththeModem connector. NENUMBER The phonenumberspecifiedmustbeinaformatacceptableto yourmodem.The comma inthestring. parentheses, dashes,orspacesinthestring.However, DCSpauses foronesecondeach The PhoneNumber PhoneNumber DIAL SET PHONENUMBER@S1 LOAD “COMPUSER” This commanddoesnotapplytoIBM TN3270emulations. SET PHONENUMBER‘0-312-555-1222,,,,,,5554445’ commandonlyhasaneffectwhen you have configured asessionwhichusesthe COMPUSER argument isastringspecifyingthephonenumber. DCSignores any commandsetsthephonenumberfor is loadedandthenaphonenumberdialed.The 5554445 . CONNECT command whenthe SET PHO - 3 Commands 501 - - com SET SET TASKERROR TASKERROR . , that assign a value to , that assign a value TABLE COPY TABLE Appendix A Task Errors Task A Appendix argument specifies the value assigned to the Result system variable. Result system to the value assigned argument specifies the command assigns the specified string value to the Result system variable. Result system value to the specified string command assigns the command assigns a value to the Result system variable. Throughout the script refer the script Throughout system variable. to the Result command assigns a value BEGIN “ | RESULT () SET RESULT “Run Time Error: TASKERROR 2 END WHEN ERROR 3 String a custom routine is established for handling run time errors is established. When a run time is established for handling run is established. a custom routine time errors (a level system variable occurs, DCS appends the normal contents of the Result 3) error (level Result as the stored This new is now string Error:” Time message) to the string “Run 3 error the routine is then called using handling 2 error The level system variable. the script to These commands allow system variable. will be passed the new Result mand. It a warning error. handle a run as if it were time error The contents of the Result system variable may be modified by several methods. The by several may be modified variable Result system The contents of the RESULT such as will also see notations of commands, ence, you system to the Result occurs, DCS will assign a value a task error If system variable. the Result message. to the error equivalent variable messages, see numbers and a list of error For this example: In String The Example Arguments Comments SET RESULT SET SET RESULT String SET RESULT The SET RESULT 502
DCS Script Language Reference SET RETRY connection. (Thisonlyaffectsthemodem;nonoticewillappearinadialog box.) The SET RETRY Boolean SET RETRY Arguments Example Note: dial 5551234repeatedly untilaconnectionismade. These commands: ful connection. ful connectionismade.If the Boolean evaluates toFALSE, DCSdoesnotredial anunsuccess If theBooleanevaluates to TRUE, DCSredials aphonenumbercontinuouslyuntilsuccess evaluate to FALSE. words ON, YES, and TRUE evaluate to TRUE. TheBooleankeywords OFF, NO,and FALSE The Boolean Boolean DIAL ‘5551234’ SET RETRYTRUE This commanddoesnotapplytoIBM TN3270emulations. commandtellsDCSwhethertodialaphonenumberagainafteranunsuccessful argument isspecified by aBooleanexpression orkeyword. TheBooleankey - - - 3 Commands 503 command indicates the amount of time DCS waits before redialing. This redialing. the amount of time DCS waits before command indicates argument is a numeric specifying the number of seconds to wait between successive successive between specifying the number of seconds to wait argument is a numeric SET RETRY TRUE SET RETRYDELAY 60 This command does not apply to IBM TN3270 emulations. not apply to IBM This command does Delay and then continues to redial everyand then continues to redial 60 seconds until a connection is established. redials. DCS delays for the default time of 30 seconds. a delay less than 30 seconds is specified, If After dialing, these commands: if no connection is made, DCS only redials redialing. DCS to wait for 60 seconds before direct Delay The Note: Comments Example Arguments SET RETRYDELAY SET SET RETRYDELAY Delay SET RETRYDELAY The to modems. command applies only SET RETRYDELAY 504
DCS Script Language Reference SET SENDDELAY each characterwhensendingdatatoahostwiththe The SET SENDDELAY Delay SET SENDDELAY Arguments Example Delay mand. directs DCStowaitfor0.25secondsbetween eachcharacterittransmitswiththe This command: a second). a numericofgreater than30unitsisspecified,the second). If anumericoflessthanzero unitsisspecified,the The Delay SET SENDDELAY15 argument isanumericspecifyingthedelay(measured inunitsofone-sixtietha commandspecifiestheamountoftimeforDCStowaitbetween transmitting SEND Delay command. argument defaultsto30(one-halfof Delay argument defaultstozero. If SEND com - 3 Commands 505 - command directs DCS to ring the bell when a connection is made. DCS to ring the bell command directs argument is specified by a Boolean expression or keyword. The Boolean key or keyword. expression by a Boolean argument is specified command is a setting for the DIAL command and specifies whether DCS should for the DIAL command and specifies command is a setting LOAD “SET1” SET SIGNAL TRUE DIAL “5551234” This command does not apply to IBM TN3270 emulations. not apply to IBM This command does Boolean SET SIGNAL SET the words ON, YES, and TRUE evaluate to TRUE. The Boolean keywords OFF, NO, and FALSE NO, and OFF, Boolean keywords The TRUE. to evaluate TRUE YES, and ON, words to FALSE. evaluate the is made. If the bell sounds when a successful connection TRUE, to the Boolean evaluates If no signal is made to indicate a successful connection. to FALSE, Boolean evaluates this example: In Boolean The Note: Example Arguments SET SIGNAL SET SET SIGNAL Boolean SET SIGNAL The when a connection is made. sound the system bell SET SIGNAL 506
DCS Script Language Reference SET SOUND The SET SOUNDBoolean SET SOUND Arguments Example Comments Boolean directs DCSnottosoundincomingbellsfrom thehostsystem. This command: able DCS’s systemwarnings. This commanddisableswarningbellsthatcomeintothesessionwindow only. It doesnotdis FALSE, warningbellsare disabled. If theBoolean evaluates to TRUE, warningbellsare enabled.If theBooleanevaluates to evaluate to FALSE. words ON, YES, and TRUE evaluate to TRUE. TheBooleankeywords OFF, NO,and FALSE The Boolean SET SOUNDFALSE Also see: commandcontrols whetherwarningbellsfrom thehostare enabled. argument isspecified by aBooleanexpression orkeyword. TheBooleankey GENERALCONFIG command - - 3 Commands 507
Directs DCS to expect 1 stop bit per character packet. Directs DCS to expect 1 stop bit per character packet. Directs DCS to expect 2 stop bits per character command sets the intervalduring a each character packet sent of time between SET DATABITS 7 SET STOPBITS 1 SET PARITY MARK Value Action Value 1 1.5 2 to expect 1.5 stop bits per character packet. Directs DCS This command does not apply to IBM TN3270 emulations. not apply to IBM This command does the contents of character packets is established as seven data bits and one stop bit. as seven the contents of character packets is established In this example: In Numeric values: of the following Numeric argument can be one The Note: Example Arguments SET STOPBITS SET SET STOPBITS Numeric SET STOPBITS The intervalserial transmission. This signals the end of a character packet. SET STOPBITS 508
DCS Script Language Reference SET TERMCLOSE window duringscriptexecution. The SET TERMCLOSEBoolean SET TERMCLOSE Arguments Example Comments Boolean procedure. you are notallowed tocloseasessionwindow whileDCSisexecuting the In thisexample: If awindow handleisnotspecified,thecommand isappliedtotheactive sessionwindow. When thesessionwindow cannotbeclosed, DCScannotbeclosed. window specified by the The The The optional WINDOW WinHandle executed. the sessionwindow duringscriptexecution untilaSET TERMCLOSE TRUE commandis ing scriptexecution. If theBooleanargumentevaluates toFALSE, you are notallowed toclose If theBoolean argumentevaluates to TRUE, you are allowed toclosethesessionwindow dur ate toFALSE. ON, YES, and TRUE evaluate to TRUE. TheBooleankeywords OFF, NO,and FALSE evalu The Booleanargumentisspecified byaBooleanexpression orkeyword. TheBooleankeywords WINDOW WinHandle SET TERMCLOSETRUE PERFORM gather_info SET TERMCLOSEFALSE WINDOW clause directs DCStocontrol whetheryou are allowed toclose thesession commandspecifieswhether you willbeallowed toclosethedefaultsession argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular clause includesthe WinHandle WINDOW WinHandle argument. WINDOW keyword andthe WinHandle gather_info argument.
- - 3 Commands 509 - argument. WinHandle keyword and the keyword command instead of this command. WINDOW WINDOW WinHandle WINDOW command for backward compatibility. DCS automatically DCS automatically compatibility. command for backward DISPLAYCONFIG arguments are integers specifying a valid pixel width and height for width and height pixel integers specifying a valid arguments are clause includes the . SizeY SizeY argument is an integer identifying a particular session window. argument no longer has an effect in the session window. This argument has an effect in the session window. argument no longer clause directs DCS to change the size of the font in the session window speci of the font in the session window DCS to change the size clause directs SET TERMFONT SET command changes the size of the font displayed in the session window. the font displayed of size command changes the WINDOW WinHandle and the SET TERMFONT ‘’ 8 12 SizeX WinHandle WINDOW FontName If a window handle is not specified, the command is applied to the active session window. session is not specified, the command is applied to the active handle a window If possible use the Wherever This command: high. pixels wide and twelve sets the session font to eight pixels SizeX SizeY The the font. WINDOW WinHandle The optional The The by the fied FontName The in the remains chosen for the session. have based on the terminal emulation you chooses one of its fonts Comments Example Arguments SET TERMFONT SET SET TERMFONT FontName SizeX SizeY SizeX SizeY FontName SET TERMFONT The SET TERMFONT 510
DCS Script Language Reference SET USERID The SET USERIDText SET USERID Arguments Comments Note: the NetID systemvariable. Compare withthe This commandanditssystem variable are similarinnature tothe system variable. The Text Text This commanddoesnotapplytoIBM TN3270emulations. argument isthestringthat commandchangesthecharactersofUserID systemvariable. SET USERID USERID commandplacesintotheUserID function. SET NETID commandand 3 Commands 511 - - - com string, DCS WAIT STRING WAIT $password command to assign a different command to assign a different SET WILDCARD SET argument becomes the character that represents any argument becomes the character that represents Str2 argument becomes the character that represents any single arbi any single character that represents argument becomes the Str1 Str2 command changes the characters that normally represent arbitrary characters in characters that normally represent command changes the CONNECT SET WILDCARD “?” “t” WAIT STRING “***” SEND $password SET WILDCARD “?” “*” This command does not apply to IBM TN3270 emulations. not apply to IBM This command does resets the wildcard character to its normal value. the wildcard resets In this example: In any arbitrary string to t, so the that represents DCS sets the wildcard After sending the for the asterisk (*) character. mand can search trary character. The question mark (?) normally represents this character. represents (?) normally mark The question trary character. Str2 The first character of the optional The asterisk number of arbitrary characters, or a null character. characters, including no (zero) this character. (*) normally represents or asterisk must be literal char the question mark When using a command or function where use the characters, acters rather than wildcard first example below. in the as shown character to the wildcard Str1 of the The first character Note: Example Comments Arguments SET WILDCARD SET SET WILDCARD Str1 SET WILDCARD The a string. SET WILDCARD 512
DCS Script Language Reference SET WINDOWTITLE the specifiedstring. The SET WINDOWTITLEString SET WINDOWTITLE Arguments Example Comments String title ofthesessionwindow to DCS opens,andconnects,toasessionwindow withthename In thisexample: If awindow handleisnotspecified,thecommand isappliedtotheactive window. The The The optional WINDOW WinHandle The WINDOW WinHandle String SET WINDOWTITLE“HostSession1” CONNECT “SCR1” argument specifiesthestringtobedisplayed. WINDOW clause changesthetitleofwindow tothestringspecified by argument is an integer identifying a particular childwindow. argumentisanintegeridentifyingaparticular commandchangesthestringdisplayed intheactive window’s titlebarto clause includesthe WINDOW WinHandle Host Session1 WINDOW . keyword andthe SCR1 . DCSthenchangesthe WinHandle WinHandle argument. . 3 Commands 513 command to specify command to specify LOGTOFILE LOGTOFILE command directs DCS to open a file command directs LOGTOFILE ot apply to IBM TN3270 emulations. ot apply to IBM is 0 (zero), wordwrap is deactivated. wordwrap is 0 (zero), command is used in conjunction with the command is used in argument is a numeric (from 0 to n) that specifies the desired column. If the column. that specifies the desired 0 to n) (from argument is a numeric Column SET WORDWRAP 95 LOGTOFILE “ONLINE.TXT” PERFORM get_data FILE CLOSE “ONLINE.TXT” This command does n This command does Column saved. value of value this example: In column 95. The wrap is set to the word the file is closed and After the data is received, into which the online session will be captured. Column The Note: Example Arguments SET WORDWRAP SET SET WORDWRAP Column SET WORDWRAP The to wrap words. the column at which SET WORDWRAP 514
DCS Script Language Reference SET XCLOCK system, foranXCLOCK messagefrom thehosttobecleared before generatinganexecution error. The SET XCLOCKTime SET XCLOCK Arguments Example Comments Time command isexecuted. DCS waitsforoneminutetheXCLOCK statetobecleared onthehostafter In thisexample: If awindow handleisnotspecified,thecommand isappliedtotheactive sessionwindow. command. To timeerror hasoccurred, determineifarun usethe The The optional WINDOW WinHandle Hours andminutesare optional, butifhoursare specified,minutesmustalsobespecified. The WinHandle Time SEND “ SET XCLOCK“1:00” Hours:Minutes:Seconds argument isastringinthefollowing format: commandspecifieshow longDCSwillwait,whilesendingdatatoanIBM3270 WINDOW WINDOW WinHandle argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular clause includesthe WINDOW ERROR( ) keyword andthe function or WinHandle WHEN ERROR argument. SEND
3 Commands 515 argument. WinHandle keyword and the keyword WINDOW clause includes the WINDOW WinHandle WINDOW argument is an integer identifying a particular session window. WINDOW command specifies how long DCS should wait, when sending data to an IBM should wait, when sending data to an long DCS how command specifies SEND “ “ Hours:Minutes:Seconds SET XSYSTEM “2:00” WinHandle an execution error will occur if an XSYSTEM message from the host is not cleared within two the host is not cleared will occur if an XSYSTEM message from error an execution minutes of sending the space character. Hours and minutes are optional, but if hours are specified, minutes must also be specified. optional, but if hours are and minutes are Hours WINDOW WinHandle The optional The this example: In Time format: is a string in the following Time argument The Example Arguments SET XSYSTEM SET SET XSYSTEM Time Time SET XSYSTEM The generating an execution before the host to be cleared XSYSTEM message from 3270 system, for an error. SET XSYSTEM 516
DCS Script Language Reference SETTINGS a tabwithinthedialogbefore resuming scriptexecution. The SETTINGS Tab WINDOWWinHandle SETTINGS Arguments Example Comments Tab to modifythecommunicationsettingsduringscriptexecution. the In thisexample: regardless ofthe If nosessionwindow sessionanddefaulttotheConnectorstab isopen,DCSwillopenanew If awindow handleisnotspecified,thecommand isappliedtotheactive sessionwindow. command presents. The The The optional WINDOW WinHandle The Connectors ERROR WinHandle Tab SETTINGS COMMUNICATIONS TRANSFERS MOUSE EMULATE COMMUNICATIONS Keyword Action argument isspecified by oneofthefollowing keywords: command opensthe WINDOW function returns TRUE ifyou selectthe argument is an integer identifying a particular sessionwindow. argumentisanintegeridentifyingaparticular tab ofthe Tab keyword. clause includesthe Session Properties Session Properties Opens theFile Transfers taboftheSessionPropertiesdialog. Opens theMousetabofSessionPropertiesdialog. Opens theEmulationstabofSessionPropertiesdialog. Opens theConnectorstabofSessionPropertiesdialog. WINDOW dialogisdisplayed onthescreen, allowing you dialog,allowing you tomodifyanoptionon Cancel keyword andthe button inanyofthedialogsthis WinHandle argument. 3 Commands 517 SHOW command SHOW command into each subroutine you want to you command into each subroutine command. SHOW SHOW command at compile time. The command at compile SHOW command. command will cancel the command takes no arguments. DEBUG command directs DCS to display script commands in a dialog box as they execute. box to display script commands in a dialog DCS command directs NOSHOW SHOW command. Therefore, you must insert the command. Therefore, debug. The the See The the resolves The DCS compiler placed the have in which you routine the from that execute displays the commands Example Arguments Comments SHOW SHOW The SHOW 518
DCS Script Language Reference SPAWN of thescriptwhichspawnedit.Theoriginalalsocontinuestoexecute withoutinterruption The SPAWN SPAWN Arguments Example Comments SAFE script isalready attachedtothatsession. This examplecausesthescript In thisexample: command, the the functionality,however. With The default sessionhandle. The The The optional WINDOW WinHandle The Target script isalready attached. the a defaultsessionwindow handlethatalready hasatleastonescriptattachedtoit.In thisway The optional SAFE Target SPAWN SPAWN WINDOW WinHandle Target command instructs DCS to start another script. The spawned script runs independently anotherscript.Thespawnedscript DCStostart command instructs SPAWN SAFE$DCscriptWINDOW%hndle %hndle =WINDOWHND(“Session1”) $DCscript =“dodde.dct” Target of the argument isastringspecifyingthescripttostart. command could avoid starting acompetingscriptinsessionwindowcommand couldavoid starting towhicha and WINDOW SAFE Target clause directs DCStoassignthespecifiedwindow script’s handleasthenew argument is an integer identifying a particular window argumentisanintegeridentifyingaparticular inDCS. PERFORM PERFORM WINDOW WinHandle keyword prevents ifitwouldbeattachedto thetargetscriptfrom starting script executes completelyindependently andasynchronously. clause includesthe commandcompletesexecution andreturns. With the PERFORM commands are similar. The dodde.dct , execution until ofthecallingscriptisinterrupted WINDOW to run and actupon torun keyword andthe SPAWN Session1 command provides different WinHandle onlyifnoother SPAWN argument. . 3 Commands 519 - clauses CASE to the line fol Command SWITCH END block if none of the Command clause and argument with the SwitchVariable. The argument with the SwitchVariable. n argument. Var DEFAULT DEFAULT . Command argument is a numeric or string variable or expression that is compared to is compared that or expression argument is a numeric or string variable command is inserted, execution branches past command is inserted, execution clause compares the clause compares n SwitchVariable LEAVE LEAVE command allows script execution to branch to multiple command blocks. to branch to multiple command script execution command allows Command CASE SwitchVariable SwitchVariable DCS executes the optional DCS executes match the Each the match. If if the variables which DCS executes argument is a command or command block an If next CASE variable. to the the SwitchVariable do not match, DCS compares variables optional of the execution lowing DEFAULT: SwitchVariable The each CASE variable. CASE Var Var1: Var2: LEAVE Command LEAVE Arguments SWITCH SWITCH END The SWITCH SWITCH CASE Command LEAVE CASE Command LEAVE DEFAULT: Command LEAVE SWITCH 520
DCS Script Language Reference SWITCH, Example In thisexample: example, if match thestringargumentforoneofcases,scriptdisplaysappropriate string.For DCS compares thecontentsofstringvariable continued SWITCH END LEAVE DISPLAY “none^M” DEFAULT: LEAVE DISPLAY “Candy/Dog^M” CASE “D”: CASE “C”: LEAVE DISPLAY “Ball^M” CASE “B”: LEAVE DISPLAY “Apple^M” CASE “A”: SWITCH $char $char contains“ B ”, thescriptdisplays“ $char Ball toeachofthecases.If thecontents ” followed by acarriagereturn. 3 Commands 521 SYSTEM 0x0701 $FileName $WinFuncNum %ContextNum This command executes the Windows WinHelp function and opens a help file at a topic where WinHelp finds the first instance of a keyword (or phrase) in the help file. which is the path name The first parameter for this command is a string parameter, of the help file. indicating the Windows help The second parameter for this command is an integer, in WINDOWS.H, These numbers are located access. you would like to function that which is a part of the SDK. The third parameter is a string, which is a keyword in the help file. Do not use pointers or custom data types with this command. SYSTEM 0x0702 $FileName %WinFuncNum %ContextNum This command executes the Windows WinHelp function and opens a help file at This command executes the Windows WinHelp context number must be The help file. a topic defined by a context number of the support HPJ or in one of the HPJ’s contained in the Map section of the help file’s files. which is the path name parameter, The first parameter for this command is a string of the help file. indicating the Windows help integer, The second parameter for this command is an These numbers are located in WINDOWS.H, access. you would like to function that Development Kit (SDK). which is a part of the Microsoft Windows Software the context number of the topic that you which is The third parameter is an integer, want to display. Do not use pointers or custom data types with this command. Definition The first parameter for terminal. The command sends a string to a debugging The to the debugging terminal. the command is a string that you want to send use this command you must run To string. second parameter is a null, or empty, terminals and DBWIN.EXE, DBWIN.EXE. For further information about debugging Kit (SDK) and the discussion of see the Microsoft Windows Software Development the OutputDebugString function in the SDK. “” SYSTEM 0x00FF “Procedure succeeded.” arguments are specified by one or more integers or strings. by one or more specified arguments are n P1, P2, … argument is specified by a hexadecimal value from the table below. value from by a hexadecimal argument is specified P command provides script access to operating system-level parameters and environment parameters and environment access to operating system-level script command provides 0x0702 0x0701 SysNum 0x00FF This command does not apply to IBM TN3270 emulations. not apply to IBM This command does SysNum P1, P2, … The optional SysNum The Note: Arguments SYSTEM SYSTEM SysNum SYSTEM SysNum The variables. SYSTEM 522
DCS Script Language Reference SYSTEM, Example Comments See each entry inthetableaboveSee eachentry forasyntaxexample. mand. Contact FutureSoft Technical Support forinformationorquestionsaboutthe and are subjecttochangewithoutnotice. please notethattheparametersforthiscommandare notuniversal between versions ofDCS The parameterslistedinthiselectronic documentare alwaysthemostup-to-date. However, continued Also see: 0x0901 0x0900 0x0803 SysNum
SYSTEM SYSTEM 0x0901“ChangedTitleName” or nullstring. been definedwithatitlebar, andthetitlemustbesomethingotherthananempty For thiscommandtoaffect thetitlebarofdialogbox,box musthave This commandchangesthetitleinadialogboxcreatedbyDCSscript. SYSTEM 0x0900 This commandsetsthefontsizefornextdialoginscriptto8point. $font [%dlgIndex] SYSTEM 0x0803$DlgTitle$control%index\ dialog indexnumber. The fifthparameterisoptionalandidentifiesaparticulardialogasspecifiedby 3.0 andabove,thedefaultfontfordialogcontrolsisSystemVariable font. able” willassigntheSystemVariable-pitch fonttothecontrol.NotethatinWindows nored. “Fixed”willassignthesystemFixed-pitchfonttospecifiedcontrol.“V The fourthparameteriseitherthestring“Fixed,”or“Variable.” Othervaluesareig 1 ,“Message”5etc.). number. This followsthesamesyntaxasexistingscriptdialogverbs(“Edittext” The thirdparameteridentifiesaparticularcontrolasspecifiedbyindex “GROUPBOX” “RADIOGROUP”, “RADIOBUTTON”, “CHECKBOX”,“EDITTEXT”,“LISTBOX”, of thefollowingstringvalues:“ICON”,“MESSAGE”,“BUTTON”, “ICONBUTTON”, The secondparameteridentifiesaparticulardialogcontrolasspecifiedbyone string. The firstparameterisastringspecifyingthetitleofdialogboxoranempty This commandchangesthefontusedinpreviousdialogscript. Definition function
SYSTEM com ari - - - 3 Commands 523 command clears any existing data from a specified table. existing data from command clears any argument is a numeric specifying the table number. argument is a numeric TABLE DEFINE 0 FIELDS CHAR 20 CHAR 10 TABLE DEFINE 0 FIELDS CHAR AS SYLK TABLE LOAD 0 FROM “EXPENSES” PERFORM modifyData AS SYLK TABLE SAVE 0 TO “EXPENSES” TABLE CLEAR 0 Table Table a structured table is defined and data loaded into it. When the table has been modified, it is When the table has been modified, it table is defined and data loaded into it. a structured memory. from to a file and cleared saved Because structured tables are maintained in memory, clearing a table makes more memory more clearing a table makes memory, maintained in tables are structured Because available. this example: In Table The Example Arguments Comments TABLE CLEAR TABLE TABLE CLEAR Table CLEAR TABLE The TABLE CLEAR TABLE 524
DCS Script Language Reference TABLE CLOSE The TABLE CLOSETable TABLE CLOSE Arguments Example Table Line the In thisexample: The TABLE CLOSE5 Table TABLE CLOSE5 RECORD WRITE5 @R5 =“NewLine” TABLE DEFINE5TEXT“MYFILE.TXT” ” into argument isanumericspecifyingthetablenumber. commandclosesatable. MYFILE.TXT statementcloses Table 5(five) afterthescriptwritesstring“ . New 3 Commands 525 - - - copy from a copy from RANGE Contents String Contents Directs DCS to copy only those records that begin with the specified String. Directs DCS to copy only those records that String. be copied from the specified re Specifies a range of characters or fields to record or byte must follow the RANGE keyword with a beginning You cords. number and an ending record or byte number. Directs DCS to copy all records except those that begin with the specified Directs DCS to copy all records except those argument is one of the following keywords: argument is one of the following values are record numbers. Remember that DCS begins numbering the numbers. Remember record are values table. A record numbers in the characters positions or byte are values argument is a numeric (from 0 to 15) specifying the table number of the 0 to 15) (from argument is a numeric
argument is a numeric (from 0 to 15) specifying the table number of the desti 0 to 15) specifying the table argument is a numeric (from RANGE RANGE Contents command copies the contents of the specified source table to the specified destina contents of the specified source command copies the may have a maximum of 254 characters. When performing a a maximum of 254 characters. may have text table, the last full line is always copied to the destination table. The zero. in a text table with byte table and the first in a structured record first The Structured Tables Text Tables RANGE Keyword Action INCLUDE EXCLUDE DestTable SourceTable The Result system variable is set to the number of records copied. records variable is set to the number of Result system The an existing table is replaced, If destination table does not exist, the new the table is created. If any data in the existing table is overwritten. the same format. and destination tables must have Both source DestTable The nation table. Contents String The optional SourceTable The table. source Comments Arguments TABLE COPY TABLE TABLE COPY SourceTable TO DestTable DestTable TO SourceTable COPY TABLE The tion table. TABLE COPY TABLE 526
DCS Script Language Reference TABLE COPY, Example the records from Table 1(one)are copiedto Table 2(two),except forunderscore characters, In thisexample: (one). the charactersinpositions3(three) through 9(nine)are copiedfrom Table 0(zero) to Table 1 In thisexample: and thendisplaysthenumberofrecords copied. TABLE CLOSE0 TABLE COPY0TO1RANGE39 TABLE DEFINE1TEXT“testout.TXT” TABLE DEFINE0TEXT“test.TXT” DISPLAY RESULT()|“recordscopied” TABLE COPY1TO2EXCLUDE“_” continued 3 Commands 527 -
- - TABLE TABLE TABLE SAVE TABLE keyword, the table is maintained in the table is maintained keyword, FILE TEXT FileName FILE argument includes: fi keyword temporarily stores the data as a file-based table on disk temporarily stores keyword CHAR REAL INT argument specifies the file which fills the table. Any changes made to FILE clause defines the record layout for the table data (and corresponding for the table data (and corresponding layout record clause defines the command. A table can be saved to a permanent file with the command. A table can be saved One of the following keywords specifying the logical data type for the field: keywords of the following One An integer specifying the length of the field FileName FIELDS command creates one of two types of tables. one command creates TEXT FileName The If the file does not exist, an empty table is in changes to the file. reflected the table are drive. on the computer hard created A field may have a maximum length of 254 bytes. A table may have a maximum of may have bytes. A table a maximum length of 254 A field may have definition determines the number 1 to 254). A table (numbered record 254 fields in a record. of fields in a table’s FILE The optional a or larger) until the script ends or until DCS executes (for tables 64K in size, CLOSE not included the have you command. If memory. FIELDS f1…fi The buffer). Each record 1 2 Text Text Tables Structured Tables
DCS cannot directly access table data. It must access one record at a time through the corre at a time through must access one record access table data. It DCS cannot directly All data maintained in a file is stored as a string. The CHAR, INT, and REAL data type speci The CHAR, INT, as a string. All data maintained in a file is stored fications maintain the logical data type for data import and export to other applications. maintained as right-justified fields. specified as either INT or REAL are Fields The table argument is an integer (from 0 to 15) specifying the table number. All references to a references All the table number. 0 to 15) specifying The table argument is an integer (from this number. table will reference Table Comments Arguments TABLE DEFINE TABLE TABLE DEFINE Table FIELDS f1...fi FIELDS Table DEFINE TABLE The possible: struc Two types of tables are data. of whole files or masses of for manipulation allow Tables records have Text tables length fields. of fixed records length fixed tables have Structured or text. tured 254. 1 to from of any number of bytes TABLE DEFINE TABLE 528
DCS Script Language Reference TABLE DEFINE, Example A record inatablemaycontainmaximumof254characters. DEFINE DCS clearsthecontentsofacurrently definedtablewhenthescriptexecutes another RECORD READ sponding record buffer variable @R the In thisexample: presents thetextoftable,onelineatatime,inactive sessionwindow. Table 1(one)isdefinedasatexttablecontainingcharactersfrom In thisexample: characters. 1 (one)isacharactertypeandhastencharacters.Field 2(two)isanintegertypeandhasfive Table 1(one)isdefinedasafile-basedstructured-record table,withtwofieldsper record. Field In thisexample: TABLE DEFINE TABLE DEFINE1TEXT“BUDGET.XLS” TABLE CLOSE1 END RECORD READ1 DISPLAY @R1|“^M” BEGIN WHILE NOTEOF() RECORD READ1at0 *ReadLoop TABLE DEFINE1TEXT“MEMO.TXT” TABLE DEFINE1FIELDSCHAR10INT5SAVEDATA commandwiththesamenumberascurrently definedtable. continued commandandwrittentoatablewiththeRECORD WRITE command. commandredefines Table 1(one)asatexttable. n , where n isthetablenumber. Table dataisread with the MEMO.TXT . Thescriptthen TABLE 3 Commands 529 argument is either Source argument specifies a data file, a Source TEXT command). SYLK , or the name of a file. If the , or the name of a file. TABLE DEFINE TABLE DYNACOMM CLIPBOARD clause specifies the source of the data. The value of the of the data. The clause specifies the source command imports data from a file or the clipboard to a structured table. to a structured command imports a file or the clipboard data from argument is an integer (from 0 to 15) specifying the number of the table into which specifying the number of the table into 0 to 15) (from argument is an integer clause specifies the standard data format in which to store the imported data. The in which to store data format clause specifies the standard argument is one of the following keywords: argument is one of the following TABLE LOAD 5 FROM “FORECAST.SYL” AS SYLK TABLE LOAD 5 FROM “FORECAST.SYL” DIF This command is used only with structured tables. only with structured This command is used FROM AS Table Table : interchange (see the interchange This command: in SYLK format. into table five loads the contents of FORECAST.SYL FROM Source The the keyword file name must be used. valid AS Format The Format tables and cannot be used for data valid only for file-based format is DYNACOMM The Table The to load the data. Note Example Arguments TABLE LOAD TABLE TABLE LOAD Table FROM Source AS Format Source FROM Table LOAD TABLE The TABLE LOAD TABLE 530
DCS Script Language Reference TABLE SAVE The TABLE SAVE Table TO Destination AS Format TABLE SAVE Arguments Example Note named “ when a In thisexample: interchange. The DYNACOMM formatis valid onlyforfile-basedtablesandcannotbeuseddata argument isoneofthefollowing keywords: The AS Format specify adatafile,itmustbestringspecifying valid filenamefor yoursystem. the keyword CLIPBOARD, orthenameofafile. If you usethe The TO Destination to save. The Table POKE DATARECEIVED : AS TO Table This commandisusedonlywithstructured tables. END TABLE SAVE0TO“DATA”ASSYLK DISPLAY “POKEDATARECEIVED” BEGIN WHEN POKE0TABLE“item0” DIF DATA POKE clause specifiesthestandard dataformatinwhichtostore thetable’s data.The clause specifiesthedestinationoftable’s data.The command exports thecontentsofastructured tabletoeithertheclipboard commandexports orafile. argument isaninteger(from 0to15)specifyingthetablewhosecontentsyou want . is received from theDDEclientontopicitem0,DCSdisplaysmessage DYNACOMM ” inthesessionwindow andsaves thereceived datatothefile SYLK TEXT Destination Destination argument iseither argument to Format 3 Commands 531 - - keyword per keyword DESCEND argument is an integer specify
n Fld argument is specified by one of the following keywords: by one of the following argument is specified n Dir Fld2 Dir2 Fld3 Dir3 Fld2 Dir2 argument pair defines a sort criterion. The keyword performs the sort in ascending order. The performs the sortkeyword in ascending order. n command sorts table based upon a sort the contents of a structured criteria. argument is a numeric (from 0 to 15) specifying the table to sort. 0 to 15) (from argument is a numeric Dir n n TABLE SORT 0 1 ASCEND 5 DESCEND ASCEND DESCEND This command is used only with structured tables. only with structured This command is used Fld Dir ASCEND Table Table n : This command: using the contents is first sorted in ascending order using two criteria. It 0 (zero) Table sorts the first sort, identical items from a second sort is two or more are If there of field 1 (one). using the contents of field 5 (five). performed order in descending Fld Each The field number. ing the desired The forms the sort in descending order. are sort can be defined. The second sort keys A maximum of three key is used only when there the first sort identical items from key. two or more Table The Note Example Comments Arguments TABLE SORT TABLE TABLE SORT Table Fld1 Dir1 Table SORT TABLE The TABLE SORT TABLE 532
DCS Script Language Reference TASKERROR error level andcode. The TASKERROR TASKERROR Arguments Comments Level example). error message,thescriptmusttrapalevel 3error witha Error level 3(three does notcausethedisplayofanerror message. -run-time) To displayan All error codesoutsideoftherange100-999produce thestring“User-defined error”. Appendix A Task Errors This commandcansimulatetheoccurrence ofanexecution error ofatype you specify. See you mustincludethe Code the typeoferror. Theerror message displayed dependsonthecode. If you donotincludethe The optional Code error level. Thefollowing error levels are available: The optional Also see: Note: User-defined Runtime Warning 4 (four) Critical 3 (three) 2 (two) Fatal 1 (one) 0 (zero) Level Meaning argument, three zeros (000)ispassedasthecode.If you includethe Level Code command callstheDCSinternalexecution error-handling routine andpassesthe
Code Level If aLevel argumentisnotincluded,error level 3(three) isused. SET RESULT argument isanumericspecifyingthethree-digit error codethatidentifies argument isanumeric,from 0(zero) to4(four)thatspecifiesthedesired Level . argument. command WHEN ERROR3 command(seethe Code argument 3 Commands 533 ; a “real” error ; a “real” error ; a “real” error ; default ; default ; custom message “Error Text:” message $result button default “OK” resume continued dialog end wait resume dialog cancel $level=str(%level) $result=result() “ | $level dialog “Error Handler — Level return taskerror 2 221 taskerror taskerror 3 taskerror 3 99 cancel ;error trap routine *HandleError(%level) ;set traps to handle errors ;set traps to perform HandleError(0) when error 0 perform HandleError(1) when error 1 perform HandleError(2) when error 2 perform HandleError(3) when error 3 user-defined errors ;simulate three taskerror 0 221 taskerror 1 221 Example TASKERROR, TASKERROR, 534
DCS Script Language Reference TASKSTOP The TASKSTOP commandwillstopthescriptwithgiven taskID. TASKSTOP Arguments Example: Comments cancel wait delay"9" dialog updatemessage1"Nobody butme!" END TASKSTOP num($tID) if($tID<>$meTask) waitdelay"2" dialogupdatemessage2$tID|"taskname(NUM($tID)) parse$allTasks $tID","$allTasks BEGIN WHILE($allTasks !="") dialog updatemessage1$allTasks $allTasks= TASKLIST() $meTask= TASKLIST(-1) dialog end message"taskid______" message"tasklist______" dialog (7,7)"Stop allotherscripts" spawn "dialogupdate" spawn "simpledlg" spawn "script2" See alsothe TASKLIST function. See alsothe TASKFILE function. See alsothe TASKNAME function. See alsotheSPAWN command. Use themenuoptionScript:Status... scripts. toseealistofrunning The argumentisanumeric,specifyingthedesired scripttostop. taskID taskID 3 Commands 535 function, the script provides the function, the script provides TIMER ( ) command directs DCS to set a timer to zero. DCS command directs argument is a numeric from 0 (zero) to 3 (three) that specifies a timer to reset. Four reset. that specifies a timer to to 3 (three) 0 (zero) from argument is a numeric TIMER RESET 0 CONNECT PERFORM login1 1 for “ | TIMER (0) DISPLAY “Connected to login TIMER RESET 0 Timer Timer that point in the script. In this example: In using the the login. By before the timer is reset system up to to the remote long DCS has been connected or how length of the login process Timer The can only be accessed through maintanied in a single script. These timers separate timers can be a script. Example Arguments TIMER RESET TIMER RESET Timer TIMER RESET The TIMER RESET TIMER 536
DCS Script Language Reference TITLE in thetitlebarofDCSapplicationwindow. The TITLE String TITLE Arguments Example Comments String the textinDCSwindow changesto “ When DCSexecutes thisscriptsegment: Only onetitlemaybeassignedtoeachtaskfile. characters. marks must beused,notastringvariable. Themaximumlength ofthe The command assignsatitletoscript. While thescriptexecutes, the String TITLE “MyScript” Also see: argument specifiesatitle.Aliteralstringofcharactersenclosedwithinquotation Set WindowTitle Set AppTitle command command My Script ”. String String argument displays argument is61 3 Commands 537 - OLE command TOOLBARSHOW
E command closes the specified toolbar, removing it from viewthe application in from it removing specified toolbar, E command closes the TOOLBARHIDE “transfer” ALL ALL EDIT SCRIPT STANDARD TRANSFER SESSION FILE TRACE Also see: This line of script: hidden, the command has no effect. already the toolbar is If toolbar. Transfer hides the or the name assigned to a user-defined toolbar. until after DCS has been restarted, hidden, even will remain hidden via scripting Toolbars again. shown BarName the follow It must be one of toolbar to hide. argument is used to specify which BarName The ing toolbars: Comments Example Arguments TOOLBARHID TOOLBARHIDE BarName TOOLBARHIDE The window. TOOLBARHIDE 538
DCS Script Language Reference TOOLBARSHOW application window. The TOOLBARSHOW BarName TOOLBARSHOW Arguments Example Comments BarName displays thetransfertoolbar. If thetoolbarisalready visible,thecommandhasnoeffect. This lineofscript: hidden. Toolbars displayed viascriptingwillremain visible,even afterDCShasbeenrestarted, until or thenameassignedtoauser-definedtoolbar. lowing: The BarName TOOLBARSHOW “transfer” Also see: TRACE FILE SESSION STANDARDTRANSFER SCRIPT EDIT ALL argument isusedtospecifywhichtoolbarshow andmustbeoneofthefol commandopensthespecifiedtoolbar, displayingitinthetoolbararea ofthe TOOLBARHIDE command OLE - 3 Commands 539 - - Sta keyword of keyword clause. The Status Status and the keyword and the keyword BLOCKSIZE ISSUECLEAR clause to transfer a file with a remote system with a VM/ with a remote system clause to transfer a file with a argument is either the CMS or TSO keyword. TSO argument is either the CMS or clause to transfer a file with a remote system with a TSO remote system with a clause to transfer a file with a Action Directs the remote system to clear the terminal screen before a file transfer is initiated. Directs that the remote system should not automatically clear the terminal screen before a transfer. Specifies to use the value of the Length argument to determine the block Specifies to use the value of the Length argument length of the host data set. the size of the host data The Length argument is an integer and determines set in units of bytes. 80. The default value for a data set block size is with the BLOCKSIZE clause Specifies that the default length associated of space allocated with the is to be used to determine the size for a unit TRANSFERS command (when you have not included option of the SPACE the UNITS clause in the command). ISSUECLEAR BLOCKSIZE clause includes the clause includes the keyword clause includes the keyword
CommandProcessor command sets the parameters in which DCS will send and receive files using a in which DCS will send and receive command sets the parameters CommandProcessor BLOCKSIZE Status Length ISSUECLEAR Sta Length ISSUECLEAR Status BLOCKSIZE CommandProcessor Keyword ON OFF ON Length OFF Clause Action ISSUECLEAR BLOCKSIZE clause includes either: Include the optional Include CMS command processor. The either: ISSUECLEAR Status CommandProcessor The optional BLOCKSIZE Status Length the optional Include command processor. The tus Arguments TRANSFERS TRANSFERS TRANSFERS Status HOSTPROGRAM FileName RECORDLENGTH Number tus PACKETSIZE Type UNITS AddedSpace Status InitialSpace SPACE Type RECORDFORMAT Length Country PCCODEPAGE TIMEOUT Number HOSTCODEPAGE CPUUSAGE Number WinHandle Country WINDOW The sets the parameters for file transfers This command only and its command processor. computer remote or similar mainframe transfer programs. program, file transfer the IND$File involving TRANSFERS 540
DCS Script Language Reference TRANSFERS, transfer, themaximumpacketsize is7(seven). SNAtransferscanbeaslarge32. Transfers The The remote systemcommandprocessor. The optional PACKETSIZE Number The of the that hasa TSO or VM/CMS commandprocessor. The Include theoptional RECORDLENGTH StatusLength The defaultfiletransfer program forDCSisIND$FILE. program ontheremote system. Name The remote system. The optional HOSTPROGRAM FileName with anoldversion oftheIND$FILEtransferprogram shoulduseapacketsize of2(two). Status HOSTPROGRAM Number PACKETSIZE OFF ON Length Clause Keywords RECORDLENGTH argument. The continued clause includeseither: HOSTPROGRAM PACKETSIZE argument isaninteger(from 0to32).However, ifthefiletransferisanon-SNA
clause includesthekeyword RECORDLENGTH FileName clause iscomposedofthe keyword andthe clause specifiesthesize ofdatapacketstransferred toandfrom the involved inthetransfer. associated withtheparticularcommandprocessorandrecordformat Specifies thattheremotesystemistousedefaultrecordlength length ofavariablerecordis84bytes. the defaultlengthofafixedrecordis80bytes,and 84 bytes.OnaremotesystemwithVM/CMScommandprocessor, record is80bytes;however, thedefault foravariablelengthrecordis command processor, thedefaultlengthofafixed orundefinedlength LENGTH appended orreplaced,theremotesystemignores of arecordinunitsbytes.Iffileontheremotesystemisbeing set. The Lengthargumentisaninteger thatdeterminesthesize argument todeterminethelengthofalogicalrecordinhostdata Specifies thattheremotesystemistousevalueofLength Action clause allows accesstoavariety offiletransferprograms ona argument isastringofvalid file nameforatransfer clause oritsdefault.Onaremotesystemwith TSO clausewhenafileistransferred witha remote system Status PACKETSIZE HOSTPROGRAM clause. RECORDLENGTH and the keyword andthe Number clauseiscomposed RECORD argument. File - - 3 Commands 541 - - - - argu clause argument. Type Type Status Type Type and the clause. clause. The keyword and the keyword UNITS SPACE SPACE Status and the Possible Keywords or UNDEFINED FIXED, VARIABLE, FIXED or VARIABLE RECORDFORMAT RECORDFORMAT clause to send a file to a remote system with a TSO remote system with a to a clause to send a file SPACE SPACE The ON keyword specifies to use the InitialSpace and The ON keyword specifies to use the InitialSpace amount of AddedSpace arguments to determine the total argu The InitialSpace space allocated to a new data set. of units ment is an integer that specifies the initial number argument AddedSpace The allocated to a new data set. of space is an integer that specifies the number of units fills with added to the initial space (when the initial space more the new data set, and when the data set requires The maximum number of units that space on the system). + might be available on a remote system is [AddedSpace are clause for the SPACE The units (15 x InitialSpace)]. TRANSFERS com determined by the UNITS clause of the mand. The OFF keyword specifies that the remote system is to use default values for space allocation. Action clause incudes the keyword clause incudes the keyword clause when a file is sent to a remote system that has a TSO com that has a remote system clause when a file is sent to a clause when DCS sends a file to a remote system that has a TSO remote system that has a clause when DCS sends a file to a UNITS clause includes the UNITS SPACE SPACE RECORDFORMAT RECORDFORMAT argument may be one of the following keywords: of the following argument may be one clause includes the keyword clause includes the keyword clause determines the unit of space used by the clause determines the unit of space used by continued Type Type argument is specified by one of the following keywords: by one of the following argument is specified BLOCKS TRACKS CYLINDERS AddedSpace ON InitialSpace OFF VM/CMS command processor Clause Options Files Sent to TSO command processor Type Type UNITS SPACE SPACE RECORDFORMAT RECORDFORMAT UNITS Type UNITS Type the optional Include The command processor. The The SPACE Status InitialSpace AddedSpace Status InitialSpace SPACE the optional Include mand processor. The includes either: RECORDFORMAT Type Type RECORDFORMAT the optional Include VM/CMS command processor. or he ment. The TRANSFERS, TRANSFERS, 542
DCS Script Language Reference TRANSFERS, (five). Number The during afiletransfer. The optional CPUUSAGE Number WinHandle The The The optional WINDOW WinHandle strings: Country transfer viascript.Codepagessetwiththeseoptionsoverride previous sessionsettings.The The optional HOSTCODEPAGE CountryPCCODEPAGE Country Number Number The respond toatransferrequest. The optional TIMEOUT Number TIMEOUT CPUUSAGE WINDOW WinHandle wteln Fec) wteln Gra) UnitedKingdom Switzerland(German) United States Switzerland (French) Sweden Portugal Spain America Latin Germany Italy France Canada (French) Australia argument value is30seconds. argument isanintegerindicatingamountoftimeinunitsseconds.Thedefault argument isanintegerbetween 1(one)and9(nine),inclusive. Thedefault value is5 argument foreither continued . WINDOW HOSTCODEPAGE TIMEOUT CPUUSAGE clause directs DCStosetuptransferparametersforthesession specified by the clause includesthekeyword argument is an integer identifying a particular sessionwindow.argument isanintegeridentifyingaparticular clause includesthekeyword clause includesthe clause setstheamountoftimeDCSwaitsforaremote systemto clause determineshow longDCScontrols theCPUonyour PC HOSTCODEPAGE and International Netherlands Denmark Belgium PCCODEPAGE WINDOW TIMEOUT CPUUSAGE or PCCODEPAGE keyword andthe and the clauses setthecodepagesforafile and the ANSI Norway Finland Canada (English) Number Number is oneofthefollowing WinHandle argument. The argument. The argument. 3 Commands 543 - command. ). If you do not in you ). If FILE SEND BINARY command, and then the file whose file FILE RECEIVE BINARY or TRANSFERS command in a script before a file transfer command, the file transfer a file transfer command, the file transfer before command in a script FILE SEND BINARY , is sent to the remote system with the , is sent to the remote clause is not included, DCS changes the transfer parameters for the active for the active DCS changes the transfer parameters clause is not included, continued $PATH TRANSFERS WINDOW 1234 | “B.DCP” $PATH = DIRECTORY (SCRIPT) “TEST” “TASK” “A” \ FILE SEND BINARY $PATH AS ASCII NOCRLF WINDOW 1234 TRANSFERS CMS \ BLOCKSIZE OFF \ ISSUECLEAR OFF \ BUFFERSIZE 2 \ HOSTPROGRAM “IND$FILE” \ RECORDLENGTH OFF \ RECORDFORMAT FIXED \ SPACE OFF \ UNITS BLOCKS \ WINDOW the transfer environment is set with the the transfer environment name is in In this example: In The parameters in this command determine the operation of a file transfer started command determine the operation of The parameters in this a file by transfer command ( clude the parameters or uses the relevant transfer parameters of the session command uses the existing file transfer command. defined prior to a previous the If session window. Example Comments TRANSFERS, TRANSFERS, 544
DCS Script Language Reference WAIT CHAR window. The WAIT CHARCharacter WAIT CHAR Arguments Example Comments Note: the sessionwindow. Thehexadecimalnumber0x04 represents Control-D inascript. ment, the works onlyinsessionwindows usingaterminalemulationotherthan3270.In thisscriptfrag This example: You. script untilyou press the[G]key(lower caseletterg).Afterthe[G]keyispressed, “ ple prompts you topress the[G]key. The works onlyinsessionwindows usingaterminalemulationotherthan3270.Thescriptexam This example: the To waituntilahostisinready statebefore sendingdata,seethespecialstringsforusewith If thewindow handleisnotincluded,thecommand isappliedtotheactive sessionwindow. session window. The The The optional WINDOW WinHandle The Characterargumentspecifiesacharacterforwhichtowait. Character SEND
WINDOW WinHandle The EDITCOPYSPECIAL commanddoesnotapplytotheIBM TN3270emulation. WAIT CHARCHR(0x04) DISPLAY “ExecutionPaused,HitControl-D To Continue: ^M” DISPLAY “ThankYou.^M” WAIT CHAR‘g’ DISPLAY “Pleaseenter‘g’togonextmenu:^M ” appearsinthesessionwindow commandpausesexecution untilthespecifiedcharacteris received inthesession WAIT CHAR command. WINDOW clause directs DCStowaitforcharacterechofrom aremote systeminaspecific argument is an integer identifying a particular sessionwindow.argument isanintegeridentifyingaparticular WINDOW WinHandle commandpausestheexecution ofthescriptuntilaControl-D enters clause includesthe WAIT CHAR WINDOW keyword andthe commandpausestheexecution ofthe WinHandle Thank argument. - - 3 Commands 545 - LOGTO argument. WinHandle WinHandle keyword and the keyword WINDOW command does not apply to the IBM TN3270 emulation. apply to the IBM command does not clause includes the is not included, the command is applied to the active window. to the active is not included, the command is applied argument is an integer identifying a particular child window. clause directs DCS to wait until the text file opened in a specific window is file opened in a specific window DCS to wait until the text clause directs WINDOW command pauses script execution until you close a text file opened by the a text file opened close you until execution command pauses script EDIT COPYSPECIAL EDIT WINDOW WinHandle WINDOW WinHandle WinHandle WinHandle WinHandle WINDOW The The The closed. the If WINDOW WinHandle The optional Note: command. Comments Arguments WAIT CLOSE WAIT WAIT CLOSE CLOSE WAIT The FILE WAIT CLOSE WAIT 546
DCS Script Language Reference WAIT DELAY The WAIT DELAY Time WAIT DELAY Arguments Comments The Time The scriptlanguageallows thiscommandtowaitafractionofsecond. WAIT DELAY branches pastthecurrent If a mand. Thisformofthecommandactivates a A before thestringforafractionofsecond. minutes, andsecondsstrings(withthecolonbetween each)andthatyou includeaperiod The formatforpausinglessthanasecond requires that you includea0(zero) forthehours, have thefollowing format: For thiscommandtopauseascriptforonlyfractionofsecond,the where: WAIT DELAY RESUME Time 0:0:0.fff fff ss mm Description hh Time Element hh:mm:ss.fff argument isastringinthefollowing format: commandpausestheexecution ofascriptforspecifiedperiodtime. “0”command,ifany). command executes afterexecution of value ofzero ( Optional integercharacterstringforafractionofsecond Required integercharacterstringforanumberofseconds Optional integercharacterstringforanumberofminutes Optional integercharacterstringforanumberofhours WAIT WAIT DELAY command (thelast “0”)isaspecialcaseofthe WHEN WAIT WAIT DELAY command withoutenteringawaitstate. command priortoexecution ofthe “0”,execution ofthescript Time WAIT DELAY argument must com - 3 Commands 547 command WAIT DELAY “0” command. Because DCS treats active active DCS treats command. Because WHEN command does not create a wait state, the execution of the a wait state, the execution command does not create commands, DCS is able to determine if someone has selected the commands, DCS is able to determine if WHEN continued command causes execution to cancel. command causes execution WAIT DELAY “0” button during the execution of the loop. button during the execution WAIT DELAY “0:0:0.25” WAIT DELAY “0” END DISPLAY “Aborted” CANCEL *CountSub DIALOG MESSAGE “Count: “ BUTTON CANCEL “Cancel” RESUME DIALOG END SET %counter 1 WHILE (TRUE) BEGIN “ | STR (%counter) DIALOG UPDATE MESSAGE 1 “Count: INCREMENT %counter WAIT DELAY “00:10” PERFORM CountSub WHEN TIMER “5” WAIT RESUME the script waits for one quarter second. a dialog box displays while a loop executes. Each time the displays while a loop executes. a dialog box of a the script checks for the activation executes, as dialog controls Cancel the Since RESUME this example: In This command: for ten seconds. to pause script execution DCS directs this example: In Examples WAIT DELAY, DELAY, WAIT 548
DCS Script Language Reference WAIT ECHO system. The WAIT ECHO WAIT ECHO Arguments Example Comments WINDOW WinHandle determines ifthehostsentanexpectedprompt. DCS waits30secondstoreceive inputfrom theremote system.The In thisexample: the To waituntilahostisinready statebefore sendingdata,seethespecialstringsforusewith the active sessionwindow. If the session window. The The The optional SEND WINDOW WinHandle WINDOW SEND ‘USER’ IF SEARCH(‘ID:’)<>-1 WAIT ECHO END CANCEL DISPLAY (0,0)“NoPrompt” BEGIN WHEN QUIET‘30’ WINDOW WinHandle commandpausesscriptexecution untilanycharacterisreceived from theremote command. WINDOW clause directs DCStowaitforcharacterechofrom aremote systeminaspecific clause isnotincludedinthecommand,DCSwillwaitforcharacterecho argument is an integer identifying a particular sessionwindow.argument isanintegeridentifyingaparticular clause includesthe WINDOW keyword andthe SEARCH WinHandle function then argument. 3 Commands 549 - - com File WAIT EDIT WAIT and pauses script execution until the memo and pauses script execution specifies the position and size of a memo window. It memo window. of a and size specifies the position BILLS.TXT h) w, (x, y, argument is a string specifying the name of the file to edit. The argument is a string specifying the name command is equivalent to closing the memo child window. command is equivalent FileName is the string “?”, DCS prompts for a file name during script execution. is the string “?”, DCS prompts a new or is the null string “”, DCS opens memo window. is not provided RESUME command invokes the memo editor and pauses script execution until you close the until you editor and pauses script execution the memo command invokes argument must specify a valid file name for your system. file name for argument must specify a valid WAIT EDIT “bills.TXT” PERFORM file_transfer h) FileName w, (x, y, FileName FileName Executing a Executing this example: In the script opens the memo file is closed. window FileName The optional Name If If the at the line following script execution resumes Closing the memo window automatically. mand. The document is saved h) w, (x, y, set The optional coordinate the height (h). corner (x, y), the width (w), and indicates the top left Example Comments Arguments WAIT EDIT WAIT WAIT EDIT EDIT WAIT The memo editor. WAIT EDIT WAIT 550
DCS Script Language Reference WAIT PROMPT session window. The WAIT PROMPTNumChar WAIT PROMPT Arguments Example Comments Note: The run script execution pausesuntiltencharactersare received inthesessionwindow, then In thisexample: the To waituntilahostisinready statebefore sendingdata,seethespecialstringsforusewith characterreceived.DCS countsevery active sessionwindow. If the window. The optional The The optional WINDOW WinHandle The NumChar SEND WinHandle NumChar isperformed. WINDOW PERFORM trial_run WAIT PROMPT10 WAIT PROMPT command. commandpausesexecution untilaspecifiednumberofcharactersis received ina WINDOW WINDOW argumentisanintegerspecifyinganumberofcharacterstoreceive. clause isnotincludedinthecommand,DCSwaitsforcharacters argument is an integer identifying a particular sessionwindow.argument isanintegeridentifyingaparticular WINDOW WinHandle clause directs session DCStowaitforthecharactersinaparticular clause includesthe commanddoesnotapplytotheIBM TN3270 emulation. WINDOW keyword andthe WinHandle trial_ argument. 3 Commands 551 - - WinHan keyword and the keyword WINDOW argument is an integer that identifies a particularargument is an integer that identifies a session window. Optional integer character string for a number of hours Optional integer character string for a number of minutes Optional integer character string for a number of seconds Required integer character string for a number of a second Optional integer character string for a fraction clause is composed of both the clause specifies to watch for character transmission in a specific session clause specifies to watch for character transmission clause is not included in the command, DCS will watch for character trans clause is not included in the command, DCS WINDOW WinHandle WINDOW WINDOW WinHandle argument is a string in the following format: in the following argument is a string command pauses the execution of a script for a specified period of time wherein no wherein a script for a specified period of time of execution command pauses the Time Element Time hh Description mm ss fff hh:mm:ss WINDOW Time Time argument. The optional The window. dle The optional the If session window. missions in the active where: WINDOW WinHandle Time The Comments Arguments WAIT QUIET WAIT WAIT QUIET Time QUIET Time WAIT The occurs. character transmission WAIT QUIET WAIT 552
DCS Script Language Reference WAIT QUIET, Example These commands: demonstrate anotherexampleofasimpleloginscript,butfornon-IBM TN3270 terminal. These commands: to beready forthepassword. activity hasstoppedfortwoseconds.At thispointinscriptsegment,thehostisassumed followed by acarriagereturn. DCSthensuspendsthescriptsexecution untilcommunication host, waitsforthecharacters“ demonstrate anexampleofasimpleloginscriptfor3270terminal.DCSconnectstothe SEND $password WAIT QUIET“00:02” SEND $UserName WAIT STRING“login:” DIAL SEND $Password|“{ENTER}” WAIT QUIET“00:02” SEND $UserName|“{ENTER}” WAIT STRING“login:” CONNECT continued login: ” toappear, andthensendsthestringin $UserName
3 Commands 553 command. command takes no arguments. command takes no RESUME command pauses execution until you select the Resume option in the Script the Resume select you until command pauses execution DIALOG “EDIT” EDITTEXT 120 “Enter Name:” BUTTON DEFAULT “OK” RESUME BUTTON CANCEL “CANCEL” CANCEL DIALOG END WAIT RESUME DIALOG CANCEL WAIT RESUME WAIT In this example: In script resuming then waits for an option to be selected before DCS displays a dialog box, execution. The Arguments Example WAIT RESUME WAIT WAIT RESUME WAIT The a menu, or DCS executes WAIT RESUME WAIT 554
DCS Script Language Reference WAIT SCREEN session window. The WAIT SCREEN WAIT SCREEN Arguments Example Comments WINDOW WinHandle window changes,DCSsendsacommand,“ remote datainthesessionwindow. systemtodisplaynew Afterthecontentsofsession sends thestring“ DCS waitsfortheremote systemtodisplaythetext“ In thisexample: the To waituntilahostisinready statebefore sendingdata,seethespecialstringsforusewith active sessionwindow. If the Only onecharacterneedstobeupdatedforthesessionwindow tobeconsidered screen. anew The dle The optional SEND argument. The WINDOW WINDOW SEND “PROFS” WAIT SCREEN SEND “MYID” WAIT STRING“USERID” command. WINDOW WinHandle commandpausesscriptexecution untiltheremote host changesthedatain WINDOW clause directs DCStowaitfordatachangeinaspecificsessionwindow. clause isnotincludedinthecommand,DCSwaitsfordatatochange MYID WinHandle ” totheremote system.Aftersending“ clause iscomposedofboththe argument is an integer identifying a particular sessionwindow.argument isanintegeridentifyingaparticular PROFS ”, totheremote system. USERID WINDOW MYID ” inthesessionwindow, then keyword andthe ”, DCSwaitsforthe WinHan - 3 Commands 555 - argu WinHandle WinHandle argument may contain the argument may contain keyword and the keyword String time expires. WINDOW QUIET QUIET ” to appear in the session window. After 5 seconds, the ” to appear in the session window. login command does not apply to the IBM TN3270 emulation. to the IBM command does not apply argument is an integer and identifies a particular session window. clause directs DCS to wait for the string in a specific session window. in a specific session window. DCS to wait for the string clause directs clause causes execution to resume if an amount of time elapses without if an amount to resume clause causes execution QUIET Time Window WinHandle Window QUIET Time clause is not included in the command, DCS will wait for the string in the clause is composed of both the function returns TRUE if the TRUE function returns WINDOW WinHandle QUIET command pauses execution until DCS receives a string during a session. DCS receives until command pauses execution argument specifies the string to wait for. The string to wait for. argument specifies the command. WAIT STRING WAIT WAIT STRING “login” QUIET “00:00:05” Hours:Minutes:Seconds WINDOW WINDOW ERROR String SEND To wait until a host is in a ready state before sending data, see the special strings for use with state before wait until a host is in a ready To the this example: In the script waits for the string “ wait string is canceled. The optional The ment. The optional the If session window. active The that string position. The * wildcard indicates that 0 (zero) or more characters may occupy that characters may occupy or more indicates that 0 (zero) that string position. The * wildcard string position. QUIET Time The optional Time argument is a string in the The not received. character transmission, and the string is format: following specified, minutes must also be specified. optional, but if hours are and minutes are Hours WINDOW WinHandle String The occupy indicates that any single character may characters ? and *. The ? wildcard wildcard The Note: Example Comments Arguments WAIT STRING WAIT WAIT STRING String STRING WAIT The WAIT STRING WAIT 556
DCS Script Language Reference WAIT UNTIL The WAIT UNTIL Time WAIT UNTIL Arguments Example Time DCs waitsuntil5:00P.M. andthenconnectstothehostcomputer. In thisexample: Hours andminutesare optional, butifhoursare specified,minutesmustalsobespecified. The Time CONNECT WAIT UNTIL“17:00:00” Hours:Minutes:Seconds commandwaitsuntilthespecifiedtimeofday. argument isastringinthefollowing format(basedona24-hour clock): 3 Commands 557 - - - - - WHEN argument is an integer Level argument is an integer specifying argument is an integer specify argument is an integer (from 0 to 15) Index Index Index argument is an integer specifying which argument is an integer specifying which command. Index Index WHEN command to cancel. If it is not included, all it is not If command to cancel. WHEN Directs DCS to cancel one or more (DDE) WHEN POKE com The ERROR clause directs DCS to cancel one or more WHEN The ERROR clause directs DCS to cancel one Directs DCS to cancel one or more WHEN SCREEN commands. Directs DCS to cancel one or more (DDE) WHEN REQUEST Directs DCS to cancel one or more (DDE) WHEN REQUEST Directs DCS to cancel the active WHEN QUIET command. Directs DCS to cancel the active WHEN QUIET execution are cancelled. The optional WHEN SCREEN command to cancel. If it is not included, all WHEN SCREEN commands on all levels of execution are can celled. included, all (DDE) WHEN ADVISE commands on all levels of included, all (DDE) WHEN execution are cancelled. The optional to cancel. If it is not included, all command WHEN COLLECT are cancelled. commands WHEN COLLECT com Directs DCS to cancel the active WHEN DISCONNECT mand. command. Directs DCS to cancel the active WHEN ECHO The optional ERROR commands. to cancel. If it is not specifying which WHEN ERROR command levels of execution included, all WHEN ERROR commands on all are cancelled. com INITIATE Directs DCS to cancel the active (DDE) WHEN mand. command. Directs DCS to cancel the active WHEN INPUT mands. The optional specifying which (DDE) WHEN POKE command to cancel. If it is not included, all (DDE) WHEN POKE commands on all levels of execution are cancelled. commands. The optional command to cancel. If it is not which (DDE) WHEN REQUEST commands on all levels of included, all (DDE) WHEN REQUEST Action commands. The optional to cancel. If it is not ADVISE command ing which (DDE) WHEN Directs DCS to cancel one or more WHEN COLLECT commands. Directs DCS to cancel one or more WHEN COLLECT Directs DCS to cancel one or more (DDE) WHEN ADVISE Directs DCS to cancel one or more (DDE) WHEN argument consists of a command keyword and an optional and an optional a command keyword argument consists of
argument is specified by one of the following keywords or clauses: keywords by one of the following argument is specified
Index Index
Index Index Level command cancels a specified command cancels a CommandType Index
CommandType QUIET REQUEST SCREEN ECHO ERROR INITIATE INPUT POKE Keyword Clause ADVISE COLLECT DISCONNECT CommandType The CommandType The optional specifies which command index. It cancelled. are of execution level commands on the current Arguments WHEN CANCEL WHEN CANCEL WHEN CANCEL The WHEN CANCEL WHEN 558
DCS Script Language Reference WHEN CANCEL, Example See the WINDOW TIMER TERMINATE STRING Keyword Clause (DDE) WHEN ADVISE (DDE) Index continued
command. Directs DCStocanceltheactiveWHENWINDOWcommand. Directs DCStocanceltheactiveWHEN TIMER command. mand. Directs DCStocanceltheactive(DDE)WHEN TERMINATE com celled. WHEN STRINGcommandsonalllevelsofexecutionarecan WHEN STRINGcommandtocancel.Ifitisnotincluded,all The optional Action Directs DCStocanceloneormoreWHENSTRINGcommands. Index argument isanintegerspecifyingwhich - - 3 Commands 559
- pOffStr pOffStr , commands pExcludeStr nQuiet , WHENCOL WHENCOLLECT nLimit text. Set to a null string if text. Set WHENCOLLECT time is reached. Set to a null Set time is reached. text. Set to a null string if not text. Set pOffStr pOffStr text. Set to a null string if not used. text. Set nQuiet argument. The pFromStr pToStr pToStr nLimit command replaces any previous any previous command replaces argument. argument text or the Index pToStr pToStr WHENCOLLECT or string directs DCS to exclude any characters contained in the DCS to exclude string directs pOffStr pOffStr string argument directs DCS to start collecting characters when the text in the string argument directs command directs DCS to return a maximum of 254 incoming characters from incoming characters from a maximum of 254 to return DCS command directs string argument directs DCS to stop collecting characters when the text in the DCS to stop collecting string argument directs string argument directs DCS to stop collecting characters when the text in the string argument directs arguments can work together (DCS stops collecting characters when any condition arguments can work WINDOW WinHandle integer argument directs DCS to stop collecting characters after it has received a DCS to stop collecting characters after it has received integer argument directs argument is an integer (from 0 to 63) and is the identifier for the 0 to 63) (from argument is an integer is received. The collected data includes the The collected data includes the is received. is received. The collected data does not include the The collected data does not include is received. is received. The collected data includes the is received. command that has the same pExcludeStr nLimit pFromStr pToStr pOffStr pOffStr Index pToStr pToStr is met). Set to a minus one (-1) if not used. is met). Set ExcludeStr The characters until the characters it collects. DCS continues to collect and exclude argument from it encounters the string if not used. Limit The number of characters equal to the integer in the and pOffStr pOffStr not used. FromStr The pFromStr used. ToStr The pToStr command. This argument allows DCS to have a maximum of 64 a DCS to have command. This argument allows at the same time. A active LECT OnStr DCS to start collecting characters when the text in the string argument directs The pOnStr Set to a null string if text. pOnStr The collected data does not include the received. pOnStr not used. OffStr The Index The Arguments WHENCOLLECT WHEN COLLECT Index OnStr OffStr FromStr ToStr WaitExclude Quiet limit SAVECR Quiet limit SAVECR WaitExclude Index OnStr OffStr FromStr ToStr WHEN COLLECT NOTTERMINAL The one of the stop collecting conditions. DCS receives until into a string variable a session window WHEN COLLECT WHEN 560
DCS Script Language Reference WHEN COLLECT, Comments SAVECR one (-1)ifnotused. work together (DCSstopscollectingcharacterswhenanyconditionismet).Set toaminus received forthe The Quiet Handle) subroutine forprocessing. void nIndex,WhenCollect(short booleanbTimeout, BSTRpCollectBuffer, longlWindow When DCStriggersthe WhenCollect event itpassesthecollectedstringto thecorresponding This command returns 0(zero) ifsuccessful and1(one)ifanerror occurs. argument is0(zero), DCSusestheactive sessionwindow. sessionwindowThis integerargumentidentifiesaparticular inDCS. Ifthe WinHandle are passestotheterminalemulationforprocessing. lation, theyare alsonotdisplayed inthesessionwindow. If setFALSE, thecollectedcharacters to theterminalemulationforprocessing. Asthecharactersare not passed totheterminalemu The NOTERMINAL carriage returns. If on theBooleanvalue ofthe The bNOTTERMINAL bSAVECR nQuiet Note: integer argumentdirects DCStostopcollectingcharactersafternoare
might belost. the The argument directs DCStostore carriagereturns inthecollectionstringbased nQuiet COLLECT continued bNOTTERMINAL bSAVECR argument ifset TRUE, directs DCSnottopassthecollectedcharacters number ofseconds.The bSAVECR command is known. Otherwise, important terminalcommands command isknown. important Otherwise, is FALSE, DCSdoesnotsave received carriagereturns. set TRUE shouldbeusedonlyincaseswhere theinputto argument. If nQuiet bSAVECR , pOffStr is TRUE, DCSsaves received and pToStr lWindowHandle arguments can -
- 3 Commands 561 - - - WinHandle WinHandle keyword and the keyword ” in a dialog box upon disconnec ” in a dialog box command and before the condition of command and before WINDOW command executes the logical command. command executes WAIT WAIT ” displays in the session window. argument is an integer and identifies a particular session window. Connection terminated WHEN DISCONNECT clause directs DCS to check the connection for a specific session win to check the connection for a specific session DCS clause directs clause is composed of both the clause is composed of command activates when DCS is in a wait state and when the communi when DCS command activates clause is not included in the command, DCS will check the connection for clause is not included in the command, DCS argument specifies a logical command (either a single command or a command argument specifies a logical command (either WinHandle WinHandle WINDOW Connection terminated command is fulfilled. WINDOW DIALOG CANCEL QUIT END WHEN DISCONNECT BEGIN DISPLAY “Connection terminated” END WHEN DISCONNECT BEGIN DIALOG MESSAGE “Connection terminated” BUTTON DEFAULT “OK” RESUME DIALOG END WAIT RESUME WINDOW Command WAIT WAIT the string “ DCS displays the string “ tion. this example: In the this example: In The optional Command The of the block). Activation the If session window. the active a DCS is in a wait state after DCS has executed WINDOW WinHandle The optional The dow. argument. Example Comments Arguments WHEN DISCONNECT WHEN DISCONNECT WINDOW WinHandle Command WinHandle WINDOW WHEN DISCONNECT The a session is terminated. cations connection of WHEN DISCONNECT WHEN 562
DCS Script Language Reference WHEN ECHO ter through the communications port forthesessionwindow.ter through thecommunicationsport The WHEN ECHOStringVar WHEN ECHO Arguments Example Comments StringVar window. isdisplayedeach characterthatcomesinthrough inthesession thecommunicationsport In thisexample: the DCS isinawaitstateafterhasexecuted a active sessionwindow. If the block). Activation ofthe The Command The The The optional WINDOW WinHandle The WAIT Command WINDOW WinHandle StringVar WINDOW WAIT RESUME END RESUME IF $char=“Z” DISPLAY $char|“received” BEGIN WHEN ECHO$char SET $char“” command isfulfilled. commandactivates whenDCSisinawaitstateandreceives acharac WINDOW argument specifiesastring variable inwhichtostore the received character. clause directs DCStowatchforcharactersinaspecificsessionwindow. argument specifiesalogicalcommand(eithersingleor clause isnotincludedinthecommand,DCSwatchesforcharacters argument is an integer that identifies a particular sessionwindow.argument isanintegerthatidentifiesaparticular WINDOW WinHandle clause includesthe WHEN ECHO commandexecutes thelogicalcommand. WINDOW Command WAIT command andbefore theconditionof keyword andthe WinHandle argument. - 3 Commands 563 command. command and before the condition of the the condition of command and before function returns information about the error which error information about the function returns WAIT WAIT TASKERROR TASKERROR command executes the logical command. command executes RESULT RESULT command. WHEN ERROR command and the argument specifies a logical command (either a single command or a command argument specifies a logical command (either argument is an integer, from 0 (zero) through 3 (three), that specifies the 3 (three), through 0 (zero) from argument is an integer, WHEN ERROR command activates when DCD is in a wait state and encounters an execution is in a wait state and encounters an execution when DCD command activates SET RESULT SET command is fulfilled. The LevelNum Command See the See Command The of the block). Activation of a DCS is in a wait state after execution WAIT the activated LevelNum The level. error desired Comments Example Arguments WHEN ERROR WHEN ERROR LevelNum Command LevelNum WHEN ERROR The during script execution. error WHEN ERROR WHEN 564
DCS Script Language Reference WHEN INPUT pressing forthesessionwindow akeycombinationissentoutofthecommunicationsport The WHEN INPUTStringVar WHEN INPUT Arguments Comments StringVar sent isplacedintotheStringVar, and thelogicalcommandisperformed. the tions port, (real oremulatedviathe tons onasessiontoolbar)alsoactivate the the DCS isinawaitstateafterhasexecuted a tered intotheactive sessionwindow. If the mand block).Activation ofthe The Command window. The The The optional WINDOW WinHandle The WAIT Command WINDOW WinHandle StringVar WINDOW command isfulfilled. optionsthatemulatekeyboardInterface input(suchasbut commandactivates whenDCSisinawaitstateandcharactergeneratedby WINDOW argument specifiesastring variable inwhichtostore theoutgoingcharacter. WHEN INPUT clause directs DCStowatchforthecharactersentered intoaspecificsession argument specifiesalogicalcommand(eithersingleorcom clause isnotincludedinthecommand,DCSwatchesforcharactersen argument is an integer that identifies a particular sessionwindow.argument isanintegerthatidentifiesaparticular WINDOW WinHandle clause includesthe SEND commandcanbeactivated by eachcharactersent.The WHEN INPUT command oratoolbarbutton)issentoutofthecommunica WHEN INPUT WINDOW commandexecutes thelogicalcommand. Command WAIT command andbefore theconditionof keyword andthe command. When keyboard input WinHandle . argument. - - - - 3 Commands 565 - routine for each character sent to the remote system. It con system. It for each character sent to the remote routine $char \ check_char ”. If this string is found in the buffer, the computer beeps. If you press the you press If the computer beeps. this string is found in the buffer, ”. If check_char continued Tom ($char = “^C”) ($char = “^M”) (pos ($buffer, $name) > 0) $buffer = “ “ ;re-initializes buffer END IF ;stops buffering on [Ctrl]+[C] RESUME return ;calls check_char WAIT RESUME CANCEL *check_char $buffer = $buffer | $char buffer ;concatenates character to IF ;checks for carriage return BEGIN IF a line ;beeps if “Tom” is found in BEEP 1 $name = “Tom” name to “Tom” ;initializes $buffer = “ “ buffer to empty ;initializes WHEN INPUT is typed, ;when a character PERFORM DCS calls the return is sent, scans the buffer for a carriage and when catenates the characters into a buffer, the string “ [CTRL]+[C] key combination, the script terminates. In this example: In Example WHEN INPUT, INPUT, WHEN 566
DCS Script Language Reference WHEN QUIET within thespecifiedamountoftime. The WHEN QUIETTime WHEN QUIET Arguments Example Comments Time after 5(five) secondspasswithoutcharactertransmission,DCSsendsthestring“ In thisexample: WAIT DCS isinawaitstateafterexecution ofa sion intheactive sessionwindow. If the block). Activation ofthe The Command window. The The The optional WINDOW WinHandle Hours andminutesare optional, butifhoursare specified,minutesmustalsobespecified. The Time argumentisastringinthefollowing format: Command WINDOW WinHandle WINDOW SEND “Good-bye” WAIT STRING“Ready” SEND “hello” WHEN QUIET“5” Hours:Minutes:Seconds command isfulfilled. commandactivates whenDCSisinawaitstateandhasnotreceived acharacter WINDOW clause directs DCStowatchforcharactertransmissioninaspecificsession argument specifiesalogicalcommand(eithersingleor WINDOW WinHandle clause isnotincludedinthecommand,DCSwatchesforcharactertransmis argument is an integer and identifies a particular sessionwindow.argument isanintegerandidentifiesaparticular clause includesthe WHEN QUIET commandexecutes thelogicalcommand. WAIT Command WINDOW command andbefore theconditionof keyword andthe WinHandle hello argument. ”. - 3 Commands 567 WHEN argument. The Command WinHandle WinHandle command and before the condition of the command and before WINDOW WinHandle WINDOW keyword and the keyword ) command executes the logical command. command executes WAIT WAIT Lns WINDOW arguments are integers specifying the top line, left column, integers specifying the top arguments are commands to be active at the same time. A maximum of 24 at the commands to be active WHEN SCREEN Lns ) argument is not included, the specified screen region will be 1 (one) line screen argument is not included, the specified Lns , and clause is not included in the command, DCS will watch the screen region of region clause is not included in the command, DCS will watch the screen argument. argument specifies a logical command (either a single command or a command argument specifies a logical command (either clause directs DCS to watch the screen region in a session window specified by specified in a session window region DCS to watch the screen clause directs clause includes the Wid Lns command activates when DCS is in a wait state, a region has been modified, has been modified, is in a wait state, a region when DCS command activates , argument is an integer and identifies a particular session window. argument is a numeric (from 0 to 23) specifying the command identifier. It allows It allows specifying the command identifier. 0 to 23) (from argument is a numeric Col commands may exist at one time. commands may exist , WHEN SCREEN command is fulfilled. WINDOW WINDOW Row WINDOW Index Command WinHandle WinHandle DCS is in a wait state after execution of a DCS is in a wait state after execution WAIT The the Command The of the block). Activation the If session window. the active SCREEN Col, Wid, (Row, The screen of the terminal of the region respectively, column width, and optional number of lines, column column is considered The first zero. row row is considered The first to be monitored. the If 0 (zero). long. WINDOW WinHandle The WinHandle Index The multiple Comments Arguments WHEN SCREEN WHEN SCREEN Index (Row, Col, Wid, Col, Wid, Index (Row, WHEN SCREEN The region. of the modified out and the cursor moves WHEN SCREEN WHEN 568
DCS Script Language Reference WHEN SCREEN, Example In thisexample: at row 23,column0(zero), and5(five) characterswide)ismodified. until thevariable Also see: END Display (23,20)“” DISPLAY (23,0)str(%cnt) WAIT DELAY“2” BEGIN WHILE (%cnt<9) %cnt =0 INCREMENT %cnt WHEN SCREEN0(23,0,5) continued (DDE) WHE %cnt equals9,DCSdisplaysthenumberoftimesscreen region (located N ADVISE
command 3 Commands 569 -
WHEN WHEN WHEN STRING commands in a script. command to deactivate a command to deactivate command, that command will replace any previous any previous command will replace command and before the condition of command and before keyword and the WinHandle argument. WinHandle and the keyword WHEN STRING Command WHEN CANCEL WAIT WAIT WHEN STRING WINDOW command executes the logical command. command executes WHEN STRING command does not apply to the IBM TN3270 emulation. to the IBM command does not apply WINDOW WinHandle WINDOW command. A WHEN STRING clause includes the argument is an integer (from 0 to 63) and is the identifier for the 0 to 63) (from argument is an integer String argument is an integer and identifies a particular session window. clause is not included in the command, DCS will watch for the string in the command that has the same Index argument. command that has the same Index argument. argument specifies a logical command (either a single command or a command argument specifies a logical command (either clause directs DCS to watch for the string in the session window specified by specified in the session window DCS to watch for the string clause directs WINDOW Index command activates when DCS is in a wait state and a string enters the commu is in a wait state and a string enters the when DCS command activates Index argument specifies a string. WHEN STRING WHEN STRING command is fulfilled. command. This argument allows DCS to have a maximum of 64 a maximum of DCS to have command. This argument allows defined all previously command will replace WINDOW WinHandle WinHandle WINDOW String Command The WAIT WAIT WinHandle WinHandle If the the If session window. active a DCS is in a wait state after DCS has executed the The optional The The the Command The of the block). Activation STRING the at the same time, and allows commands active particular WHEN STRING argument in a do not include the Index you If STRING String The WINDOW WinHandle Index The optional Note: Comments Arguments WHEN STRING WHEN STRING WHEN STRING The nications port of a session window. WHEN STRING WHEN 570
DCS Script Language Reference WHEN STRING, Example This example: tion. Otherwise, DCSresumes executiontion. Otherwise, afterreceiving thestring“ sible responses. If theremote systemindicatesthatthepassword isinvalid, DCSstopsexecu the string“ demonstrates asimpleloginprocedure. DCSdialsthespecifiednumberandwaitsto receive This example: DCSresumes executionOtherwise, afterreceiving thestringSelect topic:. responses. If theremote systemindicatesthatthepassword isinvalid, DCSstopsexecution. string “ demonstrates asimpleloginprocedure. DCSconnectstothehostandwaitsreceive the WAIT STRING“Selecttopic:” WHEN STRING“Invalidpassword”CANCEL SEND “password” WAIT STRING“Enterpassword” DIAL “5551234” WAIT STRING“Selecttopic:” WHEN STRING“Invalidpassword”CANCEL SEND “password” WAIT STRING“Enterpassword” CONNECT Enter password Enter password continued ”. DCSsendsthepassword, andprepares tohandletwopossible ”. DCSsendsthepassword, andprepares tohandletwo pos Select topic: ”. - - 3 Commands 571 command executes the logical command. command executes WHEN TIMER argument specifies a logical command (either a single command or a command argument specifies a logical command (either command activates when DCS is in a wait state and after the specified amount of is in a wait state and after the specified when DCS command activates argument is a string in the following format: in the following argument is a string Hours:Minutes:Seconds Time Time Command Hours and minutes are optional, but if hours are specified, minutes must also be specified. optional, but if hours are and minutes are Hours Command The of the block). Activation Time The Arguments WHEN TIMER WHEN TIMER Time Command Time WHEN TIMER The time has elapsed. WHEN TIMER WHEN 572
DCS Script Language Reference WHEN WINDOW DCS mustbeinawaitstatebefore a Windows messagecanactivate thiscommand. dows andactsuponthem.Thiscommandallows forahighlevel ofcontrol over DCSchildwindows. The WHEN WINDOWWinHandleVar MessageWParamLParam WHEN WINDOW Example Comments Arguments Note: The See the WAIT DCS isinawaitstateafterexecution ofa messages andtheircorresponding parameters. Microsoft Windows Software Development informationaboutwindow Kit(SDK)forfurther The lar window message. The LParam lar window message. The WParam Windows. The Message dow. The WinHandleVar WParam LParam WParam Message WinHandleVar command isfulfilled. WINDOW DEFAULT WHEN WINDOW argument isanumericcontaininginformationthatdependentontheparticu and argument isanumericcontaininginformationthatdependentontheparticu argument isalow level messagewhichdependson actionsthathave occurred in commandfiltersoutalimitedsubsetof Windows messagestothechildwin LParam argument isanumericvariable thatstores win thehandletoaparticular variables are assignedavalue uponexecution. Refer tothe commanddoesnotapplytoIBM TN 3270emulations. command. WAIT command andbefore theconditionof - - - - 3 Commands 573 - - - command equals 10 %ndx WHILE TRUE command, ready to process the to process command, ready argument is evaluated before the com before argument is evaluated command. Boolean loop that includes a Boolean argument and a loop that includes a CONTINUE (DDE) WAIT SIGNAL (DDE) WAIT WHILE or LEAVE LEAVE (converted to a string) repeatedly, until the value of until the value (converted to a string) repeatedly, argument specifies a logical command (either a single command or a com argument specifies a logical command (either argument is initially FALSE, DCS skips the command, and execution contin DCS skips the command, and execution argument is initially FALSE, %ndx argument specifies the Boolean to be evaluated. argument specifies the command in this example: WHEN INITIATE PERFORM dde initiate WHEN POKE 0 TABLE 0 “item0” PERFORM poke0 WHEN TERMINATE DISPLAY “DDE ended” WHILE TRUE WAIT SIGNAL SET %ndx 0 WHILE %ndx < 10 BEGIN DISPLAY (%ndx, 0) STR (%ndx), INCREMENT %ndx END Boolean command defines the startcommand defines the of a WHILE Boolean Command The the is processed, After each DDE request establishes an endless loop. to wait at the causes script execution message. Terminate of a until receipt next DDE request, In this example: In DCS displays (ten). The Command The mand block). the If the command. The ues on the line following for the first time. mand is executed Boolean Examples Comments Arguments WHILE WHILE Boolean Command WHILE Boolean The The Boolean the command. DCS executes TRUE, to evaluates the Boolean argument command. If Boolean argument until the repeatedly and the command is executed repeatedly argument is evaluated a or until DCS executes is FALSE WHILE 574
DCS Script Language Reference WINDOW ACTIVATE The WINDOW ACTIVATEWinHandle WINDOW ACTIVATE Arguments WinHandle dow. If thevalue isFALSE, thespecifiedwindow doesnotbecometheactive window. be brought intofocus.If thevalue is TRUE (thedefault),thewindow ismadetheactive win The optional Boolean window. The WinHandle Boolean argument isanumericexpression thatcontainsthehandleofaparticular command makes a particular window commandmakesaparticular theactive window. expression determineswhetherthewindow withhandle Window will Boolean - 3 Commands 575 Window Window on the Tile Tile command is equivalent to selecting to selecting command is equivalent command takes no arguments. command takes no command tiles all open document windows so that they can be viewed at that they can be viewed so document windows command tiles all open WINDOW ARRANGE WINDOW ARRANGE Executing the Executing size. for maximum arranged to allow are menu. The document windows The Arguments Comments WINDOW ARRANGE WINDOW ARRANGE WINDOW The the same time. WINDOW ARRANGE WINDOW 576
DCS Script Language Reference WINDOW CLOSE have made. The WINDOW CLOSEWinHandle WINDOW CLOSE Arguments Example Comments WinHandle The sessionwindow ispositionedwith the memo andscriptwindows are positioned usingargumentsinthe opens three windows: memo,the anew Th WINDOW CLOSE a command, insert When using dow. The is example: WinHandle WINDOW CLOSE%WIN3 WINDOW CLOSE%WIN2 WINDOW CLOSE%WIN1 WAIT RESUME WINDOW MOVE%WIN3(0,247,635,150) ;opens adefaultsessionwindow WINDOW OPENSETTINGS“”FALSE%WIN3 WINDOW OPENSCRIPT“Report”(316,0,317,245)True%WIN2 WINDOW OPENMEMO“”(0,0,317,245)%WIN1 WINDOW CLOSE commandclosesaspecifiedwindow andprompts you tosave anychanges you argument isanintegerexpression win specifyingthehandleofaparticular command. WAIT DELAY aftera commandwithavalue of1(one) or2(two)following the WAIT ECHO Report WINDOW MOVE script, and a new sessionwindow.script, andanew The , WHEN ECHO command. WINDOW OPEN , or WAIT PROMPT command.
- 3 Commands 577 - - - command passes , the message is placed command to process any win command to process WINDOW DEFAULT WHEN WINDOW WHEN WINDOW to the window, and the IF command is executed. and the IF command is executed. to the window, %msg specifies to destroy the memo window associated with the memo window specifies to destroy 0x0002 command intercepts messages for the window whose window handle is whose window messages for the window command intercepts command passes a message to the default handler for a window defined by defined to the default handler for a window command passes a message argument is an integer variable that stores the handle of a particular window. that stores variable argument is an integer . Use this command with the . Use argument is a low level message which depends on actions that have occurred in occurred message which depends on actions that have level argument is a low argument is a numeric containing information that is dependent on the particuargument is a numeric containing information argument is a numeric containing information that is dependent on the particuargument is a numeric containing information . . When the window message is received, the is received, message When the window . . When a window message is interrupted message by When a window . IF ((%hWnd = %memoHnd) and (%msg = 0x0002)) PERFORM message_script END WHEN WINDOW %hWnd %msg %wParam %lParam BEGIN WINDOW DEFAULT %hWnd %msg %wParam %lParam Message WParam LParam WinHandle WHEN WINDOW WinHandle %msg the %hwnd in message contained in the window Windows message The %memoHnd lar window message. lar window Kit (SDK) for further information Development Software Windows to the Microsoft Refer parameters. messages and their corresponding about window this example: In Message The Windows. WParam The message. lar window LParam The WinHandle The Comments Example Arguments WINDOW DEFAULT WINDOW DEFAULT WinHandle Message WParam LParam Message WinHandle DEFAULT WINDOW The the handle not process. script does messages which your dow WINDOW DEFAULT WINDOW 578
DCS Script Language Reference WINDOW HIDE of itschildwindows. session window); however, the command issimilartousingthe The WINDOW HIDE WINDOW HIDE Comments Arguments the memory thatitallocatedtoDCSonly the memory another applicationusingDynamicData Exchange (DDE). Without DDE, Windows regains view, butstillresides inmemory. When DCSisinthisstate,itcanbeaccessedonlythrough If ascriptterminateswhiletheDCSapplicationwindow ishidden,DCSdisappearsfrom If you donotincludethe dcs applicationwindow hasthehandlenumberzero. The optional WinHandle WinHandle commandhidestheapplicationwindow, orachildwindow, from view. This WinHandle WINDOW HIDE SCREEN WinHandle argument is an integer and identifies a particular childwindow.argument isanintegerandidentifiesaparticular The command withthe argument, thecommandaffectsactive window. commandcanhidethedcsapplicationwindow orany after you restart Windows HIDE keyword (whichwillhidethe . 3 Commands 579 on the Maximize Maximize command is equivalent to selecting command is equivalent argument is a numeric expression that evaluates to the handle of a that evaluates expression argument is a numeric command enlarges the DCS window to fill the entire screen or enlarges one screen to fill the entire DCS window command enlarges the WinHandle WINDOW MAXIMIZE WinHandle WinHandle WINDOW MAXIMIZE %win maximizes the window specified by the window handle in the %win variable. handle in the %win by the window specified the window maximizes If no window handle is specified, the command affects the active window. is specified, the command affects the active handle no window If the Executing menu. control menu or a DCS child-window DCS control This example: WinHandle The optional the DCS application window. to specify (zero) the number 0 Use particular window. Comments Example Arguments WINDOW MAXIMIZE WINDOW WINDOW MAXIMIZE WINDOW The the application window. to fill of the DCS child windows WINDOW MAXIMIZE WINDOW 580
DCS Script Language Reference WINDOW MESSAGE The WINDOW MESSAGEWinHandle MessageWParamLParam WINDOW MESSAGE Arguments Example Comments WinHandle Edit MESSAGE window whenamenuitemischosenorbuttonpressed. In thisexample,the (see the Windows Software Development Kitfordetails). WM_COMMAND issenttoa The messageparameter all textinthewindow In thisexample: about window messagesandtheircorresponding parameters. Refer totheMicrosoft Windows Software Development information Kit(SDK)forfurther window message. The LParam lar window message. The WParam in Windows. The Message window. The LParam WParam Message WinHandle menu. ;copy WINDOW MESSAGE%dcHnd0x01110xE1220 WAIT DELAY‘1’ ;select all WINDOW MESSAGE%dcHnd0x01110xE12A0 commandssimulateselecting argument is an integer containing information that is dependent on the particular argument isanintegercontaininginformationthatdependentontheparticular argument isanintegercontaininginformationthatdependentontheparticu argument isalow level messagewhichdependentsonactionsthathave occurred argument isanumericexpression thatevaluates tothehandleofaparticular commandsendsamessagetothewindow withthehandle WinHandle. %dcHnd 0x0111 isselecedandcopiedtotheclipboard. corresponds tothe WM_COMMAND Windows message Select All ( 0xE12A )and Copy ( 0xE122 WINDOW ) onthe - 3 Commands 581 command is equivalent to selecting Minimize on the DCS to selecting Minimize command is equivalent argument is a numeric expression that evaluates to the handle of a that evaluates expression argument is a numeric command iconizes the given window, or causes DCS to run or causes while appearing window, the given command iconizes WinHandle WINDOW MINIMIZE WinHandle WINDOW MINIMIZE %win will minimize the window specified by the window handle in the %win variable. handle in the %win by the window specified the window will minimize Executing the Executing menu. control window. is not included, the command is applied to the active handle the window If This example: WinHandle The optional the DCS application window. to specify (zero) the number 0 Use particular window. Comments Example Arguments WINDOW MINIMIZE WINDOW MINIMIZE WINDOW The as an icon. on the screen WINDOW MINIMIZE WINDOW 582
DCS Script Language Reference WINDOW MOVE The WINDOW MOVE WINDOW MOVE Arguments Examples WinHandle See the The coordinates ofchildwindows are relative tothepositionofapplicationwindow. If itisnotincluded,adefaultsize andplacementisassigned. included, onetofourcoordinates canbespecified(forexample,(,,40,)tospecifywidthonly). dow. It indicatesthetopleftcorner(x, y),width(w),andheight(h).If thecoordinate setis The optionalcoordinate set (x, y, w, h) window.particular ThedefaultistheDCSapplicationwindow. The optional WINDOW CLOSE WinHandle (x, y, w, h) WinHandle commandmoves andsizes awindow. argument isanumericexpression thatcontainsthehandletoa command. (x, y, w, h) specifiesthedesired positionandsize ofthewin - 3 Commands 583 - argument.
specifies the desired position and size of the win position and size specifies the desired argument. h) Boolean WinHandle h) Boolean w, (x, y, MEMO h) w, (x, y, argument is a numeric which contains the handle to the window of handle to the window argument is a numeric which contains the argument in the command, a 0 (zero) is placed in the argument in the command, a 0 (zero) FileName argument is used to set a window in read-only or read/write mode. A or read/write in read-only argument is used to set a window argument is specified by one of the following keywords: of the following by one argument is specified FileName FileName argument is a string specifying the file name to be opened. If a null string (“”) is to be opened. argument is a string specifying the file name command opens a new empty window or a window with an existing file. or a window command opens a new empty window Boolean WinHandle Type Type WinHandle WinHandle Type Type SETTINGS SCRIPT FileName If the maximum number of windows are open, another window is not opened. If you have have you If is not opened. open, another window are maximum number of windows the If included the your limitations of by the specific is limited only The maximum number of open windows number of communication ports, etc. memory, including the amount of available computer, the child windows are relative to the position of the application window. to the position of relative are the child windows Boolean The optional FALSE. The default state is state sets read-only. TRUE WinHandle The optional by the the file described If the file does returned. is argument is included but the file cannot be opened, 0 (zero) this If for the file, the file cannot be opened. path is given not exist or if an incorrect FileName The opens. used, a new window h) w, (x, y, set The optional coordinate is set the coordinate indicates the top left corner (x, y), width (w), and height (h). If It dow. be specified (for example, (,,40,) to specify width only). can included, one to four coordinates of and placement is assigned. The coordinates this argument is not included, a default size If Type The optional type is MEMO. The default window Comments Arguments WINDOW OPEN WINDOW OPEN WINDOW The WINDOW OPEN WINDOW 584
DCS Script Language Reference WINDOW OPEN, Example Th window ispositionedwiththe script windows are positionedusingargumentsinthe opens three sessionwindow. windows: script,andanew memo,anew anew Thememoand is example: WINDOW CLOSE%WIN3 WINDOW CLOSE%WIN2 WINDOW CLOSE%WIN1 WAIT RESUME WINDOW MOVE%WIN3(0,247,635,150) WINDOW OPENSETTINGS“”FALSE%WIN3 WINDOW OPENSCRIPT“”(316,0,317,245)TRUE%WIN2 WINDOW OPENMEMO“”(0,0,317,245)%WIN1 continued WINDOW MOVE command. WINDOW OPEN command.Thesession 3 Commands 585 on the DCS Restore Restore command. is opened in the upper left corner of the is opened in the upper left corner of the %WIN1 command is equivalent to selecting command is equivalent WINDOW MINIMIZE or argument is a numeric that evaluates to the handle of a particular that evaluates argument is a numeric command restores the DCS application window size and placement prior and placement prior size the DCS application window command restores WinHandle WINDOW RESTORE Window Window WINDOW MAXIMIZE WINDOW RESTORE %WIN1 WINDOW OPEN MEMO “” (0,0,317,245) %WIN1 WINDOW OPEN MEMO “” (0,0,317,245) WINDOW MINIMIZE %WIN1 the memo window specified by the variable by the specified the memo window size. to its previous restored then is minimized, This window screen. Executing the Executing menu. control menu or a child window control window. is not included, the command is applied to the active handle the window If this example: In WinHandle The optional window. Comments Example Arguments WINDOW RESTORE WINDOW RESTORE RESTORE WINDOW The of a to execution WINDOW RESTORE WINDOW 586
DCS Script Language Reference WINDOW STACK that thetopleftcornerofeachwindow isaccessible The WINDOW STACK WINDOW STACK Arguments Comments The The windows are stackedfrom toptobottom withoutchangingtheircurrent order. menu. Executing the WINDOW STACK WINDOW STACK commandpositionsallopenwindows intheDCSapplication window such commandtakesnoarguments. commandisequivalent toselectingCascadeonthe . Window 3 Commands 587 - WIN command. argument is an integer that identifies a particular child window to be that identifies a particularargument is an integer child window WINDOW HIDE command displays the application window or a child window that the a child window or application window command displays the WinHandle WinHandle WinHandle command has hidden. The window appears with the same size and position properties with the same size appears The window command has hidden. restored. The default window is the DCS application window. The default window restored. WinHandle The optional Arguments WINDOW UNHIDE WINDOW UNHIDE WINDOW The DOW HIDE of the prior to execution WINDOW UNHIDE WINDOW 588
DCS Script Language Reference XFERCONFIG configuration fortheactive session. The XFERCONFIG String XFERCONFIG Arguments String protocol for theactive session. a valid setting. Together, thekeyword andthesettingare usedtoconfigure thefiletransfer The String FT_DISABLESTATUSSTOP FT_TIMEOUTVALUE 0-9999 FT_ENABLETIMEOUT Kermit_ExitKermitCommand Kermit_WindowSizeCommand Kermit_RcvPktLenCommand Kermit_SendPktLenCommand Kermit_TextXferCommand Kermit_BinaryXferCommand Kermit_KermitServerCommand Kermit_KermitCommand Kermit_AutoHostActivation Kermit_ChangeFileName Kermit_PacketSize Kermit_WindowSize Kermit_PacketChoice Kermit_WindowChoice Kermit_FileExist Kermit_FileType Kermit_ErrorCheckType Kermit_TimeConstraintsType Keywords forKERMIT Note: argument represents asinglekeyword followed by theassignmentoperator(=)and
command isusedtosetthevalue ofaparameterusedinthefiletransferprotocol Configuration keywords fortransferprotocols shippedwithclientoptions,such as IXFandIND$File, are valid onlyiftheclientoptionhasbeeninstalled. WINDOW WinHandle
1 (true),0(false) 1 (true),0(false) command string command string command string command string command string command string command string command string 1 (true),0(false) 1 (true),0(false) integer (80-9024) integer (1-31) 1 (true),0(false) 1 (true),0(false) prompt, skip,overwrite binary, text 1bytechecksum, 2bytechecksum,3bytecrc standard, loose Valid Setting(s) 3 Commands 589 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) Valid Setting(s) Valid crc16, crc32, auto ascii binary, prompt, resume, skip, overwrite 1 (true), 0 (false) 128, 256, 512, 1K, auto 1 (true), 0 (false) 1 (true), 0 (false) Valid Setting(s) Valid xmodem, ymodem, ymodemg ascii binary, prompt, overwrite, resume 128, 1k checksum, crc16 1 (true), 0 (false) string string 1 (true), 0 (false) string String 1 (true), 0 (false) 1 (true), 0 (false)
continued ZMODEM_SENDCOMMAND string ZMODEM_ESCCTRLCHAR ZMODEM_CHANGEFILENAME FT_ENABLETIMEOUT 0-9999 FT_TIMEOUTVALUE FT_DISABLESTATUSSTOP Keywords for ZMODEM ZERRORCHECK ZFILETYPE ZFILEEXIST ZAUTOSTART ZBLOCKSIZE integer ZMAXIMUMRETRIES ZCONSECUTIVERETRIES integer ZMODEM_AUTOHOSTACTIVATION ZMODEM_RCVCOMMAND string XMODEM_RCVCOMMAND XMODEM_SENDCOMMAND YMODEM_AUTOHOSTACTIVATION YMODEM_RCVCOMMAND YMODEM_SENDCOMMAND FT_ENABLETIMEOUT 0-9999 FT_TIMEOUTVALUE FT_DISABLESTATUSSTOP Keywords for XYMODEM XYOPTION XYFILETYPE XYFILEEXIST XYBLOCKSIZE XYERRORCHECK Integer XYMAXIMUMRETRIES XMODEM_AUTOHOSTACTIVATION XFERCONFIG, XFERCONFIG, 590
DCS Script Language Reference XFERCONFIG, If theIBM TN3270 ClientOption hasbeeninstalled,thefollowing keywords are available: ** * FT_DISABLESTATUSSTOP FT_TIMEOUTVALUE 0-9999 FT_ENABLETIMEOUT IND3270_Extra_Options IND3270_Host_CodePage IND3270_PC_CodePage IND3270_PaceketSize IND3270_Program_Name IND3270_SpaceUnits** IND3270_SpaceSecondary** IND3270_SpacePrimary** IND3270_ChkSpace** IND3270_ConvertCRLF IND3270_ConvertASCII IND3270_Append IND3270_RecFormat IND3270_RecLength* IND3270_ChkRecLength* IND3270_BlockSize IND3270_ChkBlockSize IND3270_HostEnvironment Keywords forIND$File Applicable onlyto TSO environments. Applicable onlytoCMSand TSO environments. continued
1 (true),0(false) 1 (true),0(false) the Sessionor Advanced tabsprovidesettings. Parameters thatyourhostrequiresforwhichneither English-US, CanadianFrench French ISO Latin-1(WindowsNSI),English-US,Canadian 256 to32767 DCS, usuallyIND$File. program thattransfersfilesbetweenthehostand String. The stringshouldbethenameofhost Blocks, Tracks,Cylinders 0 to99999 0 to99999 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) 1 (true),0(false) Default, Fixed,Variable, Undefined 1 to32760 1 (true),0(false) 1 to6233 1 (true),0(false) CICS CMS, TSO, Valid Setting(s) 3 Commands 591
1 (true), 0 (false) SendAbort, SendPurge, SendErase, SendAppend TabList TabsToSpaces, DeleteTabs, in range Stops Tab 128 up to comma-delimited of list 1 – 4096 1 (true), 0 (false) 1 (true), 0 (false) ReceiveAbort, ReceivePrompt, ReceiveOverwrite, ReceiveAppend 1 (true), 0 (false) 1 (true), 0 (false) 0 – 255 0 – 255 A, N, G, O, C, U, S (may four character string, using also be -), or D 1 – 65535 positive integer (1 – 4096) 1 (true), 0 (false) Valid Setting(s) Valid string (48 character limit) limit) positive integer (5 digit volume/subvolume name positive integer (1 – 4096) 1 (true), 0 (false) 1 – 16 transfer) true (Binary transfer), false (Text 0 – 65535 (may not be 101 for binary transfer) 0.001 – 2000.999 1 (true), 0 (false) 1 (true), 0 (false) 1 (true), 0 (false) 1 – 3 1 (true), 0 (false) 1 (true), 0 (false) 1 – 65535
continued IXF_KEEPPCFILEDATE IXF_SENDFILEEXISTOPTION IXF_TABOPTION IXF_TABSEVERY IXF_TABLIST FT_ENABLETIMEOUT 0-9999 FT_TIMEOUTVALUE FT_DISABLESTATUSSTOP IXF_RCVFILEEXISTOPTION IXF_NOEXTENSIONS IXF_OWNER IXF_GROUP IXF_USER IXF_FILESECURITY IXF_PRIMARYHOSTEXT IXF_SECONDARYHOSTEXT IXF_BINARY IXF_FILECODE IXF_EDITINCREMENT IXF_ENABLEPRINTER IXF_STRIPHIGHBIT IXF_SKIPPERFS IXF_MAKEEXTENSION IXF_NUMEXTENSIONCHARS IXF_CRLF IXF_KEEPHOSTFILEDATE Keywords for IXF IXF_HOSTPROGRAM IXF_MAXRETRIES IXF_DEFAULTVOL IXF_RECORDSIZE IXF_SHARE IXF_PACKETDEPTH If the Tandem 6530 Client Option is installed, the following keywords are available: are keywords the following is installed, 6530 Client Option Tandem the If XFERCONFIG, XFERCONFIG, 592
DCS Script Language Reference XFERCONFIG, Example Comments window. The The The optional WINDOW WinHandle the blocksize forthetransferis setto256bytes. In thisexample: the active sessionwindow. If The DCS ScriptLanguageratherthanusingthedialogbox. Properties The keywords correspond toparametersavailable onthe WinHandle ERROR WINDOW WinHandle XFERCONFIG “BlockSize=256” dialog.Thiscommand,therefore, allows you tosettheseparametersthrough the continued WINDOW function returns TRUE ifthe isnotspecified,thefiletransfer protocol configurationsettings are appliedto clause applies the file transfer configuration settings to a particular session clause appliesthefiletransferconfigurationsettingstoaparticular argument is an integer identifying a particular childwindow.argument isanintegeridentifyingaparticular clause includesthe WINDOW WinHandle keyword andthe or File Transfers String keyword isinvalid. tabofthe WinHandle Session argument. A Task Errors
DCS 594
DCS Script Language Reference an example: When anerror occursduringscriptexecution, DCSdisplaysafourdigitnumberinanerror dialog.Here’s Task Errors The firstdigitintheerror numberisthelevel atwhichtheerror occurred. Thefollowing tablelists First Digit all three descriptionofeach. digiterror numberswithashort The three digitsfollowing theerror level indicatetheactual error number. Thefollowing tablelists Remaining Digits all error descriptionofeach: levels withashort Also see: 3 Run Time Run 3 Warning Critical 2 Fatal 1 0 Description Error Level 3411 TASKERROR command Task Errors, continued
Error # Cause of the Error
101 Occurs if a memory allocation or a memory lock fails. 111 Occurs when an attempt is made to assign a value to a variable and it fails. 112 Occurs when a RECORD FORMAT command is executed with illegal row/ column parameters, or a memory allocation in which to store the information fails. 113 Occurs when trying to add a dialog control and it cannot add the new control information to the master dialog control structure. This is due to a memory shortage. 114 Occurs if an unseccessful attempt to save a keymap filehas been made. 115 The keyname parameter resolves to an integer less than zero or greater than 255 when using the KEY command. 201 Occurs when trying to execute a FILE command and the source file does not exist. 202 Occurs when using a FILE RENAME command and the destination file already exists. 211 Occurs if an unsuccessful attempt to launch another application has been made. 301 No terminal window is open when using the following commands: DIAL, BREAK, DROPDTR, FILE SEND..., FILE RECEIVE..., SENDBREAK, SET- TINGS, SAVE, and any SCREEN... command (except SCREEN HIDE). 321 The text specified by the EDIT FIND or EDIT REPLACE commands is not found. 331 The window specified by the WINDOW OPEN command was not opened for any reason. 341 The SET ATTRIBUTES command fails to set the specified attributes. 351 When using the FILE OPENNAME or FILE CREATENAME commands and the user cancels the dialog without choosing a file name. 361 Occurs when using the LIBRARY LOAD command and the maximum num- ber DLLs the script may load has been exceeded, or if the command returns an error value. 362 Occurs when using the LIBRARY CALL command and GetProcAddress cannot resolve the entry point of the specified DLL function or GlobalReAl- loc fails in allocating space to pass parameters from a table. 363 Occurs when using the LIBRARY UNLOAD command returns an error value. 401 Occurs when trying to decode the next command and it is not a valid com- mand. 402 Occurs if a valid command is followed by an option that the command does not use. 403 Unused; ignore if displayed. A TaskErrors 404 Occurs if trying to use TRANSFER OBJECT and the application is not run- ning under NewWave. 408 Occurs if an attempt is made to divide by zero in the expression.
595 596
DCS Script Language Reference Task Errors, 501 426 425 424 423 422 421 PARSE 412 411 Error # continued commands fortheparticularcase ofxxxx. STRING, POKE,etc.andNumber exceedsthemaximumnumberofWHEN Occurs whentryingtoexecutea WHEN xxxxNumber. Wherexxxxis Occurs whenexpecting(x,y, width, height)andthereisanerror. Cases: Occurs whenitexpectsavalidtimeexpression. Cases: Occurs whenabranchcannotberesolved. Occurs whenaBooleanexpressionisexpectedbutnotfound. Occurs whenanintegerexpressionisexpectedbutnotfound. Occurs whenastringexpressionisexpectedbutnotfound. Cases: is presentbutthewrongtype. but notpresent,orwhenvariable is needed Occurs whenanintegervariable Cases: is presentbutthewrongtype. but notpresent,orwhenvariable is needed Occurs whenanintegervariable Cause oftheError WHEN QUIET WHEN TIMER WAIT STRING WAIT QUIET WAIT UNTIL WAIT DELAY PERFORM (sameasEXECUTE) GOTO (sameasEXECUTE) the stringmissing) EXECUTE (ajumpusingastringdenotedtargetnamethathas INCREMENT orDECREMENT variable(IntVar) (DDE) WHENtablenumber(TABLE Table) (DDE) ACCESS channelvariable (ChannelVar) sage, WinParam,LevelParam) WHEN WINDOWanyofthefourvariables(WinHandleVar, Mes WINDOW OPENwindowhandle(WinHandle) LIBRARY LOADlibraryhandle(LibraryName) wards compatibility) CONCAT (obsolete,nolonger documented, butkeptforback WHEN EXECUTE (DDE) WHENREQUEST (DDE) ACCESS (withtheoptionalDDEList) WHEN ECHO WHEN INPUT WAIT COLLECT FILE OPENNAMEorCREATENAME - - Task Errors, continued
Error # Cause of the Error
502 Occurs when trying to setup a WHEN SCREEN command and the user tries to define an area that is not on the screen. 511 No longer used. 524 NetBios error. 525 Connection already made. 526 Already connected to host. 601 Occurs when trying to use a table that has not been defined or when creat- ing a list box in a dialog that uses an undefined table in a DDE transaction Cases: TABLE SORT 602 Occurs when a table number less than zero or greater than MAXTABLE- NUM-1 Cases: Any TABLE command any RECORD command updating a dialog list box using an undefined table in a DDE transaction using an undefined table in a (DDE) WHEN command 603 Invalid field count. 604 A table to be sorted with the SORT command contains zero records. 605 Occurs when using the TABLE LOAD command and the source data fails to load for any reason. 606 Occurs when using the TABLE SAVE command and the data fails to be writ- ten to the destination specified for any reason 611 Occurs when trying to update a list box and an invalid record number is given. 621 Occurs when using the TABLE COPY command and the source and desti- nation tables are the same. 651 Occurs if you attempt to add popups or menu items without first executing the MENU command. 661 Occurs if you try to add an item and there are no popups defined. 671 Occurs when trying to access undefined menu or item. Cases: Try to access an undefined system menu Try to access an undefined user menu Try to access an undefined item in the system menu Try to access an undefined item in a user menu 701 Try to create or update an item in a dialog without having executed the DIA- LOG command. 702 Occurs if you try to have a total of more than 255 dialog controls. 711 Occurs if you try to define more than MAX_WHEN_BUTTONS buttons. This includes buttons, wide buttons, and icon buttons. A TaskErrors 712 Occurs if you try to define more than MAX_WHEN_GROUPS radio groups. 713 Occurs if you try to use a radio button without a radio group. 714 Occurs if you try to define more than MAX_WHEN_CHECKS check boxes. 715 Occurs if you try to define more than MAX_DLG_EDITS edit texts. 716 Occurs if you try to define more than MAX_WHEN_LISTS list boxes.
597 598
DCS Script Language Reference Task Errors, 999 998 997 996 991 986 985 984 983 982 981 931 921 904 903 902 901 851-874 820-844 801-816 732 731 721 Error # continued Error withNetBios.Mostlikelyitis notloaded. commands isnotaDCSchildwindow handle. If thewindowhandlepassedto WINDOWCLOSEorSAVE used todecryptthestring. If rudimentarysanitycheckofdecrypted stringfailsorifincorrectpassword be passedtotheserver. GlobalAlloc failsinallocatingtheglobalmemoryobjecttohold stringto ed isnotastingvariable. transaction hasbeenacknowledged. Also occursifthevaluetobedecrypt Occurs ifanotherDDEtransactionisreceivedbeforetheresponse toaprior been exceededandthetaskenginecannotreplytoanadvisetransaction. Occurs whenthemaximumnumberofWHEN ADVISE commandshave memory. attempted. Also occursifuponfailureofaDDEcommandtoallocateorlock Occurs ifnoDDEchannelsarecurrentlyopenandatransaction is Occurs whentheDDEPOKEcommandfails. Occurs whenaDDEcommandtimesout. table isnotinCF_TEXT format. Occurs whenusingthe(DDE) TABLE REPLY commandandthereplying is notintheCF_TEXT format. Occurs whenusingthe(DDE) TABLE POKEcommandandthetargettable server doesnotpassdatabackinCF_TEXT format. Occurs whenusingthe(DDE) TABLE REQUEST commandandtheDDE WM_DDE_INITIATE messagefailstoinitiateaDDEconversation. Occurs whenusingthe(DDE) ACCESS commandandthe bytes. Occurs ifanencryptedstringoverflowsthescriptsizelimitof254 branch. Could notexecuteaWHENERRORbranch. flush dataassociatedwiththecurrentlevelofoperation. to occurimmediatelybeforeabranchwhenthesystemistryingsaveor Occurs ifthesystemcannothaltcurrentlevelofoperation.Mostlikely Occurs ifPERFORMorEXECUTEfails. Occurs ifaRETURNcommandcannotbeexecutedcorrectly. state ofexecutionbeforeabranchtosubroutine. Occurs ifmemorycannotbeallocatedtostoreinformationaboutthecurrent store theWHENactivationinformation. The WHENACTIVATE errorsoccur whenmemorycannotbeallocatedto the WHENlookupinformation. The WHENENABLEerrorsoccurwhenmemorycannotbeallocatedtostore the WAIT information. The WAIT errorsoccurwhenmemorycannotbeallocatedinwhichtostore Occurs whenthespecifiedICONresourcedoesnotexist. Occurs ifyoutrytoperformaDIALOGUPDATE onanonexistentitem. mand withavaluegreaterthanSTR255-2(256-2). Occurs ifyoutrytouseaLIMIT qualifierina(DIALOG)EDITTEXT com Cause oftheError
- - B New and Removed Commands and Functions
DCS 600
DCS Script Language Reference The following have beenaddedtotheDCSScriptLanguage: New CommandsandFunctions DISPLAYCONFIG CONNCONFIG APPCONFIG —Commands— XFERCONFIG TOOLBARSHOW TOOLBARHIDE SPAWN SET DDETIMEOUT SET DEFAULTSESSIONHANDLE SET AUTOSCROLLTOCURSOR SCROLL UP SCROLL RIGHT SCROLL LEFT SCROLL DOWn MENU INSERT POPUP MENU INSERT ITEM MENU DELETEPOPUp MENU DELETEITEM LOGOTFILE KEYMAP SAVE KEYMAP LOAD EMULCONFIG GENERALCONFIG GETDISPLAYCONFIG GETCONNCONFIG GETAPPCONFIG FLDTEXT FLDNUM FLDATTREXPOS EXPLDATTR DIALOGHANDLE DEFAULTSESSIONHANDLE BUFFER —Functions— WNDFILE TYPEDLIBRARYCALL SEARCHINRECT MESSAGEBOX GETXFERCONFIG GETGENERALCONFIG GETEMULCONFIG B New and Removed Commandsand Functions 601 WINDOW SELECT WINDOW SHOW SET TASKYIELD SET TERMSCROLLBARS SET TERMTITLE SET TEXTTRANSFERS SET TIMEOUT SET TRANSLATION SET TRUEATTRIBUTES SET UNITS SET TIMER VIDEO LOAD VIDEO RESET VIDEO SAVE VIDEO STYLE VIDEO UPDATE NETWORK WAIT WAITFORCALL WHEN LISTEN WHEN RECEIVE WINDOW ATTACHMENT WINDOW SAVE SET NETWORK RECEIVETIMEOUT SET NETWORK REMOTENAME SET NETWORK SENDTIMEOUT SET PARITYCHECK SET PINTER SET RECORDFORMAT SET RECORDLENGTH SET SCROLLMARGINS SET SPACE1 SET SPACE2 SET STOPALERT SET
SET NETWORK LUPUNAME NETWORK SET SET MODEM SET MODEMTYPE SET MONITORMODE SET SYSTEM 0x801 (use MESSAGEBOX() function NETWORK SET CARDNUM NETWORK SET LINK NETWORK SET NAME LOCAL NETWORK SET LUNUM NETWORK SET SET FKEYSICONS SET FKEYSONEROW SET FOLDER SET IBMTOANSI SET INCOMINGCR SET INCOMINGLF SET INPUTMODE SET LIMITWINDOWSIZE SET LINEWRAP SET MEMOTITLE SET RESET SERIAL RESET ANSWERBACK SET AUTORESET SET BLOCKSIZE SET CONFIRMDISCONNECT SET CONNECTOR SET COUNTRY SET CURSORBLINK SET EMULATE SET FKEYSARRANGE SET (DIALOG) WIDEBUTTON FILE VIEW GIF FILE VIEW RLE FILE VIEW TEXT KEYCODE MERGE —Commands— Removed Commands and Functions Commands Removed Script Language: the DCS from removed been have The following 602
DCS Script Language Reference Removed CommandsandFunctions, —Functions— VIDEO () SETTINGS (Translation) SETTINGS (Country) SELECTION () MODEMTYPE KEYBOARDSTATE () HWNDFILE () FOLDER () BUFFER () continued C Quick Reference for Command and Function Syntax
DCS
Syntax Quick Reference
All functions and commands available in the DCS Script Language are listed below with the required state- ment syntax for each. Functions are followed by “( )” characters. Note: Commands or functions flagged with an asterisk do not apply to the IBM TN3270 emu- lation.
Command/Function Name Statement Syntax
—A—
ACTIVE ( ) ACTIVE ( )
APPCONFIG APPCONFIG String
ARGUMENTS ARGUMENTS (Parameter, ...)
ATTRIBUTES ( ) ATTRIBUTES (FileName)
—B—
BAND ( ) BAND (Source, Mask)
BEEP* BEEP Num
BEGIN BEGIN
BNOT ( ) BNOT (Numeric)
BOOL ( ) BOOL (Integer)
BOR ( ) BOR (Source, Mask)
BREAK* BREAK DelayUnits
BXOR ( ) BXOR (Source, Mask)
—C—
CANCEL CANCEL
CHR ( ) CHR (Numeric)
CLEAR CLEAR Screen WINDOW WinHandle
COLLECT* COLLECT UNTIL String1 EXCLUDE String2 String3 LIMIT Num SAVECR SBoolean NOTERMINAL WINDOW WinHandle
COMPILE COMPILE Script Make Display
CONCAT CONCAT StringVar String String …
CONNCONFIG CONNCONFIG String WINDOW WinHandle
CONNECT ( ) CONNECT ( )
CONNECT CONNECT SessionFile WINDOW WinHandleVar
CONNECTMESSAGE ( )* CONNECTMESSAGE ( )
CONNECTRESULT ( )* CONNECTRESULT (WinHandle) DCS Script Language Reference CONTINUE CONTINUE
CREATE DIRECTORY* CREATE DIRECTORY Path 604 C Command and Function Syntax Quick Reference 605 Item Command Item Item AS Item Command Item Channel ) Item Channel Item Command Channel Command Control ControlNum Channel CheckBoxText CheckBoxText
Item Command Command Command Title Title
CommandVar Command CommandVar Channel Item Channel
ChannelVar DDEList ChannelVar ) Channel Command, ... Channel DialogIndex Channel DialogIndex Channel ChannelVar ChannelVar ) Channel ControlNum, DialogIndex (x, y, w, h) Default w, (x, y, Channel WinHandle (x, y, w, h) Default w, (x, y, (x, y, w, h) Title SYSMENU SBoolean MODAL SYSMENU SBoolean MODAL h) Title w, (x, y, Seconds PhoneNum RETRY Retries DELAY RetryDelay Retries DELAY PhoneNum RETRY DEFAULTSESSIONHANDLE ( ) DEFAULTSESSIONHANDLE BUTTON DIALOG CANCEL CHECKBOX ( CHECKBOX DIALOG CONTROL Update Attribute Value DIMENSION Control INSTRUCT INSTRUCT TO StrucTableNum REPLY TABLE FROM StrucTableNum REQUEST TABLE AS Format Format WHEN ADVISE Index WHEN EXECUTE WHEN INITIATE Table WHEN POKE Index TABLE WHEN TERMINATE DEBUG FileName IntVar DECREMENT (EncryptedString, Key) DECRYPT MBoolean NOFOCUS FBoolean Statement Syntax Statement CURSOR ( ( DATE ACCESS Server Topic ACCESS CANCEL ADVISE ( ) TO POKE Data FROM DataVar REQUEST TO SEND StrucTableNum TABLE SIGNAL WAIT Index WHEN REQUEST continued continued
(DIALOG) DIMENSION DEFAULTSESSIONHANDLE ( ) DEFAULTSESSIONHANDLE DIAL* DIAL DIALOG DIALOG (DIALOG) BUTTON DIALOG CANCEL (DIALOG) CHECKBOX ( ) (DIALOG) CHECKBOX DIALOG CONTROL* (DDE) WHEN ADVISE (DDE) WHEN EXECUTE (DDE) WHEN INITIATE (DDE) WHEN POKE (DDE) WHEN REQUEST (DDE) WHEN TERMINATE DEBUG DECREMENT ( ) DECRYPT (DDE) INSTRUCT (DDE) POKE (DDE) REQUEST REPLY TABLE (DDE) REQUEST TABLE (DDE) SEND TABLE (DDE) SIGNAL (DDE) WAIT CURSOR ( ) ) ( DATE (DDE) ACCESS CANCEL ACCESS (DDE) ( ) ADVISE (DDE) Command/Function Name Command/Function —D— Syntax Quick Reference, Quick Reference, Syntax
Syntax Quick Reference, continued
Command/Function Name Statement Syntax
(DIALOG) EDITTEXT ( ) EDITTEXT (ControlNum, DialogIndex) (DIALOG) EDITTEXT EDITTEXT (x, y, w, h) Box Prompt Text LIMIT NumChars PASSWORD (DIALOG) GROUPBOX GROUPBOX (x, y, w, h) Message (DIALOG) ICON ICON (x, y, w, h) IconId (DIALOG) ICONBUTTON ICONBUTTON (x, y, w, h) IconId Default Title Command (DIALOG) LISTBOX ( ) LISTBOX (ControlNum, DialogIndex) (DIALOG) LISTBOX LISTBOX (x, y, w, h) Table Record INVERT COMBOBOX Command (DIALOG) MESSAGE MESSAGE (x, y, w, h) Text (DIALOG) MESSAGEBOX ( ) MESSAGEBOX (Message, Title, Style) (DIALOG) NEWLINE NEWLINE (DIALOG) PICTURE PICTURE (x, y, w, h) PictureId (DIALOG) RADIOBUTTON RADIOBUTTON (x, y, w, h) ButtonName (DIALOG) RADIOGROUP ( ) RADIOGROUP (ControlNum, DialogIndex) (DIALOG) RADIOGROUP RADIOGROUP (x, y, w, h) Default GroupName Command DIALOG UPDATE DIALOG UPDATE DialogIndex Control ControlNum Update DIALOGHANDLE ( ) DIALOGHANDLE (Index) DIRECTORY ( ) DIRECTORY (Type) DISCONNECT DISCONNECT WINDOW WinHandle DISKSPACE ( ) DISKSPACE (Drive) DISPLAY DISPLAY (Row, Col) String CRONLY WINDOW WinHandle DISPLAYCONFIG DISPLAYCONFIG String WINDOW WinHandle DROPDTR* DROPDTR DelayUnits
—E— EDIT COPY EDIT COPY String WINDOW WinHandle EDIT COPYSPECIAL* EDIT COPYSPECIAL Destination Format WINDOW WinHandle EDIT CUT EDIT CUT WINDOW WinHandle
DCS Script Language Reference EDIT FIND EDIT FIND String CASE REVERSE WINDOW WinHandle EDIT GOTO EDIT GOTO Line WINDOW WinHandle 606 C Command and Function Syntax Quick Reference 607
) AS Dest AS Hostname ) APPEND CASE REVERSE TYPE Type DEFAULT DEFAULT TYPE Type
, ReplaceChars ) TYPE Type DEFAULT String DEFAULT Type TYPE BINARY FileName BINARY WinHandle
, WinHandle BINARY FileName BINARY WINDOW WinHandle
, WinHandle REMOTE WINDOW WINDOW WinHandle WINDOW WinHandle
REMOTE FILE SEND APPEND WINDOW CRLF NOCRLF ASCII BINARY WinHandle FILESIZE (FileName) (String, SearchChars FILTER FKEYS Display (Field FLDATTR FILE CLOSE FILE COMPRESS FileName Destination TO Source FILE COPY FileName FILE CREATENAME NOCREATE String TITLE TitleText FILE DECOMPRESS FileName FileName Key FILE DECRYPT FILE DELETE FileName FileName Key FILE ENCRYPT OPENNAME FileName FILE TITLE TitleText FILE PAUSE FILE RECEIVE APPEND CRLF NOCRLF NEITHER ASCII BINARY WINDOW WinHandle Destination TO FILE RENAME Source FILE RESUME Statement Syntax PASTE EDIT String2 REPLACE String1 EDIT WINDOW WinHandle EMULCONFIG String Key) (OrigString, ENCRYPT EOF ( ) ERROR ( ) EXECUTE Target (FieldNum EXFLDATTR EXISTS (FileName) continued continued
*
FLDATTR ( ) FLDATTR FILE RECEIVE BINARY FILE RENAME FILE RESUME* FILE SEND BINARY FILESIZE ( ) ( ) FILTER FKEYS FILE CREATENAME FILE DECOMPRESS FILE DECRYPT FILE DELETE FILE ENCRYPT FILE OPENNAME FILE PAUSE* EOF ( ) ERROR ( ) EXECUTE ( ) EXFLDATTR EXISTS ( ) FILE CLOSE FILE COMPRESS FILE COPY PASTE EDIT REPLACE EDIT EMULCONFIG ) ( ENCRYPT END END —F— Command/Function Name Command/Function Name Syntax Quick Reference, Quick Reference, Syntax
Syntax Quick Reference, continued
Command/Function Name Statement Syntax
FLDATTREXPOS ( ) FLDATTREXPOS (Row, Column, WinHandle) FLDLEN ( ) FLDLEN (Field, WinHandle) FLDNUM ( ) FLDNUM (Row, Column, WinHandle) FLDPOS ( ) FLDPOS (Field, WinHandle)
—G— GENERALCONFIG GENERALCONFIG String WINDOW WinHandle GETAPPCONFIG ( ) GETAPPCONFIG (KeyString) GETCONNCONFIG ( ) GETCONNCONFIG (KeyString, WinHandle) GETDISPLAYCONFIG ( ) GETDISPLAYCONFIG (KeyString, WinHandle) GETEMULCONFIG ( ) GETEMULCONFIG (KeyString, WinHandle) GETGENERALCONFIG ( ) GETGENERALCONFIG(KeyString, WinHandle) GETPROFILEDATA ( ) GETPROFILEDATA (Section, KeyName, INIFile) GETXFERCONFIG ( ) GETXFERCONFIG (KeyString, WinHandle) GOTO GOTO Target
—H— HANGUP* HANGUP WINDOW WinHandle HWNDLIST ( ) HWNDLIST (NumWin)
—I— ICONIC ( ) ICONIC (WinHandle) IF IF Boolean Command ELSE Command INCREMENT INCREMENT IntVar INT ( ) INT (RealNum)
—K— KERMIT COPY* KERMIT COPY SourceFile TO DestinationFile WINDOW WinHandle KERMIT DIRECTORY* KERMIT DIRECTORY DirectoryName WINDOW WinHandle KERMIT ERASE* KERMIT ERASE FileName WINDOW WinHandle KERMIT FINISH* KERMIT FINISH WINDOW WinHandle KERMIT FREESPACE* KERMIT FREESPACE WINDOW WinHandle KERMIT HELP* KERMIT HELP HelpTopic WINDOW WinHandle DCS Script Language Reference KERMIT LOGOUT* KERMIT LOGOUT WINDOW WinHandle
608 C Command and Function Syntax Quick Reference 609
Enabled (Parameter, (Parameter, WINDOW
WINDOW WinHandle LibraryReference WINDOW WinHandle
WINDOW WinHandle
Command, ... ContinueScript WINDOW WinHandle Key1 Definition UserName WINDOW WinHandle Command FileName
Modifier1 CHECKED (Popup, Item) MENU DELETE ITEM IntPopup IntItem IntPopup MENU DELETE POPUP ENABLED (Popup, Item) ITEM IntPopup IntItem StrText MENU INSERT Checked KEYMAP RESET KEYMAP FileName SAVE KEYMAP LAUNCH Application LEAVE LENGTH (String) KeyLevel LEVEL LibraryReference Procedure CALL LIBRARY …) LOAD LibraryName LIBRARY UNLOAD LibraryReference LIBRARY LINENUMBERS LOAD FileName LOGTOFILE MENU MENU CANCEL Statement Syntax MessageText MESSAGE ReceiverName KERMIT WINDOW WinHandle DirectoryName NEWDIRECTORY KERMIT WinHandle NewFileName TO RENAME OldFileName KERMIT WINDOW WinHandle TYPE KERMIT FileName WHO KERMIT KEY KEYBOARD State LOAD FileName KEYMAP continued continued
MENU MENU CANCEL (MENU) CHECKED ( ) (MENU) DELETE ITEM (MENU) DELETE POPUP (MENU) ENABLED ( ) ITEM (MENU) INSERT LEAVE LENGTH ( ) LEVEL CALL LIBRARY LOAD LIBRARY UNLOAD LIBRARY LINENUMBERS LOAD LOGTOFILE KERMIT WHO* KERMIT KEY KEYBOARD LOAD KEYMAP RESET KEYMAP SAVE KEYMAP LAUNCH KERMIT MESSAGE* KERMIT NEWDIRECTORY* KERMIT RENAME* KERMIT TYPE* KERMIT —M— —L— Command/Function Name Command/Function Name Syntax Quick Reference, Quick Reference, Syntax
Syntax Quick Reference, continued
Command/Function Name Statement Syntax
(MENU) INSERT POPUP MENU INSERT POPUP IntPopup StrText (MENU) ITEM ITEM Text Enabled Checked Command, ... (MENU) POPUP POPUP Text SYSTEM Pos (MENU) SEPARATOR SEPARATOR MENU UPDATE MENU UPDATE Popup Item Text Enabled Checked
—N— NETID ( )* NETID ( ) NEXT ( ) NEXT ( ) NOSHOW NOSHOW NUM ( ) NUM (String)
—O— ORD ( ) ORD (String)
—P— PARSE PARSE String StringVar1 Keyword StringVar2 PASSWORD ( )* PASSWORD ( ) PERFORM PERFORM Target (Parameter, ...) PHONENUMBER ( )* PHONENUMBER ( ) POS ( ) POS (String, Keyword, Start) POSITION ( ) POSITION (WinHandle, Boolean) POWER ( ) POWER (Base, Exponent) PRINT CANCEL PRINT CANCEL PRINT CLOSE PRINT CLOSE PRINT FILE PRINT FILE FileName LF PRINT FONT PRINT FONT Font Point PRINT NEWLINE PRINT NEWLINE PRINT NEWPAGE PRINT NEWPAGE PRINT OPEN PRINT OPEN PORT Port DRIVER Driver TYPE Type ABORT PRINT STRING PRINT STRING String PRINT STYLE PRINT STYLE Attribute ... PRINT TABS PRINT TABS Width
DCS Script Language Reference PRINT TERMINAL* PRINT TERMINAL State WINDOW WinHandle PRTMETRICS ( ) PRTMETRICS ( ) 610 C Command and Function Syntax Quick Reference 611 ) ) n ) , WinHandle ) AT Position LENGTH AT
String ) WINDOW WinHandle ) (Row1 Col1) ... (Rown Col
AT Record AT )
WINDOW WinHandle AT Record AT Position LENGTH AT Record AT fields
, ATTRIBUTES Type , ATTRIBUTES (TopRow, BottomRow, LeftCol, BottomRow, (TopRow, , WinHandle , Column, Length, WinHandle , Places, Boolean Time, Date Time, Row, Column, Length, Row, (x, y, w, h) Display WINDOW WinHandle w, (x, y, SCREEN (Row SEARCH ( SEARCHINRECT RightCol, String SECONDS ( SELECTION StartLine EndLine RECORD SCAN Table RECORD WRITE Table Bytes Path REMOVE DIRECTORY RESETSERIAL RESTART ( ) RESULT RESUME RETURN ROUND (Real ROUTE (FileSpec FileName SAVE SCREEN DOWN Rows SCROLL Columns LEFT SCROLL Columns RIGHT SCROLL Rows UP SCROLL Statement Syntax File) (Section, KeyName, Data, PUTPROFILEDATA QUIT RANDOM (Range) (Numeric) REAL Lines RECORD FORMAT WINDOW WinHandle RECORD READ Table Bytes continued continued
SELECTION SCREEN ( ) SCREEN DOWN SCROLL LEFT SCROLL RIGHT SCROLL UP SCROLL SEARCH ( ) ( ) SEARCHINRECT SECONDS ( ) RESTART ( ) RESULT RESUME RETURN ROUND ( ) ROUTE ( ) SAVE REAL ( ) REAL RECORD FORMAT RECORD READ RECORD SCAN RECORD WRITE REMOVE DIRECTORY* RESETSERIAL PUTPROFILEDATA ( ) PUTPROFILEDATA QUIT RANDOM ( ) —S— Command/Function Name Command/Function Name —Q— —R— Syntax Quick Reference, Quick Reference, Syntax
Syntax Quick Reference, continued
Command/Function Name Statement Syntax
SELECTION APPEND SELECTION APPEND FileName TABLE WINDOW Win- Handle SELECTION BUFFER SELECTION BUFFER WINDOW WinHandle SELECTION PRINT SELECTION PRINT WINDOW WinHandle SELECTION SAVE SELECTION SAVE FileName TABLE WINDOW WinHandle SELECTION SEND SELECTION SEND WINDOW WinHandle SEND SEND (Row, Col) NOCR String ONEPACKET WAITECHO WINDOW WinHandle SENDBREAK* SENDBREAK DelayUnits SET SET Variable Source SET APPTITLE SET APPTITLE Name SET ATTRIBUTES SET ATTRIBUTES FileName Attribute SET AUTOSCROLLTOCURSOR SET AUTOSCROLLTOCURSOR Boolean SET AUTOSIZE* SET AUTOSIZE Boolean SET BACKSPACEDESTRUCTIVE* SET BACKSPACEDESTRUCTIVE Boolean SET BACKSPACEKEY* SET BACKSPACEKEY Keyword SET BAUDRATE* SET BAUDRATE Rate
SET BINARYTRANSFERPARAMS* SET BINARYTRANSFERPARAMS OptionKeyWord ActionKey- Word OptionKeyWord ActionKeyWord… SET BINARYTRANSFERS SET BINARYTRANSFERS Protocol WINDOW WinHandle SET BUFFERLINES SET BUFFERLINES Lines SET CARRIERDETECT* SET CARRIERDETECT Boolean SET COLUMNS SET COLUMNS Integer SET CONNECTION* SET CONNECTION Connector Command WINDOW WinHandle SET CONNECTMESSAGE* SET CONNECTMESSAGE Text SET CONNECTRESULT* SET CONNECTRESULT Num SET CURSOR SET CURSOR Display SET DATABITS* SET DATABITS Integer SET DDETIMEOUT SET DDETIMEOUT Seconds SET DECIMAL SET DECIMAL Numeric SET DEFAULTSESSIONHANDLE SET DEFAULTSESSIONHANDLE WinHandle
DCS Script Language Reference SET DIRECTORY SET DIRECTORY Type CREATE Path SET EMULATION* SET EMULATION Emulation WINDOW WinHandle 612 SET FKEYSSHOW SET FKEYSSHOW Boolean C Command and Function Syntax Quick Reference 613 WINDOW
) ) WINDOW WinHandle WINDOW WinHandle
) , Length Str2 WINDOW WinHandle WINDOW WinHandle
, WinHandle WINDOW WinHandle Target Target , Precision SAFE SETTINGS (Keyword SPAWN STR (Numeric SUBSTR (String, Start SET SENDDELAY Delay SENDDELAY SET Boolean SIGNAL SET SOUND Boolean SET Numeric STOPBITS SET TERMCLOSE SET Boolean FontName SizeX SizeY TERMFONT SET WinHandle Text USERID SET WILDCARD Str1 SET WINDOWTITLE String SET Column WORDWRAP SET Time XCLOCK SET Time XSYSTEM SET WINDOW WinHandle Tab SETTINGS SHOW Statement Syntax Type SET FLOWCONTROL KBoolean KEEPPRINTCHANNELOPEN SET LOCALECHO Boolean SET SET NETID Text OUTGOINGCR Option SET Type SET PARITY State PASSTHROUGH SET Text SET PASSWORD PHONENUMBER PhoneNumber SET String RESULT SET Boolean RETRY SET Delay RETRYDELAY SET continued continued
SETTINGS ( ) SETTINGS SHOW SPAWN STR ( ) SUBSTR ( ) STOPBITS* SET TERMCLOSE SET TERMFONT SET USERID* SET WILDCARD* SET WINDOWTITLE SET WORDWRAP* SET XCLOCK SET XSYSTEM SET PASSTHROUGH* SET PASSWORD* SET PHONENUMBER* SET RESULT SET RETRY* SET RETRYDELAY* SET SENDDELAY SET SIGNAL* SET SOUND SET SET FLOWCONTROL* SET KEEPPRINTCHANNELOPEN SET LOCALECHO* SET NETID* SET OUTGOINGCR* SET PARITY* SET Command/Function Name Command/Function Name Syntax Quick Reference, Quick Reference, Syntax
Syntax Quick Reference, continued
Command/Function Name Statement Syntax
SWITCH SWITCH SwitchVariable CASE Var1: Command LEAVE CASE Var2: Command LEAVE DEFAULT: Command LEAVE SWITCH END SYSMETRICS ( ) SYSMETRICS ( ) SYSTEM ( )* SYSTEM (SysNum P1, P2) SYSTEM* SYSTEM SysNum P1, P2, …
—T— TABLE CLEAR TABLE CLEAR Table TABLE CLOSE TABLE CLOSE Table TABLE COPY TABLE COPY SourceTable TO DestTable Contents String TABLE DEFINE TABLE DEFINE Table FIELDS f1...fiFILE TEXT FileName TABLE LOAD TABLE LOAD Table FROM Source AS Format TABLE SAVE TABLE LOAD Table FROM Source AS Format TABLE SORT TABLE SORT Table Fld1 Dir1 Fld2 Dir2 Fld3 Dir3 TASKERROR TASKERROR Level Code TIME ( ) TIME (Seconds) TIMER ( ) TIMER (Index) TIMER RESET TIMER RESET Timer TITLE TITLE String TOOLBARHIDE TOOLBARHIDE BarName TOOLBARSHOW TOOLBARSHOW BarName DCS Script Language Reference
614 C Command and Function Syntax Quick Reference 615 Command ) n WINDOW WinHandle WINDOW WinHandle WINDOW WinHandle
) WINDOW WinHandle (LibName, ProcName, TypeString, (LibName, ProcName, TypeString, QUIET Time Window WinHandle Window QUIET Time WINDOW WinHandle CommandType WINDOW WinHandle WINDOW WinHandle CommandProcessor BLOCKSIZE CommandProcessor WINDOW WinHandle , Pre, Post h) FileName w, (x, y, WAIT RESUME WAIT SCREEN WAIT STRING String WAIT Time UNTIL WAIT WHEN CANCEL ToStr FromStr Index OnStr OffStr WHEN COLLECT NOTTERMINAL Quiet limit SAVECR WaitExclude WINDOW WinHandle WHEN ECHO StringVar VISIBLE (WinHandle) CHAR Character WAIT CLOSE WAIT Time DELAY WAIT ECHO WAIT NumChar PROMPT WAIT Time QUIET WAIT WINDOW WinHandle Command WHEN DISCONNECT Statement Syntax Status PACKETSIZE Status Length ISSUECLEAR FileName RECORDLENGTH Number HOSTPROGRAM Status SPACE Type Status Length RECORDFORMAT CPUUSAGE UNITS Type AddedSpace InitialSpace Country Number HOSTCODEPAGE Number TIMEOUT Country WINDOW WinHandle PCCODEPAGE TRIM (String TYPEDLIBRARYCALL Param1, Param2, ..., Param UPPER (String) USERID ( ) VERSION ( ) EDIT WAIT continued continued
*
WHEN ECHO WAIT RESUME WAIT SCREEN WAIT STRING* WAIT UNTIL WAIT WHEN CANCEL WHEN COLLECT WHEN DISCONNECT VISIBLE ( ) CHAR WAIT CLOSE* WAIT DELAY WAIT ECHO WAIT EDIT WAIT PROMPT* WAIT QUIET WAIT TRIM ( ) ( ) TYPEDLIBRARYCALL UPPER ( ) USERID ( )* VERSION ( ) TRANSFERS TRANSFERS —W— —U— —V— Command/Function Name Command/Function Name Syntax Quick Reference, Quick Reference, Syntax
Syntax Quick Reference, continued
Command/Function Name Statement Syntax
WHEN ERROR WHEN ERROR LevelNum Command WHEN INPUT WHEN INPUT StringVar WINDOW WinHandle Command WHEN QUIET WHEN QUIET Time WINDOW WinHandle Command WHEN SCREEN WHEN SCREEN Index (Row, Col, Wid, Lns) WINDOW WinHandle Command WHEN STRING* WHEN STRING Index String WINDOW WinHandle Command WHEN TIMER WHEN TIMER Time Command WHEN WINDOW* WHEN WINDOW WinHandleVar Message WParam LParam WHILE WHILE Boolean Command WINDOW ( ) WINDOW (WinHandle) WINDOWHND ( ) WINDOWHND (WinName) WINDOWNAME ( ) WINDOWNAME (WinHandle) WINDOW ACTIVATE WINDOW ACTIVATE WinHandle Boolean WINDOW ARRANGE WINDOW ARRANGE WINDOW CLOSE WINDOW CLOSE WinHandle WINDOW DEFAULT WINDOW DEFAULT WinHandle Message WParam LParam WINDOW HIDE WINDOW HIDE WinHandle WINDOW MAXIMIZE WINDOW MAXIMIZE WinHandle WINDOW MESSAGE WINDOW MESSAGE WinHandle Message WParam LParam WINDOW MINIMIZE WINDOW MINIMIZE WinHandle WINDOW MOVE WINDOW MOVE WinHandle (x, y, w, h) WINDOW OPEN WINDOW OPEN Type FileName (x, y, w, h) Boolean WinHandle WINDOW RESTORE WINDOW RESTORE WinHandle WINDOW STACK WINDOW STACK WINDOW UNHIDE WINDOW UNHIDE WinHandle WNDCLASS ( ) WNDCLASS (WinHandle) WNDFILE ( ) WNDFILE (WinHandle) WNDTITLE ( ) WNDTITLE (WinHandle) DCS Script Language Reference
616 C Command and Function Syntax Quick Reference 617 WINDOW WinHandle Statement Syntax XFERCONFIG String ZOOMED (WinHandle) continued continued
XFERCONFIG ZOOMED ( ) Command/Function Name Command/Function Name —X— —Z— Syntax Quick Reference, Quick Reference, Syntax
DCS Script Language Reference
618 Index
in relational expressions 40 precedence 58 Index statement syntax 55 >= (greater than or equal to) in relational expressions 40 precedence 58 statement syntax 56 Symbols < (less than) in relational expressions 40 3270 emulations precedence 58 , , field attributes, retrieving 129 138 140 statement syntax 55 field identifier, retrieving 142 <= (less than or equal to) field length, retrieving 141 in relational expressions 58 field starting position, retrieving 143 precedence 58 XCLOCK messages 514 statement syntax 56 XSYSTEM messages 515 % (modulus operator) $ (dollar sign) precedence 58 named string variables 27 statement syntax 55 statement syntax 51 use of 38 + (addition operator or plus sign) * (multiplication operator) precedence 58 precedence 58 statement syntax 54 statement syntax 54 use of 38 use of 38 = (assignment operator) != (not equal to) statement syntax 55 in relational expressions 40 use of 47 precedence 58 * (asterisk) statement syntax 56 label statement syntax 49 <> (not equal to) use of 25 in relational expressions 40 @ (at sign) precedence 58 use of 50 statement syntax 56 \ (backslash) # (number sign) embedding control characters in a string 27 statement syntax 51 statement syntax 50 use of 40, 348, 355 use of 23 = or == (equal to) .bmp files. See bitmap graphics. in relational expressions 40 ^ (caret) precedence 58 embedding control characters in a string 27 statement syntax 55 statement syntax 50 ( ) (parentheses) : (colon) precedence 58 use of 50 statement syntax 51 , (comma) use of 51 statement syntax 51 % (percent sign) use of 23 statement syntax 52 | (concatenation operator) use of 37 creating string expressions with 35 . (period) statement syntax 58 use of and statement syntax 52 use of 23 ? (question mark) .dcp (source script file), defined 17 use of and statement syntax 52 .dct (task script file), defined 17 " (quotation mark) / (division operator) embedding in a string 27 precedence 58 null string, creating 27 statement syntax 54 statement syntax 52 use of 38 @R (Record Buffer variable) ! (exclamation point) statement syntax 50, 66, 68 statement syntax 51 use of 28 use of 37 ; (semicolon) @F (Function key variable) use of 24, 53 Index statement syntax 50 ' (single quote) 52 use of 32 @S (Settings variable) > (greater than) statement syntax 50 use of 34 619 - (subtraction operator) in CHR function 105 precedence 58 assigning values to variables 47, 59 statement syntax 54 assignment commands, grouped 227 use of 38 assignment operator (=) @T (Function Key Title variable) defined 21 statement syntax 50 precedence 58 use of 32 use of 47 - (unary minus) asterisk (*) precedence 58 as modulus operator 38 use of 37 label statement syntax 49 .wmf files. See Windows metafile graphics. use of 25 AT&T emulations, configuring. See emulation configura- tion. attributes A of fields, retrieving 129, 138, 140 of files, retrieving 97 ACCESS CANCEL (DDE command). See (DDE) AC- ATTRIBUTES function 97 CESS CANCEL command. autosizing font 468 . ACCESS (DDE command) See (DDE) ACCESS com- autostart script, defined and use of 17 mand. ACTIVE function 96 active session, defined 74 active window, defined 74 B addition operator (+) backslash (\) precedence 58 embedding control characters 27 statement syntax 54 statement syntax 50 use of 38 use of 23 . ADDS emulation, configuring. See emulation configura- backspace key, setting 469, 470 tion. BAND function 98 advise message baud rate, setting 471 determining reception of 112 BEEP command 243 servicing requests via script 270 BEGIN command 244 AND (Boolean operator) example of 22, 45, 106, 501 precedence 58 bell (host), enabled state 506 use of 57 bell (PC), ringing via script 243 AND function. See BAND function. bitmap graphics ANSI emulation, configuring. See emulation configura- adding to scripted dialog boxes 311 tion. copyig to a printer 325 API (Application Programming Interface) calls 203 copying to the clipboard 325 APPCONFIG command 240–241 bitwise appending selected text to a file 453 AND operation 98 application configuration 85 complement operation 99 , applications, launching via script 393 OR operation 101 104 99 application title, setting 465 BNOT function arguments Boolean constants, statement syntax and use of 40 Command 22 Boolean expressions definition 20 definition and use of 41 field 28, 31 parameters, passing 61 file names 43 Boolean functions Function 51 definition and use of 40 Key 32 grouped 92 Numeric 43 Boolean modifiers 57 Table 28, 31, 43, 64, 67 Boolean operators types 43 AND 57 valid content type 20 NOT 57 WinHandle 74 OR 57 ARGUMENTS command 242 use of 41 creating variables 47, 62 Booleans example of 61, 63 complex 42 , , argument types 43 Boolean value 100 107 112
DCS Script Language Reference ASCII characters Boolean variables, named , , converted to 346 definition and use of 40 47 48 embedding 27, 50 parameters, passing 62 BOOL function 100 620 BOR function 101 combo boxes. See list boxes. branching commands, grouped 227 comma (,) BREAK command 245 statement syntax 51 use of 33 use of 23 break, sending to a host 463 command block 51 break signal, sending via script 245 defined and use of 22 BUFFER function 102 command block commands, grouped 228 buffer, session. See history buffer. command blocks BUTTON (Dialog command). See (DIALOG) BUTTON beginning 244 command. branching to multiple 519 buttons (in scripted dialog boxes) ending 343 creating 291 for scripted menus 405 positioning and sizing 300 commands updating attributes 296, 315 assignment operations, grouped 227 BXOR function 104 branching operations, grouped 227 command block operations, grouped 228 conditional operations, grouped 227 configuration operations, grouped 228 C continuing on another line 23 conversion operations, grouped 229 246 CANCEL command data and file transfer operations, grouped 229 example of 56 DDE operations, grouped 231 capturing data, functions for 92 defined 20 capturing incoming data, command 248 dialog operations, grouped 230 caret (^) DLL operations, grouped 231 embedding control characters, used to 27 edit operations, grouped 231 statement syntax 50 file operations, grouped 232 carriage return, outgoing 496 listed with brief explanations 217, 604 carrier detection 476 math operations, grouped 233 cascading windows 586 menu operations, grouped 233 channel numbers (DDE) 80 multiple on the same line 23 characters network operations, grouped 233 copying to new to DCS, listed 600 a file 325 print operations, grouped 234 a printer 325 removed from DCS, listed 601 the clipboard 324 script control operations, grouped 234 displaying in a session window 319 session window operations, grouped 235 echo in session, detecting 548 string operations, grouped 235 print attributes 431 subroutine operations, grouped 227 removing from a string 202 system operations, grouped 236 replacing in a string 136 table operations, grouped 236 , waiting for specified 544 548 telecommunications operations, grouped 237 CHECKBOX (Dialog command). See (DIALOG) CHECK- toolbar operations, grouped 233 BOX command. command syntax 20 check boxes (in scripted dialog boxes) comments, defined and syntax 24 creating 294 COMPILE command 251 determining status of 116 compiling scripts 17 positioning and sizing 300 caution note 19 updating attributes 296, 315 errors 19 child routine, defined 59 via script 251 child windows 110 complex CHR function 105–106 Booleans 42 example of 105 numeric variable, defined and use of 38 CLEAR command 247 string clipboard creating 27 copying characters to 324 defined and use of 36 copying graphics to 325 compressing files 346 cutting to 328 CONCAT command 252
pasting text from 331 concatenation Index COLLECT command 248–250 of strings via script 36, 252 example of 47 concatenation operator (|) use of 47 statement syntax 58 colon (:), definition and use of 50 use of 23 column width, setting 477 conditional branching, event-based 76 621 conditional commands, grouped 227 data configuration commands, grouped 228 receiving from DDE server 268 configuration functions, grouped 92 retrieving from screen display 102, 178 configuring searching and capturing functions, grouped 92 application options via script 240 sending to DDE server 264 applications 85 data bits, setting 483 connectors 84 data items (DDE) 80 connectors via script 253, 478 data manipulation through tables 64 displays 84 data types 28 displays via script 321 DATE function 111 emulations 84 date, retrieving 111 emulations via script 334, 488 DCS file transfers 84 terminating via script 434 file transfers via script 472, 474, 539, 588 version number, retrieving 207 menus 85 DDE. See DDE (Dynamic Data Exchange). sessions 84 (DDE) ACCESS CANCEL command 262 sessions via script 516 (DDE) ACCESS command 260–261 toolbar 85 example of 81 253–255 CONNCONFIG command use of 80 256–257 CONNECT command (DDE) ADVISE function 112 example of 56 DDE (Dynamic Data Exchange) use of 74 canceling wait state 557 107 CONNECT function commands, grouped 231 connecting a session via script 256 commands, sending to server 263 connection status, determining 107 concepts and use of 78 connection termination, detecting 561 conversation initiation, detecting 275 108 CONNECTMESSAGE function conversation termination, detecting 280 ConnectMessage system variable data retrieving current value 108 receiving from a server 265 setting 480 sending to server 264 , connector configuration 84 478 DCS server name 79 command and keywords 253 events, detecting 275, 276, 278, 280 retrieving current settings 146 functions, grouped 93 109 CONNECTRESULT function initiating via script 260 ConnectResult system variable maximum number of channels 80 retrieving current value 109 overview of 78 setting 481 servicing requests 271, 273, 276, 278 constant statement syntax for messages 81 Boolean 40 structured table numeric 37 sending to server 266, 269 258 CONTINUE command storing received data 268 continuing, line 23 terminating via script 262 control characters wait signal 270 defined 43 (DDE) INSTRUCT command 263 embedding in a string 27 example of 81 conversion commands, grouped 229 (DDE) POKE command 264 conversion functions, grouped 92 use of 80 conversion of scripts 84 (DDE) REQUEST command 265 converting numeric variables 37 use of 47, 80 copying (DDE) TABLE REPLY command 266–267 characters to clipboard 325 (DDE) TABLE REQUEST command 268 files 347 use of 80 259 CREATE DIRECTORY command (DDE) TABLE SEND command 269 critical errors 82 use of 80 cursor (DDE) WAIT SIGNAL command 270 appearance, setting 482 (DDE) WHEN ADVISE command 271–272 automatic scrolling to, setting 467 (DDE) WHEN EXECUTE command 273–274 positioning at beginning of line 330 (DDE) WHEN INITIATE command 275 110 CURSOR function use of 80 cursor position 110 (DDE) WHEN POKE command 276–277 cutting to the clipboard 328 (DDE) WHEN REQUEST command 278–279 DCS Script Language Reference (DDE) WHEN TERMINATE command 280 DEBUG command 281–282 D debug window 622 hiding 419 updating attributes 296, 315 showing 517 icons decimal places, setting 485 creating 304 decompressing files 351 positioning and sizing 300 DECREMENT command 283 updating attributes 296, 315 DECRYPT function 113–114 line spaces, adding 310 decrypting files 352 list boxes default directories, listed 123 creating 307 DEFAULTSESSIONHANDLE function 115 positioning and sizing 300 and multiple concurrent scripts 74 updating attributes 296, 315 use of 75 messages default session window handle, setting 486 creating 309 delaying script execution 546 positioning and sizing 300 during memo editing 549 updating attributes 296, 315 waiting for a string 555 modal vs. non-modal 287 waiting for period of inactivity 551 radio buttons waiting for RESUME command 553 creating 312 waiting for screen refresh 554 positioning and sizing 300 waiting for specified file to close 545 updating attributes 296, 315 waiting for specified number of characters 550 radio groups waiting for specified time of day 556 creating 313 destination argument. See file name arguments. positioning and sizing 300 , detecting events during script execution 76 updating attributes 296 315 dial title bar and control menu 286 retries, setting 502 updating controls 296 , retry delay, setting 503 widebuttons, updating attributes 296 315 signal, setting 505 Windows metafile graphics DIAL command 284–285 adding 311 example of 500, 502 updating 315 291–292 use of 35 (DIALOG) BUTTON command 293 dialog boxes, scripted DIALOG CANCEL command as child routines 59 example of 35 294–295 bitmap graphics (DIALOG) CHECKBOX command 116 adding 311 (DIALOG) CHECKBOX function 286–290 updating 315 DIALOG command buttons dialog commands creating 291 grouped 230 positioning and sizing 300 used in command blocks 22 296–299 updating attributes 296, 315 DIALOG CONTROL command 300 check boxes (DIALOG) DIMENSION command 301–302 creating 294 (DIALOG) EDITTEXT command positioning and sizing 300 example of 35 117 updating attributes 296, 315 (DIALOG) EDITTEXT function controls dialog functions, grouped 93 303 creating 307 (DIALOG) GROUPBOX command 122 maximum number of 288 DIALOGHANDLE 305–306 updating 296–299, 315 (DIALOG) ICONBUTTON command 304 creating (command structure) 286 (DIALOG) ICON command 307–308 destroying 293 (DIALOG) LISTBOX command 118 displaying (DIALOG) LISTBOX function 119–120 pictures 311 (DIALOG) MESSAGEBOX function 309 text 309 (DIALOG) MESSAGE command 310 edit text boxes (DIALOG) NEWLINE command 311 creating 301 (DIALOG) PICTURE command 312 positioning and sizing 300 (DIALOG) RADIOBUTTON command 313–314 updating attributes 296, 315 (DIALOG) RADIOGROUP command 121 group boxes (DIALOG) RADIOGROUP function creating 303 dialogs, Script Compiler 19 315–317 positioning and sizing 300 DIALOG UPDATE command Index updating attributes 296, 315 Digital VT emulations, configuring. See emulation con- icon buttons figuration. creating 305 DIMENSION (Dialog command). See (DIALOG) DIMEN- positioning and sizing 300 SION command. 623 dimensions, window, retrieving 167 EDIT CUT command 328 directories EDIT FIND command 329 creating via script 259 EDIT GOTO command 330 default paths, listed 123 editing scripts 18 default paths, setting 487 EDIT PASTE command 331 deleting 441 EDIT REPLACE command 332–333 DIRECTORY function 123–124 edit text boxes (in scripted dialog boxes) example of 97 creating 301 Direct Serial connector. See also connector configura- postioning and sizing 300 tion. retrieving contents of 117 , baud rate, setting 471 updating attributes 296 315 data bits, setting 483 EDITTEXT (Dialog command). See (DIALOG) EDIT- dialing via script 284 TEXT command. flowcontrol, setting 491 ELSE clause parity, setting 497 example of 23 stopbits, setting 507 used in command blocks 22 direct variables, defined and use of 47 embedding characters in a string 27 DISCONNECT command 318 emulation configuration 84, 488 disconnecting a session 318 command and keywords 334 disk space, determining free remaining 194 retrieving current settings 148 DISKSPACE function 125 EMULCONFIG command 334–342 DISPLAY command 319–320 encrypted strings, decrypting 113 example of 22, 31, 41, 45, 106, 109 ENCRYPT function 126 use of 47 encrypting 126 DISPLAYCONFIG command 321–322 encrypting files 354 display configuration 84 encryption key. See ENCRYPT function. autosize font, setting 468 END command 343 command and keywords 321 example of 22, 501 cursor appearance 482 used in command blocks 22 font size, setting 509 end-of-file. See EOF function. font type, setting 509 EOF function 127 local echo, setting 494 example of 45, 46, 57 retrieving current settings 147 equal to operator (= or ==) displaying characters in a session window 319 in relational expressions 40 division operator (/) precedence 58 precedence 58 statement syntax 55 statement syntax 54 error detection 563 use of 38 ERROR function 128 DLL (Dynamic Link Library) example of 46, 49 API calls, retrieving values 203 returns 97, 107, 110 calling 397 use of 82 commands, grouped 231 . ; loading 400 error numbers See also TASKERROR command. unloading 401 See task errors. dollar sign ($) errors 82 named string variables 27 errors, determining occurrence of 128 statement syntax 51 escape sequences, representing in a string 27 DROPDTR command 323 evaluation order 51, 55 DTR line 323 event handling, defined and use of 76 , dynamic data exchange. See DDE (Dynamic Data events 76 77 Exchange). exclamation point (!) statement syntax 51 Dynamic Data Exchange (DDE). See DDE (Dynamic use of 37 Data Exchange). EXECUTE command 344 . Dynamic Link Library (DLL) See DLL (Dynamic Link use of 33, 44 Library). executing scripts 18 EXFLDATTR function 129–133 existence of a file, determining 134 E EXISTS function 134 exponential function 168. See POWER function. edit commands, grouped 231
DCS Script Language Reference expressions 324 EDIT COPY command Boolean 41 325–327 EDIT COPYSPECIAL command defined 21 624 described 21 FILE SEND BINARY command 363–365 numeric, creating 38 FILESIZE function 135 relational 40 file transfer commands, grouped 229, 232 string 35 file transfer configuration 84, 474, 539, 588 retrieving current settings 151 word wrap, setting 513 file transfers F configuring 84, 472, 474, 539, 588 receiving binary files 358 far target arguments, definition and use of. See labels. resuming suspended 362 far targets sending binary files 363 definition and use of 45 suspending 357 executing 422 terminating 345 returning from 445 waiting for specified file to close 545 fatal errors 82 FILTER function 136–137 field functions, grouped 93 . fields find or finding See searching. 366 attributes, retrieving 129, 138, 140 FKEYS command 140 defining FLDATTREXPOS function 138–139 for structured tables 64 FLDATTR function 141 for text tables 67 FLDLEN function 142 identifier, retrieving 142 FLDNUM function 143 length, retrieving 141 FLDPOS function starting position, retrieving 143 FLDTEXT function 144 file attributes 97 flow control, setting 491 FILE CLOSE command 345 font configuration. See display configuration. FILE COMPRESS command 346 free disk space, determining 125 FILE COPY command 347 Function Key Title variable (@T) FILE CREATENAME command 348–350 maximum characters 32 use of 47 statement syntax 50 FILE DECOMPRESS command 351 Function Key variable (@F) FILE DECRYPT command 352 example of 50 FILE DELETE command 353 maximum characters 32 FILE ENCRYPT command 354 statement syntax 50 file name arguments, definition and use of 43 functions FILE OPENNAME command 355–356 Boolean 40 use of 47 Boolean operations, grouped 92 FILE PAUSE command 357 configuration operations, grouped 92 FILE RECEIVE BINARY command 358–360 conversion operations, grouped 92 FILE RENAME command 361 data searching and capturing operation, grouped 92 FILE RESUME command 362 DDE operations, grouped 93 files defined 20 appending selected text to 453 dialog opeartions, grouped 93 attributes as numeric values, listed 97 field operations, grouped 93 attributes, setting 466 file operations, grouped 93 commands, grouped 232 listed with brief explanations 88, 604 compressing 346 math operation, grouped 94 copying 347 menu operations, grouped 94 creating 348 new to DCS, listed 600 decrypting 352 numeric 37 deleting 353 removed from DCS, listed 602 encrypting 354 string operations, grouped 94 existence, determining 134 system operations, grouped 94 functions, grouped 93 table operations, grouped 95 logging incoming data to 404 telecommunication operations, grouped 95 name, retrieving from associated window 213 window operations, grouped 95 opening 355, 583 function syntax 20 path names, representing 43 renaming 361 retrieving default path by type 123 Index saving 446 G session, loading 403 GENERALCONFIG command 367–368 size, determining 135 GETAPPCONFIG function 145 uncompressing 351 625 GETCONNCONFIG function 146 INCREMENT command 372 GETDISPLAYCONFIG function 147 example of 22, 31, 48, 70, 106 GETEMULCONFIG function 148 indirect variables, definition and use of 48 GETGENERALCONFIG function 149 initialization files GETPROFILEDATA function 150 creating or changing entries 170 GETXFERCONFIG function 151–152 retrieving entry text 150 GOTO command 369 integer numeric variable example of 23, 46, 107 converting to real variable 37 use of 44 defined 37 greater than operator (>) example of 38 in relational expressions 40 integers precedence 58 converting statement syntax 55 to real numerics 173 greater than or equal to operator (>=) intergers in relational expressions 40 converting precedence 58 from a real numeric 156 statement syntax 56 from a string 163 GROUPBOX (Dialog command). See (DIALOG) to Boolean values 100 156 GROUPBOX command. INT function group boxes (in scripted dialog boxes) use of 37 creating 303 ITEM (Menu command). See (MENU) ITEM command. positioning and sizing 300 updating attributes 296, 315 grouped. See radio groups (in scripted dialog boxes). K keep print channel open, setting 492 H Kermit configuration. See file transfer configuration. KERMIT COPY command 373 HANGUP command 370 KERMIT DIRECTORY command 374 hidden windows, effect on commands 74 KERMIT ERASE command 375 history buffer KERMIT FINISH command 376 saving selected text 456 KERMIT FREESPACE command 377 scrolling KERMIT HELP command 378 down 448 KERMIT LOGOUT command 379 left 449 KERMIT MESSAGE command 380 right 450 KERMIT NEWDIRECTORY command 381 up 451 KERMIT RENAME command 382 selected text, sending 457 KERMIT TYPE command 383 selecting text in 454 KERMIT WHO command 384 size, setting 475 keyboard host cursor position, retrieving 110 input, detecting 564 HWNDLIST function 153–154 remapping via script 385 use of 74 resetting 391 state, resetting 389 KEYBOARD command 389 KEY command 385–388 I example of 105 use of 44 ICONBUTTON (Dialog command). See (DIALOG) ICON- key map files BUTTON command. loading 390 icon buttons (in scripted dialog boxes) resetting 391 creating 305 saving 392 positioning and sizing 300 KEYMAP LOAD command 390 updating attributes 296, 315 KEYMAP RESET command 391 . ICON (Dialog command) See (DIALOG) ICON com- KEYMAP SAVE command 392 mand. keywords 155 ICONIC function CHAR, INT and REAL in TABLE DEFINE command icons (in scripted dialog boxes) 29 creating 304 FILE in TABLE DEFINE command 64 positioning and sizing 300 TEXT in TABLE DEFINE command 67 ,
DCS Script Language Reference updating attributes 296 315 IF command 371 example of 22, 23, 41, 83, 107, 112, 116 IF - ELSE command block, across multiple lines 23 L 626 Include Line Numbers 19 labels controls in a dialog box 288 defined and use of 25 DDE channels 80 definition and use of. See far target arguments; near fields in a structured table 28 , target arguments. tables 28 64 statement syntax 49 memory, free remaining, determining 194 406 LAUNCH command 393–394 MENU CANCEL command example of 43 example of 72 158 LEAVE command 395 (MENU) CHECKED function 405 length MENU command of fields 141 example of 73 LENGTH function 157 menu commands example of 36 grouped 233 length of a string, determining 157 working with 71 407 less than operator (<) MENU DELETE ITEM command 408 in relational expressions 40 MENU DELETE POPUP command precedence 58 menu editor 71 159 statement syntax 55 (MENU) ENABLED function less than or equal to operator (<=) menu functions, grouped 94 409–410 in relational expressions 40 MENU INSERT ITEM command 411 precedence 58 MENU INSERT POPUP command 412–413 statement syntax 56 (MENU) ITEM command LEVEL command 396 example of 73 example of 33 menu items use of 32 determining if checked 158 LIBRARY CALL command 397–399 determining if enabled 159 414–415 LIBRARY LOAD command 400 (MENU) POPUP command LIBRARY UNLOAD command 401 example of 73 416 line continuation 23, 50 (MENU) SEPARATOR command line numbers, adding to scripts 19, 402 example of 73 LINENUMBERS command 402 menus, scripted configuration via script 85 LISTBOX (Dialog command). See (DIALOG) LISTBOX creating 405 command. destroying 406 list boxes (in scripted dialog boxes) items, adding 412 creating 307 items, deleting 407 determining currently selected item 118 popup menus, adding 411, 414 positioning and sizing 300 popup menus, deleting 408 updating attributes 296, 315 popup menus, example of 73 LOAD command 403 separators, adding 416 example of 35, 500 updating 417 local echo, setting 494 MENU UPDATE command 417–418 logical structures 22 . LOGTOFILE command 404 Meridian LAT32 connector, configuring See connector loop structure, creating 573 configuration. messages. See also messages (in scripted dialog boxes). determining response with 112 M displaying 119 math messages (in scripted dialog boxes) commands, grouped 233 creating 309 functions, grouped 94 positioning and sizing 300 , operators, listed 54 updating attributes 296 315 maximized window state, determining 215 META keys 33 maximizing a window 447, 579 MIDI application 71 maximum characters minimized window state, determining 155 for capturing incoming data 248 minimizing a window 581 for function key title variables 32 modal dialog boxes 287 for Function Key variables 32 modem for named Boolean variables 40 dialing via script 284 for named numeric variables 37 disconnecting 370 Index in a named string variable 27 Modem connector, configuring. See connector configura- in a structured table field 64 tion. in Record Buffer variables 27 modular scripts maximum number of creating with labels 25 627 use of parent and child routines 61 defined and use of 37, 47 modulus operator (%) parameters, passing 61 precedence 58 NUM function 162 statement syntax 55 example of 30 use of 38 multiple concurrent scripts launching 518 programming considerations 75 O running 84 operands multiplication operator (*) Boolean 40 precedence 58 defined 21 statement syntax 54 multiple on the same line 23 use of 38 numeric 37, 52 strings, defined 27 types 21 N operations AND 98 named Boolean variables 40 OR 101, 104 named numeric variables 37 table 65 named string variables operator characters defined and use of 27 defined and use of 54 maximum characters 27 precedence, listed 58 near targets operators arguments, defined and use of 44 assignment 47, 55 executing 422 concatenation 36 returning from 445 math 54 NETID function 160 precedence 58 network commands, grouped 233 relational 55, 56 Network ID system variable using 38 setting 495 optional syntax, notation convention 20 NetworkID system variable OR (Boolean operator) retrieving current value 160 example of 57 new commands, listed 600 precedence 58 new functions, listed 600 use of 57 163 NEWLINE (Dialog command). See (DIALOG) NEWLINE ORD function command. outgoing carriage return, setting 496 new scripts, creating 17 NEXT function 161 NOSHOW command 419 P NOT (Boolean operator) example of 41 parameter lists 51 precedence 58 parameter passing (DLL) 397 use of 57 parameters not equal to operator (<> or !=) passing between child and parent routines 61 in relational expressions 40 working with 61 precedence 58 parentheses ( () ), use of and statement syntax 51 statement syntax 56 parent routine, defined 59 null string, creating 27 parity, setting 497 number sign (#) PARSE command 420–421 use of 40, 51, 348, 355 use of 47 numeric constants, defined 37 passing variable parameters 61 numeric expressions passthrough printing, setting 498 creating 38 PASSWORD function 164 parameters, passing 61 Password system variable numeric functions, defined 37 retrieving current value 164 numeric operand 37 setting 499 numerics 21, 37, 38, 50 pasting from the clipboard 331 converting to strings 105, 192 path and file names, respresenting 43 numeric variables, complex percent sign (%) defined and use of 38 as modulus operator 38
DCS Script Language Reference numeric variables, named statement syntax 55 use of 37
628 PERFORM command 422 QUIT command 434 compared with SPAWN command 518 quotation mark (" or ') example of 45, 63, 112, 116, 495 embedding in a string 27 use of 33, 44 null string, creating 27 period (.), use of and statement syntax 52 statement syntax 52 PHONENUMBER function 165 Phonenumber system variable retrieving current value 165 setting 500 R . PICTURE (Dialog command) See (DIALOG) PICTURE RADIOBUTTON (Dialog command). See (DIALOG) command. RADIOBUTTON command. piping symbol (|). See concatenation operator. radio buttons (in scripted dialog boxes) plus sign (+). See addition operator (+). creating 312 . POKE (DDE command). See (DDE) POKE command. grouped See radio groups. positioning and sizing 300 POPUP (Menu command). See (MENU) POPUP com- updating attributes 296, 315 mand. . POS function 166 RADIOGROUP (Dialog command) See (DIALOG) RA- position DIOGROUP command. of a window, determining 167 radio groups (in scripted dialog boxes) of first characer in a string, determining 166 creating 313 of host cursor, determining 110 determining currently selected button 121 POSITION function 167 positioning and sizing 300 updating attributes 296, 315 pound sign (#). See number sign (#). RANDOM function 172 POWER function 168 random numbers, generating 172 precedence of operators, listed 58 REAL function 173 PRINT CANCEL command 423 use of 37 PRINT CLOSE command 424 real numerics PRINT FILE command 425 converting example of 498 from an integer 173 PRINT FONT command 426 from a string 162 printing to integers 156 carriage return or line feed 427 decimal places, setting 485 character attributes, setting 431 exponential function 168 closing print channel 424 rounding operation 175 commands, grouped 234 real numeric variable file to printer 425 converting to interger variable 37 form feed 428 defined 37 keep print channel open, setting 492 example of 38 parameters, retrieving 169 Record Buffer variable (@R) passthrough state, setting 498 use of 28 print channel, opening 429 Record Buffer variables printer font, changing 426 definition and use of 27 screen data, routing to printer 433 examples of 30 selected window area 455 for structured tables 28 string to printer 430 for text tables 28 tab widths, setting 432 maximum character 27 terminating via script 423 statement syntax 28, 50 PRINT NEWLINE command 427 RECORD FORMAT command 435 PRINT NEWPAGE command 428 use of 66 PRINT OPEN command 429 RECORD READ command 436–437 PRINT STRING command 430 example of 24, 31, 45, 66, 118 PRINT STYLE command 431 use of 68 PRINT TABS command 432 RECORD SCAN command 438 PRINT TERMINAL command 433 use of 66 programming considerations RECORD WRITE command 439–440 for multiple concurrent scripts 75 example of 31, 67, 70, 113 PRTMETRICS function 169
relational expressions, definition and use of 40 Index PUTPROFILEDATA function 170–171 remapping keys via script 385 removed commands, listed 601 removed functions, listed 602 Q REMOVE DIRECTORY command 441 REQUEST (DDE command). See (DDE) REQUEST question mark (?), use of and statement syntax 52 629 command. SEARCH function 180–181 RESETSERIAL command 442 example of 51, 56 RESTART command 443 searching a window 329 RESULT function 174 searching data, functions for 92 Result system variable searching for and replacing characters 332 setting 501 SEARCHINRECT function 182 Result sytem variable SECONDS function 183 current value, retrieving 174 example of 55 RESUME command 444 SELECTION APPEND command 453 example of 22, 76 SELECTION BUFFER command 454 resuming script execution 444 SELECTION command 452 due to keyboard input 564 SELECTION PRINT command 455 due to received character 562 SELECTION SAVE command 456 due to received string 569 SELECTION SEND command 457 due to session disconnect 561 semicolon (;) due to specified elapsed time 571 statement syntax 53 due to specified period of inactivity 566 use of 24 due to specified screen activity 567 SENDBREAK command 463 due to specified Windows message 572 SEND command 458–462 retry delay, setting 503 example of 35, 56, 105 RETURN command 445 sending delay, setting 504 example of 45 sending text to a host 458 175 ROUND function SEPARATOR (Menu command). See (MENU) SEPARA- 176–177 ROUTE function TOR command. example of 52 separators 52 , rules, scoping 59 60 serial port, resetting 442 run-time errors 82 session break, sending to a host 463 buffer. See history buffer. S closing of, restricting 508 column width, setting 477 446 SAVE command connecting via script 256 example of 34 connection status, determining 107 , scoping rules 59 60 default window handle, setting 486 447 SCREEN command disconnecting 318 178–179 SCREEN function DTR and serial port 323 Script Compiler dialog 19 history buffer. See history buffer. script control commands, grouped 234 loading a saved file 403 scripts saving 446 autostart 17 selected text, appending to file 453 compiling and executing 18 selected text, saving 456 compiling via script 251 selected text, sending 457 converting 84, 85 selecting text 452 converting or updating from previous versions 84 sending text to a host 458 creating 17 termination, detecting 561 delaying execution 546 . editing 17 session buffer See history buffer. , launching from a script 518 session configuration 84 516 modular 61 command and keywords 367 multiple concurrent, writing and running 84 current settings, file transfer, retrieving 184–187 multiple sessions 84, 85 current settings, general, retrieving 184–191 restarting 443 Session Properties dialog, displaying 516 , resuming execution 444 sessions, configuring 84 85 saving 18 session toolbars starting from within scripts 344 displaying 490 stopping 434 display, state 366 stopping via script 246 levels, assigning 396 title, assigning 536 session window commands, grouped 235 , . session windows 109 115 scroll buffer See history buffer. 465 448 SET APPTITLE command SCROLL DOWN command 466 449 SET ATTRIBUTES command
DCS Script Language Reference SCROLL LEFT command SET AUTOSCROLLTOCURSOR command 467 SCROLL RIGHT command 450 SET AUTOSIZE command 468 SCROLL UP command 451 630 SET BACKSPACEDESTRUCTIVE command 469 stopbits, setting 507 SET BACKSPACEKEY command 470 stopping script execution 246 SET BAUDRATE command 471 STR function 192 SET BINARYTRANSFERPARAMS command 472–473 example of 55 SET BINARYTRANSFERS command 474 string constants, defined and use of 27 SET BUFFERLINES command 475 string expressions SET CARRIERDETECT command 476 creating 27 SET COLUMNS command 477 definition and use of 35 SET command 464 parameters, passing 62 example of 51 string functions, grouped 94 use of 21, 47, 54 strings 21, 27–36 SET CONNECTION command 478–479 as expressions, defined and use of 35 SET CONNECTMESSAGE command 480 capturing incoming data into 248 SET CONNECTRESULT command 481 commands, grouped 235 SET CURSOR command 482 complex 36 SET DATABITS command 483 complex, defined and use of 36 SET DDETIMEOUT command 484 concatenation via script 252 SET DECIMAL command 485 constants 27 SET DEFAULTSESSIONHANDLE command 486 converting from and multiple concurrent scripts 75 a numeric 105, 192 use of 74, 75 converting to SET DIRECTORY command 487 integers 163 SET EMULATION command 488–489 real numerics 162 SET FKEYSSHOW command 490 uppercase 205 SET FLOWCONTROL command 491 creating complex 27 SET KEEPPRINTCHANNELOPEN command 492–493 displaying in a session window 319 SET LOCALECHO command 494 functions 27 SET NETID command 495 functions, defined and use 27 SET OUTGOINGCR command 496 in scripted dialog boxes. See messages (in scripted SET PARITY command 497 dialog boxes). SET PASSTHROUGH command 498 joining via script 252 SET PASSWORD command 499 length, determining 157 SET PHONENUMBER command 500 mapping to a key 385 SET RESULT command 501 parsing 420 SET RETRY command 502 position of first character, determining 166, 180, 182 SET RETRYDELAY command 503 printing 430 SET SENDDELAY command 504 removing characters from 202 SET SIGNAL command 505 replacing characters 136 SET SOUND command 506 searching for 182, 329 SET STOPBITS command 507 searching for and replacing 332 SET TERMCLOSE command 508 sending to a host 458 SET TERMFONT command 509 wildcard characters, setting 511 SETTINGS command 516 string variable, named SETTINGS function 184–191 defined and use of 47 settings variables (@S) definition and use of 27 defined and use of 34 parameters, passing 61 statement syntax 50 structured tables SET USERID command 510 clearing of data 523 SET WILDCARD command 511 data, importing 529 SET WINDOWTITLE command 512 defined 64 SET WORDWRAP command 513 field data types 28 SET XCLOCK command 514 manipulating records 66 SET XSYSTEM command 515 manipulating whole table 65 SHOW command 517 maximum characters in a field 64 use of 19 maximum number of fields 28 size of a file, determining 135 reading data from 66, 436 size of scripted dialog box 300 Record Buffer variables 27, 30 sounds, host enabled state 506 record format, creating 435 source argument. See file name arguments. saving 67 Index source script file, defined 17 saving to clipboard 530 SPAWN command 518 saving to file 530 and multiple concurrent scripts 75 sending to DDE server 266, 269 startup scripts 17
631 sorting 531 table functions, grouped 95 statement syntax 64 TABLE LOAD command 529 writing data to 67, 438, 439 example of 31, 57 subroutine commands, grouped 227 TABLE REPLY (DDE command). See (DDE) TABLE , , , subroutines 33 61 62 63 REPLY command. executing 422 TABLE REQUEST (DDE command). See (DDE) TABLE returning from 445 REQUEST command. SUBSTR function 193 . subtraction operator (-) tables See structured tables; text tables. precedence 58 clearing of data 523 statement syntax 54 closing 524 use of 38 copying data 525 SWITCH command 519–520 defined and use of 64 symbols 50 defining 527 $ (dollar sign) 51 end of, determining 127. See also EOF function. " and ' (quotation marks) 52 manipulating structured tables 65 @ (at sign) 50 maximum number 28, 64 \ (backslash) 50 reading data from 436 ^ (caret) 50 record format, creating 435 characters, definition and use of 49 structured 28, 64 , (comma) 51 saving 67 ! (exclamation point) 51 text 28, 67 # (number sign) 51 use of (overview) 64 ( ) (parentheses) 51 writing data to 438, 439 % (percent sign) 52 TABLE SAVE command 530 . (period) 52 use of 67 ? (question mark) 52 TABLE SEND (DDE command). See (DDE) TABLE ; (semicolon) 53 SEND command. syntax TABLE SORT command 531 quick reference 604 targets statement 20 far 33, 45 194 SYSMETRICS function near 44 system bell (PC), ringing via script 243 TASKERROR command 532 521–522 SYSTEM command example of 501 system commands, grouped 236 task errors 195–196 SYSTEM function defined 82 system functions, grouped 94 listed with brief explanations 595 system parameters TASKFILE ii–xiv , retrieving 194 195 task script file, defined 17 setting 521 telecommunication system variables 47 commands, grouped 237 ConnectMessage 108 functions, grouped 95 ConnectResult 109 TeleVideo emulations, configuring.. See emulation NetworkID 160 configuration. Password 164 . PhoneNumber 165 Telnet connector, configuring. See connector configura- Result 174 tion. UserID 206 terminating file transfers 345 text (in scripted dialog boxes.. See messages (in scripted dialog boxes). text tables T clearing of data 523 , table arguments, definition and use of 43 defining 67 527 TABLE CLEAR command 523 manipulating records 68 TABLE CLOSE command 524 manipulating whole table 68 table commands, grouped 236 maximum record length 67 , TABLE COPY command 525–526 reading data from 68 436 TABLE DEFINE command 527–528 Record Buffer variables 28 example of 23, 30, 31, 57, 65, 113 statement syntax 67 , for structured table 29, 65 writing data to 70 438 use of 28, 64, 68 tiling windows 575 DCS Script Language Reference use of keywords 28, 64, 67 time table field 52 determining elapsed 201 retrieving a value 197, 198, 199, 200 632 TIME function 200 TIMER function 201 TIMER RESET command 535 string 35 TITLE command 536 system 47, 108, 109, 160, 164, 165, 206 toolbar commands, grouped 233 VERSION function 207 toolbar configuration via script 85 version of DCS, determining 207 TOOLBARHIDE command 537 VISIBLE function 208 toolbars VT Series emulations, configuring. See emulation con- hiding 537 figuration. showing 538 TOOLBARSHOW command 538 TRANSFERS command 539–543 TRIM function 202 W troubleshooting 563 WAIT CHAR command 544 DEBUG command 281 WAIT CLOSE command 545 debug window, hiding 419 WAIT commands, using 76 debug window, showing 517 WAIT DELAY command 546–547 TYPEDLIBRARYCALL function 203–204 WAIT ECHO command 548 WAIT EDIT command 549 WAIT PROMPT command 550 U WAIT QUIET command 551–552 example of 56 unadvise message, determining reception of 112 WAIT RESUME command 553 unary minus operator (-) example of 76 precedence 58 use of 79 use of 54 WAIT SCREEN command 554 uncompressing files 351 WAIT SIGNAL (DDE command). See (DDE) WAIT SIG- updating scripts 84 NAL command. UPPER function 205 wait state USERID function 206 defined 76 UserID system variable terminating 76 current value, retrieving 206 WAIT STRING command 555 setting 510 example of 35 WAIT UNTIL command 556 warning errors V defined 82 WHEN ADVISE (DDE command). See (DDE) WHEN variables ADVISE command. assigning values via script 464 WHEN CANCEL command 557–558 Boolean 40, 47, 51 WHEN COLLECT command 559–560 branching, effect of 59 WHEN commands complex numeric 38 use of 22, 76 created in child routine 60 WHEN DISCONNECT command 561 creating 47 WHEN ECHO command 562 creation of 59 use of 47 DDE data, storing 265 WHEN ERROR command 563 declaring, command 242 example of 501 decreasing numeric values 283 . default 74 WHEN EXECUTE (DDE command) See (DDE) WHEN DEFAULTSESSIONHANDLE 74 EXECUTE command. direct 47 WHEN INITIATE (DDE command). See (DDE) WHEN example of 21 INITIATE command. Function Key (@F) 32 WHEN INPUT command 564–565 Function Key Title (@T) 32 use of 47 increasing numeric values 372 WHEN POKE (DDE command). See (DDE) WHEN , indirect 27 48 POKE command. named Boolean 40 WHEN QUIET command 566 named numeric, defined and use of 37 example of 22 named string 27, 51 WHEN REQUEST (DDE command). See (DDE) WHEN numeric 36, 37, 47, 51, 52
REQUEST command. Index passing between routines 61 WHEN SCREEN command 567–568 record buffer 27, 30, 52 WHEN STRING command 569–570 Result 174 example of 76 scoping rules 59, 60 . settings 34 WHEN TERMINATE (DDE command) See (DDE) 633 WHEN TERMINATE command. WINDOW HIDE command 578 WHEN TIMER command 571 example of 74 example of 76 WINDOWHND function 210 WHEN WINDOW command 572 example of 74 WHILE command 573 WINDOW MAXIMIZE command 579 across multiple lines 23 WINDOW MESSAGE command 580 example of 24, 31, 45, 106 WINDOW MINIMIZE command 581 use of 22 WINDOW MOVE command 582 wide buttons (in scripted dialog boxes) WINDOWNAME function 211 updating attributes 296, 315 WINDOW OPEN command 583–584 wildcard characters window operations, grouped 239 use of 52 WINDOW RESTORE command 585 wildcard characters, setting 511 windows window session 74 application title, setting 465 window handles 74, 75 associated file name, retrieving 214 Windows messages, sending 580 buffer. See history buffer. Windows metafile graphics cascading 586 adding to scripted dialog boxes 311 clearing via script 247 copying to a printer 325 closing 576 copying to the clipboard 325 586 commands, grouped 239 WINDOW STACK command 587 default for Windows messages, setting 577 WINDOW UNHIDE command 212 dimensions, retrieving 167 WNDCLASS function 213 dimensions, setting 447 WNDFILE function 214 functions, grouped 95 WNDTITLE function hiding 578 word wrapping for file transfers 513 making active 574 maximized state, determining 215 maximized state, setting 447 X maximizing 579 minimized state, determining 155 XCLOCK messages 514 minimizing 581 XFERCONFIG command 588–592 moving 582 XModem configuration. See file transfer configuration. , name, retrieving 214 215 XSYSTEM messages 515 name, setting 512 opening 583 pasting text from the clipboard 331 position, retrieving 167 Y restoring previous state 447 . restoring to previous size 585 YModem configuration See file transfer configuration. selected text, saving 456 selected text, sending 457 selecting text 452 Z showing (unhiding) 587 tiling 575 ZModem configuration. See file transfer configuration. , title, retrieving 211 214 ZOOMED function 215 title, setting 512 visibility, determining 208 visibility, setting 447 Windows messages, sending 580 WINDOW ACTIVATE command 574 WINDOW ARRANGE command 575 WINDOW CLOSE command 576 WINDOW DEFAULT command 577 WINDOW function 209 window handle of active child window 96 of active session window 107 of session window 115 window handles default, setting 486 DCS Script Language Reference defined and use of 74 of active window, retrieving 96 of default session, retrieving 115 634